Index for Section 9

Alphabetical listing for D

Bottom of page

dma_put_prev_sgentry(9r)
NAME
  dma_put_prev_sgentry - General: Updates an internal pointer index to the
  linked list of sg_entry structures

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


  int dma_put_prev_sgentry(
	  dma_handle_t dma_handle,
	  sg_entry_t sg_entryp );

ARGUMENTS
  dma_handle
      Specifies 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.

  sg_entryp
      Specifies a pointer to the sg_entry structure that contains the bus
      address/byte count values to replace the corresponding bus address/byte
      count of the sg_entry structure associated with this DMA handle. The
      device driver writer sets the bus address/byte count in the ba and bc
      members of the sg_entry structure and then passes its address to
      dma_put_prev_sgentry.

DESCRIPTION
  The dma_put_prev_sgentry interface updates an internal pointer index to the
  linked list of sg_entry structures, and then puts new bus address/byte
  count values into the existing bus address/byte count pair pointed to by
  the DMA handle passed in by you. This interface enables device drivers to
  patch existing bus address/byte count pairs due to an unexpected
  interruption in a DMA transfer. A bus address/byte count pair is
  represented by the ba and bc members of an sg_entry structure pointer.

  This interface is useful for DMA engines that do not have total control of
  a DMA transfer. For example, a SCSI device doing an unexpected disconnect
  in the middle of a block transfer can interrupt a SCSI controller. Such a
  disconnect can require the driver to do one or more patches to the list of
  bus address/byte count pairs in order to restart the DMA transfer (without
  starting from the beginning of the list). Device drivers call the
  dma_put_curr_sgentry and dma_put_prev_sgentry interfaces to accomplish
  these patch operations.  Typically, only buses that do not have byte
  atomicity transfers (for example, the TURBOchannel bus on Alpha CPUs)
  require these patch operations.

  The dma_put_prev_sgentry differs from dma_put_curr_sgentry in that it
  updates an internal pointer index before inserting the new bus address/byte
  count values into the existing bus address/byte count pair. The pointer-
  index retains this updated value after dma_put_prev_sgentry returns.


RETURN VALUES
  Upon successful completion, dma_put_prev_sgentry returns the value 1.
  Otherwise, dma_put_prev_sgentry returns the value zero (0) to indicate
  failure. This failure indicates that the index into the DMA handle points
  to the first element in the byte address/byte count list. In this case,
  there is no previous byte address/byte count entry to patch.

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

SEE ALSO
  Kernel Interfaces: dma_put_curr_sgentry(9r)

  Data Structures: sg_entry(9s)

Index for Section 9

Alphabetical listing for D

Top of page