Difference between revisions of "Unit DMA"

From Ultibo.org
Jump to: navigation, search
 
(22 intermediate revisions by the same user not shown)
Line 5: Line 5:
 
----
 
----
  
−
''To be documented''
+
'''Ultibo DMA Interface unit'''
 +
 
 +
The DMA interfaces are 1 tier (Host only) whereas the USB interface is 3 tier (Host, Device and Driver).
  
 
=== Constants ===
 
=== Constants ===
 
----
 
----
  
−
''To be documented''
+
 
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 20px; padding-bottom: 15px;">
 +
<div style="font-size: 14px; padding-left: 12px;">'''DMA specific constants''' <code> DMA_* </code></div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
| <code>DMA_NAME_PREFIX = 'DMA';</code>
 +
| Name prefix for DMA Hosts
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 20px; padding-bottom: 15px;">
 +
<div style="font-size: 14px; padding-left: 12px;">'''DMA host type''' <code> DMA_TYPE_* </code></div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
| <code>DMA_TYPE_NONE = 0;</code>
 +
| style="width: 50%;"|&nbsp;
 +
|-
 +
|colspan="2"|&nbsp;
 +
|-
 +
| <code>DMA_TYPE_MAX = 0;</code>
 +
| &nbsp;
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 20px; padding-bottom: 15px;">
 +
<div style="font-size: 14px; padding-left: 12px;">'''DMA host state''' <code> DMA_STATE_* </code></div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
| <code>DMA_STATE_DISABLED = 0;</code>
 +
| style="width: 50%;"|&nbsp;
 +
|-
 +
| <code>DMA_STATE_ENABLED = 1;</code>
 +
| &nbsp;
 +
|-
 +
|colspan="2"|&nbsp;
 +
|-
 +
| <code>DMA_STATE_MAX = 1;</code>
 +
| &nbsp;
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 20px; padding-bottom: 15px;">
 +
<div style="font-size: 14px; padding-left: 12px;">'''DMA host flag''' <code> DMA_FLAG_* </code></div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
| <code>DMA_FLAG_NONE = $00000000;</code>
 +
| &nbsp;
 +
|-
 +
| <code>DMA_FLAG_SHARED = $00000001;</code>
 +
| Host requires data buffers in shared memory
 +
|-
 +
| <code>DMA_FLAG_NOCACHE = $00000002;</code>
 +
| Host requires data buffers in non cached memory
 +
|-
 +
| <code>DMA_FLAG_COHERENT = $00000004;</code>
 +
| Data buffers are cache coherent if allocated according to host configuration
 +
|-
 +
| <code>DMA_FLAG_STRIDE = $00000008;</code>
 +
| Host supports 2D stride on source and/or dest address
 +
|-
 +
| <code>DMA_FLAG_DREQ = $00000010;</code>
 +
| Host supports data request gating (DREQ) on source and/or dest address
 +
|-
 +
| <code>DMA_FLAG_NOINCREMENT = $00000020;</code>
 +
| Host supports no increment on source and/or dest address
 +
|-
 +
| <code>DMA_FLAG_NOREAD = $00000040;</code>
 +
| Host supports no read from source address (write to dest address only) (Zero fill the destination)
 +
|-
 +
| <code>DMA_FLAG_NOWRITE = $00000080;</code>
 +
| Host supports no write to dest address (read from source address only) (Cache fill from the source)
 +
|-
 +
| <code>DMA_FLAG_WIDE = $00000100;</code>
 +
| Host supports wide read and/or write
 +
|-
 +
| <code>DMA_FLAG_BULK = $00000200;</code>
 +
| Host supports bulk transfer
 +
|-
 +
| <code>DMA_FLAG_LITE = $00000400;</code>
 +
| Host supports "lite" transfer
 +
|-
 +
| <code>DMA_FLAG_40BIT = $00000800;</code>
 +
| Host supports 40-bit address transfer
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 20px; padding-bottom: 15px;">
 +
<div style="font-size: 14px; padding-left: 12px;">'''DMA data flag''' <code> DMA_DATA_FLAG_* </code></div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
|colspan="2"|See: Platform DMA_DATA_FLAG_*
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 20px; padding-bottom: 15px;">
 +
<div style="font-size: 14px; padding-left: 12px;">'''DMA request flag''' <code> DMA_REQUEST_FLAG_* </code></div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
| <code>DMA_REQUEST_FLAG_NONE = $00000000;</code>
 +
| &nbsp;
 +
|-
 +
| <code>DMA_REQUEST_FLAG_RELEASE = $00000001;</code>
 +
| If set then release the request automatically after completion
 +
