ddi_dma_alloc_handle(9f)

1ddi_dma_alloc_handle(9F) Kernel Functions for Drivers ddi_dma_alloc_handle(9F)
2
3
4

NAME

6       ddi_dma_alloc_handle - allocate DMA handle
7

SYNOPSIS

9       #include <sys/ddi.h>
10       #include <sys/sunddi.h>
11
12
13
14       int ddi_dma_alloc_handle(dev_info_t *dip, ddi_dma_attr_t *attr,
15            int  (*callback) (caddr_t), caddr_t arg, ddi_dma_handle_t *handlep);
16
17

INTERFACE LEVEL

19       Solaris DDI specific (Solaris DDI).
20

PARAMETERS

22       dip         Pointer to the device's  dev_info structure.
23
24
25       attr        Pointer  to a  DMA attribute structure for this device (see
26                   ddi_dma_attr(9S)).
27
28
29       callback    The address of a function to call back later  if  resources
30                   aren't  available  now.   The  following  special  function
31                   addresses may also be used.
32
33                   DDI_DMA_SLEEP       Wait until resources are available.
34
35
36                   DDI_DMA_DONTWAIT    Do not wait until resources are  avail‐
37                                       able and do not schedule a callback.
38
39
40
41       arg         Argument  to  be  passed  to a callback function, if such a
42                   function is specified.
43
44
45       handlep     Pointer to the  DMA handle to be initialized.
46
47

DESCRIPTION

49       ddi_dma_alloc_handle() allocates a new  DMA handle. A  DMA handle is an
50       opaque  object  used  as  a  reference  to  subsequently allocated  DMA
51       resources.   ddi_dma_alloc_handle() accepts as  parameters  the  device
52       information  referred  to  by   dip  and  the  device's  DMA attributes
53       described  by  a  ddi_dma_attr(9S)  structure.  A  successful  call  to
54       ddi_dma_alloc_handle()  fills  in  the  value pointed to by  handlep. A
55       DMA handle must only be used by the device for which it  was  allocated
56       and is only valid for one  I/O transaction at a time.
57
58
59       The callback function, callback, indicates how a caller wants to handle
60       the possibility of resources not being available. If  callback  is  set
61       to  DDI_DMA_DONTWAIT,  then  the caller does not care if the allocation
62       fails, and can handle an allocation failure appropriately. If  callback
63       is set to  DDI_DMA_SLEEP, then the caller wishes to have the allocation
64       routines wait for resources to become available. If any other value  is
65       set, and a DMA resource allocation fails, this value is assumed to be a
66       function to call at a later time when resources may  become  available.
67       When the specified function is called, it is passed arg as an argument.
68       The  specified  callback  function  must  return  either  DDI_DMA_CALL‐
69       BACK_RUNOUT or DDI_DMA_CALLBACK_DONE. DDI_DMA_CALLBACK_RUNOUT indicates
70       that the callback routine  attempted  to  allocate  DMA  resources  but
71       failed  to  do so, in which case the callback function is put back on a
72       list to be called again later.  DDI_DMA_CALLBACK_DONE indicates  either
73       success  at  allocating DMA resources or the driver no longer wishes to
74       retry.
75
76
77       The callback function is called in interrupt context.  Therefore,  only
78       system  functions that are accessible from interrupt context  is avail‐
79       able. The callback function must take whatever steps necessary to  pro‐
80       tect its critical resources, data structures, queues, and so forth.
81
82
83       When a  DMA handle is no longer needed, ddi_dma_free_handle(9F) must be
84       called to free the handle.
85

RETURN VALUES

87       ddi_dma_alloc_handle() returns:
88
89       DDI_SUCCESS            Successfully allocated a new DMA handle.
90
91
92       DDI_DMA_BADATTR        The attributes specified in the ddi_dma_attr(9S)
93                              structure  make  it impossible for the system to
94                              allocate potential  DMA resources.
95
96
97       DDI_DMA_NORESOURCES    No resources are available.
98
99

CONTEXT

101       ddi_dma_alloc_handle() can be called from user,  kernel,  or  interrupt
102       context,  except  when callback is set to  DDI_DMA_SLEEP, in which case
103       it can be called from user or kernel context only.
104