ddi_dma_nextcookie(9f)

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

NAME

6       ddi_dma_nextcookie - retrieve subsequent DMA cookie
7

SYNOPSIS

9       #include <sys/ddi.h>
10       #include <sys/sunddi.h>
11
12
13
14       void ddi_dma_nextcookie(ddi_dma_handle_t handle,
15            ddi_dma_cookie_t *cookiep);
16
17

PARAMETERS

19       handle     The    handle    previously   allocated   by   a   call   to
20                  ddi_dma_alloc_handle(9F).
21
22
23       cookiep    A pointer to a  ddi_dma_cookie(9S) structure.
24
25

INTERFACE LEVEL

27       Solaris DDI specific (Solaris DDI).
28

DESCRIPTION

30       ddi_dma_nextcookie() retrieves  subsequent   DMA  cookies  for  a   DMA
31       object.    ddi_dma_nextcookie() fills in the  ddi_dma_cookie(9S) struc‐
32       ture pointed to by  cookiep. The ddi_dma_cookie(9S) structure  must  be
33       allocated prior to calling  ddi_dma_nextcookie().
34
35
36       The   DMA   cookie   count   returned  by  ddi_dma_buf_bind_handle(9F),
37       ddi_dma_addr_bind_handle(9F), or ddi_dma_getwin(9F) indicates the  num‐
38       ber  of  DMA  cookies a DMA object consists of. If the resulting cookie
39       count,  N, is larger than 1,  ddi_dma_nextcookie() must be  called  N-1
40       times to retrieve all  DMA cookies.
41

CONTEXT

43       ddi_dma_nextcookie() can be called from user, kernel, or interrupt con‐
44       text.
45

EXAMPLES

47       Example 1 Process a scatter-gather list of I/O requests.
48
49
50       This example demonstrates the use of  ddi_dma_nextcookie() to process a
51       scatter-gather list of I/O requests.
52
53
54         /* setup scatter-gather list with multiple DMA cookies */
55         ddi_dma_cookie_t  dmacookie;
56         uint_t            ccount;
57         ...
58
59         status = ddi_dma_buf_bind_handle(handle, bp, DDI_DMA_READ,
60              NULL, NULL, &dmacookie, &ccount);
61
62         if (status == DDI_DMA_MAPPED) {
63
64              /* program DMA engine with first cookie */
65
66              while (--ccount > 0) {
67                   ddi_dma_nextcookie(handle, &dmacookie);
68                   /* program DMA engine with next cookie */
69              }
70         }
71         ...
72
73