|-
 +
| <code>DMA_REQUEST_FLAG_CYCLIC = $00000002;</code>
 +
| This is a cyclic request which loops around from tail to head
 +
|-
 +
| <code>DMA_REQUEST_FLAG_COMPATIBLE = $00000004;</code>
 +
| If set then all buffers supplied are host configuration compatible (Sizing, Alignment, Flags)
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 20px; padding-bottom: 15px;">
 +
<div style="font-size: 14px; padding-left: 12px;">'''DMA logging''' <code> DMA_LOG_* </code></div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
| <code>DMA_LOG_LEVEL_DEBUG = LOG_LEVEL_DEBUG;</code>
 +
| DMA debugging messages
 +
|-
 +
| <code>DMA_LOG_LEVEL_INFO = LOG_LEVEL_INFO;</code>
 +
| DMA informational messages, such as a device being attached or detached
 +
|-
 +
| <code>DMA_LOG_LEVEL_WARN = LOG_LEVEL_WARN;</code>
 +
| DMA warning messages
 +
|-
 +
| <code>DMA_LOG_LEVEL_ERROR = LOG_LEVEL_ERROR;</code>
 +
| DMA error messages
 +
|-
 +
| <code>DMA_LOG_LEVEL_NONE = LOG_LEVEL_NONE;</code>
 +
| No DMA messages
 +
|-
 +
|}
 +
</div></div>
 +
<br />
  
 
=== Type definitions ===
 
=== Type definitions ===
 
----
 
----
  
−
''To be documented''
+
 
 +
'''DMA properties'''
 +
 
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial;">
 +
<code>PDMAProperties = ^TDMAProperties;</code>
 +
 
 +
<code>TDMAProperties = record</code>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
| <code>Flags:LongWord;</code>
 +
| Host flags (eg DMA_FLAG_STRIDE)
 +
|-
 +
| <code>Alignment:LongWord;</code>
 +
| Host data buffer alignment
 +
|-
 +
| <code>Multiplier:LongWord;</code>
 +
| Host data buffer multiplier
 +
|-
 +
| <code>Channels:LongWord;</code>
 +
| Total number of host channels
 +
|-
 +
| <code>MaxSize:LongWord;</code>
 +
| Maximum transfer size
 +
|-
 +
| <code>MaxCount:LongWord;</code>
 +
| Maximum Y count for 2D stride
 +
|-
 +
| <code>MaxLength:LongWord;</code>
 +
| Maximum X length for 2D stride
 +
|-
 +
| <code>MinStride:LongInt;</code>
 +
| Minimum stride value (Increment between rows) May be negative.
 +
|-
 +
| <code>MaxStride:LongWord;</code>
 +
| Maximum stride value (Increment between rows)
 +
|-
 +
|}
 +
</div></div> 
 +
 
 +
'''DMA enumeration callback'''
 +
 
 +
{| class="wikitable" style="font-size: 14px; text-align: left; width: 100%; height: 50px;"
 +
|-
 +
| <code>TDMAEnumerate = function(DMA:PDMAHost; Data:Pointer):LongWord;</code>
 +
| style="width: 40%;"|
 +
|-
 +
|}
 +
 
 +
'''DMA notification callback'''
 +
 
 +
{| class="wikitable" style="font-size: 14px; text-align: left; width: 100%; height: 50px;"
 +
|-
 +
| <code>TDMANotification = function(Device:PDevice; Data:Pointer; Notification:LongWord):LongWord;</code>
 +
| style="width: 40%;"|
 +
|-
 +
|}
 +
 
 +
'''DMA host start'''
 +
 
 +
{| class="wikitable" style="font-size: 14px; text-align: left; width: 100%; height: 50px;"
 +
|-
 +
| <code>TDMAHostStart = function(DMA:PDMAHost):LongWord;</code>
 +
| style="width: 40%;"|
 +
|-
 +
|}
 +
 
 +
'''DMA host stop'''
 +
 
 +
{| class="wikitable" style="font-size: 14px; text-align: left; width: 100%; height: 50px;"
 +
|-
 +
| <code>TDMAHostStop = function(DMA:PDMAHost):LongWord;</code>
 +
| style="width: 40%;"|
 +
|-
 +
|}
 +
 
 +
'''DMA host reset'''
 +
 
 +
{| class="wikitable" style="font-size: 14px; text-align: left; width: 100%; height: 50px;"
 +
|-
 +
| <code>TDMAHostReset = function(DMA:PDMAHost):LongWord;</code>
 +
| style="width: 40%;"|
 +
|-
 +
|}
 +
 
 +
