| bus_dma.9 (161929) | bus_dma.9 (162404) |
|---|---|
| 1.\" Copyright (c) 2002, 2003 Hiten M. Pandya. 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions, and the following disclaimer, --- 43 unchanged lines hidden (view full) --- 52.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 53.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 54.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 55.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 56.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 57.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 58.\" POSSIBILITY OF SUCH DAMAGE. 59.\" | 1.\" Copyright (c) 2002, 2003 Hiten M. Pandya. 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions, and the following disclaimer, --- 43 unchanged lines hidden (view full) --- 52.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 53.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 54.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 55.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 56.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 57.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 58.\" POSSIBILITY OF SUCH DAMAGE. 59.\" |
| 60.\" $FreeBSD: head/share/man/man9/bus_dma.9 161929 2006-09-03 00:31:21Z jmg $ | 60.\" $FreeBSD: head/share/man/man9/bus_dma.9 162404 2006-09-18 15:24:20Z ru $ |
| 61.\" $NetBSD: bus_dma.9,v 1.25 2002/10/14 13:43:16 wiz Exp $ 62.\" 63.Dd August 31, 2006 64.Dt BUS_DMA 9 65.Os 66.Sh NAME 67.Nm bus_dma , 68.Nm bus_dma_tag_create , --- 59 unchanged lines hidden (view full) --- 128.Nm 129API is a bus, device, and machine-independent (MI) interface to 130DMA mechanisms. 131It provides the client with flexibility and simplicity by 132abstracting machine dependent issues like setting up 133DMA mappings, handling cache issues, bus specific features 134and limitations. 135.Sh STRUCTURES AND TYPES | 61.\" $NetBSD: bus_dma.9,v 1.25 2002/10/14 13:43:16 wiz Exp $ 62.\" 63.Dd August 31, 2006 64.Dt BUS_DMA 9 65.Os 66.Sh NAME 67.Nm bus_dma , 68.Nm bus_dma_tag_create , --- 59 unchanged lines hidden (view full) --- 128.Nm 129API is a bus, device, and machine-independent (MI) interface to 130DMA mechanisms. 131It provides the client with flexibility and simplicity by 132abstracting machine dependent issues like setting up 133DMA mappings, handling cache issues, bus specific features 134and limitations. 135.Sh STRUCTURES AND TYPES |
| 136.Bl -tag -width compact | 136.Bl -tag -width indent |
| 137.It Vt bus_dma_tag_t 138A machine-dependent (MD) opaque type that describes the 139characteristics of DMA transactions. 140DMA tags are organized into a hierarchy, with each child 141tag inheriting the restrictions of its parent. 142This allows all devices along the path of DMA transactions 143to contribute to the constraints of those transactions. 144.It Vt bus_dma_filter_t 145Client specified address filter having the format: | 137.It Vt bus_dma_tag_t 138A machine-dependent (MD) opaque type that describes the 139characteristics of DMA transactions. 140DMA tags are organized into a hierarchy, with each child 141tag inheriting the restrictions of its parent. 142This allows all devices along the path of DMA transactions 143to contribute to the constraints of those transactions. 144.It Vt bus_dma_filter_t 145Client specified address filter having the format: |
| 146.Bl -tag -width compact | 146.Bl -tag -width indent |
| 147.It Ft int 148.Fn "client_filter" "void *filtarg" "bus_addr_t testaddr" 149.El | 147.It Ft int 148.Fn "client_filter" "void *filtarg" "bus_addr_t testaddr" 149.El |
| 150.sp | 150.Pp |
| 151Address filters can be specified during tag creation to allow 152for devices whose DMA address restrictions cannot be specified 153by a single window. 154The 155.Fa filtarg 156is client specified during tag creation to be passed to all 157invocations of the callback. 158The --- 8 unchanged lines hidden (view full) --- 167that can be accommodated by the device and non-zero otherwise. 168.It Vt bus_dma_segment_t 169A machine-dependent type that describes individual 170DMA segments. 171.Bd -literal 172 bus_addr_t ds_addr; 173 bus_size_t ds_len; 174.Ed | 151Address filters can be specified during tag creation to allow 152for devices whose DMA address restrictions cannot be specified 153by a single window. 154The 155.Fa filtarg 156is client specified during tag creation to be passed to all 157invocations of the callback. 158The --- 8 unchanged lines hidden (view full) --- 167that can be accommodated by the device and non-zero otherwise. 168.It Vt bus_dma_segment_t 169A machine-dependent type that describes individual 170DMA segments. 171.Bd -literal 172 bus_addr_t ds_addr; 173 bus_size_t ds_len; 174.Ed |
| 175.sp | 175.Pp |
| 176The 177.Fa ds_addr 178field contains the device visible address of the DMA segment, and 179.Fa ds_len 180contains the length of the DMA segment. 181Although the DMA segments returned by a mapping call will adhere to 182all restrictions necessary for a successful DMA operation, some conversion 183(e.g.\& a conversion from host byte order to the device's byte order) is 184almost always required when presenting segment information to the device. 185.It Vt bus_dmamap_t 186A machine-dependent opaque type describing an individual mapping. 187One map is used for each memory allocation that will be loaded. 188Maps can be reused once they have been unloaded. 189Multiple maps can be associated with one DMA tag. | 176The 177.Fa ds_addr 178field contains the device visible address of the DMA segment, and 179.Fa ds_len 180contains the length of the DMA segment. 181Although the DMA segments returned by a mapping call will adhere to 182all restrictions necessary for a successful DMA operation, some conversion 183(e.g.\& a conversion from host byte order to the device's byte order) is 184almost always required when presenting segment information to the device. 185.It Vt bus_dmamap_t 186A machine-dependent opaque type describing an individual mapping. 187One map is used for each memory allocation that will be loaded. 188Maps can be reused once they have been unloaded. 189Multiple maps can be associated with one DMA tag. |
| 190While the value of the map may evaluate to NULL on some platforms under 191certain conditions, it should never be assumed that it will be NULL in all 192cases. | 190While the value of the map may evaluate to 191.Dv NULL 192on some platforms under certain conditions, 193it should never be assumed that it will be 194.Dv NULL 195in all cases. |
| 193.It Vt bus_dmamap_callback_t 194Client specified callback for receiving mapping information resulting from 195the load of a 196.Vt bus_dmamap_t 197via 198.Fn bus_dmamap_load . 199Callbacks are of the format: | 196.It Vt bus_dmamap_callback_t 197Client specified callback for receiving mapping information resulting from 198the load of a 199.Vt bus_dmamap_t 200via 201.Fn bus_dmamap_load . 202Callbacks are of the format: |
| 200.Bl -tag -width compact | 203.Bl -tag -width indent |
| 201.It Ft void 202.Fn "client_callback" "void *callback_arg" "bus_dma_segment_t *segs" \ 203"int nseg" "int error" 204.El | 204.It Ft void 205.Fn "client_callback" "void *callback_arg" "bus_dma_segment_t *segs" \ 206"int nseg" "int error" 207.El |
| 205.sp | 208.Pp |
| 206The 207.Fa callback_arg 208is the callback argument passed to dmamap load functions. 209The 210.Fa segs 211and 212.Fa nseg 213parameters describe an array of --- 8 unchanged lines hidden (view full) --- 222.It Vt bus_dmamap_callback2_t 223Client specified callback for receiving mapping information resulting from 224the load of a 225.Vt bus_dmamap_t 226via 227.Fn bus_dmamap_load_uio 228or 229.Fn bus_dmamap_load_mbuf . | 209The 210.Fa callback_arg 211is the callback argument passed to dmamap load functions. 212The 213.Fa segs 214and 215.Fa nseg 216parameters describe an array of --- 8 unchanged lines hidden (view full) --- 225.It Vt bus_dmamap_callback2_t 226Client specified callback for receiving mapping information resulting from 227the load of a 228.Vt bus_dmamap_t 229via 230.Fn bus_dmamap_load_uio 231or 232.Fn bus_dmamap_load_mbuf . |
| 230.sp | 233.Pp |
| 231Callback2s are of the format: | 234Callback2s are of the format: |
| 232.Bl -tag -width compact | 235.Bl -tag -width indent |
| 233.It Ft void 234.Fn "client_callback2" "void *callback_arg" "bus_dma_segment_t *segs" \ 235"int nseg" "bus_size_t mapsize" "int error" 236.El | 236.It Ft void 237.Fn "client_callback2" "void *callback_arg" "bus_dma_segment_t *segs" \ 238"int nseg" "bus_size_t mapsize" "int error" 239.El |
| 237.sp | 240.Pp |
| 238Callback2's behavior is the same as 239.Vt bus_dmamap_callback_t 240with the addition that the length of the data mapped is provided via 241.Fa mapsize . 242.It Vt bus_dmasync_op_t 243Memory synchronization operation specifier. 244Bus DMA requires explicit synchronization of memory with its device 245visible mapping in order to guarantee memory coherency. --- 36 unchanged lines hidden (view full) --- 282the callback for a dma load operation that has been deferred with 283.Dv BUS_DMA_LOCK 284and immediately after with 285.Dv BUS_DMA_UNLOCK . 286If the load operation does not need to be deferred, then it 287will not be called since the function loading the map should 288be holding the appropriate locks. 289This method is of the format: | 241Callback2's behavior is the same as 242.Vt bus_dmamap_callback_t 243with the addition that the length of the data mapped is provided via 244.Fa mapsize . 245.It Vt bus_dmasync_op_t 246Memory synchronization operation specifier. 247Bus DMA requires explicit synchronization of memory with its device 248visible mapping in order to guarantee memory coherency. --- 36 unchanged lines hidden (view full) --- 285the callback for a dma load operation that has been deferred with 286.Dv BUS_DMA_LOCK 287and immediately after with 288.Dv BUS_DMA_UNLOCK . 289If the load operation does not need to be deferred, then it 290will not be called since the function loading the map should 291be holding the appropriate locks. 292This method is of the format: |
| 290.Bl -tag -width compact | 293.Bl -tag -width indent |
| 291.It Ft void 292.Fn "lockfunc" "void *lockfunc_arg" "bus_dma_lock_op_t op" 293.El | 294.It Ft void 295.Fn "lockfunc" "void *lockfunc_arg" "bus_dma_lock_op_t op" 296.El |
| 294.sp | 297.Pp |
| 295Two 296.Vt lockfunc 297implementations are provided for convenience. 298.Fn busdma_lock_mutex 299performs standard mutex operations on the sleep mutex provided via the 300.Fa lockfuncarg . 301passed into 302.Fn bus_dma_tag_create . 303.Fn dflt_lock 304will generate a system panic if it is called. 305It is substituted into the tag when 306.Fa lockfunc | 298Two 299.Vt lockfunc 300implementations are provided for convenience. 301.Fn busdma_lock_mutex 302performs standard mutex operations on the sleep mutex provided via the 303.Fa lockfuncarg . 304passed into 305.Fn bus_dma_tag_create . 306.Fn dflt_lock 307will generate a system panic if it is called. 308It is substituted into the tag when 309.Fa lockfunc |
| 307is passed as NULL to | 310is passed as 311.Dv NULL 312to |
| 308.Fn bus_dma_tag_create . 309.It Vt bus_dma_lock_op_t 310Operations to be performed by the client-specified 311.Fn lockfunc . | 313.Fn bus_dma_tag_create . 314.It Vt bus_dma_lock_op_t 315Operations to be performed by the client-specified 316.Fn lockfunc . |
| 312.Bl -tag -width BUS_DMA_UNLOCK | 317.Bl -tag -width ".Dv BUS_DMA_UNLOCK" |
| 313.It Dv BUS_DMA_LOCK 314Acquires and/or locks the client locking primitive. 315.It Dv BUS_DMA_UNLOCK 316Releases and/or unlocks the client locking primitive. 317.El 318.El | 318.It Dv BUS_DMA_LOCK 319Acquires and/or locks the client locking primitive. 320.It Dv BUS_DMA_UNLOCK 321Releases and/or unlocks the client locking primitive. 322.El 323.El |
| 319.sp | |
| 320.Sh FUNCTIONS | 324.Sh FUNCTIONS |
| 321.Bl -tag -width compact | 325.Bl -tag -width indent |
| 322.It Fn bus_dma_tag_create "parent" "alignment" "boundary" "lowaddr" \ 323"highaddr" "*filtfunc" "*filtfuncarg" "maxsize" "nsegments" "maxsegsz" \ 324"flags" "lockfunc" "lockfuncarg" "*dmat" 325Allocates a device specific DMA tag, and initializes it according to 326the arguments provided: | 326.It Fn bus_dma_tag_create "parent" "alignment" "boundary" "lowaddr" \ 327"highaddr" "*filtfunc" "*filtfuncarg" "maxsize" "nsegments" "maxsegsz" \ 328"flags" "lockfunc" "lockfuncarg" "*dmat" 329Allocates a device specific DMA tag, and initializes it according to 330the arguments provided: |
| 327.Bl -tag -width *filtfuncarg -compact | 331.Bl -tag -width ".Fa filtfuncarg" |
| 328.It Fa parent 329Indicates restrictions between the parent bridge, CPU memory, and the 330device. 331Each device must use a master parent tag by calling 332.Fn bus_get_dma_tag . 333.It Fa alignment 334Alignment constraint, in bytes, of any mappings created using this tag. 335The alignment must be a power of 2. --- 7 unchanged lines hidden (view full) --- 343Boundary constraint, in bytes, of the target DMA memory region. 344The boundary indicates the set of addresses, all multiples of the 345boundary argument, that cannot be crossed by a single 346.Vt bus_dma_segment_t . 347The boundary must be a power of 2 and must be no smaller than the 348maximum segment size. 349.Ql 0 350indicates that there are no boundary restrictions. | 332.It Fa parent 333Indicates restrictions between the parent bridge, CPU memory, and the 334device. 335Each device must use a master parent tag by calling 336.Fn bus_get_dma_tag . 337.It Fa alignment 338Alignment constraint, in bytes, of any mappings created using this tag. 339The alignment must be a power of 2. --- 7 unchanged lines hidden (view full) --- 347Boundary constraint, in bytes, of the target DMA memory region. 348The boundary indicates the set of addresses, all multiples of the 349boundary argument, that cannot be crossed by a single 350.Vt bus_dma_segment_t . 351The boundary must be a power of 2 and must be no smaller than the 352maximum segment size. 353.Ql 0 354indicates that there are no boundary restrictions. |
| 351.It Fa lowaddr 352.It Fa highaddr | 355.It Fa lowaddr , highaddr |
| 353Bounds of the window of bus address space that 354.Em cannot 355be directly accessed by the device. 356The window contains all addresses greater than lowaddr and 357less than or equal to highaddr. 358For example, a device incapable of DMA above 4GB, would specify 359a highaddr of 360.Dv BUS_SPACE_MAXADDR --- 7 unchanged lines hidden (view full) --- 368Some implementations requires that some region of device visible 369address space, overlapping available host memory, be outside the 370window. 371This area of 372.Ql safe memory 373is used to bounce requests that would otherwise conflict with 374the exclusion window. 375.It Fa filtfunc | 356Bounds of the window of bus address space that 357.Em cannot 358be directly accessed by the device. 359The window contains all addresses greater than lowaddr and 360less than or equal to highaddr. 361For example, a device incapable of DMA above 4GB, would specify 362a highaddr of 363.Dv BUS_SPACE_MAXADDR --- 7 unchanged lines hidden (view full) --- 371Some implementations requires that some region of device visible 372address space, overlapping available host memory, be outside the 373window. 374This area of 375.Ql safe memory 376is used to bounce requests that would otherwise conflict with 377the exclusion window. 378.It Fa filtfunc |
| 376Optional filter function (may be NULL) to be called for any attempt to | 379Optional filter function (may be 380.Dv NULL ) 381to be called for any attempt to |
| 377map memory into the window described by 378.Fa lowaddr 379and 380.Fa highaddr . 381A filter function is only required when the single window described 382by 383.Fa lowaddr 384and 385.Fa highaddr 386cannot adequately describe the constraints of the device. 387The filter function will be called for every machine page 388that overlaps the exclusion window. 389.It Fa filtfuncarg 390Argument passed to all calls to the filter function for this tag. | 382map memory into the window described by 383.Fa lowaddr 384and 385.Fa highaddr . 386A filter function is only required when the single window described 387by 388.Fa lowaddr 389and 390.Fa highaddr 391cannot adequately describe the constraints of the device. 392The filter function will be called for every machine page 393that overlaps the exclusion window. 394.It Fa filtfuncarg 395Argument passed to all calls to the filter function for this tag. |
| 391May be NULL. | 396May be 397.Dv NULL . |
| 392.It Fa maxsize 393Maximum size, in bytes, of the sum of all segment lengths in a given 394DMA mapping associated with this tag. 395.It Fa nsegments 396Number of discontinuities (scatter/gather segments) allowed 397in a DMA mapped region. 398If there is no restriction, 399.Dv BUS_SPACE_UNRESTRICTED 400may be specified. 401.It Fa maxsegsz 402Maximum size, in bytes, of a segment in any DMA mapped region associated 403with 404.Fa dmat . 405.It Fa flags 406Are as follows: | 398.It Fa maxsize 399Maximum size, in bytes, of the sum of all segment lengths in a given 400DMA mapping associated with this tag. 401.It Fa nsegments 402Number of discontinuities (scatter/gather segments) allowed 403in a DMA mapped region. 404If there is no restriction, 405.Dv BUS_SPACE_UNRESTRICTED 406may be specified. 407.It Fa maxsegsz 408Maximum size, in bytes, of a segment in any DMA mapped region associated 409with 410.Fa dmat . 411.It Fa flags 412Are as follows: |
| 407.Bl -tag -width "BUS_DMA_ALLOCNOW" -compact | 413.Bl -tag -width ".Dv BUS_DMA_ALLOCNOW" |
| 408.It Dv BUS_DMA_ALLOCNOW 409Pre-allocate enough resources to handle at least one map load operation on 410this tag. 411If sufficient resources are not available, 412.Er ENOMEM 413is returned. 414This should not be used for tags that only describe buffers that will be 415allocated with 416.Fn bus_dmamem_alloc . 417Also, due to resource sharing with other tags, this flag does not guarantee 418that resources will be allocated or reserved exclusively for this tag. 419It should be treated only as a minor optimization. 420.El 421.It Fa lockfunc | 414.It Dv BUS_DMA_ALLOCNOW 415Pre-allocate enough resources to handle at least one map load operation on 416this tag. 417If sufficient resources are not available, 418.Er ENOMEM 419is returned. 420This should not be used for tags that only describe buffers that will be 421allocated with 422.Fn bus_dmamem_alloc . 423Also, due to resource sharing with other tags, this flag does not guarantee 424that resources will be allocated or reserved exclusively for this tag. 425It should be treated only as a minor optimization. 426.El 427.It Fa lockfunc |
| 422Optional lock manipulation function (may be NULL) to be called when busdma | 428Optional lock manipulation function (may be 429.Dv NULL ) 430to be called when busdma |
| 423needs to manipulate a lock on behalf of the client. | 431needs to manipulate a lock on behalf of the client. |
| 424If NULL is specified, | 432If 433.Dv NULL 434is specified, |
| 425.Fn dflt_lock 426is used. 427.It Fa lockfuncarg 428Optional argument to be passed to the function specified by 429.Fa lockfunc . 430.It Fa dmat 431Pointer to a bus_dma_tag_t where the resulting DMA tag will 432be stored. --- 14 unchanged lines hidden (view full) --- 447if any DMA maps remain associated with 448.Fa dmat 449or 450.Ql 0 451on success. 452.It Fn bus_dmamap_create "dmat" "flags" "*mapp" 453Allocates and initializes a DMA map. 454Arguments are as follows: | 435.Fn dflt_lock 436is used. 437.It Fa lockfuncarg 438Optional argument to be passed to the function specified by 439.Fa lockfunc . 440.It Fa dmat 441Pointer to a bus_dma_tag_t where the resulting DMA tag will 442be stored. --- 14 unchanged lines hidden (view full) --- 457if any DMA maps remain associated with 458.Fa dmat 459or 460.Ql 0 461on success. 462.It Fn bus_dmamap_create "dmat" "flags" "*mapp" 463Allocates and initializes a DMA map. 464Arguments are as follows: |
| 455.Bl -tag -width nsegments -compact | 465.Bl -tag -width ".Fa nsegments" |
| 456.It Fa dmat 457DMA tag. 458.It Fa flags 459The value of this argument is currently undefined and should be 460specified as 461.Ql 0 . 462.It Fa mapp 463Pointer to a 464.Vt bus_dmamap_t 465where the resulting DMA map will be stored. 466.El 467.Pp 468Returns 469.Er ENOMEM 470if sufficient memory is not available for creating the 471map or allocating mapping resources. 472.It Fn bus_dmamap_destroy "dmat" "map" 473Frees all resources associated with a given DMA map. 474Arguments are as follows: | 466.It Fa dmat 467DMA tag. 468.It Fa flags 469The value of this argument is currently undefined and should be 470specified as 471.Ql 0 . 472.It Fa mapp 473Pointer to a 474.Vt bus_dmamap_t 475where the resulting DMA map will be stored. 476.El 477.Pp 478Returns 479.Er ENOMEM 480if sufficient memory is not available for creating the 481map or allocating mapping resources. 482.It Fn bus_dmamap_destroy "dmat" "map" 483Frees all resources associated with a given DMA map. 484Arguments are as follows: |
| 475.Bl -tag -width dmat -compact | 485.Bl -tag -width ".Fa dmat" |
| 476.It Fa dmat 477DMA tag used to allocate 478.Fa map . 479.It Fa map 480The DMA map to destroy. 481.El 482.Pp 483Returns --- 5 unchanged lines hidden (view full) --- 489Creates a mapping in device visible address space of 490.Fa buflen 491bytes of 492.Fa buf , 493associated with the DMA map 494.Fa map . 495This call will always return immediately and will not block for any reason. 496Arguments are as follows: | 486.It Fa dmat 487DMA tag used to allocate 488.Fa map . 489.It Fa map 490The DMA map to destroy. 491.El 492.Pp 493Returns --- 5 unchanged lines hidden (view full) --- 499Creates a mapping in device visible address space of 500.Fa buflen 501bytes of 502.Fa buf , 503associated with the DMA map 504.Fa map . 505This call will always return immediately and will not block for any reason. 506Arguments are as follows: |
| 497.Bl -tag -width buflen -compact | 507.Bl -tag -width ".Fa buflen" |
| 498.It Fa dmat 499DMA tag used to allocate 500.Fa map . 501.It Fa map 502A DMA map without a currently active mapping. 503.It Fa buf 504A kernel virtual address pointer to a contiguous (in KVA) buffer, to be 505mapped into device visible address space. --- 5 unchanged lines hidden (view full) --- 511the DMA operation. 512If resources are temporarily unavailable, this function will be deferred until 513later, but the load operation will still return immediately to the caller. 514Thus, callers should not assume that the callback will be called before the 515load returns, and code should be structured appropriately to handle this. 516See below for specific flags and error codes that control this behavior. 517.It Fa flags 518Are as follows: | 508.It Fa dmat 509DMA tag used to allocate 510.Fa map . 511.It Fa map 512A DMA map without a currently active mapping. 513.It Fa buf 514A kernel virtual address pointer to a contiguous (in KVA) buffer, to be 515mapped into device visible address space. --- 5 unchanged lines hidden (view full) --- 521the DMA operation. 522If resources are temporarily unavailable, this function will be deferred until 523later, but the load operation will still return immediately to the caller. 524Thus, callers should not assume that the callback will be called before the 525load returns, and code should be structured appropriately to handle this. 526See below for specific flags and error codes that control this behavior. 527.It Fa flags 528Are as follows: |
| 519.Bl -tag -width BUS_DMA_NOWAIT -compact 520.It Er BUS_DMA_NOWAIT | 529.Bl -tag -width ".Dv BUS_DMA_NOWAIT" 530.It Dv BUS_DMA_NOWAIT |
| 521The load should not be deferred in case of insufficient mapping resources, 522and instead should return immediately with an appropriate error. 523.El 524.El 525.Pp 526Return values to the caller are as follows: | 531The load should not be deferred in case of insufficient mapping resources, 532and instead should return immediately with an appropriate error. 533.El 534.El 535.Pp 536Return values to the caller are as follows: |
| 527.Bl -tag -width EINPROGRESS -compact | 537.Bl -tag -width ".Er EINPROGRESS" |
| 528.It 0 529The callback has been called and completed. 530The status of the mapping has been delivered to the callback. 531.It Er EINPROGRESS 532The mapping has been deferred for lack of resources. 533The callback will be called as soon as resources are available. 534Callbacks are serviced in FIFO order. 535To ensure that ordering is guaranteed, all subsequent load requests will also 536be deferred until all callbacks have been processed. 537.It Er ENOMEM 538The load request has failed due to insufficient resources, and the caller 539specifically used the | 538.It 0 539The callback has been called and completed. 540The status of the mapping has been delivered to the callback. 541.It Er EINPROGRESS 542The mapping has been deferred for lack of resources. 543The callback will be called as soon as resources are available. 544Callbacks are serviced in FIFO order. 545To ensure that ordering is guaranteed, all subsequent load requests will also 546be deferred until all callbacks have been processed. 547.It Er ENOMEM 548The load request has failed due to insufficient resources, and the caller 549specifically used the |
| 540.Fa BUS_DMA_NOWAIT | 550.Dv BUS_DMA_NOWAIT |
| 541flag. 542.It Er EINVAL 543The load request was invalid. 544The callback has been called and has been provided the same error. 545This error value may indicate that 546.Fa dmat , 547.Fa map , 548.Fa buf , --- 5 unchanged lines hidden (view full) --- 554.Fa maxsize 555argument used to create the dma tag 556.Fa dmat . 557.El 558.Pp 559When the callback is called, it is presented with an error value 560indicating the disposition of the mapping. 561Error may be one of the following: | 551flag. 552.It Er EINVAL 553The load request was invalid. 554The callback has been called and has been provided the same error. 555This error value may indicate that 556.Fa dmat , 557.Fa map , 558.Fa buf , --- 5 unchanged lines hidden (view full) --- 564.Fa maxsize 565argument used to create the dma tag 566.Fa dmat . 567.El 568.Pp 569When the callback is called, it is presented with an error value 570indicating the disposition of the mapping. 571Error may be one of the following: |
| 562.Bl -tag -width EINPROGRESS -compact | 572.Bl -tag -width ".Er EINPROGRESS" |
| 563.It 0 564The mapping was successful and the 565.Fa dm_segs 566callback argument contains an array of 567.Vt bus_dma_segment_t 568elements describing the mapping. 569This array is only valid during the scope of the callback function. 570.It Er EFBIG --- 6 unchanged lines hidden (view full) --- 577.Fn bus_dmamap_load 578which maps mbuf chains 579for DMA transfers. 580A 581.Vt bus_size_t 582argument is also passed to the callback routine, which 583contains the mbuf chain's packet header length. 584The | 573.It 0 574The mapping was successful and the 575.Fa dm_segs 576callback argument contains an array of 577.Vt bus_dma_segment_t 578elements describing the mapping. 579This array is only valid during the scope of the callback function. 580.It Er EFBIG --- 6 unchanged lines hidden (view full) --- 587.Fn bus_dmamap_load 588which maps mbuf chains 589for DMA transfers. 590A 591.Vt bus_size_t 592argument is also passed to the callback routine, which 593contains the mbuf chain's packet header length. 594The |
| 585.Fa BUS_DMA_NOWAIT | 595.Dv BUS_DMA_NOWAIT |
| 586flag is implied, thus no callback deferral will happen. 587.Pp 588Mbuf chains are assumed to be in kernel virtual address space. 589.Pp 590Beside the error values listed for 591.Fn bus_dmamap_load , 592.Er EINVAL 593will be returned if the size of the mbuf chain exceeds the maximum limit of the --- 19 unchanged lines hidden (view full) --- 613for DMA transfers. 614A 615.Vt bus_size_t 616argument is also passed to the callback routine, which contains the size of 617.Fa uio , 618i.e. 619.Fa uio->uio_resid . 620The | 596flag is implied, thus no callback deferral will happen. 597.Pp 598Mbuf chains are assumed to be in kernel virtual address space. 599.Pp 600Beside the error values listed for 601.Fn bus_dmamap_load , 602.Er EINVAL 603will be returned if the size of the mbuf chain exceeds the maximum limit of the --- 19 unchanged lines hidden (view full) --- 623for DMA transfers. 624A 625.Vt bus_size_t 626argument is also passed to the callback routine, which contains the size of 627.Fa uio , 628i.e. 629.Fa uio->uio_resid . 630The |
| 621.Fa BUS_DMA_NOWAIT | 631.Dv BUS_DMA_NOWAIT |
| 622flag is implied, thus no callback deferral will happen. 623Returns the same errors as 624.Fn bus_dmamap_load . 625.Pp 626If 627.Fa uio->uio_segflg 628is 629.Dv UIO_USERSPACE , --- 4 unchanged lines hidden (view full) --- 634address space. 635User space memory must be in-core and wired prior to attempting a map 636load operation. 637Pages may be locked using 638.Xr vslock 9 . 639.It Fn bus_dmamap_unload "dmat" "map" 640Unloads a DMA map. 641Arguments are as follows: | 632flag is implied, thus no callback deferral will happen. 633Returns the same errors as 634.Fn bus_dmamap_load . 635.Pp 636If 637.Fa uio->uio_segflg 638is 639.Dv UIO_USERSPACE , --- 4 unchanged lines hidden (view full) --- 644address space. 645User space memory must be in-core and wired prior to attempting a map 646load operation. 647Pages may be locked using 648.Xr vslock 9 . 649.It Fn bus_dmamap_unload "dmat" "map" 650Unloads a DMA map. 651Arguments are as follows: |
| 642.Bl -tag -width dmam -compact | 652.Bl -tag -width ".Fa dmam" |
| 643.It Fa dmat 644DMA tag used to allocate 645.Fa map . 646.It Fa map 647The DMA map that is to be unloaded. 648.El 649.Pp 650.Fn bus_dmamap_unload 651will not perform any implicit synchronization of DMA buffers. 652This must be done explicitly by a call to 653.Fn bus_dmamap_sync 654prior to unloading the map. 655.It Fn bus_dmamap_sync "dmat" "map" "op" 656Performs synchronization of a device visible mapping with the CPU visible 657memory referenced by that mapping. 658Arguments are as follows: | 653.It Fa dmat 654DMA tag used to allocate 655.Fa map . 656.It Fa map 657The DMA map that is to be unloaded. 658.El 659.Pp 660.Fn bus_dmamap_unload 661will not perform any implicit synchronization of DMA buffers. 662This must be done explicitly by a call to 663.Fn bus_dmamap_sync 664prior to unloading the map. 665.It Fn bus_dmamap_sync "dmat" "map" "op" 666Performs synchronization of a device visible mapping with the CPU visible 667memory referenced by that mapping. 668Arguments are as follows: |
| 659.Bl -tag -width dmat -compact | 669.Bl -tag -width ".Fa dmat" |
| 660.It Fa dmat 661DMA tag used to allocate 662.Fa map . 663.It Fa map 664The DMA mapping to be synchronized. 665.It Fa op 666Type of synchronization operation to perform. 667See the definition of --- 33 unchanged lines hidden (view full) --- 701Allocates memory that is mapped into KVA at the address returned 702in 703.Fa vaddr 704that is permanently loaded into the newly created 705.Vt bus_dmamap_t 706returned via 707.Fa mapp . 708Arguments are as follows: | 670.It Fa dmat 671DMA tag used to allocate 672.Fa map . 673.It Fa map 674The DMA mapping to be synchronized. 675.It Fa op 676Type of synchronization operation to perform. 677See the definition of --- 33 unchanged lines hidden (view full) --- 711Allocates memory that is mapped into KVA at the address returned 712in 713.Fa vaddr 714that is permanently loaded into the newly created 715.Vt bus_dmamap_t 716returned via 717.Fa mapp . 718Arguments are as follows: |
| 709.Bl -tag -width alignment -compact | 719.Bl -tag -width ".Fa alignment" |
| 710.It Fa dmat 711DMA tag describing the constraints of the DMA mapping. 712.It Fa vaddr 713Pointer to a pointer that will hold the returned KVA mapping of 714the allocated region. 715.It Fa flags 716Flags are defined as follows: | 720.It Fa dmat 721DMA tag describing the constraints of the DMA mapping. 722.It Fa vaddr 723Pointer to a pointer that will hold the returned KVA mapping of 724the allocated region. 725.It Fa flags 726Flags are defined as follows: |
| 717.Bl -tag -width BUS_DMA_NOWAIT -compact | 727.Bl -tag -width ".Dv BUS_DMA_NOWAIT" |
| 718.It Dv BUS_DMA_WAITOK 719The routine can safely wait (sleep) for resources. 720.It Dv BUS_DMA_NOWAIT 721The routine is not allowed to wait for resources. 722If resources are not available, 723.Dv ENOMEM 724is returned. 725.It Dv BUS_DMA_COHERENT 726Attempt to map this memory such that cache sync operations are 727as cheap as possible. 728This flag is typically set on memory that will be accessed by both 729a CPU and a DMA engine, frequently. 730Use of this flag does not remove the requirement of using 731bus_dmamap_sync, but it may reduce the cost of performing 732these operations. | 728.It Dv BUS_DMA_WAITOK 729The routine can safely wait (sleep) for resources. 730.It Dv BUS_DMA_NOWAIT 731The routine is not allowed to wait for resources. 732If resources are not available, 733.Dv ENOMEM 734is returned. 735.It Dv BUS_DMA_COHERENT 736Attempt to map this memory such that cache sync operations are 737as cheap as possible. 738This flag is typically set on memory that will be accessed by both 739a CPU and a DMA engine, frequently. 740Use of this flag does not remove the requirement of using 741bus_dmamap_sync, but it may reduce the cost of performing 742these operations. |
| 733The BUS_DMA_COHERENT flag is currently implemented on sparc64 and arm. | 743The 744.Dv BUS_DMA_COHERENT 745flag is currently implemented on sparc64 and arm. |
| 734.It Dv BUS_DMA_ZERO 735Causes the allocated memory to be set to all zeros. 736.El 737.It Fa mapp 738Pointer to a 739.Vt bus_dmamap_t 740where the resulting DMA map will be stored. 741.El --- 26 unchanged lines hidden (view full) --- 768if sufficient memory is not available for completing 769the operation. 770.It Fn bus_dmamem_free "dmat" "*vaddr" "map" 771Frees memory previously allocated by 772.Fn bus_dmamem_alloc . 773Any mappings 774will be invalidated. 775Arguments are as follows: | 746.It Dv BUS_DMA_ZERO 747Causes the allocated memory to be set to all zeros. 748.El 749.It Fa mapp 750Pointer to a 751.Vt bus_dmamap_t 752where the resulting DMA map will be stored. 753.El --- 26 unchanged lines hidden (view full) --- 780if sufficient memory is not available for completing 781the operation. 782.It Fn bus_dmamem_free "dmat" "*vaddr" "map" 783Frees memory previously allocated by 784.Fn bus_dmamem_alloc . 785Any mappings 786will be invalidated. 787Arguments are as follows: |
| 776.Bl -tag -width vaddr -compact | 788.Bl -tag -width ".Fa vaddr" |
| 777.It Fa dmat 778DMA tag. 779.It Fa vaddr 780Kernel virtual address of the memory. 781.It Fa map 782DMA map to be invalidated. 783.El 784.El --- 33 unchanged lines hidden (view full) --- 818acts on its own without being called by the driver, the lock primitive 819specified in the tag is acquired and released automatically. 820An example of this is when the 821.Fn bus_dmamap_load 822callback function is called from a deferred context instead of the driver 823context. 824This means that certain 825.Nm | 789.It Fa dmat 790DMA tag. 791.It Fa vaddr 792Kernel virtual address of the memory. 793.It Fa map 794DMA map to be invalidated. 795.El 796.El --- 33 unchanged lines hidden (view full) --- 830acts on its own without being called by the driver, the lock primitive 831specified in the tag is acquired and released automatically. 832An example of this is when the 833.Fn bus_dmamap_load 834callback function is called from a deferred context instead of the driver 835context. 836This means that certain 837.Nm |
| 826functions must always be called with same lock held that is specified in the 827tag. These functions include: | 838functions must always be called with the same lock held that is specified in the 839tag. 840These functions include: |
| 828.Pp | 841.Pp |
| 829.Bl -inset -offset indent -compact 830.It bus_dmamap_load 831.It bus_dmamap_load_uio 832.It bus_dmamap_load_mbuf 833.It bus_dmamap_load_mbuf_sg 834.It bus_dmamap_unload 835.It bus_dmamap_sync | 842.Bl -item -offset indent -compact 843.It 844.Fn bus_dmamap_load 845.It 846.Fn bus_dmamap_load_uio 847.It 848.Fn bus_dmamap_load_mbuf 849.It 850.Fn bus_dmamap_load_mbuf_sg 851.It 852.Fn bus_dmamap_unload 853.It 854.Fn bus_dmamap_sync |
| 836.El 837.Pp 838There is one exception to this rule. 839It is common practice to call some of these functions during driver start-up 840without any locks held. 841So long as there is a guarantee of no possible concurrent use of the tag by 842different threads during this operation, it is safe to not hold a lock for 843these functions. 844.Pp 845Certain 846.Nm 847operations should not be called with the driver lock held, either because 848they are already protected by an internal lock, or because they might sleep | 855.El 856.Pp 857There is one exception to this rule. 858It is common practice to call some of these functions during driver start-up 859without any locks held. 860So long as there is a guarantee of no possible concurrent use of the tag by 861different threads during this operation, it is safe to not hold a lock for 862these functions. 863.Pp 864Certain 865.Nm 866operations should not be called with the driver lock held, either because 867they are already protected by an internal lock, or because they might sleep |
| 849due to memory or resource allocation. The following functions must not be | 868due to memory or resource allocation. 869The following functions must not be |
| 850called with any non-sleepable locks held: 851.Pp | 870called with any non-sleepable locks held: 871.Pp |
| 852.Bl -inset -offset indent -compact 853.It bus_dma_tag_create 854.It bus_dmamap_create 855.It bus_dmamem_alloc | 872.Bl -item -offset indent -compact 873.It 874.Fn bus_dma_tag_create 875.It 876.Fn bus_dmamap_create 877.It 878.Fn bus_dmamem_alloc |
| 856.El 857.Pp 858All other functions do not have a locking protocol and can thus be 859called with or without and system or driver locks held. 860.Sh SEE ALSO 861.Xr devclass 9 , 862.Xr device 9 , 863.Xr driver 9 , --- 65 unchanged lines hidden --- | 879.El 880.Pp 881All other functions do not have a locking protocol and can thus be 882called with or without and system or driver locks held. 883.Sh SEE ALSO 884.Xr devclass 9 , 885.Xr device 9 , 886.Xr driver 9 , --- 65 unchanged lines hidden --- |