diff options
Diffstat (limited to 'share/man/man9')
-rw-r--r-- | share/man/man9/VFS_ROOT.9 | 3 | ||||
-rw-r--r-- | share/man/man9/bus_dma.9 | 137 | ||||
-rw-r--r-- | share/man/man9/crypto.9 | 6 | ||||
-rw-r--r-- | share/man/man9/ktr.9 | 2 | ||||
-rw-r--r-- | share/man/man9/memguard.9 | 12 | ||||
-rw-r--r-- | share/man/man9/pfil.9 | 4 | ||||
-rw-r--r-- | share/man/man9/sbuf.9 | 22 | ||||
-rw-r--r-- | share/man/man9/sleep.9 | 6 |
8 files changed, 117 insertions, 75 deletions
diff --git a/share/man/man9/VFS_ROOT.9 b/share/man/man9/VFS_ROOT.9 index 7af1fe6..1aa0194 100644 --- a/share/man/man9/VFS_ROOT.9 +++ b/share/man/man9/VFS_ROOT.9 @@ -48,7 +48,8 @@ Its arguments are: .It Fa mp The file system. .It Fa flags -The lock type. Could be +The lock type. +Could be .Dv LK_EXCLUSIVE or .Dv LK_SHARED . diff --git a/share/man/man9/bus_dma.9 b/share/man/man9/bus_dma.9 index 0f738ac..9911b8b 100644 --- a/share/man/man9/bus_dma.9 +++ b/share/man/man9/bus_dma.9 @@ -133,7 +133,7 @@ abstracting machine dependent issues like setting up DMA mappings, handling cache issues, bus specific features and limitations. .Sh STRUCTURES AND TYPES -.Bl -tag -width compact +.Bl -tag -width indent .It Vt bus_dma_tag_t A machine-dependent (MD) opaque type that describes the characteristics of DMA transactions. @@ -143,11 +143,11 @@ This allows all devices along the path of DMA transactions to contribute to the constraints of those transactions. .It Vt bus_dma_filter_t Client specified address filter having the format: -.Bl -tag -width compact +.Bl -tag -width indent .It Ft int .Fn "client_filter" "void *filtarg" "bus_addr_t testaddr" .El -.sp +.Pp Address filters can be specified during tag creation to allow for devices whose DMA address restrictions cannot be specified by a single window. @@ -172,7 +172,7 @@ DMA segments. bus_addr_t ds_addr; bus_size_t ds_len; .Ed -.sp +.Pp The .Fa ds_addr field contains the device visible address of the DMA segment, and @@ -187,9 +187,12 @@ A machine-dependent opaque type describing an individual mapping. One map is used for each memory allocation that will be loaded. Maps can be reused once they have been unloaded. Multiple maps can be associated with one DMA tag. -While the value of the map may evaluate to NULL on some platforms under -certain conditions, it should never be assumed that it will be NULL in all -cases. +While the value of the map may evaluate to +.Dv NULL +on some platforms under certain conditions, +it should never be assumed that it will be +.Dv NULL +in all cases. .It Vt bus_dmamap_callback_t Client specified callback for receiving mapping information resulting from the load of a @@ -197,12 +200,12 @@ the load of a via .Fn bus_dmamap_load . Callbacks are of the format: -.Bl -tag -width compact +.Bl -tag -width indent .It Ft void .Fn "client_callback" "void *callback_arg" "bus_dma_segment_t *segs" \ "int nseg" "int error" .El -.sp +.Pp The .Fa callback_arg is the callback argument passed to dmamap load functions. @@ -227,14 +230,14 @@ via .Fn bus_dmamap_load_uio or .Fn bus_dmamap_load_mbuf . -.sp +.Pp Callback2s are of the format: -.Bl -tag -width compact +.Bl -tag -width indent .It Ft void .Fn "client_callback2" "void *callback_arg" "bus_dma_segment_t *segs" \ "int nseg" "bus_size_t mapsize" "int error" .El -.sp +.Pp Callback2's behavior is the same as .Vt bus_dmamap_callback_t with the addition that the length of the data mapped is provided via @@ -287,11 +290,11 @@ If the load operation does not need to be deferred, then it will not be called since the function loading the map should be holding the appropriate locks. This method is of the format: -.Bl -tag -width compact +.Bl -tag -width indent .It Ft void .Fn "lockfunc" "void *lockfunc_arg" "bus_dma_lock_op_t op" .El -.sp +.Pp Two .Vt lockfunc implementations are provided for convenience. @@ -304,27 +307,28 @@ passed into will generate a system panic if it is called. It is substituted into the tag when .Fa lockfunc -is passed as NULL to +is passed as +.Dv NULL +to .Fn bus_dma_tag_create . .It Vt bus_dma_lock_op_t Operations to be performed by the client-specified .Fn lockfunc . -.Bl -tag -width BUS_DMA_UNLOCK +.Bl -tag -width ".Dv BUS_DMA_UNLOCK" .It Dv BUS_DMA_LOCK Acquires and/or locks the client locking primitive. .It Dv BUS_DMA_UNLOCK Releases and/or unlocks the client locking primitive. .El .El -.sp .Sh FUNCTIONS -.Bl -tag -width compact +.Bl -tag -width indent .It Fn bus_dma_tag_create "parent" "alignment" "boundary" "lowaddr" \ "highaddr" "*filtfunc" "*filtfuncarg" "maxsize" "nsegments" "maxsegsz" \ "flags" "lockfunc" "lockfuncarg" "*dmat" Allocates a device specific DMA tag, and initializes it according to the arguments provided: -.Bl -tag -width *filtfuncarg -compact +.Bl -tag -width ".Fa filtfuncarg" .It Fa parent Indicates restrictions between the parent bridge, CPU memory, and the device. @@ -348,8 +352,7 @@ The boundary must be a power of 2 and must be no smaller than the maximum segment size. .Ql 0 indicates that there are no boundary restrictions. -.It Fa lowaddr -.It Fa highaddr +.It Fa lowaddr , highaddr Bounds of the window of bus address space that .Em cannot be directly accessed by the device. @@ -373,7 +376,9 @@ This area of is used to bounce requests that would otherwise conflict with the exclusion window. .It Fa filtfunc -Optional filter function (may be NULL) to be called for any attempt to +Optional filter function (may be +.Dv NULL ) +to be called for any attempt to map memory into the window described by .Fa lowaddr and @@ -388,7 +393,8 @@ The filter function will be called for every machine page that overlaps the exclusion window. .It Fa filtfuncarg Argument passed to all calls to the filter function for this tag. -May be NULL. +May be +.Dv NULL . .It Fa maxsize Maximum size, in bytes, of the sum of all segment lengths in a given DMA mapping associated with this tag. @@ -404,7 +410,7 @@ with .Fa dmat . .It Fa flags Are as follows: -.Bl -tag -width "BUS_DMA_ALLOCNOW" -compact +.Bl -tag -width ".Dv BUS_DMA_ALLOCNOW" .It Dv BUS_DMA_ALLOCNOW Pre-allocate enough resources to handle at least one map load operation on this tag. @@ -419,9 +425,13 @@ that resources will be allocated or reserved exclusively for this tag. It should be treated only as a minor optimization. .El .It Fa lockfunc -Optional lock manipulation function (may be NULL) to be called when busdma +Optional lock manipulation function (may be +.Dv NULL ) +to be called when busdma needs to manipulate a lock on behalf of the client. -If NULL is specified, +If +.Dv NULL +is specified, .Fn dflt_lock is used. .It Fa lockfuncarg @@ -452,7 +462,7 @@ on success. .It Fn bus_dmamap_create "dmat" "flags" "*mapp" Allocates and initializes a DMA map. Arguments are as follows: -.Bl -tag -width nsegments -compact +.Bl -tag -width ".Fa nsegments" .It Fa dmat DMA tag. .It Fa flags @@ -472,7 +482,7 @@ map or allocating mapping resources. .It Fn bus_dmamap_destroy "dmat" "map" Frees all resources associated with a given DMA map. Arguments are as follows: -.Bl -tag -width dmat -compact +.Bl -tag -width ".Fa dmat" .It Fa dmat DMA tag used to allocate .Fa map . @@ -494,7 +504,7 @@ associated with the DMA map .Fa map . This call will always return immediately and will not block for any reason. Arguments are as follows: -.Bl -tag -width buflen -compact +.Bl -tag -width ".Fa buflen" .It Fa dmat DMA tag used to allocate .Fa map . @@ -516,15 +526,15 @@ load returns, and code should be structured appropriately to handle this. See below for specific flags and error codes that control this behavior. .It Fa flags Are as follows: -.Bl -tag -width BUS_DMA_NOWAIT -compact -.It Er BUS_DMA_NOWAIT +.Bl -tag -width ".Dv BUS_DMA_NOWAIT" +.It Dv BUS_DMA_NOWAIT The load should not be deferred in case of insufficient mapping resources, and instead should return immediately with an appropriate error. .El .El .Pp Return values to the caller are as follows: -.Bl -tag -width EINPROGRESS -compact +.Bl -tag -width ".Er EINPROGRESS" .It 0 The callback has been called and completed. The status of the mapping has been delivered to the callback. @@ -537,7 +547,7 @@ be deferred until all callbacks have been processed. .It Er ENOMEM The load request has failed due to insufficient resources, and the caller specifically used the -.Fa BUS_DMA_NOWAIT +.Dv BUS_DMA_NOWAIT flag. .It Er EINVAL The load request was invalid. @@ -559,7 +569,7 @@ argument used to create the dma tag When the callback is called, it is presented with an error value indicating the disposition of the mapping. Error may be one of the following: -.Bl -tag -width EINPROGRESS -compact +.Bl -tag -width ".Er EINPROGRESS" .It 0 The mapping was successful and the .Fa dm_segs @@ -582,7 +592,7 @@ A argument is also passed to the callback routine, which contains the mbuf chain's packet header length. The -.Fa BUS_DMA_NOWAIT +.Dv BUS_DMA_NOWAIT flag is implied, thus no callback deferral will happen. .Pp Mbuf chains are assumed to be in kernel virtual address space. @@ -618,7 +628,7 @@ argument is also passed to the callback routine, which contains the size of i.e. .Fa uio->uio_resid . The -.Fa BUS_DMA_NOWAIT +.Dv BUS_DMA_NOWAIT flag is implied, thus no callback deferral will happen. Returns the same errors as .Fn bus_dmamap_load . @@ -639,7 +649,7 @@ Pages may be locked using .It Fn bus_dmamap_unload "dmat" "map" Unloads a DMA map. Arguments are as follows: -.Bl -tag -width dmam -compact +.Bl -tag -width ".Fa dmam" .It Fa dmat DMA tag used to allocate .Fa map . @@ -656,7 +666,7 @@ prior to unloading the map. Performs synchronization of a device visible mapping with the CPU visible memory referenced by that mapping. Arguments are as follows: -.Bl -tag -width dmat -compact +.Bl -tag -width ".Fa dmat" .It Fa dmat DMA tag used to allocate .Fa map . @@ -706,7 +716,7 @@ that is permanently loaded into the newly created returned via .Fa mapp . Arguments are as follows: -.Bl -tag -width alignment -compact +.Bl -tag -width ".Fa alignment" .It Fa dmat DMA tag describing the constraints of the DMA mapping. .It Fa vaddr @@ -714,7 +724,7 @@ Pointer to a pointer that will hold the returned KVA mapping of the allocated region. .It Fa flags Flags are defined as follows: -.Bl -tag -width BUS_DMA_NOWAIT -compact +.Bl -tag -width ".Dv BUS_DMA_NOWAIT" .It Dv BUS_DMA_WAITOK The routine can safely wait (sleep) for resources. .It Dv BUS_DMA_NOWAIT @@ -730,7 +740,9 @@ a CPU and a DMA engine, frequently. Use of this flag does not remove the requirement of using bus_dmamap_sync, but it may reduce the cost of performing these operations. -The BUS_DMA_COHERENT flag is currently implemented on sparc64 and arm. +The +.Dv BUS_DMA_COHERENT +flag is currently implemented on sparc64 and arm. .It Dv BUS_DMA_ZERO Causes the allocated memory to be set to all zeros. .El @@ -773,7 +785,7 @@ Frees memory previously allocated by Any mappings will be invalidated. Arguments are as follows: -.Bl -tag -width vaddr -compact +.Bl -tag -width ".Fa vaddr" .It Fa dmat DMA tag. .It Fa vaddr @@ -823,16 +835,23 @@ callback function is called from a deferred context instead of the driver context. This means that certain .Nm -functions must always be called with same lock held that is specified in the -tag. These functions include: -.Pp -.Bl -inset -offset indent -compact -.It bus_dmamap_load -.It bus_dmamap_load_uio -.It bus_dmamap_load_mbuf -.It bus_dmamap_load_mbuf_sg -.It bus_dmamap_unload -.It bus_dmamap_sync +functions must always be called with the same lock held that is specified in the +tag. +These functions include: +.Pp +.Bl -item -offset indent -compact +.It +.Fn bus_dmamap_load +.It +.Fn bus_dmamap_load_uio +.It +.Fn bus_dmamap_load_mbuf +.It +.Fn bus_dmamap_load_mbuf_sg +.It +.Fn bus_dmamap_unload +.It +.Fn bus_dmamap_sync .El .Pp There is one exception to this rule. @@ -846,13 +865,17 @@ Certain .Nm operations should not be called with the driver lock held, either because they are already protected by an internal lock, or because they might sleep -due to memory or resource allocation. The following functions must not be +due to memory or resource allocation. +The following functions must not be called with any non-sleepable locks held: .Pp -.Bl -inset -offset indent -compact -.It bus_dma_tag_create -.It bus_dmamap_create -.It bus_dmamem_alloc +.Bl -item -offset indent -compact +.It +.Fn bus_dma_tag_create +.It +.Fn bus_dmamap_create +.It +.Fn bus_dmamem_alloc .El .Pp All other functions do not have a locking protocol and can thus be diff --git a/share/man/man9/crypto.9 b/share/man/man9/crypto.9 index 97db9aa..da9db86 100644 --- a/share/man/man9/crypto.9 +++ b/share/man/man9/crypto.9 @@ -292,7 +292,9 @@ is an mbuf chain. .It Dv CRYPTO_F_IOV The buffer pointed to by .Va crp_buf -is an uio structure. +is an +.Vt uio +structure. .It Dv CRYPTO_F_REL Must return data in the same place. .It Dv CRYPTO_F_BATCH @@ -355,7 +357,7 @@ For MAC algorithms, this is where the result of the keyed hash will be inserted. .It Va crd_flags The following flags are defined: -.Bl -tag -width ".Dv CRD" +.Bl -tag -width 3n .It Dv CRD_F_ENCRYPT For encryption algorithms, this bit is set when encryption is required (when not set, decryption is performed). diff --git a/share/man/man9/ktr.9 b/share/man/man9/ktr.9 index a096c7f..19b91de 100644 --- a/share/man/man9/ktr.9 +++ b/share/man/man9/ktr.9 @@ -24,7 +24,7 @@ .\" .\" $FreeBSD$ .\" -.Dd February 15, 2001 +.Dd December 27, 2005 .Dt KTR 9 .Os .Sh NAME diff --git a/share/man/man9/memguard.9 b/share/man/man9/memguard.9 index 1851407..72a41e5 100644 --- a/share/man/man9/memguard.9 +++ b/share/man/man9/memguard.9 @@ -48,19 +48,25 @@ and .Fn free for a particular malloc type. .Sh EXAMPLES -To use memguard for memory type compiled into the kernel, one has to add the +To use +.Nm +for memory type compiled into the kernel, one has to add the following line to the .Pa /boot/loader.conf : .Bd -literal -offset indent vm.memguard.desc=<memory_type> .Ed .Pp -Where memory_type is a short description of memory type to monitor. +Where +.Ar memory_type +is a short description of memory type to monitor. The short description of memory type is the second argument to .Xr MALLOC_DEFINE 9 , so one has to find it in the kernel source. .Pp -To use memguard for memory type defined in a kernel module, one has to set +To use +.Nm +for memory type defined in a kernel module, one has to set .Va vm.memguard.desc .Xr sysctl 8 variable before loading the module: diff --git a/share/man/man9/pfil.9 b/share/man/man9/pfil.9 index 11ce046..e0df8c9 100644 --- a/share/man/man9/pfil.9 +++ b/share/man/man9/pfil.9 @@ -200,8 +200,8 @@ The diverts .Dv AF_INET and -.DV AF_INET6 -traffic according to it's sysctl settings, but contrary to the above +.Dv AF_INET6 +traffic according to its sysctl settings, but contrary to the above statements, the data is provided in host byte order. .Pp When a diff --git a/share/man/man9/sbuf.9 b/share/man/man9/sbuf.9 index ca9aa85..1a752db 100644 --- a/share/man/man9/sbuf.9 +++ b/share/man/man9/sbuf.9 @@ -29,6 +29,7 @@ .Dt SBUF 9 .Os .Sh NAME +.Nm sbuf , .Nm sbuf_new , .Nm sbuf_clear , .Nm sbuf_setpos , @@ -92,7 +93,7 @@ .Fn sbuf_delete "struct sbuf *s" .Sh DESCRIPTION The -.Nm sbuf +.Nm family of functions allows one to safely allocate, construct and release bounded null-terminated strings in kernel space. Instead of arrays of characters, these functions operate on structures @@ -308,37 +309,46 @@ size of its storage buffer using or it is reinitialized to a sufficiently short string using .Fn sbuf_cpy . .Sh RETURN VALUES +The .Fn sbuf_new -returns +function returns .Dv NULL if it failed to allocate a storage buffer, and a pointer to the new .Fa sbuf otherwise. .Pp +The .Fn sbuf_setpos -returns \-1 if +function returns \-1 if .Fa pos was invalid, and zero otherwise. .Pp +The .Fn sbuf_cat , .Fn sbuf_cpy , .Fn sbuf_printf , .Fn sbuf_putc , and .Fn sbuf_trim +functions all return \-1 if the buffer overflowed, and zero otherwise. .Pp +The .Fn sbuf_overflowed +function returns a non-zero value if the buffer overflowed, and zero otherwise. .Pp +The .Fn sbuf_data and .Fn sbuf_len -return +functions return .Dv NULL and \-1, respectively, if the buffer overflowed. .Pp +The .Fn sbuf_copyin +function returns \-1 if copying string from userland failed, and number of bytes copied otherwise. .Sh SEE ALSO @@ -350,13 +360,13 @@ copied otherwise. .Xr printf 9 .Sh HISTORY The -.Nm sbuf +.Nm family of functions first appeared in .Fx 4.4 . .Sh AUTHORS .An -nosplit The -.Nm sbuf +.Nm family of functions was designed by .An Poul-Henning Kamp Aq phk@FreeBSD.org and implemented by diff --git a/share/man/man9/sleep.9 b/share/man/man9/sleep.9 index 1562c55a..db97565 100644 --- a/share/man/man9/sleep.9 +++ b/share/man/man9/sleep.9 @@ -25,7 +25,7 @@ .\" .\" $FreeBSD$ .\" -.Dd December 17, 1998 +.Dd April 17, 2006 .Os .Dt SLEEP 9 .Sh NAME @@ -124,8 +124,8 @@ If .Fa timo is not 0, then the thread will sleep for at most -.Fa timo -\&/ hz seconds. +.Fa timo No / Va hz +seconds. If the .Va Giant lock is not held and |