'''DMA host submit'''
 +
 
 +
{| class="wikitable" style="font-size: 14px; text-align: left; width: 100%; height: 50px;"
 +
|-
 +
| <code>TDMAHostSubmit = function(DMA:PDMAHost; Request:PDMARequest):LongWord;</code>
 +
| style="width: 40%;"|
 +
|-
 +
|}
 +
 
 +
'''DMA host cancel'''
 +
 
 +
{| class="wikitable" style="font-size: 14px; text-align: left; width: 100%; height: 50px;"
 +
|-
 +
| <code>TDMAHostCancel = function(DMA:PDMAHost; Request:PDMARequest):LongWord;</code>
 +
| style="width: 40%;"|
 +
|-
 +
|}
 +
 
 +
'''DMA host properties'''
 +
 
 +
{| class="wikitable" style="font-size: 14px; text-align: left; width: 100%; height: 50px;"
 +
|-
 +
| <code>TDMAHostProperties = function(DMA:PDMAHost; Properties:PDMAProperties):LongWord;</code>
 +
| style="width: 40%;"|
 +
|-
 +
|}
 +
 
 +
'''DMA host'''
 +
 
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial;">
 +
<code>PDMAHost = ^TDMAHost;</code>
 +
 
 +
<code>TDMAHost = record</code>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
|colspan="2"|''Device Properties''
 +
|-
 +
| <code>Device:TDevice;</code>
 +
| The Device entry for this DMA host
 +
|-
 +
|colspan="2"|''DMA Properties''
 +
|-
 +
| <code>DMAId:LongWord;</code>
 +
| Unique Id of this DMA host in the DMA host table
 +
|-
 +
| <code>DMAId:LongWord;</code>
 +
| Unique Id of this DMA host in the DMA host table
 +
|-
 +
| <code>DMAState:LongWord;</code>
 +
| DMA state (eg DMA_STATE_ENABLED)
 +
|-
 +
| <code>HostStart:TDMAHostStart;</code>
 +
| A Host specific HostStart method implementing the standard DMA host interface (Mandatory)
 +
|-
 +
| <code>HostStop:TDMAHostStop;</code>
 +
| A Host specific HostStop method implementing the standard DMA host interface (Mandatory)
 +
|-
 +
| <code>HostReset:TDMAHostReset;</code>
 +
| A Host specific HostReset method implementing the standard DMA host interface (Or nil if the default method is suitable)
 +
|-
 +
| <code>HostSubmit:TDMAHostSubmit;</code>
 +
| A Host specific HostSubmit method implementing the standard DMA host interface (Mandatory)
 +
|-
 +
| <code>HostCancel:TDMAHostCancel;</code>
 +
| A Host specific HostCancel method implementing the standard DMA host interface (Mandatory)
 +
|-
 +
| <code>HostProperties:TDMAHostProperties;</code>
 +
| A Host specific HostProperties method implementing the standard DMA host interface (Or nil if the default method is suitable)
 +
|-
 +
|colspan="2"|''Driver Properties''
 +
|-
 +
| <code>Lock:TMutexHandle;</code>
 +
| Host lock
 +
|-
 +
| <code>Alignment:LongWord;</code>
 +
| Host data buffer alignment
 +
|-
 +
| <code>Multiplier:LongWord;</code>
 +
| Host data buffer multiplier
 +
|-
 +
| <code>Properties:TDMAProperties;</code>
 +
| Host properties
 +
|-
 +
| <code>LastError:LongWord;</code>
 +
| Last error to occur on this host
 +
|-
 +
| <code>PendingCount:LongWord;</code>
 +
| Number of DMA requests pending for this host
 +
|-
 +
| <code>WaiterThread:TThreadId;</code>
 +
| Thread waiting for pending requests to complete
 +
|-
 +
|colspan="2"|''Statistics Properties''
 +
|-
 +
| <code>RequestCount:LongWord;</code>
 +
| Number of DMA requests that have been submitted to this host
 +
|-
 +
| <code>RequestErrors:LongWord;</code>
 +
| Number of DMA requests that have failed on this host
 +
|-
 +
|colspan="2"|''Internal Properties''
 +
|-
 +
| <code>Prev:PDMAHost;</code>
 +
| Previous entry in DMA host table
 +
|-
 +
| <code>Next:PDMAHost;</code>
 +
| Next entry in DMA host table
 +
|-
 +
|}
 +
</div></div>
 +
 
 +
'''DMA request completed'''
 +
 
 +
{| class="wikitable" style="font-size: 14px; text-align: left; width: 100%; height: 50px;"
 +
|-
 +
| <code>TDMARequestCompleted = procedure(Request:PDMARequest);</code>
 +
| style="width: 40%;"|
 +
|-
 +
|}
 +
 
 +
