Manual Pages for UNIX Operating System command usage for man ddi_dma_setup

Kernel Functions for Drivers                    ddi_dma_setup(9F)



NAME
     ddi_dma_setup - setup DMA resources

SYNOPSIS
     #include 
     #include 



     int ddi_dma_setup(dev_info_t *dip, ddi_dma_req_t *dmareqp,
          ddi_dma_handle_t *handlep);


INTERFACE LEVEL
     This    interface     is     obsolete.     The     functions
     ddi_dma_addr_bind_handle(9F),      ddi_dma_alloc_handle(9F),
     ddi_dma_buf_bind_handle(9F),  ddi_dma_free_handle(9F),   and
     ddi_dma_unbind_handle(9F) should be used instead.

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


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


     handlep    A pointer to a DMA handle to be  filled  in.  See
                below for a discussion of a handle. If handlep is
                NULL, the call to ddi_dma_setup()  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  ddi_dma_setup()  function  allocates  resources  for  a
     memory  object such that a device can perform DMA to or from
     that object.


     A call to ddi_dma_setup() 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 ddi_dma_req structure pointed to by
     dmareqp.


     A successful call to  ddi_dma_setup()  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                    ddi_dma_setup(9F)



     until ddi_dma_free(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 ddi_dma_htoc(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 ddi_dma_free()

RETURN VALUES
     The ddi_dma_setup() function returns:

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


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


     DDI_DMA_NORESOURCES    When no resources are available.


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


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


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




SunOS 5.11          Last change: 16 Jan 2006                    2






Kernel Functions for Drivers                    ddi_dma_setup(9F)



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



     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Stability Level             | Obsolete                    |
    |_____________________________|_____________________________|


SEE ALSO
     attributes(5),                 ddi_dma_addr_bind_handle(9F),
     ddi_dma_alloc_handle(9F),       ddi_dma_buf_bind_handle(9F),
     ddi_dma_free_handle(9F),
     ddi_dma_unbind_handle(9F)ddi_dma_addr_setup(9F),
     ddi_dma_buf_setup(9F),  ddi_dma_free(9F),  ddi_dma_htoc(9F),
     ddi_dma_movwin(9F), ddi_dma_sync(9F), ddi_dma_req(9S)


     Writing Device Drivers

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



























SunOS 5.11          Last change: 16 Jan 2006                    3