Index for Section 9

Alphabetical listing for D

Bottom of page

dma_map_load(9r)
NAME
  dma_map_load - General: Loads and sets allocated DMA resources and sets up
  a DMA data path for DMA data transfers

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


  u_long dma_map_load(
	  u_long byte_count,
	  vm_offset_t virt_addr,
	  struct proc* *proc_p,
	  struct controller* *ctlr_p,
	  dma_handle_t* *dma_handle_p,
	  u_long max_byte_count,
	  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, load, and set.

  virt_addr
      Specifies the virtual address where the DMA transfer occurs.  The
      interface uses this address with the pointer to the proc structure to
      obtain the physical addresses of the system memory pages to load into
      DMA mapping resources.

  proc_p
      Specifies a pointer to the proc structure associated with the valid
      context for the virtual address specified in virt_addr. The interface
      uses this pointer to retrieve the pmap that is needed to translate this
      virtual address to a physical address. If proc_p is equal to zero (0),
      the address is a kernel address.

  ctlr_p
      Specifies a pointer to the controller structure associated with this
      controller. The dma_map_load interface uses the pointer to get the
      bus-specific interfaces and data structures that it needs to load and
      set 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 *.	If the device driver called
      dma_map_alloc prior to calling dma_map_load, then dma_map_alloc returns
      to this argument the address of the allocated DMA handle. The
      dma_map_load interface can then use this handle to load the appropriate
      DMA mapping resources. If the device driver did not call dma_map_alloc
      prior to calling dma_map_load, then you must set the dma_handle_p
      argument to the value zero (0).  Upon completing execution,
      dma_map_load returns a valid DMA handle to dma_handle_p.

  max_byte_count
      Specifies the maximum-size byte-count value that should be stored in
      the bc members of the sg_entry structures.

  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_load interface loads and sets the system resources necessary to
  perform a DMA transfer of size byte_count to the virtual address specified
  in the virt_addr argument. This virtual address must be valid in the
  context of the process's proc structure, specified in the proc_p argument.

  If the device driver calls dma_map_alloc prior to calling dma_map_load,
  then dma_map_alloc returns to dma_handle_p the address of the allocated DMA
  handle. The dma_map_load interface uses this handle to load and set the
  appropriate DMA mapping resources. If the device driver did not call
  dma_map_alloc prior to calling dma_map_load, then you must set dma_handle_p
  to the value zero (0). In this case, dma_map_load allocates the appropriate
  DMA mapping resources (just as if the allocation were done in a previous
  call to the dma_map_alloc interface) and loads and sets the resources as
  necessary.


  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_load 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_load
  interface.

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

  If the device driver sets flags to DMA_ALL, then dma_map_load 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_load 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_load 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_load has
  allocated, loaded, and set 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:

    ·  Release and deallocate resources

       If the device driver needs more resources associated with the
       specified byte_count than dma_map_load can allocate, the driver calls
       dma_map_unload, dma_map_dealloc, or both to unload, 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.

    ·  Use the resources already allocated

       The device driver can use the resources already allocated, loaded, and
       set to perform the DMA data transfers. This data was indicated as
       mapped by dma_map_alloc in the dma_handle_p argument.

    ·  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_load.  In this case, you set the
       DMA_SLEEP bit in the flags argument. This causes dma_map_load to block
       (sleep) until all the resources necessary to perform a DMA transfer of
       size byte_count are available to be allocated, loaded, and set.

SEE ALSO
  Kernel Interfaces: dma_map_alloc(9r), dma_map_dealloc(9r),
  dma_map_unload(9r)

  Data Structures: sg_entry(9s)

Index for Section 9

Alphabetical listing for D

Top of page