File:  [DragonFly] / src / share / man / man9 / bus_dma.9
Revision 1.2: download - view: text, annotated - select for diffs
Fri May 14 16:23:17 2004 UTC (10 years, 4 months ago) by hmp
Branches: MAIN
CVS tags: HEAD, DragonFly_1_0_REL, DragonFly_1_0_RC1, DragonFly_1_0A_REL
Remove an extra comma at the end of .Nm list.

    1: .\" Copyright (c) 2002, 2003, 2004 Hiten Pandya <hmp@backplane.com>
    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: .\" 3. All advertising materials mentioning features or use of this software
   41: .\"    must display the following acknowledgment:
   42: .\" 	This product includes software developed by the NetBSD
   43: .\" 	Foundation, Inc. and its contributors.
   44: .\" 4. Neither the name of The NetBSD Foundation nor the names of its
   45: .\"    contributors may be used to endorse or promote products derived
   46: .\"    from this software without specific prior written permission.
   47: .\"
   48: .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
   49: .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
   50: .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
   51: .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
   52: .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
   53: .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
   54: .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
   55: .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
   56: .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
   57: .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
   58: .\" POSSIBILITY OF SUCH DAMAGE.
   59: .\"
   60: .\" $FreeBSD: /repoman/r/ncvs/src/share/man/man9/bus_dma.9,v 1.7 2003/07/27 14:05:29 mux Exp $
   61: .\" $NetBSD: bus_dma.9,v 1.25 2002/10/14 13:43:16 wiz Exp $
   62: .\" $DragonFly: src/share/man/man9/bus_dma.9,v 1.2 2004/05/14 16:23:17 hmp Exp $
   63: .\"
   64: .Dd March 17, 2004
   65: .Dt BUS_DMA 9
   66: .Os
   67: .Sh NAME
   68: .Nm bus_dma ,
   69: .Nm bus_dma_tag_create ,
   70: .Nm bus_dma_tag_destroy ,
   71: .Nm bus_dmamap_create ,
   72: .Nm bus_dmamap_destroy ,
   73: .Nm bus_dmamap_load ,
   74: .Nm bus_dmamap_load_mbuf ,
   75: .Nm bus_dmamap_load_uio ,
   76: .Nm bus_dmamap_unload ,
   77: .Nm bus_dmamap_sync ,
   78: .Nm bus_dmamem_alloc ,
   79: .Nm bus_dmamem_free
   80: .Nd Bus and Machine Independent DMA Mapping Interface
   81: .Sh SYNOPSIS
   82: .In machine/bus.h
   83: .Ft int
   84: .Fn bus_dma_tag_create "bus_dma_tag_t parent" "bus_size_t alignment" \
   85: "bus_size_t boundary" "bus_addr_t lowaddr" "bus_addr_t highaddr" \
   86: "bus_dma_filter_t *filtfunc" "void *filtfuncarg" "bus_size_t maxsize" \
   87: "int nsegments" "bus_size_t maxsegsz" "int flags" "bus_dma_tag_t *dmat"
   88: .Ft int
   89: .Fn bus_dma_tag_destroy "bus_dma_tag_t dmat"
   90: .Ft int
   91: .Fn bus_dmamap_create "bus_dma_tag_t dmat" "int flags" "bus_dmamap_t *mapp"
   92: .Ft int
   93: .Fn bus_dmamap_destroy "bus_dma_tag_t dmat" "bus_dmamap_t map"
   94: .Ft int
   95: .Fn bus_dmamap_load "bus_dma_tag_t dmat" "bus_dmamap_t map" "void *buf" \
   96: "bus_size_t buflen" "bus_dmamap_callback_t *callback" "void *callback_arg" \
   97: "int flags"
   98: .Ft int
   99: .Fn bus_dmamap_load_mbuf "bus_dma_tag_t dmat" "bus_dmamap_t map" \
  100: "struct mbuf *mbuf" "bus_dmamap_callback2_t *callback" "void *callback_arg" \
  101: "int flags"
  102: .Ft int
  103: .Fn bus_dmamap_load_uio "bus_dma_tag_t dmat" "bus_dmamap_t map" \
  104: "struct uio *uio" "bus_dmamap_callback2_t *callback" "void *callback_arg" \
  105: "int flags"
  106: .Ft int
  107: .Fn bus_dmamem_alloc "bus_dma_tag_t dmat" "void **vaddr" \
  108: "int flags" "bus_dmamap_t *mapp"
  109: .Ft void
  110: .Fn bus_dmamap_unload "bus_dma_tag_t dmat" "bus_dmamap_t map"
  111: .Ft void
  112: .Fn bus_dmamap_sync "bus_dma_tag_t dmat" "bus_dmamap_t map" \
  113: "op"
  114: .Ft void
  115: .Fn bus_dmamem_free "bus_dma_tag_t dmat" "void *vaddr" \
  116: "bus_dmamap_t map"
  117: .Sh DESCRIPTION
  118: Direct Memory Access (DMA) is a method of transferring data
  119: without involving the CPU, thus providing higher performance.
  120: A DMA transaction can be achieved between device to memory,
  121: device to device, or memory to memory.
  122: .Pp
  123: The
  124: .Nm
  125: API is a bus, device, and machine-independent (MI) interface to
  126: DMA mechanisms.
  127: It provides the client with flexibility and simplicity by
  128: abstracting machine dependent issues like setting up
  129: DMA mappings, handling cache issues, bus specific features
  130: and limitations.
  131: .Sh STRUCTURES AND TYPES
  132: .Bl -tag -width compact
  133: .It Vt bus_dma_tag_t
  134: A machine-dependent (MD) opaque type that describes the
  135: characteristics of DMA transactions.
  136: DMA tags are organized into a hierarchy, with each child
  137: tag inheriting the restrictions of its parent.
  138: This allows all devices along the path of DMA transactions
  139: to contribute to the constraints of those transactions.
  140: .It Vt bus_dma_filter_t
  141: Client specified address filter having the format:
  142: .Bl -tag -width compact
  143: .It Ft int
  144: .Fn "client_filter" "void *filtarg" "bus_addr_t testaddr"
  145: .El
  146: .sp
  147: Address filters can be specified during tag creation to allow
  148: for devices who's DMA address restrictions cannot be specified
  149: by a single window.
  150: The
  151: .Fa filtarg
  152: is client specified during tag creation to be passed to all
  153: invocations of the callback.
  154: The
  155: .Fa testaddr
  156: argument contains a potential starting address of a DMA mapping.
  157: The filter function operates on the set of addresses from
  158: .Fa testaddr
  159: to
  160: .Ql trunc_page(testaddr) + PAGE_SIZE - 1 ,
  161: inclusive.
  162: The filter function should return zero for any mapping in this range
  163: that can be accommodated by the device and non-zero otherwise.
  164: .It Vt bus_dma_segment_t
  165: A machine-dependent type that describes individual
  166: DMA segments.
  167: .Bd -literal
  168: 	bus_addr_t	ds_addr;
  169: 	bus_size_t	ds_len;
  170: .Ed
  171: .sp
  172: The
  173: .Fa ds_addr
  174: field contains the device visible address of the DMA segment, and
  175: .Fa ds_len
  176: contains the length of the DMA segment.
  177: Although the DMA segments returned by a mapping call will adhere to
  178: all restrictions necessary for a successful DMA operation, some conversion
  179: (e.g. a conversion from host byte order to the device's byte order) is
  180: almost always required when presenting segment information to the device.
  181: .It Vt bus_dmamap_t
  182: A machine-dependent opaque type describing an individual mapping.
  183: Multiple DMA maps can be associated with one DMA tag.
  184: .It Vt bus_dmamap_callback_t
  185: Client specified callback for receiving mapping information resulting from
  186: the load of a
  187: .Vt bus_dmamap_t
  188: via
  189: .Fn bus_dmamap_load .
  190: Callbacks are of the format:
  191: .Bl -tag -width compact
  192: .It Ft void
  193: .Fn "client_callback" "void *callback_arg" "bus_dma_segment_t *segs" \
  194: "int nseg" "int error"
  195: .El
  196: .sp
  197: The
  198: .Fa callback_arg
  199: is the callback argument passed to dmamap load functions.
  200: The 
  201: .Fa segs
  202: and
  203: .Fa nseg
  204: parameters describe an array of
  205: .Vt bus_dma_segment_t
  206: structures that represent the mapping.
  207: This array is only valid within the scope of the callback function.
  208: The success or failure of the mapping is indicated by the
  209: .Fa error
  210: parameter.
  211: More information on the use of callbacks can be found in the
  212: description of the individual dmamap load functions.
  213: .It Vt bus_dmamap_callback2_t
  214: Client specified callback for receiving mapping information resulting from
  215: the load of a
  216: .Vt bus_dmamap_t
  217: via
  218: .Fn bus_dmamap_load_uio
  219: or 
  220: .Fn bus_dmamap_load_mbuf .
  221: .sp
  222: Callback2s are of the format:
  223: .Bl -tag -width compact
  224: .It Ft void
  225: .Fn "client_callback2" "void *callback_arg" "bus_dma_segment_t *segs" \
  226: "int nseg" "bus_size_t mapsize" "int error"
  227: .El
  228: .sp
  229: Callback2's behavior is the same as
  230: .Vt bus_dmamap_callback_t
  231: with the addition that the length of the data mapped is provided via
  232: .Fa mapsize .
  233: .It Vt bus_dmasync_op_t
  234: Memory synchronization operation specifier.
  235: Bus DMA requires explicit synchronization of memory with it's device
  236: visible mapping in order to guarantee memory coherency.
  237: The
  238: .Vt bus_dmasync_op_t
  239: allows the type of DMA operation that will be or has been performed
  240: to be communicated to the system so that the correct coherency measures
  241: are taken.
  242: All operations specified below are performed from the DMA engine's
  243: point of view:
  244: .Bl -tag -width BUS_DMASYNC_POSTWRITE
  245: .It Dv BUS_DMASYNC_PREREAD
  246: Perform any synchronization required after an update of memory by the CPU
  247: but prior to DMA read operations.
  248: .It Dv BUS_DMASYNC_PREWRITE
  249: Perform any synchronization required after an update of memory by the CPU
  250: but prior to DMA write operations.
  251: .It Dv BUS_DMASYNC_PREREAD|BUS_DMASYNC_PREWRITE
  252: Perform any synchronization required prior to a combination of DMA read
  253: and write operations.
  254: .It Dv BUS_DMASYNC_POSTREAD
  255: Perform any synchronization required after DMA read operations, but prior
  256: to CPU access of the memory.
  257: .It Dv BUS_DMASYNC_POSTWRITE
  258: Perform any synchronization required after DMA write operations, but prior
  259: to CPU access of the memory.
  260: .It Dv BUS_DMASYNC_POSTREAD|BUS_DMASYNC_POSTWRITE
  261: Perform any synchronization required after a combination of DMA read
  262: and write operations.
  263: .El
  264: .El
  265: .sp
  266: .Sh FUNCTIONS
  267: .Bl -tag -width compact
  268: .It Fn bus_dma_tag_create "parent" "alignment" "boundary" "lowaddr" \
  269: "highaddr" "*filtfunc" "*filtfuncarg" "maxsize" "nsegments" "maxsegsz" \
  270: "flags" "*dmat"
  271: Allocates a device specific DMA tag, and initializes it according to
  272: the arguments provided:
  273: .Bl -tag -width *filtfuncarg -compact
  274: .It Fa parent
  275: Indicates restrictions between the parent bridge, CPU memory, and the
  276: device.
  277: May be NULL, if no DMA restrictions are to be inherited.
  278: .It Fa alignment
  279: Alignment constraint, in bytes, of any mappings created using this tag.
  280: The alignment must be a power of 2.
  281: Hardware that can DMA starting at any address would specify
  282: .Em 1
  283: for byte alignment.
  284: Hardware requiring DMA transfers to start on a multiple of 4K
  285: would specify
  286: .Em 4096.
  287: .It Fa boundary
  288: Boundary constraint, in bytes, of the target DMA memory region.
  289: The boundary indicates the set of addresses, all multiples of the
  290: boundary argument, that cannot be crossed by a single
  291: .Vt bus_dma_segment_t .
  292: The boundary must be either a power of 2 or 0.
  293: .Ql 0
  294: indicates that there are no boundary restrictions.
  295: .It Fa lowaddr
  296: .It Fa highaddr
  297: Bounds of the window of bus address space that
  298: .Em cannot
  299: be directly accessed by the device.
  300: The window contains all address greater than lowaddr and
  301: less than or equal to highaddr.
  302: For example, a device incapable of DMA above 4GB, would specify
  303: a highaddr of
  304: .Dv BUS_SPACE_MAXADDR
  305: and a lowaddr of
  306: .Dv BUS_SPACE_MAXADDR_32BIT .
  307: Similarly a device that can only dma to addresses bellow 16MB would
  308: specify a highaddr of
  309: .Dv BUS_SPACE_MAXADDR
  310: and a lowaddr of
  311: .Dv BUS_SPACE_MAXADDR_24BIT .
  312: Some implementations requires that some region of device visible
  313: address space, overlapping available host memory, be outside the
  314: window.
  315: This area of
  316: .Ql safe memory
  317: is used to bounce requests that would otherwise conflict with
  318: the exclusion window.
  319: .It Fa filtfunc
  320: Optional filter function (may be NULL) to be called for any attempt to
  321: map memory into the window described by
  322: .Fa lowaddr
  323: and
  324: .Fa highaddr.
  325: A filter function is only required when the single window described
  326: by
  327: .Fa lowaddr
  328: and
  329: .Fa highaddr
  330: cannot adequately describe the constraints of the device.
  331: The filter function will be called for every machine page
  332: that overlaps the exclusion window.
  333: .It Fa filtfuncarg
  334: Argument passed to all calls to the filter function for this tag.
  335: May be NULL.
  336: .It Fa maxsize
  337: Maximum size, in bytes, of the sum of all segment lengths in a given
  338: DMA mapping associated with this tag.
  339: .It Fa nsegments
  340: Number of discontinuities (scatter/gather segments) allowed
  341: in a DMA mapped region.
  342: If there is no restriction, 
  343: .Dv BUS_SPACE_UNRESTRICTED
  344: may be specified.
  345: .It Fa maxsegsz
  346: Maximum size, in bytes, of a segment in any DMA mapped region associated
  347: with
  348: .Fa dmat .
  349: .It Fa flags
  350: Are as follows:
  351: .Bl -tag -width "BUS_DMA_ALLOCNOW" -compact
  352: .It Dv BUS_DMA_ALLOCNOW
  353: Allocate the resources necessary to guarantee that all map load
  354: operations associated with this tag will not block.
  355: If sufficient resources are not available,
  356: .Er ENOMEM
  357: is returned.
  358: .El
  359: .It Fa dmat
  360: Pointer to a bus_dma_tag_t where the resulting DMA tag will 
  361: be stored.
  362: .El
  363: .Pp
  364: Returns
  365: .Er ENOMEM
  366: if sufficient memory is not available for tag creation
  367: or allocating mapping resources.
  368: .It Fn bus_dma_tag_destroy "dmat"
  369: Deallocate the DMA tag
  370: .Fa dmat
  371: that was created by
  372: .Fn bus_dma_tag_create .
  373: .Pp
  374: Returns
  375: .Er EBUSY
  376: if any DMA maps remain associated with
  377: .Fa dmat
  378: or
  379: .Ql 0
  380: on success.
  381: .It Fn bus_dmamap_create "dmat" "flags" "*mapp"
  382: Allocates and initializes a DMA map.
  383: Arguments are as follows:
  384: .Bl -tag -width nsegments -compact
  385: .It Fa dmat
  386: DMA tag.
  387: .It Fa flags
  388: The value of this argument is currently undefined and should be
  389: specified as
  390: .Ql 0 .
  391: .It Fa mapp
  392: Pointer to a
  393: .Vt bus_dmamap_t
  394: where the resulting DMA map will be stored.
  395: .El
  396: .Pp
  397: Returns
  398: .Er ENOMEM
  399: if sufficient memory is not available for creating the
  400: map or allocating mapping resources.
  401: .It Fn bus_dmamap_destroy "dmat" "map"
  402: Frees all resources associated with a given DMA map.
  403: Arguments are as follows:
  404: .Bl -tag -width dmat -compact
  405: .It Fa dmat
  406: DMA tag used to allocate
  407: .Fa map .
  408: .It Fa map
  409: The DMA map to destroy.
  410: .El
  411: .Pp
  412: Returns
  413: .Er EBUSY
  414: if a mapping is still active for
  415: .Fa map .
  416: .It Fn bus_dmamap_load "dmat" "map" "buf" "buflen" "*callback" "..."
  417: Creates a mapping in device visible address space of
  418: .Fa buflen
  419: bytes of
  420: .Fa buf ,
  421: associated with the DMA map
  422: .Fa map.
  423: Arguments are as follows:
  424: .Bl -tag -width buflen -compact
  425: .It Fa dmat
  426: DMA tag used to allocate
  427: .Fa map.
  428: .It Fa map
  429: A DMA map without a currently active mapping.
  430: .It Fa buf
  431: A kernel virtual address pointer to a contiguous (in KVA) buffer, to be
  432: mapped into device visible address space.
  433: .It Fa buflen
  434: The size of the buffer.
  435: .It Fa callback Fa callback_arg
  436: The callback function, and its argument.
  437: .It Fa flags
  438: The value of this argument is currently undefined, and should be
  439: specified as
  440: .Ql 0 .
  441: .El
  442: .Pp
  443: Return values to the caller are as follows:
  444: .Bl -tag -width EINPROGRESS -compact
  445: .It 0
  446: The callback has been called and completed.
  447: The status of the mapping has been delivered to the callback.
  448: .It Er EINPROGRESS
  449: The mapping has been deferred for lack of resources.
  450: The callback will be called as soon as resources are available.
  451: Callbacks are serviced in FIFO order.
  452: DMA maps created from DMA tags that are allocated with
  453: the
  454: .Dv BUS_DMA_ALLOCNOW
  455: flag will never return this status for a load operation.
  456: .It Er EINVAL
  457: The load request was invalid.
  458: The callback has not, and will not be called.
  459: This error value may indicate that
  460: .Fa dmat ,
  461: .Fa map ,
  462: .Fa buf ,
  463: or
  464: .Fa callback
  465: were invalid, or
  466: .Fa buslen
  467: was larger than the
  468: .Fa maxsize
  469: argument used to create the dma tag
  470: .Fa dmat .
  471: .El
  472: .Pp
  473: When the callback is called, it is presented with an error value
  474: indicating the disposition of the mapping.
  475: Error may be one of the following:
  476: .Bl -tag -width EINPROGRESS -compact
  477: .It 0
  478: The mapping was successful and the
  479: .Fa dm_segs
  480: callback argument contains an array of
  481: .Vt bus_dma_segment_t
  482: elements describing the mapping.
  483: This array is only valid during the scope of the callback function.
  484: .It Er EFBIG
  485: A mapping could not be achieved within the segment constraints provided
  486: in the tag even though the requested allocation size was less than maxsize.
  487: .El
  488: .It Fn bus_dmamap_load_mbuf "dmat" "map" "mbuf" "callback2" "callback_arg" \
  489: "flags"
  490: This is a variation of
  491: .Fn bus_dmamap_load
  492: which maps mbuf chains
  493: for DMA transfers.
  494: A
  495: .Vt bus_size_t
  496: argument is also passed to the callback routine, which
  497: contains the mbuf chain's packet header length.
  498: .Pp
  499: Mbuf chains are assumed to be in kernel virtual address space.
  500: .Pp
  501: Returns
  502: .Er EINVAL
  503: if the size of the mbuf chain exceeds the maximum limit of the
  504: DMA tag.
  505: .It Fn bus_dmamap_load_uio "dmat" "map" "uio" "callback2" "callback_arg" "flags"
  506: This is a variation of
  507: .Fn bus_dmamap_load
  508: which maps buffers pointed to by
  509: .Fa uio
  510: for DMA transfers.
  511: A
  512: .Vt bus_size_t
  513: argument is also passed to the callback routine, which contains the size of
  514: .Fa uio ,
  515: i.e.
  516: .Fa uio->uio_resid .
  517: .Pp
  518: If
  519: .Fa uio->uio_segflg
  520: is
  521: .Dv UIO_USERSPACE ,
  522: then it is assumed that the buffer,
  523: .Fa uio
  524: is in
  525: .Fa "uio->uio_td->td_proc" Ns 's
  526: address space.
  527: User space memory must be in-core and wired prior to attempting a map
  528: load operation.
  529: .It Fn bus_dmamap_unload "dmat" "map"
  530: Unloads a DMA map.
  531: Arguments are as follows:
  532: .Bl -tag -width dmam -compact
  533: .It Fa dmat
  534: DMA tag used to allocate
  535: .Fa map .
  536: .It Fa map
  537: The DMA map that is to be unloaded.
  538: .El
  539: .Pp
  540: .Fn bus_dmamap_unload
  541: will not perform any implicit synchronization of DMA buffers.
  542: This must be done explicitly by a call to
  543: .Fn bus_dmamap_sync
  544: prior to unloading the map.
  545: .It Fn bus_dmamap_sync "dmat" "map" "op"
  546: Performs synchronization of a device visible mapping with the CPU visible
  547: memory referenced by that mapping.
  548: Arguments are as follows:
  549: .Bl -tag -width dmat -compact
  550: .It Fa dmat
  551: DMA tag used to allocate
  552: .Fa map .
  553: .It Fa map
  554: The DMA mapping to be synchronized.
  555: .It Fa op
  556: Type of synchronization operation to perform.
  557: See the definition of
  558: .Vt bus_dmasync_op_t
  559: for a description of the acceptable values for
  560: .Fa op .
  561: .El
  562: .Pp
  563: .Fn bus_dmamap_sync
  564: is the method used to ensure that CPU and device DMA access to shared
  565: memory is coherent.
  566: For example, the CPU might be used to setup the contents of a buffer
  567: that is to be DMA'ed into a device.
  568: To ensure that the data are visible via the device's mapping of that
  569: memory, the buffer must be loaded and a dma sync operation of
  570: .Dv BUS_DMASYNC_PREREAD
  571: must be performed.
  572: Additional sync operations must be performed after every CPU write
  573: to this memory if additional DMA reads are to be performed.
  574: Conversely, for the DMA write case, the buffer must be loaded,
  575: and a dma sync operation of
  576: .Dv BUS_DMASYNC_PREWRITE
  577: must be performed.
  578: The CPU will only be able to see the results of this DMA write
  579: once the DMA has completed and a
  580: .Dv BUS_DMASYNC_POSTWRITE
  581: operation has been performed.
  582: .Pp
  583: If DMA read and write operations are not preceded and followed by the
  584: appropriate synchronization operations, behavior is undefined.
  585: .It Fn bus_dmamem_alloc "dmat" "**vaddr" "flags" "mapp"
  586: Allocates memory that is mapped into KVA at the address returned
  587: in
  588: .Fa vaddr
  589: that is permanently loaded into the newly created
  590: .Vt bus_dmamap_t
  591: returned via
  592: .Fa mapp .
  593: Arguments are as follows:
  594: .Bl -tag -width alignment -compact
  595: .It Fa dmat 
  596: DMA tag describing the constraints of the DMA mapping.
  597: .It Fa vaddr
  598: Pointer to a pointer that will hold the returned KVA mapping of
  599: the allocated region.
  600: .It Fa flags
  601: Flags are defined as follows:
  602: .Bl -tag -width BUS_DMA_NOWAIT -compact
  603: .It Dv BUS_DMA_WAITOK
  604: The routine can safely wait (sleep) for resources.
  605: .It Dv BUS_DMA_NOWAIT
  606: The routine is not allowed to wait for resources.
  607: If resources are not available, 
  608: .Dv ENOMEM
  609: is returned.
  610: .It Dv BUS_DMA_COHERENT
  611: Attempt to map this memory such that cache sync operations are
  612: as cheap as possible.
  613: This flag is typically set on memory that will be accessed by both
  614: a CPU and a DMA engine, frequently.
  615: Use of this flag does not remove the requirement of using
  616: bus_dmamap_sync, but it may reduce the cost of performing
  617: these operations.
  618: .It Dv BUS_DMA_ZERO
  619: Causes the allocated memory to be set to all zeros.
  620: .El
  621: .It Fa mapp
  622: Pointer to storage for the returned DMA map.
  623: .El
  624: .Pp
  625: The size of memory to be allocated is
  626: .Fa maxsize
  627: as specified in
  628: .Fa dmat .
  629: .Pp
  630: The current implementation of
  631: .Fn bus_dmamem_alloc
  632: will allocate all requests as a single segment.
  633: .Pp
  634: Although no explicit loading is required to access the memory
  635: referenced by the returned map, the synchronization requirements
  636: as described in the
  637: .Fn bus_dmamap_sync
  638: section still apply.
  639: .Pp
  640: Returns
  641: .Er ENOMEM
  642: if sufficient memory is not available for completing
  643: the operation.
  644: .It Fn bus_dmamem_free "dmat" "*vaddr" "map"
  645: Frees memory previously allocated by
  646: .Fn bus_dmamem_alloc .
  647: Any mappings
  648: will be invalidated.
  649: Arguments are as follows:
  650: .Bl -tag -width vaddr -compact
  651: .It Fa dmat
  652: DMA tag.
  653: .It Fa vaddr
  654: Kernel virtual address of the memory.
  655: .It Fa map
  656: DMA map to be invalidated.
  657: .El
  658: .El
  659: .Sh RETURN VALUES
  660: Behavior is undefined if invalid arguments are passed to
  661: any of the above functions.
  662: If sufficient resources cannot be allocated for a given
  663: transaction,
  664: .Er ENOMEM
  665: is returned.
  666: All
  667: routines that are not of type,
  668: .Vt void ,
  669: will return 0 on success or an error
  670: code, as discussed above.
  671: .Pp
  672: All
  673: .Vt void
  674: routines will succeed if provided with valid arguments.
  675: .Sh SEE ALSO
  676: .Xr devclass 9 ,
  677: .Xr device 9 ,
  678: .Xr driver 9 ,
  679: .Xr rman 9
  680: .Pp
  681: .Rs
  682: .%A "Jason R. Thorpe"
  683: .%T "A Machine-Independent DMA Framework for NetBSD"
  684: .%J "Proceedings of the Summer 1998 USENIX Technical Conference"
  685: .%Q "USENIX Association"
  686: .%D "June 1998"
  687: .Re
  688: .Sh HISTORY
  689: The
  690: .Nm
  691: interface first appeared in
  692: .Nx 1.3 .
  693: .Pp
  694: The
  695: .Nm
  696: API was adopted from
  697: .Nx
  698: for use in the CAM SCSI subsystem.
  699: The alterations to the original API were aimed to remove the need for
  700: a
  701: .Vt bus_dma_segment_t
  702: array stored in each
  703: .Vt bus_dmamap_t
  704: while allowing callers to queue up on scarce resources.
  705: .Sh AUTHORS
  706: The
  707: .Nm
  708: interface was designed and implemented by
  709: .An Jason R. Thorpe
  710: of the Numerical Aerospace Simulation Facility, NASA Ames Research Center.
  711: Additional input on the
  712: .Nm
  713: design was provided by
  714: .An -nosplit
  715: .An Chris Demetriou ,
  716: .An Charles Hannum ,
  717: .An Ross Harvey ,
  718: .An Matthew Jacob ,
  719: .An Jonathan Stone ,
  720: and
  721: .An Matt Thomas .
  722: .Pp
  723: This manual page was written by
  724: .An Hiten Pandya
  725: and
  726: .An Justin T. Gibbs .