1.\" Copyright (c) 2002, 2003 Hiten M. Pandya. 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions, and the following disclaimer, 9.\" without modification, immediately at the beginning of the file. 10.\" 2. The name of the author may not be used to endorse or promote products 11.\" derived from this software without specific prior written permission. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR, CONTRIBUTORS OR THE 17.\" VOICES IN HITEN PANDYA'S HEAD BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 18.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED 19.\" TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 20.\" PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 21.\" LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 22.\" NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 23.\" SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 24.\" 25.\" Copyright (c) 1996, 1997, 1998, 2001 The NetBSD Foundation, Inc. 26.\" All rights reserved. 27.\" 28.\" This code is derived from software contributed to The NetBSD Foundation 29.\" by Jason R. Thorpe of the Numerical Aerospace Simulation Facility, 30.\" NASA Ames Research Center. 31.\" 32.\" Redistribution and use in source and binary forms, with or without 33.\" modification, are permitted provided that the following conditions 34.\" are met: 35.\" 1. Redistributions of source code must retain the above copyright 36.\" notice, this list of conditions and the following disclaimer. 37.\" 2. Redistributions in binary form must reproduce the above copyright 38.\" notice, this list of conditions and the following disclaimer in the 39.\" documentation and/or other materials provided with the distribution. 40.\" 41.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 42.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 43.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 44.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 45.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 46.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 47.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 48.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 49.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 50.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 51.\" POSSIBILITY OF SUCH DAMAGE. 52.\" 53.\" $FreeBSD$ 54.\" $NetBSD: bus_dma.9,v 1.25 2002/10/14 13:43:16 wiz Exp $ 55.\" 56.Dd April 14, 2020 57.Dt BUS_DMA 9 58.Os 59.Sh NAME 60.Nm bus_dma , 61.Nm bus_dma_tag_create , 62.Nm bus_dma_tag_destroy , 63.Nm bus_dma_template_init , 64.Nm bus_dma_template_tag , 65.Nm bus_dma_template_clone , 66.Nm bus_dmamap_create , 67.Nm bus_dmamap_destroy , 68.Nm bus_dmamap_load , 69.Nm bus_dmamap_load_bio , 70.Nm bus_dmamap_load_ccb , 71.Nm bus_dmamap_load_crp , 72.Nm bus_dmamap_load_mbuf , 73.Nm bus_dmamap_load_mbuf_sg , 74.Nm bus_dmamap_load_uio , 75.Nm bus_dmamap_unload , 76.Nm bus_dmamap_sync , 77.Nm bus_dmamem_alloc , 78.Nm bus_dmamem_free 79.Nd Bus and Machine Independent DMA Mapping Interface 80.Sh SYNOPSIS 81.In machine/bus.h 82.Ft int 83.Fn bus_dma_tag_create "bus_dma_tag_t parent" "bus_size_t alignment" \ 84"bus_addr_t boundary" "bus_addr_t lowaddr" "bus_addr_t highaddr" \ 85"bus_dma_filter_t *filtfunc" "void *filtfuncarg" "bus_size_t maxsize" \ 86"int nsegments" "bus_size_t maxsegsz" "int flags" "bus_dma_lock_t *lockfunc" \ 87"void *lockfuncarg" "bus_dma_tag_t *dmat" 88.Ft int 89.Fn bus_dma_tag_destroy "bus_dma_tag_t dmat" 90.Ft void 91.Fo bus_dma_template_init 92.Fa "bus_dma_template_t template" 93.Fa "bus_dma_tag_t parent" 94.Fc 95.Ft int 96.Fo bus_dma_template_tag 97.Fa "bus_dma_template_t template" 98.Fa "bus_dma_tag_t *dmat" 99.Fc 100.Ft void 101.Fo bus_dma_template_clone 102.Fa "bus_dma_template_t template" 103.Fa "bus_dma_tag_t dmat" 104.Fc 105.Ft int 106.Fn bus_dmamap_create "bus_dma_tag_t dmat" "int flags" "bus_dmamap_t *mapp" 107.Ft int 108.Fn bus_dmamap_destroy "bus_dma_tag_t dmat" "bus_dmamap_t map" 109.Ft int 110.Fn bus_dmamap_load "bus_dma_tag_t dmat" "bus_dmamap_t map" "void *buf" \ 111"bus_size_t buflen" "bus_dmamap_callback_t *callback" "void *callback_arg" \ 112"int flags" 113.Ft int 114.Fn bus_dmamap_load_bio "bus_dma_tag_t dmat" "bus_dmamap_t map" \ 115"struct bio *bio" "bus_dmamap_callback_t *callback" "void *callback_arg" \ 116"int flags" 117.Ft int 118.Fn bus_dmamap_load_ccb "bus_dma_tag_t dmat" "bus_dmamap_t map" \ 119"union ccb *ccb" "bus_dmamap_callback_t *callback" "void *callback_arg" \ 120"int flags" 121.Ft int 122.Fn bus_dmamap_load_crp "bus_dma_tag_t dmat" "bus_dmamap_t map" \ 123"struct crypto *crp" "bus_dmamap_callback_t *callback" "void *callback_arg" \ 124"int flags" 125.Ft int 126.Fn bus_dmamap_load_mbuf "bus_dma_tag_t dmat" "bus_dmamap_t map" \ 127"struct mbuf *mbuf" "bus_dmamap_callback2_t *callback" "void *callback_arg" \ 128"int flags" 129.Ft int 130.Fn bus_dmamap_load_mbuf_sg "bus_dma_tag_t dmat" "bus_dmamap_t map" \ 131"struct mbuf *mbuf" "bus_dma_segment_t *segs" "int *nsegs" "int flags" 132.Ft int 133.Fn bus_dmamap_load_uio "bus_dma_tag_t dmat" "bus_dmamap_t map" \ 134"struct uio *uio" "bus_dmamap_callback2_t *callback" "void *callback_arg" \ 135"int flags" 136.Ft void 137.Fn bus_dmamap_unload "bus_dma_tag_t dmat" "bus_dmamap_t map" 138.Ft void 139.Fn bus_dmamap_sync "bus_dma_tag_t dmat" "bus_dmamap_t map" \ 140"op" 141.Ft int 142.Fn bus_dmamem_alloc "bus_dma_tag_t dmat" "void **vaddr" \ 143"int flags" "bus_dmamap_t *mapp" 144.Ft void 145.Fn bus_dmamem_free "bus_dma_tag_t dmat" "void *vaddr" \ 146"bus_dmamap_t map" 147.Sh DESCRIPTION 148Direct Memory Access (DMA) is a method of transferring data 149without involving the CPU, thus providing higher performance. 150A DMA transaction can be achieved between device to memory, 151device to device, or memory to memory. 152.Pp 153The 154.Nm 155API is a bus, device, and machine-independent (MI) interface to 156DMA mechanisms. 157It provides the client with flexibility and simplicity by 158abstracting machine dependent issues like setting up 159DMA mappings, handling cache issues, bus specific features 160and limitations. 161.Sh OVERVIEW 162A tag structure 163.Vt ( bus_dma_tag_t ) 164is used to describe the properties of a group of related DMA 165transactions. 166One way to view this is that a tag describes the limitations of a DMA engine. 167For example, if a DMA engine in a device is limited to 32-bit addresses, 168that limitation is specified by a parameter when creating the tag 169for that device. 170Similarly, a tag can be marked as requiring buffers whose addresses are 171aligned to a specific boundary. 172.Pp 173Some devices may require multiple tags to describe DMA 174transactions with differing properties. 175For example, a device might require 16-byte alignment of its descriptor ring 176while permitting arbitrary alignment of I/O buffers. 177In this case, 178the driver must create one tag for the descriptor ring and a separate tag for 179I/O buffers. 180If a device has restrictions that are common to all DMA transactions 181in addition to restrictions that differ between unrelated groups of 182transactions, 183the driver can first create a 184.Dq parent 185tag that decribes the common restrictions. 186The per-group tags can then inherit these restrictions from this 187.Dq parent 188tag rather than having to list them explicitly when creating the per-group tags. 189.Pp 190A mapping structure 191.Vt ( bus_dmamap_t ) 192represents a mapping of a memory region for DMA. 193On systems with I/O MMUs, 194the mapping structure tracks any I/O MMU entries used by a request. 195For DMA requests that require bounce pages, 196the mapping tracks the bounce pages used. 197.Pp 198To prepare for one or more DMA transactions, 199a mapping must be bound to a memory region by calling one of the 200.Fn bus_dmamap_load 201functions. 202These functions configure the mapping which can include programming entries 203in an I/O MMU and/or allocating bounce pages. 204An output of these functions 205(either directly or indirectly by invoking a callback routine) 206is the list of scatter/gather address ranges a consumer can pass to a DMA 207engine to access the memory region. 208When a mapping is no longer needed, 209the mapping must be unloaded via 210.Fn bus_dmamap_unload . 211.Pp 212Before and after each DMA transaction, 213.Fn bus_dmamap_sync 214must be used to ensure that the correct data is used by the DMA engine and 215the CPU. 216If a mapping uses bounce pages, 217the sync operations copy data between the bounce pages and the memory region 218bound to the mapping. 219Sync operations also handle architecture-specific details such as CPU cache 220flushing and CPU memory operation ordering. 221.Sh STATIC VS DYNAMIC 222.Nm 223handles two types of DMA transactions: static and dynamic. 224Static transactions are used with a long-lived memory region that is reused 225for many transactions such as a descriptor ring. 226Dynamic transactions are used for transfers to or from transient buffers 227such as I/O buffers holding a network packet or disk block. 228Each transaction type uses a different subset of the 229.Nm 230API. 231.Ss Static Transactions 232Static transactions use memory regions allocated by 233.Nm . 234Each static memory region is allocated by calling 235.Fn bus_dmamem_alloc . 236This function requires a valid tag describing the properties of the 237DMA transactions to this region such as alignment or address restrictions. 238Multiple regions can share a single tag if they share the same restrictions. 239.Pp 240.Fn bus_dmamem_alloc 241allocates a memory region along with a mapping object. 242The associated tag, memory region, and mapping object must then be passed to 243.Fn bus_dmamap_load 244to bind the mapping to the allocated region and obtain the 245scatter/gather list. 246.Pp 247It is expected that 248.Fn bus_dmamem_alloc 249will attempt to allocate memory requiring less expensive sync operations 250(for example, implementations should not allocate regions requiring bounce 251pages), 252but sync operations should still be used. 253For example, a driver should use 254.Fn bus_dmamap_sync 255in an interrupt handler before reading descriptor ring entries written by the 256device prior to the interrupt. 257.Pp 258When a consumer is finished with a memory region, 259it should unload the mapping via 260.Fn bus_dmamap_unload 261and then release the memory region and mapping object via 262.Fn bus_dmamem_free . 263.Ss Dynamic Transactions 264Dynamic transactions map memory regions provided by other parts of the system. 265A tag must be created via 266.Fn bus_dma_tag_create 267to describe the DMA transactions to and from these memory regions, 268and a pool of mapping objects must be allocated via 269.Fn bus_dmamap_create 270to track the mappings of any in-flight transactions. 271.Pp 272When a consumer wishes to schedule a transaction for a memory region, 273the consumer must first obtain an unused mapping object from its pool 274of mapping objects. 275The memory region must be bound to the mapping object via one of the 276.Fn bus_dmamap_load 277functions. 278Before scheduling the transaction, 279the consumer should sync the memory region via 280.Fn bus_dmamap_sync 281with one or more of the 282.Dq PRE 283flags. 284After the transaction has completed, 285the consumer should sync the memory region via 286.Fn bus_dmamap_sync 287with one or more of the 288.Dq POST 289flags. 290The mapping can then be unloaded via 291.Fn bus_dmamap_unload , 292and the mapping object can be returned to the pool of unused mapping objects. 293.Pp 294When a consumer is no longer scheduling DMA transactions, 295the mapping objects should be freed via 296.Fn bus_dmamap_destroy , 297and the tag should be freed via 298.Fn bus_dma_tag_destroy . 299.Sh STRUCTURES AND TYPES 300.Bl -tag -width indent 301.It Vt bus_dma_tag_t 302A machine-dependent (MD) opaque type that describes the 303characteristics of a group of DMA transactions. 304DMA tags are organized into a hierarchy, with each child 305tag inheriting the restrictions of its parent. 306This allows all devices along the path of DMA transactions 307to contribute to the constraints of those transactions. 308.It Vt bus_dma_template_t 309A template structure for creating a 310.Fa bus_dma_tag_t 311from a set of defaults. 312Once initialized with 313.Fn bus_dma_template_init , 314a driver can over-ride individual fields to suit its needs. 315The following fields have the indicated values: 316.Bd -literal 317 alignment 1 318 boundary 0 319 lowaddr BUS_SPACE_MAXADDR 320 highaddr BUS_SPACE_MAXADDR 321 maxsize BUS_SPACE_MAXSIZE 322 nsegments BUS_SPACE_UNRESTRICTED 323 maxsegsize BUS_SPACE_MAXSIZE 324 flags 0 325 lockfunc NULL 326 lockfuncarg NULL 327.Ed 328.Pp 329Descriptions of each field are documented with 330.Fn bus_dma_tag_create . 331Note that the 332.Fa filtfunc 333and 334.Fa filtfuncarg 335attributes of the DMA tag are not supported with templates. 336.It Vt bus_dma_filter_t 337Client specified address filter having the format: 338.Bl -tag -width indent 339.It Ft int 340.Fn "client_filter" "void *filtarg" "bus_addr_t testaddr" 341.El 342.Pp 343Address filters can be specified during tag creation to allow 344for devices whose DMA address restrictions cannot be specified 345by a single window. 346The 347.Fa filtarg 348argument is specified by the client during tag creation to be passed to all 349invocations of the callback. 350The 351.Fa testaddr 352argument contains a potential starting address of a DMA mapping. 353The filter function operates on the set of addresses from 354.Fa testaddr 355to 356.Ql trunc_page(testaddr) + PAGE_SIZE - 1 , 357inclusive. 358The filter function should return zero if any mapping in this range 359can be accommodated by the device and non-zero otherwise. 360.It Vt bus_dma_segment_t 361A machine-dependent type that describes individual 362DMA segments. 363It contains the following fields: 364.Bd -literal 365 bus_addr_t ds_addr; 366 bus_size_t ds_len; 367.Ed 368.Pp 369The 370.Fa ds_addr 371field contains the device visible address of the DMA segment, and 372.Fa ds_len 373contains the length of the DMA segment. 374Although the DMA segments returned by a mapping call will adhere to 375all restrictions necessary for a successful DMA operation, some conversion 376(e.g.\& a conversion from host byte order to the device's byte order) is 377almost always required when presenting segment information to the device. 378.It Vt bus_dmamap_t 379A machine-dependent opaque type describing an individual mapping. 380One map is used for each memory allocation that will be loaded. 381Maps can be reused once they have been unloaded. 382Multiple maps can be associated with one DMA tag. 383While the value of the map may evaluate to 384.Dv NULL 385on some platforms under certain conditions, 386it should never be assumed that it will be 387.Dv NULL 388in all cases. 389.It Vt bus_dmamap_callback_t 390Client specified callback for receiving mapping information resulting from 391the load of a 392.Vt bus_dmamap_t 393via 394.Fn bus_dmamap_load , 395.Fn bus_dmamap_load_bio , 396.Fn bus_dmamap_load_ccb , 397or 398.Fn bus_dmamap_load_crp . 399Callbacks are of the format: 400.Bl -tag -width indent 401.It Ft void 402.Fn "client_callback" "void *callback_arg" "bus_dma_segment_t *segs" \ 403"int nseg" "int error" 404.El 405.Pp 406The 407.Fa callback_arg 408is the callback argument passed to dmamap load functions. 409The 410.Fa segs 411and 412.Fa nseg 413arguments describe an array of 414.Vt bus_dma_segment_t 415structures that represent the mapping. 416This array is only valid within the scope of the callback function. 417The success or failure of the mapping is indicated by the 418.Fa error 419argument. 420More information on the use of callbacks can be found in the 421description of the individual dmamap load functions. 422.It Vt bus_dmamap_callback2_t 423Client specified callback for receiving mapping information resulting from 424the load of a 425.Vt bus_dmamap_t 426via 427.Fn bus_dmamap_load_uio 428or 429.Fn bus_dmamap_load_mbuf . 430.Pp 431Callback2s are of the format: 432.Bl -tag -width indent 433.It Ft void 434.Fn "client_callback2" "void *callback_arg" "bus_dma_segment_t *segs" \ 435"int nseg" "bus_size_t mapsize" "int error" 436.El 437.Pp 438Callback2's behavior is the same as 439.Vt bus_dmamap_callback_t 440with the addition that the length of the data mapped is provided via 441.Fa mapsize . 442.It Vt bus_dmasync_op_t 443Memory synchronization operation specifier. 444Bus DMA requires explicit synchronization of memory with its device 445visible mapping in order to guarantee memory coherency. 446The 447.Vt bus_dmasync_op_t 448allows the type of DMA operation that will be or has been performed 449to be communicated to the system so that the correct coherency measures 450are taken. 451The operations are represented as bitfield flags that can be combined together, 452though it only makes sense to combine PRE flags or POST flags, not both. 453See the 454.Fn bus_dmamap_sync 455description below for more details on how to use these operations. 456.Pp 457All operations specified below are performed from the host memory point of view, 458where a read implies data coming from the device to the host memory, and a write 459implies data going from the host memory to the device. 460Alternatively, the operations can be thought of in terms of driver operations, 461where reading a network packet or storage sector corresponds to a read operation 462in 463.Nm . 464.Bl -tag -width ".Dv BUS_DMASYNC_POSTWRITE" 465.It Dv BUS_DMASYNC_PREREAD 466Perform any synchronization required prior to an update of host memory by the 467device. 468.It Dv BUS_DMASYNC_PREWRITE 469Perform any synchronization required after an update of host memory by the CPU 470and prior to device access to host memory. 471.It Dv BUS_DMASYNC_POSTREAD 472Perform any synchronization required after an update of host memory by the 473device and prior to CPU access to host memory. 474.It Dv BUS_DMASYNC_POSTWRITE 475Perform any synchronization required after device access to host memory. 476.El 477.It Vt bus_dma_lock_t 478Client specified lock/mutex manipulation method. 479This will be called from 480within busdma whenever a client lock needs to be manipulated. 481In its current form, the function will be called immediately before 482the callback for a DMA load operation that has been deferred with 483.Dv BUS_DMA_LOCK 484and immediately after with 485.Dv BUS_DMA_UNLOCK . 486If the load operation does not need to be deferred, then it 487will not be called since the function loading the map should 488be holding the appropriate locks. 489This method is of the format: 490.Bl -tag -width indent 491.It Ft void 492.Fn "lockfunc" "void *lockfunc_arg" "bus_dma_lock_op_t op" 493.El 494.Pp 495The 496.Fa lockfuncarg 497argument is specified by the client during tag creation to be passed to all 498invocations of the callback. 499The 500.Fa op 501argument specifies the lock operation to perform. 502.Pp 503Two 504.Vt lockfunc 505implementations are provided for convenience. 506.Fn busdma_lock_mutex 507performs standard mutex operations on the sleep mutex provided via 508.Fa lockfuncarg . 509.Fn dflt_lock 510will generate a system panic if it is called. 511It is substituted into the tag when 512.Fa lockfunc 513is passed as 514.Dv NULL 515to 516.Fn bus_dma_tag_create 517and is useful for tags that should not be used with deferred load operations. 518.It Vt bus_dma_lock_op_t 519Operations to be performed by the client-specified 520.Fn lockfunc . 521.Bl -tag -width ".Dv BUS_DMA_UNLOCK" 522.It Dv BUS_DMA_LOCK 523Acquires and/or locks the client locking primitive. 524.It Dv BUS_DMA_UNLOCK 525Releases and/or unlocks the client locking primitive. 526.El 527.El 528.Sh FUNCTIONS 529.Bl -tag -width indent 530.It Fn bus_dma_tag_create "parent" "alignment" "boundary" "lowaddr" \ 531"highaddr" "*filtfunc" "*filtfuncarg" "maxsize" "nsegments" "maxsegsz" \ 532"flags" "lockfunc" "lockfuncarg" "*dmat" 533Allocates a DMA tag, and initializes it according to 534the arguments provided: 535.Bl -tag -width ".Fa filtfuncarg" 536.It Fa parent 537A parent tag from which to inherit restrictions. 538The restrictions passed in other arguments can only further tighten the 539restrictions inherited from the parent tag. 540.Pp 541All tags created by a device driver must inherit from the tag returned by 542.Fn bus_get_dma_tag 543to honor restrictions between the parent bridge, CPU memory, and the 544device. 545.It Fa alignment 546Alignment constraint, in bytes, of any mappings created using this tag. 547The alignment must be a power of 2. 548Hardware that can DMA starting at any address would specify 549.Em 1 550for byte alignment. 551Hardware requiring DMA transfers to start on a multiple of 4K 552would specify 553.Em 4096 . 554.It Fa boundary 555Boundary constraint, in bytes, of the target DMA memory region. 556The boundary indicates the set of addresses, all multiples of the 557boundary argument, that cannot be crossed by a single 558.Vt bus_dma_segment_t . 559The boundary must be a power of 2 and must be no smaller than the 560maximum segment size. 561.Ql 0 562indicates that there are no boundary restrictions. 563.It Fa lowaddr , highaddr 564Bounds of the window of bus address space that 565.Em cannot 566be directly accessed by the device. 567The window contains all addresses greater than 568.Fa lowaddr 569and less than or equal to 570.Fa highaddr . 571For example, a device incapable of DMA above 4GB, would specify a 572.Fa highaddr 573of 574.Dv BUS_SPACE_MAXADDR 575and a 576.Fa lowaddr 577of 578.Dv BUS_SPACE_MAXADDR_32BIT . 579Similarly a device that can only perform DMA to addresses below 58016MB would specify a 581.Fa highaddr 582of 583.Dv BUS_SPACE_MAXADDR 584and a 585.Fa lowaddr 586of 587.Dv BUS_SPACE_MAXADDR_24BIT . 588Some implementations require that some region of device visible 589address space, overlapping available host memory, be outside the 590window. 591This area of 592.Ql safe memory 593is used to bounce requests that would otherwise conflict with 594the exclusion window. 595.It Fa filtfunc 596Optional filter function (may be 597.Dv NULL ) 598to be called for any attempt to 599map memory into the window described by 600.Fa lowaddr 601and 602.Fa highaddr . 603A filter function is only required when the single window described 604by 605.Fa lowaddr 606and 607.Fa highaddr 608cannot adequately describe the constraints of the device. 609The filter function will be called for every machine page 610that overlaps the exclusion window. 611.It Fa filtfuncarg 612Argument passed to all calls to the filter function for this tag. 613May be 614.Dv NULL . 615.It Fa maxsize 616Maximum size, in bytes, of the sum of all segment lengths in a given 617DMA mapping associated with this tag. 618.It Fa nsegments 619Number of discontinuities (scatter/gather segments) allowed 620in a DMA mapped region. 621.It Fa maxsegsz 622Maximum size, in bytes, of a segment in any DMA mapped region associated 623with 624.Fa dmat . 625.It Fa flags 626Are as follows: 627.Bl -tag -width ".Dv BUS_DMA_ALLOCNOW" 628.It Dv BUS_DMA_ALLOCNOW 629Pre-allocate enough resources to handle at least one map load operation on 630this tag. 631If sufficient resources are not available, 632.Er ENOMEM 633is returned. 634This should not be used for tags that only describe buffers that will be 635allocated with 636.Fn bus_dmamem_alloc . 637Also, due to resource sharing with other tags, this flag does not guarantee 638that resources will be allocated or reserved exclusively for this tag. 639It should be treated only as a minor optimization. 640.It Dv BUS_DMA_COHERENT 641Indicate that the DMA engine and CPU are cache-coherent. 642Cached memory may be used to back allocations created by 643.Fn bus_dmamem_alloc . 644For 645.Fn bus_dma_tag_create , 646the 647.Dv BUS_DMA_COHERENT 648flag is currently implemented on arm64. 649.El 650.It Fa lockfunc 651Optional lock manipulation function (may be 652.Dv NULL ) 653to be called when busdma 654needs to manipulate a lock on behalf of the client. 655If 656.Dv NULL 657is specified, 658.Fn dflt_lock 659is used. 660.It Fa lockfuncarg 661Optional argument to be passed to the function specified by 662.Fa lockfunc . 663.It Fa dmat 664Pointer to a bus_dma_tag_t where the resulting DMA tag will 665be stored. 666.El 667.Pp 668Returns 669.Er ENOMEM 670if sufficient memory is not available for tag creation 671or allocating mapping resources. 672.It Fn bus_dma_tag_destroy "dmat" 673Deallocate the DMA tag 674.Fa dmat 675that was created by 676.Fn bus_dma_tag_create . 677.Pp 678Returns 679.Er EBUSY 680if any DMA maps remain associated with 681.Fa dmat 682or 683.Ql 0 684on success. 685.It Fn bus_dma_template_init "*template" "parent" 686Initializes a 687.Fa bus_dma_template_t 688structure and associates it with an optional 689.Fa parent . 690The 691.Fa parent 692argument may be NULL. 693.It Fn bus_dma_template_tag "*template" "*dmat" 694Unpacks a template into a tag, and returns the tag via the 695.Fa dmat . 696All return values are identical to 697.Fn bus_dma_tag_create . 698.It Fn bus_dma_template_clone "*template" "dmat" 699Clones the fields from a tag to a template. 700This is useful for cloning tags when paired with 701.Fn bus_dma_template_tag . 702A template that is filled in as a clone does not need to be initialized 703first. 704.It Fn bus_dmamap_create "dmat" "flags" "*mapp" 705Allocates and initializes a DMA map. 706Arguments are as follows: 707.Bl -tag -width ".Fa nsegments" 708.It Fa dmat 709DMA tag. 710.It Fa flags 711Are as follows: 712.Bl -tag -width ".Dv BUS_DMA_COHERENT" 713.It Dv BUS_DMA_COHERENT 714Attempt to map the memory loaded with this map such that cache sync 715operations are as cheap as possible. 716This flag is typically set on maps when the memory loaded with these will 717be accessed by both a CPU and a DMA engine, frequently such as control data 718and as opposed to streamable data such as receive and transmit buffers. 719Use of this flag does not remove the requirement of using 720.Fn bus_dmamap_sync , 721but it may reduce the cost of performing these operations. 722.El 723.It Fa mapp 724Pointer to a 725.Vt bus_dmamap_t 726where the resulting DMA map will be stored. 727.El 728.Pp 729Returns 730.Er ENOMEM 731if sufficient memory is not available for creating the 732map or allocating mapping resources. 733.It Fn bus_dmamap_destroy "dmat" "map" 734Frees all resources associated with a given DMA map. 735Arguments are as follows: 736.Bl -tag -width ".Fa dmat" 737.It Fa dmat 738DMA tag used to allocate 739.Fa map . 740.It Fa map 741The DMA map to destroy. 742.El 743.Pp 744Returns 745.Er EBUSY 746if a mapping is still active for 747.Fa map . 748.It Fn bus_dmamap_load "dmat" "map" "buf" "buflen" "*callback" \ 749"callback_arg" "flags" 750Creates a mapping in device visible address space of 751.Fa buflen 752bytes of 753.Fa buf , 754associated with the DMA map 755.Fa map . 756This call will always return immediately and will not block for any reason. 757Arguments are as follows: 758.Bl -tag -width ".Fa buflen" 759.It Fa dmat 760DMA tag used to allocate 761.Fa map . 762.It Fa map 763A DMA map without a currently active mapping. 764.It Fa buf 765A kernel virtual address pointer to a contiguous (in KVA) buffer, to be 766mapped into device visible address space. 767.It Fa buflen 768The size of the buffer. 769.It Fa callback Fa callback_arg 770The callback function, and its argument. 771This function is called once sufficient mapping resources are available for 772the DMA operation. 773If resources are temporarily unavailable, this function will be deferred until 774later, but the load operation will still return immediately to the caller. 775Thus, callers should not assume that the callback will be called before the 776load returns, and code should be structured appropriately to handle this. 777See below for specific flags and error codes that control this behavior. 778.It Fa flags 779Are as follows: 780.Bl -tag -width ".Dv BUS_DMA_NOWAIT" 781.It Dv BUS_DMA_NOWAIT 782The load should not be deferred in case of insufficient mapping resources, 783and instead should return immediately with an appropriate error. 784.It Dv BUS_DMA_NOCACHE 785The generated transactions to and from the virtual page are non-cacheable. 786.El 787.El 788.Pp 789Return values to the caller are as follows: 790.Bl -tag -width ".Er EINPROGRESS" 791.It 0 792The callback has been called and completed. 793The status of the mapping has been delivered to the callback. 794.It Er EINPROGRESS 795The mapping has been deferred for lack of resources. 796The callback will be called as soon as resources are available. 797Callbacks are serviced in FIFO order. 798.Pp 799Note that subsequent load operations for the same tag that do not require 800extra resources will still succeed. 801This may result in out-of-order processing of requests. 802If the caller requires the order of requests to be preserved, 803then the caller is required to stall subsequent requests until a pending 804request's callback is invoked. 805.It Er ENOMEM 806The load request has failed due to insufficient resources, and the caller 807specifically used the 808.Dv BUS_DMA_NOWAIT 809flag. 810.It Er EINVAL 811The load request was invalid. 812The callback has been called and has been provided the same error. 813This error value may indicate that 814.Fa dmat , 815.Fa map , 816.Fa buf , 817or 818.Fa callback 819were invalid, or 820.Fa buflen 821was larger than the 822.Fa maxsize 823argument used to create the dma tag 824.Fa dmat . 825.El 826.Pp 827When the callback is called, it is presented with an error value 828indicating the disposition of the mapping. 829Error may be one of the following: 830.Bl -tag -width ".Er EINPROGRESS" 831.It 0 832The mapping was successful and the 833.Fa dm_segs 834callback argument contains an array of 835.Vt bus_dma_segment_t 836elements describing the mapping. 837This array is only valid during the scope of the callback function. 838.It Er EFBIG 839A mapping could not be achieved within the segment constraints provided 840in the tag even though the requested allocation size was less than maxsize. 841.El 842.It Fn bus_dmamap_load_bio "dmat" "map" "bio" "callback" "callback_arg" "flags" 843This is a variation of 844.Fn bus_dmamap_load 845which maps buffers pointed to by 846.Fa bio 847for DMA transfers. 848.Fa bio 849may point to either a mapped or unmapped buffer. 850.It Fn bus_dmamap_load_ccb "dmat" "map" "ccb" "callback" "callback_arg" "flags" 851This is a variation of 852.Fn bus_dmamap_load 853which maps data pointed to by 854.Fa ccb 855for DMA transfers. 856The data for 857.Fa ccb 858may be any of the following types: 859.Bl -tag -width ".Er CAM_DATA_SG_PADDR" 860.It CAM_DATA_VADDR 861The data is a single KVA buffer. 862.It CAM_DATA_PADDR 863The data is a single bus address range. 864.It CAM_DATA_SG 865The data is a scatter/gather list of KVA buffers. 866.It CAM_DATA_SG_PADDR 867The data is a scatter/gather list of bus address ranges. 868.It CAM_DATA_BIO 869The data is contained in a 870.Vt struct bio 871attached to the CCB. 872.El 873.Pp 874.Fn bus_dmamap_load_ccb 875supports the following CCB XPT function codes: 876.Pp 877.Bl -item -offset indent -compact 878.It 879XPT_ATA_IO 880.It 881XPT_CONT_TARGET_IO 882.It 883XPT_SCSI_IO 884.El 885.It Fn bus_dmamap_load_crp "dmat" "map" "crp" "callback" "callback_arg" "flags" 886This is a variation of 887.Fn bus_dmamap_load 888which maps buffers pointed to by 889.Fa crp 890for DMA transfers. 891The 892.Dv BUS_DMA_NOWAIT 893flag is implied, thus no callback deferral will happen. 894.It Fn bus_dmamap_load_mbuf "dmat" "map" "mbuf" "callback2" "callback_arg" \ 895"flags" 896This is a variation of 897.Fn bus_dmamap_load 898which maps mbuf chains 899for DMA transfers. 900A 901.Vt bus_size_t 902argument is also passed to the callback routine, which 903contains the mbuf chain's packet header length. 904The 905.Dv BUS_DMA_NOWAIT 906flag is implied, thus no callback deferral will happen. 907.Pp 908Mbuf chains are assumed to be in kernel virtual address space. 909.Pp 910Beside the error values listed for 911.Fn bus_dmamap_load , 912.Er EINVAL 913will be returned if the size of the mbuf chain exceeds the maximum limit of the 914DMA tag. 915.It Fn bus_dmamap_load_mbuf_sg "dmat" "map" "mbuf" "segs" "nsegs" "flags" 916This is just like 917.Fn bus_dmamap_load_mbuf 918except that it returns immediately without calling a callback function. 919It is provided for efficiency. 920The scatter/gather segment array 921.Va segs 922is provided by the caller and filled in directly by the function. 923The 924.Va nsegs 925argument is returned with the number of segments filled in. 926Returns the same errors as 927.Fn bus_dmamap_load_mbuf . 928.It Fn bus_dmamap_load_uio "dmat" "map" "uio" "callback2" "callback_arg" "flags" 929This is a variation of 930.Fn bus_dmamap_load 931which maps buffers pointed to by 932.Fa uio 933for DMA transfers. 934A 935.Vt bus_size_t 936argument is also passed to the callback routine, which contains the size of 937.Fa uio , 938i.e. 939.Fa uio->uio_resid . 940The 941.Dv BUS_DMA_NOWAIT 942flag is implied, thus no callback deferral will happen. 943Returns the same errors as 944.Fn bus_dmamap_load . 945.Pp 946If 947.Fa uio->uio_segflg 948is 949.Dv UIO_USERSPACE , 950then it is assumed that the buffer, 951.Fa uio 952is in 953.Fa "uio->uio_td->td_proc" Ns 's 954address space. 955User space memory must be in-core and wired prior to attempting a map 956load operation. 957Pages may be locked using 958.Xr vslock 9 . 959.It Fn bus_dmamap_unload "dmat" "map" 960Unloads a DMA map. 961Arguments are as follows: 962.Bl -tag -width ".Fa dmam" 963.It Fa dmat 964DMA tag used to allocate 965.Fa map . 966.It Fa map 967The DMA map that is to be unloaded. 968.El 969.Pp 970.Fn bus_dmamap_unload 971will not perform any implicit synchronization of DMA buffers. 972This must be done explicitly by a call to 973.Fn bus_dmamap_sync 974prior to unloading the map. 975.It Fn bus_dmamap_sync "dmat" "map" "op" 976Performs synchronization of a device visible mapping with the CPU visible 977memory referenced by that mapping. 978Arguments are as follows: 979.Bl -tag -width ".Fa dmat" 980.It Fa dmat 981DMA tag used to allocate 982.Fa map . 983.It Fa map 984The DMA mapping to be synchronized. 985.It Fa op 986Type of synchronization operation to perform. 987See the definition of 988.Vt bus_dmasync_op_t 989for a description of the acceptable values for 990.Fa op . 991.El 992.Pp 993The 994.Fn bus_dmamap_sync 995function 996is the method used to ensure that CPU's and device's direct 997memory access (DMA) to shared 998memory is coherent. 999For example, the CPU might be used to set up the contents of a buffer 1000that is to be made available to a device. 1001To ensure that the data are visible via the device's mapping of that 1002memory, the buffer must be loaded and a DMA sync operation of 1003.Dv BUS_DMASYNC_PREWRITE 1004must be performed after the CPU has updated the buffer and before the device 1005access is initiated. 1006If the CPU modifies this buffer again later, another 1007.Dv BUS_DMASYNC_PREWRITE 1008sync operation must be performed before an additional device 1009access. 1010Conversely, suppose a device updates memory that is to be read by a CPU. 1011In this case, the buffer must be loaded, and a DMA sync operation of 1012.Dv BUS_DMASYNC_PREREAD 1013must be performed before the device access is initiated. 1014The CPU will only be able to see the results of this memory update 1015once the DMA operation has completed and a 1016.Dv BUS_DMASYNC_POSTREAD 1017sync operation has been performed. 1018.Pp 1019If read and write operations are not preceded and followed by the 1020appropriate synchronization operations, behavior is undefined. 1021.It Fn bus_dmamem_alloc "dmat" "**vaddr" "flags" "*mapp" 1022Allocates memory that is mapped into KVA at the address returned 1023in 1024.Fa vaddr 1025and that is permanently loaded into the newly created 1026.Vt bus_dmamap_t 1027returned via 1028.Fa mapp . 1029Arguments are as follows: 1030.Bl -tag -width ".Fa alignment" 1031.It Fa dmat 1032DMA tag describing the constraints of the DMA mapping. 1033.It Fa vaddr 1034Pointer to a pointer that will hold the returned KVA mapping of 1035the allocated region. 1036.It Fa flags 1037Flags are defined as follows: 1038.Bl -tag -width ".Dv BUS_DMA_NOWAIT" 1039.It Dv BUS_DMA_WAITOK 1040The routine can safely wait (sleep) for resources. 1041.It Dv BUS_DMA_NOWAIT 1042The routine is not allowed to wait for resources. 1043If resources are not available, 1044.Dv ENOMEM 1045is returned. 1046.It Dv BUS_DMA_COHERENT 1047Attempt to map this memory in a coherent fashion. 1048See 1049.Fn bus_dmamap_create 1050above for a description of this flag. 1051For 1052.Fn bus_dmamem_alloc , 1053the 1054.Dv BUS_DMA_COHERENT 1055flag is currently implemented on arm and arm64. 1056.It Dv BUS_DMA_ZERO 1057Causes the allocated memory to be set to all zeros. 1058.It Dv BUS_DMA_NOCACHE 1059The allocated memory will not be cached in the processor caches. 1060All memory accesses appear on the bus and are executed 1061without reordering. 1062For 1063.Fn bus_dmamem_alloc , 1064the 1065.Dv BUS_DMA_NOCACHE 1066flag is currently implemented on amd64 and i386 where it results in the 1067Strong Uncacheable PAT to be set for the allocated virtual address range. 1068.El 1069.It Fa mapp 1070Pointer to a 1071.Vt bus_dmamap_t 1072where the resulting DMA map will be stored. 1073.El 1074.Pp 1075The size of memory to be allocated is 1076.Fa maxsize 1077as specified in the call to 1078.Fn bus_dma_tag_create 1079for 1080.Fa dmat . 1081.Pp 1082The current implementation of 1083.Fn bus_dmamem_alloc 1084will allocate all requests as a single segment. 1085.Pp 1086An initial load operation is required to obtain the bus address of the allocated 1087memory, and an unload operation is required before freeing the memory, as 1088described below in 1089.Fn bus_dmamem_free . 1090Maps are automatically handled by this function and should not be explicitly 1091allocated or destroyed. 1092.Pp 1093Although an explicit load is not required for each access to the memory 1094referenced by the returned map, the synchronization requirements 1095as described in the 1096.Fn bus_dmamap_sync 1097section still apply and should be used to achieve portability on architectures 1098without coherent buses. 1099.Pp 1100Returns 1101.Er ENOMEM 1102if sufficient memory is not available for completing 1103the operation. 1104.It Fn bus_dmamem_free "dmat" "*vaddr" "map" 1105Frees memory previously allocated by 1106.Fn bus_dmamem_alloc . 1107Any mappings 1108will be invalidated. 1109Arguments are as follows: 1110.Bl -tag -width ".Fa vaddr" 1111.It Fa dmat 1112DMA tag. 1113.It Fa vaddr 1114Kernel virtual address of the memory. 1115.It Fa map 1116DMA map to be invalidated. 1117.El 1118.El 1119.Sh RETURN VALUES 1120Behavior is undefined if invalid arguments are passed to 1121any of the above functions. 1122If sufficient resources cannot be allocated for a given 1123transaction, 1124.Er ENOMEM 1125is returned. 1126All 1127routines that are not of type 1128.Vt void 1129will return 0 on success or an error 1130code on failure as discussed above. 1131.Pp 1132All 1133.Vt void 1134routines will succeed if provided with valid arguments. 1135.Sh LOCKING 1136Two locking protocols are used by 1137.Nm . 1138The first is a private global lock that is used to synchronize access to the 1139bounce buffer pool on the architectures that make use of them. 1140This lock is strictly a leaf lock that is only used internally to 1141.Nm 1142and is not exposed to clients of the API. 1143.Pp 1144The second protocol involves protecting various resources stored in the tag. 1145Since almost all 1146.Nm 1147operations are done through requests from the driver that created the tag, 1148the most efficient way to protect the tag resources is through the lock that 1149the driver uses. 1150In cases where 1151.Nm 1152acts on its own without being called by the driver, the lock primitive 1153specified in the tag is acquired and released automatically. 1154An example of this is when the 1155.Fn bus_dmamap_load 1156callback function is called from a deferred context instead of the driver 1157context. 1158This means that certain 1159.Nm 1160functions must always be called with the same lock held that is specified in the 1161tag. 1162These functions include: 1163.Pp 1164.Bl -item -offset indent -compact 1165.It 1166.Fn bus_dmamap_load 1167.It 1168.Fn bus_dmamap_load_bio 1169.It 1170.Fn bus_dmamap_load_ccb 1171.It 1172.Fn bus_dmamap_load_mbuf 1173.It 1174.Fn bus_dmamap_load_mbuf_sg 1175.It 1176.Fn bus_dmamap_load_uio 1177.It 1178.Fn bus_dmamap_unload 1179.It 1180.Fn bus_dmamap_sync 1181.El 1182.Pp 1183There is one exception to this rule. 1184It is common practice to call some of these functions during driver start-up 1185without any locks held. 1186So long as there is a guarantee of no possible concurrent use of the tag by 1187different threads during this operation, it is safe to not hold a lock for 1188these functions. 1189.Pp 1190Certain 1191.Nm 1192operations should not be called with the driver lock held, either because 1193they are already protected by an internal lock, or because they might sleep 1194due to memory or resource allocation. 1195The following functions must not be 1196called with any non-sleepable locks held: 1197.Pp 1198.Bl -item -offset indent -compact 1199.It 1200.Fn bus_dma_tag_create 1201.It 1202.Fn bus_dmamap_create 1203.It 1204.Fn bus_dmamem_alloc 1205.El 1206.Pp 1207All other functions do not have a locking protocol and can thus be 1208called with or without any system or driver locks held. 1209.Sh SEE ALSO 1210.Xr devclass 9 , 1211.Xr device 9 , 1212.Xr driver 9 , 1213.Xr rman 9 , 1214.Xr vslock 9 1215.Pp 1216.Rs 1217.%A "Jason R. Thorpe" 1218.%T "A Machine-Independent DMA Framework for NetBSD" 1219.%J "Proceedings of the Summer 1998 USENIX Technical Conference" 1220.%Q "USENIX Association" 1221.%D "June 1998" 1222.Re 1223.Sh HISTORY 1224The 1225.Nm 1226interface first appeared in 1227.Nx 1.3 . 1228.Pp 1229The 1230.Nm 1231API was adopted from 1232.Nx 1233for use in the CAM SCSI subsystem. 1234The alterations to the original API were aimed to remove the need for 1235a 1236.Vt bus_dma_segment_t 1237array stored in each 1238.Vt bus_dmamap_t 1239while allowing callers to queue up on scarce resources. 1240.Sh AUTHORS 1241The 1242.Nm 1243interface was designed and implemented by 1244.An Jason R. Thorpe 1245of the Numerical Aerospace Simulation Facility, NASA Ames Research Center. 1246Additional input on the 1247.Nm 1248design was provided by 1249.An -nosplit 1250.An Chris Demetriou , 1251.An Charles Hannum , 1252.An Ross Harvey , 1253.An Matthew Jacob , 1254.An Jonathan Stone , 1255and 1256.An Matt Thomas . 1257.Pp 1258The 1259.Nm 1260interface in 1261.Fx 1262benefits from the contributions of 1263.An Justin T. Gibbs , 1264.An Peter Wemm , 1265.An Doug Rabson , 1266.An Matthew N. Dodd , 1267.An Sam Leffler , 1268.An Maxime Henrion , 1269.An Jake Burkholder , 1270.An Takahashi Yoshihiro , 1271.An Scott Long 1272and many others. 1273.Pp 1274This manual page was written by 1275.An Hiten M. Pandya 1276and 1277.An Justin T. Gibbs . 1278