Difference between revisions of "Unit DMA"

From Ultibo.org
Jump to: navigation, search
Line 305: Line 305:
 
! '''Return'''
 
! '''Return'''
 
| ERROR_SUCCESS on success or another error code on failure
 
| ERROR_SUCCESS on success or another error code on failure
 +
|-
 +
|}
 +
</div></div>
 +
<br />
 +
 +
'''DMA request 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 DMARequestAllocate(DMA:PDMAHost; Data:PDMAData; Callback:TDMARequestCompleted; DriverData:Pointer; Direction,Peripheral,Flags:LongWord):PDMARequest;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Allocate a new DMA request</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! '''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
 +
|-
 +
|}
 +
</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 DMARequestRelease(Request:PDMARequest):LongWord;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Release and destroy a DMA request</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! '''Request'''
 +
| The request to be released
 +
|-
 +
! '''Return'''
 +
| ERROR_SUCCESS on success or another error code on failure
 +
|-
 +
|}
 +
</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 DMARequestSubmit(Request:PDMARequest):LongWord;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Submit a DMA request to a DMA host</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! '''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
 +
|-
 +
|}
 +
</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 DMARequestCancel(Request:PDMARequest):LongWord;</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Cancel a DMA request previously submitted to a DMA host</div>
 +
<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
 +
{| class="wikitable" style="font-size: 14px; background: white;"
 +
|-
 +
! '''Request'''
 +
| The request to be cancelled
 +
|-
 +
! '''Return'''
 +
| ERROR_SUCCESS if completed or another error code on failure
 +
|-
 +
|}
 +
</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 DMARequestComplete(Request:PDMARequest);</pre>
 +
<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Called by a DMA host when a DMA 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'''
 +
| DMA host drivers may call this on a worker thread
 
|-
 
|-
 
|}
 
|}

Revision as of 03:24, 28 July 2016

Return to Unit Reference


Description

To be documented

Constants

To be documented

Type definitions

To be documented

Public variables

To be documented

Function declarations


Initialization functions 

procedure DMAInit;
Description: To be documented
Note To be documented


DMA host functions 

function DMAHostStart(DMA:PDMAHost):LongWord;
Description: To be documented
Note To be documented 


function DMAHostStop(DMA:PDMAHost):LongWord;
Description: To be documented
Note To be documented 


function DMAHostReset(DMA:PDMAHost):LongWord;
Description: To be documented
Note To be documented 


function DMAHostProperties(DMA:PDMAHost; Properties:PDMAProperties):LongWord;
Description: To be documented
Note To be 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 To be documented 


function DMAHostRegister(DMA:PDMAHost):LongWord;
Description: Register a new DMA in the DMA host table
Note To be documented 


function DMAHostDeregister(DMA:PDMAHost):LongWord;
Description: Deregister a DMA from the DMA host table
Note To be documented 


function DMAHostFind(DMAId:LongWord):PDMAHost;
Description: To be documented
Note To be documented 


function DMAHostEnumerate(Callback:TDMAEnumerate; Data:Pointer):LongWord;
Description: To be documented
Note To be documented 


function DMAHostNotification(DMA:PDMAHost; Callback:TDMANotification; Data:Pointer; Notification,Flags:LongWord):LongWord;
Description: To be documented
Note To be documented


DMA data functions 

function DMADataCount(Data:PDMAData):LongWord;
Description: Return the total number of data blocks in the linked list
Note To be documented 


function DMADataFlags(Data:PDMAData):LongWord;
Description: Return the combined flags of the data blocks in the linked list
Note To be documented 


function DMADataMaximum(Data:PDMAData):LongWord;
Description: Return the size of the largest data block in the linked list
Note To be documented


DMA buffer functions 

function DMABufferAllocate(DMA:PDMAHost; Size:LongWord):Pointer; inline;
Description: Allocate a data buffer for a DMA request
DMA The DMA host that the request will be sent to
Size The size of the data buffer to allocate
Return The newly allocated buffer or nil on failure 


function DMABufferAllocateEx(DMA:PDMAHost; var Size:LongWord):Pointer;
Description: Allocate a data buffer for a DMA request
DMA The DMA host that the request will be sent to
Size The size of the data buffer to allocate (Updated on return to actual size)
Return The newly allocated buffer or nil on failure
Note This differs from DMABufferAllocate in that it updates the size value to reflect the actual size of the buffer allocated which may be required for some uses 


function DMABufferValidate(DMA:PDMAHost; Buffer:Pointer; Size:LongWord):LongWord;
Description: Validate a data buffer for a DMA request against the DMA host requirements
DMA The DMA host that the request will be sent to
Buffer The data buffer to validate
Size The size of the data buffer
Return ERROR_SUCCESS on success or another error code on failure (ERROR_NOT_COMPATIBLE if not compatible with host)
Note Does not check for cache coherency requirements (Shared, Non Cached) only alignment and size. Buffers used as the source of a DMA request do not neccessarily need to meet alignment and size requirements, however buffers used as a destintation must meet these requirements or the caller must take appropriate actions to prevent undesiraable side effects from cache invalidation. 


function DMABufferRelease(Buffer:Pointer):LongWord;
Description: Release a data buffer from a DMA request
Data The buffer to be released
Return ERROR_SUCCESS on success or another error code on failure


DMA request functions 

function DMARequestAllocate(DMA:PDMAHost; Data:PDMAData; Callback:TDMARequestCompleted; DriverData:Pointer; Direction,Peripheral,Flags:LongWord):PDMARequest;
Description: Allocate a new DMA request
DMA The DMA host this request will be sent to
Data A linked list of DMA data blocks for the transfer (Optional)
Callback The callback function to be called on completion of the request
DriverData Driver private data for the callback (Optional)
Direction The direction of the DMA request (eg DMA_DIR_MEM_TO_MEM)
Peripheral The peripheral ID for data request gating (eg DMA_DREQ_ID_NONE)
Flags Additional flags for this request (eg DMA_REQUEST_FLAG_CYCLIC)
Return The newly allocated request or nil on failure 


function DMARequestRelease(Request:PDMARequest):LongWord;
Description: Release and destroy a DMA request
Request The request to be released
Return ERROR_SUCCESS on success or another error code on failure 


function DMARequestSubmit(Request:PDMARequest):LongWord;
Description: Submit a DMA request to a DMA host
Request The request to be submitted
Return ERROR_SUCCESS if completed or another error code on failure
Note The request will be completed asynchronously by the DMA host and the completion callback will be called when the request has either succeeded or failed 


function DMARequestCancel(Request:PDMARequest):LongWord;
Description: Cancel a DMA request previously submitted to a DMA host
Request The request to be cancelled
Return ERROR_SUCCESS if completed or another error code on failure 


procedure DMARequestComplete(Request:PDMARequest);
Description: Called by a DMA host when a DMA request completes
Request The DMA request which has completed
Note DMA host drivers may call this on a worker thread



Return to Unit Reference

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