ddi_dma_getwin(9f)

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

NAME

6       ddi_dma_getwin - activate a new DMA window
7

SYNOPSIS

9       #include <sys/ddi.h>
10       #include <sys/sunddi.h>
11
12
13
14       int ddi_dma_getwin(ddi_dma_handle_t handle, uint_t win,
15            off_t *offp, size_t *lenp, ddi_dma_cookie_t *cookiep,
16            uint_t *ccountp);
17
18

INTERFACE LEVEL

20       Solaris DDI specific (Solaris DDI).
21

PARAMETERS

23       handle      The    DMA   handle  previously  allocated  by  a  call  to
24                   ddi_dma_alloc_handle(9F).
25
26
27       win         Number of the window to activate.
28
29
30       offp        Pointer to an offset.  Upon a successful return,  offp will
31                   contain  the  new  offset  indicating the  beginning of the
32                   window within the object.
33
34
35       lenp        Upon a successful return,  lenp will contain the  size,  in
36                   bytes, of the current window.
37
38
39       cookiep     A pointer to the first  ddi_dma_cookie(9S) structure.
40
41
42       ccountp     Upon  a successful return,  ccountp will contain the number
43                   of cookies for this  DMA window.
44
45

DESCRIPTION

47       ddi_dma_getwin() activates a new  DMA window. If a  DMA resource  allo‐
48       cation  request  returns  DDI_DMA_PARTIAL_MAP indicating that resources
49       for less than the entire object were allocated, the current  DMA window
50       can be changed by a call to  ddi_dma_getwin().
51
52
53       The  caller  must first determine the number of  DMA windows,  N, using
54       ddi_dma_numwin(9F). ddi_dma_getwin() takes a  DMA  window  number  from
55       the  range  [0..N-1] as the parameter win and makes it the current  DMA
56       window.
57
58
59       ddi_dma_getwin() fills in the first DMA cookie pointed  to  by  cookiep
60       with  the appropriate address, length, and bus type. *ccountp is set to
61       the number of DMA cookies representing this DMA object. Subsequent  DMA
62       cookies must be retrieved using ddi_dma_nextcookie(9F).
63
64
65       ddi_dma_getwin()  takes  care  of  underlying resource synchronizations
66       required to shift the window. However accessing the data  prior  to  or
67       after  moving  the  window requires further synchronization steps using
68       ddi_dma_sync(9F).
69
70
71       ddi_dma_getwin() is normally called  from  an  interrupt  routine.  The
72       first invocation of the  DMA engine is done from the driver. All subse‐
73       quent invocations of the  DMA engine are done from the  interrupt  rou‐
74       tine.  The interrupt routine checks to see if the request has been com‐
75       pleted. If it has,  the  interrupt  routine  returns  without  invoking
76       another   DMA  transfer. Otherwise, it calls  ddi_dma_getwin() to shift
77       the current window and start another DMA transfer.
78

RETURN VALUES

80       ddi_dma_getwin() returns:
81
82       DDI_SUCCESS     Resources for the specified DMA window are allocated.
83
84
85       DDI_FAILURE     win is not a valid window index.
86
87

CONTEXT

89       ddi_dma_getwin() can be called from user, kernel, or interrupt context.
90