'''DMA request'''
 +
 
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial;">
 +
<code>PDMARequest = ^TDMARequest;</code>
 +
 
 +
<code>TDMARequest = record</code>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
|colspan="2"|Note: Forward declared to satisfy DMAHost
 +
|-
 +
|colspan="2"|''Request Properties''
 +
|-
 +
| <code>Host:PDMAHost;</code>
 +
| &nbsp;
 +
|-
 +
| <code>Data:PDMAData;</code>
 +
| List of data blocks for this request
 +
|-
 +
| <code>Flags:LongWord;</code>
 +
| Flags for the request (eg DMA_REQUEST_FLAG_RELEASE)
 +
|-
 +
| <code>Direction:LongWord;</code>
 +
| The direction of the DMA request (eg DMA_DIR_MEM_TO_MEM)
 +
|-
 +
| <code>Peripheral:LongWord;</code>
 +
| The peripheral ID for data request gating (eg DMA_DREQ_ID_NONE)
 +
|-
 +
| <code>Callback:TDMARequestCompleted;</code>
 +
| Callback function that will be called when this DMA request has been successfully completed or has failed
 +
|-
 +
| <code>DriverData:Pointer;</code>
 +
| Private data for the completion callback (Optional)
 +
|-
 +
|colspan="2"|''Result Properties''
 +
|-
 +
| <code>Status:LongWord;</code>
 +
| Status of the request (ERROR_SUCCESS if successful, or another error code if the request failed)
 +
|-
 +
|colspan="2"|''Driver Properties (Private variables for use by Host drivers)''
 +
|-
 +
| <code>ControlBlocks:Pointer;</code>
 +
| &nbsp;
 +
|-
 +
|}
 +
</div></div>
 +
<br />
  
 
=== Public variables ===
 
=== Public variables ===
 
----
 
----
  
−
''To be documented''
+
 
 +
