Tribblix: manual page: ddi_dma_cookie

DDI_DMA_COOKIE_ITER(9F) Kernel Functions for Drivers

NAME

ddi_dma_cookie_get, ddi_dma_cookie_iter, ddi_dma_cookie_one,
ddi_dma_ncookies, ddi_dma_nextcookie - retrieve DMA cookies

SYNOPSIS

#include <sys/ddi.h>
#include <sys/sunddi.h>

const ddi_dma_cookie_t *
ddi_dma_cookie_iter(ddi_dma_handle_t handle,
const ddi_dma_cookie_t *cookiep);

const ddi_dma_cookie_t *
ddi_dma_cookie_get(ddi_dma_handle_t handle, uint_t index);

const ddi_dma_cookie_t *
ddi_dma_cookie_one(ddi_dma_handle_t handle);

uint_t
ddi_dma_ncookies(ddi_dma_handle_t handle);

void
ddi_dma_nextcookie(ddi_dma_handle_t handle, ddi_dma_cookie_t *cookiep);

PARAMETERS

handle The DMA handle obtained by a call to
ddi_dma_alloc_handle(9F).

cookie A pointer to a ddi_dma_cookie(9S) structure.

index An unsigned integer that represents the index of a cookie
to obtain. The first entry is at index zero.

DESCRIPTION

The ddi_dma_cookie_iter(), ddi_dma_cookie_get(), and
ddi_dma_cookie_one() functions obtain information about DMA cookies.
When a DMA request, represented by the DMA handle handle, has been
bound to a series of addresses with the ddi_dma_addr_bind_handle(9F) or
ddi_dma_buf_bind_handle(9F) functions, the resulting addresses are
stored in one or more ddi_dma_cookie(9S) structures. the three
different functions provide different ways to obtain cookies and are
safe alternatives to the unsafe ddi_dma_nextcookie() function. To see
how to use these functions, please see the EXAMPLES section.

The ddi_dma_cookie_iter() function provides a way to iterate over all
the cookies that are associated with the DMA handle handle. To get the
first handle, pass NULL in cookiep. Do not use the DMA cookie returned
from either of the ddi_dma_addr_bind_handle(9F) or
ddi_dma_buf_bind_handle(9F) functions. To get subsequent cookies, pass
the returned cookie as the argument cookiep. When the function returns
NULL then that indicates that the last handle has been iterated over.

The ddi_dma_cookie_get() function returns a specific cookie. The index
indicates which of the cookies should be returned. The first cookie is
at index 0. If an invalid index is specified, the function returns
NULL.

The ddi_dma_cookie_one function is a convenience function for DMA
requests that have a single cookie. This function always returns the
single cookie associated with the DMA handle handle. If this function
is used when there is a DMA request with multiple cookies, then it will
panic the system. It can never return NULL.

The ddi_dma_ncookies() function returns the number of DMA cookies that
are associated with the DMA handle handle. If there are no DMA
resources bound to the handle, then this will return 0.

The ddi_dma_nextcookie() function was the historical function that was
associated with obtaining DMA cookies. It should not be used due to
several flaws. The ddi_dma_nextcookie() function mutates the
underlying DMA handle meaning that a driver cannot obtain a cookie a
second time and thus a device driver using this interface must either
manually keep storage of the cookie around wasting space or rebind the
handle, wasting time. In addition, there is no way for the function to
indicate that a driver has consumed all of its cookies. If for some
reason a device driver calls the ddi_dma_nextcookie() function more
times than there are cookies, the results are undefined. In short,
this function should not be used for any purpose. Use the
ddi_dma_cookie_iter(), ddi_dma_cookie_get(), or ddi_dma_cookie_one()
functions instead.

CONTEXT

The ddi_dma_cookie_iter(), ddi_dma_cookie_get(), ddi_dma_cookie_one(),
ddi_dma_ncookies(), and ddi_dma_nextcookie() functions may be called
from user, kernel, or interrupt context.

RETURN VALUES

Upon successful completion, the ddi_dma_cookie_iter(),
ddi_dma_cookie_get(), ddi_dma_cookie_one() functions will return the
requested DMA cookie. If there are no more cookies, or cookiep is
invalid, the ddi_dma_cookie_iter() function will return NULL. If index
does not correspond to a valid cookie, the ddi_dma_cookie_get()
function will return NULL. If there is not exactly one DMA cookie, or
another issue occurs, then the ddi_dma_cookie_one() function will panic
the system.

Upon successful completion, the ddi_dma_ncookies() function returns the
number of cookies associated with handle. If there are none, then 0 is
returned.

The ddi_dma_nextcookie() function always updates cookiep regardless of
whether it is valid or not.

EXAMPLES

Example 1 Using the ddi_dma_cookie_iter() function to obtain all DMA
cookies.

/*
* This example assumes that either ddi_dma_addr_bind_handle() or
* ddi_dma_buf_bind_handle() has already been successfully called.
*/
void
program_dma(ddi_dma_handle_t handle)
{
const ddi_dma_cookie_t *c;

for (cookie = ddi_dma_cookie_iter(handle, NULL); c != NULL;
c = ddi_dma_cookie_iter(handle, c)) {
/*
* Use the dmac_laddress and dmac_size members to
* properly program the device or descriptor rings.
*/
}
}

Example 2 Using the ddi_dma_cookie_get() function.

/*
* This example assumes that either ddi_dma_mem_alloc() has already
* been successfully called.
*/
int
bind_dma(ddi_dma_handle_t handle, void *addr, size_t len)
{
int ret;
uint_t i, ncookies;
ddi_dma_cookie_t first;

ret = ddi_dma_addr_bind_handle(handle, NULL, addr, len,
DDI_DMA_RDWR | DDI_DMA_CONSISTENT, NULL, NULL, &first,
&ncookies);
if (ret != DDI_DMA_MAPPED) {
return (ret);
}

/*
* A driver doesn't need to store ncookies. It can get it again
* by simply calling ddi_dma_ncookies() and using the result in
* place of ncookies from ddi_dma_addr_bind_handle().
*/
for (i = 0; i < ncookies; i++) {
const ddi_dma_cookie_t *cookie;

cookie = ddi_dma_cookie_get(handle, i);
/*
* Use the dmac_laddress and dmac_size members to
* properly program the device or descriptor rings.
*/
}
}