Unit DMA
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_*
DMA_NAME_PREFIX = 'DMA';
|
Name prefix for DMA Hosts |
DMA_TYPE_*
DMA_TYPE_NONE = 0;
|
|
DMA_TYPE_MAX = 0;
|
DMA_STATE_*
DMA_STATE_DISABLED = 0;
|
|
DMA_STATE_ENABLED = 1;
|
|
DMA_STATE_MAX = 1;
|
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_FLAG_LITE = $00000400;
|
Host supports "lite" transfer |
DMA_FLAG_40BIT = $00000800;
|
Host supports 40-bit address transfer |
DMA_DATA_FLAG_*
See: Platform DMA_DATA_FLAG_* |
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_REQUEST_FLAG_COMPATIBLE = $00000004;
|
If set then all buffers supplied are host configuration compatible (Sizing, Alignment, Flags) |
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_WARN = LOG_LEVEL_WARN;
|
DMA warning messages |
DMA_LOG_LEVEL_ERROR = LOG_LEVEL_ERROR;
|
DMA error messages |
DMA_LOG_LEVEL_NONE = LOG_LEVEL_NONE;
|
No DMA messages |
Type definitions
DMA properties
PDMAProperties = ^TDMAProperties;
TDMAProperties = record
Flags:LongWord;
|
Host flags (eg DMA_FLAG_STRIDE) |
Alignment:LongWord;
|
Host data buffer alignment |
Multiplier:LongWord;
|
Host data buffer multiplier |
Channels:LongWord;
|
Total number of host channels |
MaxSize:LongWord;
|
Maximum transfer size |
MaxCount:LongWord;
|
Maximum Y count for 2D stride |
MaxLength:LongWord;
|
Maximum X length for 2D stride |
MinStride:LongInt;
|
Minimum stride value (Increment between rows) May be negative. |
MaxStride:LongWord;
|
Maximum stride value (Increment between rows) |
DMA enumeration callback
TDMAEnumerate = function(DMA:PDMAHost; Data:Pointer):LongWord;
|
DMA notification callback
TDMANotification = function(Device:PDevice; Data:Pointer; Notification:LongWord):LongWord;
|
DMA host start
TDMAHostStart = function(DMA:PDMAHost):LongWord;
|
DMA host stop
TDMAHostStop = function(DMA:PDMAHost):LongWord;
|
DMA host reset
TDMAHostReset = function(DMA:PDMAHost):LongWord;
|
DMA host submit
TDMAHostSubmit = function(DMA:PDMAHost; Request:PDMARequest):LongWord;
|
DMA host cancel
TDMAHostCancel = function(DMA:PDMAHost; Request:PDMARequest):LongWord;
|
DMA host properties
TDMAHostProperties = function(DMA:PDMAHost; Properties:PDMAProperties):LongWord;
|
DMA host
PDMAHost = ^TDMAHost;
TDMAHost = record
Device Properties | |
Device:TDevice;
|
The Device entry for this DMA host |
DMA Properties | |
DMAId:LongWord;
|
Unique Id of this DMA host in the DMA host table |
DMAId:LongWord;
|
Unique Id of this DMA host in the DMA host table |
DMAState:LongWord;
|
DMA state (eg DMA_STATE_ENABLED) |
HostStart:TDMAHostStart;
|
A Host specific HostStart method implementing the standard DMA host interface (Mandatory) |
HostStop:TDMAHostStop;
|
A Host specific HostStop method implementing the standard DMA host interface (Mandatory) |
HostReset:TDMAHostReset;
|
A Host specific HostReset method implementing the standard DMA host interface (Or nil if the default method is suitable) |
HostSubmit:TDMAHostSubmit;
|
A Host specific HostSubmit method implementing the standard DMA host interface (Mandatory) |
HostCancel:TDMAHostCancel;
|
A Host specific HostCancel method implementing the standard DMA host interface (Mandatory) |
HostProperties:TDMAHostProperties;
|
A Host specific HostProperties method implementing the standard DMA host interface (Or nil if the default method is suitable) |
Driver Properties | |
Lock:TMutexHandle;
|
Host lock |
Alignment:LongWord;
|
Host data buffer alignment |
Multiplier:LongWord;
|
Host data buffer multiplier |
Properties:TDMAProperties;
|
Host properties |
LastError:LongWord;
|
Last error to occur on this host |
PendingCount:LongWord;
|
Number of DMA requests pending for this host |
WaiterThread:TThreadId;
|
Thread waiting for pending requests to complete |
Statistics Properties | |
RequestCount:LongWord;
|
Number of DMA requests that have been submitted to this host |
RequestErrors:LongWord;
|
Number of DMA requests that have failed on this host |
Internal Properties | |
Prev:PDMAHost;
|
Previous entry in DMA host table |
Next:PDMAHost;
|
Next entry in DMA host table |
DMA request completed
TDMARequestCompleted = procedure(Request:PDMARequest);
|
DMA request
PDMARequest = ^TDMARequest;
TDMARequest = record
Note: Forward declared to satisfy DMAHost | |
Request Properties | |
Host:PDMAHost;
|
|
Data:PDMAData;
|
List of data blocks for this request |
Flags:LongWord;
|
Flags for the request (eg DMA_REQUEST_FLAG_RELEASE) |
Direction:LongWord;
|
The direction of the DMA request (eg DMA_DIR_MEM_TO_MEM) |
Peripheral:LongWord;
|
The peripheral ID for data request gating (eg DMA_DREQ_ID_NONE) |
Callback:TDMARequestCompleted;
|
Callback function that will be called when this DMA request has been successfully completed or has failed |
DriverData:Pointer;
|
Private data for the completion callback (Optional) |
Result Properties | |
Status:LongWord;
|
Status of the request (ERROR_SUCCESS if successful, or another error code if the request failed) |
Driver Properties (Private variables for use by Host drivers) | |
ControlBlocks:Pointer;
|
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;
Note | None documented |
---|
DMA host functions
function DMAHostStart(DMA:PDMAHost):LongWord;
Note | None documented |
---|
function DMAHostStop(DMA:PDMAHost):LongWord;
Note | None documented |
---|
function DMAHostReset(DMA:PDMAHost):LongWord;
Note | None documented |
---|
function DMAHostProperties(DMA:PDMAHost; Properties:PDMAProperties):LongWord;
Note | None documented |
---|
function DMAHostCreate:PDMAHost;
Return | Pointer to new DMA entry or nil if DMA could not be created |
---|
function DMAHostCreateEx(Size:LongWord):PDMAHost;
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;
Note | None documented |
---|
function DMAHostRegister(DMA:PDMAHost):LongWord;
Note | None documented |
---|
function DMAHostDeregister(DMA:PDMAHost):LongWord;
Note | None documented |
---|
function DMAHostFind(DMAId:LongWord):PDMAHost;
Note | None documented |
---|
function DMAHostEnumerate(Callback:TDMAEnumerate; Data:Pointer):LongWord;
Note | None documented |
---|
function DMAHostNotification(DMA:PDMAHost; Callback:TDMANotification; Data:Pointer; Notification,Flags:LongWord):LongWord;
Note | None documented |
---|
DMA data functions
function DMADataCount(Data:PDMAData):LongWord;
Note | None documented |
---|
function DMADataFlags(Data:PDMAData):LongWord;
Note | None documented |
---|
function DMADataMaximum(Data:PDMAData):LongWord;
Note | None documented |
---|
DMA buffer functions
function DMABufferAllocate(DMA:PDMAHost; Size:LongWord):Pointer; inline;
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;
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;
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 necessarily need to meet alignment and size requirements, however buffers used as a destination must meet these requirements or the caller must take appropriate actions to prevent undesirable side effects from cache invalidation. |
function DMABufferRelease(Buffer:Pointer):LongWord;
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;
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;
Request | The request to be released |
---|---|
Return | ERROR_SUCCESS on success or another error code on failure |
function DMARequestSubmit(Request:PDMARequest):LongWord;
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;
Request | The request to be cancelled |
---|---|
Return | ERROR_SUCCESS if completed or another error code on failure |
procedure DMARequestComplete(Request:PDMARequest);
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;
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;
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);
Request | The DMA request which has completed |
---|---|
Note | This is the internal callback for DMATransferRequest |
RTL DMA functions
function SysDMAAvailable:Boolean;
Note | None documented |
---|
function SysDMATransfer(Data:PDMAData; Direction,Peripheral:LongWord):LongWord;
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;
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;
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;
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;
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;
Size | The size of the buffer to allocate |
---|
function SysDMAAllocateBufferEx(var Size:LongWord):Pointer;
Size | The size of the buffer to allocate (Updated on return to actual size) |
---|
function SysDMAReleaseBuffer(Buffer:Pointer):LongWord;
Buffer | The buffer to be released |
---|
DMA helper functions
function DMAGetCount:LongWord;
Note | None documented |
---|
function DMAHostGetDefault:PDMAHost;
Note | None documented |
---|
function DMAHostSetDefault(DMA:PDMAHost):LongWord;
Note | None documented |
---|
function DMAHostCheck(DMA:PDMAHost):PDMAHost;
Note | None documented |
---|
function DMATypeToString(DMAType:LongWord):String;
Note | None documented |
---|
function DMAStateToString(DMAState:LongWord):String;
Note | None documented |
---|
procedure DMALog(Level:Integer; DMA:PDMAHost; const AText:String);
Note | None documented |
---|
procedure DMALogInfo(DMA:PDMAHost; const AText:String); inline;
Note | None documented |
---|
procedure DMALogWarn(DMA:PDMAHost; const AText:String); inline;
Note | None documented |
---|
procedure DMALogError(DMA:PDMAHost; const AText:String); inline;
Note | None documented |
---|
procedure DMALogDebug(DMA:PDMAHost; const AText:String); inline;
Note | None documented |
---|
Return to Unit Reference