diff options
Diffstat (limited to 'share/man/man9/bus_dma.9')
| -rw-r--r-- | share/man/man9/bus_dma.9 | 137 |
1 files changed, 80 insertions, 57 deletions
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 |
