Index for Section 9

Alphabetical listing for D

Bottom of page

dma_map_alloc(9r)
NAME
  dma_map_alloc - General: Allocates resources for DMA data transfers

SYNOPSIS
  #include <io/common/devdriver.h>


  u_long dma_map_alloc(
	  u_long byte_count,
	  struct controller *ctlr_p,
	  dma_handle_t *dma_handle_p,
	  int flags );

ARGUMENTS
  byte_count
      Specifies the maximum size (in bytes) of the data to be transferred
      during the DMA transfer operation. The kernel uses this size to
      determine the resources (mapping registers, I/O channels, and other
      software resources) to allocate.

  ctlr_p
      Specifies a pointer to the controller structure associated with this
      controller. The interface uses this pointer to obtain the bus-specific
      interfaces and data structures that it needs to allocate the necessary
      mapping resources.

  dma_handle_p
      Specifies a pointer to a handle to DMA resources associated with the
      mapping of an in-memory I/O buffer onto a controller's I/O bus. This
      handle provides the information to access bus address/byte count pairs.
      A bus address/byte count pair is represented by the ba and bc members
      of an sg_entry structure pointer. Device driver writers can view the
      DMA handle as the tag to the allocated system resources needed to
      perform a DMA operation. Typically, the device driver passes an
      argument of type dma_handle_t *.	The dma_map_alloc interface returns
      to this variable the address of the DMA handle. The device driver uses
      this address in a call to dma_map_load.

  flags
      Specifies special conditions that the device driver needs the system to
      perform. You can pass the bitwise inclusive OR of the following special
      condition bits defined in /usr/sys/include/io/common/devdriver.h:

      DMA_GUARD_UPPER
	      Allocates additional resources so that contiguous data overruns
	      are captured by the system map error functions. This bit is
	      probably most useful during device driver development and
	      debugging.

      DMA_GUARD_LOWER
	      Allocates additional resources so that contiguous data
	      underruns are captured by the system map error functions. This
	      bit is probably most useful during device driver development
	      and debugging.

      DMA_SLEEP
	      Puts the process to sleep if the system cannot allocate the
	      necessary resources to perform a data transfer of size
	      byte_count at the time the driver calls the interface.

      DMA_IN  Sets up a DMA write into main core memory.

      DMA_OUT Sets up a DMA read from main core memory.

      DMA_ALL Returns a nonzero value, only if the system can satisfy a DMA
	      transfer of size byte_count.

      DMA_CONTIG
	      Signifies a request to the DMA mapping interface to provide a
	      single sg_entry structure mapping of a buffer to which DMA
	      access will be made (on an I/O bus by a DMA engine).

DESCRIPTION
  The dma_map_alloc interface allocates the resources (mapping registers, I/O
  channels, and other hardware and software resources) for DMA data
  transfers. You specify the size of the DMA data transfer in the byte_count
  argument.

  The dma_map_alloc interface returns to the dma_handle_p argument a handle
  to DMA resources associated with the mapping of an in-memory I/O buffer
  onto a controller's I/O bus. Device driver writers can view the DMA handle
  as the tag to the allocated system resources needed to perform a DMA
  operation.

  The dma_map_alloc interface allocates only the necessary resources for a
  device driver to perform a maximum transfer of size byte_count. However,
  the maximum transfer size is the size of the returned byte count if the
  returned byte count is not equal to byte_count. All drivers must be
  prepared for a returned byte count that is less than byte_count. The reason
  for this is that system resources can have physical limits that may never
  satisfy an allocation request of size byte_count. To actually initialize
  and set up the resources, the driver must make a call to dma_map_load.

  The dma_map_alloc interface does not put the process to sleep and returns
  the value zero (0) if both the following are true:

    ·  The driver writer sets the flags argument to DMA_SLEEP

    ·  The specified byte_count exceeds all available system resources; that
       is, the system cannot provide the resources for a data transfer of
       size byte_count

  The DMA_CONTIG flag is a request for contiguous memory space on an I/O bus
  for a virtually mapped buffer in system memory space that may be physically
  discontiguous. The call to the dma_map_alloc or dma_map_load interface with
  the DMA_CONTIG flag will not fail if a contiguous I/O address space cannot
  be used to map the memory buffer, for example, if more than one sg_entry
  structure is returned. The device driver can determine if the DMA_CONTIG
  satisfied the request by comparing the byte count value of the bc member in
  the first returned sg_entry structure to the requested byte count in the
  byte_count argument of the dma_map_alloc or dma_map_load interface.

  This flag is useful for I/O devices whose DMA typically crosses one or more
  (8 Kbyte) pages. This is because system hardware scatter-gather resources
  can be set up and used to do scatter-gather mapping of a virtually
  contiguous, physically discontiguous I/O buffer during the calls to
  dma_map_alloc or dma_map_load. This DMA mapping makes a physically
  discontiguous memory buffer appear physically contiguous to an I/O device
  on an I/O bus.


  Even if an I/O device's DMA engine has scatter-gather resources or support,
  DMA is typically faster if the system scatter-gather resources are used.
  This is due to the system's lower overhead to set up scatter-gather
  resources relative to an I/O device reading and processing multiple
  scatter-gather data structures.

NOTES
  Use of the dma_map_alloc interface makes device drivers more portable
  between DMA hardware-mapping implementations across different hardware
  platforms because it masks out any future changes in the kernel- and
  system-level DMA mapping data structures.

EXAMPLE
  See Writing Device Drivers: Tutorial for a code example of the
  dma_map_alloc interface.

RETURN VALUES
  Upon successful completion, dma_map_alloc returns a byte count (in bytes)
  that indicates the DMA transfer size it can map. It returns the value zero
  (0) to indicate a failure.

  If the device driver sets flags to DMA_ALL, then dma_map_alloc returns a
  nonzero value only if the system can satisfy a transfer size of byte_count.
  This means that if the system cannot support a transfer of size byte_count
  (even if all DMA resources were made available), dma_map_alloc refuses to
  allocate any portion of the resources associated with the specified
  byte_count and returns a byte count of zero (0). This behavior -- no
  allocation of resources unless dma_map_alloc can allocate the resources
  needed to do an uninterruptible transfer of the requested size -- avoids
  extra calls to dma_map_dealloc.

  If the returned byte count equals byte_count, then dma_map_alloc has
  allocated all of the resources necessary to allow the DMA transfer, without
  additional system resource allocation.

  If the returned byte count does not equal byte_count, the device driver can
  perform one of the following tasks:

    ·  Partition the DMA data transfer

       A device driver can partition the DMA data transfer into a byte_count
       that is less than or equal to the returned byte count and then perform
       a sequence of DMA data transfer operations until the transfer has
       completed.

    ·  Release and deallocate resources

       If the device driver needs more resources associated with the
       specified byte_count than dma_map_alloc can allocate, the driver calls
       dma_map_dealloc to release and deallocate these resources. The driver
       then recalls dma_map_alloc (possibly with the DMA_SLEEP flag set)
       until the necessary resources are available.

    ·  Set the DMA_SLEEP bit

       A system can have the necessary resources to perform a DMA transfer of
       size byte_count. However, the resources might not be available at the
       time of the driver's call to dma_map_alloc.  In this case, you set the
       DMA_SLEEP bit in the flags argument. This causes dma_map_alloc to
       block (sleep) until all the resources necessary to perform a DMA
       transfer of size byte_count are available to be allocated.



SEE ALSO
  Kernel Interfaces: dma_map_dealloc(9r), dma_map_load(9r)

  Data Structures: controller(9s), sg_entry(9s)

Index for Section 9

Alphabetical listing for D

Top of page