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