Kernel Functions for Drivers                   ddidmagetwin(9F)



NAME
     ddidmagetwin - activate a new DMA window

SYNOPSIS
     #include 
     #include 



     int ddidmagetwin(ddidmahandlet handle, uintt win,
          offt *offp, sizet *lenp, ddidmacookiet *cookiep,
          uintt *ccountp);


INTERFACE LEVEL
     Solaris DI specific (Solaris DI).

PARAMETERS
     handle      The  DMA handle previously allocated by  a  call
                 to  ddidmaallochandle(9F).


     win         Number of the window to activate.


     offp        Pointer to an offset.  Upon a successful return,
                 offp  will contain the new offset indicating the
                 beginning of the window within the object.


     lenp        Upon a successful return,  lenp will contain the
                 size, in bytes, of the current window.


     cookiep     A  pointer  to  the  first    ddidmacookie(9S)
                 structure.


     ccountp     Upon a successful return,  ccountp will  contain
                 the number of cookies for this  DMA window.


DESCRIPTION
     ddidmagetwin() activates a new   DMA  window.  If  a   DMA
     resource   allocation  request  returns  DIDMAPARTIALMAP
     indicating that resources for less than  the  entire  object
     were  allocated, the current  DMA window can be changed by a
     call to  ddidmagetwin().


     The caller must first determine the number of  DMA  windows,
     N,  using  ddidmanumwin(9F). ddidmagetwin() takes a  DMA



SunOS 5.11          Last change: 15 Nov 1996                    1






Kernel Functions for Drivers                   ddidmagetwin(9F)



     window number from the range  [0..N-1] as the parameter  win
     and makes it the current  DMA window.


     ddidmagetwin() fills in the first DMA cookie pointed to by
     cookiep  with the appropriate address, length, and bus type.
     *ccountp is set to the number of  DMA  cookies  representing
     this  DMA  object.  Subsequent DMA cookies must be retrieved
     using ddidmanextcookie(9F).


     ddidmagetwin() takes care of underlying resource synchron-
     izations required to shift the window. However accessing the
     data prior to or after moving the  window  requires  further
     synchronization steps using  ddidmasync(9F).


     ddidmagetwin() is normally called from an  interrupt  rou-
     tine.  The  first invocation of the  DMA engine is done from
     the driver. All subsequent invocations of  the   DMA  engine
     are  done  from the interrupt routine. The interrupt routine
     checks to see if the request has been completed. If it  has,
     the  interrupt routine returns without invoking another  DMA
     transfer. Otherwise, it calls  ddidmagetwin() to shift the
     current window and start another DMA transfer.

RETURN VALUES
     ddidmagetwin() returns:

     DISUCES     Resources for the specified DMA  window  are
                     allocated.


     DIFAILURE     win is not a valid window index.


CONTEXT
     ddidmagetwin() can be called from user, kernel, or  inter-
     rupt context.

SEE ALSO
     ddidmaaddrbindhandle(9F),      ddidmaallochandle(9F),
     ddidmabufbindhandle(9F),         ddidmanextcookie(9F),
     ddidmanumwin(9F),                        ddidmasync(9F),
     ddidmaunbindhandle(9F), ddidmacookie(9S)


     Writing Device Drivers







SunOS 5.11          Last change: 15 Nov 1996                    2