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