Kernel Functions for Drivers                    ddidmasetup(9F)



NAME
     ddidmasetup - setup DMA resources

SYNOPSIS
     #include 
     #include 



     int ddidmasetup(devinfot *dip, ddidmareqt *dmareqp,
          ddidmahandlet *handlep);


INTERFACE LEVEL
     This    interface     is     obsolete.     The     functions
     ddidmaaddrbindhandle(9F),      ddidmaallochandle(9F),
     ddidmabufbindhandle(9F),  ddidmafreehandle(9F),   and
     ddidmaunbindhandle(9F) should be used instead.

PARAMETERS
     dip        A pointer to the device's devinfo structure.


     dmareqp    A  pointer  to  a  DMA  request  structure   (see
                ddidmareq(9S)).


     handlep    A pointer to a DMA handle to be  filled  in.  See
                below for a discussion of a handle. If handlep is
                NUL, the call to ddidmasetup()  is  considered
                an  advisory call, in which case no resources are
                allocated, but a value  indicating  the  legality
                and the feasibility of the request is returned.


DESCRIPTION
     The  ddidmasetup()  function  allocates  resources  for  a
     memory  object such that a device can perform DMA to or from
     that object.


     A call to ddidmasetup() informs  the  system  that  device
     referred to by dip wishes to perform DMA to or from a memory
     object. The memory object, the  device's  DMA  capabilities,
     the device driver's policy on whether to wait for resources,
     are all specified in the ddidmareq structure pointed to by
     dmareqp.


     A successful call to  ddidmasetup()  fills  in  the  value
     pointed to by handlep. This is an opaque object called a DMA
     handle. This handle is then used in  subsequent  DMA  calls,



SunOS 5.11          Last change: 16 Jan 2006                    1






Kernel Functions for Drivers                    ddidmasetup(9F)



     until ddidmafree(9F) is called.


     Again a DMA handle is  opaque-drivers  may  not  attempt  to
     interpret  its  value. When a driver wants to enable its DMA
     engine, it must retrieve the appropriate address  to  supply
     to  its  DMA  engine using a call to ddidmahtoc(9F), which
     takes a pointer to a  DMA handle and returns the appropriate
     DMA address.


     When DMA transfer completes, the driver should free  up  the
     allocated DMA resources by calling ddidmafree()

RETURN VALUES
     The ddidmasetup() function returns:

     DIDMAMAPED         Successfully allocated resources  for
                            the   object.   In  the  case  of  an
                            advisory call,  this  indicates  that
                            the request is legal.


     DIDMAPARTIALMAP    Successfully allocated resources  for
                            a part of the object. This is accept-
                            able  when  partial   transfers   are
                            allowed  using  a flag setting in the
                            ddidmareq      structure       (see
                            ddidmareq(9S)                   and
                            ddidmamovwin(9F)).


     DIDMANORESOURCES    When no resources are available.


     DIDMANOMAPING      The object cannot be reached  by  the
                            device requesting the resources.


     DIDMATOBIG         The object is too big and exceeds the
                            available resources. The maximum size
                            varies depending on machine and  con-
                            figuration.


CONTEXT
     The ddidmasetup() function can be called from user, inter-
     rupt,  or  kernel context, except when the dmarfp member of
     the ddidmareq structure pointed to by dmareqp  is  set  to
     DIDMASLEP, in which case it cannot be called from inter-
     rupt context.




SunOS 5.11          Last change: 16 Jan 2006                    2






Kernel Functions for Drivers                    ddidmasetup(9F)



ATRIBUTES
     See attributes(5) for a description of the following  attri-
     butes:



     
           ATRIBUTE TYPE               ATRIBUTE VALUE       
    
     Stability Level              Obsolete                    
    


SEE ALSO
     attributes(5),                 ddidmaaddrbindhandle(9F),
     ddidmaallochandle(9F),       ddidmabufbindhandle(9F),
     ddidmafreehandle(9F),
     ddidmaunbindhandle(9F)ddidmaaddrsetup(9F),
     ddidmabufsetup(9F),  ddidmafree(9F),  ddidmahtoc(9F),
     ddidmamovwin(9F), ddidmasync(9F), ddidmareq(9S)


     Writing Device Drivers

NOTES
     The construction of the  ddidmareq  structure  is  compli-
     cated.  Use  of  the  provided  interface  functions such as
     ddidmabufsetup(9F) simplifies this task.



























SunOS 5.11          Last change: 16 Jan 2006                    3