1.\" 2.\" Copyright (c) 2002, 2003, 2004 The DragonFly Project. All rights reserved. 3.\" 4.\" This code is derived from software contributed to The DragonFly Project 5.\" by Hiten Pandya <hmp@backplane.com>. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" notice, this list of conditions and the following disclaimer in 15.\" the documentation and/or other materials provided with the 16.\" distribution. 17.\" 3. Neither the name of The DragonFly Project nor the names of its 18.\" contributors may be used to endorse or promote products derived 19.\" from this software without specific, prior written permission. 20.\" 21.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 22.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 23.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 24.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE 25.\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, 26.\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING, 27.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 28.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 29.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 30.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT 31.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32.\" SUCH DAMAGE. 33.\" 34.\" Copyright (c) 1996, 1997, 1998, 2001 The NetBSD Foundation, Inc. 35.\" All rights reserved. 36.\" 37.\" This code is derived from software contributed to The NetBSD Foundation 38.\" by Jason R. Thorpe of the Numerical Aerospace Simulation Facility, 39.\" NASA Ames Research Center. 40.\" 41.\" Redistribution and use in source and binary forms, with or without 42.\" modification, are permitted provided that the following conditions 43.\" are met: 44.\" 1. Redistributions of source code must retain the above copyright 45.\" notice, this list of conditions and the following disclaimer. 46.\" 2. Redistributions in binary form must reproduce the above copyright 47.\" notice, this list of conditions and the following disclaimer in the 48.\" documentation and/or other materials provided with the distribution. 49.\" 3. All advertising materials mentioning features or use of this software 50.\" must display the following acknowledgment: 51.\" This product includes software developed by the NetBSD 52.\" Foundation, Inc. and its contributors. 53.\" 4. Neither the name of The NetBSD Foundation nor the names of its 54.\" contributors may be used to endorse or promote products derived 55.\" from this software without specific prior written permission. 56.\" 57.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 58.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 59.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 60.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 61.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 62.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 63.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 64.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 65.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 66.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 67.\" POSSIBILITY OF SUCH DAMAGE. 68.\" 69.\" $FreeBSD: /repoman/r/ncvs/src/share/man/man9/bus_dma.9,v 1.7 2003/07/27 14:05:29 mux Exp $ 70.\" $NetBSD: bus_dma.9,v 1.25 2002/10/14 13:43:16 wiz Exp $ 71.\" $DragonFly: src/share/man/man9/bus_dma.9,v 1.5 2005/12/28 13:35:02 swildner Exp $ 72.\" 73.Dd March 17, 2004 74.Dt BUS_DMA 9 75.Os 76.Sh NAME 77.Nm bus_dma , 78.Nm bus_dma_tag_create , 79.Nm bus_dma_tag_destroy , 80.Nm bus_dmamap_create , 81.Nm bus_dmamap_destroy , 82.Nm bus_dmamap_load , 83.Nm bus_dmamap_load_mbuf , 84.Nm bus_dmamap_load_uio , 85.Nm bus_dmamap_unload , 86.Nm bus_dmamap_sync , 87.Nm bus_dmamem_alloc , 88.Nm bus_dmamem_free 89.Nd Bus and Machine Independent DMA Mapping Interface 90.Sh SYNOPSIS 91.In machine/bus.h 92.Ft int 93.Fn bus_dma_tag_create "bus_dma_tag_t parent" "bus_size_t alignment" \ 94"bus_size_t boundary" "bus_addr_t lowaddr" "bus_addr_t highaddr" \ 95"bus_dma_filter_t *filtfunc" "void *filtfuncarg" "bus_size_t maxsize" \ 96"int nsegments" "bus_size_t maxsegsz" "int flags" "bus_dma_tag_t *dmat" 97.Ft int 98.Fn bus_dma_tag_destroy "bus_dma_tag_t dmat" 99.Ft int 100.Fn bus_dmamap_create "bus_dma_tag_t dmat" "int flags" "bus_dmamap_t *mapp" 101.Ft int 102.Fn bus_dmamap_destroy "bus_dma_tag_t dmat" "bus_dmamap_t map" 103.Ft int 104.Fn bus_dmamap_load "bus_dma_tag_t dmat" "bus_dmamap_t map" "void *buf" \ 105"bus_size_t buflen" "bus_dmamap_callback_t *callback" "void *callback_arg" \ 106"int flags" 107.Ft int 108.Fn bus_dmamap_load_mbuf "bus_dma_tag_t dmat" "bus_dmamap_t map" \ 109"struct mbuf *mbuf" "bus_dmamap_callback2_t *callback" "void *callback_arg" \ 110"int flags" 111.Ft int 112.Fn bus_dmamap_load_uio "bus_dma_tag_t dmat" "bus_dmamap_t map" \ 113"struct uio *uio" "bus_dmamap_callback2_t *callback" "void *callback_arg" \ 114"int flags" 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_dmamap_unload "bus_dma_tag_t dmat" "bus_dmamap_t map" 120.Ft void 121.Fn bus_dmamap_sync "bus_dma_tag_t dmat" "bus_dmamap_t map" \ 122"op" 123.Ft void 124.Fn bus_dmamem_free "bus_dma_tag_t dmat" "void *vaddr" \ 125"bus_dmamap_t map" 126.Sh DESCRIPTION 127Direct Memory Access (DMA) is a method of transferring data 128without involving the CPU, thus providing higher performance. 129A DMA transaction can be achieved between device to memory, 130device to device, or memory to memory. 131.Pp 132The 133.Nm 134API is a bus, device, and machine-independent (MI) interface to 135DMA mechanisms. 136It provides the client with flexibility and simplicity by 137abstracting machine dependent issues like setting up 138DMA mappings, handling cache issues, bus specific features 139and limitations. 140.Sh STRUCTURES AND TYPES 141.Bl -tag -width compact 142.It Vt bus_dma_tag_t 143A machine-dependent (MD) opaque type that describes the 144characteristics of DMA transactions. 145DMA tags are organized into a hierarchy, with each child 146tag inheriting the restrictions of its parent. 147This allows all devices along the path of DMA transactions 148to contribute to the constraints of those transactions. 149.It Vt bus_dma_filter_t 150Client specified address filter having the format: 151.Bl -tag -width compact 152.It Ft int 153.Fn "client_filter" "void *filtarg" "bus_addr_t testaddr" 154.El 155.sp 156Address filters can be specified during tag creation to allow 157for devices who's DMA address restrictions cannot be specified 158by a single window. 159The 160.Fa filtarg 161is client specified during tag creation to be passed to all 162invocations of the callback. 163The 164.Fa testaddr 165argument contains a potential starting address of a DMA mapping. 166The filter function operates on the set of addresses from 167.Fa testaddr 168to 169.Ql trunc_page(testaddr) + PAGE_SIZE - 1 , 170inclusive. 171The filter function should return zero for any mapping in this range 172that can be accommodated by the device and non-zero otherwise. 173.It Vt bus_dma_segment_t 174A machine-dependent type that describes individual 175DMA segments. 176.Bd -literal 177 bus_addr_t ds_addr; 178 bus_size_t ds_len; 179.Ed 180.sp 181The 182.Fa ds_addr 183field contains the device visible address of the DMA segment, and 184.Fa ds_len 185contains the length of the DMA segment. 186Although the DMA segments returned by a mapping call will adhere to 187all restrictions necessary for a successful DMA operation, some conversion 188(e.g. a conversion from host byte order to the device's byte order) is 189almost always required when presenting segment information to the device. 190.It Vt bus_dmamap_t 191A machine-dependent opaque type describing an individual mapping. 192Multiple DMA maps can be associated with one DMA tag. 193.It Vt bus_dmamap_callback_t 194Client specified callback for receiving mapping information resulting from 195the load of a 196.Vt bus_dmamap_t 197via 198.Fn bus_dmamap_load . 199Callbacks are of the format: 200.Bl -tag -width compact 201.It Ft void 202.Fn "client_callback" "void *callback_arg" "bus_dma_segment_t *segs" \ 203"int nseg" "int error" 204.El 205.sp 206The 207.Fa callback_arg 208is the callback argument passed to dmamap load functions. 209The 210.Fa segs 211and 212.Fa nseg 213parameters describe an array of 214.Vt bus_dma_segment_t 215structures that represent the mapping. 216This array is only valid within the scope of the callback function. 217The success or failure of the mapping is indicated by the 218.Fa error 219parameter. 220More information on the use of callbacks can be found in the 221description of the individual dmamap load functions. 222.It Vt bus_dmamap_callback2_t 223Client specified callback for receiving mapping information resulting from 224the load of a 225.Vt bus_dmamap_t 226via 227.Fn bus_dmamap_load_uio 228or 229.Fn bus_dmamap_load_mbuf . 230.sp 231Callback2s are of the format: 232.Bl -tag -width compact 233.It Ft void 234.Fn "client_callback2" "void *callback_arg" "bus_dma_segment_t *segs" \ 235"int nseg" "bus_size_t mapsize" "int error" 236.El 237.sp 238Callback2's behavior is the same as 239.Vt bus_dmamap_callback_t 240with the addition that the length of the data mapped is provided via 241.Fa mapsize . 242.It Vt bus_dmasync_op_t 243Memory synchronization operation specifier. 244Bus DMA requires explicit synchronization of memory with it's device 245visible mapping in order to guarantee memory coherency. 246The 247.Vt bus_dmasync_op_t 248allows the type of DMA operation that will be or has been performed 249to be communicated to the system so that the correct coherency measures 250are taken. 251All operations specified below are performed from the DMA engine's 252point of view: 253.Bl -tag -width BUS_DMASYNC_POSTWRITE 254.It Dv BUS_DMASYNC_PREREAD 255Perform any synchronization required after an update of memory by the CPU 256but prior to DMA read operations. 257.It Dv BUS_DMASYNC_PREWRITE 258Perform any synchronization required after an update of memory by the CPU 259but prior to DMA write operations. 260.It Dv BUS_DMASYNC_PREREAD|BUS_DMASYNC_PREWRITE 261Perform any synchronization required prior to a combination of DMA read 262and write operations. 263.It Dv BUS_DMASYNC_POSTREAD 264Perform any synchronization required after DMA read operations, but prior 265to CPU access of the memory. 266.It Dv BUS_DMASYNC_POSTWRITE 267Perform any synchronization required after DMA write operations, but prior 268to CPU access of the memory. 269.It Dv BUS_DMASYNC_POSTREAD|BUS_DMASYNC_POSTWRITE 270Perform any synchronization required after a combination of DMA read 271and write operations. 272.El 273.El 274.sp 275.Sh FUNCTIONS 276.Bl -tag -width compact 277.It Fn bus_dma_tag_create "parent" "alignment" "boundary" "lowaddr" \ 278"highaddr" "*filtfunc" "*filtfuncarg" "maxsize" "nsegments" "maxsegsz" \ 279"flags" "*dmat" 280Allocates a device specific DMA tag, and initializes it according to 281the arguments provided: 282.Bl -tag -width *filtfuncarg -compact 283.It Fa parent 284Indicates restrictions between the parent bridge, CPU memory, and the 285device. 286May be NULL, if no DMA restrictions are to be inherited. 287.It Fa alignment 288Alignment constraint, in bytes, of any mappings created using this tag. 289The alignment must be a power of 2. 290Hardware that can DMA starting at any address would specify 291.Em 1 292for byte alignment. 293Hardware requiring DMA transfers to start on a multiple of 4K 294would specify 295.Em 4096. 296.It Fa boundary 297Boundary constraint, in bytes, of the target DMA memory region. 298The boundary indicates the set of addresses, all multiples of the 299boundary argument, that cannot be crossed by a single 300.Vt bus_dma_segment_t . 301The boundary must be either a power of 2 or 0. 302.Ql 0 303indicates that there are no boundary restrictions. 304.It Fa lowaddr 305.It Fa highaddr 306Bounds of the window of bus address space that 307.Em cannot 308be directly accessed by the device. 309The window contains all address greater than lowaddr and 310less than or equal to highaddr. 311For example, a device incapable of DMA above 4GB, would specify 312a highaddr of 313.Dv BUS_SPACE_MAXADDR 314and a lowaddr of 315.Dv BUS_SPACE_MAXADDR_32BIT . 316Similarly a device that can only dma to addresses bellow 16MB would 317specify a highaddr of 318.Dv BUS_SPACE_MAXADDR 319and a lowaddr of 320.Dv BUS_SPACE_MAXADDR_24BIT . 321Some implementations requires that some region of device visible 322address space, overlapping available host memory, be outside the 323window. 324This area of 325.Ql safe memory 326is used to bounce requests that would otherwise conflict with 327the exclusion window. 328.It Fa filtfunc 329Optional filter function (may be NULL) to be called for any attempt to 330map memory into the window described by 331.Fa lowaddr 332and 333.Fa highaddr. 334A filter function is only required when the single window described 335by 336.Fa lowaddr 337and 338.Fa highaddr 339cannot adequately describe the constraints of the device. 340The filter function will be called for every machine page 341that overlaps the exclusion window. 342.It Fa filtfuncarg 343Argument passed to all calls to the filter function for this tag. 344May be NULL. 345.It Fa maxsize 346Maximum size, in bytes, of the sum of all segment lengths in a given 347DMA mapping associated with this tag. 348.It Fa nsegments 349Number of discontinuities (scatter/gather segments) allowed 350in a DMA mapped region. 351If there is no restriction, 352.Dv BUS_SPACE_UNRESTRICTED 353may be specified. 354.It Fa maxsegsz 355Maximum size, in bytes, of a segment in any DMA mapped region associated 356with 357.Fa dmat . 358.It Fa flags 359Are as follows: 360.Bl -tag -width "BUS_DMA_ALLOCNOW" -compact 361.It Dv BUS_DMA_ALLOCNOW 362Allocate the resources necessary to guarantee that all map load 363operations associated with this tag will not block. 364If sufficient resources are not available, 365.Er ENOMEM 366is returned. 367.El 368.It Fa dmat 369Pointer to a bus_dma_tag_t where the resulting DMA tag will 370be stored. 371.El 372.Pp 373Returns 374.Er ENOMEM 375if sufficient memory is not available for tag creation 376or allocating mapping resources. 377.It Fn bus_dma_tag_destroy "dmat" 378Deallocate the DMA tag 379.Fa dmat 380that was created by 381.Fn bus_dma_tag_create . 382.Pp 383Returns 384.Er EBUSY 385if any DMA maps remain associated with 386.Fa dmat 387or 388.Ql 0 389on success. 390.It Fn bus_dmamap_create "dmat" "flags" "*mapp" 391Allocates and initializes a DMA map. 392Arguments are as follows: 393.Bl -tag -width nsegments -compact 394.It Fa dmat 395DMA tag. 396.It Fa flags 397The value of this argument is currently undefined and should be 398specified as 399.Ql 0 . 400.It Fa mapp 401Pointer to a 402.Vt bus_dmamap_t 403where the resulting DMA map will be stored. 404.El 405.Pp 406Returns 407.Er ENOMEM 408if sufficient memory is not available for creating the 409map or allocating mapping resources. 410.It Fn bus_dmamap_destroy "dmat" "map" 411Frees all resources associated with a given DMA map. 412Arguments are as follows: 413.Bl -tag -width dmat -compact 414.It Fa dmat 415DMA tag used to allocate 416.Fa map . 417.It Fa map 418The DMA map to destroy. 419.El 420.Pp 421Returns 422.Er EBUSY 423if a mapping is still active for 424.Fa map . 425.It Fn bus_dmamap_load "dmat" "map" "buf" "buflen" "*callback" "..." 426Creates a mapping in device visible address space of 427.Fa buflen 428bytes of 429.Fa buf , 430associated with the DMA map 431.Fa map. 432Arguments are as follows: 433.Bl -tag -width buflen -compact 434.It Fa dmat 435DMA tag used to allocate 436.Fa map. 437.It Fa map 438A DMA map without a currently active mapping. 439.It Fa buf 440A kernel virtual address pointer to a contiguous (in KVA) buffer, to be 441mapped into device visible address space. 442.It Fa buflen 443The size of the buffer. 444.It Fa callback Fa callback_arg 445The callback function, and its argument. 446.It Fa flags 447The value of this argument is currently undefined, and should be 448specified as 449.Ql 0 . 450.El 451.Pp 452Return values to the caller are as follows: 453.Bl -tag -width EINPROGRESS -compact 454.It 0 455The callback has been called and completed. 456The status of the mapping has been delivered to the callback. 457.It Er EINPROGRESS 458The mapping has been deferred for lack of resources. 459The callback will be called as soon as resources are available. 460Callbacks are serviced in FIFO order. 461DMA maps created from DMA tags that are allocated with 462the 463.Dv BUS_DMA_ALLOCNOW 464flag will never return this status for a load operation. 465.It Er EINVAL 466The load request was invalid. 467The callback has not, and will not be called. 468This error value may indicate that 469.Fa dmat , 470.Fa map , 471.Fa buf , 472or 473.Fa callback 474were invalid, or 475.Fa buslen 476was larger than the 477.Fa maxsize 478argument used to create the dma tag 479.Fa dmat . 480.El 481.Pp 482When the callback is called, it is presented with an error value 483indicating the disposition of the mapping. 484Error may be one of the following: 485.Bl -tag -width EINPROGRESS -compact 486.It 0 487The mapping was successful and the 488.Fa dm_segs 489callback argument contains an array of 490.Vt bus_dma_segment_t 491elements describing the mapping. 492This array is only valid during the scope of the callback function. 493.It Er EFBIG 494A mapping could not be achieved within the segment constraints provided 495in the tag even though the requested allocation size was less than maxsize. 496.El 497.It Fn bus_dmamap_load_mbuf "dmat" "map" "mbuf" "callback2" "callback_arg" \ 498"flags" 499This is a variation of 500.Fn bus_dmamap_load 501which maps mbuf chains 502for DMA transfers. 503A 504.Vt bus_size_t 505argument is also passed to the callback routine, which 506contains the mbuf chain's packet header length. 507.Pp 508Mbuf chains are assumed to be in kernel virtual address space. 509.Pp 510Returns 511.Er EINVAL 512if the size of the mbuf chain exceeds the maximum limit of the 513DMA tag. 514.It Fn bus_dmamap_load_uio "dmat" "map" "uio" "callback2" "callback_arg" "flags" 515This is a variation of 516.Fn bus_dmamap_load 517which maps buffers pointed to by 518.Fa uio 519for DMA transfers. 520A 521.Vt bus_size_t 522argument is also passed to the callback routine, which contains the size of 523.Fa uio , 524i.e. 525.Fa uio->uio_resid . 526.Pp 527If 528.Fa uio->uio_segflg 529is 530.Dv UIO_USERSPACE , 531then it is assumed that the buffer, 532.Fa uio 533is in 534.Fa "uio->uio_td->td_proc" Ns 's 535address space. 536User space memory must be in-core and wired prior to attempting a map 537load operation. 538.It Fn bus_dmamap_unload "dmat" "map" 539Unloads a DMA map. 540Arguments are as follows: 541.Bl -tag -width dmam -compact 542.It Fa dmat 543DMA tag used to allocate 544.Fa map . 545.It Fa map 546The DMA map that is to be unloaded. 547.El 548.Pp 549.Fn bus_dmamap_unload 550will not perform any implicit synchronization of DMA buffers. 551This must be done explicitly by a call to 552.Fn bus_dmamap_sync 553prior to unloading the map. 554.It Fn bus_dmamap_sync "dmat" "map" "op" 555Performs synchronization of a device visible mapping with the CPU visible 556memory referenced by that mapping. 557Arguments are as follows: 558.Bl -tag -width dmat -compact 559.It Fa dmat 560DMA tag used to allocate 561.Fa map . 562.It Fa map 563The DMA mapping to be synchronized. 564.It Fa op 565Type of synchronization operation to perform. 566See the definition of 567.Vt bus_dmasync_op_t 568for a description of the acceptable values for 569.Fa op . 570.El 571.Pp 572.Fn bus_dmamap_sync 573is the method used to ensure that CPU and device DMA access to shared 574memory is coherent. 575For example, the CPU might be used to setup the contents of a buffer 576that is to be DMA'ed into a device. 577To ensure that the data are visible via the device's mapping of that 578memory, the buffer must be loaded and a dma sync operation of 579.Dv BUS_DMASYNC_PREREAD 580must be performed. 581Additional sync operations must be performed after every CPU write 582to this memory if additional DMA reads are to be performed. 583Conversely, for the DMA write case, the buffer must be loaded, 584and a dma sync operation of 585.Dv BUS_DMASYNC_PREWRITE 586must be performed. 587The CPU will only be able to see the results of this DMA write 588once the DMA has completed and a 589.Dv BUS_DMASYNC_POSTWRITE 590operation has been performed. 591.Pp 592If DMA read and write operations are not preceded and followed by the 593appropriate synchronization operations, behavior is undefined. 594.It Fn bus_dmamem_alloc "dmat" "**vaddr" "flags" "mapp" 595Allocates memory that is mapped into KVA at the address returned 596in 597.Fa vaddr 598that is permanently loaded into the newly created 599.Vt bus_dmamap_t 600returned via 601.Fa mapp . 602Arguments are as follows: 603.Bl -tag -width alignment -compact 604.It Fa dmat 605DMA tag describing the constraints of the DMA mapping. 606.It Fa vaddr 607Pointer to a pointer that will hold the returned KVA mapping of 608the allocated region. 609.It Fa flags 610Flags are defined as follows: 611.Bl -tag -width BUS_DMA_NOWAIT -compact 612.It Dv BUS_DMA_WAITOK 613The routine can safely wait (sleep) for resources. 614.It Dv BUS_DMA_NOWAIT 615The routine is not allowed to wait for resources. 616If resources are not available, 617.Er ENOMEM 618is returned. 619.It Dv BUS_DMA_COHERENT 620Attempt to map this memory such that cache sync operations are 621as cheap as possible. 622This flag is typically set on memory that will be accessed by both 623a CPU and a DMA engine, frequently. 624Use of this flag does not remove the requirement of using 625bus_dmamap_sync, but it may reduce the cost of performing 626these operations. 627.It Dv BUS_DMA_ZERO 628Causes the allocated memory to be set to all zeros. 629.El 630.It Fa mapp 631Pointer to storage for the returned DMA map. 632.El 633.Pp 634The size of memory to be allocated is 635.Fa maxsize 636as specified in 637.Fa dmat . 638.Pp 639The current implementation of 640.Fn bus_dmamem_alloc 641will allocate all requests as a single segment. 642.Pp 643Although no explicit loading is required to access the memory 644referenced by the returned map, the synchronization requirements 645as described in the 646.Fn bus_dmamap_sync 647section still apply. 648.Pp 649Returns 650.Er ENOMEM 651if sufficient memory is not available for completing 652the operation. 653.It Fn bus_dmamem_free "dmat" "*vaddr" "map" 654Frees memory previously allocated by 655.Fn bus_dmamem_alloc . 656Any mappings 657will be invalidated. 658Arguments are as follows: 659.Bl -tag -width vaddr -compact 660.It Fa dmat 661DMA tag. 662.It Fa vaddr 663Kernel virtual address of the memory. 664.It Fa map 665DMA map to be invalidated. 666.El 667.El 668.Sh RETURN VALUES 669Behavior is undefined if invalid arguments are passed to 670any of the above functions. 671If sufficient resources cannot be allocated for a given 672transaction, 673.Er ENOMEM 674is returned. 675All 676routines that are not of type, 677.Vt void , 678will return 0 on success or an error 679code, as discussed above. 680.Pp 681All 682.Vt void 683routines will succeed if provided with valid arguments. 684.Sh SEE ALSO 685.Xr devclass 9 , 686.Xr device 9 , 687.Xr driver 9 , 688.Xr rman 9 689.Pp 690.Rs 691.%A "Jason R. Thorpe" 692.%T "A Machine-Independent DMA Framework for NetBSD" 693.%J "Proceedings of the Summer 1998 USENIX Technical Conference" 694.%Q "USENIX Association" 695.%D "June 1998" 696.Re 697.Sh HISTORY 698The 699.Nm 700interface first appeared in 701.Nx 1.3 . 702.Pp 703The 704.Nm 705API was adopted from 706.Nx 707for use in the CAM SCSI subsystem. 708The alterations to the original API were aimed to remove the need for 709a 710.Vt bus_dma_segment_t 711array stored in each 712.Vt bus_dmamap_t 713while allowing callers to queue up on scarce resources. 714.Sh AUTHORS 715The 716.Nm 717interface was designed and implemented by 718.An Jason R. Thorpe 719of the Numerical Aerospace Simulation Facility, NASA Ames Research Center. 720Additional input on the 721.Nm 722design was provided by 723.An -nosplit 724.An Chris Demetriou , 725.An Charles Hannum , 726.An Ross Harvey , 727.An Matthew Jacob , 728.An Jonathan Stone , 729and 730.An Matt Thomas . 731.Pp 732This manual page was written by 733.An Hiten Pandya 734and 735.An Justin T. Gibbs . 736