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.6 2006/02/26 09:07:35 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_POSTREAD 261Perform any synchronization required after DMA read operations, but prior 262to CPU access of the memory. 263.It Dv BUS_DMASYNC_POSTWRITE 264Perform any synchronization required after DMA write operations, but prior 265to CPU access of the memory. 266.El 267.El 268.sp 269.Sh FUNCTIONS 270.Bl -tag -width compact 271.It Fn bus_dma_tag_create "parent" "alignment" "boundary" "lowaddr" \ 272"highaddr" "*filtfunc" "*filtfuncarg" "maxsize" "nsegments" "maxsegsz" \ 273"flags" "*dmat" 274Allocates a device specific DMA tag, and initializes it according to 275the arguments provided: 276.Bl -tag -width *filtfuncarg -compact 277.It Fa parent 278Indicates restrictions between the parent bridge, CPU memory, and the 279device. 280May be NULL, if no DMA restrictions are to be inherited. 281.It Fa alignment 282Alignment constraint, in bytes, of any mappings created using this tag. 283The alignment must be a power of 2. 284Hardware that can DMA starting at any address would specify 285.Em 1 286for byte alignment. 287Hardware requiring DMA transfers to start on a multiple of 4K 288would specify 289.Em 4096. 290.It Fa boundary 291Boundary constraint, in bytes, of the target DMA memory region. 292The boundary indicates the set of addresses, all multiples of the 293boundary argument, that cannot be crossed by a single 294.Vt bus_dma_segment_t . 295The boundary must be either a power of 2 or 0. 296.Ql 0 297indicates that there are no boundary restrictions. 298.It Fa lowaddr 299.It Fa highaddr 300Bounds of the window of bus address space that 301.Em cannot 302be directly accessed by the device. 303The window contains all address greater than lowaddr and 304less than or equal to highaddr. 305For example, a device incapable of DMA above 4GB, would specify 306a highaddr of 307.Dv BUS_SPACE_MAXADDR 308and a lowaddr of 309.Dv BUS_SPACE_MAXADDR_32BIT . 310Similarly a device that can only dma to addresses bellow 16MB would 311specify a highaddr of 312.Dv BUS_SPACE_MAXADDR 313and a lowaddr of 314.Dv BUS_SPACE_MAXADDR_24BIT . 315Some implementations requires that some region of device visible 316address space, overlapping available host memory, be outside the 317window. 318This area of 319.Ql safe memory 320is used to bounce requests that would otherwise conflict with 321the exclusion window. 322.It Fa filtfunc 323Optional filter function (may be NULL) to be called for any attempt to 324map memory into the window described by 325.Fa lowaddr 326and 327.Fa highaddr. 328A filter function is only required when the single window described 329by 330.Fa lowaddr 331and 332.Fa highaddr 333cannot adequately describe the constraints of the device. 334The filter function will be called for every machine page 335that overlaps the exclusion window. 336.It Fa filtfuncarg 337Argument passed to all calls to the filter function for this tag. 338May be NULL. 339.It Fa maxsize 340Maximum size, in bytes, of the sum of all segment lengths in a given 341DMA mapping associated with this tag. 342.It Fa nsegments 343Number of discontinuities (scatter/gather segments) allowed 344in a DMA mapped region. 345If there is no restriction, 346.Dv BUS_SPACE_UNRESTRICTED 347may be specified. 348.It Fa maxsegsz 349Maximum size, in bytes, of a segment in any DMA mapped region associated 350with 351.Fa dmat . 352.It Fa flags 353Are as follows: 354.Bl -tag -width "BUS_DMA_ALLOCNOW" -compact 355.It Dv BUS_DMA_ALLOCNOW 356Allocate the resources necessary to guarantee that all map load 357operations associated with this tag will not block. 358If sufficient resources are not available, 359.Er ENOMEM 360is returned. 361.El 362.It Fa dmat 363Pointer to a bus_dma_tag_t where the resulting DMA tag will 364be stored. 365.El 366.Pp 367Returns 368.Er ENOMEM 369if sufficient memory is not available for tag creation 370or allocating mapping resources. 371.It Fn bus_dma_tag_destroy "dmat" 372Deallocate the DMA tag 373.Fa dmat 374that was created by 375.Fn bus_dma_tag_create . 376.Pp 377Returns 378.Er EBUSY 379if any DMA maps remain associated with 380.Fa dmat 381or 382.Ql 0 383on success. 384.It Fn bus_dmamap_create "dmat" "flags" "*mapp" 385Allocates and initializes a DMA map. 386Arguments are as follows: 387.Bl -tag -width nsegments -compact 388.It Fa dmat 389DMA tag. 390.It Fa flags 391The value of this argument is currently undefined and should be 392specified as 393.Ql 0 . 394.It Fa mapp 395Pointer to a 396.Vt bus_dmamap_t 397where the resulting DMA map will be stored. 398.El 399.Pp 400Returns 401.Er ENOMEM 402if sufficient memory is not available for creating the 403map or allocating mapping resources. 404.It Fn bus_dmamap_destroy "dmat" "map" 405Frees all resources associated with a given DMA map. 406Arguments are as follows: 407.Bl -tag -width dmat -compact 408.It Fa dmat 409DMA tag used to allocate 410.Fa map . 411.It Fa map 412The DMA map to destroy. 413.El 414.Pp 415Returns 416.Er EBUSY 417if a mapping is still active for 418.Fa map . 419.It Fn bus_dmamap_load "dmat" "map" "buf" "buflen" "*callback" "..." 420Creates a mapping in device visible address space of 421.Fa buflen 422bytes of 423.Fa buf , 424associated with the DMA map 425.Fa map. 426Arguments are as follows: 427.Bl -tag -width buflen -compact 428.It Fa dmat 429DMA tag used to allocate 430.Fa map. 431.It Fa map 432A DMA map without a currently active mapping. 433.It Fa buf 434A kernel virtual address pointer to a contiguous (in KVA) buffer, to be 435mapped into device visible address space. 436.It Fa buflen 437The size of the buffer. 438.It Fa callback Fa callback_arg 439The callback function, and its argument. 440.It Fa flags 441The value of this argument is currently undefined, and should be 442specified as 443.Ql 0 . 444.El 445.Pp 446Return values to the caller are as follows: 447.Bl -tag -width EINPROGRESS -compact 448.It 0 449The callback has been called and completed. 450The status of the mapping has been delivered to the callback. 451.It Er EINPROGRESS 452The mapping has been deferred for lack of resources. 453The callback will be called as soon as resources are available. 454Callbacks are serviced in FIFO order. 455DMA maps created from DMA tags that are allocated with 456the 457.Dv BUS_DMA_ALLOCNOW 458flag will never return this status for a load operation. 459.It Er EINVAL 460The load request was invalid. 461The callback has not, and will not be called. 462This error value may indicate that 463.Fa dmat , 464.Fa map , 465.Fa buf , 466or 467.Fa callback 468were invalid, or 469.Fa buslen 470was larger than the 471.Fa maxsize 472argument used to create the dma tag 473.Fa dmat . 474.El 475.Pp 476When the callback is called, it is presented with an error value 477indicating the disposition of the mapping. 478Error may be one of the following: 479.Bl -tag -width EINPROGRESS -compact 480.It 0 481The mapping was successful and the 482.Fa dm_segs 483callback argument contains an array of 484.Vt bus_dma_segment_t 485elements describing the mapping. 486This array is only valid during the scope of the callback function. 487.It Er EFBIG 488A mapping could not be achieved within the segment constraints provided 489in the tag even though the requested allocation size was less than maxsize. 490.El 491.It Fn bus_dmamap_load_mbuf "dmat" "map" "mbuf" "callback2" "callback_arg" \ 492"flags" 493This is a variation of 494.Fn bus_dmamap_load 495which maps mbuf chains 496for DMA transfers. 497A 498.Vt bus_size_t 499argument is also passed to the callback routine, which 500contains the mbuf chain's packet header length. 501.Pp 502Mbuf chains are assumed to be in kernel virtual address space. 503.Pp 504Returns 505.Er EINVAL 506if the size of the mbuf chain exceeds the maximum limit of the 507DMA tag. 508.It Fn bus_dmamap_load_uio "dmat" "map" "uio" "callback2" "callback_arg" "flags" 509This is a variation of 510.Fn bus_dmamap_load 511which maps buffers pointed to by 512.Fa uio 513for DMA transfers. 514A 515.Vt bus_size_t 516argument is also passed to the callback routine, which contains the size of 517.Fa uio , 518i.e. 519.Fa uio->uio_resid . 520.Pp 521If 522.Fa uio->uio_segflg 523is 524.Dv UIO_USERSPACE , 525then it is assumed that the buffer, 526.Fa uio 527is in 528.Fa "uio->uio_td->td_proc" Ns 's 529address space. 530User space memory must be in-core and wired prior to attempting a map 531load operation. 532.It Fn bus_dmamap_unload "dmat" "map" 533Unloads a DMA map. 534Arguments are as follows: 535.Bl -tag -width dmam -compact 536.It Fa dmat 537DMA tag used to allocate 538.Fa map . 539.It Fa map 540The DMA map that is to be unloaded. 541.El 542.Pp 543.Fn bus_dmamap_unload 544will not perform any implicit synchronization of DMA buffers. 545This must be done explicitly by a call to 546.Fn bus_dmamap_sync 547prior to unloading the map. 548.It Fn bus_dmamap_sync "dmat" "map" "op" 549Performs synchronization of a device visible mapping with the CPU visible 550memory referenced by that mapping. 551Arguments are as follows: 552.Bl -tag -width dmat -compact 553.It Fa dmat 554DMA tag used to allocate 555.Fa map . 556.It Fa map 557The DMA mapping to be synchronized. 558.It Fa op 559Type of synchronization operation to perform. 560See the definition of 561.Vt bus_dmasync_op_t 562for a description of the acceptable values for 563.Fa op . 564.El 565.Pp 566.Fn bus_dmamap_sync 567is the method used to ensure that CPU and device DMA access to shared 568memory is coherent. 569For example, the CPU might be used to setup the contents of a buffer 570that is to be DMA'ed into a device. 571To ensure that the data are visible via the device's mapping of that 572memory, the buffer must be loaded and a dma sync operation of 573.Dv BUS_DMASYNC_PREREAD 574must be performed. 575Additional sync operations must be performed after every CPU write 576to this memory if additional DMA reads are to be performed. 577Conversely, for the DMA write case, the buffer must be loaded, 578and a dma sync operation of 579.Dv BUS_DMASYNC_PREWRITE 580must be performed. 581The CPU will only be able to see the results of this DMA write 582once the DMA has completed and a 583.Dv BUS_DMASYNC_POSTWRITE 584operation has been performed. 585.Pp 586If DMA read and write operations are not preceded and followed by the 587appropriate synchronization operations, behavior is undefined. 588.It Fn bus_dmamem_alloc "dmat" "**vaddr" "flags" "mapp" 589Allocates memory that is mapped into KVA at the address returned 590in 591.Fa vaddr 592that is permanently loaded into the newly created 593.Vt bus_dmamap_t 594returned via 595.Fa mapp . 596Arguments are as follows: 597.Bl -tag -width alignment -compact 598.It Fa dmat 599DMA tag describing the constraints of the DMA mapping. 600.It Fa vaddr 601Pointer to a pointer that will hold the returned KVA mapping of 602the allocated region. 603.It Fa flags 604Flags are defined as follows: 605.Bl -tag -width BUS_DMA_NOWAIT -compact 606.It Dv BUS_DMA_WAITOK 607The routine can safely wait (sleep) for resources. 608.It Dv BUS_DMA_NOWAIT 609The routine is not allowed to wait for resources. 610If resources are not available, 611.Er ENOMEM 612is returned. 613.It Dv BUS_DMA_COHERENT 614Attempt to map this memory such that cache sync operations are 615as cheap as possible. 616This flag is typically set on memory that will be accessed by both 617a CPU and a DMA engine, frequently. 618Use of this flag does not remove the requirement of using 619bus_dmamap_sync, but it may reduce the cost of performing 620these operations. 621.It Dv BUS_DMA_ZERO 622Causes the allocated memory to be set to all zeros. 623.El 624.It Fa mapp 625Pointer to storage for the returned DMA map. 626.El 627.Pp 628The size of memory to be allocated is 629.Fa maxsize 630as specified in 631.Fa dmat . 632.Pp 633The current implementation of 634.Fn bus_dmamem_alloc 635will allocate all requests as a single segment. 636.Pp 637Although no explicit loading is required to access the memory 638referenced by the returned map, the synchronization requirements 639as described in the 640.Fn bus_dmamap_sync 641section still apply. 642.Pp 643Returns 644.Er ENOMEM 645if sufficient memory is not available for completing 646the operation. 647.It Fn bus_dmamem_free "dmat" "*vaddr" "map" 648Frees memory previously allocated by 649.Fn bus_dmamem_alloc . 650Any mappings 651will be invalidated. 652Arguments are as follows: 653.Bl -tag -width vaddr -compact 654.It Fa dmat 655DMA tag. 656.It Fa vaddr 657Kernel virtual address of the memory. 658.It Fa map 659DMA map to be invalidated. 660.El 661.El 662.Sh RETURN VALUES 663Behavior is undefined if invalid arguments are passed to 664any of the above functions. 665If sufficient resources cannot be allocated for a given 666transaction, 667.Er ENOMEM 668is returned. 669All 670routines that are not of type, 671.Vt void , 672will return 0 on success or an error 673code, as discussed above. 674.Pp 675All 676.Vt void 677routines will succeed if provided with valid arguments. 678.Sh SEE ALSO 679.Xr devclass 9 , 680.Xr device 9 , 681.Xr driver 9 , 682.Xr rman 9 683.Pp 684.Rs 685.%A "Jason R. Thorpe" 686.%T "A Machine-Independent DMA Framework for NetBSD" 687.%J "Proceedings of the Summer 1998 USENIX Technical Conference" 688.%Q "USENIX Association" 689.%D "June 1998" 690.Re 691.Sh HISTORY 692The 693.Nm 694interface first appeared in 695.Nx 1.3 . 696.Pp 697The 698.Nm 699API was adopted from 700.Nx 701for use in the CAM SCSI subsystem. 702The alterations to the original API were aimed to remove the need for 703a 704.Vt bus_dma_segment_t 705array stored in each 706.Vt bus_dmamap_t 707while allowing callers to queue up on scarce resources. 708.Sh AUTHORS 709The 710.Nm 711interface was designed and implemented by 712.An Jason R. Thorpe 713of the Numerical Aerospace Simulation Facility, NASA Ames Research Center. 714Additional input on the 715.Nm 716design was provided by 717.An -nosplit 718.An Chris Demetriou , 719.An Charles Hannum , 720.An Ross Harvey , 721.An Matthew Jacob , 722.An Jonathan Stone , 723and 724.An Matt Thomas . 725.Pp 726This manual page was written by 727.An Hiten Pandya 728and 729.An Justin T. Gibbs . 730