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.\" 3. All advertising materials mentioning features or use of this software 41.\" must display the following acknowledgment: 42.\" This product includes software developed by the NetBSD 43.\" Foundation, Inc. and its contributors. 44.\" 4. Neither the name of The NetBSD Foundation nor the names of its 45.\" contributors may be used to endorse or promote products derived 46.\" from this software without specific prior written permission. 47.\" 48.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 49.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 50.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 51.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 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$ 61.\" $NetBSD: bus_dma.9,v 1.25 2002/10/14 13:43:16 wiz Exp $ 62.\" 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 , 72.Nm bus_dmamap_load , 73.Nm bus_dmamap_load_mbuf , 74.Nm bus_dmamap_load_mbuf_sg , 75.Nm bus_dmamap_load_uio , 76.Nm bus_dmamap_unload , 77.Nm bus_dmamap_sync , 78.Nm bus_dmamem_alloc , 79.Nm bus_dmamem_free 80.Nd Bus and Machine Independent DMA Mapping Interface 81.Sh SYNOPSIS 82.In machine/bus.h 83.Ft int 84.Fn bus_dma_tag_create "bus_dma_tag_t parent" "bus_size_t alignment" \ 85"bus_size_t boundary" "bus_addr_t lowaddr" "bus_addr_t highaddr" \ 86"bus_dma_filter_t *filtfunc" "void *filtfuncarg" "bus_size_t maxsize" \ 87"int nsegments" "bus_size_t maxsegsz" "int flags" "bus_dma_lock_t *lockfunc" \ 88"void *lockfuncarg" "bus_dma_tag_t *dmat" 89.Ft int 90.Fn bus_dma_tag_destroy "bus_dma_tag_t dmat" 91.Ft int 92.Fn bus_dmamap_create "bus_dma_tag_t dmat" "int flags" "bus_dmamap_t *mapp" 93.Ft int 94.Fn bus_dmamap_destroy "bus_dma_tag_t dmat" "bus_dmamap_t map" 95.Ft int 96.Fn bus_dmamap_load "bus_dma_tag_t dmat" "bus_dmamap_t map" "void *buf" \ 97"bus_size_t buflen" "bus_dmamap_callback_t *callback" "void *callback_arg" \ 98"int flags" 99.Ft int 100.Fn bus_dmamap_load_mbuf "bus_dma_tag_t dmat" "bus_dmamap_t map" \ 101"struct mbuf *mbuf" "bus_dmamap_callback2_t *callback" "void *callback_arg" \ 102"int flags" 103.Ft int 104.Fn bus_dmamap_load_mbuf_sg "bus_dma_tag_t dmat" "bus_dmamap_t map" \ 105"struct mbuf *mbuf" "bus_dma_segment_t *segs" "int *nsegs" "int flags" 106.Ft int 107.Fn bus_dmamap_load_uio "bus_dma_tag_t dmat" "bus_dmamap_t map" \ 108"struct uio *uio" "bus_dmamap_callback2_t *callback" "void *callback_arg" \ 109"int flags" 110.Ft void 111.Fn bus_dmamap_unload "bus_dma_tag_t dmat" "bus_dmamap_t map" 112.Ft void 113.Fn bus_dmamap_sync "bus_dma_tag_t dmat" "bus_dmamap_t map" \ 114"op" 115.Ft int 116.Fn bus_dmamem_alloc "bus_dma_tag_t dmat" "void **vaddr" \ 117"int flags" "bus_dmamap_t *mapp" 118.Ft void 119.Fn bus_dmamem_free "bus_dma_tag_t dmat" "void *vaddr" \ 120"bus_dmamap_t map" 121.Sh DESCRIPTION 122Direct Memory Access (DMA) is a method of transferring data 123without involving the CPU, thus providing higher performance. 124A DMA transaction can be achieved between device to memory, 125device to device, or memory to memory. 126.Pp 127The 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 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: 146.Bl -tag -width indent 147.It Ft int 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 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. 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. 171It contains the following fields: 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 180.Fa ds_len 181contains the length of the DMA segment. 182Although the DMA segments returned by a mapping call will adhere to 183all restrictions necessary for a successful DMA operation, some conversion 184(e.g.\& a conversion from host byte order to the device's byte order) is 185almost always required when presenting segment information to the device. 186.It Vt bus_dmamap_t 187A machine-dependent opaque type describing an individual mapping. 188One map is used for each memory allocation that will be loaded. 189Maps can be reused once they have been unloaded. 190Multiple maps can be associated with one DMA tag. 191While the value of the map may evaluate to 192.Dv NULL 193on some platforms under certain conditions, 194it should never be assumed that it will be 195.Dv NULL 196in all cases. 197.It Vt bus_dmamap_callback_t 198Client specified callback for receiving mapping information resulting from 199the load of a 200.Vt bus_dmamap_t 201via 202.Fn bus_dmamap_load . 203Callbacks are of the format: 204.Bl -tag -width indent 205.It Ft void 206.Fn "client_callback" "void *callback_arg" "bus_dma_segment_t *segs" \ 207"int nseg" "int error" 208.El 209.Pp 210The 211.Fa callback_arg 212is the callback argument passed to dmamap load functions. 213The 214.Fa segs 215and 216.Fa nseg 217arguments describe an array of 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 223argument. 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 232or 233.Fn bus_dmamap_load_mbuf . 234.Pp 235Callback2s are of the format: 236.Bl -tag -width indent 237.It Ft void 238.Fn "client_callback2" "void *callback_arg" "bus_dma_segment_t *segs" \ 239"int nseg" "bus_size_t mapsize" "int error" 240.El 241.Pp 242Callback2's behavior is the same as 243.Vt bus_dmamap_callback_t 244with the addition that the length of the data mapped is provided via 245.Fa mapsize . 246.It Vt bus_dmasync_op_t 247Memory synchronization operation specifier. 248Bus DMA requires explicit synchronization of memory with its device 249visible mapping in order to guarantee memory coherency. 250The 251.Vt bus_dmasync_op_t 252allows the type of DMA operation that will be or has been performed 253to be communicated to the system so that the correct coherency measures 254are taken. 255The operations are represented as bitfield flags that can be combined together, 256though it only makes sense to combine PRE flags or POST flags, not both. 257See the 258.Fn bus_dmamap_sync 259description below for more details on how to use these operations. 260.Pp 261All operations specified below are performed from the host memory point of view, 262where a read implies data coming from the device to the host memory, and a write 263implies data going from the host memory to the device. 264Alternatively, the operations can be thought of in terms of driver operations, 265where reading a network packet or storage sector corresponds to a read operation 266in 267.Nm . 268.Bl -tag -width ".Dv BUS_DMASYNC_POSTWRITE" 269.It Dv BUS_DMASYNC_PREREAD 270Perform any synchronization required prior to an update of host memory by the 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 279Perform any synchronization required after device access to host memory. 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 307Two 308.Vt lockfunc 309implementations are provided for convenience. 310.Fn busdma_lock_mutex 311performs standard mutex operations on the sleep mutex provided via 312.Fa lockfuncarg . 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 320.Fn bus_dma_tag_create 321and is useful for tags that should not be used with deferred load operations. 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. 330.El 331.El 332.Sh FUNCTIONS 333.Bl -tag -width indent 334.It Fn bus_dma_tag_create "parent" "alignment" "boundary" "lowaddr" \ 335"highaddr" "*filtfunc" "*filtfuncarg" "maxsize" "nsegments" "maxsegsz" \ 336"flags" "lockfunc" "lockfuncarg" "*dmat" 337Allocates a device specific DMA tag, and initializes it according to 338the arguments provided: 339.Bl -tag -width ".Fa filtfuncarg" 340.It Fa parent 341Indicates restrictions between the parent bridge, CPU memory, and the 342device. 343Each device must use a master parent tag by calling 344.Fn bus_get_dma_tag . 345.It Fa alignment 346Alignment constraint, in bytes, of any mappings created using this tag. 347The alignment must be a power of 2. 348Hardware that can DMA starting at any address would specify 349.Em 1 350for byte alignment. 351Hardware requiring DMA transfers to start on a multiple of 4K 352would specify 353.Em 4096 . 354.It Fa boundary 355Boundary constraint, in bytes, of the target DMA memory region. 356The boundary indicates the set of addresses, all multiples of the 357boundary argument, that cannot be crossed by a single 358.Vt bus_dma_segment_t . 359The boundary must be a power of 2 and must be no smaller than the 360maximum segment size. 361.Ql 0 362indicates that there are no boundary restrictions. 363.It Fa lowaddr , highaddr 364Bounds of the window of bus address space that 365.Em cannot 366be directly accessed by the device. 367The window contains all addresses greater than 368.Fa lowaddr 369and less than or equal to 370.Fa highaddr . 371For example, a device incapable of DMA above 4GB, would specify a 372.Fa highaddr 373of 374.Dv BUS_SPACE_MAXADDR 375and a 376.Fa lowaddr 377of 378.Dv BUS_SPACE_MAXADDR_32BIT . 379Similarly a device that can only perform DMA to addresses below 38016MB would specify a 381.Fa highaddr 382of 383.Dv BUS_SPACE_MAXADDR 384and a 385.Fa lowaddr 386of 387.Dv BUS_SPACE_MAXADDR_24BIT . 388Some implementations requires that some region of device visible 389address space, overlapping available host memory, be outside the 390window. 391This area of 392.Ql safe memory 393is used to bounce requests that would otherwise conflict with 394the exclusion window. 395.It Fa filtfunc 396Optional filter function (may be 397.Dv NULL ) 398to be called for any attempt to 399map memory into the window described by 400.Fa lowaddr 401and 402.Fa highaddr . 403A filter function is only required when the single window described 404by 405.Fa lowaddr 406and 407.Fa highaddr 408cannot adequately describe the constraints of the device. 409The filter function will be called for every machine page 410that overlaps the exclusion window. 411.It Fa filtfuncarg 412Argument passed to all calls to the filter function for this tag. 413May be 414.Dv NULL . 415.It Fa maxsize 416Maximum size, in bytes, of the sum of all segment lengths in a given 417DMA mapping associated with this tag. 418.It Fa nsegments 419Number of discontinuities (scatter/gather segments) allowed 420in a DMA mapped region. 421If there is no restriction, 422.Dv BUS_SPACE_UNRESTRICTED 423may be specified. 424.It Fa maxsegsz 425Maximum size, in bytes, of a segment in any DMA mapped region associated 426with 427.Fa dmat . 428.It Fa flags 429Are as follows: 430.Bl -tag -width ".Dv BUS_DMA_ALLOCNOW" 431.It Dv BUS_DMA_ALLOCNOW 432Pre-allocate enough resources to handle at least one map load operation on 433this tag. 434If sufficient resources are not available, 435.Er ENOMEM 436is returned. 437This should not be used for tags that only describe buffers that will be 438allocated with 439.Fn bus_dmamem_alloc . 440Also, due to resource sharing with other tags, this flag does not guarantee 441that resources will be allocated or reserved exclusively for this tag. 442It should be treated only as a minor optimization. 443.El 444.It Fa lockfunc 445Optional lock manipulation function (may be 446.Dv NULL ) 447to be called when busdma 448needs to manipulate a lock on behalf of the client. 449If 450.Dv NULL 451is specified, 452.Fn dflt_lock 453is used. 454.It Fa lockfuncarg 455Optional argument to be passed to the function specified by 456.Fa lockfunc . 457.It Fa dmat 458Pointer to a bus_dma_tag_t where the resulting DMA tag will 459be stored. 460.El 461.Pp 462Returns 463.Er ENOMEM 464if sufficient memory is not available for tag creation 465or allocating mapping resources. 466.It Fn bus_dma_tag_destroy "dmat" 467Deallocate the DMA tag 468.Fa dmat 469that was created by 470.Fn bus_dma_tag_create . 471.Pp 472Returns 473.Er EBUSY 474if any DMA maps remain associated with 475.Fa dmat 476or 477.Ql 0 478on success. 479.It Fn bus_dmamap_create "dmat" "flags" "*mapp" 480Allocates and initializes a DMA map. 481Arguments are as follows: 482.Bl -tag -width ".Fa nsegments" 483.It Fa dmat 484DMA tag. 485.It Fa flags 486The value of this argument is currently undefined and should be 487specified as 488.Ql 0 . 489.It Fa mapp 490Pointer to a 491.Vt bus_dmamap_t 492where the resulting DMA map will be stored. 493.El 494.Pp 495Returns 496.Er ENOMEM 497if sufficient memory is not available for creating the 498map or allocating mapping resources. 499.It Fn bus_dmamap_destroy "dmat" "map" 500Frees all resources associated with a given DMA map. 501Arguments are as follows: 502.Bl -tag -width ".Fa dmat" 503.It Fa dmat 504DMA tag used to allocate 505.Fa map . 506.It Fa map 507The DMA map to destroy. 508.El 509.Pp 510Returns 511.Er EBUSY 512if a mapping is still active for 513.Fa map . 514.It Fn bus_dmamap_load "dmat" "map" "buf" "buflen" "*callback" \ 515"callback_arg" "flags" 516Creates a mapping in device visible address space of 517.Fa buflen 518bytes of 519.Fa buf , 520associated with the DMA map 521.Fa map . 522This call will always return immediately and will not block for any reason. 523Arguments are as follows: 524.Bl -tag -width ".Fa buflen" 525.It Fa dmat 526DMA tag used to allocate 527.Fa map . 528.It Fa map 529A DMA map without a currently active mapping. 530.It Fa buf 531A kernel virtual address pointer to a contiguous (in KVA) buffer, to be 532mapped into device visible address space. 533.It Fa buflen 534The size of the buffer. 535.It Fa callback Fa callback_arg 536The callback function, and its argument. 537This function is called once sufficient mapping resources are available for 538the DMA operation. 539If resources are temporarily unavailable, this function will be deferred until 540later, but the load operation will still return immediately to the caller. 541Thus, callers should not assume that the callback will be called before the 542load returns, and code should be structured appropriately to handle this. 543See below for specific flags and error codes that control this behavior. 544.It Fa flags 545Are as follows: 546.Bl -tag -width ".Dv BUS_DMA_NOWAIT" 547.It Dv BUS_DMA_NOWAIT 548The load should not be deferred in case of insufficient mapping resources, 549and instead should return immediately with an appropriate error. 550.It Dv BUS_DMA_NOCACHE 551The allocated memory will not be cached in the processor caches. 552All memory accesses appear on the bus and are executed 553without reordering. 554Currently the flag is implemented for i386 and amd64 architectures 555only, where it results in the Strong Uncacheable 556PAT to be set for the allocated virtual address range. 557.El 558.El 559.Pp 560Return values to the caller are as follows: 561.Bl -tag -width ".Er EINPROGRESS" 562.It 0 563The callback has been called and completed. 564The status of the mapping has been delivered to the callback. 565.It Er EINPROGRESS 566The mapping has been deferred for lack of resources. 567The callback will be called as soon as resources are available. 568Callbacks are serviced in FIFO order. 569To ensure that ordering is guaranteed, all subsequent load requests will also 570be deferred until all callbacks have been processed. 571.It Er ENOMEM 572The load request has failed due to insufficient resources, and the caller 573specifically used the 574.Dv BUS_DMA_NOWAIT 575flag. 576.It Er EINVAL 577The load request was invalid. 578The callback has been called and has been provided the same error. 579This error value may indicate that 580.Fa dmat , 581.Fa map , 582.Fa buf , 583or 584.Fa callback 585were invalid, or 586.Fa buflen 587was larger than the 588.Fa maxsize 589argument used to create the dma tag 590.Fa dmat . 591.El 592.Pp 593When the callback is called, it is presented with an error value 594indicating the disposition of the mapping. 595Error may be one of the following: 596.Bl -tag -width ".Er EINPROGRESS" 597.It 0 598The mapping was successful and the 599.Fa dm_segs 600callback argument contains an array of 601.Vt bus_dma_segment_t 602elements describing the mapping. 603This array is only valid during the scope of the callback function. 604.It Er EFBIG 605A mapping could not be achieved within the segment constraints provided 606in the tag even though the requested allocation size was less than maxsize. 607.El 608.It Fn bus_dmamap_load_mbuf "dmat" "map" "mbuf" "callback2" "callback_arg" \ 609"flags" 610This is a variation of 611.Fn bus_dmamap_load 612which maps mbuf chains 613for DMA transfers. 614A 615.Vt bus_size_t 616argument is also passed to the callback routine, which 617contains the mbuf chain's packet header length. 618The 619.Dv BUS_DMA_NOWAIT 620flag is implied, thus no callback deferral will happen. 621.Pp 622Mbuf chains are assumed to be in kernel virtual address space. 623.Pp 624Beside the error values listed for 625.Fn bus_dmamap_load , 626.Er EINVAL 627will be returned if the size of the mbuf chain exceeds the maximum limit of the 628DMA tag. 629.It Fn bus_dmamap_load_mbuf_sg "dmat" "map" "mbuf" "segs" "nsegs" "flags" 630This is just like 631.Fn bus_dmamap_load_mbuf 632except that it returns immediately without calling a callback function. 633It is provided for efficiency. 634The scatter/gather segment array 635.Va segs 636is provided by the caller and filled in directly by the function. 637The 638.Va nsegs 639argument is returned with the number of segments filled in. 640Returns the same errors as 641.Fn bus_dmamap_load_mbuf . 642.It Fn bus_dmamap_load_uio "dmat" "map" "uio" "callback2" "callback_arg" "flags" 643This is a variation of 644.Fn bus_dmamap_load 645which maps buffers pointed to by 646.Fa uio 647for DMA transfers. 648A 649.Vt bus_size_t 650argument is also passed to the callback routine, which contains the size of 651.Fa uio , 652i.e. 653.Fa uio->uio_resid . 654The 655.Dv BUS_DMA_NOWAIT 656flag is implied, thus no callback deferral will happen. 657Returns the same errors as 658.Fn bus_dmamap_load . 659.Pp 660If 661.Fa uio->uio_segflg 662is 663.Dv UIO_USERSPACE , 664then it is assumed that the buffer, 665.Fa uio 666is in 667.Fa "uio->uio_td->td_proc" Ns 's 668address space. 669User space memory must be in-core and wired prior to attempting a map 670load operation. 671Pages may be locked using 672.Xr vslock 9 . 673.It Fn bus_dmamap_unload "dmat" "map" 674Unloads a DMA map. 675Arguments are as follows: 676.Bl -tag -width ".Fa dmam" 677.It Fa dmat 678DMA tag used to allocate 679.Fa map . 680.It Fa map 681The DMA map that is to be unloaded. 682.El 683.Pp 684.Fn bus_dmamap_unload 685will not perform any implicit synchronization of DMA buffers. 686This must be done explicitly by a call to 687.Fn bus_dmamap_sync 688prior to unloading the map. 689.It Fn bus_dmamap_sync "dmat" "map" "op" 690Performs synchronization of a device visible mapping with the CPU visible 691memory referenced by that mapping. 692Arguments are as follows: 693.Bl -tag -width ".Fa dmat" 694.It Fa dmat 695DMA tag used to allocate 696.Fa map . 697.It Fa map 698The DMA mapping to be synchronized. 699.It Fa op 700Type of synchronization operation to perform. 701See the definition of 702.Vt bus_dmasync_op_t 703for a description of the acceptable values for 704.Fa op . 705.El 706.Pp 707The 708.Fn bus_dmamap_sync 709function 710is the method used to ensure that CPU's and device's direct 711memory access (DMA) to shared 712memory is coherent. 713For example, the CPU might be used to set up the contents of a buffer 714that is to be made available to a device. 715To ensure that the data are visible via the device's mapping of that 716memory, the buffer must be loaded and a DMA sync operation of 717.Dv BUS_DMASYNC_PREWRITE 718must be performed after the CPU has updated the buffer and before the device 719access is initiated. 720If the CPU modifies this buffer again later, another 721.Dv BUS_DMASYNC_PREWRITE 722sync operation must be performed before an additional device 723access. 724Conversely, suppose a device updates memory that is to be read by a CPU. 725In this case, the buffer must be loaded, and a DMA sync operation of 726.Dv BUS_DMASYNC_PREREAD 727must be performed before the device access is initiated. 728The CPU will only be able to see the results of this memory update 729once the DMA operation has completed and a 730.Dv BUS_DMASYNC_POSTREAD 731sync operation has been performed. 732.Pp 733If read and write operations are not preceded and followed by the 734appropriate synchronization operations, behavior is undefined. 735.It Fn bus_dmamem_alloc "dmat" "**vaddr" "flags" "*mapp" 736Allocates memory that is mapped into KVA at the address returned 737in 738.Fa vaddr 739and that is permanently loaded into the newly created 740.Vt bus_dmamap_t 741returned via 742.Fa mapp . 743Arguments are as follows: 744.Bl -tag -width ".Fa alignment" 745.It Fa dmat 746DMA tag describing the constraints of the DMA mapping. 747.It Fa vaddr 748Pointer to a pointer that will hold the returned KVA mapping of 749the allocated region. 750.It Fa flags 751Flags are defined as follows: 752.Bl -tag -width ".Dv BUS_DMA_NOWAIT" 753.It Dv BUS_DMA_WAITOK 754The routine can safely wait (sleep) for resources. 755.It Dv BUS_DMA_NOWAIT 756The routine is not allowed to wait for resources. 757If resources are not available, 758.Dv ENOMEM 759is returned. 760.It Dv BUS_DMA_COHERENT 761Attempt to map this memory such that cache sync operations are 762as cheap as possible. 763This flag is typically set on memory that will be accessed by both 764a CPU and a DMA engine, frequently. 765Use of this flag does not remove the requirement of using 766bus_dmamap_sync, but it may reduce the cost of performing 767these operations. 768The 769.Dv BUS_DMA_COHERENT 770flag is currently implemented on sparc64 and arm. 771.It Dv BUS_DMA_ZERO 772Causes the allocated memory to be set to all zeros. 773.El 774.It Fa mapp 775Pointer to a 776.Vt bus_dmamap_t 777where the resulting DMA map will be stored. 778.El 779.Pp 780The size of memory to be allocated is 781.Fa maxsize 782as specified in the call to 783.Fn bus_dma_tag_create 784for 785.Fa dmat . 786.Pp 787The current implementation of 788.Fn bus_dmamem_alloc 789will allocate all requests as a single segment. 790.Pp 791An initial load operation is required to obtain the bus address of the allocated 792memory, and an unload operation is required before freeing the memory, as 793described below in 794.Fn bus_dmamem_free . 795Maps are automatically handled by this function and should not be explicitly 796allocated or destroyed. 797.Pp 798Although an explicit load is not required for each access to the memory 799referenced by the returned map, the synchronization requirements 800as described in the 801.Fn bus_dmamap_sync 802section still apply and should be used to achieve portability on architectures 803without coherent buses. 804.Pp 805Returns 806.Er ENOMEM 807if sufficient memory is not available for completing 808the operation. 809.It Fn bus_dmamem_free "dmat" "*vaddr" "map" 810Frees memory previously allocated by 811.Fn bus_dmamem_alloc . 812Any mappings 813will be invalidated. 814Arguments are as follows: 815.Bl -tag -width ".Fa vaddr" 816.It Fa dmat 817DMA tag. 818.It Fa vaddr 819Kernel virtual address of the memory. 820.It Fa map 821DMA map to be invalidated. 822.El 823.El 824.Sh RETURN VALUES 825Behavior is undefined if invalid arguments are passed to 826any of the above functions. 827If sufficient resources cannot be allocated for a given 828transaction, 829.Er ENOMEM 830is returned. 831All 832routines that are not of type 833.Vt void 834will return 0 on success or an error 835code on failure as discussed above. 836.Pp 837All 838.Vt void 839routines will succeed if provided with valid arguments. 840.Sh LOCKING 841Two locking protocols are used by 842.Nm . 843The first is a private global lock that is used to synchronize access to the 844bounce buffer pool on the architectures that make use of them. 845This lock is strictly a leaf lock that is only used internally to 846.Nm 847and is not exposed to clients of the API. 848.Pp 849The second protocol involves protecting various resources stored in the tag. 850Since almost all 851.Nm 852operations are done through requests from the driver that created the tag, 853the most efficient way to protect the tag resources is through the lock that 854the driver uses. 855In cases where 856.Nm 857acts on its own without being called by the driver, the lock primitive 858specified in the tag is acquired and released automatically. 859An example of this is when the 860.Fn bus_dmamap_load 861callback function is called from a deferred context instead of the driver 862context. 863This means that certain 864.Nm 865functions must always be called with the same lock held that is specified in the 866tag. 867These functions include: 868.Pp 869.Bl -item -offset indent -compact 870.It 871.Fn bus_dmamap_load 872.It 873.Fn bus_dmamap_load_uio 874.It 875.Fn bus_dmamap_load_mbuf 876.It 877.Fn bus_dmamap_load_mbuf_sg 878.It 879.Fn bus_dmamap_unload 880.It 881.Fn bus_dmamap_sync 882.El 883.Pp 884There is one exception to this rule. 885It is common practice to call some of these functions during driver start-up 886without any locks held. 887So long as there is a guarantee of no possible concurrent use of the tag by 888different threads during this operation, it is safe to not hold a lock for 889these functions. 890.Pp 891Certain 892.Nm 893operations should not be called with the driver lock held, either because 894they are already protected by an internal lock, or because they might sleep 895due to memory or resource allocation. 896The following functions must not be 897called with any non-sleepable locks held: 898.Pp 899.Bl -item -offset indent -compact 900.It 901.Fn bus_dma_tag_create 902.It 903.Fn bus_dmamap_create 904.It 905.Fn bus_dmamem_alloc 906.El 907.Pp 908All other functions do not have a locking protocol and can thus be 909called with or without any system or driver locks held. 910.Sh SEE ALSO 911.Xr devclass 9 , 912.Xr device 9 , 913.Xr driver 9 , 914.Xr rman 9 , 915.Xr vslock 9 916.Pp 917.Rs 918.%A "Jason R. Thorpe" 919.%T "A Machine-Independent DMA Framework for NetBSD" 920.%J "Proceedings of the Summer 1998 USENIX Technical Conference" 921.%Q "USENIX Association" 922.%D "June 1998" 923.Re 924.Sh HISTORY 925The 926.Nm 927interface first appeared in 928.Nx 1.3 . 929.Pp 930The 931.Nm 932API was adopted from 933.Nx 934for use in the CAM SCSI subsystem. 935The alterations to the original API were aimed to remove the need for 936a 937.Vt bus_dma_segment_t 938array stored in each 939.Vt bus_dmamap_t 940while allowing callers to queue up on scarce resources. 941.Sh AUTHORS 942The 943.Nm 944interface was designed and implemented by 945.An Jason R. Thorpe 946of the Numerical Aerospace Simulation Facility, NASA Ames Research Center. 947Additional input on the 948.Nm 949design was provided by 950.An -nosplit 951.An Chris Demetriou , 952.An Charles Hannum , 953.An Ross Harvey , 954.An Matthew Jacob , 955.An Jonathan Stone , 956and 957.An Matt Thomas . 958.Pp 959The 960.Nm 961interface in 962.Fx 963benefits from the contributions of 964.An Justin T. Gibbs , 965.An Peter Wemm , 966.An Doug Rabson , 967.An Matthew N. Dodd , 968.An Sam Leffler , 969.An Maxime Henrion , 970.An Jake Burkholder , 971.An Takahashi Yoshihiro , 972.An Scott Long 973and many others. 974.Pp 975This manual page was written by 976.An Hiten M. Pandya 977and 978.An Justin T. Gibbs . 979