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 March 27, 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. 621If there is no restriction, 622.Dv BUS_SPACE_UNRESTRICTED 623may be specified. 624.It Fa maxsegsz 625Maximum size, in bytes, of a segment in any DMA mapped region associated 626with 627.Fa dmat . 628.It Fa flags 629Are as follows: 630.Bl -tag -width ".Dv BUS_DMA_ALLOCNOW" 631.It Dv BUS_DMA_ALLOCNOW 632Pre-allocate enough resources to handle at least one map load operation on 633this tag. 634If sufficient resources are not available, 635.Er ENOMEM 636is returned. 637This should not be used for tags that only describe buffers that will be 638allocated with 639.Fn bus_dmamem_alloc . 640Also, due to resource sharing with other tags, this flag does not guarantee 641that resources will be allocated or reserved exclusively for this tag. 642It should be treated only as a minor optimization. 643.It Dv BUS_DMA_COHERENT 644Indicate that the DMA engine and CPU are cache-coherent. 645Cached memory may be used to back allocations created by 646.Fn bus_dmamem_alloc . 647For 648.Fn bus_dma_tag_create , 649the 650.Dv BUS_DMA_COHERENT 651flag is currently implemented on arm64. 652.El 653.It Fa lockfunc 654Optional lock manipulation function (may be 655.Dv NULL ) 656to be called when busdma 657needs to manipulate a lock on behalf of the client. 658If 659.Dv NULL 660is specified, 661.Fn dflt_lock 662is used. 663.It Fa lockfuncarg 664Optional argument to be passed to the function specified by 665.Fa lockfunc . 666.It Fa dmat 667Pointer to a bus_dma_tag_t where the resulting DMA tag will 668be stored. 669.El 670.Pp 671Returns 672.Er ENOMEM 673if sufficient memory is not available for tag creation 674or allocating mapping resources. 675.It Fn bus_dma_tag_destroy "dmat" 676Deallocate the DMA tag 677.Fa dmat 678that was created by 679.Fn bus_dma_tag_create . 680.Pp 681Returns 682.Er EBUSY 683if any DMA maps remain associated with 684.Fa dmat 685or 686.Ql 0 687on success. 688.It Fn bus_dma_template_init "*template" "parent" 689Initializes a 690.Fa bus_dma_template_t 691structure and associates it with an optional 692.Fa parent . 693The 694.Fa parent 695argument may be NULL. 696.It Fn bus_dma_template_tag "*template" "*dmat" 697Unpacks a template into a tag, and returns the tag via the 698.Fa dmat . 699All return values are identical to 700.Fn bus_dma_tag_create . 701.It Fn bus_dma_template_clone "*template" "dmat" 702Clones the fields from a tag to a template. 703This is useful for cloning tags when paired with 704.Fn bus_dma_template_tag . 705A template that is filled in as a clone does not need to be initialized 706first. 707.It Fn bus_dmamap_create "dmat" "flags" "*mapp" 708Allocates and initializes a DMA map. 709Arguments are as follows: 710.Bl -tag -width ".Fa nsegments" 711.It Fa dmat 712DMA tag. 713.It Fa flags 714Are as follows: 715.Bl -tag -width ".Dv BUS_DMA_COHERENT" 716.It Dv BUS_DMA_COHERENT 717Attempt to map the memory loaded with this map such that cache sync 718operations are as cheap as possible. 719This flag is typically set on maps when the memory loaded with these will 720be accessed by both a CPU and a DMA engine, frequently such as control data 721and as opposed to streamable data such as receive and transmit buffers. 722Use of this flag does not remove the requirement of using 723.Fn bus_dmamap_sync , 724but it may reduce the cost of performing these operations. 725.El 726.It Fa mapp 727Pointer to a 728.Vt bus_dmamap_t 729where the resulting DMA map will be stored. 730.El 731.Pp 732Returns 733.Er ENOMEM 734if sufficient memory is not available for creating the 735map or allocating mapping resources. 736.It Fn bus_dmamap_destroy "dmat" "map" 737Frees all resources associated with a given DMA map. 738Arguments are as follows: 739.Bl -tag -width ".Fa dmat" 740.It Fa dmat 741DMA tag used to allocate 742.Fa map . 743.It Fa map 744The DMA map to destroy. 745.El 746.Pp 747Returns 748.Er EBUSY 749if a mapping is still active for 750.Fa map . 751.It Fn bus_dmamap_load "dmat" "map" "buf" "buflen" "*callback" \ 752"callback_arg" "flags" 753Creates a mapping in device visible address space of 754.Fa buflen 755bytes of 756.Fa buf , 757associated with the DMA map 758.Fa map . 759This call will always return immediately and will not block for any reason. 760Arguments are as follows: 761.Bl -tag -width ".Fa buflen" 762.It Fa dmat 763DMA tag used to allocate 764.Fa map . 765.It Fa map 766A DMA map without a currently active mapping. 767.It Fa buf 768A kernel virtual address pointer to a contiguous (in KVA) buffer, to be 769mapped into device visible address space. 770.It Fa buflen 771The size of the buffer. 772.It Fa callback Fa callback_arg 773The callback function, and its argument. 774This function is called once sufficient mapping resources are available for 775the DMA operation. 776If resources are temporarily unavailable, this function will be deferred until 777later, but the load operation will still return immediately to the caller. 778Thus, callers should not assume that the callback will be called before the 779load returns, and code should be structured appropriately to handle this. 780See below for specific flags and error codes that control this behavior. 781.It Fa flags 782Are as follows: 783.Bl -tag -width ".Dv BUS_DMA_NOWAIT" 784.It Dv BUS_DMA_NOWAIT 785The load should not be deferred in case of insufficient mapping resources, 786and instead should return immediately with an appropriate error. 787.It Dv BUS_DMA_NOCACHE 788The generated transactions to and from the virtual page are non-cacheable. 789.El 790.El 791.Pp 792Return values to the caller are as follows: 793.Bl -tag -width ".Er EINPROGRESS" 794.It 0 795The callback has been called and completed. 796The status of the mapping has been delivered to the callback. 797.It Er EINPROGRESS 798The mapping has been deferred for lack of resources. 799The callback will be called as soon as resources are available. 800Callbacks are serviced in FIFO order. 801.Pp 802Note that subsequent load operations for the same tag that do not require 803extra resources will still succeed. 804This may result in out-of-order processing of requests. 805If the caller requires the order of requests to be preserved, 806then the caller is required to stall subsequent requests until a pending 807request's callback is invoked. 808.It Er ENOMEM 809The load request has failed due to insufficient resources, and the caller 810specifically used the 811.Dv BUS_DMA_NOWAIT 812flag. 813.It Er EINVAL 814The load request was invalid. 815The callback has been called and has been provided the same error. 816This error value may indicate that 817.Fa dmat , 818.Fa map , 819.Fa buf , 820or 821.Fa callback 822were invalid, or 823.Fa buflen 824was larger than the 825.Fa maxsize 826argument used to create the dma tag 827.Fa dmat . 828.El 829.Pp 830When the callback is called, it is presented with an error value 831indicating the disposition of the mapping. 832Error may be one of the following: 833.Bl -tag -width ".Er EINPROGRESS" 834.It 0 835The mapping was successful and the 836.Fa dm_segs 837callback argument contains an array of 838.Vt bus_dma_segment_t 839elements describing the mapping. 840This array is only valid during the scope of the callback function. 841.It Er EFBIG 842A mapping could not be achieved within the segment constraints provided 843in the tag even though the requested allocation size was less than maxsize. 844.El 845.It Fn bus_dmamap_load_bio "dmat" "map" "bio" "callback" "callback_arg" "flags" 846This is a variation of 847.Fn bus_dmamap_load 848which maps buffers pointed to by 849.Fa bio 850for DMA transfers. 851.Fa bio 852may point to either a mapped or unmapped buffer. 853.It Fn bus_dmamap_load_ccb "dmat" "map" "ccb" "callback" "callback_arg" "flags" 854This is a variation of 855.Fn bus_dmamap_load 856which maps data pointed to by 857.Fa ccb 858for DMA transfers. 859The data for 860.Fa ccb 861may be any of the following types: 862.Bl -tag -width ".Er CAM_DATA_SG_PADDR" 863.It CAM_DATA_VADDR 864The data is a single KVA buffer. 865.It CAM_DATA_PADDR 866The data is a single bus address range. 867.It CAM_DATA_SG 868The data is a scatter/gather list of KVA buffers. 869.It CAM_DATA_SG_PADDR 870The data is a scatter/gather list of bus address ranges. 871.It CAM_DATA_BIO 872The data is contained in a 873.Vt struct bio 874attached to the CCB. 875.El 876.Pp 877.Fn bus_dmamap_load_ccb 878supports the following CCB XPT function codes: 879.Pp 880.Bl -item -offset indent -compact 881.It 882XPT_ATA_IO 883.It 884XPT_CONT_TARGET_IO 885.It 886XPT_SCSI_IO 887.El 888.It Fn bus_dmamap_load_crp "dmat" "map" "crp" "callback" "callback_arg" "flags" 889This is a variation of 890.Fn bus_dmamap_load 891which maps buffers pointed to by 892.Fa crp 893for DMA transfers. 894The 895.Dv BUS_DMA_NOWAIT 896flag is implied, thus no callback deferral will happen. 897.It Fn bus_dmamap_load_mbuf "dmat" "map" "mbuf" "callback2" "callback_arg" \ 898"flags" 899This is a variation of 900.Fn bus_dmamap_load 901which maps mbuf chains 902for DMA transfers. 903A 904.Vt bus_size_t 905argument is also passed to the callback routine, which 906contains the mbuf chain's packet header length. 907The 908.Dv BUS_DMA_NOWAIT 909flag is implied, thus no callback deferral will happen. 910.Pp 911Mbuf chains are assumed to be in kernel virtual address space. 912.Pp 913Beside the error values listed for 914.Fn bus_dmamap_load , 915.Er EINVAL 916will be returned if the size of the mbuf chain exceeds the maximum limit of the 917DMA tag. 918.It Fn bus_dmamap_load_mbuf_sg "dmat" "map" "mbuf" "segs" "nsegs" "flags" 919This is just like 920.Fn bus_dmamap_load_mbuf 921except that it returns immediately without calling a callback function. 922It is provided for efficiency. 923The scatter/gather segment array 924.Va segs 925is provided by the caller and filled in directly by the function. 926The 927.Va nsegs 928argument is returned with the number of segments filled in. 929Returns the same errors as 930.Fn bus_dmamap_load_mbuf . 931.It Fn bus_dmamap_load_uio "dmat" "map" "uio" "callback2" "callback_arg" "flags" 932This is a variation of 933.Fn bus_dmamap_load 934which maps buffers pointed to by 935.Fa uio 936for DMA transfers. 937A 938.Vt bus_size_t 939argument is also passed to the callback routine, which contains the size of 940.Fa uio , 941i.e. 942.Fa uio->uio_resid . 943The 944.Dv BUS_DMA_NOWAIT 945flag is implied, thus no callback deferral will happen. 946Returns the same errors as 947.Fn bus_dmamap_load . 948.Pp 949If 950.Fa uio->uio_segflg 951is 952.Dv UIO_USERSPACE , 953then it is assumed that the buffer, 954.Fa uio 955is in 956.Fa "uio->uio_td->td_proc" Ns 's 957address space. 958User space memory must be in-core and wired prior to attempting a map 959load operation. 960Pages may be locked using 961.Xr vslock 9 . 962.It Fn bus_dmamap_unload "dmat" "map" 963Unloads a DMA map. 964Arguments are as follows: 965.Bl -tag -width ".Fa dmam" 966.It Fa dmat 967DMA tag used to allocate 968.Fa map . 969.It Fa map 970The DMA map that is to be unloaded. 971.El 972.Pp 973.Fn bus_dmamap_unload 974will not perform any implicit synchronization of DMA buffers. 975This must be done explicitly by a call to 976.Fn bus_dmamap_sync 977prior to unloading the map. 978.It Fn bus_dmamap_sync "dmat" "map" "op" 979Performs synchronization of a device visible mapping with the CPU visible 980memory referenced by that mapping. 981Arguments are as follows: 982.Bl -tag -width ".Fa dmat" 983.It Fa dmat 984DMA tag used to allocate 985.Fa map . 986.It Fa map 987The DMA mapping to be synchronized. 988.It Fa op 989Type of synchronization operation to perform. 990See the definition of 991.Vt bus_dmasync_op_t 992for a description of the acceptable values for 993.Fa op . 994.El 995.Pp 996The 997.Fn bus_dmamap_sync 998function 999is the method used to ensure that CPU's and device's direct 1000memory access (DMA) to shared 1001memory is coherent. 1002For example, the CPU might be used to set up the contents of a buffer 1003that is to be made available to a device. 1004To ensure that the data are visible via the device's mapping of that 1005memory, the buffer must be loaded and a DMA sync operation of 1006.Dv BUS_DMASYNC_PREWRITE 1007must be performed after the CPU has updated the buffer and before the device 1008access is initiated. 1009If the CPU modifies this buffer again later, another 1010.Dv BUS_DMASYNC_PREWRITE 1011sync operation must be performed before an additional device 1012access. 1013Conversely, suppose a device updates memory that is to be read by a CPU. 1014In this case, the buffer must be loaded, and a DMA sync operation of 1015.Dv BUS_DMASYNC_PREREAD 1016must be performed before the device access is initiated. 1017The CPU will only be able to see the results of this memory update 1018once the DMA operation has completed and a 1019.Dv BUS_DMASYNC_POSTREAD 1020sync operation has been performed. 1021.Pp 1022If read and write operations are not preceded and followed by the 1023appropriate synchronization operations, behavior is undefined. 1024.It Fn bus_dmamem_alloc "dmat" "**vaddr" "flags" "*mapp" 1025Allocates memory that is mapped into KVA at the address returned 1026in 1027.Fa vaddr 1028and that is permanently loaded into the newly created 1029.Vt bus_dmamap_t 1030returned via 1031.Fa mapp . 1032Arguments are as follows: 1033.Bl -tag -width ".Fa alignment" 1034.It Fa dmat 1035DMA tag describing the constraints of the DMA mapping. 1036.It Fa vaddr 1037Pointer to a pointer that will hold the returned KVA mapping of 1038the allocated region. 1039.It Fa flags 1040Flags are defined as follows: 1041.Bl -tag -width ".Dv BUS_DMA_NOWAIT" 1042.It Dv BUS_DMA_WAITOK 1043The routine can safely wait (sleep) for resources. 1044.It Dv BUS_DMA_NOWAIT 1045The routine is not allowed to wait for resources. 1046If resources are not available, 1047.Dv ENOMEM 1048is returned. 1049.It Dv BUS_DMA_COHERENT 1050Attempt to map this memory in a coherent fashion. 1051See 1052.Fn bus_dmamap_create 1053above for a description of this flag. 1054For 1055.Fn bus_dmamem_alloc , 1056the 1057.Dv BUS_DMA_COHERENT 1058flag is currently implemented on arm and arm64. 1059.It Dv BUS_DMA_ZERO 1060Causes the allocated memory to be set to all zeros. 1061.It Dv BUS_DMA_NOCACHE 1062The allocated memory will not be cached in the processor caches. 1063All memory accesses appear on the bus and are executed 1064without reordering. 1065For 1066.Fn bus_dmamem_alloc , 1067the 1068.Dv BUS_DMA_NOCACHE 1069flag is currently implemented on amd64 and i386 where it results in the 1070Strong Uncacheable PAT to be set for the allocated virtual address range. 1071.El 1072.It Fa mapp 1073Pointer to a 1074.Vt bus_dmamap_t 1075where the resulting DMA map will be stored. 1076.El 1077.Pp 1078The size of memory to be allocated is 1079.Fa maxsize 1080as specified in the call to 1081.Fn bus_dma_tag_create 1082for 1083.Fa dmat . 1084.Pp 1085The current implementation of 1086.Fn bus_dmamem_alloc 1087will allocate all requests as a single segment. 1088.Pp 1089An initial load operation is required to obtain the bus address of the allocated 1090memory, and an unload operation is required before freeing the memory, as 1091described below in 1092.Fn bus_dmamem_free . 1093Maps are automatically handled by this function and should not be explicitly 1094allocated or destroyed. 1095.Pp 1096Although an explicit load is not required for each access to the memory 1097referenced by the returned map, the synchronization requirements 1098as described in the 1099.Fn bus_dmamap_sync 1100section still apply and should be used to achieve portability on architectures 1101without coherent buses. 1102.Pp 1103Returns 1104.Er ENOMEM 1105if sufficient memory is not available for completing 1106the operation. 1107.It Fn bus_dmamem_free "dmat" "*vaddr" "map" 1108Frees memory previously allocated by 1109.Fn bus_dmamem_alloc . 1110Any mappings 1111will be invalidated. 1112Arguments are as follows: 1113.Bl -tag -width ".Fa vaddr" 1114.It Fa dmat 1115DMA tag. 1116.It Fa vaddr 1117Kernel virtual address of the memory. 1118.It Fa map 1119DMA map to be invalidated. 1120.El 1121.El 1122.Sh RETURN VALUES 1123Behavior is undefined if invalid arguments are passed to 1124any of the above functions. 1125If sufficient resources cannot be allocated for a given 1126transaction, 1127.Er ENOMEM 1128is returned. 1129All 1130routines that are not of type 1131.Vt void 1132will return 0 on success or an error 1133code on failure as discussed above. 1134.Pp 1135All 1136.Vt void 1137routines will succeed if provided with valid arguments. 1138.Sh LOCKING 1139Two locking protocols are used by 1140.Nm . 1141The first is a private global lock that is used to synchronize access to the 1142bounce buffer pool on the architectures that make use of them. 1143This lock is strictly a leaf lock that is only used internally to 1144.Nm 1145and is not exposed to clients of the API. 1146.Pp 1147The second protocol involves protecting various resources stored in the tag. 1148Since almost all 1149.Nm 1150operations are done through requests from the driver that created the tag, 1151the most efficient way to protect the tag resources is through the lock that 1152the driver uses. 1153In cases where 1154.Nm 1155acts on its own without being called by the driver, the lock primitive 1156specified in the tag is acquired and released automatically. 1157An example of this is when the 1158.Fn bus_dmamap_load 1159callback function is called from a deferred context instead of the driver 1160context. 1161This means that certain 1162.Nm 1163functions must always be called with the same lock held that is specified in the 1164tag. 1165These functions include: 1166.Pp 1167.Bl -item -offset indent -compact 1168.It 1169.Fn bus_dmamap_load 1170.It 1171.Fn bus_dmamap_load_bio 1172.It 1173.Fn bus_dmamap_load_ccb 1174.It 1175.Fn bus_dmamap_load_mbuf 1176.It 1177.Fn bus_dmamap_load_mbuf_sg 1178.It 1179.Fn bus_dmamap_load_uio 1180.It 1181.Fn bus_dmamap_unload 1182.It 1183.Fn bus_dmamap_sync 1184.El 1185.Pp 1186There is one exception to this rule. 1187It is common practice to call some of these functions during driver start-up 1188without any locks held. 1189So long as there is a guarantee of no possible concurrent use of the tag by 1190different threads during this operation, it is safe to not hold a lock for 1191these functions. 1192.Pp 1193Certain 1194.Nm 1195operations should not be called with the driver lock held, either because 1196they are already protected by an internal lock, or because they might sleep 1197due to memory or resource allocation. 1198The following functions must not be 1199called with any non-sleepable locks held: 1200.Pp 1201.Bl -item -offset indent -compact 1202.It 1203.Fn bus_dma_tag_create 1204.It 1205.Fn bus_dmamap_create 1206.It 1207.Fn bus_dmamem_alloc 1208.El 1209.Pp 1210All other functions do not have a locking protocol and can thus be 1211called with or without any system or driver locks held. 1212.Sh SEE ALSO 1213.Xr devclass 9 , 1214.Xr device 9 , 1215.Xr driver 9 , 1216.Xr rman 9 , 1217.Xr vslock 9 1218.Pp 1219.Rs 1220.%A "Jason R. Thorpe" 1221.%T "A Machine-Independent DMA Framework for NetBSD" 1222.%J "Proceedings of the Summer 1998 USENIX Technical Conference" 1223.%Q "USENIX Association" 1224.%D "June 1998" 1225.Re 1226.Sh HISTORY 1227The 1228.Nm 1229interface first appeared in 1230.Nx 1.3 . 1231.Pp 1232The 1233.Nm 1234API was adopted from 1235.Nx 1236for use in the CAM SCSI subsystem. 1237The alterations to the original API were aimed to remove the need for 1238a 1239.Vt bus_dma_segment_t 1240array stored in each 1241.Vt bus_dmamap_t 1242while allowing callers to queue up on scarce resources. 1243.Sh AUTHORS 1244The 1245.Nm 1246interface was designed and implemented by 1247.An Jason R. Thorpe 1248of the Numerical Aerospace Simulation Facility, NASA Ames Research Center. 1249Additional input on the 1250.Nm 1251design was provided by 1252.An -nosplit 1253.An Chris Demetriou , 1254.An Charles Hannum , 1255.An Ross Harvey , 1256.An Matthew Jacob , 1257.An Jonathan Stone , 1258and 1259.An Matt Thomas . 1260.Pp 1261The 1262.Nm 1263interface in 1264.Fx 1265benefits from the contributions of 1266.An Justin T. Gibbs , 1267.An Peter Wemm , 1268.An Doug Rabson , 1269.An Matthew N. Dodd , 1270.An Sam Leffler , 1271.An Maxime Henrion , 1272.An Jake Burkholder , 1273.An Takahashi Yoshihiro , 1274.An Scott Long 1275and many others. 1276.Pp 1277This manual page was written by 1278.An Hiten M. Pandya 1279and 1280.An Justin T. Gibbs . 1281