'''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: 40%;"|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: 40%;"|
 +
|-
 +
|}
 +
<br />
  
 
=== Function declarations ===
 
=== Function declarations ===
 
----
 
----
−
<br />
+
 
 +
 
 
'''Initialization functions'''
 
'''Initialization functions'''
  
Line 33: Line 449:
 
{| class="wikitable" style="font-size: 14px; background: white;"
 
{| class="wikitable" style="font-size: 14px; background: white;"
 
|-
 
|-
−
! '''Note'''
+
! Note
 
| None documented
 
| None documented
 
|-
 
|-
Line 48: Line 464:
 
{| class="wikitable" style="font-size: 14px; background: white;"
 
{| class="wikitable" style="font-size: 14px; background: white;"
 
|-
 
|-
−
! '''Note'''
+
! Note
 
| None documented
 
| None documented
 
|-
 
|-
Line 60: Line 476:
 
{| class="wikitable" style="font-size: 14px; background: white;"
 
{| class="wikitable" style="font-size: 14px; background: white;"
 
|-
 
|-
−
! '''Note'''
+
! Note
 
| None documented
 
| None documented
 
|-
 
|-
Line 72: Line 488:
 
{| class="wikitable" style="font-size: 14px; background: white;"
 
{| class="wikitable" style="font-size: 14px; background: white;"
 
|-
 
|-
−
! '''Note'''
+
! Note
 
| None documented
 
| None documented
 
|-
 
|-
Line 84: Line 500:
 
{| class="wikitable" style="font-size: 14px; background: white;"
 
{| class="wikitable" style="font-size: 14px; background: white;"
 
|-
 
|-
−
! '''Note'''
+
! Note
 
| None documented
 
| None documented
 
|-
 
|-
Line 96: Line 512:
 
{| class="wikitable" style="font-size: 14px; background: white;"
 
{| class="wikitable" style="font-size: 14px; background: white;"
 
|-
 
|-
−
! '''Return'''
+
! Return
 
| Pointer to new DMA entry or nil if DMA could not be created
 
| Pointer to new DMA entry or nil if DMA could not be created
 
|-
 
|-
Line 108: Line 524:
 
{| class="wikitable" style="font-size: 14px; background: white;"
 
{| class="wikitable" style="font-size: 14px; background: white;"
 
|-
 
|-
−
! '''Size'''
+
! Size
−
| Size in bytes to allocate for new DMA (Including the DMA entry")
+
| Size in bytes to allocate for new DMA (Including the DMA entry)
 
|-
 
|-
−
! '''Return'''
+
! Return
 
| Pointer to new DMA entry or nil if DMA could not be created
 
| Pointer to new DMA entry or nil if DMA could not be created
 
|-
 
|-
Line 123: Line 539:
 
{| class="wikitable" style="font-size: 14px; background: white;"
 
{| class="wikitable" style="font-size: 14px; background: white;"
 
|-
 
|-
−
! '''Note'''
+
! Note
 
| None documented
 
| None documented
 
|-
 
|-
Line 135: Line 551:
 
{| class="wikitable" style="font-size: 14px; background: white;"
 
{| class="wikitable" style="font-size: 14px; background: white;"
 
|-
 
|-
−
! '''Note'''
+
! Note
 
| None documented
 
| None documented
 
|-
 
|-
Line 147: Line 563:
 
{| class="wikitable" style="font-size: 14px; background: white;"
 
{| class="wikitable" style="font-size: 14px; background: white;"
 
|-
 
|-
−
! '''Note'''
+
! Note
 
| None documented
 
| None documented
 
|-
 
|-
Line 159: Line 575:
 
{| class="wikitable" style="font-size: 14px; background: white;"
 
{| class="wikitable" style="font-size: 14px; background: white;"
 
|-
 
|-
−
! '''Note'''
+
! Note
 
| None documented
 
| None documented
 
|-
 
|-
Line 171: Line 587:
 
{| class="wikitable" style="font-size: 14px; background: white;"
 
{| class="wikitable" style="font-size: 14px; background: white;"
 
|-
 
|-
−
! '''Note'''
+
! Note
 
| None documented
 
| None documented
 
|-
 
|-
Line 183: Line 599:
 
{| class="wikitable" style="font-size: 14px; background: white;"
 
{| class="wikitable" style="font-size: 14px; background: white;"
 
|-
 
|-
−
! '''Note'''
+
! Note
 
| None documented
 
| None documented
 
|-
 
|-
Line 198: Line 614:
 
{| class="wikitable" style="font-size: 14px; background: white;"
 
{| class="wikitable" style="font-size: 14px; background: white;"
 
|-
 
|-
−
! '''Note'''
+
! Note
 
| None documented
 
| None documented
 
|-
 
|-
Line 210: Line 626:
 
{| class="wikitable" style="font-size: 14px; background: white;"
 
{| class="wikitable" style="font-size: 14px; background: white;"
 
|-
 
|-
−
! '''Note'''
+
! Note
 
| None documented
 
| None documented
 
|-
 
|-
Line 222: Line 638:
 
{| class="wikitable" style="font-size: 14px; background: white;"
 
{| class="wikitable" style="font-size: 14px; background: white;"
 
|-
 
|-
−
! '''Note'''
+
! Note
 
| None documented
 
| None documented
 
|-
 
|-
Line 237: Line 653:
 
{| class="wikitable" style="font-size: 14px; background: white;"
 
{| class="wikitable" style="font-size: 14px; background: white;"
 
|-
 
|-
−
! '''DMA'''
+
! DMA
 
| The DMA host that the request will be sent to
 
| The DMA host that the request will be sent to
 
|-
 
|-
−
! '''Size'''
+
! Size
 
| The size of the data buffer to allocate
 
| The size of the data buffer to allocate
 
|-
 
|-
−
! '''Return'''
+
! Return
 
| The newly allocated buffer or nil on failure
 
| The newly allocated buffer or nil on failure
 
|-
 
|-
Line 255: Line 671:
 
{| class="wikitable" style="font-size: 14px; background: white;"
 
{| class="wikitable" style="font-size: 14px; background: white;"
 
|-
 
|-
−
! '''DMA'''
+
! DMA
 
| The DMA host that the request will be sent to
 
| The DMA host that the request will be sent to
 
|-
 
|-
−
! '''Size'''
+
! Size
 
| The size of the data buffer to allocate (Updated on return to actual size)
 
| The size of the data buffer to allocate (Updated on return to actual size)
 
|-
 
|-
−
! '''Return'''
+
! Return
 
| The newly allocated buffer or nil on failure
 
| The newly allocated buffer or nil on failure
 
|-
 
|-
−
! '''Note'''
+
! 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
 
| 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
 
|-
 
|-
Line 276: Line 692:
 
{| class="wikitable" style="font-size: 14px; background: white;"
 
{| class="wikitable" style="font-size: 14px; background: white;"
 
|-
 
|-
−
! '''DMA'''
+
! DMA
 
| The DMA host that the request will be sent to
 
| The DMA host that the request will be sent to
 
|-
 
|-
−
! '''Buffer'''
+
! Buffer
 
| The data buffer to validate
 
| The data buffer to validate
 
|-
 
|-
−
! '''Size'''
+
! Size
 
| The size of the data buffer
 
| The size of the data buffer
 
|-
 
|-
−
! '''Return'''
+
! Return
 
| ERROR_SUCCESS on success or another error code on failure (ERROR_NOT_COMPATIBLE if not compatible with host)
 
| ERROR_SUCCESS on success or another error code on failure (ERROR_NOT_COMPATIBLE if not compatible with host)
 
|-
 
|-
−
! '''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 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.
+
| 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.
 
