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 November 16, 2008 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 486Are as follows: 487.Bl -tag -width ".Dv BUS_DMA_COHERENT" 488.It Dv BUS_DMA_COHERENT 489Attempt to map the memory loaded with this map such that cache sync 490operations are as cheap as possible. 491This flag is typically set on maps when the memory loaded with these will 492be accessed by both a CPU and a DMA engine, frequently such as control data 493and as opposed to streamable data such as receive and transmit buffers. 494Use of this flag does not remove the requirement of using 495.Fn bus_dmamap_sync , 496but it may reduce the cost of performing these operations. 497For 498.Fn bus_dmamap_create , 499the 500.Dv BUS_DMA_COHERENT 501flag is currently implemented on sparc64. 502.El 503.It Fa mapp 504Pointer to a 505.Vt bus_dmamap_t 506where the resulting DMA map will be stored. 507.El 508.Pp 509Returns 510.Er ENOMEM 511if sufficient memory is not available for creating the 512map or allocating mapping resources. 513.It Fn bus_dmamap_destroy "dmat" "map" 514Frees all resources associated with a given DMA map. 515Arguments are as follows: 516.Bl -tag -width ".Fa dmat" 517.It Fa dmat 518DMA tag used to allocate 519.Fa map . 520.It Fa map 521The DMA map to destroy. 522.El 523.Pp 524Returns 525.Er EBUSY 526if a mapping is still active for 527.Fa map . 528.It Fn bus_dmamap_load "dmat" "map" "buf" "buflen" "*callback" \ 529"callback_arg" "flags" 530Creates a mapping in device visible address space of 531.Fa buflen 532bytes of 533.Fa buf , 534associated with the DMA map 535.Fa map . 536This call will always return immediately and will not block for any reason. 537Arguments are as follows: 538.Bl -tag -width ".Fa buflen" 539.It Fa dmat 540DMA tag used to allocate 541.Fa map . 542.It Fa map 543A DMA map without a currently active mapping. 544.It Fa buf 545A kernel virtual address pointer to a contiguous (in KVA) buffer, to be 546mapped into device visible address space. 547.It Fa buflen 548The size of the buffer. 549.It Fa callback Fa callback_arg 550The callback function, and its argument. 551This function is called once sufficient mapping resources are available for 552the DMA operation. 553If resources are temporarily unavailable, this function will be deferred until 554later, but the load operation will still return immediately to the caller. 555Thus, callers should not assume that the callback will be called before the 556load returns, and code should be structured appropriately to handle this. 557See below for specific flags and error codes that control this behavior. 558.It Fa flags 559Are as follows: 560.Bl -tag -width ".Dv BUS_DMA_NOWAIT" 561.It Dv BUS_DMA_NOWAIT 562The load should not be deferred in case of insufficient mapping resources, 563and instead should return immediately with an appropriate error. 564.It Dv BUS_DMA_NOCACHE 565The allocated memory will not be cached in the processor caches. 566All memory accesses appear on the bus and are executed 567without reordering. 568On the amd64 and i386 architectures this flag results in the 569Strong Uncacheable PAT to be set for the allocated virtual address range. 570The 571.Dv BUS_DMA_NOCACHE 572flag is currently implemented on amd64, i386 and sparc64. 573.El 574.El 575.Pp 576Return values to the caller are as follows: 577.Bl -tag -width ".Er EINPROGRESS" 578.It 0 579The callback has been called and completed. 580The status of the mapping has been delivered to the callback. 581.It Er EINPROGRESS 582The mapping has been deferred for lack of resources. 583The callback will be called as soon as resources are available. 584Callbacks are serviced in FIFO order. 585To ensure that ordering is guaranteed, all subsequent load requests will also 586be deferred until all callbacks have been processed. 587.It Er ENOMEM 588The load request has failed due to insufficient resources, and the caller 589specifically used the 590.Dv BUS_DMA_NOWAIT 591flag. 592.It Er EINVAL 593The load request was invalid. 594The callback has been called and has been provided the same error. 595This error value may indicate that 596.Fa dmat , 597.Fa map , 598.Fa buf , 599or 600.Fa callback 601were invalid, or 602.Fa buflen 603was larger than the 604.Fa maxsize 605argument used to create the dma tag 606.Fa dmat . 607.El 608.Pp 609When the callback is called, it is presented with an error value 610indicating the disposition of the mapping. 611Error may be one of the following: 612.Bl -tag -width ".Er EINPROGRESS" 613.It 0 614The mapping was successful and the 615.Fa dm_segs 616callback argument contains an array of 617.Vt bus_dma_segment_t 618elements describing the mapping. 619This array is only valid during the scope of the callback function. 620.It Er EFBIG 621A mapping could not be achieved within the segment constraints provided 622in the tag even though the requested allocation size was less than maxsize. 623.El 624.It Fn bus_dmamap_load_mbuf "dmat" "map" "mbuf" "callback2" "callback_arg" \ 625"flags" 626This is a variation of 627.Fn bus_dmamap_load 628which maps mbuf chains 629for DMA transfers. 630A 631.Vt bus_size_t 632argument is also passed to the callback routine, which 633contains the mbuf chain's packet header length. 634The 635.Dv BUS_DMA_NOWAIT 636flag is implied, thus no callback deferral will happen. 637.Pp 638Mbuf chains are assumed to be in kernel virtual address space. 639.Pp 640Beside the error values listed for 641.Fn bus_dmamap_load , 642.Er EINVAL 643will be returned if the size of the mbuf chain exceeds the maximum limit of the 644DMA tag. 645.It Fn bus_dmamap_load_mbuf_sg "dmat" "map" "mbuf" "segs" "nsegs" "flags" 646This is just like 647.Fn bus_dmamap_load_mbuf 648except that it returns immediately without calling a callback function. 649It is provided for efficiency. 650The scatter/gather segment array 651.Va segs 652is provided by the caller and filled in directly by the function. 653The 654.Va nsegs 655argument is returned with the number of segments filled in. 656Returns the same errors as 657.Fn bus_dmamap_load_mbuf . 658.It Fn bus_dmamap_load_uio "dmat" "map" "uio" "callback2" "callback_arg" "flags" 659This is a variation of 660.Fn bus_dmamap_load 661which maps buffers pointed to by 662.Fa uio 663for DMA transfers. 664A 665.Vt bus_size_t 666argument is also passed to the callback routine, which contains the size of 667.Fa uio , 668i.e. 669.Fa uio->uio_resid . 670The 671.Dv BUS_DMA_NOWAIT 672flag is implied, thus no callback deferral will happen. 673Returns the same errors as 674.Fn bus_dmamap_load . 675.Pp 676If 677.Fa uio->uio_segflg 678is 679.Dv UIO_USERSPACE , 680then it is assumed that the buffer, 681.Fa uio 682is in 683.Fa "uio->uio_td->td_proc" Ns 's 684address space. 685User space memory must be in-core and wired prior to attempting a map 686load operation. 687Pages may be locked using 688.Xr vslock 9 . 689.It Fn bus_dmamap_unload "dmat" "map" 690Unloads a DMA map. 691Arguments are as follows: 692.Bl -tag -width ".Fa dmam" 693.It Fa dmat 694DMA tag used to allocate 695.Fa map . 696.It Fa map 697The DMA map that is to be unloaded. 698.El 699.Pp 700.Fn bus_dmamap_unload 701will not perform any implicit synchronization of DMA buffers. 702This must be done explicitly by a call to 703.Fn bus_dmamap_sync 704prior to unloading the map. 705.It Fn bus_dmamap_sync "dmat" "map" "op" 706Performs synchronization of a device visible mapping with the CPU visible 707memory referenced by that mapping. 708Arguments are as follows: 709.Bl -tag -width ".Fa dmat" 710.It Fa dmat 711DMA tag used to allocate 712.Fa map . 713.It Fa map 714The DMA mapping to be synchronized. 715.It Fa op 716Type of synchronization operation to perform. 717See the definition of 718.Vt bus_dmasync_op_t 719for a description of the acceptable values for 720.Fa op . 721.El 722.Pp 723The 724.Fn bus_dmamap_sync 725function 726is the method used to ensure that CPU's and device's direct 727memory access (DMA) to shared 728memory is coherent. 729For example, the CPU might be used to set up the contents of a buffer 730that is to be made available to a device. 731To ensure that the data are visible via the device's mapping of that 732memory, the buffer must be loaded and a DMA sync operation of 733.Dv BUS_DMASYNC_PREWRITE 734must be performed after the CPU has updated the buffer and before the device 735access is initiated. 736If the CPU modifies this buffer again later, another 737.Dv BUS_DMASYNC_PREWRITE 738sync operation must be performed before an additional device 739access. 740Conversely, suppose a device updates memory that is to be read by a CPU. 741In this case, the buffer must be loaded, and a DMA sync operation of 742.Dv BUS_DMASYNC_PREREAD 743must be performed before the device access is initiated. 744The CPU will only be able to see the results of this memory update 745once the DMA operation has completed and a 746.Dv BUS_DMASYNC_POSTREAD 747sync operation has been performed. 748.Pp 749If read and write operations are not preceded and followed by the 750appropriate synchronization operations, behavior is undefined. 751.It Fn bus_dmamem_alloc "dmat" "**vaddr" "flags" "*mapp" 752Allocates memory that is mapped into KVA at the address returned 753in 754.Fa vaddr 755and that is permanently loaded into the newly created 756.Vt bus_dmamap_t 757returned via 758.Fa mapp . 759Arguments are as follows: 760.Bl -tag -width ".Fa alignment" 761.It Fa dmat 762DMA tag describing the constraints of the DMA mapping. 763.It Fa vaddr 764Pointer to a pointer that will hold the returned KVA mapping of 765the allocated region. 766.It Fa flags 767Flags are defined as follows: 768.Bl -tag -width ".Dv BUS_DMA_NOWAIT" 769.It Dv BUS_DMA_WAITOK 770The routine can safely wait (sleep) for resources. 771.It Dv BUS_DMA_NOWAIT 772The routine is not allowed to wait for resources. 773If resources are not available, 774.Dv ENOMEM 775is returned. 776.It Dv BUS_DMA_COHERENT 777Attempt to map this memory in a coherent fashion. 778See 779.Fn bus_dmamap_create 780above for a description of this flag. 781For 782.Fn bus_dmamem_alloc , 783the 784.Dv BUS_DMA_COHERENT 785flag is currently implemented on arm and sparc64. 786.It Dv BUS_DMA_ZERO 787Causes the allocated memory to be set to all zeros. 788.El 789.It Fa mapp 790Pointer to a 791.Vt bus_dmamap_t 792where the resulting DMA map will be stored. 793.El 794.Pp 795The size of memory to be allocated is 796.Fa maxsize 797as specified in the call to 798.Fn bus_dma_tag_create 799for 800.Fa dmat . 801.Pp 802The current implementation of 803.Fn bus_dmamem_alloc 804will allocate all requests as a single segment. 805.Pp 806An initial load operation is required to obtain the bus address of the allocated 807memory, and an unload operation is required before freeing the memory, as 808described below in 809.Fn bus_dmamem_free . 810Maps are automatically handled by this function and should not be explicitly 811allocated or destroyed. 812.Pp 813Although an explicit load is not required for each access to the memory 814referenced by the returned map, the synchronization requirements 815as described in the 816.Fn bus_dmamap_sync 817section still apply and should be used to achieve portability on architectures 818without coherent buses. 819.Pp 820Returns 821.Er ENOMEM 822if sufficient memory is not available for completing 823the operation. 824.It Fn bus_dmamem_free "dmat" "*vaddr" "map" 825Frees memory previously allocated by 826.Fn bus_dmamem_alloc . 827Any mappings 828will be invalidated. 829Arguments are as follows: 830.Bl -tag -width ".Fa vaddr" 831.It Fa dmat 832DMA tag. 833.It Fa vaddr 834Kernel virtual address of the memory. 835.It Fa map 836DMA map to be invalidated. 837.El 838.El 839.Sh RETURN VALUES 840Behavior is undefined if invalid arguments are passed to 841any of the above functions. 842If sufficient resources cannot be allocated for a given 843transaction, 844.Er ENOMEM 845is returned. 846All 847routines that are not of type 848.Vt void 849will return 0 on success or an error 850code on failure as discussed above. 851.Pp 852All 853.Vt void 854routines will succeed if provided with valid arguments. 855.Sh LOCKING 856Two locking protocols are used by 857.Nm . 858The first is a private global lock that is used to synchronize access to the 859bounce buffer pool on the architectures that make use of them. 860This lock is strictly a leaf lock that is only used internally to 861.Nm 862and is not exposed to clients of the API. 863.Pp 864The second protocol involves protecting various resources stored in the tag. 865Since almost all 866.Nm 867operations are done through requests from the driver that created the tag, 868the most efficient way to protect the tag resources is through the lock that 869the driver uses. 870In cases where 871.Nm 872acts on its own without being called by the driver, the lock primitive 873specified in the tag is acquired and released automatically. 874An example of this is when the 875.Fn bus_dmamap_load 876callback function is called from a deferred context instead of the driver 877context. 878This means that certain 879.Nm 880functions must always be called with the same lock held that is specified in the 881tag. 882These functions include: 883.Pp 884.Bl -item -offset indent -compact 885.It 886.Fn bus_dmamap_load 887.It 888.Fn bus_dmamap_load_uio 889.It 890.Fn bus_dmamap_load_mbuf 891.It 892.Fn bus_dmamap_load_mbuf_sg 893.It 894.Fn bus_dmamap_unload 895.It 896.Fn bus_dmamap_sync 897.El 898.Pp 899There is one exception to this rule. 900It is common practice to call some of these functions during driver start-up 901without any locks held. 902So long as there is a guarantee of no possible concurrent use of the tag by 903different threads during this operation, it is safe to not hold a lock for 904these functions. 905.Pp 906Certain 907.Nm 908operations should not be called with the driver lock held, either because 909they are already protected by an internal lock, or because they might sleep 910due to memory or resource allocation. 911The following functions must not be 912called with any non-sleepable locks held: 913.Pp 914.Bl -item -offset indent -compact 915.It 916.Fn bus_dma_tag_create 917.It 918.Fn bus_dmamap_create 919.It 920.Fn bus_dmamem_alloc 921.El 922.Pp 923All other functions do not have a locking protocol and can thus be 924called with or without any system or driver locks held. 925.Sh SEE ALSO 926.Xr devclass 9 , 927.Xr device 9 , 928.Xr driver 9 , 929.Xr rman 9 , 930.Xr vslock 9 931.Pp 932.Rs 933.%A "Jason R. Thorpe" 934.%T "A Machine-Independent DMA Framework for NetBSD" 935.%J "Proceedings of the Summer 1998 USENIX Technical Conference" 936.%Q "USENIX Association" 937.%D "June 1998" 938.Re 939.Sh HISTORY 940The 941.Nm 942interface first appeared in 943.Nx 1.3 . 944.Pp 945The 946.Nm 947API was adopted from 948.Nx 949for use in the CAM SCSI subsystem. 950The alterations to the original API were aimed to remove the need for 951a 952.Vt bus_dma_segment_t 953array stored in each 954.Vt bus_dmamap_t 955while allowing callers to queue up on scarce resources. 956.Sh AUTHORS 957The 958.Nm 959interface was designed and implemented by 960.An Jason R. Thorpe 961of the Numerical Aerospace Simulation Facility, NASA Ames Research Center. 962Additional input on the 963.Nm 964design was provided by 965.An -nosplit 966.An Chris Demetriou , 967.An Charles Hannum , 968.An Ross Harvey , 969.An Matthew Jacob , 970.An Jonathan Stone , 971and 972.An Matt Thomas . 973.Pp 974The 975.Nm 976interface in 977.Fx 978benefits from the contributions of 979.An Justin T. Gibbs , 980.An Peter Wemm , 981.An Doug Rabson , 982.An Matthew N. Dodd , 983.An Sam Leffler , 984.An Maxime Henrion , 985.An Jake Burkholder , 986.An Takahashi Yoshihiro , 987.An Scott Long 988and many others. 989.Pp 990This manual page was written by 991.An Hiten M. Pandya 992and 993.An Justin T. Gibbs . 994