Difference between revisions of "Unit DMA"
From Ultibo.org
| Line 705: | Line 705: | ||
|- | |- | ||
! Note | ! 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 | + | | 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. |
|- | |- | ||
|} | |} | ||
Latest revision as of 04:51, 10 October 2023
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
DMA_TYPE_* DMA_TYPE_NONE = 0;
|
|
DMA_TYPE_MAX = 0;
|
|
DMA host state
DMA_STATE_* DMA_STATE_DISABLED = 0;
|
|
DMA_STATE_ENABLED = 1;
|
|
DMA_STATE_MAX = 1;
|
|
DMA host flag
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
DMA_DATA_FLAG_* | See: Platform DMA_DATA_FLAG_* |
DMA request 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 logging
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;
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 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;
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;
Description: Get the current DMA host count
| Note | None documented |
|---|
function DMAHostGetDefault:PDMAHost;
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 |
|---|
function DMATypeToString(DMAType:LongWord):String;
Description: Convert a DMA type value to a string
| Note | None documented |
|---|
function DMAStateToString(DMAState:LongWord):String;
Description: Convert a DMA state value to a string
| 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); inline;
Description: To be documented
| Note | None documented |
|---|
procedure DMALogWarn(DMA:PDMAHost; const AText:String); inline;
Description: To be documented
| Note | None documented |
|---|
procedure DMALogError(DMA:PDMAHost; const AText:String); inline;
Description: To be documented
| Note | None documented |
|---|
procedure DMALogDebug(DMA:PDMAHost; const AText:String); inline;
Description: To be documented
| Note | None documented |
|---|
Return to Unit Reference
