| bus_dma.9 (165213) | bus_dma.9 (167274) |
|---|---|
| 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 165213 2006-12-14 14:33:13Z mpp $ | 60.\" $FreeBSD: head/share/man/man9/bus_dma.9 167274 2007-03-06 17:32:49Z jhb $ |
| 61.\" $NetBSD: bus_dma.9,v 1.25 2002/10/14 13:43:16 wiz Exp $ 62.\" | 61.\" $NetBSD: bus_dma.9,v 1.25 2002/10/14 13:43:16 wiz Exp $ 62.\" |
| 63.Dd August 31, 2006 | 63.Dd March 6, 2007 |
| 64.Dt BUS_DMA 9 65.Os 66.Sh NAME 67.Nm bus_dma , 68.Nm bus_dma_tag_create , 69.Nm bus_dma_tag_destroy , 70.Nm bus_dmamap_create , 71.Nm bus_dmamap_destroy , --- 76 unchanged lines hidden (view full) --- 148.Fn "client_filter" "void *filtarg" "bus_addr_t testaddr" 149.El 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 | 64.Dt BUS_DMA 9 65.Os 66.Sh NAME 67.Nm bus_dma , 68.Nm bus_dma_tag_create , 69.Nm bus_dma_tag_destroy , 70.Nm bus_dmamap_create , 71.Nm bus_dmamap_destroy , --- 76 unchanged lines hidden (view full) --- 148.Fn "client_filter" "void *filtarg" "bus_addr_t testaddr" 149.El 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 | 156argument is specified by the client during tag creation to be passed to all |
| 157invocations of the callback. 158The 159.Fa testaddr 160argument contains a potential starting address of a DMA mapping. 161The filter function operates on the set of addresses from 162.Fa testaddr 163to 164.Ql trunc_page(testaddr) + PAGE_SIZE - 1 , 165inclusive. | 157invocations of the callback. 158The 159.Fa testaddr 160argument contains a potential starting address of a DMA mapping. 161The filter function operates on the set of addresses from 162.Fa testaddr 163to 164.Ql trunc_page(testaddr) + PAGE_SIZE - 1 , 165inclusive. |
| 166The filter function should return zero for any mapping in this range 167that can be accommodated by the device and non-zero otherwise. | 166The filter function should return zero if any mapping in this range 167can 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. | 168.It Vt bus_dma_segment_t 169A machine-dependent type that describes individual 170DMA segments. |
| 171It contains the following fields: |
|
| 171.Bd -literal 172 bus_addr_t ds_addr; 173 bus_size_t ds_len; 174.Ed 175.Pp 176The 177.Fa ds_addr 178field contains the device visible address of the DMA segment, and --- 29 unchanged lines hidden (view full) --- 208.Pp 209The 210.Fa callback_arg 211is the callback argument passed to dmamap load functions. 212The 213.Fa segs 214and 215.Fa nseg | 172.Bd -literal 173 bus_addr_t ds_addr; 174 bus_size_t ds_len; 175.Ed 176.Pp 177The 178.Fa ds_addr 179field contains the device visible address of the DMA segment, and --- 29 unchanged lines hidden (view full) --- 209.Pp 210The 211.Fa callback_arg 212is the callback argument passed to dmamap load functions. 213The 214.Fa segs 215and 216.Fa nseg |
| 216parameters describe an array of | 217arguments describe an array of |
| 217.Vt bus_dma_segment_t 218structures that represent the mapping. 219This array is only valid within the scope of the callback function. 220The success or failure of the mapping is indicated by the 221.Fa error | 218.Vt bus_dma_segment_t 219structures that represent the mapping. 220This array is only valid within the scope of the callback function. 221The success or failure of the mapping is indicated by the 222.Fa error |
| 222parameter. | 223argument. |
| 223More information on the use of callbacks can be found in the 224description of the individual dmamap load functions. 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 --- 39 unchanged lines hidden (view full) --- 270device. 271.It Dv BUS_DMASYNC_PREWRITE 272Perform any synchronization required after an update of host memory by the CPU 273and prior to device access to host memory. 274.It Dv BUS_DMASYNC_POSTREAD 275Perform any synchronization required after an update of host memory by the 276device and prior to CPU access to host memory. 277.It Dv BUS_DMASYNC_POSTWRITE | 224More information on the use of callbacks can be found in the 225description of the individual dmamap load functions. 226.It Vt bus_dmamap_callback2_t 227Client specified callback for receiving mapping information resulting from 228the load of a 229.Vt bus_dmamap_t 230via 231.Fn bus_dmamap_load_uio --- 39 unchanged lines hidden (view full) --- 271device. 272.It Dv BUS_DMASYNC_PREWRITE 273Perform any synchronization required after an update of host memory by the CPU 274and prior to device access to host memory. 275.It Dv BUS_DMASYNC_POSTREAD 276Perform any synchronization required after an update of host memory by the 277device and prior to CPU access to host memory. 278.It Dv BUS_DMASYNC_POSTWRITE |
| 278Perform any synchronization required after the device access to host memory. | 279Perform any synchronization required after device access to host memory. |
| 279.El 280.It Vt bus_dma_lock_t 281Client specified lock/mutex manipulation method. 282This will be called from 283within busdma whenever a client lock needs to be manipulated. 284In its current form, the function will be called immediately before 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: 293.Bl -tag -width indent 294.It Ft void 295.Fn "lockfunc" "void *lockfunc_arg" "bus_dma_lock_op_t op" 296.El 297.Pp | 280.El 281.It Vt bus_dma_lock_t 282Client specified lock/mutex manipulation method. 283This will be called from 284within busdma whenever a client lock needs to be manipulated. 285In its current form, the function will be called immediately before 286the callback for a dma load operation that has been deferred with 287.Dv BUS_DMA_LOCK 288and immediately after with 289.Dv BUS_DMA_UNLOCK . 290If the load operation does not need to be deferred, then it 291will not be called since the function loading the map should 292be holding the appropriate locks. 293This method is of the format: 294.Bl -tag -width indent 295.It Ft void 296.Fn "lockfunc" "void *lockfunc_arg" "bus_dma_lock_op_t op" 297.El 298.Pp |
| 299The 300.Fa lockfuncarg 301argument is specified by the client during tag creation to be passed to all 302invocations of the callback. 303The 304.Fa op 305argument specifies the lock operation to perform. 306.Pp |
|
| 298Two 299.Vt lockfunc 300implementations are provided for convenience. 301.Fn busdma_lock_mutex | 307Two 308.Vt lockfunc 309implementations are provided for convenience. 310.Fn busdma_lock_mutex |
| 302performs standard mutex operations on the sleep mutex provided via the | 311performs standard mutex operations on the sleep mutex provided via |
| 303.Fa lockfuncarg . | 312.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 310is passed as 311.Dv NULL 312to | 313.Fn dflt_lock 314will generate a system panic if it is called. 315It is substituted into the tag when 316.Fa lockfunc 317is passed as 318.Dv NULL 319to |
| 313.Fn bus_dma_tag_create . | 320.Fn bus_dma_tag_create 321and is useful for tags that should not be used with deferred load operations. |
| 314.It Vt bus_dma_lock_op_t 315Operations to be performed by the client-specified 316.Fn lockfunc . 317.Bl -tag -width ".Dv BUS_DMA_UNLOCK" 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. --- 364 unchanged lines hidden (view full) --- 686is the method used to ensure that CPU's and device's direct 687memory access (DMA) to shared 688memory is coherent. 689For example, the CPU might be used to set up the contents of a buffer 690that is to be made available to a device. 691To ensure that the data are visible via the device's mapping of that 692memory, the buffer must be loaded and a DMA sync operation of 693.Dv BUS_DMASYNC_PREWRITE | 322.It Vt bus_dma_lock_op_t 323Operations to be performed by the client-specified 324.Fn lockfunc . 325.Bl -tag -width ".Dv BUS_DMA_UNLOCK" 326.It Dv BUS_DMA_LOCK 327Acquires and/or locks the client locking primitive. 328.It Dv BUS_DMA_UNLOCK 329Releases and/or unlocks the client locking primitive. --- 364 unchanged lines hidden (view full) --- 694is the method used to ensure that CPU's and device's direct 695memory access (DMA) to shared 696memory is coherent. 697For example, the CPU might be used to set up the contents of a buffer 698that is to be made available to a device. 699To ensure that the data are visible via the device's mapping of that 700memory, the buffer must be loaded and a DMA sync operation of 701.Dv BUS_DMASYNC_PREWRITE |
| 694must be performed. 695If later CPU modifies this buffer again, another | 702must be performed after the CPU has updated the buffer and before the device 703access is initiated. 704If the CPU modifies this buffer again later, another |
| 696.Dv BUS_DMASYNC_PREWRITE | 705.Dv BUS_DMASYNC_PREWRITE |
| 697sync operation must be performed before an additional 698access to this memory by a device. 699Conversely, a device updates the memory that is to be read by a CPU. | 706sync operation must be performed before an additional device 707access. 708Conversely, suppose a device updates memory that is to be read by a CPU. |
| 700In this case, the buffer must be loaded, and a DMA sync operation of 701.Dv BUS_DMASYNC_PREREAD | 709In this case, the buffer must be loaded, and a DMA sync operation of 710.Dv BUS_DMASYNC_PREREAD |
| 702must be performed. | 711must be performed before the device access is initiated. |
| 703The CPU will only be able to see the results of this memory update 704once the DMA operation has completed and a 705.Dv BUS_DMASYNC_POSTREAD 706sync operation has been performed. 707.Pp 708If read and write operations are not preceded and followed by the 709appropriate synchronization operations, behavior is undefined. 710.It Fn bus_dmamem_alloc "dmat" "**vaddr" "flags" "*mapp" 711Allocates memory that is mapped into KVA at the address returned 712in 713.Fa vaddr | 712The CPU will only be able to see the results of this memory update 713once the DMA operation has completed and a 714.Dv BUS_DMASYNC_POSTREAD 715sync operation has been performed. 716.Pp 717If read and write operations are not preceded and followed by the 718appropriate synchronization operations, behavior is undefined. 719.It Fn bus_dmamem_alloc "dmat" "**vaddr" "flags" "*mapp" 720Allocates memory that is mapped into KVA at the address returned 721in 722.Fa vaddr |
| 714that is permanently loaded into the newly created | 723and that is permanently loaded into the newly created |
| 715.Vt bus_dmamap_t 716returned via 717.Fa mapp . 718Arguments are as follows: 719.Bl -tag -width ".Fa alignment" 720.It Fa dmat 721DMA tag describing the constraints of the DMA mapping. 722.It Fa vaddr --- 26 unchanged lines hidden (view full) --- 749.It Fa mapp 750Pointer to a 751.Vt bus_dmamap_t 752where the resulting DMA map will be stored. 753.El 754.Pp 755The size of memory to be allocated is 756.Fa maxsize | 724.Vt bus_dmamap_t 725returned via 726.Fa mapp . 727Arguments are as follows: 728.Bl -tag -width ".Fa alignment" 729.It Fa dmat 730DMA tag describing the constraints of the DMA mapping. 731.It Fa vaddr --- 26 unchanged lines hidden (view full) --- 758.It Fa mapp 759Pointer to a 760.Vt bus_dmamap_t 761where the resulting DMA map will be stored. 762.El 763.Pp 764The size of memory to be allocated is 765.Fa maxsize |
| 757as specified in | 766as specified in the call to 767.Fn bus_dma_tag_create 768for |
| 758.Fa dmat . 759.Pp 760The current implementation of 761.Fn bus_dmamem_alloc 762will allocate all requests as a single segment. 763.Pp 764An initial load operation is required to obtain the bus address of the allocated 765memory, and an unload operation is required before freeing the memory, as --- 31 unchanged lines hidden (view full) --- 797.Sh RETURN VALUES 798Behavior is undefined if invalid arguments are passed to 799any of the above functions. 800If sufficient resources cannot be allocated for a given 801transaction, 802.Er ENOMEM 803is returned. 804All | 769.Fa dmat . 770.Pp 771The current implementation of 772.Fn bus_dmamem_alloc 773will allocate all requests as a single segment. 774.Pp 775An initial load operation is required to obtain the bus address of the allocated 776memory, and an unload operation is required before freeing the memory, as --- 31 unchanged lines hidden (view full) --- 808.Sh RETURN VALUES 809Behavior is undefined if invalid arguments are passed to 810any of the above functions. 811If sufficient resources cannot be allocated for a given 812transaction, 813.Er ENOMEM 814is returned. 815All |
| 805routines that are not of type, 806.Vt void , | 816routines that are not of type 817.Vt void |
| 807will return 0 on success or an error | 818will return 0 on success or an error |
| 808code, as discussed above. | 819code on failure as discussed above. |
| 809.Pp 810All 811.Vt void 812routines will succeed if provided with valid arguments. 813.Sh LOCKING 814Two locking protocols are used by 815.Nm . 816The first is a private global lock that is used to synchronize access to the --- 57 unchanged lines hidden (view full) --- 874.Fn bus_dma_tag_create 875.It 876.Fn bus_dmamap_create 877.It 878.Fn bus_dmamem_alloc 879.El 880.Pp 881All other functions do not have a locking protocol and can thus be | 820.Pp 821All 822.Vt void 823routines will succeed if provided with valid arguments. 824.Sh LOCKING 825Two locking protocols are used by 826.Nm . 827The first is a private global lock that is used to synchronize access to the --- 57 unchanged lines hidden (view full) --- 885.Fn bus_dma_tag_create 886.It 887.Fn bus_dmamap_create 888.It 889.Fn bus_dmamem_alloc 890.El 891.Pp 892All other functions do not have a locking protocol and can thus be |
| 882called with or without and system or driver locks held. | 893called with or without any system or driver locks held. |
| 883.Sh SEE ALSO 884.Xr devclass 9 , 885.Xr device 9 , 886.Xr driver 9 , 887.Xr rman 9 , 888.Xr vslock 9 889.Pp 890.Rs --- 61 unchanged lines hidden --- | 894.Sh SEE ALSO 895.Xr devclass 9 , 896.Xr device 9 , 897.Xr driver 9 , 898.Xr rman 9 , 899.Xr vslock 9 900.Pp 901.Rs --- 61 unchanged lines hidden --- |