feat: Added NetBSD man pages

1 files changed, 642 insertions, 0 deletions

diff --git a/static/netbsd/man9/vmem.9 b/static/netbsd/man9/vmem.9
new file mode 100644
index 00000000..b3f454dd
--- /dev/null
+++ b/static/netbsd/man9/vmem.9
@@ -0,0 +1,642 @@
+.\"	$NetBSD: vmem.9,v 1.22 2023/12/02 21:02:12 thorpej Exp $
+.\"
+.\" Copyright (c)2006 YAMAMOTO Takashi,
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\" ------------------------------------------------------------
+.Dd December 2, 2023
+.Dt VMEM 9
+.Os
+.\" ------------------------------------------------------------
+.Sh NAME
+.Nm vmem
+.Nd virtual memory allocator
+.\" ------------------------------------------------------------
+.Sh SYNOPSIS
+.In sys/vmem.h
+.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.Ft vmem_t *
+.Fn vmem_create \
+"const char *name" "vmem_addr_t base" "vmem_size_t size" "vmem_size_t quantum" \
+"int (*allocfn)(void *, vmem_size_t, vm_flag_t, vmem_addr_t *)" \
+"void (*freefn)(void *, vmem_addr_t, vmem_size_t)" \
+"void *arg" "vmem_size_t qcache_max" "vm_flag_t flags" "int ipl"
+.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.Ft vmem_t *
+.Fn vmem_xcreate \
+"const char *name" "vmem_addr_t base" "vmem_size_t size" "vmem_size_t quantum" \
+"int (*allocfn)(void *, vmem_size_t, vmem_size_t *, vm_flag_t, vmem_addr_t *)" \
+"void (*freefn)(void *, vmem_addr_t, vmem_size_t)" \
+"void *arg" "vmem_size_t qcache_max" "vm_flag_t flags" "int ipl"
+.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.Ft int
+.Fn vmem_add \
+"vmem_t *vm" "vmem_addr_t addr" "vmem_size_t size" "vm_flag_t flags"
+.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.Ft int
+.Fn vmem_xalloc \
+"vmem_t *vm" "vmem_size_t size" "vmem_size_t align" \
+"vmem_size_t phase" "vmem_size_t nocross" "vmem_addr_t minaddr" \
+"vmem_addr_t maxaddr" "vm_flag_t flags" "vmem_addr_t *addrp"
+.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.Ft int
+.Fn vmem_xalloc_addr \
+"vmem_t *vm" "vmem_addr_t addr" "vmem_size_t size" "vm_flag_t flags"
+.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.Ft void
+.Fn vmem_xfree "vmem_t *vm" "vmem_addr_t addr" "vmem_size_t size"
+.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.Ft void
+.Fn vmem_xfreeall "vmem_t *vm"
+.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.Ft int
+.Fn vmem_alloc "vmem_t *vm" "vmem_size_t size" "vm_flag_t flags" "vmem_addr_t *addrp"
+.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.Ft void
+.Fn vmem_free "vmem_t *vm" "vmem_addr_t addr" "vmem_size_t size"
+.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.Ft void
+.Fn vmem_destroy "vmem_t *vm"
+.\" ------------------------------------------------------------
+.Sh DESCRIPTION
+The
+.Nm
+is a general purpose resource allocator.
+Despite its name, it can be used for arbitrary resources
+other than virtual memory.
+.Pp
+.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.Fn vmem_create
+creates a new vmem arena.
+.Bl -tag -offset indent -width qcache_max
+.It Fa name
+The string to describe the vmem.
+.It Fa base
+The start address of the initial span.
+Pass
+.Dv 0
+if no initial span is required.
+.It Fa size
+The size of the initial span.
+Pass
+.Dv 0
+if no initial span is required.
+.It Fa quantum
+The smallest unit of allocation.
+.It Fa allocfn
+The callback function used to import spans from the backend arena.
+Set both
+.Fa allocfn
+and
+.Fa freefn
+to
+.Dv NULL
+to disable automatic imports.
+.Nm
+calls
+.Fo "(*allocfn)"
+.Fa arg
+.Fa size
+.Fa flags
+.Fa "&addrp"
+.Fc
+to import a span of size at least
+.Fa size .
+.Fa allocfn
+must accept the same
+.Fa flags
+as
+.Fn vmem_alloc .
+.Fa allocfn
+must return
+.Dv ENOMEM
+to indicate failure, or 0 on success.
+If
+.Fa allocfn
+succeeds, it must write the starting address of the imported span to
+.Fa addrp .
+.It Fa freefn
+The callback function used to free spans to the backend arena.
+.Fa freefn
+may be
+.Dv NULL
+even if
+.Fa allocfn
+is not
+.Dv NULL .
+.Nm
+calls
+.Fn "(*freefn)" arg addr size
+to return to
+.Fa arg
+a span of size
+.Fa size ,
+starting at
+.Fa addr ,
+that was previously allocated by
+.Fa allocfn .
+.It Fa arg
+The backend arena.
+.Fa arg
+may be
+.Dv NULL .
+.Nm
+passes
+.Fa arg
+as the first argument of
+.Fa allocfn
+and
+.Fa freefn .
+.It Fa qcache_max
+The largest size of allocations which can be served by quantum cache.
+It is merely a hint and can be ignored.
+.It Fa flags
+Either of:
+.Bl -tag -width VM_NOSLEEP
+.It Dv VM_SLEEP
+If the allocation cannot be satisfied immediately, sleep until enough
+resources are available.
+.It Dv VM_NOSLEEP
+Don't sleep.
+Immediately return
+.Dv NULL
+if there are not enough resources available.
+.El
+.It Fa ipl
+Interrupt level to be blocked for allocating from vmem.
+.El
+.Pp
+.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.Fn vmem_xcreate
+creates a new vmem arena.
+.Bl -tag -offset indent -width qcache_max
+.It Fa name
+The string to describe the vmem.
+.It Fa base
+The start address of the initial span.
+Pass
+.Dv 0
+if no initial span is required.
+.It Fa size
+The size of the initial span.
+Pass
+.Dv 0
+if no initial span is required.
+.It Fa quantum
+The smallest unit of allocation.
+.It Fa allocfn
+The callback function used to import spans from the backend arena.
+Set both
+.Fa allocfn
+and
+.Fa freefn
+to
+.Dv NULL
+to disable automatic imports.
+.Nm
+calls
+.Fo "(*allocfn)"
+.Fa arg
+.Fa size
+.Fa "&actualsize"
+.Fa flags
+.Fa "&addrp"
+.Fc
+to import a span of size at least
+.Fa size .
+.Fa allocfn
+must accept the same
+.Fa flags
+as
+.Fn vmem_alloc .
+.Fa allocfn
+must return
+.Dv ENOMEM
+to indicate failure, or 0 on success.
+If
+.Fa allocfn
+succeeds, it must write the actual size of the allocation to
+.Fa actualsize
+and the starting address of the imported span to
+.Fa addrp .
+The actual size will always be greater than or equal to the requested size.
+.It Fa freefn
+The callback function used to free spans to the backend arena.
+.Fa freefn
+may be
+.Dv NULL
+even if
+.Fa allocfn
+is not
+.Dv NULL .
+.Nm
+calls
+.Fn "(*freefn)" arg addr size
+to return to
+.Fa arg
+a span of size
+.Fa size ,
+starting at
+.Fa addr ,
+that was previously allocated by
+.Fa allocfn .
+.It Fa arg
+The backend arena.
+.Fa arg
+may be
+.Dv NULL .
+.Nm
+passes
+.Fa arg
+as the first argument of
+.Fa allocfn
+and
+.Fa freefn .
+.It Fa qcache_max
+The largest size of allocations which can be served by quantum cache.
+It is merely a hint and can be ignored.
+.It Fa flags
+Either of:
+.Bl -tag -width VM_NOSLEEP
+.It Dv VM_SLEEP
+If the allocation cannot be satisfied immediately, sleep until enough
+resources are available.
+.It Dv VM_NOSLEEP
+Don't sleep.
+Immediately return
+.Dv NULL
+if there are not enough resources available.
+.El
+.It Fa ipl
+Interrupt level to be blocked for allocating from vmem.
+.El
+.Pp
+.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.Fn vmem_add
+adds a span of size
+.Fa size
+starting at
+.Fa addr
+to the arena.
+Returns
+0
+on success,
+.Dv ENOMEM
+on failure.
+.Bl -tag -offset indent -width flags
+.It Fa flags
+Either of:
+.Bl -tag -width VM_NOSLEEP
+.It Dv VM_SLEEP
+If the allocation cannot be satisfied immediately, sleep until enough
+resources are available.
+.It Dv VM_NOSLEEP
+Don't sleep.
+Immediately return
+.Dv ENOMEM
+if there are not enough resources available.
+.El
+.El
+.Pp
+.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.Fn vmem_xalloc
+allocates a resource from the arena.
+.Bl -tag -offset indent -width nocross
+.It Fa vm
+The arena which we allocate from.
+.It Fa size
+Specify the size of the allocation.
+.It Fa align
+If zero, don't care about the alignment of the allocation.
+Otherwise, request a resource segment starting at
+offset
+.Fa phase
+from an
+.Fa align
+aligned boundary.
+.It Fa phase
+See the above description of
+.Fa align .
+If
+.Fa align
+is zero,
+.Fa phase
+must be zero.
+Otherwise,
+.Fa phase
+must be smaller than
+.Fa align .
+.It Fa nocross
+Request a resource which doesn't cross
+.Fa nocross
+aligned boundary.
+.It Fa minaddr
+Specify the minimum address which can be allocated, or
+.Dv VMEM_ADDR_MIN
+if the caller does not care.
+.It Fa maxaddr
+Specify the maximum address which can be allocated, or
+.Dv VMEM_ADDR_MAX
+if the caller does not care.
+.It Fa flags
+A bitwise OR of an allocation strategy and a sleep flag.
+.Pp
+The allocation strategy must be one of:
+.Bl -tag -width VM_INSTANTFIT
+.It Dv VM_BESTFIT
+Prefer space efficiency.
+.It Dv VM_INSTANTFIT
+Prefer performance.
+.El
+.Pp
+The sleep flag must be one of:
+.Bl -tag -width VM_NOSLEEP
+.It Dv VM_SLEEP
+If the allocation cannot be satisfied immediately, sleep until enough
+resources are available.
+.It Dv VM_NOSLEEP
+Don't sleep.
+Immediately return
+.Dv ENOMEM
+if there are not enough resources available.
+.El
+.It Fa addrp
+On success, if
+.Fa addrp
+is not
+.Dv NULL ,
+.Fn vmem_xalloc
+overwrites it with the start address of the allocated span.
+.El
+.Pp
+.\" ------------------------------------------------------------
+.Fn vmem_xalloc_addr
+allocates a specific address from the arena.
+The requested address must be aligned with the arena's quantum.
+.Bl -tag -offset indent -width flags
+.It Fa vm
+The arena which we allocate from.
+.It Fa addr
+The address to allocate.
+.It Fa size
+Specify the size of the allocation.
+.It Fa flags
+A sleep flag.
+Because a specific address is being allocated, any specified allocation
+strategy is ignored.
+.Pp
+The sleep flag must be one of:
+.Bl -tag -width VM_NOSLEEP
+.It Dv VM_SLEEP
+If the allocation cannot be satisfied immediately, sleep until the
+requested range can be allocated.
+.It Dv VM_NOSLEEP
+Don't sleep.
+Immediately return
+.Dv ENOMEM
+if the requested range is not available.
+.El
+.El
+.Pp
+.\" ------------------------------------------------------------
+.Fn vmem_xfree
+frees resource allocated by
+.Fn vmem_xalloc
+or
+.Fn vmem_xalloc_addr
+to the arena.
+.Bl -tag -offset indent -width addr
+.It Fa vm
+The arena which we free to.
+.It Fa addr
+The resource being freed.
+It must have been allocated via
+.Fn vmem_xalloc
+or
+.Fn vmem_xalloc_addr .
+Notably, it must not have been allocated via
+.Fn vmem_alloc ,
+otherwise, the behaviour is undefined.
+.It Fa size
+The size of the resource being freed.
+It must be the same as the
+.Fa size
+argument used for
+.Fn vmem_xalloc
+or
+.Fn vmem_xalloc_addr .
+.El
+.Pp
+.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.Fn vmem_xfreeall
+frees all resources that have been allocated by
+.Fn vmem_xalloc
+to the arena.
+.Bl -tag -offset indent -width addr
+.It Fa vm
+The arena which we free to.
+Note that this function is may not be used on arenas
+where resources have been allocated using
+.Fn vmem_alloc
+or arenas that have a quantum cache
+.Po
+i.e. were created with a non-zero
+.Fa qcache_max
+.Pc .
+.El
+.Pp
+.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.Fn vmem_alloc
+allocates a resource from the arena.
+.Bl -tag -offset indent -width flags
+.It Fa vm
+The arena which we allocate from.
+.It Fa size
+Specify the size of the allocation.
+.It Fa flags
+A bitwise OR of an allocation strategy and a sleep flag.
+.Pp
+The allocation strategy must be one of:
+.Bl -tag -width VM_INSTANTFIT
+.It Dv VM_BESTFIT
+Prefer space efficiency.
+.It Dv VM_INSTANTFIT
+Prefer performance.
+.El
+.Pp
+The sleep flag must be one of:
+.Bl -tag -width VM_NOSLEEP
+.It Dv VM_SLEEP
+If the allocation cannot be satisfied immediately, sleep until enough
+resources are available.
+.It Dv VM_NOSLEEP
+Don't sleep.
+Immediately return
+.Dv ENOMEM
+if there are not enough resources available.
+.El
+.It Fa addrp
+On success, if
+.Fa addrp
+is not
+.Dv NULL ,
+.Fn vmem_alloc
+overwrites it with the start address of the allocated span.
+.El
+.Pp
+.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.Fn vmem_free
+frees resource allocated by
+.Fn vmem_alloc
+to the arena.
+.Bl -tag -offset indent -width addr
+.It Fa vm
+The arena which we free to.
+.It Fa addr
+The resource being freed.
+It must have been allocated via
+.Fn vmem_alloc .
+Notably, it must not have been allocated via
+.Fn vmem_xalloc
+or
+.Fn vmem_xalloc addr ,
+otherwise, the behaviour is undefined.
+.It Fa size
+The size of the resource being freed.
+It must be the same as the
+.Fa size
+argument used for
+.Fn vmem_alloc .
+.El
+.Pp
+.\" ------------------------------------------------------------
+.Fn vmem_destroy
+destroys a vmem arena.
+.Bl -tag -offset indent -width vm
+.It Fa vm
+The vmem arena being destroyed.
+The caller must ensure that no one will use it anymore.
+.El
+.\" ------------------------------------------------------------
+.Sh RETURN VALUES
+.Fn vmem_create
+and
+.Fn vmem_xcreate
+return a pointer to the newly allocated vmem_t on success, or
+.Dv NULL
+if
+.Dv VM_NOSLEEP
+was specified and memory could not be allocated immediately.
+.Pp
+.Fn vmem_add
+returns 0 on success, or
+.Er ENOMEM
+if
+.Dv VM_NOSLEEP
+was specified and memory could not be allocated immediately to record
+the region.
+.Pp
+.Fn vmem_alloc
+and
+.Fn vmem_xalloc
+return 0 on success, or
+.Er ENOMEM
+if either:
+.Bl -dash
+.It
+.Dv VM_NOSLEEP
+was specified and a matching region could not be allocated immediately;
+or
+.It
+non-default
+.Fa align ,
+.Fa phase ,
+or
+.Fa nocross
+parameters were specified, and a matching region could not be allocated
+without calling the backing
+.Fa allocfn
+passed to
+.Fn vmem_create .
+.El
+.\" ------------------------------------------------------------
+.Sh CODE REFERENCES
+The
+.Nm
+subsystem is implemented within the file
+.Pa sys/kern/subr_vmem.c .
+.\" ------------------------------------------------------------
+.Sh SEE ALSO
+.Xr intro 9 ,
+.Xr kmem 9 ,
+.Xr memoryallocators 9 ,
+.Xr uvm 9
+.Rs
+.%A Jeff Bonwick
+.%A Jonathan Adams
+.%T "Magazines and Vmem: Extending the Slab Allocator to Many CPUs and Arbitrary Resources"
+.%J "2001 USENIX Annual Technical Conference"
+.%D 2001
+.Re
+.\" ------------------------------------------------------------
+.Sh AUTHORS
+This implementation of
+.Nm
+was written by
+.An YAMAMOTO Takashi .
+.Sh BUGS
+.Nm
+relies on
+.Xr malloc 9 ,
+.Xr pool 9 ,
+and
+.Xr RUN_ONCE 9 ,
+so it cannot be used as early during system bootstrap as
+.Xr extent 9 .
+.Pp
+.Nm
+has no way to pass
+.Fa align ,
+.Fa phase ,
+.Fa nocross ,
+.Fa minaddr ,
+or
+.Fa maxaddr
+constraints into the backing allocator
+.Fa allocfn ,
+so even if
+.Dv VM_SLEEP
+is specified,
+.Fn vmem_alloc
+and
+.Fn vmem_xalloc
+may spuriously fail immediately with
+.Fa align ,
+.Fa phase ,
+or
+.Fa nocross ,
+or sleep forever with
+.Fa minaddr
+or
+.Fa maxaddr .