Difference between revisions of "Unit DMA"
From Ultibo.org
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