1.\" $NetBSD: bus_dma.9,v 1.44 2007/05/19 14:30:55 wiz Exp $ 2.\" 3.\" Copyright (c) 1996, 1997, 1998, 2001, 2005, 2006 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Jason R. Thorpe of the Numerical Aerospace Simulation Facility, 8.\" NASA Ames Research Center. 9.\" 10.\" Redistribution and use in source and binary forms, with or without 11.\" modification, are permitted provided that the following conditions 12.\" are met: 13.\" 1. Redistributions of source code must retain the above copyright 14.\" notice, this list of conditions and the following disclaimer. 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in the 17.\" documentation and/or other materials provided with the distribution. 18.\" 3. All advertising materials mentioning features or use of this software 19.\" must display the following acknowledgment: 20.\" This product includes software developed by the NetBSD 21.\" Foundation, Inc. and its contributors. 22.\" 4. Neither the name of The NetBSD Foundation nor the names of its 23.\" contributors may be used to endorse or promote products derived 24.\" from this software without specific prior written permission. 25.\" 26.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 27.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 28.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 29.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 30.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 31.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 32.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 33.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 34.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 35.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 36.\" POSSIBILITY OF SUCH DAMAGE. 37.\" 38.Dd March 7, 2007 39.Dt BUS_DMA 9 40.Os 41.Sh NAME 42.Nm bus_dma , 43.Nm bus_dmamap_create , 44.Nm bus_dmamap_destroy , 45.Nm bus_dmamap_load , 46.Nm bus_dmamap_load_mbuf , 47.Nm bus_dmamap_load_uio , 48.Nm bus_dmamap_load_raw , 49.Nm bus_dmamap_unload , 50.Nm bus_dmamap_sync , 51.Nm bus_dmamem_alloc , 52.Nm bus_dmamem_free , 53.Nm bus_dmamem_map , 54.Nm bus_dmamem_unmap , 55.Nm bus_dmamem_mmap , 56.Nm bus_dmatag_subregion , 57.Nm bus_dmatag_destroy 58.Nd Bus and Machine Independent DMA Mapping Interface 59.Sh SYNOPSIS 60.In machine/bus.h 61.Ft int 62.Fn bus_dmamap_create "bus_dma_tag_t tag" "bus_size_t size" "int nsegments" \ 63"bus_size_t maxsegsz" "bus_size_t boundary" "int flags" "bus_dmamap_t *dmamp" 64.Ft void 65.Fn bus_dmamap_destroy "bus_dma_tag_t tag" "bus_dmamap_t dmam" 66.Ft int 67.Fn bus_dmamap_load "bus_dma_tag_t tag" "bus_dmamap_t dmam" "void *buf" \ 68"bus_size_t buflen" "struct lwp *l" "int flags" 69.Ft int 70.Fn bus_dmamap_load_mbuf "bus_dma_tag_t tag" "bus_dmamap_t dmam" \ 71"struct mbuf *chain" "int flags" 72.Ft int 73.Fn bus_dmamap_load_uio "bus_dma_tag_t tag" "bus_dmamap_t dmam" \ 74"struct uio *uio" "int flags" 75.Ft int 76.Fn bus_dmamap_load_raw "bus_dma_tag_t tag" "bus_dmamap_t dmam" \ 77"bus_dma_segment_t *segs" "int nsegs" "bus_size_t size" "int flags" 78.Ft void 79.Fn bus_dmamap_unload "bus_dma_tag_t tag" "bus_dmamap_t dmam" 80.Ft void 81.Fn bus_dmamap_sync "bus_dma_tag_t tag" "bus_dmamap_t dmam" \ 82"bus_addr_t offset" "bus_size_t len" "int ops" 83.Ft int 84.Fn bus_dmamem_alloc "bus_dma_tag_t tag" "bus_size_t size" \ 85"bus_size_t alignment" "bus_size_t boundary" "bus_dma_segment_t *segs" \ 86"int nsegs" "int *rsegs" "int flags" 87.Ft void 88.Fn bus_dmamem_free "bus_dma_tag_t tag" "bus_dma_segment_t *segs" "int nsegs" 89.Ft int 90.Fn bus_dmamem_map "bus_dma_tag_t tag" "bus_dma_segment_t *segs" "int nsegs" \ 91"size_t size" "void **kvap" "int flags" 92.Ft void 93.Fn bus_dmamem_unmap "bus_dma_tag_t tag" "void *kva" "size_t size" 94.Ft paddr_t 95.Fn bus_dmamem_mmap "bus_dma_tag_t tag" "bus_dma_segment_t *segs" \ 96"int nsegs" "off_t off" "int prot" "int flags" 97.Ft int 98.Fn bus_dmatag_subregion "bus_dma_tag_t tag" "bus_addr_t min_addr" \ 99"bus_addr_t max_addr" "bus_dma_tag_t *newtag" "int flags" 100.Ft void 101.Fn bus_dmatag_destroy "bus_dma_tag_t tag" 102.Sh DESCRIPTION 103Provide a bus- and machine-independent "DMA mapping interface." 104.Sh NOTES 105All data structures, function prototypes, and macros will be defined 106by the port-specific header 107.Aq Pa machine/bus.h . 108Note that this document 109assumes the existence of types already defined by the current "bus.h" 110interface. 111.Pp 112Unless otherwise noted, all function calls in this interface may be 113defined as 114.Xr cpp 1 115macros. 116.Sh DATA TYPES 117Individual implementations may name these structures whatever they 118wish, providing that the external representations are: 119.Bl -tag -width compact 120.It Fa bus_dma_tag_t 121A machine-dependent opaque type describing the implementation of 122DMA for a given bus. 123.It Fa bus_dma_segment_t 124A structure with at least the following members: 125.Bd -literal 126 bus_addr_t ds_addr; 127 bus_size_t ds_len; 128.Ed 129.sp 130The structure may have machine-dependent members and arbitrary layout. 131The values in 132.Fa ds_addr 133and 134.Fa ds_len 135are suitable for programming into 136DMA controller address and length registers. 137.It Fa bus_dmamap_t 138A pointer to a structure with at least the following members: 139.Bd -literal 140 bus_size_t dm_maxsegsz; 141 bus_size_t dm_mapsize; 142 int dm_nsegs; 143 bus_dma_segment_t *dm_segs; 144.Ed 145.sp 146The structure may have machine-dependent members and arbitrary layout. 147The 148.Fa dm_maxsegsz 149member indicates the maximum number of bytes that may be transferred by 150any given DMA segment. 151The 152.Fa dm_mapsize 153member indicates the size of the mapping. 154A value of 0 indicates the mapping is invalid. 155The 156.Fa dm_segs 157member may be an array of segments or a pointer to an 158array of segments. 159The 160.Fa dm_nsegs 161member indicates the number of segments in 162.Fa dm_segs . 163.El 164.Sh FUNCTIONS 165.Bl -tag -width compact 166.It Fn bus_dmamap_create "tag" "size" "nsegments" "maxsegsz" "boundary" "flags" "dmamp" 167Allocates a DMA handle and initializes it according to the parameters 168provided. 169Arguments are as follows: 170.Bl -tag -width nsegments -compact 171.It Fa tag 172This is the bus_dma_tag_t passed down from the parent driver via 173.Fa \*[Lt]bus\*[Gt]_attach_args . 174.It Fa size 175This is the maximum DMA transfer that can be mapped by the handle. 176.It Fa nsegments 177Number of segments the device can support in a single DMA transaction. 178This may be the number of scatter-gather descriptors supported by the 179device. 180.It Fa maxsegsz 181The maximum number of bytes that may be transferred by any given DMA 182segment and will be assigned to the 183.Fa dm_maxsegsz 184member. 185.It Fa boundary 186Some DMA controllers are not able to transfer data that crosses a 187particular boundary. 188This argument allows this boundary to be specified. 189The boundary lines begin at 0, and occur every 190.Fa boundary 191bytes. 192Mappings may begin on a boundary line but may not end on or 193cross a boundary line. 194If no boundary condition needs to be observed, a 195.Fa boundary 196argument of 0 should be used. 197.It Fa flags 198Flags are defined as follows: 199.Bl -tag -width BUS_DMA_ALLOCNOW -compact 200.It Dv BUS_DMA_WAITOK 201It is safe to wait (sleep) for resources during this call. 202.It Dv BUS_DMA_NOWAIT 203It is not safe to wait (sleep) for resources during this call. 204.It Dv BUS_DMA_ALLOCNOW 205Perform any resource allocation this handle may need now. 206If this is not specified, the allocation may be deferred to 207.Fn bus_dmamap_load . 208If this flag is specified, 209.Fn bus_dmamap_load 210will not block on resource 211allocation. 212.It Dv BUS_DMA_BUS[1-4] 213These flags are placeholders, and may be used by busses to provide 214bus-dependent functionality. 215.El 216.It Fa dmamp 217This is a pointer to a bus_dmamap_t. 218A DMA map will be allocated and pointed to by 219.Fa dmamp 220upon successful completion of this routine. 221.El 222.Pp 223Behavior is not defined if invalid arguments are passed to 224.Fn bus_dmamap_create . 225.Pp 226Returns 0 on success, or an error code to indicate mode of failure. 227.It Fn bus_dmamap_destroy "tag" "dmam" 228Frees all resources associated with a given DMA handle. 229Arguments are as follows: 230.Bl -tag -width dmam -compact 231.It Fa tag 232This is the bus_dma_tag_t passed down from the parent driver via 233.Fa \*[Lt]bus\*[Gt]_attach_args . 234.It Fa dmam 235The DMA handle to destroy. 236.El 237.Pp 238In the event that the DMA handle contains a valid mapping, 239the mapping will be unloaded via the same mechanism used by 240.Fn bus_dmamap_unload . 241.Pp 242Behavior is not defined if invalid arguments are passed to 243.Fn bus_dmamap_destroy . 244.Pp 245If given valid arguments, 246.Fn bus_dmamap_destroy 247always succeeds. 248.It Fn bus_dmamap_load "tag" "dmam" "buf" "buflen" "l" "flags" 249Loads a DMA handle with mappings for a DMA transfer. 250It assumes that all pages involved in a DMA transfer are wired. 251Arguments are as follows: 252.Bl -tag -width buflen -compact 253.It Fa tag 254This is the bus_dma_tag_t passed down from the parent driver via 255.Fa \*[Lt]bus\*[Gt]_attach_args . 256.It Fa dmam 257The DMA handle with which to map the transfer. 258.It Fa buf 259The buffer to be used for the DMA transfer. 260.It Fa buflen 261The size of the buffer. 262.It Fa l 263Used to indicate the address space in which the buffer is located. 264If 265.Dv NULL , 266the buffer is assumed to be in kernel space. 267Otherwise, the buffer is assumed to be in lwp 268.Fa l Ap s 269address space. 270.It Fa flags 271are defined as follows: 272.Bl -tag -width "BUS_DMA_STREAMING" -compact 273.It Dv BUS_DMA_WAITOK 274It is safe to wait (sleep) for resources during this call. 275.It Dv BUS_DMA_NOWAIT 276It is not safe to wait (sleep) for resources during this call. 277.It Dv BUS_DMA_STREAMING 278By default, the 279.Nm 280API assumes that there is coherency between memory and the device 281performing the DMA transaction. 282Some platforms, however, have special hardware, such as an 283.Dq I/O cache , 284which may improve performance 285of some types of DMA transactions, but which break the assumption 286that there is coherency between memory and the device performing 287the DMA transaction. 288This flag allows the use of this special hardware, provided that 289the device is doing sequential, unidirectional transfers which 290conform to certain alignment and size constraints defined by the 291platform. 292If the platform does not support the feature, or if the buffer being 293loaded into the DMA map does not conform to the constraints required 294for use of the feature, then this flag will be silently ignored. 295Also refer to the use of this flag with the 296.Fn bus_dmamem_alloc 297function. 298.It Dv BUS_DMA_READ 299This is a hint to the machine-dependent back-end that indicates the 300mapping will be used only for a 301.Em "device -\*[Gt] memory" 302transaction. 303The back-end may perform optimizations based on this information. 304.It Dv BUS_DMA_WRITE 305This is a hint to the machine-dependent back-end that indicates the 306mapping will be used only for a 307.Em "memory -\*[Gt] device" 308transaction. 309The back-end may perform optimizations based on this information. 310.It Dv BUS_DMA_BUS[1-4] 311These flags are placeholders, and may be used by busses to 312provide bus-dependent functionality. 313.El 314.El 315.Pp 316As noted above, if a DMA handle is created with 317.Dv BUS_DMA_ALLOCNOW , 318.Fn bus_dmamap_load 319will never block. 320.Pp 321If a call to 322.Fn bus_dmamap_load 323fails, the mapping in 324the DMA handle will be invalid. 325It is the responsibility of the caller to clean up any inconsistent 326device state resulting from incomplete iteration through the uio. 327.Pp 328Behavior is not defined if invalid arguments are passed to 329.Fn bus_dmamap_load . 330.Pp 331Returns 0 on success, or an error code to indicate mode of failure. 332.It Fn bus_dmamap_load_mbuf "tag" "dmam" "chain" "flags" 333This is a variation of 334.Fn bus_dmamap_load 335which maps mbuf chains 336for DMA transfers. 337Mbuf chains are assumed to be in kernel virtual address space. 338.It Fn bus_dmamap_load_uio "tag" "dmam" "uio" "flags" 339This is a variation of 340.Fn bus_dmamap_load 341which maps buffers pointed to by 342.Fa uio 343for DMA transfers. 344Determination if the buffers are in user or kernel virtual address space 345is done internally, according to 346.Fa "uio-\*[Gt]uio_vmspace" . 347See 348.Xr uiomove 9 349for details of the 350.Dv uio 351structure. 352.It Fn bus_dmamap_load_raw "tag" "dmam" "segs" "nsegs" "size" "flags" 353This is a variation of 354.Fn bus_dmamap_load 355which maps buffers 356allocated by 357.Fn bus_dmamem_alloc 358(see below). 359The 360.Fa segs 361argument is an array of bus_dma_segment_t's filled in 362by 363.Fn bus_dmamem_alloc . 364The 365.Fa nsegs 366argument is the number of segments in the array. 367The 368.Fa size 369argument is the size of the DMA transfer. 370.It Fn bus_dmamap_unload "tag" "dmam" 371Deletes the mappings for a given DMA handle. 372Arguments are as follows: 373.Bl -tag -width dmam -compact 374.It Fa tag 375This is the bus_dma_tag_t passed down from the parent driver via 376.Fa \*[Lt]bus\*[Gt]_attach_args . 377.It Fa dmam 378The DMA handle containing the mappings which are to be deleted. 379.El 380.Pp 381If the DMA handle was created with 382.Dv BUS_DMA_ALLOCNOW , 383.Fn bus_dmamap_unload 384will not free the corresponding 385resources which were allocated by 386.Fn bus_dmamap_create . 387This is to ensure that 388.Fn bus_dmamap_load 389will never block 390on resources if the handle was created with 391.Dv BUS_DMA_ALLOCNOW . 392.Pp 393.Fn bus_dmamap_unload 394will not perform any implicit synchronization of DMA buffers. 395This must be done explicitly by 396.Fn bus_dmamap_sync . 397.Pp 398.Fn bus_dmamap_unload 399will restore the 400.Fa dm_maxsegsz 401member to its initial value assigned by 402.Fn bus_dmamap_create . 403.Pp 404Behavior is not defined if invalid arguments are passed to 405.Fn bus_dmamap_unload . 406.Pp 407If given valid arguments, 408.Fn bus_dmamap_unload 409always succeeds. 410.It Fn bus_dmamap_sync "tag" "dmam" "offset" "len" "ops" 411Performs pre- and post-DMA operation cache and/or buffer synchronization. 412Arguments are as follows: 413.Bl -tag -width offset -compact 414.It Fa tag 415This is the bus_dma_tag_t passed down from the parent driver via 416.Fa \*[Lt]bus\*[Gt]_attach_args . 417.It Fa dmam 418The DMA mapping to be synchronized. 419.It Fa offset 420The offset into the DMA mapping to synchronize. 421.It Fa len 422The length of the mapping from 423.Fa offset 424to synchronize. 425.It Fa ops 426One or more synchronization operation to perform. 427The following DMA synchronization operations are defined: 428.Bl -tag -width BUS_DMASYNC_POSTWRITE -compact 429.It Dv BUS_DMASYNC_PREREAD 430Perform any pre-read DMA cache and/or bounce operations. 431.It Dv BUS_DMASYNC_POSTREAD 432Perform any post-read DMA cache and/or bounce operations. 433.It Dv BUS_DMASYNC_PREWRITE 434Perform any pre-write DMA cache and/or bounce operations. 435.It Dv BUS_DMASYNC_POSTWRITE 436Perform any post-write DMA cache and/or bounce operations. 437.El 438.Pp 439More than one operation may performed in a given synchronization call. 440Mixing of 441.Em PRE 442and 443.Em POST 444operations is not allowed, and behavior is undefined if this is attempted. 445.El 446.Pp 447Synchronization operations are expressed from the perspective of 448the host RAM, e.g., a 449.Em "device -\*[Gt] memory" 450operation is a 451.Em READ 452and a 453.Em "memory -\*[Gt] device" 454operation is a 455.Em WRITE . 456.Pp 457.Fn bus_dmamap_sync 458may consult state kept within the DMA map to determine if the memory 459is mapped in a DMA coherent fashion. 460If so, 461.Fn bus_dmamap_sync 462may elect to skip certain expensive operations, such as flushing 463of the data cache. 464See 465.Fn bus_dmamem_map 466for more information on this subject. 467.Pp 468On platforms which implement a weak memory access ordering model, 469.Fn bus_dmamap_sync 470will always cause the appropriate memory barriers to be issued. 471.Pp 472This function exists to ensure that the host and the device have 473a consistent view of a range of DMA memory, before and after 474a DMA operation. 475.Pp 476An example of using 477.Fn bus_dmamap_sync , 478involving multiple read-write use of a single mapping 479might look like this: 480.Bd -literal 481bus_dmamap_load(...); 482 483while (not done) { 484 /* invalidate soon-to-be-stale cache blocks */ 485 bus_dmamap_sync(..., BUS_DMASYNC_PREREAD); 486 487 [ do read DMA ] 488 489 /* copy from bounce */ 490 bus_dmamap_sync(..., BUS_DMASYNC_POSTREAD); 491 492 /* read data now in driver-provided buffer */ 493 494 [ computation ] 495 496 /* data to be written now in driver-provided buffer */ 497 498 /* flush write buffers and writeback, copy to bounce */ 499 bus_dmamap_sync(..., BUS_DMASYNC_PREWRITE); 500 501 [ do write DMA ] 502 503 /* probably a no-op, but provided for consistency */ 504 bus_dmamap_sync(..., BUS_DMASYNC_POSTWRITE); 505} 506 507bus_dmamap_unload(...); 508.Ed 509.Pp 510This function 511.Em must 512be called to synchronize DMA buffers before and after a DMA operation. 513Other 514.Nm 515functions can 516.Em not 517be relied on to do this synchronization implicitly. 518If DMA read and write operations are not preceded and followed by the 519appropriate synchronization operations, behavior is undefined. 520.Pp 521Behavior is not defined if invalid arguments are passed to 522.Fn bus_dmamap_sync . 523.Pp 524If given valid arguments, 525.Fn bus_dmamap_sync 526always succeeds. 527.\" XXX: This does not work with all the arguments. 528.It Fn bus_dmamem_alloc "tag" "size" "alignment" "boundary" "segs" "..." 529Allocates memory that is "DMA safe" for the bus corresponding to the 530given tag. 531.Pp 532The mapping of this memory is machine-dependent (or 533"opaque"); machine-independent code is not to assume that the 534addresses returned are valid in kernel virtual address space, or that 535the addresses returned are system physical addresses. 536The address value returned as part of 537.Fa segs 538can thus not be used to program DMA controller address registers. 539Only the values in the 540.Fa dm_segs 541array of a successfully loaded DMA map (using 542.Fn bus_dmamap_load ) 543can be used for this purpose. 544.Pp 545Allocations will always be rounded to the hardware page size. 546Callers may wish to take advantage of this, and cluster allocation of small 547data structures. 548Arguments are as follows: 549.Bl -tag -width alignment -compact 550.It Fa tag 551This is the bus_dma_tag_t passed down from the parent driver via 552.Fa \*[Lt]bus\*[Gt]_attach_args . 553.It Fa size 554The amount of memory to allocate. 555.It Fa alignment 556Each segment in the allocated memory will be aligned to this value. 557If the alignment is less than a hardware page size, it will be rounded up 558to the hardware page size. 559This value must be a power of two. 560.It Fa boundary 561Each segment in the allocated memory must not cross this boundary 562(relative to zero). 563This value must be a power of two. 564A boundary value less than the size of the allocation is invalid. 565.It Fa segs 566An array of bus_dma_segment_t's, filled in as memory is allocated, 567representing the opaque addresses of the memory chunks. 568.It Fa nsegs 569Specifies the number of segments in 570.Fa segs , 571and this is the maximum number 572of segments that the allocated memory may contain. 573.It Fa rsegs 574Used to return the actual number of segments the memory contains. 575.It Fa flags 576Flags are defined as follows: 577.Bl -tag -width BUS_DMA_STREAMING -compact 578.It Dv BUS_DMA_WAITOK 579It is safe to wait (sleep) for resources during this call. 580.It Dv BUS_DMA_NOWAIT 581It is not safe to wait (sleep) for resources during this call. 582.It Dv BUS_DMA_STREAMING 583Adjusts, if necessary, the size, alignment, and boundary constrains 584to conform to the platform-dependent requirements for the use of the 585.Dv BUS_DMA_STREAMING 586flag with the 587.Fn bus_dmamap_load 588function. 589If the platform does not support the 590.Dv BUS_DMA_STREAMING 591feature, or if the size, alignment, and boundary constraints 592would already satisfy the platform's requirements, this flag 593is silently ignored. 594The 595.Dv BUS_DMA_STREAMING 596flag will never relax the constraints specified in the call. 597.It Dv BUS_DMA_BUS[1-4] 598These flags are placeholders, and may be used by busses to provide 599bus-dependent functionality. 600.El 601.El 602.Pp 603All pages allocated by 604.Fn bus_dmamem_alloc 605will be wired down 606until they are freed by 607.Fn bus_dmamem_free . 608.Pp 609Behavior is undefined if invalid arguments are passed to 610.Fn bus_dmamem_alloc . 611.Pp 612Returns 0 on success, or an error code indicating mode of failure. 613.It Fn bus_dmamem_free "tag" "segs" "nsegs" 614Frees memory previously allocated by 615.Fn bus_dmamem_alloc . 616Any mappings 617will be invalidated. 618Arguments are as follows: 619.Bl -tag -width nsegs -compact 620.It Fa tag 621This is the bus_dma_tag_t passed down from the parent driver via 622.Fa \*[Lt]bus\*[Gt]_attach_args . 623.It Fa segs 624The array of bus_dma_segment_t's filled in by 625.Fn bus_dmamem_alloc . 626.It Fa nsegs 627The number of segments in 628.Fa segs . 629.El 630.Pp 631Behavior is undefined if invalid arguments are passed to 632.Fn bus_dmamem_free . 633.Pp 634If given valid arguments, 635.Fn bus_dmamem_free 636always succeeds. 637.It Fn bus_dmamem_map "tag" "segs" "nsegs" "size" "kvap" "flags" 638Maps memory allocated with 639.Fn bus_dmamem_alloc 640into kernel virtual address space. 641Arguments are as follows: 642.Bl -tag -width flags -compact 643.It Fa tag 644This is the bus_dma_tag_t passed down from the parent driver via 645.Fa \*[Lt]bus\*[Gt]_attach_args . 646.It Fa segs 647The array of bus_dma_segment_t's filled in by 648.Fn bus_dmamem_alloc , 649representing the memory regions to map. 650.It Fa nsegs 651The number of segments in 652.Fa segs . 653.It Fa size 654The size of the mapping. 655.It Fa kvap 656Filled in to specify the kernel virtual address where the memory is mapped. 657.It Fa flags 658Flags are defined as follows: 659.Bl -tag -width BUS_DMA_COHERENT -compact 660.It Dv BUS_DMA_WAITOK 661It is safe to wait (sleep) for resources during this call. 662.It Dv BUS_DMA_NOWAIT 663It is not safe to wait (sleep) for resources during this call. 664.It Dv BUS_DMA_BUS[1-4] 665These flags are placeholders, and may be used by busses to provide 666bus-dependent functionality. 667.It Dv BUS_DMA_COHERENT 668This flag is a 669.Em hint 670to machine-dependent code. 671If possible, map the memory in such a way as it will be DMA coherent. 672This may include mapping the pages into uncached address space or 673setting the cache-inhibit bits in page table entries. 674If DMA coherent mappings are impossible, this flag is silently ignored. 675.Pp 676Later, when this memory is loaded into a DMA map, machine-dependent code 677will take whatever steps are necessary to determine if the memory was 678mapped in a DMA coherent fashion. 679This may include checking if the kernel virtual address lies within 680uncached address space or if the cache-inhibit bits are set in page 681table entries. 682If it is determined that the mapping is DMA coherent, state may be 683placed into the DMA map for use by later calls to 684.Fn bus_dmamap_sync . 685.Pp 686Note that a device driver must not rely on 687.Dv BUS_DMA_COHERENT 688for correct operation. 689All calls to 690.Fn bus_dmamap_sync 691must still be made. 692This flag is provided only as an optimization hint to machine-dependent code. 693.Pp 694Also note that this flag only applies to coherency between the CPU 695and memory. 696Coherency between memory and the device is controlled with a different flag. 697See the description of the 698.Fn bus_dmamap_load 699function. 700.It Dv BUS_DMA_NOCACHE 701This flag is a 702.Em hint 703to machine-dependent code. 704If possible, map the uncached memory. 705This flag may be useful in the case that the memory cache causes unexpected 706behavior of the device. 707.El 708.El 709.Pp 710Behavior is undefined if invalid arguments are passed to 711.Fn bus_dmamem_map . 712.Pp 713Returns 0 on success, or an error code indicating mode of failure. 714.It Fn bus_dmamem_unmap "tag" "kva" "size" 715Unmaps memory previously mapped with 716.Fn bus_dmamem_map , 717freeing the 718kernel virtual address space used by the mapping. 719The arguments are as follows: 720.Bl -tag -width size -compact 721.It Fa tag 722This is the bus_dma_tag_t passed down from the parent driver via 723.Fa \*[Lt]bus\*[Gt]_attach_args . 724.It Fa kva 725The kernel virtual address of the mapped memory. 726.It Fa size 727The size of the mapping. 728.El 729.Pp 730Behavior is undefined if invalid arguments are passed to 731.Fn bus_dmamem_unmap . 732.Pp 733If given valid arguments, 734.Fn bus_dmamem_unmap 735always succeeds. 736.It Fn bus_dmamem_mmap "tag" "segs" "nsegs" "off" "prot" "flags" 737Provides support for user 738.Xr mmap 2 Ap ing 739of DMA-safe memory. 740This function is to be called by a device driver's (*d_mmap)() entry 741point, which is called by the device pager for each page to be mapped. 742The arguments are as follows: 743.Bl -tag -width nsegs -compact 744.It Fa tag 745This is the bus_dma_tag_t passed down from the parent driver via 746.Fa \*[Lt]bus\*[Gt]_attach_args . 747.It Fa segs 748The array of bus_dma_segment_t's filled in by 749.Fn bus_dmamem_alloc , 750representing the memory to be 751.Xr mmap 2 Ap ed . 752.It Fa nsegs 753The number of elements in the 754.Fa segs 755array. 756.It Fa off 757The offset of the page in DMA memory which is to be mapped. 758.It Fa prot 759The protection codes for the mapping. 760.It Fa flags 761Flags are defined as follows: 762.Bl -tag -width BUS_DMA_COHERENT -compact 763.It Dv BUS_DMA_WAITOK 764It is safe to wait (sleep) for resources during this call. 765.It Dv BUS_DMA_NOWAIT 766It is not safe to wait (sleep) for resources during this call. 767.It Dv BUS_DMA_BUS[1-4] 768These flags are placeholders, and may be used by busses to provide 769bus-dependent functionality. 770.It Dv BUS_DMA_COHERENT 771See 772.Fn bus_dmamem_map 773above for a description of this flag. 774.It Dv BUS_DMA_NOCACHE 775See 776.Fn bus_dmamem_map 777above for a description of this flag. 778.El 779.El 780.Pp 781Behavior is undefined if invalid arguments are passed 782to 783.Fn bus_dmamem_mmap . 784.Pp 785Returns -1 to indicate failure. 786Otherwise, returns an opaque value to be interpreted by the device pager. 787.It Fn bus_dmatag_subregion "tag" "min_addr" "max_addr" "newtag" "flags" 788Given a bus_dma_tag_t 789create a new bus_dma_tag_t with a limited bus address space. 790This function should not normally be used, but is useful for devices 791that do not support the full address space of the parent bus. 792The arguments are as follows: 793.Bl -tag -width max_addr -compact 794.It Fa tag 795This is the bus_dma_tag_t to subregion. 796.It Fa min_addr 797The smallest address this new tag can address. 798.It Fa max_addr . 799The largest address this new tag can address. 800.It Fa newtag 801Pointer filled in with the address of the new bus_dma_tag_t. 802.It Fa flags 803Flags are defined as follows: 804.Bl -tag -width BUS_DMA_WAITOK -compact 805.It Dv BUS_DMA_WAITOK 806It is safe to wait (sleep) for resources during this call. 807.It Dv BUS_DMA_NOWAIT 808It is not safe to wait (sleep) for resources during this call. 809.El 810.El 811.It Fn bus_dmatag_destroy "tag" 812Free a tag created by 813.Fn bus_dmatag_subregion . 814.El 815.Sh SEE ALSO 816.Xr bus_space 9 , 817.Xr mb 9 818.Rs 819.%A Jason Thorpe 820.%T "A Machine-Independent DMA Framework for NetBSD" 821.%J "Proceedings of the FREENIX track: 1998 USENIX Annual Technical Conference" 822.%P pp. 1-12 823.%D 1998 824.Re 825.Sh HISTORY 826The 827.Nm 828interface appeared in 829.Nx 1.3 . 830.Sh AUTHORS 831The 832.Nm 833interface was designed and implemented by Jason R. Thorpe of the 834Numerical Aerospace Simulation Facility, NASA Ames Research Center. 835Additional input on the 836.Nm 837design was provided by Chris Demetriou, Charles Hannum, Ross Harvey, 838Matthew Jacob, Jonathan Stone, and Matt Thomas. 839