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.\" 72.Dd January 11, 2010 73.Dt BUS_DMA 9 74.Os 75.Sh NAME 76.Nm bus_dma , 77.Nm bus_dma_tag_create , 78.Nm bus_dma_tag_destroy , 79.Nm bus_dmamap_create , 80.Nm bus_dmamap_destroy , 81.Nm bus_dmamap_load , 82.Nm bus_dmamap_load_mbuf , 83.Nm bus_dmamap_load_mbuf_segment , 84.Nm bus_dmamap_load_mbuf_defrag , 85.Nm bus_dmamap_load_uio , 86.Nm bus_dmamap_unload , 87.Nm bus_dmamap_sync , 88.Nm bus_dmamem_alloc , 89.Nm bus_dmamem_coherent , 90.Nm bus_dmamem_coherent_any , 91.Nm bus_dmamem_free 92.Nd Bus and Machine Independent DMA Mapping Interface 93.Sh SYNOPSIS 94.In sys/bus.h 95.Ft int 96.Fn bus_dma_tag_create "bus_dma_tag_t parent" "bus_size_t alignment" \ 97"bus_size_t boundary" "bus_addr_t lowaddr" "bus_addr_t highaddr" \ 98"bus_dma_filter_t *filtfunc" "void *filtfuncarg" "bus_size_t maxsize" \ 99"int nsegments" "bus_size_t maxsegsz" "int flags" "bus_dma_tag_t *dmat" 100.Ft int 101.Fn bus_dma_tag_destroy "bus_dma_tag_t dmat" 102.Ft int 103.Fn bus_dmamap_create "bus_dma_tag_t dmat" "int flags" "bus_dmamap_t *mapp" 104.Ft int 105.Fn bus_dmamap_destroy "bus_dma_tag_t dmat" "bus_dmamap_t map" 106.Ft int 107.Fn bus_dmamap_load "bus_dma_tag_t dmat" "bus_dmamap_t map" "void *buf" \ 108"bus_size_t buflen" "bus_dmamap_callback_t *callback" "void *callback_arg" \ 109"int flags" 110.Ft int 111.Fn bus_dmamap_load_mbuf "bus_dma_tag_t dmat" "bus_dmamap_t map" \ 112"struct mbuf *mbuf" "bus_dmamap_callback2_t *callback" "void *callback_arg" \ 113"int flags" 114.Ft int 115.Fn bus_dmamap_load_mbuf_segment "bus_dma_tag_t dmat" "bus_dmamap_t map" \ 116"struct mbuf *mbuf" "bus_dma_segment_t *segs" "int maxsegs" "int *nsegs" \ 117"int flags" 118.Ft int 119.Fn bus_dmamap_load_mbuf_defrag "bus_dma_tag_t dmat" "bus_dmamap_t map" \ 120"struct mbuf **mbuf" "bus_dma_segment_t *segs" "int maxsegs" "int *nsegs" \ 121"int flags" 122.Ft int 123.Fn bus_dmamap_load_uio "bus_dma_tag_t dmat" "bus_dmamap_t map" \ 124"struct uio *uio" "bus_dmamap_callback2_t *callback" "void *callback_arg" \ 125"int flags" 126.Ft int 127.Fn bus_dmamem_alloc "bus_dma_tag_t dmat" "void **vaddr" \ 128"int flags" "bus_dmamap_t *mapp" 129.Ft int 130.Fn bus_dmamem_coherent "bus_dma_tag_t parent" "bus_size_t alignment" \ 131"bus_size_t boundary" "bus_addr_t lowaddr" "bus_addr_t highaddr" \ 132"bus_size_t maxsize" "int flags" "bus_dmamem_t *dmem" 133.Ft void * 134.Fn bus_dmamem_coherent_any "bus_dma_tag_t parent" "bus_size_t alignment" \ 135"bus_size_t maxsize" "int flags" "bus_dma_tag_t *dtag" "bus_dmamap_t *dmap" \ 136"bus_addr_t *busaddr" 137.Ft void 138.Fn bus_dmamap_unload "bus_dma_tag_t dmat" "bus_dmamap_t map" 139.Ft void 140.Fn bus_dmamap_sync "bus_dma_tag_t dmat" "bus_dmamap_t map" \ 141"bus_dmasync_op_t op" 142.Ft void 143.Fn bus_dmamem_free "bus_dma_tag_t dmat" "void *vaddr" \ 144"bus_dmamap_t map" 145.Sh DESCRIPTION 146Direct Memory Access (DMA) is a method of transferring data 147without involving the CPU, thus providing higher performance. 148A DMA transaction can be achieved between device to memory, 149device to device, or memory to memory. 150.Pp 151The 152.Nm 153API is a bus, device, and machine-independent (MI) interface to 154DMA mechanisms. 155It provides the client with flexibility and simplicity by 156abstracting machine dependent issues like setting up 157DMA mappings, handling cache issues, bus specific features 158and limitations. 159.Sh STRUCTURES AND TYPES 160.Bl -tag -width compact 161.It Vt bus_dma_tag_t 162A machine-dependent (MD) opaque type that describes the 163characteristics of DMA transactions. 164DMA tags are organized into a hierarchy, with each child 165tag inheriting the restrictions of its parent. 166This allows all devices along the path of DMA transactions 167to contribute to the constraints of those transactions. 168.It Vt bus_dma_filter_t 169Client specified address filter having the format: 170.Bl -tag -width compact 171.It Ft int 172.Fn "client_filter" "void *filtarg" "bus_addr_t testaddr" 173.El 174.sp 175Address filters can be specified during tag creation to allow 176for devices who's DMA address restrictions cannot be specified 177by a single window. 178The 179.Fa filtarg 180is client specified during tag creation to be passed to all 181invocations of the callback. 182The 183.Fa testaddr 184argument contains a potential starting address of a DMA mapping. 185The filter function operates on the set of addresses from 186.Fa testaddr 187to 188.Ql trunc_page(testaddr) + PAGE_SIZE - 1 , 189inclusive. 190The filter function should return zero for any mapping in this range 191that can be accommodated by the device and non-zero otherwise. 192.It Vt bus_dma_segment_t 193A machine-dependent type that describes individual 194DMA segments. 195.Bd -literal 196 bus_addr_t ds_addr; 197 bus_size_t ds_len; 198.Ed 199.sp 200The 201.Fa ds_addr 202field contains the device visible address of the DMA segment, and 203.Fa ds_len 204contains the length of the DMA segment. 205Although the DMA segments returned by a mapping call will adhere to 206all restrictions necessary for a successful DMA operation, some conversion 207(e.g. a conversion from host byte order to the device's byte order) is 208almost always required when presenting segment information to the device. 209.It Vt bus_dmamap_t 210A machine-dependent opaque type describing an individual mapping. 211Multiple DMA maps can be associated with one DMA tag. 212.It Vt bus_dmamem_t 213A machine-dependent type that describes DMA memory created by 214.Fn bus_dmamem_coherent . 215.Bd -literal 216 bus_dma_tag_t dmem_tag; 217 bus_dmamap_t dmem_map; 218 void *dmem_addr; 219 bus_addr_t dmem_busaddr; 220.Ed 221.sp 222The 223.Fa dmem_tag 224field contains the DMA tag of the DMA memory and 225.Fa dmem_map 226field contains the DMA map of the DMA memory. 227The 228.Fa dmem_addr 229field points to the allocated DMA memory in kernel virtual address space. 230The 231.Fa dmem_busaddr 232field contains the device visible address of the DMA memory. 233.It Vt bus_dmamap_callback_t 234Client specified callback for receiving mapping information resulting from 235the load of a 236.Vt bus_dmamap_t 237via 238.Fn bus_dmamap_load . 239Callbacks are of the format: 240.Bl -tag -width compact 241.It Ft void 242.Fn "client_callback" "void *callback_arg" "bus_dma_segment_t *segs" \ 243"int nseg" "int error" 244.El 245.sp 246The 247.Fa callback_arg 248is the callback argument passed to dmamap load functions. 249The 250.Fa segs 251and 252.Fa nseg 253parameters describe an array of 254.Vt bus_dma_segment_t 255structures that represent the mapping. 256This array is only valid within the scope of the callback function. 257The success or failure of the mapping is indicated by the 258.Fa error 259parameter. 260More information on the use of callbacks can be found in the 261description of the individual dmamap load functions. 262.It Vt bus_dmamap_callback2_t 263Client specified callback for receiving mapping information resulting from 264the load of a 265.Vt bus_dmamap_t 266via 267.Fn bus_dmamap_load_uio 268or 269.Fn bus_dmamap_load_mbuf . 270.sp 271Callback2s are of the format: 272.Bl -tag -width compact 273.It Ft void 274.Fn "client_callback2" "void *callback_arg" "bus_dma_segment_t *segs" \ 275"int nseg" "bus_size_t mapsize" "int error" 276.El 277.sp 278Callback2's behavior is the same as 279.Vt bus_dmamap_callback_t 280with the addition that the length of the data mapped is provided via 281.Fa mapsize . 282.It Vt bus_dmasync_op_t 283Memory synchronization operation specifier. 284Bus DMA requires explicit synchronization of memory with it's device 285visible mapping in order to guarantee memory coherency. 286The 287.Vt bus_dmasync_op_t 288allows the type of DMA operation that will be or has been performed 289to be communicated to the system so that the correct coherency measures 290are taken. 291All operations specified below are performed from the DMA engine's 292point of view: 293.Bl -tag -width BUS_DMASYNC_POSTWRITE 294.It Dv BUS_DMASYNC_PREREAD 295Perform any synchronization required after an update of memory by the CPU 296but prior to DMA read operations. 297.It Dv BUS_DMASYNC_PREWRITE 298Perform any synchronization required after an update of memory by the CPU 299but prior to DMA write operations. 300.It Dv BUS_DMASYNC_POSTREAD 301Perform any synchronization required after DMA read operations, but prior 302to CPU access of the memory. 303.It Dv BUS_DMASYNC_POSTWRITE 304Perform any synchronization required after DMA write operations, but prior 305to CPU access of the memory. 306.El 307.El 308.sp 309.Sh FUNCTIONS 310.Bl -tag -width compact 311.It Fn bus_dma_tag_create "parent" "alignment" "boundary" "lowaddr" \ 312"highaddr" "*filtfunc" "*filtfuncarg" "maxsize" "nsegments" "maxsegsz" \ 313"flags" "*dmat" 314Allocates a device specific DMA tag, and initializes it according to 315the arguments provided: 316.Bl -tag -width *filtfuncarg -compact 317.It Fa parent 318Indicates restrictions between the parent bridge, CPU memory, and the 319device. 320May be NULL, if no DMA restrictions are to be inherited. 321.It Fa alignment 322Alignment constraint, in bytes, of any mappings created using this tag. 323The alignment must be a power of 2. 324Hardware that can DMA starting at any address would specify 325.Em 1 326for byte alignment. 327Hardware requiring DMA transfers to start on a multiple of 4K 328would specify 329.Em 4096 . 330.It Fa boundary 331Boundary constraint, in bytes, of the target DMA memory region. 332The boundary indicates the set of addresses, all multiples of the 333boundary argument, that cannot be crossed by a single 334.Vt bus_dma_segment_t . 335The boundary must be either a power of 2 or 0. 336.Ql 0 337indicates that there are no boundary restrictions. 338.It Fa lowaddr 339.It Fa highaddr 340Bounds of the window of bus address space that 341.Em cannot 342be directly accessed by the device. 343The window contains all address greater than lowaddr and 344less than or equal to highaddr. 345For example, a device incapable of DMA above 4GB, would specify 346a highaddr of 347.Dv BUS_SPACE_MAXADDR 348and a lowaddr of 349.Dv BUS_SPACE_MAXADDR_32BIT . 350Similarly a device that can only dma to addresses bellow 16MB would 351specify a highaddr of 352.Dv BUS_SPACE_MAXADDR 353and a lowaddr of 354.Dv BUS_SPACE_MAXADDR_24BIT . 355Some implementations requires that some region of device visible 356address space, overlapping available host memory, be outside the 357window. 358This area of 359.Ql safe memory 360is used to bounce requests that would otherwise conflict with 361the exclusion window. 362.It Fa filtfunc 363Optional filter function (may be NULL) to be called for any attempt to 364map memory into the window described by 365.Fa lowaddr 366and 367.Fa highaddr . 368A filter function is only required when the single window described 369by 370.Fa lowaddr 371and 372.Fa highaddr 373cannot adequately describe the constraints of the device. 374The filter function will be called for every machine page 375that overlaps the exclusion window. 376.It Fa filtfuncarg 377Argument passed to all calls to the filter function for this tag. 378May be NULL. 379.It Fa maxsize 380Maximum size, in bytes, of the sum of all segment lengths in a given 381DMA mapping associated with this tag. 382.It Fa nsegments 383Number of discontinuities (scatter/gather segments) allowed 384in a DMA mapped region. 385If there is no restriction, 386.Dv BUS_SPACE_UNRESTRICTED 387may be specified for the tag intended to be used as the parent. 388.Dv BUS_SPACE_UNRESTRICTED 389must not be specified for the tags 390which will be used to create maps. 391For tags which will be used to create maps, 392this argument must be less than 16384 on x86_64. 393.It Fa maxsegsz 394Maximum size, in bytes, of a segment in any DMA mapped region associated 395with 396.Fa dmat . 397.It Fa flags 398Are as follows: 399.Bl -tag -width ".Dv BUS_DMA_PRIVBZONE" -compact 400.It Dv BUS_DMA_ALLOCNOW 401Allocate the minimum resources necessary to guarantee that all map load 402operations associated with this tag may not block. 403If sufficient resources are not available, 404.Er ENOMEM 405is returned. 406.It Dv BUS_DMA_WAITOK 407Indicates that it is OK to wait for resources. 408However, 409unlike 410.Xr kmalloc 9 , 411it is not guaranteed that the resource allocation will succeed. 412This flag is the default one, 413if 414.Dv BUS_DMA_NOWAIT 415is not supplied. 416.It Dv BUS_DMA_NOWAIT 417If the resource allocation request cannot be immediately fulfilled, 418.Er ENOMEM 419is returned. 420.It Dv BUS_DMA_ONEBPAGE 421Allocte one bounce page at most, 422even if the 423.Fa maxsize 424indicates that multiple bounce pages are needed. 425.It Dv BUS_DMA_ALIGNED 426Indicates that all memory to be loaded into the DMA maps associated 427with this DMA tag is properly aligned according to 428.Fa alignment 429constraint. 430No resources, 431e.g. bounce pages, 432will be allocated due to the 433.Fa alignment 434constraint. 435If unaligned memory was loaded into the DMA maps associated with this DMA tag, 436system will panic. 437.It Dv BUS_DMA_PRIVBZONE 438Uses a private bounce zone instead of a shared one. 439A private bounce zone will vanish if the DMA tag is destroyed. 440.It Dv BUS_DMA_ALLOCALL 441Allocate all required resources (mainly the bounce buffer). 442If any allocation fails, 443.Fn bus_dma_tag_create 444fails. 445.It Dv BUS_DMA_PROTECTED 446All of the functions called with the DMA tag are already protected by the 447caller, so the 448.Nm 449code need not protect the internal data structures. 450.El 451.It Fa dmat 452Pointer to a bus_dma_tag_t where the resulting DMA tag will 453be stored. 454.El 455.Pp 456Returns 457.Er ENOMEM 458if sufficient memory is not available for tag creation 459or allocating mapping resources. 460.It Fn bus_dma_tag_destroy "dmat" 461Deallocate the DMA tag 462.Fa dmat 463that was created by 464.Fn bus_dma_tag_create . 465.Pp 466Returns 467.Er EBUSY 468if any DMA maps remain associated with 469.Fa dmat 470or 471.Ql 0 472on success. 473.It Fn bus_dmamap_create "dmat" "flags" "*mapp" 474Allocates and initializes a DMA map. 475Arguments are as follows: 476.Bl -tag -width nsegments -compact 477.It Fa dmat 478DMA tag. 479.It Fa flags 480Are as follows: 481.Bl -tag -width ".Dv BUS_DMA_ONEBPAGE" -compact 482.It Dv BUS_DMA_WAITOK 483Indicates that it is OK to wait for resources. 484However, 485unlike 486.Xr kmalloc 9 , 487it is not guaranteed that the resource allocation will succeed. 488This flag is the default one, 489if 490.Dv BUS_DMA_NOWAIT 491is not supplied. 492.It Dv BUS_DMA_NOWAIT 493If the resource allocation request cannot be immediately fulfilled, 494.Er ENOMEM 495is returned. 496.It Dv BUS_DMA_ONEBPAGE 497Allocte one bounce page at most, 498even if the 499.Fa maxsize 500used to create the 501.Fa dmat 502indicates that multiple bounce pages are needed. 503.El 504.It Fa mapp 505Pointer to a 506.Vt bus_dmamap_t 507where the resulting DMA map will be stored. 508.El 509.Pp 510Returns 511.Er ENOMEM 512if sufficient memory is not available for creating the 513map or allocating mapping resources. 514.It Fn bus_dmamap_destroy "dmat" "map" 515Frees all resources associated with a given DMA map. 516Arguments are as follows: 517.Bl -tag -width dmat -compact 518.It Fa dmat 519DMA tag used to allocate 520.Fa map . 521.It Fa map 522The DMA map to destroy. 523.El 524.Pp 525Returns 526.Er EBUSY 527if a mapping is still active for 528.Fa map . 529.It Fn bus_dmamap_load "dmat" "map" "buf" "buflen" "*callback" "..." 530Creates a mapping in device visible address space of 531.Fa buflen 532bytes of 533.Fa buf , 534associated with the DMA map 535.Fa map . 536Arguments are as follows: 537.Bl -tag -width buflen -compact 538.It Fa dmat 539DMA tag used to allocate 540.Fa map . 541.It Fa map 542A DMA map without a currently active mapping. 543.It Fa buf 544A kernel virtual address pointer to a contiguous (in KVA) buffer, to be 545mapped into device visible address space. 546.It Fa buflen 547The size of the buffer. 548.It Fa callback Fa callback_arg 549The callback function, and its argument. 550.It Fa flags 551The value of this argument is currently undefined, and should be 552specified as 553.Ql 0 . 554.El 555.Pp 556Return values to the caller are as follows: 557.Bl -tag -width ".Er EINPROGRESS" -compact 558.It 0 559The callback has been called and completed. 560The status of the mapping has been delivered to the callback. 561.It Er EINPROGRESS 562The mapping has been deferred for lack of resources. 563The callback will be called as soon as resources are available. 564Callbacks are serviced in FIFO order. 565DMA maps created from DMA tags that are allocated with 566the 567.Dv BUS_DMA_ALLOCNOW 568flag will never return this status for a load operation. 569.It Er EINVAL 570The load request was invalid. 571The callback has not, and will not be called. 572This error value may indicate that 573.Fa dmat , 574.Fa map , 575.Fa buf , 576or 577.Fa callback 578were invalid, or 579.Fa buslen 580was larger than the 581.Fa maxsize 582argument used to create the dma tag 583.Fa dmat . 584.El 585.Pp 586When the callback is called, it is presented with an error value 587indicating the disposition of the mapping. 588Error may be one of the following: 589.Bl -tag -width ".Er EINPROGRESS" -compact 590.It 0 591The mapping was successful and the 592.Fa dm_segs 593callback argument contains an array of 594.Vt bus_dma_segment_t 595elements describing the mapping. 596This array is only valid during the scope of the callback function. 597.It Er EFBIG 598A mapping could not be achieved within the segment constraints provided 599in the tag even though the requested allocation size was less than maxsize. 600.El 601.It Fn bus_dmamap_load_mbuf "dmat" "map" "mbuf" "callback2" "callback_arg" \ 602"flags" 603This is a variation of 604.Fn bus_dmamap_load 605which maps mbuf chains 606for DMA transfers. 607A 608.Vt bus_size_t 609argument is also passed to the callback routine, which 610contains the mbuf chain's packet header length. 611.Pp 612Mbuf chains are assumed to be in kernel virtual address space. 613.Pp 614Returns 615.Er EINVAL 616if the size of the mbuf chain exceeds the maximum limit of the 617DMA tag. 618.It Fn bus_dmamap_load_mbuf_segment "dmat" "map" "mbuf" "*segs" "maxsegs" \ 619"*nsegs" "flags" 620It is like 621.Fn bus_dmamap_load_mbuf 622without callback. 623Segmentation information are saved in the 624.Fa segs 625and 626.Fa nsegs 627if the loading is successful. 628The 629.Fa maxsegs , 630which indicates the number of elements in the 631.Fa segs , 632must be set by the caller and must be at least 1 and at most equal the 633.Fa nsegments 634used to create the 635.Fa dmat . 636The 637.Fa flags 638must have 639.Dv BUS_DMA_NOWAIT 640turned on. 641.Pp 642This function will not block. 643When system is short of DMA resources, 644this function will return 645.Er ENOMEM , 646instead of 647.Er EINPROGRESS . 648.It Fn bus_dmamap_load_mbuf_defrag "dmat" "map" "*mbuf" "*segs" "maxsegs" \ 649"*nsegs" "flags" 650This function is like 651.Fn bus_dmamap_load_mbuf_segment , 652but it will call 653.Fn m_defrag 654on the 655.Fa *mbuf 656and try reloading, 657if low level code indicates too many fragments in the 658.Fa *mbuf ; 659the 660.Fa mbuf 661will be updated under this situation. 662However, 663.Fa *mbuf 664would not be freed by this function, 665even if 666.Fn m_defrag 667failed. 668.Pp 669Return 670.Er ENOBUFS , 671if the calling of 672.Fn m_defrag 673failed. 674.It Fn bus_dmamap_load_uio "dmat" "map" "uio" "callback2" "callback_arg" "flags" 675This is a variation of 676.Fn bus_dmamap_load 677which maps buffers pointed to by 678.Fa uio 679for DMA transfers. 680A 681.Vt bus_size_t 682argument is also passed to the callback routine, which contains the size of 683.Fa uio , 684i.e. 685.Fa uio->uio_resid . 686.Pp 687If 688.Fa uio->uio_segflg 689is 690.Dv UIO_USERSPACE , 691then it is assumed that the buffer, 692.Fa uio 693is in 694.Fa "uio->uio_td->td_proc" Ns 's 695address space. 696User space memory must be in-core and wired prior to attempting a map 697load operation. 698.It Fn bus_dmamap_unload "dmat" "map" 699Unloads a DMA map. 700Arguments are as follows: 701.Bl -tag -width dmam -compact 702.It Fa dmat 703DMA tag used to allocate 704.Fa map . 705.It Fa map 706The DMA map that is to be unloaded. 707.El 708.Pp 709.Fn bus_dmamap_unload 710will not perform any implicit synchronization of DMA buffers. 711This must be done explicitly by a call to 712.Fn bus_dmamap_sync 713prior to unloading the map. 714.It Fn bus_dmamap_sync "dmat" "map" "op" 715Performs synchronization of a device visible mapping with the CPU visible 716memory referenced by that mapping. 717Arguments are as follows: 718.Bl -tag -width dmat -compact 719.It Fa dmat 720DMA tag used to allocate 721.Fa map . 722.It Fa map 723The DMA mapping to be synchronized. 724.It Fa op 725Type of synchronization operation to perform. 726See the definition of 727.Vt bus_dmasync_op_t 728for a description of the acceptable values for 729.Fa op . 730.El 731.Pp 732.Fn bus_dmamap_sync 733is the method used to ensure that CPU and device DMA access to shared 734memory is coherent. 735For example, the CPU might be used to setup the contents of a buffer 736that is to be DMA'ed into a device. 737To ensure that the data are visible via the device's mapping of that 738memory, the buffer must be loaded and a dma sync operation of 739.Dv BUS_DMASYNC_PREREAD 740must be performed. 741Additional sync operations must be performed after every CPU write 742to this memory if additional DMA reads are to be performed. 743Conversely, for the DMA write case, the buffer must be loaded, 744and a dma sync operation of 745.Dv BUS_DMASYNC_PREWRITE 746must be performed. 747The CPU will only be able to see the results of this DMA write 748once the DMA has completed and a 749.Dv BUS_DMASYNC_POSTWRITE 750operation has been performed. 751.Pp 752If DMA read and write operations are not preceded and followed by the 753appropriate synchronization operations, behavior is undefined. 754.It Fn bus_dmamem_alloc "dmat" "**vaddr" "flags" "mapp" 755Allocates memory that is mapped into KVA at the address returned 756in 757.Fa vaddr 758that is permanently loaded into the newly created 759.Vt bus_dmamap_t 760returned via 761.Fa mapp . 762Arguments are as follows: 763.Bl -tag -width alignment -compact 764.It Fa dmat 765DMA tag describing the constraints of the DMA mapping. 766.It Fa vaddr 767Pointer to a pointer that will hold the returned KVA mapping of 768the allocated region. 769.It Fa flags 770Flags are defined as follows: 771.Bl -tag -width ".Dv BUS_DMA_COHERENT" -compact 772.It Dv BUS_DMA_WAITOK 773The routine can safely wait (sleep) for resources. 774.It Dv BUS_DMA_NOWAIT 775The routine is not allowed to wait for resources. 776If resources are not available, 777.Er ENOMEM 778is returned. 779.It Dv BUS_DMA_COHERENT 780Attempt to map this memory such that cache sync operations are 781as cheap as possible. 782This flag is typically set on memory that will be accessed by both 783a CPU and a DMA engine, frequently. 784Use of this flag does not remove the requirement of using 785bus_dmamap_sync, but it may reduce the cost of performing 786these operations. 787.It Dv BUS_DMA_ZERO 788Causes the allocated memory to be set to all zeros. 789.It Dv BUS_DMA_NOCACHE 790The allocated memory will not be cached in the processor caches. 791All memory accesses appear on the bus and are executed 792without reordering. 793On x86_64, the 794.Dv BUS_DMA_NOCACHE 795flag results in the 796Strong Uncacheable PAT to be set for the allocated virtual address range. 797.El 798.It Fa mapp 799Pointer to storage for the returned DMA map. 800.El 801.Pp 802The size of memory to be allocated is 803.Fa maxsize 804as specified in 805.Fa dmat . 806.Pp 807The current implementation of 808.Fn bus_dmamem_alloc 809will allocate all requests as a single segment. 810.Pp 811Although no explicit loading is required to access the memory 812referenced by the returned map, the synchronization requirements 813as described in the 814.Fn bus_dmamap_sync 815section still apply. 816.Pp 817Returns 818.Er ENOMEM 819if sufficient memory is not available for completing 820the operation. 821.It Fn bus_dmamem_coherent "parent" "alignment" "boundary" "lowaddr" \ 822"highaddr" "maxsize" "flags" "*dmem" 823This is a convenient function to create one segment of DMA memory. 824It combines following 825.Xr bus_dma 9 826function calls: 827.Bd -literal 828 bus_dma_tag_create(..., dtag); 829 bus_dmamem_alloc(*dtag, vaddr, ..., dmap); 830 bus_dmamap_load(*dtag, *dmap, *vaddr, ..., \\ 831 callback, busaddr, ...); 832.Ed 833.sp 834The final results of the above function calls are: 835DMA tag, 836DMA map, 837DMA memory's kernel virtual address and 838its device visible address. 839.Fn bus_dmamem_coherent 840saves the results in 841.Fa *dmem . 842.Pp 843The 844.Fa parent , 845.Fa alignment , 846.Fa boundary , 847.Fa lowaddr 848and 849.Fa highaddr 850will be passed to 851.Fn bus_dma_tag_create 852as they are. 853The 854.Fa maxsize 855will be passed to 856.Fn bus_dma_tag_create 857as its 858.Fa maxsize 859and 860.Fa maxsegsz 861and 862.Ql 1 863will be passed to 864.Fn bus_dma_tag_create 865as its 866.Fa nsegments . 867When 868.Fn bus_dmamem_alloc 869is called, 870.Fa flags 871will be first or'ed with 872.Dv BUS_DMA_COHERENT 873then passed to it. 874The final results of the above three functions, 875i.e. DMA tag, 876DMA map, 877DMA memory's kernel virtual address and 878its device visible address, 879are saved in 880.Fa *dmem . 881If any of the three functions failed, 882this function will return the error code and the 883.Fa *dmem 884should not be used. 885.It Fn bus_dmamem_coherent_any "parent" "alignment" "maxsize" "flags" \ 886"*dtag" "*dmap" "*busaddr" 887This function is a simplified version of 888.Fn bus_dmamem_coherent 889with 890its 891.Fa boundary 892set to 893.Ql 0 , 894.Fa lowaddr 895set to 896.Dv BUS_SPACE_MAXADDR 897and 898.Fa highaddr 899set to 900.Dv BUS_SPACE_MAXADDR . 901The 902.Fa parent 903usually should not be NULL. 904.Pp 905Return the DMA memory's kernel virtual address. 906The DMA tag, DMA map and device visible address are returned in 907.Fa *dtag , 908.Fa *dmap , 909and 910.Fa *busaddr . 911If this function failed, 912NULL will be returned; 913.Fa *dtag , 914.Fa *dmap , 915and 916.Fa *busaddr 917are left unchanged. 918.It Fn bus_dmamem_free "dmat" "*vaddr" "map" 919Frees memory previously allocated by 920.Fn bus_dmamem_alloc . 921Any mappings 922will be invalidated. 923Arguments are as follows: 924.Bl -tag -width vaddr -compact 925.It Fa dmat 926DMA tag. 927.It Fa vaddr 928Kernel virtual address of the memory. 929.It Fa map 930DMA map to be invalidated. 931.El 932.El 933.Sh RETURN VALUES 934Behavior is undefined if invalid arguments are passed to 935any of the above functions. 936If sufficient resources cannot be allocated for a given 937transaction, 938.Er ENOMEM 939is returned. 940All 941routines that are not of type, 942.Vt void , 943will return 0 on success or an error 944code, as discussed above. 945.Pp 946All 947.Vt void 948routines will succeed if provided with valid arguments. 949.Sh SEE ALSO 950.Xr devclass 9 , 951.Xr device 9 , 952.Xr driver 9 , 953.Xr rman 9 954.Rs 955.%A "Jason R. Thorpe" 956.%T "A Machine-Independent DMA Framework for NetBSD" 957.%J "Proceedings of the Summer 1998 USENIX Technical Conference" 958.%Q "USENIX Association" 959.%D "June 1998" 960.Re 961.Sh HISTORY 962The 963.Nm 964interface first appeared in 965.Nx 1.3 . 966.Pp 967The 968.Nm 969API was adopted from 970.Nx 971for use in the CAM SCSI subsystem. 972The alterations to the original API were aimed to remove the need for 973a 974.Vt bus_dma_segment_t 975array stored in each 976.Vt bus_dmamap_t 977while allowing callers to queue up on scarce resources. 978.Sh AUTHORS 979The 980.Nm 981interface was designed and implemented by 982.An Jason R. Thorpe 983of the Numerical Aerospace Simulation Facility, NASA Ames Research Center. 984Additional input on the 985.Nm 986design was provided by 987.An -nosplit 988.An Chris Demetriou , 989.An Charles Hannum , 990.An Ross Harvey , 991.An Matthew Jacob , 992.An Jonathan Stone , 993and 994.An Matt Thomas . 995.Pp 996This manual page was written by 997.An Hiten Pandya 998and 999.An Justin T. Gibbs . 1000