Difference between revisions of "Unit DMA"
From Ultibo.org
| Line 136: | Line 136: | ||
---- | ---- | ||
| − | '' | + | |
| + | '''DMA logging''' | ||
| + | |||
| + | {| class="wikitable" style="font-size: 14px; text-align: left; width: 100%; height: 50px;" | ||
| + | |- | ||
| + | | <code>DMA_DEFAULT_LOG_LEVEL:LongWord = DMA_LOG_LEVEL_DEBUG;</code> | ||
| + | | style="width: 65%;"|Minimum level for DMA messages. Only messages with level greater than or equal to this will be printed. | ||
| + | |- | ||
| + | |} | ||
| + | {| class="wikitable" style="font-size: 14px; text-align: left; width: 100%; height: 50px;" | ||
| + | |- | ||
| + | | <code>DMA_LOG_ENABLED:Boolean;</code> | ||
| + | | style="width: 65%;"| | ||
| + | |- | ||
| + | |} | ||
| + | <br /> | ||
=== Function declarations === | === Function declarations === | ||
Revision as of 03:15, 5 January 2017
Return to Unit Reference
Description
Ultibo DMA interface unit
The DMA interfaces are 1 tier (Host only) whereas the USB interface is 3 tier (Host, Device and Driver).
Constants
DMA specific constants
DMA_* DMA_NAME_PREFIX = 'DMA';
|
Name prefix for DMA Hosts |
DMA host type constants
DMA_TYPE_* DMA_TYPE_NONE = 0;
|
DMA host state constants
DMA_STATE_* DMA_STATE_DISABLED = 0;
|
|
DMA_STATE_ENABLED = 1;
|
DMA host flag constants
DMA_FLAG_* DMA_FLAG_NONE = $00000000;
|
|
DMA_FLAG_SHARED = $00000001;
|
Host requires data buffers in shared memory |
DMA_FLAG_NOCACHE = $00000002;
|
Host requires data buffers in non cached memory |
DMA_FLAG_COHERENT = $00000004;
|
Data buffers are cache coherent if allocated according to host configuration |
DMA_FLAG_STRIDE = $00000008;
|
Host supports 2D stride on source and/or dest address |
DMA_FLAG_DREQ = $00000010;
|
Host supports data request gating (DREQ) on source and/or dest address |
DMA_FLAG_NOINCREMENT = $00000020;
|
Host supports no increment on source and/or dest address |
DMA_FLAG_NOREAD = $00000040;
|
Host supports no read from source address (write to dest address only) (Zero fill the destination) |
DMA_FLAG_NOWRITE = $00000080;
|
Host supports no write to dest address (read from source address only) (Cache fill from the source) |
DMA_FLAG_WIDE = $00000100;
|
Host supports wide read and/or write |
DMA_FLAG_BULK = $00000200;
|
Host supports bulk transfer |
DMA request flag constants
DMA_REQUEST_FLAG_* DMA_REQUEST_FLAG_NONE = $00000000;
|
|
DMA_REQUEST_FLAG_RELEASE = $00000001;
|
If set then release the request automatically after completion |
DMA_REQUEST_FLAG_CYCLIC = $00000002;
|
This is a cyclic request which loops around from tail to head |
DMA logging constants
DMA_LOG_* DMA_LOG_LEVEL_DEBUG = LOG_LEVEL_DEBUG;
|
DMA debugging messages |
DMA_LOG_LEVEL_INFO = LOG_LEVEL_INFO;
|
DMA informational messages, such as a device being attached or detached |
DMA_LOG_LEVEL_ERROR = LOG_LEVEL_ERROR;
|
DMA error messages |
DMA_LOG_LEVEL_NONE = LOG_LEVEL_NONE;
|
No DMA messages |
Type definitions
To be documented
Public variables
DMA logging
DMA_DEFAULT_LOG_LEVEL:LongWord = DMA_LOG_LEVEL_DEBUG;
|
Minimum level for DMA messages. Only messages with level greater than or equal to this will be printed. |
DMA_LOG_ENABLED:Boolean;
|
Function declarations
Initialization functions
procedure DMAInit;
Description: To be documented
| Note | None documented |
|---|
DMA host functions
function DMAHostStart(DMA:PDMAHost):LongWord;
Description: To be documented
| Note | None documented |
|---|
function DMAHostStop(DMA:PDMAHost):LongWord;
Description: To be documented
| Note | None documented |
|---|
function DMAHostReset(DMA:PDMAHost):LongWord;
Description: To be documented
| Note | None documented |
|---|
function DMAHostProperties(DMA:PDMAHost; Properties:PDMAProperties):LongWord;
Description: To be documented
| Note | None documented |
|---|
function DMAHostCreate:PDMAHost;
Description: Create a new DMA entry
| Return | Pointer to new DMA entry or nil if DMA could not be created |
|---|
function DMAHostCreateEx(Size:LongWord):PDMAHost;
Description: Create a new DMA entry
| Size | Size in bytes to allocate for new DMA (Including the DMA entry") |
|---|---|
| Return | Pointer to new DMA entry or nil if DMA could not be created |
function DMAHostDestroy(DMA:PDMAHost):LongWord;
Description: Destroy an existing DMA entry
| Note | None documented |
|---|
function DMAHostRegister(DMA:PDMAHost):LongWord;
Description: Register a new DMA in the DMA host table
| Note | None documented |
|---|
function DMAHostDeregister(DMA:PDMAHost):LongWord;
Description: Deregister a DMA from the DMA host table
| Note | None documented |
|---|
function DMAHostFind(DMAId:LongWord):PDMAHost;
Description: To be documented
| Note | None documented |
|---|
function DMAHostEnumerate(Callback:TDMAEnumerate; Data:Pointer):LongWord;
Description: To be documented
| Note | None documented |
|---|
function DMAHostNotification(DMA:PDMAHost; Callback:TDMANotification; Data:Pointer; Notification,Flags:LongWord):LongWord;
Description: To be documented
| Note | None documented |
|---|
DMA data functions
function DMADataCount(Data:PDMAData):LongWord;
Description: Return the total number of data blocks in the linked list
| Note | None documented |
|---|
function DMADataFlags(Data:PDMAData):LongWord;
Description: Return the combined flags of the data blocks in the linked list
| Note | None documented |
|---|
function DMADataMaximum(Data:PDMAData):LongWord;
Description: Return the size of the largest data block in the linked list
| Note | None documented |
|---|
DMA buffer functions
function DMABufferAllocate(DMA:PDMAHost; Size:LongWord):Pointer; inline;
Description: Allocate a data buffer for a DMA request
| DMA | The DMA host that the request will be sent to |
|---|---|
| Size | The size of the data buffer to allocate |
| Return | The newly allocated buffer or nil on failure |
function DMABufferAllocateEx(DMA:PDMAHost; var Size:LongWord):Pointer;
Description: Allocate a data buffer for a DMA request
| DMA | The DMA host that the request will be sent to |
|---|---|
| Size | The size of the data buffer to allocate (Updated on return to actual size) |
| Return | The newly allocated buffer or nil on failure |
| Note | This differs from DMABufferAllocate in that it updates the size value to reflect the actual size of the buffer allocated which may be required for some uses |
function DMABufferValidate(DMA:PDMAHost; Buffer:Pointer; Size:LongWord):LongWord;
Description: Validate a data buffer for a DMA request against the DMA host requirements
| DMA | The DMA host that the request will be sent to |
|---|---|
| Buffer | The data buffer to validate |
| Size | The size of the data buffer |
| Return | ERROR_SUCCESS on success or another error code on failure (ERROR_NOT_COMPATIBLE if not compatible with host) |
| Note | Does not check for cache coherency requirements (Shared, Non Cached) only alignment and size. Buffers used as the source of a DMA request do not neccessarily need to meet alignment and size requirements, however buffers used as a destintation must meet these requirements or the caller must take appropriate actions to prevent undesiraable side effects from cache invalidation. |
function DMABufferRelease(Buffer:Pointer):LongWord;
Description: Release a data buffer from a DMA request
| Data | The buffer to be released |
|---|---|
| Return | ERROR_SUCCESS on success or another error code on failure |
DMA request functions
function DMARequestAllocate(DMA:PDMAHost; Data:PDMAData; Callback:TDMARequestCompleted; DriverData:Pointer; Direction,Peripheral,Flags:LongWord):PDMARequest;
Description: Allocate a new DMA request
| DMA | The DMA host this request will be sent to |
|---|---|
| Data | A linked list of DMA data blocks for the transfer (Optional) |
| Callback | The callback function to be called on completion of the request |
| DriverData | Driver private data for the callback (Optional) |
| Direction | The direction of the DMA request (eg DMA_DIR_MEM_TO_MEM) |
| Peripheral | The peripheral ID for data request gating (eg DMA_DREQ_ID_NONE) |
| Flags | Additional flags for this request (eg DMA_REQUEST_FLAG_CYCLIC) |
| Return | The newly allocated request or nil on failure |
function DMARequestRelease(Request:PDMARequest):LongWord;
Description: Release and destroy a DMA request
| Request | The request to be released |
|---|---|
| Return | ERROR_SUCCESS on success or another error code on failure |
function DMARequestSubmit(Request:PDMARequest):LongWord;
Description: Submit a DMA request to a DMA host
| Request | The request to be submitted |
|---|---|
| Return | ERROR_SUCCESS if completed or another error code on failure |
| Note | The request will be completed asynchronously by the DMA host and the completion callback will be called when the request has either succeeded or failed |
function DMARequestCancel(Request:PDMARequest):LongWord;
Description: Cancel a DMA request previously submitted to a DMA host
| Request | The request to be cancelled |
|---|---|
| Return | ERROR_SUCCESS if completed or another error code on failure |
procedure DMARequestComplete(Request:PDMARequest);
Description: Called by a DMA host when a DMA request completes
| Request | The DMA request which has completed |
|---|---|
| Note | DMA host drivers may call this on a worker thread |
DMA transfer functions
function DMATransferRequest(DMA:PDMAHost; Data:PDMAData; Direction,Peripheral,Flags,Timeout:LongWord):LongWord;
Description: Perform a DMA transfer request with the supplied data blocks on the supplied host
| DMA | The DMA host to execute the request on |
|---|---|
| Data | A linked list of DMA data blocks for the transfer |
| Direction | The direction of the DMA request (eg DMA_DIR_MEM_TO_MEM) |
| Peripheral | The peripheral ID for data request gating (eg DMA_DREQ_ID_NONE) |
| Flags | Additional flags for this transfer request (eg DMA_REQUEST_FLAG_CYCLIC) |
| Timeout | Milliseconds to wait for request to complete (INFINITE to wait forever) |
| Note | An internal callback will be specified and the function will wait for the transfer to complete |
function DMATransferRequestEx(DMA:PDMAHost; Data:PDMAData; Callback:TDMARequestCompleted; DriverData:Pointer; Direction,Peripheral,Flags:LongWord):LongWord;
Description: Perform a DMA transfer request with the supplied data blocks on the supplied host
| DMA | The DMA host to execute the request on |
|---|---|
| Data | A linked list of DMA data blocks for the transfer |
| Callback | The callback function to be called on completion of the request |
| DriverData | Driver private data for the callback (Optional) |
| Direction | The direction of the DMA request (eg DMA_DIR_MEM_TO_MEM) |
| Peripheral | The peripheral ID for data request gating (eg DMA_DREQ_ID_NONE) |
| Flags | Additional flags for this transfer request (eg DMA_REQUEST_FLAG_CYCLIC) |
| Note | The request will be passed to the callback with the DriverData field set to the DriverData passed to this function. On completion of the callback the request will automatically be released by the internal callback handler. |
procedure DMATransferRequestComplete(Request:PDMARequest);
Description: Called when a DMA transfer request completes
| Request | The DMA request which has completed |
|---|---|
| Note | This is the internal callback for DMATransferRequest |
RTL DMA functions
function SysDMAAvailable:Boolean;
Description: Check if a DMA host is available
| Note | None documented |
|---|
function SysDMATransfer(Data:PDMAData; Direction,Peripheral:LongWord):LongWord;
Description: Perform a DMA transfer using the list of DMA data blocks provided
| Data | A linked list of DMA data blocks for the transfer |
|---|---|
| Direction | The direction of the DMA request (eg DMA_DIR_MEM_TO_MEM) |
| Peripheral | The peripheral ID for data request gating (eg DMA_DREQ_ID_NONE) |
function SysDMAFillMemory(Dest:Pointer; Size:LongWord; Value:Byte):LongWord;
Description: Fill memory at the destination address using DMA
| Dest | The address to start the memory fill |
|---|---|
| Size | The size of memory to fill in bytes |
| Value | The value to fill the memory with |
function SysDMACopyMemory(Source,Dest:Pointer; Size:LongWord):LongWord;
Description: Copy memory from the source to the destination address using DMA
| Source | The source address to start the memory copy |
|---|---|
| Dest | The destination address to start the memory copy |
| Size | The size of memory to copy in bytes |
function SysDMAReadPeripheral(Address,Dest:Pointer; Size,Peripheral:LongWord):LongWord;
Description: Read from a periperal address to the destination address using DMA
| Address | The address of the periperhal register to read from |
|---|---|
| Dest | The destination address to start writing to |
| Size | The size of the read in bytes |
| Peripheral | The peripheral ID for data request gating (eg DMA_DREQ_ID_UART_RX) |
function SysDMAWritePeripheral(Source,Address:Pointer; Size,Peripheral:LongWord):LongWord;
Description: Write to a peripheral address from the source address using DMA
| Source | The source address to start reading from |
|---|---|
| Address | The address of the peripheral register to write to |
| Size | The size of the write in bytes |
| Peripheral | The peripheral ID for data request gating (eg DMA_DREQ_ID_UART_TX) |
function SysDMAAllocateBuffer(Size:LongWord):Pointer;
Description: Allocate a buffer compatible with DMA memory reads or writes
| Size | The size of the buffer to allocate |
|---|
function SysDMAAllocateBufferEx(var Size:LongWord):Pointer;
Description: Allocate a buffer compatible with DMA memory reads or writes
| Size | The size of the buffer to allocate (Updated on return to actual size) |
|---|
function SysDMAReleaseBuffer(Buffer:Pointer):LongWord;
Description: Release a buffer allocated with DMAAllocateBuffer
| Buffer | The buffer to be released |
|---|
DMA helper functions
function DMAGetCount:LongWord; inline;
Description: Get the current DMA host count
| Note | None documented |
|---|
function DMAHostGetDefault:PDMAHost; inline;
Description: Get the current default DMA host
| Note | None documented |
|---|
function DMAHostSetDefault(DMA:PDMAHost):LongWord;
Description: Set the current default DMA device
| Note | None documented |
|---|
function DMAHostCheck(DMA:PDMAHost):PDMAHost;
Description: Check if the supplied DMA is in the DMA host table
| Note | None documented |
|---|
procedure DMALog(Level:Integer; DMA:PDMAHost; const AText:String);
Description: To be documented
| Note | None documented |
|---|
procedure DMALogInfo(DMA:PDMAHost; const AText:String);
Description: To be documented
| Note | None documented |
|---|
procedure DMALogError(DMA:PDMAHost; const AText:String);
Description: To be documented
| Note | None documented |
|---|
procedure DMALogDebug(DMA:PDMAHost;const AText:String);
Description: To be documented
| Note | None documented |
|---|
Return to Unit Reference
