Common DMA Functions (Compact 2013)

3/26/2014

The following table lists three CEDDK.dll functions that are useful for common buffer direct memory access (DMA) transfers. These functions handle bus and hardware platform-specific address translations for you. They also handle address translations between the system and the PCI bus for the DMA controller to use for copying data.

Function	Description
HalAllocateCommonBuffer	Allocates memory, locks it down, and maps it so that the microprocessor and the device can access it simultaneously.
HalFreeCommonBuffer	Frees a common buffer that is allocated by HalAllocateCommonBuffer, together with all the resources that the buffer uses.
HalTranslateSystemAddress	Translates a physical system address to a logical bus address, which you can pass to a bus controller for DMA operations.

These functions translate a physical RAM address to the corresponding bus-relative physical address for the DMA controller. To set up a common buffer for bus master DMA by using the CEDDK.dll functions, a bus master DMA device driver can call HalAllocateCommonBuffer, passing in a DMA_ADAPTER_OBJECT structure that contains information about the DMA adapter.

The following code example shows a call to HalAllocateCommonBuffer to allocate a physical memory buffer address for DMA.

// Set up the DMA adapter descriptor structure. 
DMA_ADAPTER_OBJECT AdapterObject;
AdapterObject.ObjectSize = sizeof(AdapterObject);
AdapterObject.InterfaceType = Internal;
AdapterObject.BusNumber = 0;

// Allocate a physical buffer.
m_vuaBuf = (PBYTE)HalAllocateCommonBuffer(&AdapterObject,
                cbBufSize, &m_paBuf, FALSE);

// Unable to allocate a physical buffer.
if (m_vuaBuf == NULL)
{
    RETAILMSG(1,(L"unable to allocate %d bytes\r\n", cbBufSize));
    ret = ERROR_OUTOFMEMORY;
    ASSERT(0);
    HalFreeCommonBuffer(NULL, 0, m_paBuf, m_vuaBuf, FALSE);
    goto cleanup;
}

// . . .
// Use the buffer
// . . .

// When done with the buffer:
HalFreeCommonBuffer(&AdapterObject, cbBufSize, m_paBuf,
    m_vuaBuf, FALSE);

In this example, m_vuaBuf is the DMA buffer virtual uncached address, cbBufSize is the buffer length, in bytes, and m_paBuf is the buffer physical address. The last parameter is set to FALSE to disable caching. When HalAllocateCommonBuffer successfully returns, it allocates a shared buffer of locked, physically contiguous pages that the microprocessor and the device can access simultaneously for DMA operations.

For an example that uses these common DMA functions for scatter/gather DMA, see the sample ATAPI device driver source that is located in %_WINCEROOT%\public\COMMON\oak\drivers\block\atapi. Note that to set up scatter/gather DMA, you must simultaneously use multiple pairs of base addresses and lengths as shown in the sample driver.

For more information about common DMA functions, see Ceddk.dll DMA Functions.

See Also

Concepts

Support Direct Memory Access