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, 9.\" without modification, immediately at the beginning of the file. 10.\" 2. The name of the author may not be used to endorse or promote products 11.\" derived from this software without specific prior written permission. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR, CONTRIBUTORS OR THE 17.\" VOICES IN HITEN PANDYA'S HEAD BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 18.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED 19.\" TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 20.\" PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 21.\" LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 22.\" NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 23.\" SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 24.\" 25.\" Copyright (c) 1996, 1997, 1998, 2001 The NetBSD Foundation, Inc. 26.\" All rights reserved. 27.\" 28.\" This code is derived from software contributed to The NetBSD Foundation 29.\" by Jason R. Thorpe of the Numerical Aerospace Simulation Facility, 30.\" NASA Ames Research Center. 31.\" 32.\" Redistribution and use in source and binary forms, with or without 33.\" modification, are permitted provided that the following conditions 34.\" are met: 35.\" 1. Redistributions of source code must retain the above copyright 36.\" notice, this list of conditions and the following disclaimer. 37.\" 2. Redistributions in binary form must reproduce the above copyright 38.\" notice, this list of conditions and the following disclaimer in the 39.\" documentation and/or other materials provided with the distribution. 40.\" 41.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 42.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 43.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 44.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 45.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 46.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 47.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 48.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 49.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 50.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 51.\" POSSIBILITY OF SUCH DAMAGE. 52.\" 53.\" $FreeBSD$ 54.\" $NetBSD: bus_dma.9,v 1.25 2002/10/14 13:43:16 wiz Exp $ 55.\" 56.Dd July 17, 2013 57.Dt BUS_DMA 9 58.Os 59.Sh NAME 60.Nm bus_dma , 61.Nm bus_dma_tag_create , 62.Nm bus_dma_tag_destroy , 63.Nm bus_dmamap_create , 64.Nm bus_dmamap_destroy , 65.Nm bus_dmamap_load , 66.Nm bus_dmamap_load_bio , 67.Nm bus_dmamap_load_ccb , 68.Nm bus_dmamap_load_mbuf , 69.Nm bus_dmamap_load_mbuf_sg , 70.Nm bus_dmamap_load_uio , 71.Nm bus_dmamap_unload , 72.Nm bus_dmamap_sync , 73.Nm bus_dmamem_alloc , 74.Nm bus_dmamem_free 75.Nd Bus and Machine Independent DMA Mapping Interface 76.Sh SYNOPSIS 77.In machine/bus.h 78.Ft int 79.Fn bus_dma_tag_create "bus_dma_tag_t parent" "bus_size_t alignment" \ 80"bus_addr_t boundary" "bus_addr_t lowaddr" "bus_addr_t highaddr" \ 81"bus_dma_filter_t *filtfunc" "void *filtfuncarg" "bus_size_t maxsize" \ 82"int nsegments" "bus_size_t maxsegsz" "int flags" "bus_dma_lock_t *lockfunc" \ 83"void *lockfuncarg" "bus_dma_tag_t *dmat" 84.Ft int 85.Fn bus_dma_tag_destroy "bus_dma_tag_t dmat" 86.Ft int 87.Fn bus_dmamap_create "bus_dma_tag_t dmat" "int flags" "bus_dmamap_t *mapp" 88.Ft int 89.Fn bus_dmamap_destroy "bus_dma_tag_t dmat" "bus_dmamap_t map" 90.Ft int 91.Fn bus_dmamap_load "bus_dma_tag_t dmat" "bus_dmamap_t map" "void *buf" \ 92"bus_size_t buflen" "bus_dmamap_callback_t *callback" "void *callback_arg" \ 93"int flags" 94.Ft int 95.Fn bus_dmamap_load_bio "bus_dma_tag_t dmat" "bus_dmamap_t map" \ 96"struct bio *bio" "bus_dmamap_callback_t *callback" "void *callback_arg" \ 97"int flags" 98.Ft int 99.Fn bus_dmamap_load_ccb "bus_dma_tag_t dmat" "bus_dmamap_t map" \ 100"union ccb *ccb" "bus_dmamap_callback_t *callback" "void *callback_arg" \ 101"int flags" 102.Ft int 103.Fn bus_dmamap_load_mbuf "bus_dma_tag_t dmat" "bus_dmamap_t map" \ 104"struct mbuf *mbuf" "bus_dmamap_callback2_t *callback" "void *callback_arg" \ 105"int flags" 106.Ft int 107.Fn bus_dmamap_load_mbuf_sg "bus_dma_tag_t dmat" "bus_dmamap_t map" \ 108"struct mbuf *mbuf" "bus_dma_segment_t *segs" "int *nsegs" "int flags" 109.Ft int 110.Fn bus_dmamap_load_uio "bus_dma_tag_t dmat" "bus_dmamap_t map" \ 111"struct uio *uio" "bus_dmamap_callback2_t *callback" "void *callback_arg" \ 112"int flags" 113.Ft void 114.Fn bus_dmamap_unload "bus_dma_tag_t dmat" "bus_dmamap_t map" 115.Ft void 116.Fn bus_dmamap_sync "bus_dma_tag_t dmat" "bus_dmamap_t map" \ 117"op" 118.Ft int 119.Fn bus_dmamem_alloc "bus_dma_tag_t dmat" "void **vaddr" \ 120"int flags" "bus_dmamap_t *mapp" 121.Ft void 122.Fn bus_dmamem_free "bus_dma_tag_t dmat" "void *vaddr" \ 123"bus_dmamap_t map" 124.Sh DESCRIPTION 125Direct Memory Access (DMA) is a method of transferring data 126without involving the CPU, thus providing higher performance. 127A DMA transaction can be achieved between device to memory, 128device to device, or memory to memory. 129.Pp 130The 131.Nm 132API is a bus, device, and machine-independent (MI) interface to 133DMA mechanisms. 134It provides the client with flexibility and simplicity by 135abstracting machine dependent issues like setting up 136DMA mappings, handling cache issues, bus specific features 137and limitations. 138.Sh STRUCTURES AND TYPES 139.Bl -tag -width indent 140.It Vt bus_dma_tag_t 141A machine-dependent (MD) opaque type that describes the 142characteristics of DMA transactions. 143DMA tags are organized into a hierarchy, with each child 144tag inheriting the restrictions of its parent. 145This allows all devices along the path of DMA transactions 146to contribute to the constraints of those transactions. 147.It Vt bus_dma_filter_t 148Client specified address filter having the format: 149.Bl -tag -width indent 150.It Ft int 151.Fn "client_filter" "void *filtarg" "bus_addr_t testaddr" 152.El 153.Pp 154Address filters can be specified during tag creation to allow 155for devices whose DMA address restrictions cannot be specified 156by a single window. 157The 158.Fa filtarg 159argument is specified by the client during tag creation to be passed to all 160invocations of the callback. 161The 162.Fa testaddr 163argument contains a potential starting address of a DMA mapping. 164The filter function operates on the set of addresses from 165.Fa testaddr 166to 167.Ql trunc_page(testaddr) + PAGE_SIZE - 1 , 168inclusive. 169The filter function should return zero if any mapping in this range 170can be accommodated by the device and non-zero otherwise. 171.It Vt bus_dma_segment_t 172A machine-dependent type that describes individual 173DMA segments. 174It contains the following fields: 175.Bd -literal 176 bus_addr_t ds_addr; 177 bus_size_t ds_len; 178.Ed 179.Pp 180The 181.Fa ds_addr 182field contains the device visible address of the DMA segment, and 183.Fa ds_len 184contains the length of the DMA segment. 185Although the DMA segments returned by a mapping call will adhere to 186all restrictions necessary for a successful DMA operation, some conversion 187(e.g.\& a conversion from host byte order to the device's byte order) is 188almost always required when presenting segment information to the device. 189.It Vt bus_dmamap_t 190A machine-dependent opaque type describing an individual mapping. 191One map is used for each memory allocation that will be loaded. 192Maps can be reused once they have been unloaded. 193Multiple maps can be associated with one DMA tag. 194While the value of the map may evaluate to 195.Dv NULL 196on some platforms under certain conditions, 197it should never be assumed that it will be 198.Dv NULL 199in all cases. 200.It Vt bus_dmamap_callback_t 201Client specified callback for receiving mapping information resulting from 202the load of a 203.Vt bus_dmamap_t 204via 205.Fn bus_dmamap_load , 206.Fn bus_dmamap_load_bio 207or 208.Fn bus_dmamap_load_ccb . 209Callbacks are of the format: 210.Bl -tag -width indent 211.It Ft void 212.Fn "client_callback" "void *callback_arg" "bus_dma_segment_t *segs" \ 213"int nseg" "int error" 214.El 215.Pp 216The 217.Fa callback_arg 218is the callback argument passed to dmamap load functions. 219The 220.Fa segs 221and 222.Fa nseg 223arguments describe an array of 224.Vt bus_dma_segment_t 225structures that represent the mapping. 226This array is only valid within the scope of the callback function. 227The success or failure of the mapping is indicated by the 228.Fa error 229argument. 230More information on the use of callbacks can be found in the 231description of the individual dmamap load functions. 232.It Vt bus_dmamap_callback2_t 233Client specified callback for receiving mapping information resulting from 234the load of a 235.Vt bus_dmamap_t 236via 237.Fn bus_dmamap_load_uio 238or 239.Fn bus_dmamap_load_mbuf . 240.Pp 241Callback2s are of the format: 242.Bl -tag -width indent 243.It Ft void 244.Fn "client_callback2" "void *callback_arg" "bus_dma_segment_t *segs" \ 245"int nseg" "bus_size_t mapsize" "int error" 246.El 247.Pp 248Callback2's behavior is the same as 249.Vt bus_dmamap_callback_t 250with the addition that the length of the data mapped is provided via 251.Fa mapsize . 252.It Vt bus_dmasync_op_t 253Memory synchronization operation specifier. 254Bus DMA requires explicit synchronization of memory with its device 255visible mapping in order to guarantee memory coherency. 256The 257.Vt bus_dmasync_op_t 258allows the type of DMA operation that will be or has been performed 259to be communicated to the system so that the correct coherency measures 260are taken. 261The operations are represented as bitfield flags that can be combined together, 262though it only makes sense to combine PRE flags or POST flags, not both. 263See the 264.Fn bus_dmamap_sync 265description below for more details on how to use these operations. 266.Pp 267All operations specified below are performed from the host memory point of view, 268where a read implies data coming from the device to the host memory, and a write 269implies data going from the host memory to the device. 270Alternatively, the operations can be thought of in terms of driver operations, 271where reading a network packet or storage sector corresponds to a read operation 272in 273.Nm . 274.Bl -tag -width ".Dv BUS_DMASYNC_POSTWRITE" 275.It Dv BUS_DMASYNC_PREREAD 276Perform any synchronization required prior to an update of host memory by the 277device. 278.It Dv BUS_DMASYNC_PREWRITE 279Perform any synchronization required after an update of host memory by the CPU 280and prior to device access to host memory. 281.It Dv BUS_DMASYNC_POSTREAD 282Perform any synchronization required after an update of host memory by the 283device and prior to CPU access to host memory. 284.It Dv BUS_DMASYNC_POSTWRITE 285Perform any synchronization required after device access to host memory. 286.El 287.It Vt bus_dma_lock_t 288Client specified lock/mutex manipulation method. 289This will be called from 290within busdma whenever a client lock needs to be manipulated. 291In its current form, the function will be called immediately before 292the callback for a DMA load operation that has been deferred with 293.Dv BUS_DMA_LOCK 294and immediately after with 295.Dv BUS_DMA_UNLOCK . 296If the load operation does not need to be deferred, then it 297will not be called since the function loading the map should 298be holding the appropriate locks. 299This method is of the format: 300.Bl -tag -width indent 301.It Ft void 302.Fn "lockfunc" "void *lockfunc_arg" "bus_dma_lock_op_t op" 303.El 304.Pp 305The 306.Fa lockfuncarg 307argument is specified by the client during tag creation to be passed to all 308invocations of the callback. 309The 310.Fa op 311argument specifies the lock operation to perform. 312.Pp 313Two 314.Vt lockfunc 315implementations are provided for convenience. 316.Fn busdma_lock_mutex 317performs standard mutex operations on the sleep mutex provided via 318.Fa lockfuncarg . 319.Fn dflt_lock 320will generate a system panic if it is called. 321It is substituted into the tag when 322.Fa lockfunc 323is passed as 324.Dv NULL 325to 326.Fn bus_dma_tag_create 327and is useful for tags that should not be used with deferred load operations. 328.It Vt bus_dma_lock_op_t 329Operations to be performed by the client-specified 330.Fn lockfunc . 331.Bl -tag -width ".Dv BUS_DMA_UNLOCK" 332.It Dv BUS_DMA_LOCK 333Acquires and/or locks the client locking primitive. 334.It Dv BUS_DMA_UNLOCK 335Releases and/or unlocks the client locking primitive. 336.El 337.El 338.Sh FUNCTIONS 339.Bl -tag -width indent 340.It Fn bus_dma_tag_create "parent" "alignment" "boundary" "lowaddr" \ 341"highaddr" "*filtfunc" "*filtfuncarg" "maxsize" "nsegments" "maxsegsz" \ 342"flags" "lockfunc" "lockfuncarg" "*dmat" 343Allocates a device specific DMA tag, and initializes it according to 344the arguments provided: 345.Bl -tag -width ".Fa filtfuncarg" 346.It Fa parent 347Indicates restrictions between the parent bridge, CPU memory, and the 348device. 349Each device must use a master parent tag by calling 350.Fn bus_get_dma_tag . 351.It Fa alignment 352Alignment constraint, in bytes, of any mappings created using this tag. 353The alignment must be a power of 2. 354Hardware that can DMA starting at any address would specify 355.Em 1 356for byte alignment. 357Hardware requiring DMA transfers to start on a multiple of 4K 358would specify 359.Em 4096 . 360.It Fa boundary 361Boundary constraint, in bytes, of the target DMA memory region. 362The boundary indicates the set of addresses, all multiples of the 363boundary argument, that cannot be crossed by a single 364.Vt bus_dma_segment_t . 365The boundary must be a power of 2 and must be no smaller than the 366maximum segment size. 367.Ql 0 368indicates that there are no boundary restrictions. 369.It Fa lowaddr , highaddr 370Bounds of the window of bus address space that 371.Em cannot 372be directly accessed by the device. 373The window contains all addresses greater than 374.Fa lowaddr 375and less than or equal to 376.Fa highaddr . 377For example, a device incapable of DMA above 4GB, would specify a 378.Fa highaddr 379of 380.Dv BUS_SPACE_MAXADDR 381and a 382.Fa lowaddr 383of 384.Dv BUS_SPACE_MAXADDR_32BIT . 385Similarly a device that can only perform DMA to addresses below 38616MB would specify a 387.Fa highaddr 388of 389.Dv BUS_SPACE_MAXADDR 390and a 391.Fa lowaddr 392of 393.Dv BUS_SPACE_MAXADDR_24BIT . 394Some implementations requires that some region of device visible 395address space, overlapping available host memory, be outside the 396window. 397This area of 398.Ql safe memory 399is used to bounce requests that would otherwise conflict with 400the exclusion window. 401.It Fa filtfunc 402Optional filter function (may be 403.Dv NULL ) 404to be called for any attempt to 405map memory into the window described by 406.Fa lowaddr 407and 408.Fa highaddr . 409A filter function is only required when the single window described 410by 411.Fa lowaddr 412and 413.Fa highaddr 414cannot adequately describe the constraints of the device. 415The filter function will be called for every machine page 416that overlaps the exclusion window. 417.It Fa filtfuncarg 418Argument passed to all calls to the filter function for this tag. 419May be 420.Dv NULL . 421.It Fa maxsize 422Maximum size, in bytes, of the sum of all segment lengths in a given 423DMA mapping associated with this tag. 424.It Fa nsegments 425Number of discontinuities (scatter/gather segments) allowed 426in a DMA mapped region. 427If there is no restriction, 428.Dv BUS_SPACE_UNRESTRICTED 429may be specified. 430.It Fa maxsegsz 431Maximum size, in bytes, of a segment in any DMA mapped region associated 432with 433.Fa dmat . 434.It Fa flags 435Are as follows: 436.Bl -tag -width ".Dv BUS_DMA_ALLOCNOW" 437.It Dv BUS_DMA_ALLOCNOW 438Pre-allocate enough resources to handle at least one map load operation on 439this tag. 440If sufficient resources are not available, 441.Er ENOMEM 442is returned. 443This should not be used for tags that only describe buffers that will be 444allocated with 445.Fn bus_dmamem_alloc . 446Also, due to resource sharing with other tags, this flag does not guarantee 447that resources will be allocated or reserved exclusively for this tag. 448It should be treated only as a minor optimization. 449.El 450.It Fa lockfunc 451Optional lock manipulation function (may be 452.Dv NULL ) 453to be called when busdma 454needs to manipulate a lock on behalf of the client. 455If 456.Dv NULL 457is specified, 458.Fn dflt_lock 459is used. 460.It Fa lockfuncarg 461Optional argument to be passed to the function specified by 462.Fa lockfunc . 463.It Fa dmat 464Pointer to a bus_dma_tag_t where the resulting DMA tag will 465be stored. 466.El 467.Pp 468Returns 469.Er ENOMEM 470if sufficient memory is not available for tag creation 471or allocating mapping resources. 472.It Fn bus_dma_tag_destroy "dmat" 473Deallocate the DMA tag 474.Fa dmat 475that was created by 476.Fn bus_dma_tag_create . 477.Pp 478Returns 479.Er EBUSY 480if any DMA maps remain associated with 481.Fa dmat 482or 483.Ql 0 484on success. 485.It Fn bus_dmamap_create "dmat" "flags" "*mapp" 486Allocates and initializes a DMA map. 487Arguments are as follows: 488.Bl -tag -width ".Fa nsegments" 489.It Fa dmat 490DMA tag. 491.It Fa flags 492Are as follows: 493.Bl -tag -width ".Dv BUS_DMA_COHERENT" 494.It Dv BUS_DMA_COHERENT 495Attempt to map the memory loaded with this map such that cache sync 496operations are as cheap as possible. 497This flag is typically set on maps when the memory loaded with these will 498be accessed by both a CPU and a DMA engine, frequently such as control data 499and as opposed to streamable data such as receive and transmit buffers. 500Use of this flag does not remove the requirement of using 501.Fn bus_dmamap_sync , 502but it may reduce the cost of performing these operations. 503For 504.Fn bus_dmamap_create , 505the 506.Dv BUS_DMA_COHERENT 507flag is currently implemented on sparc64. 508.El 509.It Fa mapp 510Pointer to a 511.Vt bus_dmamap_t 512where the resulting DMA map will be stored. 513.El 514.Pp 515Returns 516.Er ENOMEM 517if sufficient memory is not available for creating the 518map or allocating mapping resources. 519.It Fn bus_dmamap_destroy "dmat" "map" 520Frees all resources associated with a given DMA map. 521Arguments are as follows: 522.Bl -tag -width ".Fa dmat" 523.It Fa dmat 524DMA tag used to allocate 525.Fa map . 526.It Fa map 527The DMA map to destroy. 528.El 529.Pp 530Returns 531.Er EBUSY 532if a mapping is still active for 533.Fa map . 534.It Fn bus_dmamap_load "dmat" "map" "buf" "buflen" "*callback" \ 535"callback_arg" "flags" 536Creates a mapping in device visible address space of 537.Fa buflen 538bytes of 539.Fa buf , 540associated with the DMA map 541.Fa map . 542This call will always return immediately and will not block for any reason. 543Arguments are as follows: 544.Bl -tag -width ".Fa buflen" 545.It Fa dmat 546DMA tag used to allocate 547.Fa map . 548.It Fa map 549A DMA map without a currently active mapping. 550.It Fa buf 551A kernel virtual address pointer to a contiguous (in KVA) buffer, to be 552mapped into device visible address space. 553.It Fa buflen 554The size of the buffer. 555.It Fa callback Fa callback_arg 556The callback function, and its argument. 557This function is called once sufficient mapping resources are available for 558the DMA operation. 559If resources are temporarily unavailable, this function will be deferred until 560later, but the load operation will still return immediately to the caller. 561Thus, callers should not assume that the callback will be called before the 562load returns, and code should be structured appropriately to handle this. 563See below for specific flags and error codes that control this behavior. 564.It Fa flags 565Are as follows: 566.Bl -tag -width ".Dv BUS_DMA_NOWAIT" 567.It Dv BUS_DMA_NOWAIT 568The load should not be deferred in case of insufficient mapping resources, 569and instead should return immediately with an appropriate error. 570.It Dv BUS_DMA_NOCACHE 571The generated transactions to and from the virtual page are non-cacheable. 572For 573.Fn bus_dmamap_load , 574the 575.Dv BUS_DMA_NOCACHE 576flag is currently implemented on sparc64. 577.El 578.El 579.Pp 580Return values to the caller are as follows: 581.Bl -tag -width ".Er EINPROGRESS" 582.It 0 583The callback has been called and completed. 584The status of the mapping has been delivered to the callback. 585.It Er EINPROGRESS 586The mapping has been deferred for lack of resources. 587The callback will be called as soon as resources are available. 588Callbacks are serviced in FIFO order. 589.Pp 590Note that subsequent load operations for the same tag that do not require 591extra resources will still succeed. 592This may result in out-of-order processing of requests. 593If the caller requires the order of requests to be preserved, 594then the caller is required to stall subsequent requests until a pending 595request's callback is invoked. 596.It Er ENOMEM 597The load request has failed due to insufficient resources, and the caller 598specifically used the 599.Dv BUS_DMA_NOWAIT 600flag. 601.It Er EINVAL 602The load request was invalid. 603The callback has been called and has been provided the same error. 604This error value may indicate that 605.Fa dmat , 606.Fa map , 607.Fa buf , 608or 609.Fa callback 610were invalid, or 611.Fa buflen 612was larger than the 613.Fa maxsize 614argument used to create the dma tag 615.Fa dmat . 616.El 617.Pp 618When the callback is called, it is presented with an error value 619indicating the disposition of the mapping. 620Error may be one of the following: 621.Bl -tag -width ".Er EINPROGRESS" 622.It 0 623The mapping was successful and the 624.Fa dm_segs 625callback argument contains an array of 626.Vt bus_dma_segment_t 627elements describing the mapping. 628This array is only valid during the scope of the callback function. 629.It Er EFBIG 630A mapping could not be achieved within the segment constraints provided 631in the tag even though the requested allocation size was less than maxsize. 632.El 633.It Fn bus_dmamap_load_bio "dmat" "map" "bio" "callback" "callback_arg" "flags" 634This is a variation of 635.Fn bus_dmamap_load 636which maps buffers pointed to by 637.Fa bio 638for DMA transfers. 639.Fa bio 640may point to either a mapped or unmapped buffer. 641.It Fn bus_dmamap_load_ccb "dmat" "map" "ccb" "callback" "callback_arg" "flags" 642This is a variation of 643.Fn bus_dmamap_load 644which maps data pointed to by 645.Fa ccb 646for DMA transfers. 647The data for 648.Fa ccb 649may be any of the following types: 650.Bl -tag -width ".Er CAM_DATA_SG_PADDR" 651.It CAM_DATA_VADDR 652The data is a single KVA buffer. 653.It CAM_DATA_PADDR 654The data is a single bus address range. 655.It CAM_DATA_SG 656The data is a scatter/gather list of KVA buffers. 657.It CAM_DATA_SG_PADDR 658The data is a scatter/gather list of bus address ranges. 659.It CAM_DATA_BIO 660The data is contained in a 661.Vt struct bio 662attached to the CCB. 663.El 664.Pp 665.Fn bus_dmamap_load_ccb 666supports the following CCB XPT function codes: 667.Pp 668.Bl -item -offset indent -compact 669.It 670XPT_ATA_IO 671.It 672XPT_CONT_TARGET_IO 673.It 674XPT_SCSI_IO 675.El 676.It Fn bus_dmamap_load_mbuf "dmat" "map" "mbuf" "callback2" "callback_arg" \ 677"flags" 678This is a variation of 679.Fn bus_dmamap_load 680which maps mbuf chains 681for DMA transfers. 682A 683.Vt bus_size_t 684argument is also passed to the callback routine, which 685contains the mbuf chain's packet header length. 686The 687.Dv BUS_DMA_NOWAIT 688flag is implied, thus no callback deferral will happen. 689.Pp 690Mbuf chains are assumed to be in kernel virtual address space. 691.Pp 692Beside the error values listed for 693.Fn bus_dmamap_load , 694.Er EINVAL 695will be returned if the size of the mbuf chain exceeds the maximum limit of the 696DMA tag. 697.It Fn bus_dmamap_load_mbuf_sg "dmat" "map" "mbuf" "segs" "nsegs" "flags" 698This is just like 699.Fn bus_dmamap_load_mbuf 700except that it returns immediately without calling a callback function. 701It is provided for efficiency. 702The scatter/gather segment array 703.Va segs 704is provided by the caller and filled in directly by the function. 705The 706.Va nsegs 707argument is returned with the number of segments filled in. 708Returns the same errors as 709.Fn bus_dmamap_load_mbuf . 710.It Fn bus_dmamap_load_uio "dmat" "map" "uio" "callback2" "callback_arg" "flags" 711This is a variation of 712.Fn bus_dmamap_load 713which maps buffers pointed to by 714.Fa uio 715for DMA transfers. 716A 717.Vt bus_size_t 718argument is also passed to the callback routine, which contains the size of 719.Fa uio , 720i.e. 721.Fa uio->uio_resid . 722The 723.Dv BUS_DMA_NOWAIT 724flag is implied, thus no callback deferral will happen. 725Returns the same errors as 726.Fn bus_dmamap_load . 727.Pp 728If 729.Fa uio->uio_segflg 730is 731.Dv UIO_USERSPACE , 732then it is assumed that the buffer, 733.Fa uio 734is in 735.Fa "uio->uio_td->td_proc" Ns 's 736address space. 737User space memory must be in-core and wired prior to attempting a map 738load operation. 739Pages may be locked using 740.Xr vslock 9 . 741.It Fn bus_dmamap_unload "dmat" "map" 742Unloads a DMA map. 743Arguments are as follows: 744.Bl -tag -width ".Fa dmam" 745.It Fa dmat 746DMA tag used to allocate 747.Fa map . 748.It Fa map 749The DMA map that is to be unloaded. 750.El 751.Pp 752.Fn bus_dmamap_unload 753will not perform any implicit synchronization of DMA buffers. 754This must be done explicitly by a call to 755.Fn bus_dmamap_sync 756prior to unloading the map. 757.It Fn bus_dmamap_sync "dmat" "map" "op" 758Performs synchronization of a device visible mapping with the CPU visible 759memory referenced by that mapping. 760Arguments are as follows: 761.Bl -tag -width ".Fa dmat" 762.It Fa dmat 763DMA tag used to allocate 764.Fa map . 765.It Fa map 766The DMA mapping to be synchronized. 767.It Fa op 768Type of synchronization operation to perform. 769See the definition of 770.Vt bus_dmasync_op_t 771for a description of the acceptable values for 772.Fa op . 773.El 774.Pp 775The 776.Fn bus_dmamap_sync 777function 778is the method used to ensure that CPU's and device's direct 779memory access (DMA) to shared 780memory is coherent. 781For example, the CPU might be used to set up the contents of a buffer 782that is to be made available to a device. 783To ensure that the data are visible via the device's mapping of that 784memory, the buffer must be loaded and a DMA sync operation of 785.Dv BUS_DMASYNC_PREWRITE 786must be performed after the CPU has updated the buffer and before the device 787access is initiated. 788If the CPU modifies this buffer again later, another 789.Dv BUS_DMASYNC_PREWRITE 790sync operation must be performed before an additional device 791access. 792Conversely, suppose a device updates memory that is to be read by a CPU. 793In this case, the buffer must be loaded, and a DMA sync operation of 794.Dv BUS_DMASYNC_PREREAD 795must be performed before the device access is initiated. 796The CPU will only be able to see the results of this memory update 797once the DMA operation has completed and a 798.Dv BUS_DMASYNC_POSTREAD 799sync operation has been performed. 800.Pp 801If read and write operations are not preceded and followed by the 802appropriate synchronization operations, behavior is undefined. 803.It Fn bus_dmamem_alloc "dmat" "**vaddr" "flags" "*mapp" 804Allocates memory that is mapped into KVA at the address returned 805in 806.Fa vaddr 807and that is permanently loaded into the newly created 808.Vt bus_dmamap_t 809returned via 810.Fa mapp . 811Arguments are as follows: 812.Bl -tag -width ".Fa alignment" 813.It Fa dmat 814DMA tag describing the constraints of the DMA mapping. 815.It Fa vaddr 816Pointer to a pointer that will hold the returned KVA mapping of 817the allocated region. 818.It Fa flags 819Flags are defined as follows: 820.Bl -tag -width ".Dv BUS_DMA_NOWAIT" 821.It Dv BUS_DMA_WAITOK 822The routine can safely wait (sleep) for resources. 823.It Dv BUS_DMA_NOWAIT 824The routine is not allowed to wait for resources. 825If resources are not available, 826.Dv ENOMEM 827is returned. 828.It Dv BUS_DMA_COHERENT 829Attempt to map this memory in a coherent fashion. 830See 831.Fn bus_dmamap_create 832above for a description of this flag. 833For 834.Fn bus_dmamem_alloc , 835the 836.Dv BUS_DMA_COHERENT 837flag is currently implemented on arm and sparc64. 838.It Dv BUS_DMA_ZERO 839Causes the allocated memory to be set to all zeros. 840.It Dv BUS_DMA_NOCACHE 841The allocated memory will not be cached in the processor caches. 842All memory accesses appear on the bus and are executed 843without reordering. 844For 845.Fn bus_dmamem_alloc , 846the 847.Dv BUS_DMA_NOCACHE 848flag is currently implemented on amd64 and i386 where it results in the 849Strong Uncacheable PAT to be set for the allocated virtual address range. 850.El 851.It Fa mapp 852Pointer to a 853.Vt bus_dmamap_t 854where the resulting DMA map will be stored. 855.El 856.Pp 857The size of memory to be allocated is 858.Fa maxsize 859as specified in the call to 860.Fn bus_dma_tag_create 861for 862.Fa dmat . 863.Pp 864The current implementation of 865.Fn bus_dmamem_alloc 866will allocate all requests as a single segment. 867.Pp 868An initial load operation is required to obtain the bus address of the allocated 869memory, and an unload operation is required before freeing the memory, as 870described below in 871.Fn bus_dmamem_free . 872Maps are automatically handled by this function and should not be explicitly 873allocated or destroyed. 874.Pp 875Although an explicit load is not required for each access to the memory 876referenced by the returned map, the synchronization requirements 877as described in the 878.Fn bus_dmamap_sync 879section still apply and should be used to achieve portability on architectures 880without coherent buses. 881.Pp 882Returns 883.Er ENOMEM 884if sufficient memory is not available for completing 885the operation. 886.It Fn bus_dmamem_free "dmat" "*vaddr" "map" 887Frees memory previously allocated by 888.Fn bus_dmamem_alloc . 889Any mappings 890will be invalidated. 891Arguments are as follows: 892.Bl -tag -width ".Fa vaddr" 893.It Fa dmat 894DMA tag. 895.It Fa vaddr 896Kernel virtual address of the memory. 897.It Fa map 898DMA map to be invalidated. 899.El 900.El 901.Sh RETURN VALUES 902Behavior is undefined if invalid arguments are passed to 903any of the above functions. 904If sufficient resources cannot be allocated for a given 905transaction, 906.Er ENOMEM 907is returned. 908All 909routines that are not of type 910.Vt void 911will return 0 on success or an error 912code on failure as discussed above. 913.Pp 914All 915.Vt void 916routines will succeed if provided with valid arguments. 917.Sh LOCKING 918Two locking protocols are used by 919.Nm . 920The first is a private global lock that is used to synchronize access to the 921bounce buffer pool on the architectures that make use of them. 922This lock is strictly a leaf lock that is only used internally to 923.Nm 924and is not exposed to clients of the API. 925.Pp 926The second protocol involves protecting various resources stored in the tag. 927Since almost all 928.Nm 929operations are done through requests from the driver that created the tag, 930the most efficient way to protect the tag resources is through the lock that 931the driver uses. 932In cases where 933.Nm 934acts on its own without being called by the driver, the lock primitive 935specified in the tag is acquired and released automatically. 936An example of this is when the 937.Fn bus_dmamap_load 938callback function is called from a deferred context instead of the driver 939context. 940This means that certain 941.Nm 942functions must always be called with the same lock held that is specified in the 943tag. 944These functions include: 945.Pp 946.Bl -item -offset indent -compact 947.It 948.Fn bus_dmamap_load 949.It 950.Fn bus_dmamap_load_bio 951.It 952.Fn bus_dmamap_load_ccb 953.It 954.Fn bus_dmamap_load_mbuf 955.It 956.Fn bus_dmamap_load_mbuf_sg 957.It 958.Fn bus_dmamap_load_uio 959.It 960.Fn bus_dmamap_unload 961.It 962.Fn bus_dmamap_sync 963.El 964.Pp 965There is one exception to this rule. 966It is common practice to call some of these functions during driver start-up 967without any locks held. 968So long as there is a guarantee of no possible concurrent use of the tag by 969different threads during this operation, it is safe to not hold a lock for 970these functions. 971.Pp 972Certain 973.Nm 974operations should not be called with the driver lock held, either because 975they are already protected by an internal lock, or because they might sleep 976due to memory or resource allocation. 977The following functions must not be 978called with any non-sleepable locks held: 979.Pp 980.Bl -item -offset indent -compact 981.It 982.Fn bus_dma_tag_create 983.It 984.Fn bus_dmamap_create 985.It 986.Fn bus_dmamem_alloc 987.El 988.Pp 989All other functions do not have a locking protocol and can thus be 990called with or without any system or driver locks held. 991.Sh SEE ALSO 992.Xr devclass 9 , 993.Xr device 9 , 994.Xr driver 9 , 995.Xr rman 9 , 996.Xr vslock 9 997.Pp 998.Rs 999.%A "Jason R. Thorpe" 1000.%T "A Machine-Independent DMA Framework for NetBSD" 1001.%J "Proceedings of the Summer 1998 USENIX Technical Conference" 1002.%Q "USENIX Association" 1003.%D "June 1998" 1004.Re 1005.Sh HISTORY 1006The 1007.Nm 1008interface first appeared in 1009.Nx 1.3 . 1010.Pp 1011The 1012.Nm 1013API was adopted from 1014.Nx 1015for use in the CAM SCSI subsystem. 1016The alterations to the original API were aimed to remove the need for 1017a 1018.Vt bus_dma_segment_t 1019array stored in each 1020.Vt bus_dmamap_t 1021while allowing callers to queue up on scarce resources. 1022.Sh AUTHORS 1023The 1024.Nm 1025interface was designed and implemented by 1026.An Jason R. Thorpe 1027of the Numerical Aerospace Simulation Facility, NASA Ames Research Center. 1028Additional input on the 1029.Nm 1030design was provided by 1031.An -nosplit 1032.An Chris Demetriou , 1033.An Charles Hannum , 1034.An Ross Harvey , 1035.An Matthew Jacob , 1036.An Jonathan Stone , 1037and 1038.An Matt Thomas . 1039.Pp 1040The 1041.Nm 1042interface in 1043.Fx 1044benefits from the contributions of 1045.An Justin T. Gibbs , 1046.An Peter Wemm , 1047.An Doug Rabson , 1048.An Matthew N. Dodd , 1049.An Sam Leffler , 1050.An Maxime Henrion , 1051.An Jake Burkholder , 1052.An Takahashi Yoshihiro , 1053.An Scott Long 1054and many others. 1055.Pp 1056This manual page was written by 1057.An Hiten M. Pandya 1058and 1059.An Justin T. Gibbs . 1060