ddi_dma_setup(9f)

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

NAME

6       ddi_dma_setup - setup DMA resources
7

SYNOPSIS

9       #include <sys/ddi.h>
10       #include <sys/sunddi.h>
11
12
13
14       int ddi_dma_setup(dev_info_t *dip, ddi_dma_req_t *dmareqp,
15            ddi_dma_handle_t *handlep);
16
17

INTERFACE LEVEL

19       This interface is obsolete. The functions ddi_dma_addr_bind_handle(9F),
20       ddi_dma_alloc_handle(9F),                  ddi_dma_buf_bind_handle(9F),
21       ddi_dma_free_handle(9F),  and  ddi_dma_unbind_handle(9F) should be used
22       instead.
23

PARAMETERS

25       dip        A pointer to the device's dev_info structure.
26
27
28       dmareqp    A pointer to a DMA request structure (see ddi_dma_req(9S)).
29
30
31       handlep    A pointer to a DMA handle to be filled in. See below  for  a
32                  discussion  of  a  handle.  If  handlep is NULL, the call to
33                  ddi_dma_setup() is considered an  advisory  call,  in  which
34                  case  no resources are allocated, but a value indicating the
35                  legality and the feasibility of the request is returned.
36
37

DESCRIPTION

39       The ddi_dma_setup() function allocates resources for  a  memory  object
40       such that a device can perform DMA to or from that object.
41
42
43       A call to ddi_dma_setup() informs the system that device referred to by
44       dip wishes to perform DMA to  or  from  a  memory  object.  The  memory
45       object,  the  device's  DMA capabilities, the device driver's policy on
46       whether to wait for resources, are all  specified  in  the  ddi_dma_req
47       structure pointed to by dmareqp.
48
49
50       A  successful  call to ddi_dma_setup() fills in the value pointed to by
51       handlep. This is an opaque object called a DMA handle. This  handle  is
52       then used in subsequent DMA calls, until ddi_dma_free(9F) is called.
53
54
55       Again  a  DMA handle is opaque—drivers may not attempt to interpret its
56       value. When a driver wants to enable its DMA engine, it  must  retrieve
57       the  appropriate  address  to  supply to its DMA engine using a call to
58       ddi_dma_htoc(9F), which takes a pointer to a  DMA  handle  and  returns
59       the appropriate DMA address.
60
61
62       When  DMA  transfer  completes, the driver should free up the allocated
63       DMA resources by calling ddi_dma_free()
64

RETURN VALUES

66       The ddi_dma_setup() function returns:
67
68       DDI_DMA_MAPPED         Successfully allocated resources for the object.
69                              In  the case of an advisory call, this indicates
70                              that the request is legal.
71
72
73       DDI_DMA_PARTIAL_MAP    Successfully allocated resources for a  part  of
74                              the  object.  This  is  acceptable  when partial
75                              transfers are allowed using a  flag  setting  in
76                              the  ddi_dma_req  structure (see ddi_dma_req(9S)
77                              and ddi_dma_movwin(9F)).
78
79
80       DDI_DMA_NORESOURCES    When no resources are available.
81
82
83       DDI_DMA_NOMAPPING      The object  cannot  be  reached  by  the  device
84                              requesting the resources.
85
86
87       DDI_DMA_TOOBIG         The  object is too big and exceeds the available
88                              resources. The maximum size varies depending  on
89                              machine and configuration.
90
91

CONTEXT

93       The  ddi_dma_setup()  function  can  be called from user, interrupt, or
94       kernel context, except when  the  dmar_fp  member  of  the  ddi_dma_req
95       structure  pointed to by dmareqp is set to DDI_DMA_SLEEP, in which case
96       it cannot be called from interrupt context.
97

ATTRIBUTES

99       See attributes(5) for a description of the following attributes:
100
101
102
103
104       ┌─────────────────────────────┬─────────────────────────────┐
105       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
106       ├─────────────────────────────┼─────────────────────────────┤
107       │Stability Level              │Obsolete                     │
108       └─────────────────────────────┴─────────────────────────────┘
109

NOTES

121       The construction of the ddi_dma_req structure is  complicated.  Use  of
122       the  provided interface functions such as ddi_dma_buf_setup(9F) simpli‐
123       fies this task.
124
125
126
127SunOS 5.11                        16 Jan 2006                ddi_dma_setup(9F)