DMA Software Components: Handles, Windows, and Cookies
A DMA handle is an opaque pointer that represents an object, usually a
memory buffer or address. A DMA handle enables a device to perform DMA
transfers. Several different calls to DMA routines use the handle to identify the
DMA resources that are allocated for the object.
An object represented by a DMA handle is completely covered by one or
more DMA cookies. A DMA cookie represents a contiguous piece of memory that is
used in data transfers by the DMA engine. The system divides objects into
multiple cookies based on the following information:
The ddi_dma_attr(9S) attribute structure provided by the driver
Memory location of the target object
Alignment of the target object
If an object does not fit within the limitations of the DMA engine,
that object must be broken into multiple DMA windows. You can only activate and
allocate resources for one window at a time. Use the ddi_dma_getwin(9F) function to
position between windows within an object. Each DMA window consists of one or
more DMA cookies. For more information, see DMA Windows.
Some DMA engines can accept more than one cookie. Such engines perform scatter-gather
I/O without the help of the system. If multiple cookies are returned from
a bind, the driver should call ddi_dma_nextcookie(9F) repeatedly to retrieve each cookie.
These cookies must then be programmed into the engine. The device can then
be programmed to transfer the total number of bytes covered by the aggregate
of these DMA cookies.