|-
 
|-
 
|}
 
|}
Line 300: Line 716:
 
{| class="wikitable" style="font-size: 14px; background: white;"
 
{| class="wikitable" style="font-size: 14px; background: white;"
 
|-
 
|-
−
! '''Data'''
+
! Data
 
| The buffer to be released
 
| The buffer to be released
 
|-
 
|-
−
! '''Return'''
+
! Return
 
| ERROR_SUCCESS on success or another error code on failure
 
| ERROR_SUCCESS on success or another error code on failure
 
|-
 
|-
Line 318: Line 734:
 
{| class="wikitable" style="font-size: 14px; background: white;"
 
{| class="wikitable" style="font-size: 14px; background: white;"
 
|-
 
|-
−
! '''DMA'''
+
! DMA
 
| The DMA host this request will be sent to
 
| The DMA host this request will be sent to
 
|-
 
|-
−
! '''Data'''
+
! Data
 
| A linked list of DMA data blocks for the transfer (Optional)
 
| A linked list of DMA data blocks for the transfer (Optional)
 
|-
 
|-
−
! '''Callback'''
+
! Callback
 
| The callback function to be called on completion of the request
 
| The callback function to be called on completion of the request
 
|-
 
|-
−
! '''DriverData'''
+
! DriverData
 
| Driver private data for the callback (Optional)
 
| Driver private data for the callback (Optional)
 
|-
 
|-
−
! '''Direction'''
+
! Direction
 
| The direction of the DMA request (eg DMA_DIR_MEM_TO_MEM)
 
| The direction of the DMA request (eg DMA_DIR_MEM_TO_MEM)
 
|-
 
|-
−
! '''Peripheral'''
+
! Peripheral
 
| The peripheral ID for data request gating (eg DMA_DREQ_ID_NONE)
 
| The peripheral ID for data request gating (eg DMA_DREQ_ID_NONE)
 
|-
 
|-
−
! '''Flags'''
+
! Flags
 
| Additional flags for this request (eg DMA_REQUEST_FLAG_CYCLIC)
 
| Additional flags for this request (eg DMA_REQUEST_FLAG_CYCLIC)
 
|-
 
|-
−
! '''Return'''
+
! Return
 
| The newly allocated request or nil on failure
 
| The newly allocated request or nil on failure
 
|-
 
|-
Line 351: Line 767:
 
{| class="wikitable" style="font-size: 14px; background: white;"
 
{| class="wikitable" style="font-size: 14px; background: white;"
 
|-
 
|-
−
! '''Request'''
+
! Request
 
| The request to be released
 
| The request to be released
 
|-
 
|-
−
! '''Return'''
+
! Return
 
| ERROR_SUCCESS on success or another error code on failure
 
| ERROR_SUCCESS on success or another error code on failure
 
|-
 
|-
Line 366: Line 782:
 
{| class="wikitable" style="font-size: 14px; background: white;"
 
{| class="wikitable" style="font-size: 14px; background: white;"
 
|-
 
|-
−
! '''Request'''
+
! Request
 
| The request to be submitted
 
| The request to be submitted
 
|-
 
|-
−
! '''Return'''
+
! Return
 
| ERROR_SUCCESS if completed or another error code on failure
 
| ERROR_SUCCESS if completed or another error code on failure
 
|-
 
|-
−
! '''Note'''
+
! 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
 
| 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
 
|-
 
|-
Line 384: Line 800:
 
{| class="wikitable" style="font-size: 14px; background: white;"
 
{| class="wikitable" style="font-size: 14px; background: white;"
 
|-
 
|-
−
! '''Request'''
+
! Request
 
| The request to be cancelled
 
| The request to be cancelled
 
|-
 
|-
−
! '''Return'''
+
! Return''
 
| ERROR_SUCCESS if completed or another error code on failure
 
| ERROR_SUCCESS if completed or another error code on failure
 
|-
 
|-
Line 399: Line 815:
 
{| class="wikitable" style="font-size: 14px; background: white;"
 
{| class="wikitable" style="font-size: 14px; background: white;"
 
|-
 
|-
−
! '''Request'''
+
! Request
 
| The DMA request which has completed
 
| The DMA request which has completed
 
|-
 
|-
−
! '''Note'''
+
! Note
 
| DMA host drivers may call this on a worker thread
 
| DMA host drivers may call this on a worker thread
 
|-
 
|-
Line 417: Line 833:
 
{| class="wikitable" style="font-size: 14px; background: white;"
 
{| class="wikitable" style="font-size: 14px; background: white;"
 
|-
 
|-
−
! '''DMA'''
+
! DMA
 
| The DMA host to execute the request on
 
| The DMA host to execute the request on
 
|-
 
|-
−
! '''Data'''
+
! Data
 
| A linked list of DMA data blocks for the transfer
 
| A linked list of DMA data blocks for the transfer
 
|-
 
|-
−
! '''Direction'''
+
! Direction
 
| The direction of the DMA request (eg DMA_DIR_MEM_TO_MEM)
 
| The direction of the DMA request (eg DMA_DIR_MEM_TO_MEM)
 
|-
 
|-
−
! '''Peripheral'''
+
! Peripheral
 
| The peripheral ID for data request gating (eg DMA_DREQ_ID_NONE)
 
| The peripheral ID for data request gating (eg DMA_DREQ_ID_NONE)
 
|-
 
|-
−
! '''Flags'''
+
! Flags
 
| Additional flags for this transfer request (eg DMA_REQUEST_FLAG_CYCLIC)
 
| Additional flags for this transfer request (eg DMA_REQUEST_FLAG_CYCLIC)
 
|-
 
|-
−
! '''Timeout'''
+
! Timeout
 
| Milliseconds to wait for request to complete (INFINITE to wait forever)
 
| Milliseconds to wait for request to complete (INFINITE to wait forever)
 
|-
 
|-
−
! '''Note'''
+
! Note
 
| An internal callback will be specified and the function will wait for the transfer to complete
 
| An internal callback will be specified and the function will wait for the transfer to complete
 
|-
 
|-
Line 441: Line 857:
 
</div></div>
 
</div></div>
 
<br />
 
<br />
−
 
 
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
 
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
 
<pre style="border: 0; padding-bottom:0px;">function DMATransferRequestEx(DMA:PDMAHost; Data:PDMAData; Callback:TDMARequestCompleted; DriverData:Pointer; Direction,Peripheral,Flags:LongWord):LongWord;</pre>
 
<pre style="border: 0; padding-bottom:0px;">function DMATransferRequestEx(DMA:PDMAHost; Data:PDMAData; Callback:TDMARequestCompleted; DriverData:Pointer; Direction,Peripheral,Flags:LongWord):LongWord;</pre>
Line 448: Line 863:
 
{| class="wikitable" style="font-size: 14px; background: white;"
 
{| class="wikitable" style="font-size: 14px; background: white;"
 
|-
 
|-
−
! '''DMA'''
+
! DMA
 
| The DMA host to execute the request on
 
| The DMA host to execute the request on
 
|-
 
|-
−
! '''Data'''
+
! Data
 
| A linked list of DMA data blocks for the transfer
 
| A linked list of DMA data blocks for the transfer
 
|-
 
|-
−
! '''Callback'''
+
! Callback
 
| The callback function to be called on completion of the request
 
| The callback function to be called on completion of the request
 
|-
 
|-
−
! '''DriverData'''
+
! DriverData
 
| Driver private data for the callback (Optional)
 
| Driver private data for the callback (Optional)
 
|-
 
|-
−
! '''Direction'''
+
! Direction
 
| The direction of the DMA request (eg DMA_DIR_MEM_TO_MEM)
 
| The direction of the DMA request (eg DMA_DIR_MEM_TO_MEM)
 
|-
 
|-
−
! '''Peripheral'''
+
! Peripheral
 
| The peripheral ID for data request gating (eg DMA_DREQ_ID_NONE)
 
| The peripheral ID for data request gating (eg DMA_DREQ_ID_NONE)
 
|-
 
|-
−
! '''Flags'''
+
! Flags
 
| Additional flags for this transfer request (eg DMA_REQUEST_FLAG_CYCLIC)
 
| Additional flags for this transfer request (eg DMA_REQUEST_FLAG_CYCLIC)
 
|-
 
|-
−
! '''Note'''
+
! 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.
 
| 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.
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
 +
<pre style="border: 0; padding-bottom:0px;">procedure DMATransferRequestComplete(Request:PDMARequest);</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Called when a DMA transfer request completes</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! Request
 +
| The DMA request which has completed
 +
|-
 +
! Note
 +
| This is the internal callback for DMATransferRequest
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
 +
'''RTL DMA functions'''
 +
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
 +
<pre style="border: 0; padding-bottom:0px;">function SysDMAAvailable:Boolean;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Check if a DMA host is available</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! Note
 +
| None documented
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
 +
<pre style="border: 0; padding-bottom:0px;">function SysDMATransfer(Data:PDMAData; Direction,Peripheral:LongWord):LongWord;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Perform a DMA transfer using the list of DMA data blocks provided</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! 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)
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
 +
<pre style="border: 0; padding-bottom:0px;">function SysDMAFillMemory(Dest:Pointer; Size:LongWord; Value:Byte):LongWord;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Fill memory at the destination address using DMA</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! 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
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
 +
<pre style="border: 0; padding-bottom:0px;">function SysDMACopyMemory(Source,Dest:Pointer; Size:LongWord):LongWord;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Copy memory from the source to the destination address using DMA</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! 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
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
 +
<pre style="border: 0; padding-bottom:0px;">function SysDMAReadPeripheral(Address,Dest:Pointer; Size,Peripheral:LongWord):LongWord;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Read from a periperal address to the destination address using DMA</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! 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)
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
 +
<pre style="border: 0; padding-bottom:0px;">function SysDMAWritePeripheral(Source,Address:Pointer; Size,Peripheral:LongWord):LongWord;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Write to a peripheral address from the source address using DMA</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! 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)
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
 +
<pre style="border: 0; padding-bottom:0px;">function SysDMAAllocateBuffer(Size:LongWord):Pointer;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Allocate a buffer compatible with DMA memory reads or writes</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! Size
 +
| The size of the buffer to allocate
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
 +
<pre style="border: 0; padding-bottom:0px;">function SysDMAAllocateBufferEx(var Size:LongWord):Pointer;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Allocate a buffer compatible with DMA memory reads or writes</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! Size
 +
| The size of the buffer to allocate (Updated on return to actual size)
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
 +
<pre style="border: 0; padding-bottom:0px;">function SysDMAReleaseBuffer(Buffer:Pointer):LongWord;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Release a buffer allocated with DMAAllocateBuffer</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! Buffer
 +
| The buffer to be released
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
 +
'''DMA helper functions'''
 +
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
 +
<pre style="border: 0; padding-bottom:0px;">function DMAGetCount:LongWord;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Get the current DMA host count</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! Note
 +
| None documented
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
 +
<pre style="border: 0; padding-bottom:0px;">function DMAHostGetDefault:PDMAHost;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Get the current default DMA host</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! Note
 +
| None documented
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
 +
<pre style="border: 0; padding-bottom:0px;">function DMAHostSetDefault(DMA:PDMAHost):LongWord;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Set the current default DMA device</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! Note
 +
| None documented
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
 +
<pre style="border: 0; padding-bottom:0px;">function DMAHostCheck(DMA:PDMAHost):PDMAHost;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Check if the supplied DMA is in the DMA host table</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! Note
 +
| None documented
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
 +
<pre style="border: 0; padding-bottom:0px;">function DMATypeToString(DMAType:LongWord):String;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Convert a DMA type value to a string</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! Note
 +
| None documented
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
 +
<pre style="border: 0; padding-bottom:0px;">function DMAStateToString(DMAState:LongWord):String;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Convert a DMA state value to a string</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! Note
 +
| None documented
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
 +
<pre style="border: 0; padding-bottom:0px;">procedure DMALog(Level:Integer; DMA:PDMAHost; const AText:String);</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' To be documented</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! Note
 +
| None documented
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
 +
<pre style="border: 0; padding-bottom:0px;">procedure DMALogInfo(DMA:PDMAHost; const AText:String); inline;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' To be documented</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! Note
 +
| None documented
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
 +
<pre style="border: 0; padding-bottom:0px;">procedure DMALogWarn(DMA:PDMAHost; const AText:String); inline;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' To be documented</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! Note
 +
| None documented
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
 +
<pre style="border: 0; padding-bottom:0px;">procedure DMALogError(DMA:PDMAHost; const AText:String); inline;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' To be documented</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! Note
 +
| None documented
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
 +
<pre style="border: 0; padding-bottom:0px;">procedure DMALogDebug(DMA:PDMAHost; const AText:String); inline;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' To be documented</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! Note
 +
| None documented
 
|-
 
|-
 
|}
 
|}

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

Retrieved from "https://ultibo.org/mediawiki_ultibo_org/index.php?title=Unit_DMA&oldid=5815"