AmigaOS Documentation Wiki - User contributions [en]

Resources

2023-10-18T20:51:58Z

Jamie Krueger: /* System Resources */

== Introduction ==

Resources are responsible for low-level hardware control, see [[Exec Resources]] to have a better insight of what it is and how it's used.

== System Resources ==

[[BattClock Resource]]

[[BattMem Resource]]

[[CIA Resource]]

[[Disk Resource]]

[[DMA Resource]]

[[FileSystem Resource]]

[[Misc Resource]]

[[Potgo Resource]]

[[PerformanceMonitor Resource]]

[[Xena Resource]]

DMA Engine

2023-10-18T20:50:15Z

Jamie Krueger: Jamie Krueger moved page DMA Engine to DMA Resource: Renaming to reflect that this page covers the fsldma.resource API and not just a discussion of the underlined DMA Engine.

#REDIRECT [[DMA Resource]]

DMA Resource

2023-10-18T20:50:15Z

Jamie Krueger: Jamie Krueger moved page DMA Engine to DMA Resource: Renaming to reflect that this page covers the fsldma.resource API and not just a discussion of the underlined DMA Engine.

== Author ==

Jamie Krueger, BITbyBIT Software Group LLC 
Copyright (c) 2019, 2021 Trevor Dickinson 
Used by permission.

== DMA Engine ==

Some hardware targets include a DMA engine which can be used for general purpose copying. This article describes the DMA engines available and how to use them.

=== Hardware Features ===

The Direct Memory Access (DMA) Engines found in the NXP/Freescale p5020, p5040 and p1022 System On a Chip (SoC)s, as found in the AmigaONE X5000/20, X5000/40 and A1222 respectively, are quite flexible and powerful. Each of these chips contains two distinct engines with four data channels each. This provides the ability to have a total of eight DMA Channels working at once, with up to two DMA transactions actually being executed at the same time (one on each of the two DMA Engines).

Further, each of the four DMA Channels found in a DMA Engine may be individually programmed to handle either; a single transaction, a ''Chain'' of transactions, or even ''Lists'' of ''Chains'' of transactions. The DMA Engines automatically arbitrate control between each DMA Channel following programmed bandwidth settings for each Channel (typically 1024 bytes).

This means that after completing a transfer of 1024 bytes (for example), the hardware will consider switching to the next Channel to allow it to move another block of data, and so on in a round-robin fashion. If all other DMA Channels on a given DMA Engine are idle when arbitration would take place, the hardware will not arbitrate control to another Channel, but simply continue processing the transaction(s) for the Channel it is on.

=== DMA Copy Memory - Execution Flow Diagram ===

[[File:DMACopyMem-Diagram.png]]

=== What a call to perform a DMA copy does internally ===

As shown in the above diagram, when the user makes a call to request a memory copy be performed by the DMA hardware, the next available DMA Channel is selected for use and a DMA Transaction (source, destination and size) is constructed. The DMA Transaction is then programmed into the DMA Engine which owns the available DMA Channel.

At this point the calling task will Wait() until it hears the transaction has been completed. It will then return to the caller with the result. This provides a basic ''blocking'' function, which only returns to the caller once that data has been copied. This single tasking behavior is the simplest to use and what is normally expected by most applications using a memory copy function.

=== Diagram of multitasking DMA Copies ===

[[File:DMACopyMem-Multitasking-Diagram.png]]

=== How multiple simultaneous DMA copies are handled ===

When multiple user calls requesting a DMA copy arrive at once, each one is handed to a dedicated DMA Channel handling task for processing. As the diagram above demonstrates, there are two separate DMA Engines available, each with four channels that may be programmed at the same time. The hardware will then arbitrate the actual data move across these channels according to their respective bandwidth settings (usually 1024 bytes).

In the diagram above, a separate color indicates a distinct data path from the caller through the DMA hardware to the system RAM. A dashed line of the matching color indicates an Interrupt line signaling the respective DMA Channel Handler with the completion of the transaction. The handler task then signals back to the original caller, which returns to the user with a success or failure result.

All eight DMA Channels can handle each a single block transaction or an entire chain of block transactions before it signals completion and returns to the original caller. If all eight DMA Channels are busy processing their requested transactions when further DMA copy requests arrive, they will each be assigned a DMA Channel to wait on (managed via a Mutex lock on each Channel) and will block until allowed to add their DMA transaction to the Channel's queue.

== fsldma.resource ==

The fsldma.resource API is provided automatically in the kernel for all supported machines (Currently the AmigaONE X5000/20, X5000/40 and A1222).

=== The FslDMA API ===

The API provided by the fsldma.resource current consists of:
:* Copy Memory functions

==== Copy Memory Functions ====

Three API calls make up the FslDMA API; CopyMemDMA(), CopyMemDMATagList() and CopyMemDMATags().

<syntaxhighlight>
BOOL CopyMemDMA( CONST_APTR pSourceBuffer, APTR pDestBuffer, uint32 lBufferSize );
BOOL CopyMemDMATags( CONST_APTR pSourceBuffer, APTR pDestBuffer, uint32 lBufferSize, uint32 TagItem1, ... );
BOOL CopyMemDMATagList( CONST_APTR pSourceBuffer, APTR pDestBuffer, uint32 lBufferSize, const struct TagItem *tags );
</syntaxhighlight>

The first call, CopyMemDMA(), attempts to perform a "blocking" (does not return to the user until after the requested transfer has either succeeded or failed) operation. A value of TRUE is returned upon success and FALSE if an error occurred. The CopyMemDMA() call will automatically fall back to using an internal fast CPU copy if the requested size is too small to be efficient, or an error occurred in the DMA transaction.

In theory any ''contiguous'' block of memory from 1 Byte up to 4GB in size may be transferred using any one of these calls. In practice the DMA hardware can directly accept memory blocks up to FSLDMA_MAXBLOCK_SIZE (or 64MB - 1 Byte). Therefore any data blocks greater than FSLDMA_MAXBLOCK_SIZE will automatically be sent to the DMA hardware in a series of smaller chunks. For maximum efficiency transfer sizes should be at least 256 Bytes in size and be an even multiple of 64 Bytes. Odd sizes are handled by the hardware but will degrade performance.

==== Further reference - The fsldma.resource AutoDoc ====

See the [[http://wiki.amigaos.net/amiga/autodocs/fsldmares.doc.txt fsldma.resource AutoDoc]] file for more details on each API call.

=== Example 1: "Blocking" mode ===

<syntaxhighlight>
#include <stdio.h>
#include <stdlib.h>
#include <amiga_compiler.h>
#include <exec/types.h>
#include <proto/exec.h>
#include <dos/dos.h>
#include <interfaces/exec.h>
#include <interfaces/fsldma.h>

// fsldma.resource Example 1, "Blocking" DMA Copy
// test using Virtual memory areas
int main()
{
struct fslDMAIFace *IfslDMA = NULL;
uint32 lSize = 0;
CONST_APTR pSrc = NULL;
APTR pDest = NULL;
BOOL bGotResources = FALSE;

// Obtain the fsldma.resource
IfslDMA = IExec->OpenResource(FSLDMA_NAME);

// Set the size of our test buffers
lSize = FSLDMA_OPTIMAL_BLKSIZE; // About 64 MB

// Allocate a test source buffer (fill with some data)
pSrc = IExec->AllocVecTags(lSize,
AVT_Type, MEMF_SHARED,
AVT_ClearWithValue, 0xB3,
TAG_DONE);

// Allocate a test destination buffer (clear with zeroes)
pDest = IExec->AllocVecTags(lSize,
AVT_Type, MEMF_SHARED,
AVT_ClearWithValue, 0,
TAG_DONE);

// Verify we got all resources needed for the test
if ( (NULL != IfslDMA) && (NULL != pSrc) && (NULL != pDest) )
{
bGotResources = TRUE;
}

if ( TRUE == bGotResources )
{
// Call IfslDMA->CopyMemDMA() to perform the memory copy using the
// DMA hardware. Wait for the transaction to complete before continuing.

printf("Starting \"Blocking\" DMA Transaction"
" of %ld bytes from 0x%08lx to 0x%08lx...\n",lSize,pSrc,pDest);
fflush(stdout);

if ( TRUE == IfslDMA->CopyMemDMA(pSrc,pDest,lSize) )
{
// Success - Do something with the copied data and quit
printf("Returned with Success.\n");
fflush(stdout);
}
else
{
// Report the error
printf("Received an Error!\n");
fflush(stdout);
}
}
else
{
printf("Failed to obtain resources, aborting test.\n");
fflush(stdout);
}

// Free our test buffers (as needed)
if ( NULL != pSrc ) IExec->FreeVec((APTR)pSrc);
if ( NULL != pDest ) IExec->FreeVec(pDest);
}
</syntaxhighlight>

=== Example 2: "Non-Blocking" mode ===

<syntaxhighlight>
#include <stdio.h>
#include <stdlib.h>
#include <amiga_compiler.h>
#include <exec/types.h>
#include <proto/exec.h>
#include <dos/dos.h>
#include <interfaces/exec.h>
#include <interfaces/fsldma.h>

// fsldma.resource Example 2, "Non-blocking" DMA Copy
// test using user notifications and Physical memory areas
int main()
{
struct ExecBase *ExecBase = (*(struct ExecBase **)4);
struct MMUIFace *IMMU = NULL;
struct fslDMAIFace *IfslDMA = NULL;
uint32 lSize = 0;
CONST_APTR pSrc = NULL;
APTR pDest = NULL;
CONST_APTR pPhySrcAttr = NULL;
APTR pPhyDstAttr = NULL;
int8 nSuccessSigNum = -1;
int8 nInProgressSigNum = -1;
int8 nErrorSigNum = -1;
uint32 lSuccessSigMask = 0;
uint32 lInProgressSigMask = 0;
uint32 lErrorSigMask = 0;
uint32 lAllSigsMask = 0;
BOOL bGotResources = FALSE;

// Obtain the MMU Interface
IMMU = (struct MMUIFace *)IExec->GetInterface((struct Library *)ExecBase,
"MMU",1,NULL);
// Obtain the fsldma.resource
IfslDMA = IExec->OpenResource(FSLDMA_NAME);

// Set our test buffer size large enough to generate some sub-block transfers
lSize = FSLDMA_OPTIMAL_BLKSIZE * 4; // About 256 MB

// Allocate a test source buffer (fill with some data)
pSrc = IExec->AllocVecTags(lSize,
AVT_Type, MEMF_SHARED,
AVT_Contiguous, TRUE,
AVT_Lock, TRUE,
AVT_Alignment, 64,
AVT_PhysicalAlignment, 64,
AVT_ClearWithValue, 0xB3,
TAG_DONE);

// Allocate a test destination buffer (clear with zeroes)
pDest = IExec->AllocVecTags(lSize,
AVT_Type, MEMF_SHARED,
AVT_Contiguous, TRUE,
AVT_Lock, TRUE,
AVT_Alignment, 64,
AVT_PhysicalAlignment, 64,
AVT_ClearWithValue, 0,
TAG_DONE);

// Allocate signals to wait on
nSuccessSigNum = IExec->AllocSignal((int8)-1);
nInProgressSigNum = IExec->AllocSignal((int8)-1);
nErrorSigNum = IExec->AllocSignal((int8)-1);

// Construct the signal masks we need to Wait() on later.
// We are assuming these values are being built with
// allocated signals here, but we will verify it before use.
lSuccessSigMask = (uint32)(1L << nSuccessSigNum);
lInProgressSigMask = (uint32)(1L << nInProgressSigNum);
lErrorSigMask = (uint32)(1L << nErrorSigNum);
lAllSigsMask = (lSuccessSigMask | lInProgressSigMask | lErrorSigMask);

// Obtain the pointer to ourselves (this Task)
struct Task *pThisTask = IExec->FindTask(NULL);

// Verify we got all resources needed for the test
if ( (NULL != IMMU) && (NULL != IfslDMA) &&
(NULL != pSrc) && (NULL != pDest) &&
(NULL != pThisTask ) &&
(-1 != nSuccessSigNum) &&
(-1 != nInProgressSigNum) &&
(-1 != nErrorSigNum) )
{
bGotResources = TRUE;
}

if ( TRUE == bGotResources )
{
// In this test we are using Physical memory areas
// for both source and destination, so before we
// hand the transaction to the DMA hardware, we first
// need to set the flush the data cache, set the
// buffers to cache-inhibited and obtain the Physical
// addresses for both buffers

// Enter Supervisor Mode
APTR pUserStack = IExec->SuperState();

// Flush out any cache for our two buffers
IExec->CacheClearE((APTR)pSrc,lSize,CACRF_ClearD);
IExec->CacheClearE(pDest,lSize,CACRF_ClearD);

// Now set the memory attributes to prevent further cache operations
uint32 lSrcMemAttrs = IMMU->GetMemoryAttrs((APTR)pSrc,0);
uint32 lDstMemAttrs = IMMU->GetMemoryAttrs(pDest,0);
IMMU->SetMemoryAttrs((APTR)pSrc,lSize,(lSrcMemAttrs | FSLDMA_PHYMEM_ATTRS));
IMMU->SetMemoryAttrs(pDest,lSize,(lDstMemAttrs | FSLDMA_PHYMEM_ATTRS));

// Get the Physical addresses for our two buffers
pPhySrcAttr = IMMU->GetPhysicalAddress((APTR)pSrc);
pPhyDstAttr = IMMU->GetPhysicalAddress(pDest);

// Return to User Mode
if ( NULL != pUserStack ) IExec->UserState(pUserStack);

// Call IfslDMA->CopyMemDMATags() to perform the memory copy using the
// DMA hardware. Start off the transaction then wait on completion signals.

printf("Starting \"Non-Blocking\" DMA Transaction"
" of %ld bytes from 0x%08lx to 0x%08lx...\n",
lSize,pPhySrcAttr,pPhyDstAttr);
fflush(stdout);

if ( TRUE == IfslDMA->CopyMemDMATags(pPhySrcAttr,pPhyDstAttr,lSize,
FSLDMA_CM_SourceIsPhysical, TRUE,
FSLDMA_CM_DestinationIsPhysical, TRUE,
FSLDMA_CM_DoNotWait, TRUE,
FSLDMA_CM_NotifyTask, pThisTask,
FSLDMA_CM_NotifySignalNumber, nSuccessSigNum,
FSLDMA_CM_NotifyProgessSignalNumber, nInProgressSigNum,
FSLDMA_CM_NotifyErrorSignalNumber, nErrorSigNum,
TAG_DONE) )
{
// If the above call sets up correctly, it returns immeditately
// So do something here *while* the data is being copied...
printf("Doing other stuff before waiting...\n");
fflush(stdout);

// Now we will Wait() for the completion signals from the DMA
BOOL bStillRunning = TRUE;
uint32 lSigReceived = 0;
do
{
// Wait for the DMA completion/status/error signals
printf("Waiting for signals...\n");
fflush(stdout);
lSigReceived = IExec->Wait( lAllSigsMask | SIGBREAKF_CTRL_C );

// Test for the "In Progress" signal
if ( lInProgressSigMask == (lSigReceived & lInProgressSigMask) )
{
// Do something on the "In Process" signal and continue...
printf("Received an \"In Progress\" signal...\n");
fflush(stdout);
}

// Test for the "Success" signal
if ( lSuccessSigMask == (lSigReceived & lSuccessSigMask) )
{
// Success - Do something with the copied data and quit
printf("Received an \"Completed Successfully\" signal.\n");
fflush(stdout);
bStillRunning = FALSE;
}

// Test for the "Error" signal
if ( lErrorSigMask == (lSigReceived & lErrorSigMask) )
{
// Report the error and quit
printf("Received an \"Error\" signal!\n");
fflush(stdout);
bStillRunning = FALSE;
}

// Finally, check if we got a Break signal from the user
// just in case we want to quit out early for some reason
if ( SIGBREAKF_CTRL_C == (lSigReceived & SIGBREAKF_CTRL_C) )
{
printf("Received an \"User break\" signal, ending.\n");
fflush(stdout);
bStillRunning = FALSE;
}
} while( TRUE == bStillRunning );
}
}
else
{
printf("Failed to obtain resources, aborting test.\n");
fflush(stdout);
}

// Free our test buffers (as needed)
if ( NULL != pSrc ) IExec->FreeVec((APTR)pSrc);
if ( NULL != pDest ) IExec->FreeVec(pDest);
// Free any signals we (may have) obtained earlier
if ( -1 != nSuccessSigNum ) IExec->FreeSignal(nSuccessSigNum);
if ( -1 != nInProgressSigNum ) IExec->FreeSignal(nInProgressSigNum);
if ( -1 != nErrorSigNum ) IExec->FreeSignal(nErrorSigNum);
// Release the MMU Interface (as needed)
if ( NULL != IMMU ) IExec->DropInterface((struct Interface *)IMMU);
}
</syntaxhighlight>

==== Obtaining the fsldma.resource ====

Breaking the above example down the first thing we do is include the interface header for the fsldma.resource and obtain the resource itself.

<syntaxhighlight>
#include <interfaces/fsldma.h>
struct fslDMAIFace *IfslDMA = IExec->OpenResource(FSLDMA_NAME);
</syntaxhighlight>

== Performance ==

Testing DMA memory copies vs their CPU based equivalent indicates that the DMA hardware on all three models (X5000/20, X5000/40 and A1222)
move data approximately two to three times faster than the CPU does so alone.

It should also be noted that these tests were performed when the CPU was effectively idle. CPU memory copy operations scale down roughly
equal with the CPU actively scaling up. So the more the CPU is doing, the longer it takes to complete the memory copy.

Conversely, DMA memory copy operation times are far more predictable as they use the same amount of (minimal) CPU overhead for each copy,
and the actual time it takes the DMA hardware to complete the transaction can be calculated to range from all the DMA Channels being idle,
to all DMA Channels being busy at once and data moves arbitrating between channels every 1024 bytes.

=== Optimal use of the DMA Engine ===

To gain the best performance from the DMA Engines, block sizes of 256 bytes or more should be used.
Also, if possible the size should be an even multiple of at least 4 bytes.

Additionally the memory blocks (source and destination) should be aligned to start on a 64 Byte boundary.

The DMA Engine can and does handle misaligned and odd sized data blocks by first shifting the minimum
required bytes to correct the alignment, then taking smaller chunks of data until the largest chunk of
the block can be moved. It can also handle copies of as little as one byte (don't do this).

However, this does degrade performance.

In general, the larger the data block the better.

== Current fsldma.resource API release notes ==

<pre>
fsldma.resource 53.1 (30.9.2019) <jkrueger>

- First release.

fsldma.resource 53.2 (4.11.2019) <jkrueger>

- Replaced the Busy Wait polling of the DMA Channel
completion status with a fully event (interrupt)
driven, multitasking task handler system.

fsldma.resource 53.3 (22.11.2019) <jkrueger>

- Reworked DMACopyMem() to properly handle normal
cache-enabled virtual memory blocks using a
combination of StartDMA()/EndDMA() and "CPU Snoop"
mode on the DMA hardware.

fsldma.resource 53.4 (4.12.2019) <jkrueger>

- Major API rework and streamlining.
Removed all other API calls save DMACopyMem().
DMACopyMem() was renamed CopyMemDMA() and new
TagItem based versions were added; CopyMemDMATagList()
and CopyMemDMATags().

Seven new Tags were added to the API for use
with the Tags version of CopyMemDMA. They enable
using any combination of Virtual and Physical
memory copies and support for new "Non-Blocking"
transactions with user Notification via three
possible signals; "Success", "In Progress" and "Error."

Several internal changes and improvements including
but not limited to, streamlining internal signal
handling between DMA Handler Tasks and user tasks
and optimizing transactions using "Basic Chaining Mode."

The DMA hardware's "Basic Chaining Mode" is now used
internally to transfer larger single block sizes.
Blocks greater than FSLDMA_OPTIMAL_BLKSIZE is size
are transferred using "Basic Chaining Mode", while
blocks less than or equal to FSLDMA_OPTIMAL_BLKSIZE
are transferred using "Basic Direct Mode."

Previously, block sizes larger than FSLDMA_OPTIMAL_BLKSIZE
were all transfered using a CPU driven loop of
"Basic Direct Mode" transactions. This internal CPU
driven loop has now been replaced by programming the
hardware to perform a series of block transactions
in a "Chain" as a single hardware transaction.
This also enabled bringing out "Completed Successfully",
"In Progress" (a sub-block has transferred successfully)
and "Error" signaling during "Non-Blocking" transactions.

Note:
Currently only source and destination memory
areas of the same type, Virtual-to-Virtual or
Physical-to-Physical are supported.

Also, only Physical-to-Physical transactions
support "Non-Blocking" transactions and User
Notification signaling.

Future releases will remove these limitations.
</pre>

Autodocs:Main

2023-10-18T19:49:21Z

Jamie Krueger:

The autodocs are included in the latest [[SDK_FAQ|AmigaOS SDK]] and are also available as text files below:

* [http://wiki.amigaos.net/amiga/autodocs/a1floppy.doc.txt a1floppy.doc]
* [http://wiki.amigaos.net/amiga/autodocs/a1serial_dev.doc.txt a1serial_dev.doc]
* [http://wiki.amigaos.net/amiga/autodocs/AI_Driver.doc.txt AI_Driver.doc]
* [http://wiki.amigaos.net/amiga/autodocs/amigaguide.doc.txt amigaguide.doc]
* [http://wiki.amigaos.net/amiga/autodocs/amigaguide_dtc.doc.txt amigaguide_dtc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/AmigaInput.doc.txt AmigaInput.doc]
* [http://wiki.amigaos.net/amiga/autodocs/amiga_lib.doc.txt amiga_lib.doc]
* [http://wiki.amigaos.net/amiga/autodocs/animation_dtc.doc.txt animation_dtc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/application.doc.txt application.doc]
* [http://wiki.amigaos.net/amiga/autodocs/arexx_cl.doc.txt arexx_cl.doc]
* [http://wiki.amigaos.net/amiga/autodocs/asl.doc.txt asl.doc]
* [http://wiki.amigaos.net/amiga/autodocs/audio.doc.txt audio.doc]
* [http://wiki.amigaos.net/amiga/autodocs/battclock.doc.txt battclock.doc]
* [http://wiki.amigaos.net/amiga/autodocs/battmem.doc.txt battmem.doc]
* [http://wiki.amigaos.net/amiga/autodocs/bevel_ic.doc.txt bevel_ic.doc]
* [http://wiki.amigaos.net/amiga/autodocs/biosversion.doc.txt biosversion.doc]
* [http://wiki.amigaos.net/amiga/autodocs/bitmap_ic.doc.txt bitmap_ic.doc]
* [http://wiki.amigaos.net/amiga/autodocs/bsdsocket.doc.txt bsdsocket.doc]
* [http://wiki.amigaos.net/amiga/autodocs/btree.doc.txt btree.doc]
* [http://wiki.amigaos.net/amiga/autodocs/bullet.doc.txt bullet.doc]
* [http://wiki.amigaos.net/amiga/autodocs/button_gc.doc.txt button_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/camd.doc.txt camd.doc]
* [http://wiki.amigaos.net/amiga/autodocs/cardres.doc.txt cardres.doc]
* [http://wiki.amigaos.net/amiga/autodocs/cd.doc.txt cd.doc]
* [http://wiki.amigaos.net/amiga/autodocs/checkbox_gc.doc.txt checkbox_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/chooser_gc.doc.txt chooser_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/cia.doc.txt cia.doc]
* [http://wiki.amigaos.net/amiga/autodocs/clicktab_gc.doc.txt clicktab_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/clipboard.doc.txt clipboard.doc]
* [http://wiki.amigaos.net/amiga/autodocs/colorwheel_gc.doc.txt colorwheel_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/commodities.doc.txt commodities.doc]
* [http://wiki.amigaos.net/amiga/autodocs/console.doc.txt console.doc]
* [http://wiki.amigaos.net/amiga/autodocs/datatypes.doc.txt datatypes.doc]
* [http://wiki.amigaos.net/amiga/autodocs/datebrowser_gc.doc.txt datebrowser_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/ddebug_lib.doc.txt ddebug_lib.doc]
* [http://wiki.amigaos.net/amiga/autodocs/debug_lib.doc.txt debug_lib.doc]
* [http://wiki.amigaos.net/amiga/autodocs/diffview_gc.doc.txt diffview_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/disk.doc.txt disk.doc]
* [http://wiki.amigaos.net/amiga/autodocs/diskfont.doc.txt diskfont.doc]
* [http://wiki.amigaos.net/amiga/autodocs/diskio.doc.txt diskio.doc]
* [http://wiki.amigaos.net/amiga/autodocs/docky.doc.txt docky.doc]
* [http://wiki.amigaos.net/amiga/autodocs/dos.doc.txt dos.doc]
* [http://wiki.amigaos.net/amiga/autodocs/dos.dospackets.doc.txt dos.dospackets.doc]
* [http://wiki.amigaos.net/amiga/autodocs/dos.obsolete.doc.txt dos.obsolete.doc]
* [http://wiki.amigaos.net/amiga/autodocs/drawlist_ic.doc.txt drawlist_ic.doc]
* [http://wiki.amigaos.net/amiga/autodocs/elf.doc.txt elf.doc]
* [http://wiki.amigaos.net/amiga/autodocs/exec.doc.txt exec.doc]
* [http://wiki.amigaos.net/amiga/autodocs/expansion.doc.txt expansion.doc]
* [http://wiki.amigaos.net/amiga/autodocs/filesysbox.doc.txt filesysbox.doc]
* [http://wiki.amigaos.net/amiga/autodocs/filesysres.doc.txt filesysres.doc]
* [http://wiki.amigaos.net/amiga/autodocs/filler_ic.doc.txt filler_ic.doc]
* [http://wiki.amigaos.net/amiga/autodocs/fillrect_ic.doc.txt fillrect_ic.doc]
* [http://wiki.amigaos.net/amiga/autodocs/frame_ic.doc.txt frame_ic.doc]
* [http://wiki.amigaos.net/amiga/autodocs/frbutton_gc.doc.txt frbutton_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/fuelgauge_gc.doc.txt fuelgauge_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/gadget_gc.doc.txt gadget_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/gadtools.doc.txt gadtools.doc]
* [http://wiki.amigaos.net/amiga/autodocs/gameport.doc.txt gameport.doc]
* [http://wiki.amigaos.net/amiga/autodocs/Gameport_pci.doc.txt Gameport_pci.doc]
* [http://wiki.amigaos.net/amiga/autodocs/gauge_ic.doc.txt gauge_ic.doc]
* [http://wiki.amigaos.net/amiga/autodocs/getcolor_gc.doc.txt getcolor_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/getfile_gc.doc.txt getfile_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/getfont_gc.doc.txt getfont_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/getscreenmode_gc.doc.txt getscreenmode_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/glyph_ic.doc.txt glyph_ic.doc]
* [http://wiki.amigaos.net/amiga/autodocs/gradientslider_gc.doc.txt gradientslider_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/graphics.doc.txt graphics.doc]
* [http://wiki.amigaos.net/amiga/autodocs/group_gc.doc.txt group_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/hunk.doc.txt hunk.doc]
* [http://wiki.amigaos.net/amiga/autodocs/ibutton_gc.doc.txt ibutton_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/icon.doc.txt icon.doc]
* [http://wiki.amigaos.net/amiga/autodocs/iconmodule.doc.txt iconmodule.doc]
* [http://wiki.amigaos.net/amiga/autodocs/ic_cl.doc.txt ic_cl.doc]
* [http://wiki.amigaos.net/amiga/autodocs/iffparse.doc.txt iffparse.doc]
* [http://wiki.amigaos.net/amiga/autodocs/image_ic.doc.txt image_ic.doc]
* [http://wiki.amigaos.net/amiga/autodocs/input.doc.txt input.doc]
* [http://wiki.amigaos.net/amiga/autodocs/integer_gc.doc.txt integer_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/intuition.doc.txt intuition.doc]
* [http://wiki.amigaos.net/amiga/autodocs/iscroller_gc.doc.txt iscroller_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/istring_gc.doc.txt istring_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/itext_ic.doc.txt itext_ic.doc]
* [http://wiki.amigaos.net/amiga/autodocs/keyboard.doc.txt keyboard.doc]
* [http://wiki.amigaos.net/amiga/autodocs/keymap.doc.txt keymap.doc]
* [http://wiki.amigaos.net/amiga/autodocs/label_ic.doc.txt label_ic.doc]
* [http://wiki.amigaos.net/amiga/autodocs/layers.doc.txt layers.doc]
* [http://wiki.amigaos.net/amiga/autodocs/layout_gc.doc.txt layout_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/libamiga_a.doc.txt libamiga_a.doc]
* [http://wiki.amigaos.net/amiga/autodocs/listbrowser_gc.doc.txt listbrowser_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/locale.doc.txt locale.doc]
* [http://wiki.amigaos.net/amiga/autodocs/lowlevel.doc.txt lowlevel.doc]
* [http://wiki.amigaos.net/amiga/autodocs/mathffp.doc.txt mathffp.doc]
* [http://wiki.amigaos.net/amiga/autodocs/mathieeedoubbas.doc.txt mathieeedoubbas.doc]
* [http://wiki.amigaos.net/amiga/autodocs/mathieeedoubtrans.doc.txt mathieeedoubtrans.doc]
* [http://wiki.amigaos.net/amiga/autodocs/mathieeesingbas.doc.txt mathieeesingbas.doc]
* [http://wiki.amigaos.net/amiga/autodocs/mathieeesingtrans.doc.txt mathieeesingtrans.doc]
* [http://wiki.amigaos.net/amiga/autodocs/mathtrans.doc.txt mathtrans.doc]
* [http://wiki.amigaos.net/amiga/autodocs/menu_cl.doc.txt menu_cl.doc]
* [http://wiki.amigaos.net/amiga/autodocs/misc.doc.txt misc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/model_cl.doc.txt model_cl.doc]
* [http://wiki.amigaos.net/amiga/autodocs/narrator.doc.txt narrator.doc]
* [http://wiki.amigaos.net/amiga/autodocs/nonvolatile.doc.txt nonvolatile.doc]
* [http://wiki.amigaos.net/amiga/autodocs/openfirmware.doc.txt openfirmware.doc]
* [http://wiki.amigaos.net/amiga/autodocs/page_gc.doc.txt page_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/palette_gc.doc.txt palette_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/parallel.doc.txt parallel.doc]
* [http://wiki.amigaos.net/amiga/autodocs/partition_gc.doc.txt partition_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/penmap_ic.doc.txt penmap_ic.doc]
* [http://wiki.amigaos.net/amiga/autodocs/performancemonitor.doc.txt performancemonitor.doc]
* [http://wiki.amigaos.net/amiga/autodocs/Picasso96API.doc.txt Picasso96API.doc]
* [http://wiki.amigaos.net/amiga/autodocs/picture_dtc.doc.txt picture_dtc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/pointer_cl.doc.txt pointer_cl.doc]
* [http://wiki.amigaos.net/amiga/autodocs/popupmenu_cl.doc.txt popupmenu_cl.doc]
* [http://wiki.amigaos.net/amiga/autodocs/potgo.doc.txt potgo.doc]
* [http://wiki.amigaos.net/amiga/autodocs/printer.doc.txt printer.doc]
* [http://wiki.amigaos.net/amiga/autodocs/prop_gc.doc.txt prop_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/radiobutton_gc.doc.txt radiobutton_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/realtime.doc.txt realtime.doc]
* [http://wiki.amigaos.net/amiga/autodocs/requester_cl.doc.txt requester_cl.doc]
* [http://wiki.amigaos.net/amiga/autodocs/resource.doc.txt resource.doc]
* [http://wiki.amigaos.net/amiga/autodocs/rexxsyslib.doc.txt rexxsyslib.doc]
* [http://wiki.amigaos.net/amiga/autodocs/root_cl.doc.txt root_cl.doc]
* [http://wiki.amigaos.net/amiga/autodocs/scroller_gc.doc.txt scroller_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/serial_dev.doc.txt serial_dev.doc]
* [http://wiki.amigaos.net/amiga/autodocs/sketchboard_gc.doc.txt sketchboard_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/slider_gc.doc.txt slider_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/sound_dtc.doc.txt sound_dtc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/space_gc.doc.txt space_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/speedbar_gc.doc.txt speedbar_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/string_gc.doc.txt string_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/sys_ic.doc.txt sys_ic.doc]
* [http://wiki.amigaos.net/amiga/autodocs/tapedeck_gc.doc.txt tapedeck_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/textclip.doc.txt textclip.doc]
* [http://wiki.amigaos.net/amiga/autodocs/texteditor_gc.doc.txt texteditor_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/text_dtc.doc.txt text_dtc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/timer.doc.txt timer.doc]
* [http://wiki.amigaos.net/amiga/autodocs/timesync.doc.txt timesync.doc]
* [http://wiki.amigaos.net/amiga/autodocs/timezone.doc.txt timezone.doc]
* [http://wiki.amigaos.net/amiga/autodocs/trackdisk.doc.txt trackdisk.doc]
* [http://wiki.amigaos.net/amiga/autodocs/translator.doc.txt translator.doc]
* [http://wiki.amigaos.net/amiga/autodocs/usbfd.doc.txt usbfd.doc]
* [http://wiki.amigaos.net/amiga/autodocs/usbhcd.doc.txt usbhcd.doc]
* [http://wiki.amigaos.net/amiga/autodocs/usbresource.doc.txt usbresource.doc]
* [http://wiki.amigaos.net/amiga/autodocs/usbsys.doc.txt usbsys.doc]
* [http://wiki.amigaos.net/amiga/autodocs/utility.doc.txt utility.doc]
* [http://wiki.amigaos.net/amiga/autodocs/virtual_gc.doc.txt virtual_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/warp3d.doc.txt warp3d.doc]
* [http://wiki.amigaos.net/amiga/autodocs/window_cl.doc.txt window_cl.doc]
* [http://wiki.amigaos.net/amiga/autodocs/workbench.doc.txt workbench.doc]
* [http://wiki.amigaos.net/amiga/autodocs/xenares.doc.txt xenares.doc]
* [http://wiki.amigaos.net/amiga/autodocs/z.doc.txt z.doc]

Debug Logging on AmigaOS

2021-12-14T21:54:01Z

Jamie Krueger: /* The Debug Logging Template */

[[Category:Debug]]
= Introduction =

The sole purpose of this article is to introduce developers that may be new to AmigaOS to its debug logging function. The Exec library has a function called DebugPrintF() that provides a printf() like API for outputting text to a debug buffer. This buffer can be dumped to disk via the dumpdebugbuffer command, or it can be redirected to a serial port. The debug buffer can survive a warm-reboot so its contents can be recovered after most crashes (so long as the machine does not require a complete reset).

In brief:

* IExec->DebugPrintF() uses the same syntax as printf() and outputs to a debug buffer,
* The debug buffer can either be directed to memory (the default), or to the serial port. See the documentation for kdebug in the sys:documentation/kernel drawer of AmigaOS, and
* The debug buffer in memory can be saved to disk and cleared via: dumpdebugbuffer log.txt clear.

For those who are experienced programmers, the details above are probably all that you require; for everyone else, read on to see how and why debug logging is important, and how it can be used.

= The Importance of Debug Logging =

Developing software is a complex task. The more functions, if/else calls and loops that a program has, the more complicated its operation becomes. Sooner or later it becomes necessary to examine what a program is doing internally. Many compilers (including GCC on AmigaOS) come with debuggers that allow one to step through a program line by line. However, this can be extremely tedious and is also unsuitable for any program that requires real-time operation. For example, it may be impossible to debug a game by stepping through the code because it has to respond to a player's joystick input (which changes which parts of the program are executed). Regardless, it is useful to provide a log of significant events in a program's operation. See the debug logs output for the RadeonHD driver [http://hdrlab.org.nz/radeonhd-first-screen/ here] and [http://hdrlab.org.nz/successful-radeon-hd-2400-pro-mode-setting-test/ here], as examples.

So, what should be logged. Essentially, this is up to you, the programmer. Whatever information you think will be useful in tracking down bugs/issues, should be logged. Often it would be nice to have a hierarchy of debug levels so that it is not necessary to wade through huge debug files when only high-level information (e.g., warnings and errors) are required. I have created a debug module with a template makefile and test code precisely for this purpose.

= The Debug Logging Template =

The debug logging module provides a framework for multi-level debug logging. By providing a debug level, it is possible to specify what level of logging is required. An example executable (DebugLoggingTest) and makefile have been provided that show how to use the module.

== USING THE DEBUG LOGGING MODULE ==

The easiest way to learn how to use the debug module is to simply [[Media:DebugLogging.lha|download the template file]] and look at the provided makefile. After initial download the template is configured to output all debug messages. Type make, and then DebugLoggingTest. Now enter dumpdebugbuffer log.txt clear. Examining log.txt will show all the output messages, each of which can be matched to dprintf() calls in DebugLoggingTest.c.

In the makefile there are three lines containing "CFLAGS." Two of them are commented out (with a # character). The example code can be reconfigured to the other two modes by uncommenting the desired line, and commenting out the other two. Remember to perform a "make clean" before recompiling after making any change to the makefile. The most interesting configuration is the last one. In this configuration the user can enter a debug log level on the command line (e.g., "DebugLoggingTest 10") and thus choose how much debug information is to be output.

To use the debug module in other programs:

* Set the TARGET variable in the makefile to the name of the appliation,
* compile files with the appropriate DEBUG flags set:
** -DTARGET="$(TARGET)", and
** -DDEBUG and (optionally) -DDEBUG_LOGLEVEL, or, -DVARLEVEL_DEBUG.
* Insert dprintf() calls into the program where appropriate (e.g., dprintf(DBG_CRITICAL, "A critical error occurred.\n");), and
* the LOG_FUNCTION or LOG_FUNCENTRY/LOG_FUNCEXIT macros could also be useful.

== DOCUMENTATION ==

The debug module/template expects TARGET to be defined as a string giving the name of the program (e.g., in the makefile use -DTARGET="AppName"). It provides two functions:

* dprintf(debugLevel, fmt, ...) whichoutputs debug messages formatted printf style and adds a header giving the application name and the debug level of the message, and
* dprintf_cont(debugLevel, fmt, ...) also outputs debug messages, but minus the header (so that more complicated messages can be output).

Several debug levels have been predefined:

* DBG_CRITICAL for critical errors,
* DBG_WARNING for warnings,
* DBG_INFO for more detailed information,
* DBG_FUNCTIONCALL which should be used for identifying function calls, and
* DBG_INTERNALINFO for even more detailed information

There are also three modes of operation. If DEBUG is defined alone, it will output all debug messages. If, DEBUG_LOGLEVEL is set to a number, all messages will be output that have a debug level at or below that value. Finally, if VARLEVEL_DEBUG is defined, the user (or external code) can set the debug logging level on demand; in this case, the following two functions are defined:

* void setDebugLevel(int debugLevel) which sets the debug logging level, and
* int getDebugLevel() which returns the currently set logging level.

An example debug log message would be:

DebugLoggingTest (0): An example critical error

There are also three macros defined that are useful for monitoring function entries and exits:

* LOG_FUNCTION logs the name of the function that was called,
* LOG_FUNCENTRY logs the entry to a function, but is useful to put at the top of a function, and
* LOG_FUNCEXIT should be put before any return statement, it logs a funciton exit.

LOG_FUNCENTRY and LOG_FUNCEXIT should be used together.

== DOWNLOAD ==

[[Media:DebugLogging.lha|The debug logging module and template.]]

= Author =

Copyright (c) 2008 Hans de Ruiter. 
Reproduced with permission. 
See the original article [http://hdrlab.org.nz/articles/amiga-os-articles/debug-logging/ here].

DMA Resource

2021-12-10T18:09:24Z

Jamie Krueger:

DMA Resource

2019-12-09T22:18:12Z

Jamie Krueger:

== Author ==

Jamie Krueger, BITbyBIT Software Group LLC 
Copyright (c) 2019 Trevor Dickinson 
Used by permission.

== DMA Engine ==

Some hardware targets include a DMA engine which can be used for general purpose copying. This article describes the DMA engines available and how to use them.

=== Hardware Features ===

The Direct Memory Access (DMA) Engines found in the NXP/Freescale p5020, p5040 and p1022 System On a Chip (SoC)s, as found in the AmigaONE X5000/20, X5000/40 and A1222 respectively, are quite flexible and powerful. Each of these chips contains two distinct engines with four data channels each. This provides the ability to have a total of eight DMA Channels working at once, with up to two DMA transactions actually being executed at the same time (one on each of the two DMA Engines).

Further, each of the four DMA Channels found in a DMA Engine may be individually programmed to handle either; a single transaction, a ''Chain'' of transactions, or even ''Lists'' of ''Chains'' of transactions. The DMA Engines automatically arbitrate control between each DMA Channel following programmed bandwidth settings for each Channel (typically 1024 bytes).

This means that after completing a transfer of 1024 bytes (for example), the hardware will consider switching to the next Channel to allow it to move another block of data, and so on in a round-robin fashion. If all other DMA Channels on a given DMA Engine are idle when arbitration would take place, the hardware will not arbitrate control to another Channel, but simply continue processing the transaction(s) for the Channel it is on.

=== DMA Copy Memory - Execution Flow Diagram ===

[[File:DMACopyMem-Diagram.png]]

=== What a call to perform a DMA copy does internally ===

As shown in the above diagram, when the user makes a call to request a memory copy be performed by the DMA hardware, the next available DMA Channel is selected for use and a DMA Transaction (source, destination and size) is constructed. The DMA Transaction is then programmed into the DMA Engine which owns the available DMA Channel.

At this point the calling task will Wait() until it hears the transaction has been completed. It will then return to the caller with the result. This provides a basic ''blocking'' function, which only returns to the caller once that data has been copied. This single tasking behavior is the simplest to use and what is normally expected by most applications using a memory copy function.

=== Diagram of multitasking DMA Copies ===

[[File:DMACopyMem-Multitasking-Diagram.png]]

=== How multiple simultaneous DMA copies are handled ===

When multiple user calls requesting a DMA copy arrive at once, each one is handed to a dedicated DMA Channel handling task for processing. As the diagram above demonstrates, there are two separate DMA Engines available, each with four channels that may be programmed at the same time. The hardware will then arbitrate the actual data move across these channels according to their respective bandwidth settings (usually 1024 bytes).

In the diagram above, a separate color indicates a distinct data path from the caller through the DMA hardware to the system RAM. A dashed line of the matching color indicates an Interrupt line signaling the respective DMA Channel Handler with the completion of the transaction. The handler task then signals back to the original caller, which returns to the user with a success or failure result.

All eight DMA Channels can handle each a single block transaction or an entire chain of block transactions before it signals completion and returns to the original caller. If all eight DMA Channels are busy processing their requested transactions when further DMA copy requests arrive, they will each be assigned a DMA Channel to wait on (managed via a Mutex lock on each Channel) and will block until allowed to add their DMA transaction to the Channel's queue.

== fsldma.resource ==

The fsldma.resource API is provided automatically in the kernel for all supported machines (Currently the AmigaONE X5000/20, X5000/40 and A1222).

=== The FslDMA API ===

The API provided by the fsldma.resource current consists of:
:* Copy Memory functions

==== Copy Memory Functions ====

Three API calls make up the FslDMA API; CopyMemDMA(), CopyMemDMATagList() and CopyMemDMATags().

<syntaxhighlight>
BOOL CopyMemDMA( CONST_APTR pSourceBuffer, APTR pDestBuffer, uint32 lBufferSize );
BOOL CopyMemDMATags( CONST_APTR pSourceBuffer, APTR pDestBuffer, uint32 lBufferSize, uint32 TagItem1, ... );
BOOL CopyMemDMATagList( CONST_APTR pSourceBuffer, APTR pDestBuffer, uint32 lBufferSize, const struct TagItem *tags );
</syntaxhighlight>

The first call, CopyMemDMA(), attempts to perform a "blocking" (does not return to the user until after the requested transfer has either succeeded or failed) operation. A value of TRUE is returned upon success and FALSE if an error occurred. The CopyMemDMA() call will automatically fall back to using an internal fast CPU copy if the requested size is too small to be efficient, or an error occurred in the DMA transaction.

In theory any ''contiguous'' block of memory from 1 Byte up to 4GB in size may be transferred using any one of these calls. In practice the DMA hardware can directly accept memory blocks up to FSLDMA_MAXBLOCK_SIZE (or 64MB - 1 Byte). Therefore any data blocks greater than FSLDMA_MAXBLOCK_SIZE will automatically be sent to the DMA hardware in a series of smaller chunks. For maximum efficiency transfer sizes should be at least 256 Bytes in size and be an even multiple of 64 Bytes. Odd sizes are handled by the hardware but will degrade performance.

==== Further reference - The fsldma.resource AutoDoc ====

See the [[http://wiki.amigaos.net/amiga/autodocs/fsldmares.doc.txt fsldma.resource AutoDoc]] file for more details on each API call.

=== Example 1: "Blocking" mode ===

<syntaxhighlight>
#include <stdio.h>
#include <stdlib.h>
#include <amiga_compiler.h>
#include <exec/types.h>
#include <proto/exec.h>
#include <dos/dos.h>
#include <interfaces/exec.h>
#include <interfaces/fsldma.h>

// fsldma.resource Example 1, "Blocking" DMA Copy
// test using Virtual memory areas
int main()
{
struct fslDMAIFace *IfslDMA = NULL;
uint32 lSize = 0;
CONST_APTR pSrc = NULL;
APTR pDest = NULL;
BOOL bGotResources = FALSE;

// Obtain the fsldma.resource
IfslDMA = IExec->OpenResource(FSLDMA_NAME);

// Set the size of our test buffers
lSize = FSLDMA_OPTIMAL_BLKSIZE; // About 64 MB

// Allocate a test source buffer (fill with some data)
pSrc = IExec->AllocVecTags(lSize,
AVT_Type, MEMF_SHARED,
AVT_ClearWithValue, 0xB3,
TAG_DONE);

// Allocate a test destination buffer (clear with zeroes)
pDest = IExec->AllocVecTags(lSize,
AVT_Type, MEMF_SHARED,
AVT_ClearWithValue, 0,
TAG_DONE);

// Verify we got all resources needed for the test
if ( (NULL != IfslDMA) && (NULL != pSrc) && (NULL != pDest) )
{
bGotResources = TRUE;
}

if ( TRUE == bGotResources )
{
// Call IfslDMA->CopyMemDMA() to perform the memory copy using the
// DMA hardware. Wait for the transaction to complete before continuing.

printf("Starting \"Blocking\" DMA Transaction"
" of %ld bytes from 0x%08lx to 0x%08lx...\n",lSize,pSrc,pDest);
fflush(stdout);

if ( TRUE == IfslDMA->CopyMemDMA(pSrc,pDest,lSize) )
{
// Success - Do something with the copied data and quit
printf("Returned with Success.\n");
fflush(stdout);
}
else
{
// Report the error
printf("Received an Error!\n");
fflush(stdout);
}
}
else
{
printf("Failed to obtain resources, aborting test.\n");
fflush(stdout);
}

// Free our test buffers (as needed)
if ( NULL != pSrc ) IExec->FreeVec((APTR)pSrc);
if ( NULL != pDest ) IExec->FreeVec(pDest);
}
</syntaxhighlight>

=== Example 2: "Non-Blocking" mode ===

<syntaxhighlight>
#include <stdio.h>
#include <stdlib.h>
#include <amiga_compiler.h>
#include <exec/types.h>
#include <proto/exec.h>
#include <dos/dos.h>
#include <interfaces/exec.h>
#include <interfaces/fsldma.h>

// fsldma.resource Example 2, "Non-blocking" DMA Copy
// test using user notifications and Physical memory areas
int main()
{
struct ExecBase *ExecBase = (*(struct ExecBase **)4);
struct MMUIFace *IMMU = NULL;
struct fslDMAIFace *IfslDMA = NULL;
uint32 lSize = 0;
CONST_APTR pSrc = NULL;
APTR pDest = NULL;
CONST_APTR pPhySrcAttr = NULL;
APTR pPhyDstAttr = NULL;
int8 nSuccessSigNum = -1;
int8 nInProgressSigNum = -1;
int8 nErrorSigNum = -1;
uint32 lSuccessSigMask = 0;
uint32 lInProgressSigMask = 0;
uint32 lErrorSigMask = 0;
uint32 lAllSigsMask = 0;
BOOL bGotResources = FALSE;

// Obtain the MMU Interface
IMMU = (struct MMUIFace *)IExec->GetInterface((struct Library *)ExecBase,
"MMU",1,NULL);
// Obtain the fsldma.resource
IfslDMA = IExec->OpenResource(FSLDMA_NAME);

// Set our test buffer size large enough to generate some sub-block transfers
lSize = FSLDMA_OPTIMAL_BLKSIZE * 4; // About 256 MB

// Allocate a test source buffer (fill with some data)
pSrc = IExec->AllocVecTags(lSize,
AVT_Type, MEMF_SHARED,
AVT_Contiguous, TRUE,
AVT_Lock, TRUE,
AVT_Alignment, 64,
AVT_PhysicalAlignment, 64,
AVT_ClearWithValue, 0xB3,
TAG_DONE);

// Allocate a test destination buffer (clear with zeroes)
pDest = IExec->AllocVecTags(lSize,
AVT_Type, MEMF_SHARED,
AVT_Contiguous, TRUE,
AVT_Lock, TRUE,
AVT_Alignment, 64,
AVT_PhysicalAlignment, 64,
AVT_ClearWithValue, 0,
TAG_DONE);

// Allocate signals to wait on
nSuccessSigNum = IExec->AllocSignal((int8)-1);
nInProgressSigNum = IExec->AllocSignal((int8)-1);
nErrorSigNum = IExec->AllocSignal((int8)-1);

// Construct the signal masks we need to Wait() on later.
// We are assuming these values are being built with
// allocated signals here, but we will verify it before use.
lSuccessSigMask = (uint32)(1L << nSuccessSigNum);
lInProgressSigMask = (uint32)(1L << nInProgressSigNum);
lErrorSigMask = (uint32)(1L << nErrorSigNum);
lAllSigsMask = (lSuccessSigMask | lInProgressSigMask | lErrorSigMask);

// Obtain the pointer to ourselves (this Task)
struct Task *pThisTask = IExec->FindTask(NULL);

// Verify we got all resources needed for the test
if ( (NULL != IMMU) && (NULL != IfslDMA) &&
(NULL != pSrc) && (NULL != pDest) &&
(NULL != pThisTask ) &&
(-1 != nSuccessSigNum) &&
(-1 != nInProgressSigNum) &&
(-1 != nErrorSigNum) )
{
bGotResources = TRUE;
}

if ( TRUE == bGotResources )
{
// In this test we are using Physical memory areas
// for both source and destination, so before we
// hand the transaction to the DMA hardware, we first
// need to set the flush the data cache, set the
// buffers to cache-inhibited and obtain the Physical
// addresses for both buffers

// Enter Supervisor Mode
APTR pUserStack = IExec->SuperState();

// Flush out any cache for our two buffers
IExec->CacheClearE((APTR)pSrc,lSize,CACRF_ClearD);
IExec->CacheClearE(pDest,lSize,CACRF_ClearD);

// Now set the memory attributes to prevent further cache operations
uint32 lSrcMemAttrs = IMMU->GetMemoryAttrs((APTR)pSrc,0);
uint32 lDstMemAttrs = IMMU->GetMemoryAttrs(pDest,0);
IMMU->SetMemoryAttrs((APTR)pSrc,lSize,(lSrcMemAttrs | FSLDMA_PHYMEM_ATTRS));
IMMU->SetMemoryAttrs(pDest,lSize,(lDstMemAttrs | FSLDMA_PHYMEM_ATTRS));

// Get the Physical addresses for our two buffers
pPhySrcAttr = IMMU->GetPhysicalAddress((APTR)pSrc);
pPhyDstAttr = IMMU->GetPhysicalAddress(pDest);

// Return to User Mode
if ( NULL != pUserStack ) IExec->UserState(pUserStack);

// Call IfslDMA->CopyMemDMATags() to perform the memory copy using the
// DMA hardware. Start off the transaction then wait on completion signals.

printf("Starting \"Non-Blocking\" DMA Transaction"
" of %ld bytes from 0x%08lx to 0x%08lx...\n",
lSize,pPhySrcAttr,pPhyDstAttr);
fflush(stdout);

if ( TRUE == IfslDMA->CopyMemDMATags(pPhySrcAttr,pPhyDstAttr,lSize,
FSLDMA_CM_SourceIsPhysical, TRUE,
FSLDMA_CM_DestinationIsPhysical, TRUE,
FSLDMA_CM_DoNotWait, TRUE,
FSLDMA_CM_NotifyTask, pThisTask,
FSLDMA_CM_NotifySignalNumber, nSuccessSigNum,
FSLDMA_CM_NotifyProgessSignalNumber, nInProgressSigNum,
FSLDMA_CM_NotifyErrorSignalNumber, nErrorSigNum,
TAG_DONE) )
{
// If the above call sets up correctly, it returns immeditately
// So do something here *while* the data is being copied...
printf("Doing other stuff before waiting...\n");
fflush(stdout);

// Now we will Wait() for the completion signals from the DMA
BOOL bStillRunning = TRUE;
uint32 lSigReceived = 0;
do
{
// Wait for the DMA completion/status/error signals
printf("Waiting for signals...\n");
fflush(stdout);
lSigReceived = IExec->Wait( lAllSigsMask | SIGBREAKF_CTRL_C );

// Test for the "In Progress" signal
if ( lInProgressSigMask == (lSigReceived & lInProgressSigMask) )
{
// Do something on the "In Process" signal and continue...
printf("Received an \"In Progress\" signal...\n");
fflush(stdout);
}

// Test for the "Success" signal
if ( lSuccessSigMask == (lSigReceived & lSuccessSigMask) )
{
// Success - Do something with the copied data and quit
printf("Received an \"Completed Successfully\" signal.\n");
fflush(stdout);
bStillRunning = FALSE;
}

// Test for the "Error" signal
if ( lErrorSigMask == (lSigReceived & lErrorSigMask) )
{
// Report the error and quit
printf("Received an \"Error\" signal!\n");
fflush(stdout);
bStillRunning = FALSE;
}

// Finally, check if we got a Break signal from the user
// just in case we want to quit out early for some reason
if ( SIGBREAKF_CTRL_C == (lSigReceived & SIGBREAKF_CTRL_C) )
{
printf("Received an \"User break\" signal, ending.\n");
fflush(stdout);
bStillRunning = FALSE;
}
} while( TRUE == bStillRunning );
}
}
else
{
printf("Failed to obtain resources, aborting test.\n");
fflush(stdout);
}

// Free our test buffers (as needed)
if ( NULL != pSrc ) IExec->FreeVec((APTR)pSrc);
if ( NULL != pDest ) IExec->FreeVec(pDest);
// Free any signals we (may have) obtained earlier
if ( -1 != nSuccessSigNum ) IExec->FreeSignal(nSuccessSigNum);
if ( -1 != nInProgressSigNum ) IExec->FreeSignal(nInProgressSigNum);
if ( -1 != nErrorSigNum ) IExec->FreeSignal(nErrorSigNum);
// Release the MMU Interface (as needed)
if ( NULL != IMMU ) IExec->DropInterface((struct Interface *)IMMU);
}
</syntaxhighlight>

==== Obtaining the fsldma.resource ====

Breaking the above example down the first thing we do is include the interface header for the fsldma.resource and obtain the resource itself.

<syntaxhighlight>
#include <interfaces/fsldma.h>
struct fslDMAIFace *IfslDMA = IExec->OpenResource(FSLDMA_NAME);
</syntaxhighlight>

== Performance ==

Testing DMA memory copies vs their CPU based equivalent indicates that the DMA hardware on all three models (X5000/20, X5000/40 and A1222)
move data approximately two to three times faster than the CPU does so alone.

It should also be noted that these tests were performed when the CPU was effectively idle. CPU memory copy operations scale down roughly
equal with the CPU actively scaling up. So the more the CPU is doing, the longer it takes to complete the memory copy.

Conversely, DMA memory copy operation times are far more predictable as they use the same amount of (minimal) CPU overhead for each copy,
and the actual time it takes the DMA hardware to complete the transaction can be calculated to range from all the DMA Channels being idle,
to all DMA Channels being busy at once and data moves arbitrating between channels every 1024 bytes.

=== Optimal use of the DMA Engine ===

To gain the best performance from the DMA Engines, block sizes of 256 bytes or more should be used.
Also, if possible the size should be an even multiple of at least 4 bytes.

Additionally the memory blocks (source and destination) should be aligned to start on a 64 Byte boundary.

The DMA Engine can and does handle misaligned and odd sized data blocks by first shifting the minimum
required bytes to correct the alignment, then taking smaller chunks of data until the largest chunk of
the block can be moved. It can also handle copies of as little as one byte (don't do this).

However, this does degrade performance.

In general, the larger the data block the better.

== Current fsldma.resource API release notes ==

<pre>
fsldma.resource 53.1 (30.9.2019) <jkrueger>

- First release.

fsldma.resource 53.2 (4.11.2019) <jkrueger>

- Replaced the Busy Wait polling of the DMA Channel
completion status with a fully event (interrupt)
driven, multitasking task handler system.

fsldma.resource 53.3 (22.11.2019) <jkrueger>

- Reworked DMACopyMem() to properly handle normal
cache-enabled virtual memory blocks using a
combination of StartDMA()/EndDMA() and "CPU Snoop"
mode on the DMA hardware.

fsldma.resource 53.4 (4.12.2019) <jkrueger>

- Major API rework and streamlining.
Removed all other API calls save DMACopyMem().
DMACopyMem() was renamed CopyMemDMA() and new
TagItem based versions were added; CopyMemDMATagList()
and CopyMemDMATags().

Seven new Tags were added to the API for use
with the Tags version of CopyMemDMA. They enable
using any combination of Virtual and Physical
memory copies and support for new "Non-Blocking"
transactions with user Notification via three
possible signals; "Success", "In Progress" and "Error."

Several internal changes and improvements including
but not limited to, streamlining internal signal
handling between DMA Handler Tasks and user tasks
and optimizing transactions using "Basic Chaining Mode."

The DMA hardware's "Basic Chaining Mode" is now used
internally to transfer larger single block sizes.
Blocks greater than FSLDMA_OPTIMAL_BLKSIZE is size
are transferred using "Basic Chaining Mode", while
blocks less than or equal to FSLDMA_OPTIMAL_BLKSIZE
are transferred using "Basic Direct Mode."

Previously, block sizes larger than FSLDMA_OPTIMAL_BLKSIZE
were all transfered using a CPU driven loop of
"Basic Direct Mode" transactions. This internal CPU
driven loop has now been replaced by programming the
hardware to perform a series of block transactions
in a "Chain" as a single hardware transaction.
This also enabled bringing out "Completed Successfully",
"In Progress" (a sub-block has transferred successfully)
and "Error" signaling during "Non-Blocking" transactions.

Note:
Currently only source and destination memory
areas of the same type, Virtual-to-Virtual or
Physical-to-Physical are supported.

Also, only Physical-to-Physical transactions
support "Non-Blocking" transactions and User
Notification signaling.

Future releases will remove these limitations.
</pre>

DMA Resource

2019-12-09T22:05:30Z

Jamie Krueger: /* Example 2: "Non-Blocking" mode */

DMA Resource

2019-12-09T22:03:44Z

Jamie Krueger: /* Example 2: "Non-Blocking" mode */

== Author ==

Jamie Krueger, BITbyBIT Software Group LLC 
Copyright (c) 2019 Trevor Dickinson 
Used by permission.

== DMA Engine ==

Some hardware targets include a DMA engine which can be used for general purpose copying. This article describes the DMA engines available and how to use them.

=== Hardware Features ===

The Direct Memory Access (DMA) Engines found in the NXP/Freescale p5020, p5040 and p1022 System On a Chip (SoC)s, as found in the AmigaONE X5000/20, X5000/40 and A1222 respectively, are quite flexible and powerful. Each of these chips contains two distinct engines with four data channels each. This provides the ability to have a total of eight DMA Channels working at once, with up to two DMA transactions actually being executed at the same time (one on each of the two DMA Engines).

Further, each of the four DMA Channels found in a DMA Engine may be individually programmed to handle either; a single transaction, a ''Chain'' of transactions, or even ''Lists'' of ''Chains'' of transactions. The DMA Engines automatically arbitrate control between each DMA Channel following programmed bandwidth settings for each Channel (typically 1024 bytes).

This means that after completing a transfer of 1024 bytes (for example), the hardware will consider switching to the next Channel to allow it to move another block of data, and so on in a round-robin fashion. If all other DMA Channels on a given DMA Engine are idle when arbitration would take place, the hardware will not arbitrate control to another Channel, but simply continue processing the transaction(s) for the Channel it is on.

=== DMA Copy Memory - Execution Flow Diagram ===

[[File:DMACopyMem-Diagram.png]]

=== What a call to perform a DMA copy does internally ===

As shown in the above diagram, when the user makes a call to request a memory copy be performed by the DMA hardware, the next available DMA Channel is selected for use and a DMA Transaction (source, destination and size) is constructed. The DMA Transaction is then programmed into the DMA Engine which owns the available DMA Channel.

At this point the calling task will Wait() until it hears the transaction has been completed. It will then return to the caller with the result. This provides a basic ''blocking'' function, which only returns to the caller once that data has been copied. This single tasking behavior is the simplest to use and what is normally expected by most applications using a memory copy function.

=== Diagram of multitasking DMA Copies ===

[[File:DMACopyMem-Multitasking-Diagram.png]]

=== How multiple simultaneous DMA copies are handled ===

When multiple user calls requesting a DMA copy arrive at once, each one is handed to a dedicated DMA Channel handling task for processing. As the diagram above demonstrates, there are two separate DMA Engines available, each with four channels that may be programmed at the same time. The hardware will then arbitrate the actual data move across these channels according to their respective bandwidth settings (usually 1024 bytes).

In the diagram above, a separate color indicates a distinct data path from the caller through the DMA hardware to the system RAM. A dashed line of the matching color indicates an Interrupt line signaling the respective DMA Channel Handler with the completion of the transaction. The handler task then signals back to the original caller, which returns to the user with a success or failure result.

All eight DMA Channels can handle each a single block transaction or an entire chain of block transactions before it signals completion and returns to the original caller. If all eight DMA Channels are busy processing their requested transactions when further DMA copy requests arrive, they will each be assigned a DMA Channel to wait on (managed via a Mutex lock on each Channel) and will block until allowed to add their DMA transaction to the Channel's queue.

== fsldma.resource ==

The fsldma.resource API is provided automatically in the kernel for all supported machines (Currently the AmigaONE X5000/20, X5000/40 and A1222).

=== The FslDMA API ===

The API provided by the fsldma.resource current consists of:
:* Copy Memory functions

==== Copy Memory Functions ====

Three API calls make up the FslDMA API; CopyMemDMA(), CopyMemDMATagList() and CopyMemDMATags().

<syntaxhighlight>
BOOL CopyMemDMA( CONST_APTR pSourceBuffer, APTR pDestBuffer, uint32 lBufferSize );
BOOL CopyMemDMATags( CONST_APTR pSourceBuffer, APTR pDestBuffer, uint32 lBufferSize, uint32 TagItem1, ... );
BOOL CopyMemDMATagList( CONST_APTR pSourceBuffer, APTR pDestBuffer, uint32 lBufferSize, const struct TagItem *tags );
</syntaxhighlight>

The first call, CopyMemDMA(), attempts to perform a "blocking" (does not return to the user until after the requested transfer has either succeeded or failed) operation. A value of TRUE is returned upon success and FALSE if an error occurred. The CopyMemDMA() call will automatically fall back to using an internal fast CPU copy if the requested size is too small to be efficient, or an error occurred in the DMA transaction.

In theory any ''contiguous'' block of memory from 1 Byte up to 4GB in size may be transferred using any one of these calls. In practice the DMA hardware can directly accept memory blocks up to FSLDMA_MAXBLOCK_SIZE (or 64MB - 1 Byte). Therefore any data blocks greater than FSLDMA_MAXBLOCK_SIZE will automatically be sent to the DMA hardware in a series of smaller chunks. For maximum efficiency transfer sizes should be at least 256 Bytes in size and be an even multiple of 64 Bytes. Odd sizes are handled by the hardware but will degrade performance.

==== Further reference - The fsldma.resource AutoDoc ====

See the [[http://wiki.amigaos.net/amiga/autodocs/fsldmares.doc.txt fsldma.resource AutoDoc]] file for more details on each API call.

=== Example 1: "Blocking" mode ===

<syntaxhighlight>
#include <stdio.h>
#include <stdlib.h>
#include <amiga_compiler.h>
#include <exec/types.h>
#include <proto/exec.h>
#include <dos/dos.h>
#include <interfaces/exec.h>
#include <interfaces/fsldma.h>

// fsldma.resource Example 1, "Blocking" DMA Copy
// test using Virtual memory areas
int main()
{
struct fslDMAIFace *IfslDMA = NULL;
uint32 lSize = 0;
CONST_APTR pSrc = NULL;
APTR pDest = NULL;
BOOL bGotResources = FALSE;

// Obtain the fsldma.resource
IfslDMA = IExec->OpenResource(FSLDMA_NAME);

// Set the size of our test buffers
lSize = FSLDMA_OPTIMAL_BLKSIZE; // About 64 MB

// Allocate a test source buffer (fill with some data)
pSrc = IExec->AllocVecTags(lSize,
AVT_Type, MEMF_SHARED,
AVT_ClearWithValue, 0xB3,
TAG_DONE);

// Allocate a test destination buffer (clear with zeroes)
pDest = IExec->AllocVecTags(lSize,
AVT_Type, MEMF_SHARED,
AVT_ClearWithValue, 0,
TAG_DONE);

// Verify we got all resources needed for the test
if ( (NULL != IfslDMA) && (NULL != pSrc) && (NULL != pDest) )
{
bGotResources = TRUE;
}

if ( TRUE == bGotResources )
{
// Call IfslDMA->CopyMemDMA() to perform the memory copy using the
// DMA hardware. Wait for the transaction to complete before continuing.

printf("Starting \"Blocking\" DMA Transaction"
" of %ld bytes from 0x%08lx to 0x%08lx...\n",lSize,pSrc,pDest);
fflush(stdout);

if ( TRUE == IfslDMA->CopyMemDMA(pSrc,pDest,lSize) )
{
// Success - Do something with the copied data and quit
printf("Returned with Success.\n");
fflush(stdout);
}
else
{
// Report the error
printf("Received an Error!\n");
fflush(stdout);
}
}
else
{
printf("Failed to obtain resources, aborting test.\n");
fflush(stdout);
}

// Free our test buffers (as needed)
if ( NULL != pSrc ) IExec->FreeVec((APTR)pSrc);
if ( NULL != pDest ) IExec->FreeVec(pDest);
}
</syntaxhighlight>

=== Example 2: "Non-Blocking" mode ===

<syntaxhighlight>
#include <stdio.h>
#include <stdlib.h>
#include <amiga_compiler.h>
#include <exec/types.h>
#include <proto/exec.h>
#include <dos/dos.h>
#include <interfaces/exec.h>
#include <interfaces/fsldma.h>

// fsldma.resource Example 2, "Non-blocking" DMA Copy
// test using user notifications and Physical memory areas
int main()
{
struct ExecBase *ExecBase = (*(struct ExecBase **)4);
struct MMUIFace *IMMU = NULL;
struct fslDMAIFace *IfslDMA = NULL;
uint32 lSize = 0;
CONST_APTR pSrc = NULL;
APTR pDest = NULL;
CONST_APTR pPhySrcAttr = NULL;
APTR pPhyDstAttr = NULL;
int8 nSuccessSigNum = -1;
int8 nInProgressSigNum = -1;
int8 nErrorSigNum = -1;
uint32 lSuccessSigMask = 0;
uint32 lInProgressSigMask = 0;
uint32 lErrorSigMask = 0;
uint32 lAllSigsMask = 0;
BOOL bGotResources = FALSE;

// Obtain the MMU Interface
IMMU = (struct MMUIFace *)IExec->GetInterface((struct Library *)ExecBase,
"MMU",1,NULL);
// Obtain the fsldma.resource
IfslDMA = IExec->OpenResource(FSLDMA_NAME);

// Set our test buffer size large enough to generate some sub-block transfers
lSize = FSLDMA_OPTIMAL_BLKSIZE * 4; // About 256 MB

// Allocate a test source buffer (fill with some data)
pSrc = IExec->AllocVecTags(lSize,
AVT_Type, MEMF_SHARED,
AVT_Contiguous, TRUE,
AVT_Lock, TRUE,
AVT_Alignment, 64,
AVT_PhysicalAlignment, 64,
AVT_ClearWithValue, 0xB3,
TAG_DONE);

// Allocate a test destination buffer (clear with zeroes)
pDest = IExec->AllocVecTags(lSize,
AVT_Type, MEMF_SHARED,
AVT_Contiguous, TRUE,
AVT_Lock, TRUE,
AVT_Alignment, 64,
AVT_PhysicalAlignment, 64,
AVT_ClearWithValue, 0,
TAG_DONE);

// Allocate signals to wait on
nSuccessSigNum = IExec->AllocSignal((int8)-1);
nInProgressSigNum = IExec->AllocSignal((int8)-1);
nErrorSigNum = IExec->AllocSignal((int8)-1);

// Construct the signal masks we need to Wait() on later.
// We are assuming these values are being built with
// allocated signals here, but we will verify it before use.
lSuccessSigMask = (uint32)(1L << nSuccessSigNum);
lInProgressSigMask = (uint32)(1L << nInProgressSigNum);
lErrorSigMask = (uint32)(1L << nErrorSigNum);
lAllSigsMask = (lSuccessSigMask | lInProgressSigMask | lErrorSigMask);

// Obtain the pointer to ourselves (this Task)
struct Task *pThisTask = IExec->FindTask(NULL);

// Verify we got all resources needed for the test
if ( (NULL != IMMU) && (NULL != IfslDMA) &&
(NULL != pSrc) && (NULL != pDest) &&
(NULL != pThisTask ) &&
(-1 != nSuccessSigNum) &&
(-1 != nInProgressSigNum) &&
(-1 != nErrorSigNum) )
{
bGotResources = TRUE;
}

if ( TRUE == bGotResources )
{
// In this test we are using Physical memory areas
// for both source and destination, so before we
// hand the transaction to the DMA hardware, we first
// need to set the flush the data cache, set the
// buffers to cache-inhibited and obtain the Physical
// addresses for both buffers

// Enter Supervisor Mode
APTR pUserStack = IExec->SuperState();

// Flush out any cache for our two buffers
IExec->CacheClearE((APTR)pSrc,lSize,CACRF_ClearD);
IExec->CacheClearE(pDest,lSize,CACRF_ClearD);

// Now set the memory attributes to prevent further cache operations
uint32 lSrcMemAttrs = IMMU->GetMemoryAttrs((APTR)pSrc,0);
uint32 lDstMemAttrs = IMMU->GetMemoryAttrs(pDest,0);
IMMU->SetMemoryAttrs((APTR)pSrc,lSize,(lSrcMemAttrs | FSLDMA_PHYMEM_ATTRS));
IMMU->SetMemoryAttrs(pDest,lSize,(lDstMemAttrs | FSLDMA_PHYMEM_ATTRS));

// Get the Physical addresses for our two buffers
pPhySrcAttr = IMMU->GetPhysicalAddress((APTR)pSrc);
pPhyDstAttr = IMMU->GetPhysicalAddress(pDest);

// Return to User Mode
if ( NULL != pUserStack ) IExec->UserState(pUserStack);

// Call IfslDMA->CopyMemDMATags() to perform the memory copy using the
// DMA hardware. Start off the transaction then wait on completion signals.

printf("Starting \"Non-Blocking\" DMA Transaction"
" of %ld bytes from 0x%08lx to 0x%08lx...\n",
lSize,pPhySrcAttr,pPhyDstAttr);
fflush(stdout);

if ( TRUE == IfslDMA->CopyMemDMATags(pPhySrcAttr,pPhyDstAttr,lSize,
FSLDMA_CM_SourceIsPhysical, TRUE,
FSLDMA_CM_DestinationIsPhysical, TRUE,
FSLDMA_CM_DoNotWait, TRUE,
FSLDMA_CM_NotifyTask, pThisTask,
FSLDMA_CM_NotifySignalNumber, nSuccessSigNum,
FSLDMA_CM_NotifyProgessSignalNumber, nInProgressSigNum,
FSLDMA_CM_NotifyErrorSignalNumber, nErrorSigNum,
TAG_DONE) )
{
// If the above call sets up correctly, it returns immeditately
// So do something here *while* the data is being copied...
printf("Doing other stuff before waiting...\n");
fflush(stdout);

// Now we will Wait() for the completion signals from the DMA
BOOL bStillRunning = TRUE;
uint32 lSigReceived = 0;
do
{
// Wait for the DMA completion/status/error signals
printf("Waiting for signals...\n");
fflush(stdout);
lSigReceived = IExec->Wait( lAllSigsMask | SIGBREAKF_CTRL_C );

// Test for the "In Progress" signal
if ( lInProgressSigMask == (lSigReceived & lInProgressSigMask) )
{
// Do something on the "In Process" signal and continue...
printf("Received an \"In Progress\" signal...\n");
fflush(stdout);
}

// Test for the "Success" signal
if ( lSuccessSigMask == (lSigReceived & lSuccessSigMask) )
{
// Success - Do something with the copied data and quit
printf("Received an \"Completed Successfully\" signal.\n");
fflush(stdout);
bStillRunning = FALSE;
}

// Test for the "Error" signal
if ( lErrorSigMask == (lSigReceived & lErrorSigMask) )
{
// Report the error and quit
printf("Received an \"Error\" signal!\n");
fflush(stdout);
bStillRunning = FALSE;
}

// Finally, check if we got a Break signal from the user
// just in case we want to quit out early for some reason
if ( SIGBREAKF_CTRL_C == (lSigReceived & SIGBREAKF_CTRL_C) )
{
printf("Received an \"User break\" signal, ending.\n");
fflush(stdout);
bStillRunning = FALSE;
}
} while( TRUE == bStillRunning );
}
}
else
{
printf("Failed to obtain resources, aborting test.\n");
fflush(stdout);
}

// Free our test buffers (as needed)
if ( NULL != pSrc ) IExec->FreeVec((APTR)pSrc);
if ( NULL != pDest ) IExec->FreeVec(pDest);
// Free any signals we (may have) obtained earlier
if ( -1 != nSuccessSigNum ) IExec->FreeSignal(nSuccessSigNum);
if ( -1 != nInProgressSigNum ) IExec->FreeSignal(nInProgressSigNum);
if ( -1 != nErrorSigNum ) IExec->FreeSignal(nErrorSigNum);
// Release the MMU Interface (as needed)
if ( NULL != IMMU ) IExec->DropInterface((struct Interface *)IMMU);
}
</syntaxhighlight>

==== Obtaining the fsldma.resource ====

Breaking the above example down the first thing we do is include the interface header for the fsldma.resource and obtain the resource itself.

<syntaxhighlight>
#include <interfaces/fsldma.h>
struct fslDMAIFace *IfslDMA = IExec->OpenResource(FSLDMA_NAME);
</syntaxhighlight>

==== Allocating DMA Compliant Memory ====

Once we have successfully obtained the DMA resource we can directly use its API. The next step we need to do is to allocate some memory '''which we know is DMA compliant''' for use by the resource. This can be accomplished by using the IExec->AllocVecTags() function together with a couple of MMU functions. Together they allow you to ensuring the memory that is returned is properly aligned, contiguous, cache-inhibited and coherent.

We use the Tags version of the allocate memory function first so we can allocate a block of memory for our source buffer and fill it with some test value (in this case the byte value 0xB3).

<syntaxhighlight>
</syntaxhighlight>

We also need a destination buffer for our test. Since it only needs to start out being cleared (filled with zeroes), we can use the simplest form of the allocate memory function here as the allocated memory is cleared by default.

<syntaxhighlight>
</syntaxhighlight>

== Performance ==

Testing DMA memory copies vs their CPU based equivalent indicates that the DMA hardware on all three models (X5000/20, X5000/40 and A1222)
move data approximately two to three times faster than the CPU does so alone.

It should also be noted that these tests were performed when the CPU was effectively idle. CPU memory copy operations scale down roughly
equal with the CPU actively scaling up. So the more the CPU is doing, the longer it takes to complete the memory copy.

Conversely, DMA memory copy operation times are far more predictable as they use the same amount of (minimal) CPU overhead for each copy,
and the actual time it takes the DMA hardware to complete the transaction can be calculated to range from all the DMA Channels being idle,
to all DMA Channels being busy at once and data moves arbitrating between channels every 1024 bytes.

=== Optimal use of the DMA Engine ===

To gain the best performance from the DMA Engines, block sizes of 256 bytes or more should be used.
Also, if possible the size should be an even multiple of at least 4 bytes.

Additionally the memory blocks (source and destination) should be aligned to start on a 64 Byte boundary.

The DMA Engine can and does handle misaligned and odd sized data blocks by first shifting the minimum
required bytes to correct the alignment, then taking smaller chunks of data until the largest chunk of
the block can be moved. It can also handle copies of as little as one byte (don't do this).

However, this does degrade performance.

In general, the larger the data block the better.

DMA Resource

2019-12-09T22:00:18Z

Jamie Krueger: /* Example 1: "Blocking" mode */

== Author ==

Jamie Krueger, BITbyBIT Software Group LLC 
Copyright (c) 2019 Trevor Dickinson 
Used by permission.

== DMA Engine ==

Some hardware targets include a DMA engine which can be used for general purpose copying. This article describes the DMA engines available and how to use them.

=== Hardware Features ===

The Direct Memory Access (DMA) Engines found in the NXP/Freescale p5020, p5040 and p1022 System On a Chip (SoC)s, as found in the AmigaONE X5000/20, X5000/40 and A1222 respectively, are quite flexible and powerful. Each of these chips contains two distinct engines with four data channels each. This provides the ability to have a total of eight DMA Channels working at once, with up to two DMA transactions actually being executed at the same time (one on each of the two DMA Engines).

Further, each of the four DMA Channels found in a DMA Engine may be individually programmed to handle either; a single transaction, a ''Chain'' of transactions, or even ''Lists'' of ''Chains'' of transactions. The DMA Engines automatically arbitrate control between each DMA Channel following programmed bandwidth settings for each Channel (typically 1024 bytes).

This means that after completing a transfer of 1024 bytes (for example), the hardware will consider switching to the next Channel to allow it to move another block of data, and so on in a round-robin fashion. If all other DMA Channels on a given DMA Engine are idle when arbitration would take place, the hardware will not arbitrate control to another Channel, but simply continue processing the transaction(s) for the Channel it is on.

=== DMA Copy Memory - Execution Flow Diagram ===

[[File:DMACopyMem-Diagram.png]]

=== What a call to perform a DMA copy does internally ===

As shown in the above diagram, when the user makes a call to request a memory copy be performed by the DMA hardware, the next available DMA Channel is selected for use and a DMA Transaction (source, destination and size) is constructed. The DMA Transaction is then programmed into the DMA Engine which owns the available DMA Channel.

At this point the calling task will Wait() until it hears the transaction has been completed. It will then return to the caller with the result. This provides a basic ''blocking'' function, which only returns to the caller once that data has been copied. This single tasking behavior is the simplest to use and what is normally expected by most applications using a memory copy function.

=== Diagram of multitasking DMA Copies ===

[[File:DMACopyMem-Multitasking-Diagram.png]]

=== How multiple simultaneous DMA copies are handled ===

When multiple user calls requesting a DMA copy arrive at once, each one is handed to a dedicated DMA Channel handling task for processing. As the diagram above demonstrates, there are two separate DMA Engines available, each with four channels that may be programmed at the same time. The hardware will then arbitrate the actual data move across these channels according to their respective bandwidth settings (usually 1024 bytes).

In the diagram above, a separate color indicates a distinct data path from the caller through the DMA hardware to the system RAM. A dashed line of the matching color indicates an Interrupt line signaling the respective DMA Channel Handler with the completion of the transaction. The handler task then signals back to the original caller, which returns to the user with a success or failure result.

All eight DMA Channels can handle each a single block transaction or an entire chain of block transactions before it signals completion and returns to the original caller. If all eight DMA Channels are busy processing their requested transactions when further DMA copy requests arrive, they will each be assigned a DMA Channel to wait on (managed via a Mutex lock on each Channel) and will block until allowed to add their DMA transaction to the Channel's queue.

== fsldma.resource ==

The fsldma.resource API is provided automatically in the kernel for all supported machines (Currently the AmigaONE X5000/20, X5000/40 and A1222).

=== The FslDMA API ===

The API provided by the fsldma.resource current consists of:
:* Copy Memory functions

==== Copy Memory Functions ====

Three API calls make up the FslDMA API; CopyMemDMA(), CopyMemDMATagList() and CopyMemDMATags().

<syntaxhighlight>
BOOL CopyMemDMA( CONST_APTR pSourceBuffer, APTR pDestBuffer, uint32 lBufferSize );
BOOL CopyMemDMATags( CONST_APTR pSourceBuffer, APTR pDestBuffer, uint32 lBufferSize, uint32 TagItem1, ... );
BOOL CopyMemDMATagList( CONST_APTR pSourceBuffer, APTR pDestBuffer, uint32 lBufferSize, const struct TagItem *tags );
</syntaxhighlight>

The first call, CopyMemDMA(), attempts to perform a "blocking" (does not return to the user until after the requested transfer has either succeeded or failed) operation. A value of TRUE is returned upon success and FALSE if an error occurred. The CopyMemDMA() call will automatically fall back to using an internal fast CPU copy if the requested size is too small to be efficient, or an error occurred in the DMA transaction.

In theory any ''contiguous'' block of memory from 1 Byte up to 4GB in size may be transferred using any one of these calls. In practice the DMA hardware can directly accept memory blocks up to FSLDMA_MAXBLOCK_SIZE (or 64MB - 1 Byte). Therefore any data blocks greater than FSLDMA_MAXBLOCK_SIZE will automatically be sent to the DMA hardware in a series of smaller chunks. For maximum efficiency transfer sizes should be at least 256 Bytes in size and be an even multiple of 64 Bytes. Odd sizes are handled by the hardware but will degrade performance.

==== Further reference - The fsldma.resource AutoDoc ====

See the [[http://wiki.amigaos.net/amiga/autodocs/fsldmares.doc.txt fsldma.resource AutoDoc]] file for more details on each API call.

=== Example 1: "Blocking" mode ===

<syntaxhighlight>
#include <stdio.h>
#include <stdlib.h>
#include <amiga_compiler.h>
#include <exec/types.h>
#include <proto/exec.h>
#include <dos/dos.h>
#include <interfaces/exec.h>
#include <interfaces/fsldma.h>

// fsldma.resource Example 1, "Blocking" DMA Copy
// test using Virtual memory areas
int main()
{
struct fslDMAIFace *IfslDMA = NULL;
uint32 lSize = 0;
CONST_APTR pSrc = NULL;
APTR pDest = NULL;
BOOL bGotResources = FALSE;

// Obtain the fsldma.resource
IfslDMA = IExec->OpenResource(FSLDMA_NAME);

// Set the size of our test buffers
lSize = FSLDMA_OPTIMAL_BLKSIZE; // About 64 MB

// Allocate a test source buffer (fill with some data)
pSrc = IExec->AllocVecTags(lSize,
AVT_Type, MEMF_SHARED,
AVT_ClearWithValue, 0xB3,
TAG_DONE);

// Allocate a test destination buffer (clear with zeroes)
pDest = IExec->AllocVecTags(lSize,
AVT_Type, MEMF_SHARED,
AVT_ClearWithValue, 0,
TAG_DONE);

// Verify we got all resources needed for the test
if ( (NULL != IfslDMA) && (NULL != pSrc) && (NULL != pDest) )
{
bGotResources = TRUE;
}

if ( TRUE == bGotResources )
{
// Call IfslDMA->CopyMemDMA() to perform the memory copy using the
// DMA hardware. Wait for the transaction to complete before continuing.

printf("Starting \"Blocking\" DMA Transaction"
" of %ld bytes from 0x%08lx to 0x%08lx...\n",lSize,pSrc,pDest);
fflush(stdout);

if ( TRUE == IfslDMA->CopyMemDMA(pSrc,pDest,lSize) )
{
// Success - Do something with the copied data and quit
printf("Returned with Success.\n");
fflush(stdout);
}
else
{
// Report the error
printf("Received an Error!\n");
fflush(stdout);
}
}
else
{
printf("Failed to obtain resources, aborting test.\n");
fflush(stdout);
}

// Free our test buffers (as needed)
if ( NULL != pSrc ) IExec->FreeVec((APTR)pSrc);
if ( NULL != pDest ) IExec->FreeVec(pDest);
}
</syntaxhighlight>

=== Example 2: "Non-Blocking" mode ===

<syntaxhighlight>
#include <stdio.h>
#include <stdlib.h>
#include <amiga_compiler.h>
#include <exec/types.h>
#include <proto/exec.h>
#include <dos/dos.h>
#include <interfaces/exec.h>
#include <interfaces/fsldma.h>

// fsldma.resource Example 2, "Non-blocking" DMA Copy
// test using user notifications and Physical memory areas
int main()
{
struct ExecBase *ExecBase = (*(struct ExecBase **)4);
struct MMUIFace *IMMU = NULL;
struct fslDMAIFace *IfslDMA = NULL;
uint32 lSize = 0;
CONST_APTR pSrc = NULL;
APTR pDest = NULL;
CONST_APTR pPhySrcAttr = NULL;
APTR pPhyDstAttr = NULL;
int8 nSuccessSigNum = -1;
int8 nInProgressSigNum = -1;
int8 nErrorSigNum = -1;
uint32 lSuccessSigMask = 0;
uint32 lInProgressSigMask = 0;
uint32 lErrorSigMask = 0;
uint32 lAllSigsMask = 0;
BOOL bGotResources = FALSE;

// Obtain the MMU Interface
IMMU = (struct MMUIFace *)IExec->GetInterface((struct Library *)ExecBase,
"MMU",1,NULL);
// Obtain the fsldma.resource
IfslDMA = IExec->OpenResource(FSLDMA_NAME);

// Set our test buffer size large enough to generate some sub-block transfers
lSize = FSLDMA_OPTIMAL_BLKSIZE * 4; // About 256 MB

// Allocate a test source buffer (fill with some data)
pSrc = IExec->AllocVecTags(lSize,
AVT_Type, MEMF_SHARED,
AVT_Contiguous, TRUE,
AVT_Lock, TRUE,
AVT_Alignment, 64,
AVT_PhysicalAlignment, 64,
AVT_ClearWithValue, 0xB3,
TAG_DONE);

// Allocate a test destination buffer (clear with zeroes)
pDest = IExec->AllocVecTags(lSize,
AVT_Type, MEMF_SHARED,
AVT_Contiguous, TRUE,
AVT_Lock, TRUE,
AVT_Alignment, 64,
AVT_PhysicalAlignment, 64,
AVT_ClearWithValue, 0,
TAG_DONE);

// Allocate signals to wait on
nSuccessSigNum = IExec->AllocSignal((int8)-1);
nInProgressSigNum = IExec->AllocSignal((int8)-1);
nErrorSigNum = IExec->AllocSignal((int8)-1);

// Construct the signal masks we need to Wait() on later.
// We are assuming these values are being built with
// allocated signals here, but we will verify it before use.
lSuccessSigMask = (uint32)(1L << nSuccessSigNum);
lInProgressSigMask = (uint32)(1L << nInProgressSigNum);
lErrorSigMask = (uint32)(1L << nErrorSigNum);
lAllSigsMask = (lSuccessSigMask | lInProgressSigMask | lErrorSigMask);

// Obtain the pointer to ourselves (this Task)
struct Task *pThisTask = IExec->FindTask(NULL);

// Verify we got all resources needed for the test
if ( (NULL != IMMU) && (NULL != IfslDMA) &&
(NULL != pSrc) && (NULL != pDest) &&
(NULL != pThisTask ) &&
(-1 != nSuccessSigNum) &&
(-1 != nInProgressSigNum) &&
(-1 != nErrorSigNum) )
{
bGotResources = TRUE;
}

if ( TRUE == bGotResources )
{
// In this test we are using Physical memory areas
// for both source and destination, so before we
// hand the transaction to the DMA hardware, we first
// need to set the flush the data cache, set the
// buffers to cache-inhibited and obtain the Physical
// addresses for both buffers

// Enter Supervisor Mode
APTR pUserStack = IExec->SuperState();

// Flush out any cache for our two buffers
IExec->CacheClearE((APTR)pSrc,lSize,CACRF_ClearD);
IExec->CacheClearE(pDest,lSize,CACRF_ClearD);

// Now set the memory attributes to prevent further cache operations
uint32 lSrcMemAttrs = IMMU->GetMemoryAttrs((APTR)pSrc,0);
uint32 lDstMemAttrs = IMMU->GetMemoryAttrs(pDest,0);
IMMU->SetMemoryAttrs((APTR)pSrc,lSize,(lSrcMemAttrs | FSLDMA_PHYMEM_ATTRS));
IMMU->SetMemoryAttrs(pDest,lSize,(lDstMemAttrs | FSLDMA_PHYMEM_ATTRS));

// Get the Physical addresses for our two buffers
pPhySrcAttr = IMMU->GetPhysicalAddress((APTR)pSrc);
pPhyDstAttr = IMMU->GetPhysicalAddress(pDest);

// Return to User Mode
if ( NULL != pUserStack ) IExec->UserState(pUserStack);

// Call IfslDMA->CopyMemDMATags() to perform the memory copy using the
// DMA hardware. Start off the transaction then wait on completion signals.

// We use full 64-Bit values to pass in the source and destination to
// IfslDMA->CopyMemDMATags() so we need to use a "double cast" on the
// 32-Bit pointers returned by AllocVecTags() in order to properly pass
// in fully extended 64-Bit pointers.
// (see <resource/fsldma.h> for more details)

printf("Starting \"Non-Blocking\" DMA Transaction"
" of %ld bytes from 0x%08lx to 0x%08lx...\n",lSize,pPhySrcAttr,pPhyDstAttr);
fflush(stdout);
if ( TRUE == IfslDMA->CopyMemDMATags((CONST_DMAPTR)(uint32)pPhySrcAttr,
(DMAPTR)(uint32)pPhyDstAttr,
lSize,
FSLDMA_CM_SourceIsPhysical, TRUE,
FSLDMA_CM_DestinationIsPhysical, TRUE,
FSLDMA_CM_DoNotWait, TRUE,
FSLDMA_CM_NotifyTask, pThisTask,
FSLDMA_CM_NotifySignalNumber, nSuccessSigNum,
FSLDMA_CM_NotifyProgessSignalNumber, nInProgressSigNum,
FSLDMA_CM_NotifyErrorSignalNumber, nErrorSigNum,
TAG_DONE) )
{
// If the above call sets up correctly, it returns immeditately
// So do something here *while* the data is being copied...
printf("Doing other stuff before waiting...\n");
fflush(stdout);

// Now we will Wait() for the completion signals from the DMA
BOOL bStillRunning = TRUE;
uint32 lSigReceived = 0;
do
{
// Wait for the DMA completion/status/error signals
printf("Waiting for signals...\n");
fflush(stdout);
lSigReceived = IExec->Wait( lAllSigsMask | SIGBREAKF_CTRL_C );

// Test for the "In Progress" signal
if ( lInProgressSigMask == (lSigReceived & lInProgressSigMask) )
{
// Do something on the "In Process" signal and continue...
printf("Received an \"In Progress\" signal...\n");
fflush(stdout);
}

// Test for the "Success" signal
if ( lSuccessSigMask == (lSigReceived & lSuccessSigMask) )
{
// Success - Do something with the copied data and quit
printf("Received an \"Completed Successfully\" signal.\n");
fflush(stdout);
bStillRunning = FALSE;
}

// Test for the "Error" signal
if ( lErrorSigMask == (lSigReceived & lErrorSigMask) )
{
// Report the error and quit
printf("Received an \"Error\" signal!\n");
fflush(stdout);
bStillRunning = FALSE;
}

// Finally, check if we got a Break signal from the user
// just in case we want to quit out early for some reason
if ( SIGBREAKF_CTRL_C == (lSigReceived & SIGBREAKF_CTRL_C) )
{
printf("Received an \"User break\" signal, ending.\n");
fflush(stdout);
bStillRunning = FALSE;
}
} while( TRUE == bStillRunning );
}
}
else
{
printf("Failed to obtain resources, aborting test.\n");
fflush(stdout);
}

// Free our test buffers (as needed)
if ( NULL != pSrc ) IExec->FreeVec((APTR)pSrc);
if ( NULL != pDest ) IExec->FreeVec(pDest);
// Free any signals we (may have) obtained earlier
if ( -1 != nSuccessSigNum ) IExec->FreeSignal(nSuccessSigNum);
if ( -1 != nInProgressSigNum ) IExec->FreeSignal(nInProgressSigNum);
if ( -1 != nErrorSigNum ) IExec->FreeSignal(nErrorSigNum);
// Release the MMU Interface (as needed)
if ( NULL != IMMU ) IExec->DropInterface((struct Interface *)IMMU);
}
</syntaxhighlight>

==== Obtaining the fsldma.resource ====

Breaking the above example down the first thing we do is include the interface header for the fsldma.resource and obtain the resource itself.

<syntaxhighlight>
#include <interfaces/fsldma.h>
struct fslDMAIFace *IfslDMA = IExec->OpenResource(FSLDMA_NAME);
</syntaxhighlight>

==== Allocating DMA Compliant Memory ====

Once we have successfully obtained the DMA resource we can directly use its API. The next step we need to do is to allocate some memory '''which we know is DMA compliant''' for use by the resource. This can be accomplished by using the IExec->AllocVecTags() function together with a couple of MMU functions. Together they allow you to ensuring the memory that is returned is properly aligned, contiguous, cache-inhibited and coherent.

We use the Tags version of the allocate memory function first so we can allocate a block of memory for our source buffer and fill it with some test value (in this case the byte value 0xB3).

<syntaxhighlight>
</syntaxhighlight>

We also need a destination buffer for our test. Since it only needs to start out being cleared (filled with zeroes), we can use the simplest form of the allocate memory function here as the allocated memory is cleared by default.

<syntaxhighlight>
</syntaxhighlight>

== Performance ==

Testing DMA memory copies vs their CPU based equivalent indicates that the DMA hardware on all three models (X5000/20, X5000/40 and A1222)
move data approximately two to three times faster than the CPU does so alone.

It should also be noted that these tests were performed when the CPU was effectively idle. CPU memory copy operations scale down roughly
equal with the CPU actively scaling up. So the more the CPU is doing, the longer it takes to complete the memory copy.

Conversely, DMA memory copy operation times are far more predictable as they use the same amount of (minimal) CPU overhead for each copy,
and the actual time it takes the DMA hardware to complete the transaction can be calculated to range from all the DMA Channels being idle,
to all DMA Channels being busy at once and data moves arbitrating between channels every 1024 bytes.

=== Optimal use of the DMA Engine ===

To gain the best performance from the DMA Engines, block sizes of 256 bytes or more should be used.
Also, if possible the size should be an even multiple of at least 4 bytes.

Additionally the memory blocks (source and destination) should be aligned to start on a 64 Byte boundary.

The DMA Engine can and does handle misaligned and odd sized data blocks by first shifting the minimum
required bytes to correct the alignment, then taking smaller chunks of data until the largest chunk of
the block can be moved. It can also handle copies of as little as one byte (don't do this).

However, this does degrade performance.

In general, the larger the data block the better.

DMA Resource

2019-12-09T21:56:34Z

Jamie Krueger: /* Copy Memory Functions */

== Author ==

Jamie Krueger, BITbyBIT Software Group LLC 
Copyright (c) 2019 Trevor Dickinson 
Used by permission.

== DMA Engine ==

Some hardware targets include a DMA engine which can be used for general purpose copying. This article describes the DMA engines available and how to use them.

=== Hardware Features ===

The Direct Memory Access (DMA) Engines found in the NXP/Freescale p5020, p5040 and p1022 System On a Chip (SoC)s, as found in the AmigaONE X5000/20, X5000/40 and A1222 respectively, are quite flexible and powerful. Each of these chips contains two distinct engines with four data channels each. This provides the ability to have a total of eight DMA Channels working at once, with up to two DMA transactions actually being executed at the same time (one on each of the two DMA Engines).

Further, each of the four DMA Channels found in a DMA Engine may be individually programmed to handle either; a single transaction, a ''Chain'' of transactions, or even ''Lists'' of ''Chains'' of transactions. The DMA Engines automatically arbitrate control between each DMA Channel following programmed bandwidth settings for each Channel (typically 1024 bytes).

This means that after completing a transfer of 1024 bytes (for example), the hardware will consider switching to the next Channel to allow it to move another block of data, and so on in a round-robin fashion. If all other DMA Channels on a given DMA Engine are idle when arbitration would take place, the hardware will not arbitrate control to another Channel, but simply continue processing the transaction(s) for the Channel it is on.

=== DMA Copy Memory - Execution Flow Diagram ===

[[File:DMACopyMem-Diagram.png]]

=== What a call to perform a DMA copy does internally ===

As shown in the above diagram, when the user makes a call to request a memory copy be performed by the DMA hardware, the next available DMA Channel is selected for use and a DMA Transaction (source, destination and size) is constructed. The DMA Transaction is then programmed into the DMA Engine which owns the available DMA Channel.

At this point the calling task will Wait() until it hears the transaction has been completed. It will then return to the caller with the result. This provides a basic ''blocking'' function, which only returns to the caller once that data has been copied. This single tasking behavior is the simplest to use and what is normally expected by most applications using a memory copy function.

=== Diagram of multitasking DMA Copies ===

[[File:DMACopyMem-Multitasking-Diagram.png]]

=== How multiple simultaneous DMA copies are handled ===

When multiple user calls requesting a DMA copy arrive at once, each one is handed to a dedicated DMA Channel handling task for processing. As the diagram above demonstrates, there are two separate DMA Engines available, each with four channels that may be programmed at the same time. The hardware will then arbitrate the actual data move across these channels according to their respective bandwidth settings (usually 1024 bytes).

In the diagram above, a separate color indicates a distinct data path from the caller through the DMA hardware to the system RAM. A dashed line of the matching color indicates an Interrupt line signaling the respective DMA Channel Handler with the completion of the transaction. The handler task then signals back to the original caller, which returns to the user with a success or failure result.

All eight DMA Channels can handle each a single block transaction or an entire chain of block transactions before it signals completion and returns to the original caller. If all eight DMA Channels are busy processing their requested transactions when further DMA copy requests arrive, they will each be assigned a DMA Channel to wait on (managed via a Mutex lock on each Channel) and will block until allowed to add their DMA transaction to the Channel's queue.

== fsldma.resource ==

The fsldma.resource API is provided automatically in the kernel for all supported machines (Currently the AmigaONE X5000/20, X5000/40 and A1222).

=== The FslDMA API ===

The API provided by the fsldma.resource current consists of:
:* Copy Memory functions

==== Copy Memory Functions ====

Three API calls make up the FslDMA API; CopyMemDMA(), CopyMemDMATagList() and CopyMemDMATags().

<syntaxhighlight>
BOOL CopyMemDMA( CONST_APTR pSourceBuffer, APTR pDestBuffer, uint32 lBufferSize );
BOOL CopyMemDMATags( CONST_APTR pSourceBuffer, APTR pDestBuffer, uint32 lBufferSize, uint32 TagItem1, ... );
BOOL CopyMemDMATagList( CONST_APTR pSourceBuffer, APTR pDestBuffer, uint32 lBufferSize, const struct TagItem *tags );
</syntaxhighlight>

The first call, CopyMemDMA(), attempts to perform a "blocking" (does not return to the user until after the requested transfer has either succeeded or failed) operation. A value of TRUE is returned upon success and FALSE if an error occurred. The CopyMemDMA() call will automatically fall back to using an internal fast CPU copy if the requested size is too small to be efficient, or an error occurred in the DMA transaction.

In theory any ''contiguous'' block of memory from 1 Byte up to 4GB in size may be transferred using any one of these calls. In practice the DMA hardware can directly accept memory blocks up to FSLDMA_MAXBLOCK_SIZE (or 64MB - 1 Byte). Therefore any data blocks greater than FSLDMA_MAXBLOCK_SIZE will automatically be sent to the DMA hardware in a series of smaller chunks. For maximum efficiency transfer sizes should be at least 256 Bytes in size and be an even multiple of 64 Bytes. Odd sizes are handled by the hardware but will degrade performance.

==== Further reference - The fsldma.resource AutoDoc ====

See the [[http://wiki.amigaos.net/amiga/autodocs/fsldmares.doc.txt fsldma.resource AutoDoc]] file for more details on each API call.

=== Example 1: "Blocking" mode ===

<syntaxhighlight>
#include <stdio.h>
#include <stdlib.h>
#include <amiga_compiler.h>
#include <exec/types.h>
#include <proto/exec.h>
#include <dos/dos.h>
#include <interfaces/exec.h>
#include <interfaces/fsldma.h>

// fsldma.resource Example 1, "Blocking" DMA Copy
// test using Virtual memory areas
int main()
{
struct fslDMAIFace *IfslDMA = NULL;
uint32 lSize = 0;
CONST_APTR pSrc = NULL;
APTR pDest = NULL;
BOOL bGotResources = FALSE;

// Obtain the fsldma.resource
IfslDMA = IExec->OpenResource(FSLDMA_NAME);

// Set the size of our test buffers
lSize = FSLDMA_OPTIMAL_BLKSIZE; // About 64 MB

// Allocate a test source buffer (fill with some data)
pSrc = IExec->AllocVecTags(lSize,
AVT_Type, MEMF_SHARED,
AVT_ClearWithValue, 0xB3,
TAG_DONE);

// Allocate a test destination buffer (clear with zeroes)
pDest = IExec->AllocVecTags(lSize,
AVT_Type, MEMF_SHARED,
AVT_ClearWithValue, 0,
TAG_DONE);

// Verify we got all resources needed for the test
if ( (NULL != IfslDMA) && (NULL != pSrc) && (NULL != pDest) )
{
bGotResources = TRUE;
}

if ( TRUE == bGotResources )
{
// Call IfslDMA->CopyMemDMA() to perform the memory copy using the
// DMA hardware. Wait for the transaction to complete before continuing.

// We use full 64-Bit values to pass in the source and destination to
// IfslDMA->CopyMemDMA() so we need to use a "double cast" on the
// 32-Bit pointers returned by AllocVecTags() in order to properly pass
// in fully extended 64-Bit pointers.
// (see <resource/fsldma.h> for more details)

printf("Starting \"Blocking\" DMA Transaction"
" of %ld bytes from 0x%08lx to 0x%08lx...\n",lSize,pSrc,pDest);
fflush(stdout);
if ( TRUE == IfslDMA->CopyMemDMA((CONST_DMAPTR)(uint32)pSrc,
(DMAPTR)(uint32)pDest,
lSize) )
{
// Success - Do something with the copied data and quit
printf("Returned with Success.\n");
fflush(stdout);
}
else
{
// Report the error
printf("Received an Error!\n");
fflush(stdout);
}
}
else
{
printf("Failed to obtain resources, aborting test.\n");
fflush(stdout);
}

// Free our test buffers (as needed)
if ( NULL != pSrc ) IExec->FreeVec((APTR)pSrc);
if ( NULL != pDest ) IExec->FreeVec(pDest);
}
</syntaxhighlight>

=== Example 2: "Non-Blocking" mode ===

<syntaxhighlight>
#include <stdio.h>
#include <stdlib.h>
#include <amiga_compiler.h>
#include <exec/types.h>
#include <proto/exec.h>
#include <dos/dos.h>
#include <interfaces/exec.h>
#include <interfaces/fsldma.h>

// fsldma.resource Example 2, "Non-blocking" DMA Copy
// test using user notifications and Physical memory areas
int main()
{
struct ExecBase *ExecBase = (*(struct ExecBase **)4);
struct MMUIFace *IMMU = NULL;
struct fslDMAIFace *IfslDMA = NULL;
uint32 lSize = 0;
CONST_APTR pSrc = NULL;
APTR pDest = NULL;
CONST_APTR pPhySrcAttr = NULL;
APTR pPhyDstAttr = NULL;
int8 nSuccessSigNum = -1;
int8 nInProgressSigNum = -1;
int8 nErrorSigNum = -1;
uint32 lSuccessSigMask = 0;
uint32 lInProgressSigMask = 0;
uint32 lErrorSigMask = 0;
uint32 lAllSigsMask = 0;
BOOL bGotResources = FALSE;

// Obtain the MMU Interface
IMMU = (struct MMUIFace *)IExec->GetInterface((struct Library *)ExecBase,
"MMU",1,NULL);
// Obtain the fsldma.resource
IfslDMA = IExec->OpenResource(FSLDMA_NAME);

// Set our test buffer size large enough to generate some sub-block transfers
lSize = FSLDMA_OPTIMAL_BLKSIZE * 4; // About 256 MB

// Allocate a test source buffer (fill with some data)
pSrc = IExec->AllocVecTags(lSize,
AVT_Type, MEMF_SHARED,
AVT_Contiguous, TRUE,
AVT_Lock, TRUE,
AVT_Alignment, 64,
AVT_PhysicalAlignment, 64,
AVT_ClearWithValue, 0xB3,
TAG_DONE);

// Allocate a test destination buffer (clear with zeroes)
pDest = IExec->AllocVecTags(lSize,
AVT_Type, MEMF_SHARED,
AVT_Contiguous, TRUE,
AVT_Lock, TRUE,
AVT_Alignment, 64,
AVT_PhysicalAlignment, 64,
AVT_ClearWithValue, 0,
TAG_DONE);

// Allocate signals to wait on
nSuccessSigNum = IExec->AllocSignal((int8)-1);
nInProgressSigNum = IExec->AllocSignal((int8)-1);
nErrorSigNum = IExec->AllocSignal((int8)-1);

// Construct the signal masks we need to Wait() on later.
// We are assuming these values are being built with
// allocated signals here, but we will verify it before use.
lSuccessSigMask = (uint32)(1L << nSuccessSigNum);
lInProgressSigMask = (uint32)(1L << nInProgressSigNum);
lErrorSigMask = (uint32)(1L << nErrorSigNum);
lAllSigsMask = (lSuccessSigMask | lInProgressSigMask | lErrorSigMask);

// Obtain the pointer to ourselves (this Task)
struct Task *pThisTask = IExec->FindTask(NULL);

// Verify we got all resources needed for the test
if ( (NULL != IMMU) && (NULL != IfslDMA) &&
(NULL != pSrc) && (NULL != pDest) &&
(NULL != pThisTask ) &&
(-1 != nSuccessSigNum) &&
(-1 != nInProgressSigNum) &&
(-1 != nErrorSigNum) )
{
bGotResources = TRUE;
}

if ( TRUE == bGotResources )
{
// In this test we are using Physical memory areas
// for both source and destination, so before we
// hand the transaction to the DMA hardware, we first
// need to set the flush the data cache, set the
// buffers to cache-inhibited and obtain the Physical
// addresses for both buffers

// Enter Supervisor Mode
APTR pUserStack = IExec->SuperState();

// Flush out any cache for our two buffers
IExec->CacheClearE((APTR)pSrc,lSize,CACRF_ClearD);
IExec->CacheClearE(pDest,lSize,CACRF_ClearD);

// Now set the memory attributes to prevent further cache operations
uint32 lSrcMemAttrs = IMMU->GetMemoryAttrs((APTR)pSrc,0);
uint32 lDstMemAttrs = IMMU->GetMemoryAttrs(pDest,0);
IMMU->SetMemoryAttrs((APTR)pSrc,lSize,(lSrcMemAttrs | FSLDMA_PHYMEM_ATTRS));
IMMU->SetMemoryAttrs(pDest,lSize,(lDstMemAttrs | FSLDMA_PHYMEM_ATTRS));

// Get the Physical addresses for our two buffers
pPhySrcAttr = IMMU->GetPhysicalAddress((APTR)pSrc);
pPhyDstAttr = IMMU->GetPhysicalAddress(pDest);

// Return to User Mode
if ( NULL != pUserStack ) IExec->UserState(pUserStack);

// Call IfslDMA->CopyMemDMATags() to perform the memory copy using the
// DMA hardware. Start off the transaction then wait on completion signals.

// We use full 64-Bit values to pass in the source and destination to
// IfslDMA->CopyMemDMATags() so we need to use a "double cast" on the
// 32-Bit pointers returned by AllocVecTags() in order to properly pass
// in fully extended 64-Bit pointers.
// (see <resource/fsldma.h> for more details)

printf("Starting \"Non-Blocking\" DMA Transaction"
" of %ld bytes from 0x%08lx to 0x%08lx...\n",lSize,pPhySrcAttr,pPhyDstAttr);
fflush(stdout);
if ( TRUE == IfslDMA->CopyMemDMATags((CONST_DMAPTR)(uint32)pPhySrcAttr,
(DMAPTR)(uint32)pPhyDstAttr,
lSize,
FSLDMA_CM_SourceIsPhysical, TRUE,
FSLDMA_CM_DestinationIsPhysical, TRUE,
FSLDMA_CM_DoNotWait, TRUE,
FSLDMA_CM_NotifyTask, pThisTask,
FSLDMA_CM_NotifySignalNumber, nSuccessSigNum,
FSLDMA_CM_NotifyProgessSignalNumber, nInProgressSigNum,
FSLDMA_CM_NotifyErrorSignalNumber, nErrorSigNum,
TAG_DONE) )
{
// If the above call sets up correctly, it returns immeditately
// So do something here *while* the data is being copied...
printf("Doing other stuff before waiting...\n");
fflush(stdout);

// Now we will Wait() for the completion signals from the DMA
BOOL bStillRunning = TRUE;
uint32 lSigReceived = 0;
do
{
// Wait for the DMA completion/status/error signals
printf("Waiting for signals...\n");
fflush(stdout);
lSigReceived = IExec->Wait( lAllSigsMask | SIGBREAKF_CTRL_C );

// Test for the "In Progress" signal
if ( lInProgressSigMask == (lSigReceived & lInProgressSigMask) )
{
// Do something on the "In Process" signal and continue...
printf("Received an \"In Progress\" signal...\n");
fflush(stdout);
}

// Test for the "Success" signal
if ( lSuccessSigMask == (lSigReceived & lSuccessSigMask) )
{
// Success - Do something with the copied data and quit
printf("Received an \"Completed Successfully\" signal.\n");
fflush(stdout);
bStillRunning = FALSE;
}

// Test for the "Error" signal
if ( lErrorSigMask == (lSigReceived & lErrorSigMask) )
{
// Report the error and quit
printf("Received an \"Error\" signal!\n");
fflush(stdout);
bStillRunning = FALSE;
}

// Finally, check if we got a Break signal from the user
// just in case we want to quit out early for some reason
if ( SIGBREAKF_CTRL_C == (lSigReceived & SIGBREAKF_CTRL_C) )
{
printf("Received an \"User break\" signal, ending.\n");
fflush(stdout);
bStillRunning = FALSE;
}
} while( TRUE == bStillRunning );
}
}
else
{
printf("Failed to obtain resources, aborting test.\n");
fflush(stdout);
}

// Free our test buffers (as needed)
if ( NULL != pSrc ) IExec->FreeVec((APTR)pSrc);
if ( NULL != pDest ) IExec->FreeVec(pDest);
// Free any signals we (may have) obtained earlier
if ( -1 != nSuccessSigNum ) IExec->FreeSignal(nSuccessSigNum);
if ( -1 != nInProgressSigNum ) IExec->FreeSignal(nInProgressSigNum);
if ( -1 != nErrorSigNum ) IExec->FreeSignal(nErrorSigNum);
// Release the MMU Interface (as needed)
if ( NULL != IMMU ) IExec->DropInterface((struct Interface *)IMMU);
}
</syntaxhighlight>

==== Obtaining the fsldma.resource ====

Breaking the above example down the first thing we do is include the interface header for the fsldma.resource and obtain the resource itself.

<syntaxhighlight>
#include <interfaces/fsldma.h>
struct fslDMAIFace *IfslDMA = IExec->OpenResource(FSLDMA_NAME);
</syntaxhighlight>

==== Allocating DMA Compliant Memory ====

Once we have successfully obtained the DMA resource we can directly use its API. The next step we need to do is to allocate some memory '''which we know is DMA compliant''' for use by the resource. This can be accomplished by using the IExec->AllocVecTags() function together with a couple of MMU functions. Together they allow you to ensuring the memory that is returned is properly aligned, contiguous, cache-inhibited and coherent.

We use the Tags version of the allocate memory function first so we can allocate a block of memory for our source buffer and fill it with some test value (in this case the byte value 0xB3).

<syntaxhighlight>
</syntaxhighlight>

We also need a destination buffer for our test. Since it only needs to start out being cleared (filled with zeroes), we can use the simplest form of the allocate memory function here as the allocated memory is cleared by default.

<syntaxhighlight>
</syntaxhighlight>

== Performance ==

Testing DMA memory copies vs their CPU based equivalent indicates that the DMA hardware on all three models (X5000/20, X5000/40 and A1222)
move data approximately two to three times faster than the CPU does so alone.

It should also be noted that these tests were performed when the CPU was effectively idle. CPU memory copy operations scale down roughly
equal with the CPU actively scaling up. So the more the CPU is doing, the longer it takes to complete the memory copy.

Conversely, DMA memory copy operation times are far more predictable as they use the same amount of (minimal) CPU overhead for each copy,
and the actual time it takes the DMA hardware to complete the transaction can be calculated to range from all the DMA Channels being idle,
to all DMA Channels being busy at once and data moves arbitrating between channels every 1024 bytes.

=== Optimal use of the DMA Engine ===

To gain the best performance from the DMA Engines, block sizes of 256 bytes or more should be used.
Also, if possible the size should be an even multiple of at least 4 bytes.

Additionally the memory blocks (source and destination) should be aligned to start on a 64 Byte boundary.

The DMA Engine can and does handle misaligned and odd sized data blocks by first shifting the minimum
required bytes to correct the alignment, then taking smaller chunks of data until the largest chunk of
the block can be moved. It can also handle copies of as little as one byte (don't do this).

However, this does degrade performance.

In general, the larger the data block the better.

DMA Resource

2019-12-04T23:37:38Z

Jamie Krueger: /* Example 1: "Blocking" mode */

== Author ==

Jamie Krueger, BITbyBIT Software Group LLC 
Copyright (c) 2019 Trevor Dickinson 
Used by permission.

== DMA Engine ==

Some hardware targets include a DMA engine which can be used for general purpose copying. This article describes the DMA engines available and how to use them.

=== Hardware Features ===

The Direct Memory Access (DMA) Engines found in the NXP/Freescale p5020, p5040 and p1022 System On a Chip (SoC)s, as found in the AmigaONE X5000/20, X5000/40 and A1222 respectively, are quite flexible and powerful. Each of these chips contains two distinct engines with four data channels each. This provides the ability to have a total of eight DMA Channels working at once, with up to two DMA transactions actually being executed at the same time (one on each of the two DMA Engines).

Further, each of the four DMA Channels found in a DMA Engine may be individually programmed to handle either; a single transaction, a ''Chain'' of transactions, or even ''Lists'' of ''Chains'' of transactions. The DMA Engines automatically arbitrate control between each DMA Channel following programmed bandwidth settings for each Channel (typically 1024 bytes).

This means that after completing a transfer of 1024 bytes (for example), the hardware will consider switching to the next Channel to allow it to move another block of data, and so on in a round-robin fashion. If all other DMA Channels on a given DMA Engine are idle when arbitration would take place, the hardware will not arbitrate control to another Channel, but simply continue processing the transaction(s) for the Channel it is on.

=== DMA Copy Memory - Execution Flow Diagram ===

[[File:DMACopyMem-Diagram.png]]

=== What a call to perform a DMA copy does internally ===

As shown in the above diagram, when the user makes a call to request a memory copy be performed by the DMA hardware, the next available DMA Channel is selected for use and a DMA Transaction (source, destination and size) is constructed. The DMA Transaction is then programmed into the DMA Engine which owns the available DMA Channel.

At this point the calling task will Wait() until it hears the transaction has been completed. It will then return to the caller with the result. This provides a basic ''blocking'' function, which only returns to the caller once that data has been copied. This single tasking behavior is the simplest to use and what is normally expected by most applications using a memory copy function.

=== Diagram of multitasking DMA Copies ===

[[File:DMACopyMem-Multitasking-Diagram.png]]

=== How multiple simultaneous DMA copies are handled ===

When multiple user calls requesting a DMA copy arrive at once, each one is handed to a dedicated DMA Channel handling task for processing. As the diagram above demonstrates, there are two separate DMA Engines available, each with four channels that may be programmed at the same time. The hardware will then arbitrate the actual data move across these channels according to their respective bandwidth settings (usually 1024 bytes).

In the diagram above, a separate color indicates a distinct data path from the caller through the DMA hardware to the system RAM. A dashed line of the matching color indicates an Interrupt line signaling the respective DMA Channel Handler with the completion of the transaction. The handler task then signals back to the original caller, which returns to the user with a success or failure result.

All eight DMA Channels can handle each a single block transaction or an entire chain of block transactions before it signals completion and returns to the original caller. If all eight DMA Channels are busy processing their requested transactions when further DMA copy requests arrive, they will each be assigned a DMA Channel to wait on (managed via a Mutex lock on each Channel) and will block until allowed to add their DMA transaction to the Channel's queue.

== fsldma.resource ==

The fsldma.resource API is provided automatically in the kernel for all supported machines (Currently the AmigaONE X5000/20, X5000/40 and A1222).

=== The FslDMA API ===

The API provided by the fsldma.resource current consists of:
:* Copy Memory functions

==== Copy Memory Functions ====

Three API calls make up the FslDMA API; CopyMemDMA(), CopyMemDMATagList() and CopyMemDMATags().

<syntaxhighlight>
BOOL CopyMemDMA( CONST_DMAPTR pSourceBuffer, DMAPTR pDestBuffer, uint32 lBufferSize );
BOOL CopyMemDMATags( CONST_DMAPTR pSourceBuffer, DMAPTR pDestBuffer, uint32 lBufferSize, uint32 TagItem1, ... );
BOOL CopyMemDMATagList( CONST_DMAPTR pSourceBuffer, DMAPTR pDestBuffer, uint32 lBufferSize, const struct TagItem *tags );
</syntaxhighlight>

The first call, CopyMemDMA(), attempts to perform a "blocking" (does not return to the user until after the requested transfer has either succeeded or failed) operation. A value of TRUE is returned upon success and FALSE if an error occurred. The CopyMemDMA() call will automatically fall back to using an internal fast CPU copy if the requested size is too small to be efficient, or an error occurred in the DMA transaction.

In theory any ''contiguous'' block of memory from 1 Byte up to 4GB in size may be transferred using any one of these calls. In practice the DMA hardware can directly accept memory blocks up to FSLDMA_MAXBLOCK_SIZE (or 64MB - 1 Byte). Therefore any data blocks greater than FSLDMA_MAXBLOCK_SIZE will automatically be sent to the DMA hardware in a series of smaller chunks. For maximum efficiency transfer sizes should be at least 256 Bytes in size and be an even multiple of 64 Bytes. Odd sizes are handled by the hardware but will degrade performance.

If you are transferring many large blocks of data in series and wish to manually send them to the FslDMA API's memory copy functions one block at a time, then setting your block sizes to FSLDMA_OPTIMAL_BLKSIZE (or 64 MB - 64 Bytes) will provide the fastest transfer speeds will the least amount of CPU overhead.

==== Further reference - The fsldma.resource AutoDoc ====

See the [[http://wiki.amigaos.net/amiga/autodocs/fsldmares.doc.txt fsldma.resource AutoDoc]] file for more details on each API call.

=== Example 1: "Blocking" mode ===

<syntaxhighlight>
#include <stdio.h>
#include <stdlib.h>
#include <amiga_compiler.h>
#include <exec/types.h>
#include <proto/exec.h>
#include <dos/dos.h>
#include <interfaces/exec.h>
#include <interfaces/fsldma.h>

// fsldma.resource Example 1, "Blocking" DMA Copy
// test using Virtual memory areas
int main()
{
struct fslDMAIFace *IfslDMA = NULL;
uint32 lSize = 0;
CONST_APTR pSrc = NULL;
APTR pDest = NULL;
BOOL bGotResources = FALSE;

// Obtain the fsldma.resource
IfslDMA = IExec->OpenResource(FSLDMA_NAME);

// Set the size of our test buffers
lSize = FSLDMA_OPTIMAL_BLKSIZE; // About 64 MB

// Allocate a test source buffer (fill with some data)
pSrc = IExec->AllocVecTags(lSize,
AVT_Type, MEMF_SHARED,
AVT_ClearWithValue, 0xB3,
TAG_DONE);

// Allocate a test destination buffer (clear with zeroes)
pDest = IExec->AllocVecTags(lSize,
AVT_Type, MEMF_SHARED,
AVT_ClearWithValue, 0,
TAG_DONE);

// Verify we got all resources needed for the test
if ( (NULL != IfslDMA) && (NULL != pSrc) && (NULL != pDest) )
{
bGotResources = TRUE;
}

if ( TRUE == bGotResources )
{
// Call IfslDMA->CopyMemDMA() to perform the memory copy using the
// DMA hardware. Wait for the transaction to complete before continuing.

// We use full 64-Bit values to pass in the source and destination to
// IfslDMA->CopyMemDMA() so we need to use a "double cast" on the
// 32-Bit pointers returned by AllocVecTags() in order to properly pass
// in fully extended 64-Bit pointers.
// (see <resource/fsldma.h> for more details)

printf("Starting \"Blocking\" DMA Transaction"
" of %ld bytes from 0x%08lx to 0x%08lx...\n",lSize,pSrc,pDest);
fflush(stdout);
if ( TRUE == IfslDMA->CopyMemDMA((CONST_DMAPTR)(uint32)pSrc,
(DMAPTR)(uint32)pDest,
lSize) )
{
// Success - Do something with the copied data and quit
printf("Returned with Success.\n");
fflush(stdout);
}
else
{
// Report the error
printf("Received an Error!\n");
fflush(stdout);
}
}
else
{
printf("Failed to obtain resources, aborting test.\n");
fflush(stdout);
}

// Free our test buffers (as needed)
if ( NULL != pSrc ) IExec->FreeVec((APTR)pSrc);
if ( NULL != pDest ) IExec->FreeVec(pDest);
}
</syntaxhighlight>

=== Example 2: "Non-Blocking" mode ===

<syntaxhighlight>
#include <stdio.h>
#include <stdlib.h>
#include <amiga_compiler.h>
#include <exec/types.h>
#include <proto/exec.h>
#include <dos/dos.h>
#include <interfaces/exec.h>
#include <interfaces/fsldma.h>

// fsldma.resource Example 2, "Non-blocking" DMA Copy
// test using user notifications and Physical memory areas
int main()
{
struct ExecBase *ExecBase = (*(struct ExecBase **)4);
struct MMUIFace *IMMU = NULL;
struct fslDMAIFace *IfslDMA = NULL;
uint32 lSize = 0;
CONST_APTR pSrc = NULL;
APTR pDest = NULL;
CONST_APTR pPhySrcAttr = NULL;
APTR pPhyDstAttr = NULL;
int8 nSuccessSigNum = -1;
int8 nInProgressSigNum = -1;
int8 nErrorSigNum = -1;
uint32 lSuccessSigMask = 0;
uint32 lInProgressSigMask = 0;
uint32 lErrorSigMask = 0;
uint32 lAllSigsMask = 0;
BOOL bGotResources = FALSE;

// Obtain the MMU Interface
IMMU = (struct MMUIFace *)IExec->GetInterface((struct Library *)ExecBase,
"MMU",1,NULL);
// Obtain the fsldma.resource
IfslDMA = IExec->OpenResource(FSLDMA_NAME);

// Set our test buffer size large enough to generate some sub-block transfers
lSize = FSLDMA_OPTIMAL_BLKSIZE * 4; // About 256 MB

// Allocate a test source buffer (fill with some data)
pSrc = IExec->AllocVecTags(lSize,
AVT_Type, MEMF_SHARED,
AVT_Contiguous, TRUE,
AVT_Lock, TRUE,
AVT_Alignment, 64,
AVT_PhysicalAlignment, 64,
AVT_ClearWithValue, 0xB3,
TAG_DONE);

// Allocate a test destination buffer (clear with zeroes)
pDest = IExec->AllocVecTags(lSize,
AVT_Type, MEMF_SHARED,
AVT_Contiguous, TRUE,
AVT_Lock, TRUE,
AVT_Alignment, 64,
AVT_PhysicalAlignment, 64,
AVT_ClearWithValue, 0,
TAG_DONE);

// Allocate signals to wait on
nSuccessSigNum = IExec->AllocSignal((int8)-1);
nInProgressSigNum = IExec->AllocSignal((int8)-1);
nErrorSigNum = IExec->AllocSignal((int8)-1);

// Construct the signal masks we need to Wait() on later.
// We are assuming these values are being built with
// allocated signals here, but we will verify it before use.
lSuccessSigMask = (uint32)(1L << nSuccessSigNum);
lInProgressSigMask = (uint32)(1L << nInProgressSigNum);
lErrorSigMask = (uint32)(1L << nErrorSigNum);
lAllSigsMask = (lSuccessSigMask | lInProgressSigMask | lErrorSigMask);

// Obtain the pointer to ourselves (this Task)
struct Task *pThisTask = IExec->FindTask(NULL);

// Verify we got all resources needed for the test
if ( (NULL != IMMU) && (NULL != IfslDMA) &&
(NULL != pSrc) && (NULL != pDest) &&
(NULL != pThisTask ) &&
(-1 != nSuccessSigNum) &&
(-1 != nInProgressSigNum) &&
(-1 != nErrorSigNum) )
{
bGotResources = TRUE;
}

if ( TRUE == bGotResources )
{
// In this test we are using Physical memory areas
// for both source and destination, so before we
// hand the transaction to the DMA hardware, we first
// need to set the flush the data cache, set the
// buffers to cache-inhibited and obtain the Physical
// addresses for both buffers

// Enter Supervisor Mode
APTR pUserStack = IExec->SuperState();

// Flush out any cache for our two buffers
IExec->CacheClearE((APTR)pSrc,lSize,CACRF_ClearD);
IExec->CacheClearE(pDest,lSize,CACRF_ClearD);

// Now set the memory attributes to prevent further cache operations
uint32 lSrcMemAttrs = IMMU->GetMemoryAttrs((APTR)pSrc,0);
uint32 lDstMemAttrs = IMMU->GetMemoryAttrs(pDest,0);
IMMU->SetMemoryAttrs((APTR)pSrc,lSize,(lSrcMemAttrs | FSLDMA_PHYMEM_ATTRS));
IMMU->SetMemoryAttrs(pDest,lSize,(lDstMemAttrs | FSLDMA_PHYMEM_ATTRS));

// Get the Physical addresses for our two buffers
pPhySrcAttr = IMMU->GetPhysicalAddress((APTR)pSrc);
pPhyDstAttr = IMMU->GetPhysicalAddress(pDest);

// Return to User Mode
if ( NULL != pUserStack ) IExec->UserState(pUserStack);

// Call IfslDMA->CopyMemDMATags() to perform the memory copy using the
// DMA hardware. Start off the transaction then wait on completion signals.

// We use full 64-Bit values to pass in the source and destination to
// IfslDMA->CopyMemDMATags() so we need to use a "double cast" on the
// 32-Bit pointers returned by AllocVecTags() in order to properly pass
// in fully extended 64-Bit pointers.
// (see <resource/fsldma.h> for more details)

printf("Starting \"Non-Blocking\" DMA Transaction"
" of %ld bytes from 0x%08lx to 0x%08lx...\n",lSize,pPhySrcAttr,pPhyDstAttr);
fflush(stdout);
if ( TRUE == IfslDMA->CopyMemDMATags((CONST_DMAPTR)(uint32)pPhySrcAttr,
(DMAPTR)(uint32)pPhyDstAttr,
lSize,
FSLDMA_CM_SourceIsPhysical, TRUE,
FSLDMA_CM_DestinationIsPhysical, TRUE,
FSLDMA_CM_DoNotWait, TRUE,
FSLDMA_CM_NotifyTask, pThisTask,
FSLDMA_CM_NotifySignalNumber, nSuccessSigNum,
FSLDMA_CM_NotifyProgessSignalNumber, nInProgressSigNum,
FSLDMA_CM_NotifyErrorSignalNumber, nErrorSigNum,
TAG_DONE) )
{
// If the above call sets up correctly, it returns immeditately
// So do something here *while* the data is being copied...
printf("Doing other stuff before waiting...\n");
fflush(stdout);

// Now we will Wait() for the completion signals from the DMA
BOOL bStillRunning = TRUE;
uint32 lSigReceived = 0;
do
{
// Wait for the DMA completion/status/error signals
printf("Waiting for signals...\n");
fflush(stdout);
lSigReceived = IExec->Wait( lAllSigsMask | SIGBREAKF_CTRL_C );

// Test for the "In Progress" signal
if ( lInProgressSigMask == (lSigReceived & lInProgressSigMask) )
{
// Do something on the "In Process" signal and continue...
printf("Received an \"In Progress\" signal...\n");
fflush(stdout);
}

// Test for the "Success" signal
if ( lSuccessSigMask == (lSigReceived & lSuccessSigMask) )
{
// Success - Do something with the copied data and quit
printf("Received an \"Completed Successfully\" signal.\n");
fflush(stdout);
bStillRunning = FALSE;
}

// Test for the "Error" signal
if ( lErrorSigMask == (lSigReceived & lErrorSigMask) )
{
// Report the error and quit
printf("Received an \"Error\" signal!\n");
fflush(stdout);
bStillRunning = FALSE;
}

// Finally, check if we got a Break signal from the user
// just in case we want to quit out early for some reason
if ( SIGBREAKF_CTRL_C == (lSigReceived & SIGBREAKF_CTRL_C) )
{
printf("Received an \"User break\" signal, ending.\n");
fflush(stdout);
bStillRunning = FALSE;
}
} while( TRUE == bStillRunning );
}
}
else
{
printf("Failed to obtain resources, aborting test.\n");
fflush(stdout);
}

// Free our test buffers (as needed)
if ( NULL != pSrc ) IExec->FreeVec((APTR)pSrc);
if ( NULL != pDest ) IExec->FreeVec(pDest);
// Free any signals we (may have) obtained earlier
if ( -1 != nSuccessSigNum ) IExec->FreeSignal(nSuccessSigNum);
if ( -1 != nInProgressSigNum ) IExec->FreeSignal(nInProgressSigNum);
if ( -1 != nErrorSigNum ) IExec->FreeSignal(nErrorSigNum);
// Release the MMU Interface (as needed)
if ( NULL != IMMU ) IExec->DropInterface((struct Interface *)IMMU);
}
</syntaxhighlight>

==== Obtaining the fsldma.resource ====

Breaking the above example down the first thing we do is include the interface header for the fsldma.resource and obtain the resource itself.

<syntaxhighlight>
#include <interfaces/fsldma.h>
struct fslDMAIFace *IfslDMA = IExec->OpenResource(FSLDMA_NAME);
</syntaxhighlight>

==== Allocating DMA Compliant Memory ====

Once we have successfully obtained the DMA resource we can directly use its API. The next step we need to do is to allocate some memory '''which we know is DMA compliant''' for use by the resource. This can be accomplished by using the IExec->AllocVecTags() function together with a couple of MMU functions. Together they allow you to ensuring the memory that is returned is properly aligned, contiguous, cache-inhibited and coherent.

We use the Tags version of the allocate memory function first so we can allocate a block of memory for our source buffer and fill it with some test value (in this case the byte value 0xB3).

<syntaxhighlight>
</syntaxhighlight>

We also need a destination buffer for our test. Since it only needs to start out being cleared (filled with zeroes), we can use the simplest form of the allocate memory function here as the allocated memory is cleared by default.

<syntaxhighlight>
</syntaxhighlight>

== Performance ==

Testing DMA memory copies vs their CPU based equivalent indicates that the DMA hardware on all three models (X5000/20, X5000/40 and A1222)
move data approximately two to three times faster than the CPU does so alone.

It should also be noted that these tests were performed when the CPU was effectively idle. CPU memory copy operations scale down roughly
equal with the CPU actively scaling up. So the more the CPU is doing, the longer it takes to complete the memory copy.

Conversely, DMA memory copy operation times are far more predictable as they use the same amount of (minimal) CPU overhead for each copy,
and the actual time it takes the DMA hardware to complete the transaction can be calculated to range from all the DMA Channels being idle,
to all DMA Channels being busy at once and data moves arbitrating between channels every 1024 bytes.

=== Optimal use of the DMA Engine ===

To gain the best performance from the DMA Engines, block sizes of 256 bytes or more should be used.
Also, if possible the size should be an even multiple of at least 4 bytes.

Additionally the memory blocks (source and destination) should be aligned to start on a 64 Byte boundary.

The DMA Engine can and does handle misaligned and odd sized data blocks by first shifting the minimum
required bytes to correct the alignment, then taking smaller chunks of data until the largest chunk of
the block can be moved. It can also handle copies of as little as one byte (don't do this).

However, this does degrade performance.

In general, the larger the data block the better.

DMA Resource

2019-12-04T23:27:44Z

Jamie Krueger: /* fsldma.resource */

== Author ==

Jamie Krueger, BITbyBIT Software Group LLC 
Copyright (c) 2019 Trevor Dickinson 
Used by permission.

== DMA Engine ==

Some hardware targets include a DMA engine which can be used for general purpose copying. This article describes the DMA engines available and how to use them.

=== Hardware Features ===

The Direct Memory Access (DMA) Engines found in the NXP/Freescale p5020, p5040 and p1022 System On a Chip (SoC)s, as found in the AmigaONE X5000/20, X5000/40 and A1222 respectively, are quite flexible and powerful. Each of these chips contains two distinct engines with four data channels each. This provides the ability to have a total of eight DMA Channels working at once, with up to two DMA transactions actually being executed at the same time (one on each of the two DMA Engines).

Further, each of the four DMA Channels found in a DMA Engine may be individually programmed to handle either; a single transaction, a ''Chain'' of transactions, or even ''Lists'' of ''Chains'' of transactions. The DMA Engines automatically arbitrate control between each DMA Channel following programmed bandwidth settings for each Channel (typically 1024 bytes).

This means that after completing a transfer of 1024 bytes (for example), the hardware will consider switching to the next Channel to allow it to move another block of data, and so on in a round-robin fashion. If all other DMA Channels on a given DMA Engine are idle when arbitration would take place, the hardware will not arbitrate control to another Channel, but simply continue processing the transaction(s) for the Channel it is on.

=== DMA Copy Memory - Execution Flow Diagram ===

[[File:DMACopyMem-Diagram.png]]

=== What a call to perform a DMA copy does internally ===

As shown in the above diagram, when the user makes a call to request a memory copy be performed by the DMA hardware, the next available DMA Channel is selected for use and a DMA Transaction (source, destination and size) is constructed. The DMA Transaction is then programmed into the DMA Engine which owns the available DMA Channel.

At this point the calling task will Wait() until it hears the transaction has been completed. It will then return to the caller with the result. This provides a basic ''blocking'' function, which only returns to the caller once that data has been copied. This single tasking behavior is the simplest to use and what is normally expected by most applications using a memory copy function.

=== Diagram of multitasking DMA Copies ===

[[File:DMACopyMem-Multitasking-Diagram.png]]

=== How multiple simultaneous DMA copies are handled ===

When multiple user calls requesting a DMA copy arrive at once, each one is handed to a dedicated DMA Channel handling task for processing. As the diagram above demonstrates, there are two separate DMA Engines available, each with four channels that may be programmed at the same time. The hardware will then arbitrate the actual data move across these channels according to their respective bandwidth settings (usually 1024 bytes).

In the diagram above, a separate color indicates a distinct data path from the caller through the DMA hardware to the system RAM. A dashed line of the matching color indicates an Interrupt line signaling the respective DMA Channel Handler with the completion of the transaction. The handler task then signals back to the original caller, which returns to the user with a success or failure result.

All eight DMA Channels can handle each a single block transaction or an entire chain of block transactions before it signals completion and returns to the original caller. If all eight DMA Channels are busy processing their requested transactions when further DMA copy requests arrive, they will each be assigned a DMA Channel to wait on (managed via a Mutex lock on each Channel) and will block until allowed to add their DMA transaction to the Channel's queue.

== fsldma.resource ==

The fsldma.resource API is provided automatically in the kernel for all supported machines (Currently the AmigaONE X5000/20, X5000/40 and A1222).

=== The FslDMA API ===

The API provided by the fsldma.resource current consists of:
:* Copy Memory functions

==== Copy Memory Functions ====

Three API calls make up the FslDMA API; CopyMemDMA(), CopyMemDMATagList() and CopyMemDMATags().

<syntaxhighlight>
BOOL CopyMemDMA( CONST_DMAPTR pSourceBuffer, DMAPTR pDestBuffer, uint32 lBufferSize );
BOOL CopyMemDMATags( CONST_DMAPTR pSourceBuffer, DMAPTR pDestBuffer, uint32 lBufferSize, uint32 TagItem1, ... );
BOOL CopyMemDMATagList( CONST_DMAPTR pSourceBuffer, DMAPTR pDestBuffer, uint32 lBufferSize, const struct TagItem *tags );
</syntaxhighlight>

The first call, CopyMemDMA(), attempts to perform a "blocking" (does not return to the user until after the requested transfer has either succeeded or failed) operation. A value of TRUE is returned upon success and FALSE if an error occurred. The CopyMemDMA() call will automatically fall back to using an internal fast CPU copy if the requested size is too small to be efficient, or an error occurred in the DMA transaction.

In theory any ''contiguous'' block of memory from 1 Byte up to 4GB in size may be transferred using any one of these calls. In practice the DMA hardware can directly accept memory blocks up to FSLDMA_MAXBLOCK_SIZE (or 64MB - 1 Byte). Therefore any data blocks greater than FSLDMA_MAXBLOCK_SIZE will automatically be sent to the DMA hardware in a series of smaller chunks. For maximum efficiency transfer sizes should be at least 256 Bytes in size and be an even multiple of 64 Bytes. Odd sizes are handled by the hardware but will degrade performance.

If you are transferring many large blocks of data in series and wish to manually send them to the FslDMA API's memory copy functions one block at a time, then setting your block sizes to FSLDMA_OPTIMAL_BLKSIZE (or 64 MB - 64 Bytes) will provide the fastest transfer speeds will the least amount of CPU overhead.

==== Further reference - The fsldma.resource AutoDoc ====

See the [[http://wiki.amigaos.net/amiga/autodocs/fsldmares.doc.txt fsldma.resource AutoDoc]] file for more details on each API call.

=== Example 1: "Blocking" mode ===

<syntaxhighlight>
# <interfaces/fsldma.h>
// Obtain the fsldma.resource
struct fslDMAIFace *IfslDMA = IExec->OpenResource(FSLDMA_NAME);
if ( NULL != IfslDMA )
{
// Allocate a couple of test buffers (fill the source with data)
uint32 lSize = FSLDMA_OPTIMAL_BLKSIZE;
CONST_APTR pSrc = IExec->AllocVecTags(lSize,
AVT_Type, MEMF_SHARED,
AVT_ClearWithValue, 0xB3,
TAG_DONE);
APTR pDest = IExec->AllocVecTags(lSize,
AVT_Type, MEMF_SHARED,
AVT_ClearWithValue, 0,
TAG_DONE);
if ( (NULL != pSrc) && (NULL != pDest) )
{
// Call IfslDMA->CopyMemDMA() to perform the memory copy using the DMA hardware.
// We use full 64-Bit values to pass in the source and destination to CopyMemDMA
// so we need to use a "double cast" on the 32-Bit pointers returned by
// AllocVecTags() in order to properly pass in fully extended 64-Bit pointers
// (see <resource/fsldma.h> for more details)

if ( TRUE == IfslDMA->CopyMemDMA((CONST_DMAPTR)(uint32)pSrc,
(DMAPTR)(uint32)pDest,
lSize) )
{
// Success - Do something with the copied data
}

// Free our test buffers
IExec->FreeVec(pSrc);
IExec->FreeVec(pDest);
}
}
</syntaxhighlight>

=== Example 2: "Non-Blocking" mode ===

<syntaxhighlight>
#include <stdio.h>
#include <stdlib.h>
#include <amiga_compiler.h>
#include <exec/types.h>
#include <proto/exec.h>
#include <dos/dos.h>
#include <interfaces/exec.h>
#include <interfaces/fsldma.h>

// fsldma.resource Example 2, "Non-blocking" DMA Copy
// test using user notifications and Physical memory areas
int main()
{
struct ExecBase *ExecBase = (*(struct ExecBase **)4);
struct MMUIFace *IMMU = NULL;
struct fslDMAIFace *IfslDMA = NULL;
uint32 lSize = 0;
CONST_APTR pSrc = NULL;
APTR pDest = NULL;
CONST_APTR pPhySrcAttr = NULL;
APTR pPhyDstAttr = NULL;
int8 nSuccessSigNum = -1;
int8 nInProgressSigNum = -1;
int8 nErrorSigNum = -1;
uint32 lSuccessSigMask = 0;
uint32 lInProgressSigMask = 0;
uint32 lErrorSigMask = 0;
uint32 lAllSigsMask = 0;
BOOL bGotResources = FALSE;

// Obtain the MMU Interface
IMMU = (struct MMUIFace *)IExec->GetInterface((struct Library *)ExecBase,
"MMU",1,NULL);
// Obtain the fsldma.resource
IfslDMA = IExec->OpenResource(FSLDMA_NAME);

// Set our test buffer size large enough to generate some sub-block transfers
lSize = FSLDMA_OPTIMAL_BLKSIZE * 4; // About 256 MB

// Allocate a test source buffer (fill with some data)
pSrc = IExec->AllocVecTags(lSize,
AVT_Type, MEMF_SHARED,
AVT_Contiguous, TRUE,
AVT_Lock, TRUE,
AVT_Alignment, 64,
AVT_PhysicalAlignment, 64,
AVT_ClearWithValue, 0xB3,
TAG_DONE);

// Allocate a test destination buffer (clear with zeroes)
pDest = IExec->AllocVecTags(lSize,
AVT_Type, MEMF_SHARED,
AVT_Contiguous, TRUE,
AVT_Lock, TRUE,
AVT_Alignment, 64,
AVT_PhysicalAlignment, 64,
AVT_ClearWithValue, 0,
TAG_DONE);

// Allocate signals to wait on
nSuccessSigNum = IExec->AllocSignal((int8)-1);
nInProgressSigNum = IExec->AllocSignal((int8)-1);
nErrorSigNum = IExec->AllocSignal((int8)-1);

// Construct the signal masks we need to Wait() on later.
// We are assuming these values are being built with
// allocated signals here, but we will verify it before use.
lSuccessSigMask = (uint32)(1L << nSuccessSigNum);
lInProgressSigMask = (uint32)(1L << nInProgressSigNum);
lErrorSigMask = (uint32)(1L << nErrorSigNum);
lAllSigsMask = (lSuccessSigMask | lInProgressSigMask | lErrorSigMask);

// Obtain the pointer to ourselves (this Task)
struct Task *pThisTask = IExec->FindTask(NULL);

// Verify we got all resources needed for the test
if ( (NULL != IMMU) && (NULL != IfslDMA) &&
(NULL != pSrc) && (NULL != pDest) &&
(NULL != pThisTask ) &&
(-1 != nSuccessSigNum) &&
(-1 != nInProgressSigNum) &&
(-1 != nErrorSigNum) )
{
bGotResources = TRUE;
}

if ( TRUE == bGotResources )
{
// In this test we are using Physical memory areas
// for both source and destination, so before we
// hand the transaction to the DMA hardware, we first
// need to set the flush the data cache, set the
// buffers to cache-inhibited and obtain the Physical
// addresses for both buffers

// Enter Supervisor Mode
APTR pUserStack = IExec->SuperState();

// Flush out any cache for our two buffers
IExec->CacheClearE((APTR)pSrc,lSize,CACRF_ClearD);
IExec->CacheClearE(pDest,lSize,CACRF_ClearD);

// Now set the memory attributes to prevent further cache operations
uint32 lSrcMemAttrs = IMMU->GetMemoryAttrs((APTR)pSrc,0);
uint32 lDstMemAttrs = IMMU->GetMemoryAttrs(pDest,0);
IMMU->SetMemoryAttrs((APTR)pSrc,lSize,(lSrcMemAttrs | FSLDMA_PHYMEM_ATTRS));
IMMU->SetMemoryAttrs(pDest,lSize,(lDstMemAttrs | FSLDMA_PHYMEM_ATTRS));

// Get the Physical addresses for our two buffers
pPhySrcAttr = IMMU->GetPhysicalAddress((APTR)pSrc);
pPhyDstAttr = IMMU->GetPhysicalAddress(pDest);

// Return to User Mode
if ( NULL != pUserStack ) IExec->UserState(pUserStack);

// Call IfslDMA->CopyMemDMATags() to perform the memory copy using the
// DMA hardware. Start off the transaction then wait on completion signals.

// We use full 64-Bit values to pass in the source and destination to
// IfslDMA->CopyMemDMATags() so we need to use a "double cast" on the
// 32-Bit pointers returned by AllocVecTags() in order to properly pass
// in fully extended 64-Bit pointers.
// (see <resource/fsldma.h> for more details)

printf("Starting \"Non-Blocking\" DMA Transaction"
" of %ld bytes from 0x%08lx to 0x%08lx...\n",lSize,pPhySrcAttr,pPhyDstAttr);
fflush(stdout);
if ( TRUE == IfslDMA->CopyMemDMATags((CONST_DMAPTR)(uint32)pPhySrcAttr,
(DMAPTR)(uint32)pPhyDstAttr,
lSize,
FSLDMA_CM_SourceIsPhysical, TRUE,
FSLDMA_CM_DestinationIsPhysical, TRUE,
FSLDMA_CM_DoNotWait, TRUE,
FSLDMA_CM_NotifyTask, pThisTask,
FSLDMA_CM_NotifySignalNumber, nSuccessSigNum,
FSLDMA_CM_NotifyProgessSignalNumber, nInProgressSigNum,
FSLDMA_CM_NotifyErrorSignalNumber, nErrorSigNum,
TAG_DONE) )
{
// If the above call sets up correctly, it returns immeditately
// So do something here *while* the data is being copied...
printf("Doing other stuff before waiting...\n");
fflush(stdout);

// Now we will Wait() for the completion signals from the DMA
BOOL bStillRunning = TRUE;
uint32 lSigReceived = 0;
do
{
// Wait for the DMA completion/status/error signals
printf("Waiting for signals...\n");
fflush(stdout);
lSigReceived = IExec->Wait( lAllSigsMask | SIGBREAKF_CTRL_C );

// Test for the "In Progress" signal
if ( lInProgressSigMask == (lSigReceived & lInProgressSigMask) )
{
// Do something on the "In Process" signal and continue...
printf("Received an \"In Progress\" signal...\n");
fflush(stdout);
}

// Test for the "Success" signal
if ( lSuccessSigMask == (lSigReceived & lSuccessSigMask) )
{
// Success - Do something with the copied data and quit
printf("Received an \"Completed Successfully\" signal.\n");
fflush(stdout);
bStillRunning = FALSE;
}

// Test for the "Error" signal
if ( lErrorSigMask == (lSigReceived & lErrorSigMask) )
{
// Report the error and quit
printf("Received an \"Error\" signal!\n");
fflush(stdout);
bStillRunning = FALSE;
}

// Finally, check if we got a Break signal from the user
// just in case we want to quit out early for some reason
if ( SIGBREAKF_CTRL_C == (lSigReceived & SIGBREAKF_CTRL_C) )
{
printf("Received an \"User break\" signal, ending.\n");
fflush(stdout);
bStillRunning = FALSE;
}
} while( TRUE == bStillRunning );
}
}
else
{
printf("Failed to obtain resources, aborting test.\n");
fflush(stdout);
}

// Free our test buffers (as needed)
if ( NULL != pSrc ) IExec->FreeVec((APTR)pSrc);
if ( NULL != pDest ) IExec->FreeVec(pDest);
// Free any signals we (may have) obtained earlier
if ( -1 != nSuccessSigNum ) IExec->FreeSignal(nSuccessSigNum);
if ( -1 != nInProgressSigNum ) IExec->FreeSignal(nInProgressSigNum);
if ( -1 != nErrorSigNum ) IExec->FreeSignal(nErrorSigNum);
// Release the MMU Interface (as needed)
if ( NULL != IMMU ) IExec->DropInterface((struct Interface *)IMMU);
}
</syntaxhighlight>

==== Obtaining the fsldma.resource ====

Breaking the above example down the first thing we do is include the interface header for the fsldma.resource and obtain the resource itself.

<syntaxhighlight>
#include <interfaces/fsldma.h>
struct fslDMAIFace *IfslDMA = IExec->OpenResource(FSLDMA_NAME);
</syntaxhighlight>

==== Allocating DMA Compliant Memory ====

Once we have successfully obtained the DMA resource we can directly use its API. The next step we need to do is to allocate some memory '''which we know is DMA compliant''' for use by the resource. This can be accomplished by using the IExec->AllocVecTags() function together with a couple of MMU functions. Together they allow you to ensuring the memory that is returned is properly aligned, contiguous, cache-inhibited and coherent.

We use the Tags version of the allocate memory function first so we can allocate a block of memory for our source buffer and fill it with some test value (in this case the byte value 0xB3).

<syntaxhighlight>
</syntaxhighlight>

We also need a destination buffer for our test. Since it only needs to start out being cleared (filled with zeroes), we can use the simplest form of the allocate memory function here as the allocated memory is cleared by default.

<syntaxhighlight>
</syntaxhighlight>

== Performance ==

Testing DMA memory copies vs their CPU based equivalent indicates that the DMA hardware on all three models (X5000/20, X5000/40 and A1222)
move data approximately two to three times faster than the CPU does so alone.

It should also be noted that these tests were performed when the CPU was effectively idle. CPU memory copy operations scale down roughly
equal with the CPU actively scaling up. So the more the CPU is doing, the longer it takes to complete the memory copy.

Conversely, DMA memory copy operation times are far more predictable as they use the same amount of (minimal) CPU overhead for each copy,
and the actual time it takes the DMA hardware to complete the transaction can be calculated to range from all the DMA Channels being idle,
to all DMA Channels being busy at once and data moves arbitrating between channels every 1024 bytes.

=== Optimal use of the DMA Engine ===

To gain the best performance from the DMA Engines, block sizes of 256 bytes or more should be used.
Also, if possible the size should be an even multiple of at least 4 bytes.

Additionally the memory blocks (source and destination) should be aligned to start on a 64 Byte boundary.

The DMA Engine can and does handle misaligned and odd sized data blocks by first shifting the minimum
required bytes to correct the alignment, then taking smaller chunks of data until the largest chunk of
the block can be moved. It can also handle copies of as little as one byte (don't do this).

However, this does degrade performance.

In general, the larger the data block the better.

DMA Resource

2019-12-04T20:11:30Z

Jamie Krueger: /* Optimal use of the DMA Engine */

DMA Resource

2019-12-04T20:10:44Z

Jamie Krueger: /* Example usage */

DMA Resource

2019-12-04T20:00:55Z

Jamie Krueger: /* The FslDMA API */

== Author ==

Jamie Krueger, BITbyBIT Software Group LLC 
Copyright (c) 2019 Trevor Dickinson 
Used by permission.

== DMA Engine ==

Some hardware targets include a DMA engine which can be used for general purpose copying. This article describes the DMA engines available and how to use them.

=== Hardware Features ===

The Direct Memory Access (DMA) Engines found in the NXP/Freescale p5020, p5040 and p1022 System On a Chip (SoC)s, as found in the AmigaONE X5000/20, X5000/40 and A1222 respectively, are quite flexible and powerful. Each of these chips contains two distinct engines with four data channels each. This provides the ability to have a total of eight DMA Channels working at once, with up to two DMA transactions actually being executed at the same time (one on each of the two DMA Engines).

Further, each of the four DMA Channels found in a DMA Engine may be individually programmed to handle either; a single transaction, a ''Chain'' of transactions, or even ''Lists'' of ''Chains'' of transactions. The DMA Engines automatically arbitrate control between each DMA Channel following programmed bandwidth settings for each Channel (typically 1024 bytes).

This means that after completing a transfer of 1024 bytes (for example), the hardware will consider switching to the next Channel to allow it to move another block of data, and so on in a round-robin fashion. If all other DMA Channels on a given DMA Engine are idle when arbitration would take place, the hardware will not arbitrate control to another Channel, but simply continue processing the transaction(s) for the Channel it is on.

=== DMA Copy Memory - Execution Flow Diagram ===

[[File:DMACopyMem-Diagram.png]]

=== What a call to perform a DMA copy does internally ===

As shown in the above diagram, when the user makes a call to request a memory copy be performed by the DMA hardware, the next available DMA Channel is selected for use and a DMA Transaction (source, destination and size) is constructed. The DMA Transaction is then programmed into the DMA Engine which owns the available DMA Channel.

At this point the calling task will Wait() until it hears the transaction has been completed. It will then return to the caller with the result. This provides a basic ''blocking'' function, which only returns to the caller once that data has been copied. This single tasking behavior is the simplest to use and what is normally expected by most applications using a memory copy function.

=== Diagram of multitasking DMA Copies ===

[[File:DMACopyMem-Multitasking-Diagram.png]]

=== How multiple simultaneous DMA copies are handled ===

When multiple user calls requesting a DMA copy arrive at once, each one is handed to a dedicated DMA Channel handling task for processing. As the diagram above demonstrates, there are two separate DMA Engines available, each with four channels that may be programmed at the same time. The hardware will then arbitrate the actual data move across these channels according to their respective bandwidth settings (usually 1024 bytes).

In the diagram above, a separate color indicates a distinct data path from the caller through the DMA hardware to the system RAM. A dashed line of the matching color indicates an Interrupt line signaling the respective DMA Channel Handler with the completion of the transaction. The handler task then signals back to the original caller, which returns to the user with a success or failure result.

All eight DMA Channels can handle each a single block transaction or an entire chain of block transactions before it signals completion and returns to the original caller. If all eight DMA Channels are busy processing their requested transactions when further DMA copy requests arrive, they will each be assigned a DMA Channel to wait on (managed via a Mutex lock on each Channel) and will block until allowed to add their DMA transaction to the Channel's queue.

== fsldma.resource ==

The fsldma.resource API is provided automatically in the kernel for all supported machines (Currently the AmigaONE X5000/20, X5000/40 and A1222).

=== The FslDMA API ===

The API provided by the fsldma.resource current consists of:
:* Copy Memory functions

==== Copy Memory Functions ====

Three API calls make up the FslDMA API; CopyMemDMA(), CopyMemDMATagList() and CopyMemDMATags().

<syntaxhighlight>
BOOL CopyMemDMA( CONST_DMAPTR pSourceBuffer, DMAPTR pDestBuffer, uint32 lBufferSize );
BOOL CopyMemDMATags( CONST_DMAPTR pSourceBuffer, DMAPTR pDestBuffer, uint32 lBufferSize, uint32 TagItem1, ... );
BOOL CopyMemDMATagList( CONST_DMAPTR pSourceBuffer, DMAPTR pDestBuffer, uint32 lBufferSize, const struct TagItem *tags );
</syntaxhighlight>

The first call, CopyMemDMA(), attempts to perform a "blocking" (does not return to the user until after the requested transfer has either succeeded or failed) operation. A value of TRUE is returned upon success and FALSE if an error occurred. The CopyMemDMA() call will automatically fall back to using an internal fast CPU copy if the requested size is too small to be efficient, or an error occurred in the DMA transaction.

In theory any ''contiguous'' block of memory from 1 Byte up to 4GB in size may be transferred using any one of these calls. In practice the DMA hardware can directly accept memory blocks up to FSLDMA_MAXBLOCK_SIZE (or 64MB - 1 Byte). Therefore any data blocks greater than FSLDMA_MAXBLOCK_SIZE will automatically be sent to the DMA hardware in a series of smaller chunks. For maximum efficiency transfer sizes should be at least 256 Bytes in size and be an even multiple of 64 Bytes. Odd sizes are handled by the hardware but will degrade performance.

If you are transferring many large blocks of data in series and wish to manually send them to the FslDMA API's memory copy functions one block at a time, then setting your block sizes to FSLDMA_OPTIMAL_BLKSIZE (or 64 MB - 64 Bytes) will provide the fastest transfer speeds will the least amount of CPU overhead.

==== Further reference - The fsldma.resource AutoDoc ====

See the [[http://wiki.amigaos.net/amiga/autodocs/fsldmares.doc.txt fsldma.resource AutoDoc]] file for more details on each API call.

=== Example usage ===
<syntaxhighlight>
#include <interfaces/fsldma.h>
// Obtain the fsldma.resource
struct fslDMAIFace *IfslDMA = IExec->OpenResource(FSLDMA_NAME);
if ( NULL != IfslDMA )
{
uint32 lTestSize = 1024;
CONST_APTR pPhysicalSrcAddr = NULL;
APTR pPhysicalDestAddr = NULL;
// Allocate the Source Buffer (for DMA)
// and set the contents to 0xB3 (just an example value)
pPhysicalSrcAddr = (CONST_APTR)IfslDMA->DMAAllocPhysicalMemoryTags(lTestSize,
FSLDMA_APM_ClearWithValue, 0xB3,
TAG_END);
if ( NULL != pPhysicalSrcAddr )
{
// Allocate the Destination Buffer (for DMA)
// - contents will by cleared by default
pPhysicalDestAddr = IfslDMA->DMAAllocPhysicalMemory(lTestSize);
if ( NULL != pPhysicalDestAddr )
{
// Call IfslDMA->DMAPhysicalCopyMem()
// to perform the memory copy using the DMA hardware
if ( TRUE == IfslDMA->DMAPhysicalCopyMem(pPhysicalSrcAddr,
pPhysicalDestAddr,lTestSize) )
{
// Success - Do something with the copied data
}
else
{
// Fallback and use CPU Copy instead (or do something else)
// Since we allocated the memory buffers using the FslDMA API,
// which returns the Physical address to that memory, and the
// IExec->CopyMemQuick() function expects the Virtual address,
// we first need to obtain the Virtual address for the Physical
// ones (using the FslDMA API again) before we can call our
// fallback copy function.
CONST_APTR pVirtualSrcAddr = NULL;
APTR pVirtualDestAddr = NULL;
pVirtualSrcAddr = IfslDMA->DMAGetVirtualAddress((APTR)pPhysicalSrcAddr);
pVirtualDestAddr = IfslDMA->DMAGetVirtualAddress(pPhysicalDestAddr);
IExec->CopyMemQuick(pVirtualSrcAddr,pVirtualDestAddr,lTestSize);
}
// We *must* use DMAFreePhysicalMemory() to free the memory
// that we allocated with DMAAllocPhysicalMemory()
IfslDMA->DMAFreePhysicalMemory(pPhysicalDestAddr);
}
// We *must* use DMAFreePhysicalMemory() to free the memory
// that we allocated with DMAAllocPhysicalMemory()
IfslDMA->DMAFreePhysicalMemory((APTR)pPhysicalSrcAddr);
}
}
</syntaxhighlight>

==== Obtaining the fsldma.resource ====

Breaking the above example down the first thing we do is include the interface header for the fsldma.resource and obtain the resource itself.

<syntaxhighlight>
#include <interfaces/fsldma.h>
struct fslDMAIFace *IfslDMA = IExec->OpenResource(FSLDMA_NAME);
</syntaxhighlight>

==== Allocating DMA Compliant Memory ====

Once we have successfully obtained the DMA resource we can directly use its API. The next step we need to do is to allocate some memory '''which we know is DMA compliant''' for use by the resource. The easiest way to accomplish this is to use the IfslDMA->DMAAllocPhysicalMemory() function. This will automatically take care of ensuring the memory that is returned is properly aligned, contiguous, cache-inhibited and coherent.

We use the Tags version of the allocate memory function first so we can allocate a block of memory for our source buffer and fill it with some test value (in this case the byte value 0xB3).

<syntaxhighlight>
pPhysicalSrcAddr = (CONST_APTR)IfslDMA->DMAAllocPhysicalMemoryTags(lTestSize,
FSLDMA_APM_ClearWithValue, 0xB3,
TAG_END);
</syntaxhighlight>

We also need a destination buffer for our test. Since it only needs to start out being cleared (filled with zeroes), we can use the simplest form of the allocate memory function here as the allocated memory is cleared by default.

<syntaxhighlight>
pPhysicalDestAddr = IfslDMA->DMAAllocPhysicalMemory(lTestSize);
</syntaxhighlight>

==== The core function - Copy Physical Memory ====

Now that we have two DMA Compliant memory buffers available we can get to the heart of the API usage and make the call to IfslDMA->DMAPhysicalCopyMem().

<syntaxhighlight>
IfslDMA->DMAPhysicalCopyMem(pPhysicalSrcAddr,pPhysicalDestAddr,lTestSize);
</syntaxhighlight>

Looking at the full [[#Example usage|Example]] source above you can see that the DMAPhysicalCopyMem() call returns a Boolean value to indicate success or failure. Therefore, TRUE will be returned after the DMA hardware had completed copying the requested data (blocking call) and FALSE will be returned if a problem occurred.

Since the memory buffers we are using were allocated using the FslDMA API and our transfer size was greater than zero and less than or equal to the total size of either buffer, (in others words a legal copy request), there is '''very''' little chance that the DMAPhysicalCopyMem() function will fail. In fact, about the only reason the DMA hardware would fail to handle a legal transaction would be if the physical RAM installed in the system was faulty.

So even though it is extremely unlikely for our DMA copy to have failed and returned FALSE, let's take a look at how we might handle the failure. In other words, falling back and using a CPU based copy function instead to complete the data move.

Since we are reverting back to using a normal system copy memory function here, we first need to obtain the ''Virtual Addresses'' to both our source and destination buffers. This is accomplished by using the DMAGetVirtualAddress() function and passing in the Physical Address that was returned by DMAAllocPhysicalMemory().

<syntaxhighlight>
CONST_APTR pVirtualSrcAddr = NULL;
APTR pVirtualDestAddr = NULL;
pVirtualSrcAddr = IfslDMA->DMAGetVirtualAddress((APTR)pPhysicalSrcAddr);
pVirtualDestAddr = IfslDMA->DMAGetVirtualAddress(pPhysicalDestAddr);
</syntaxhighlight>

Now that we have the Virtual Address equivalents to the Physical Addresses that were returned by DMAAllocPhysicalMemory(), we can proceed to call the Exec CopyMemQuick() function to complete the copy. Here we can only trust that the IExec->CopyMemQuick() call can not fail since it does not return a result code.

<syntaxhighlight>
IExec->CopyMemQuick(pVirtualSrcAddr,pVirtualDestAddr,lTestSize);
</syntaxhighlight>

==== Cleaning up - Freeing DMA Compliant memory ====

It is essential that you free any memory that was allocated using the DMAAllocPhysicalMemory() function using the corresponding DMAFreePhysicalMemory() call. The reason for this is two-fold; first because additional resource tracking is maintained by the FslDMA API whenever it allocates memory which must itself be released, and second because the ''Physical Address'' to the memory is returned by the allocate call and not the ''Virtual Address'', so if you attempt to pass the address returned by DMAAllocPhysicalMemory() directly into IExec->FreeVec() it would likely result in a crash.

<syntaxhighlight>
IfslDMA->DMAFreePhysicalMemory(pPhysicalSrcAddr);
IfslDMA->DMAFreePhysicalMemory(pPhysicalDestAddr);
</syntaxhighlight>

== Performance ==

Testing DMA memory copies vs their CPU based equivalent indicates that the DMA hardware on all three models (X5000/20, X5000/40 and A1222)
move data approximately two to three times faster than the CPU does so alone.

It should also be noted that these tests were performed when the CPU was effectively idle. CPU memory copy operations scale down roughly
equal with the CPU actively scaling up. So the more the CPU is doing, the longer it takes to complete the memory copy.

Conversely, DMA memory copy operation times are far more predictable as they use the same amount of (minimal) CPU overhead for each copy,
and the actual time it takes the DMA hardware to complete the transaction can be calculated to range from all the DMA Channels being idle,
to all DMA Channels being busy at once and data moves arbitrating between channels every 1024 bytes.

=== Optimal use of the DMA Engine ===

To gain the best performance from the DMA Engines, block sizes of 256 bytes or more should be used.
Also, if possible the size should be an even multiple of at least 4 bytes.

Additionally the memory blocks (source and destination) should be aligned to start on a 64 Byte boundary.
Alignment requirements are one of items taken care of for you by the DMAAllocPhysicalMemory() function.

The DMA Engine can and does handle misaligned and odd sized data blocks by first shifting the minimum
required bytes to correct the alignment, then taking smaller chunks of data until the largest chunk of
the block can be moved. It can also handle copies of as little as one byte (don't do this).

However, this does degrade performance.

In general, the larger the data block the better.

File:DMACopyMem-Multitasking-Diagram.png

2019-12-04T19:47:24Z

Jamie Krueger: Jamie Krueger uploaded a new version of File:DMACopyMem-Multitasking-Diagram.png

DMA Engine diagram of multiple simultaneous memory copy calls.

File:DMACopyMem-Diagram.png

2019-12-04T19:42:31Z

Jamie Krueger: Jamie Krueger uploaded a new version of File:DMACopyMem-Diagram.png

Diagram of DMA Engine's Copy Memory function (execution flow)

File:DMACopyMem-Diagram.png

2019-12-04T19:41:21Z

Jamie Krueger: Jamie Krueger uploaded a new version of File:DMACopyMem-Diagram.png

Diagram of DMA Engine's Copy Memory function (execution flow)

File:DMACopyMem-Diagram.png

2019-12-04T19:35:03Z

Jamie Krueger: Jamie Krueger uploaded a new version of File:DMACopyMem-Diagram.png

Diagram of DMA Engine's Copy Memory function (execution flow)

DMA Resource

2019-11-20T16:31:01Z

Jamie Krueger: /* Performance */

== DMA Engine ==

Some hardware targets include a DMA engine which can be used for general purpose copying. This article describes the DMA engines available and how to use them.

=== Hardware Features ===

The Direct Memory Access (DMA) Engines found in the NXP/Freescale p5020, p5040 and p1022 System On a Chip (SoC)s, as found in the AmigaONE X5000/20, X5000/40 and A1222 respectively, are quite flexible and powerful. Each of these chips contains two distinct engines with four data channels each. This provides the ability to have a total of eight DMA Channels working at once, with up to two DMA transactions actually being executed at the same time (one on each of the two DMA Engines).

Further, each of the four DMA Channels found in a DMA Engine may be individually programmed to handle either; a single transaction, a ''Chain'' of transactions, or even ''Lists'' of ''Chains'' of transactions. The DMA Engines automatically arbitrate control between each DMA Channel following programmed bandwidth settings for each Channel (typically 1024 bytes).

This means that after completing a transfer of 1024 bytes (for example), the hardware will consider switching to the next Channel to allow it to move another block of data, and so on in a round-robin fashion. If all other DMA Channels on a given DMA Engine are idle when arbitration would take place, the hardware will not arbitrate control to another Channel, but simply continue processing the transaction(s) for the Channel it is on.

=== DMA Copy Memory - Execution Flow Diagram ===

[[File:DMACopyMem-Diagram.png]]

=== What a call to perform a DMA copy does internally ===

As shown in the above diagram, when the user makes a call to request a memory copy be performed by the DMA hardware, the next available DMA Channel is selected for use and a DMA Transaction (source, destination and size) is constructed. The DMA Transaction is then programmed into the DMA Engine which owns the available DMA Channel.

At this point the calling task will Wait() until it hears the transaction has been completed. It will then return to the caller with the result. This provides a basic ''blocking'' function, which only returns to the caller once that data has been copied. This single tasking behavior is the simplest to use and what is normally expected by most applications using a memory copy function.

=== Diagram of multitasking DMA Copies ===

[[File:DMACopyMem-Multitasking-Diagram.png]]

=== How multiple simultaneous DMA copies are handled ===

When multiple user calls requesting a DMA copy arrive at once, each one is handed to a dedicated DMA Channel handling task for processing. As the diagram above demonstrates, there are two separate DMA Engines available, each with four channels that may be programmed at the same time. The hardware will then arbitrate the actual data move across these channels according to their respective bandwidth settings (usually 1024 bytes).

In the diagram above, a separate color indicates a distinct data path from the caller through the DMA hardware to the system RAM. A dashed line of the matching color indicates an Interrupt line signaling the respective DMA Channel Handler with the completion of the transaction. The handler task then signals back to the original caller, which returns to the user with a success or failure result.

All eight DMA Channels can handle each a single block transaction or an entire chain of block transactions before it signals completion and returns to the original caller. If all eight DMA Channels are busy processing their requested transactions when further DMA copy requests arrive, they will each be assigned a DMA Channel to wait on (managed via a Mutex lock on each Channel) and will block until allowed to add their DMA transaction to the Channel's queue.

== fsldma.resource ==

The fsldma.resource API is provided automatically in the kernel for all supported machines (Currently the AmigaONE X5000/20, X5000/40 and A1222).

=== The FslDMA API ===

The API provided by the fsldma.resource breaks down into three main parts:
:* Memory management
:* Copy Memory functions
:* Utility / Miscellaneous

==== Memory Management Functions ====

The FslDMA resource API provides convenience functions for the allocation and freeing of '''DMA Compliant''' blocks of memory. Two functions are provided for this purpose; DMAAllocPhysicalMemory() and DMAFreePhysicalMemory().

The memory allocation function also includes two Tags based versions of the call to allow for addition variables to be passed into the call using a variable set of Tags or fixed TagList. Currently the only supported Tag is ''FSLDMA_APM_ClearWithValue'', which is the equivalent to the IExec->AllocVecTagList() function's AVT_ClearWithValue tag. If the FSLDMA_APM_ClearWithValue tag is not provided then the requested memory block is cleared with zeroes by default before being returned. DMAAllocPhysicalMemory() returns the ''Physical'' Address pointer to the allocated memory or NULL if it is unable to allocate the requested memory.

<syntaxhighlight>
APTR DMAAllocPhysicalMemoryTagList( uint32 lSize, const struct TagItem *tags );
APTR DMAAllocPhysicalMemoryTags( uint32 lSize, uint32 Tag1, ... );
APTR DMAAllocPhysicalMemory( uint32 lSize );
</syntaxhighlight>

The corresponding function to allocating a DMA Compliant memory block is DMAFreePhysicalMemory(). Any memory allocated using DMAAllocPhysicalMemory() must be eventually freed using DMAFreePhysicalMemory().

<syntaxhighlight>
void DMAFreePhysicalMemory( APTR pPhysicalMemoryBlock );
</syntaxhighlight>

==== Copy Memory Functions ====

Two API calls make up the core of the FslDMA API; DMAPhysicalCopyMem() and DMACopyMem().
Both of these calls will "block" (not return to the user) until after the requested transfer has either succeeded or failed. A value of TRUE is returned upon success and FALSE if an error occurred.

<syntaxhighlight>
BOOL DMAPhysicalCopyMem( CONST_APTR pPhysicalSourceBuffer, APTR pPhysicalDestBuffer, uint32 lBufferSize );
BOOL DMACopyMem( CONST_APTR pSourceBuffer, APTR pDestBuffer, uint32 lBufferSize );
</syntaxhighlight>

As the name implies the first (and core version) of the copy memory functions, DMAPhysicalCopyMem(), accepts the Physical Addresses to the source and destination buffers (as returned by DMAAllocPhysicalMemory()), along with an unsigned 32-Bit value for the amount of bytes that should be copied (lBuffsize must be greater than zero(0) and no more than the maximum size of the source and destination buffers).

DMAPhysicalCopyMem() is the most direct an efficient means of using the DMA hardware to effect a single memory copy. The DMACopyMem() function is provided as an alternative way to request a DMA transfer by passing in the ''Virtual Addresses'' to the source and destination buffers instead of the Physical Addresses. DMACopyMem() will attempt to determine if the supplied memory buffers are DMA Compliant and if so it will internally use DMAPhysicalCopyMem() to handle the transaction. If DMACopyMem() determines that the supplied memory is '''not''' DMA Compliant it will return FALSE and no data copy will occur.

In theory any ''contiguous'' block of memory from 1 Byte up to 4GB in size may be transferred using either one of these calls. In practice the DMA hardware can directly accept memory blocks up to FSLDMA_MAXBLOCK_SIZE (or 64MB - 1 Byte). Therefore any data blocks greater than FSLDMA_MAXBLOCK_SIZE will automatically be feed to the DMA hardware in a series of smaller chunks. For maximum efficiency transfer sizes should be at least 256 Bytes in size and be an even multiple of 64 Bytes. Odd sizes are handled by the hardware but will degrade performance.

If you are transferring many large blocks of data in series and wish to manually send them to the FslDMA API's memory copy functions one block at a time, then setting your block sizes to FSLDMA_OPTIMAL_BLKSIZE (or 64 MB - 64 Bytes) and exclusively using DMAPhysicalCopyMem() will provide the fastest transfer speeds will the least amount of CPU overhead.

==== Utility / Miscellaneous Functions ====

The last section to the FslDMA API provides a single convenience function call; DMAGetVirtualAddress().

<syntaxhighlight>
APTR DMAGetVirtualAddress( APTR pPhysicalAddress );
</syntaxhighlight>

The DMAGetVirtualAddress() function returns the Virtual memory location for the Physical memory location that was itself allocated and returned by the DMAAllocPhysicalMemory() function. DMAGetVirtualAddress() will not work on physical addresses returned by IMMU->GetPhysicalAddress() on memory not allocated using DMAAllocPhysicalMemory().

The main purpose of this function (other then debugging purposes) is to provide the "normal" Virtual Address of memory allocated by the FslDMA API for use by functions that expect "normal" Virtual address locations; for example IExec->CopyMemQuick().

==== Further reference - The fsldma.resource AutoDoc ====

See the [[http://wiki.amigaos.net/amiga/autodocs/fsldmares.doc.txt fsldma.resource AutoDoc]] file for more details on each API call.

=== Example usage ===
<syntaxhighlight>
#include <interfaces/fsldma.h>
// Obtain the fsldma.resource
struct fslDMAIFace *IfslDMA = IExec->OpenResource(FSLDMA_NAME);
if ( NULL != IfslDMA )
{
uint32 lTestSize = 1024;
CONST_APTR pPhysicalSrcAddr = NULL;
APTR pPhysicalDestAddr = NULL;
// Allocate the Source Buffer (for DMA)
// and set the contents to 0xB3 (just an example value)
pPhysicalSrcAddr = (CONST_APTR)IfslDMA->DMAAllocPhysicalMemoryTags(lTestSize,
FSLDMA_APM_ClearWithValue, 0xB3,
TAG_END);
if ( NULL != pPhysicalSrcAddr )
{
// Allocate the Destination Buffer (for DMA)
// - contents will by cleared by default
pPhysicalDestAddr = IfslDMA->DMAAllocPhysicalMemory(lTestSize);
if ( NULL != pPhysicalDestAddr )
{
// Call IfslDMA->DMAPhysicalCopyMem()
// to perform the memory copy using the DMA hardware
if ( TRUE == IfslDMA->DMAPhysicalCopyMem(pPhysicalSrcAddr,
pPhysicalDestAddr,lTestSize) )
{
// Success - Do something with the copied data
}
else
{
// Fallback and use CPU Copy instead (or do something else)
// Since we allocated the memory buffers using the FslDMA API,
// which returns the Physical address to that memory, and the
// IExec->CopyMemQuick() function expects the Virtual address,
// we first need to obtain the Virtual address for the Physical
// ones (using the FslDMA API again) before we can call our
// fallback copy function.
CONST_APTR pVirtualSrcAddr = NULL;
APTR pVirtualDestAddr = NULL;
pVirtualSrcAddr = IfslDMA->DMAGetVirtualAddress((APTR)pPhysicalSrcAddr);
pVirtualDestAddr = IfslDMA->DMAGetVirtualAddress(pPhysicalDestAddr);
IExec->CopyMemQuick(pVirtualSrcAddr,pVirtualDestAddr,lTestSize);
}
// We *must* use DMAFreePhysicalMemory() to free the memory
// that we allocated with DMAAllocPhysicalMemory()
IfslDMA->DMAFreePhysicalMemory(pPhysicalDestAddr);
}
// We *must* use DMAFreePhysicalMemory() to free the memory
// that we allocated with DMAAllocPhysicalMemory()
IfslDMA->DMAFreePhysicalMemory((APTR)pPhysicalSrcAddr);
}
}
</syntaxhighlight>

==== Obtaining the fsldma.resource ====

Breaking the above example down the first thing we do is include the interface header for the fsldma.resource and obtain the resource itself.

<syntaxhighlight>
#include <interfaces/fsldma.h>
struct fslDMAIFace *IfslDMA = IExec->OpenResource(FSLDMA_NAME);
</syntaxhighlight>

==== Allocating DMA Compliant Memory ====

Once we have successfully obtained the DMA resource we can directly use its API. The next step we need to do is to allocate some memory '''which we know is DMA compliant''' for use by the resource. The easiest way to accomplish this is to use the IfslDMA->DMAAllocPhysicalMemory() function. This will automatically take care of ensuring the memory that is returned is properly aligned, contiguous, cache-inhibited and coherent.

We use the Tags version of the allocate memory function first so we can allocate a block of memory for our source buffer and fill it with some test value (in this case the byte value 0xB3).

<syntaxhighlight>
pPhysicalSrcAddr = (CONST_APTR)IfslDMA->DMAAllocPhysicalMemoryTags(lTestSize,
FSLDMA_APM_ClearWithValue, 0xB3,
TAG_END);
</syntaxhighlight>

We also need a destination buffer for our test. Since it only needs to start out being cleared (filled with zeroes), we can use the simplest form of the allocate memory function here as the allocated memory is cleared by default.

<syntaxhighlight>
pPhysicalDestAddr = IfslDMA->DMAAllocPhysicalMemory(lTestSize);
</syntaxhighlight>

==== The core function - Copy Physical Memory ====

Now that we have two DMA Compliant memory buffers available we can get to the heart of the API usage and make the call to IfslDMA->DMAPhysicalCopyMem().

<syntaxhighlight>
IfslDMA->DMAPhysicalCopyMem(pPhysicalSrcAddr,pPhysicalDestAddr,lTestSize);
</syntaxhighlight>

Looking at the full [[#Example usage|Example]] source above you can see that the DMAPhysicalCopyMem() call returns a Boolean value to indicate success or failure. Therefore, TRUE will be returned after the DMA hardware had completed copying the requested data (blocking call) and FALSE will be returned if a problem occurred.

Since the memory buffers we are using were allocated using the FslDMA API and our transfer size was greater than zero and less than or equal to the total size of either buffer, (in others words a legal copy request), there is '''very''' little chance that the DMAPhysicalCopyMem() function will fail. In fact, about the only reason the DMA hardware would fail to handle a legal transaction would be if the physical RAM installed in the system was faulty.

So even though it is extremely unlikely for our DMA copy to have failed and returned FALSE, let's take a look at how we might handle the failure. In other words, falling back and using a CPU based copy function instead to complete the data move.

Since we are reverting back to using a normal system copy memory function here, we first need to obtain the ''Virtual Addresses'' to both our source and destination buffers. This is accomplished by using the DMAGetVirtualAddress() function and passing in the Physical Address that was returned by DMAAllocPhysicalMemory().

<syntaxhighlight>
CONST_APTR pVirtualSrcAddr = NULL;
APTR pVirtualDestAddr = NULL;
pVirtualSrcAddr = IfslDMA->DMAGetVirtualAddress((APTR)pPhysicalSrcAddr);
pVirtualDestAddr = IfslDMA->DMAGetVirtualAddress(pPhysicalDestAddr);
</syntaxhighlight>

Now that we have the Virtual Address equivalents to the Physical Addresses that were returned by DMAAllocPhysicalMemory(), we can proceed to call the Exec CopyMemQuick() function to complete the copy. Here we can only trust that the IExec->CopyMemQuick() call can not fail since it does not return a result code.

<syntaxhighlight>
IExec->CopyMemQuick(pVirtualSrcAddr,pVirtualDestAddr,lTestSize);
</syntaxhighlight>

==== Cleaning up - Freeing DMA Compliant memory ====

It is essential that you free any memory that was allocated using the DMAAllocPhysicalMemory() function using the corresponding DMAFreePhysicalMemory() call. The reason for this is two-fold; first because additional resource tracking is maintained by the FslDMA API whenever it allocates memory which must itself be released, and second because the ''Physical Address'' to the memory is returned by the allocate call and not the ''Virtual Address'', so if you attempt to pass the address returned by DMAAllocPhysicalMemory() directly into IExec->FreeVec() it would likely result in a crash.

<syntaxhighlight>
IfslDMA->DMAFreePhysicalMemory(pPhysicalSrcAddr);
IfslDMA->DMAFreePhysicalMemory(pPhysicalDestAddr);
</syntaxhighlight>

== Performance ==

Testing DMA memory copies vs their CPU based equivalent indicates that the DMA hardware on all three models (X5000/20, X5000/40 and A1222)
move data approximately two to three times faster than the CPU does so alone.

It should also be noted that these tests were performed when the CPU was effectively idle. CPU memory copy operations scale down roughly
equal with the CPU actively scaling up. So the more the CPU is doing, the longer it takes to complete the memory copy.

Conversely, DMA memory copy operation times are far more predictable as they use the same amount of (minimal) CPU overhead for each copy,
and the actual time it takes the DMA hardware to complete the transaction can be calculated to range from all the DMA Channels being idle,
to all DMA Channels being busy at once and data moves arbitrating between channels every 1024 bytes.

=== Optimal use of the DMA Engine ===

To gain the best performance from the DMA Engines, block sizes of 256 bytes or more should be used.
Also, if possible the size should be an even multiple of at least 4 bytes.

Additionally the memory blocks (source and destination) should be aligned to start on a 64 Byte boundary.
Alignment requirements are one of items taken care of for you by the DMAAllocPhysicalMemory() function.

The DMA Engine can and does handle misaligned and odd sized data blocks by first shifting the minimum
required bytes to correct the alignment, then taking smaller chunks of data until the largest chunk of
the block can be moved. It can also handle copies of as little as one byte (don't do this).

However, this does degrade performance.

In general, the larger the data block the better.

DMA Resource

2019-11-20T16:30:15Z

Jamie Krueger:

== DMA Engine ==

Some hardware targets include a DMA engine which can be used for general purpose copying. This article describes the DMA engines available and how to use them.

=== Hardware Features ===

The Direct Memory Access (DMA) Engines found in the NXP/Freescale p5020, p5040 and p1022 System On a Chip (SoC)s, as found in the AmigaONE X5000/20, X5000/40 and A1222 respectively, are quite flexible and powerful. Each of these chips contains two distinct engines with four data channels each. This provides the ability to have a total of eight DMA Channels working at once, with up to two DMA transactions actually being executed at the same time (one on each of the two DMA Engines).

Further, each of the four DMA Channels found in a DMA Engine may be individually programmed to handle either; a single transaction, a ''Chain'' of transactions, or even ''Lists'' of ''Chains'' of transactions. The DMA Engines automatically arbitrate control between each DMA Channel following programmed bandwidth settings for each Channel (typically 1024 bytes).

This means that after completing a transfer of 1024 bytes (for example), the hardware will consider switching to the next Channel to allow it to move another block of data, and so on in a round-robin fashion. If all other DMA Channels on a given DMA Engine are idle when arbitration would take place, the hardware will not arbitrate control to another Channel, but simply continue processing the transaction(s) for the Channel it is on.

=== DMA Copy Memory - Execution Flow Diagram ===

[[File:DMACopyMem-Diagram.png]]

=== What a call to perform a DMA copy does internally ===

As shown in the above diagram, when the user makes a call to request a memory copy be performed by the DMA hardware, the next available DMA Channel is selected for use and a DMA Transaction (source, destination and size) is constructed. The DMA Transaction is then programmed into the DMA Engine which owns the available DMA Channel.

At this point the calling task will Wait() until it hears the transaction has been completed. It will then return to the caller with the result. This provides a basic ''blocking'' function, which only returns to the caller once that data has been copied. This single tasking behavior is the simplest to use and what is normally expected by most applications using a memory copy function.

=== Diagram of multitasking DMA Copies ===

[[File:DMACopyMem-Multitasking-Diagram.png]]

=== How multiple simultaneous DMA copies are handled ===

When multiple user calls requesting a DMA copy arrive at once, each one is handed to a dedicated DMA Channel handling task for processing. As the diagram above demonstrates, there are two separate DMA Engines available, each with four channels that may be programmed at the same time. The hardware will then arbitrate the actual data move across these channels according to their respective bandwidth settings (usually 1024 bytes).

In the diagram above, a separate color indicates a distinct data path from the caller through the DMA hardware to the system RAM. A dashed line of the matching color indicates an Interrupt line signaling the respective DMA Channel Handler with the completion of the transaction. The handler task then signals back to the original caller, which returns to the user with a success or failure result.

All eight DMA Channels can handle each a single block transaction or an entire chain of block transactions before it signals completion and returns to the original caller. If all eight DMA Channels are busy processing their requested transactions when further DMA copy requests arrive, they will each be assigned a DMA Channel to wait on (managed via a Mutex lock on each Channel) and will block until allowed to add their DMA transaction to the Channel's queue.

== fsldma.resource ==

The fsldma.resource API is provided automatically in the kernel for all supported machines (Currently the AmigaONE X5000/20, X5000/40 and A1222).

=== The FslDMA API ===

The API provided by the fsldma.resource breaks down into three main parts:
:* Memory management
:* Copy Memory functions
:* Utility / Miscellaneous

==== Memory Management Functions ====

The FslDMA resource API provides convenience functions for the allocation and freeing of '''DMA Compliant''' blocks of memory. Two functions are provided for this purpose; DMAAllocPhysicalMemory() and DMAFreePhysicalMemory().

The memory allocation function also includes two Tags based versions of the call to allow for addition variables to be passed into the call using a variable set of Tags or fixed TagList. Currently the only supported Tag is ''FSLDMA_APM_ClearWithValue'', which is the equivalent to the IExec->AllocVecTagList() function's AVT_ClearWithValue tag. If the FSLDMA_APM_ClearWithValue tag is not provided then the requested memory block is cleared with zeroes by default before being returned. DMAAllocPhysicalMemory() returns the ''Physical'' Address pointer to the allocated memory or NULL if it is unable to allocate the requested memory.

<syntaxhighlight>
APTR DMAAllocPhysicalMemoryTagList( uint32 lSize, const struct TagItem *tags );
APTR DMAAllocPhysicalMemoryTags( uint32 lSize, uint32 Tag1, ... );
APTR DMAAllocPhysicalMemory( uint32 lSize );
</syntaxhighlight>

The corresponding function to allocating a DMA Compliant memory block is DMAFreePhysicalMemory(). Any memory allocated using DMAAllocPhysicalMemory() must be eventually freed using DMAFreePhysicalMemory().

<syntaxhighlight>
void DMAFreePhysicalMemory( APTR pPhysicalMemoryBlock );
</syntaxhighlight>

==== Copy Memory Functions ====

Two API calls make up the core of the FslDMA API; DMAPhysicalCopyMem() and DMACopyMem().
Both of these calls will "block" (not return to the user) until after the requested transfer has either succeeded or failed. A value of TRUE is returned upon success and FALSE if an error occurred.

<syntaxhighlight>
BOOL DMAPhysicalCopyMem( CONST_APTR pPhysicalSourceBuffer, APTR pPhysicalDestBuffer, uint32 lBufferSize );
BOOL DMACopyMem( CONST_APTR pSourceBuffer, APTR pDestBuffer, uint32 lBufferSize );
</syntaxhighlight>

As the name implies the first (and core version) of the copy memory functions, DMAPhysicalCopyMem(), accepts the Physical Addresses to the source and destination buffers (as returned by DMAAllocPhysicalMemory()), along with an unsigned 32-Bit value for the amount of bytes that should be copied (lBuffsize must be greater than zero(0) and no more than the maximum size of the source and destination buffers).

DMAPhysicalCopyMem() is the most direct an efficient means of using the DMA hardware to effect a single memory copy. The DMACopyMem() function is provided as an alternative way to request a DMA transfer by passing in the ''Virtual Addresses'' to the source and destination buffers instead of the Physical Addresses. DMACopyMem() will attempt to determine if the supplied memory buffers are DMA Compliant and if so it will internally use DMAPhysicalCopyMem() to handle the transaction. If DMACopyMem() determines that the supplied memory is '''not''' DMA Compliant it will return FALSE and no data copy will occur.

In theory any ''contiguous'' block of memory from 1 Byte up to 4GB in size may be transferred using either one of these calls. In practice the DMA hardware can directly accept memory blocks up to FSLDMA_MAXBLOCK_SIZE (or 64MB - 1 Byte). Therefore any data blocks greater than FSLDMA_MAXBLOCK_SIZE will automatically be feed to the DMA hardware in a series of smaller chunks. For maximum efficiency transfer sizes should be at least 256 Bytes in size and be an even multiple of 64 Bytes. Odd sizes are handled by the hardware but will degrade performance.

If you are transferring many large blocks of data in series and wish to manually send them to the FslDMA API's memory copy functions one block at a time, then setting your block sizes to FSLDMA_OPTIMAL_BLKSIZE (or 64 MB - 64 Bytes) and exclusively using DMAPhysicalCopyMem() will provide the fastest transfer speeds will the least amount of CPU overhead.

==== Utility / Miscellaneous Functions ====

The last section to the FslDMA API provides a single convenience function call; DMAGetVirtualAddress().

<syntaxhighlight>
APTR DMAGetVirtualAddress( APTR pPhysicalAddress );
</syntaxhighlight>

The DMAGetVirtualAddress() function returns the Virtual memory location for the Physical memory location that was itself allocated and returned by the DMAAllocPhysicalMemory() function. DMAGetVirtualAddress() will not work on physical addresses returned by IMMU->GetPhysicalAddress() on memory not allocated using DMAAllocPhysicalMemory().

The main purpose of this function (other then debugging purposes) is to provide the "normal" Virtual Address of memory allocated by the FslDMA API for use by functions that expect "normal" Virtual address locations; for example IExec->CopyMemQuick().

==== Further reference - The fsldma.resource AutoDoc ====

See the [[http://wiki.amigaos.net/amiga/autodocs/fsldmares.doc.txt fsldma.resource AutoDoc]] file for more details on each API call.

=== Example usage ===
<syntaxhighlight>
#include <interfaces/fsldma.h>
// Obtain the fsldma.resource
struct fslDMAIFace *IfslDMA = IExec->OpenResource(FSLDMA_NAME);
if ( NULL != IfslDMA )
{
uint32 lTestSize = 1024;
CONST_APTR pPhysicalSrcAddr = NULL;
APTR pPhysicalDestAddr = NULL;
// Allocate the Source Buffer (for DMA)
// and set the contents to 0xB3 (just an example value)
pPhysicalSrcAddr = (CONST_APTR)IfslDMA->DMAAllocPhysicalMemoryTags(lTestSize,
FSLDMA_APM_ClearWithValue, 0xB3,
TAG_END);
if ( NULL != pPhysicalSrcAddr )
{
// Allocate the Destination Buffer (for DMA)
// - contents will by cleared by default
pPhysicalDestAddr = IfslDMA->DMAAllocPhysicalMemory(lTestSize);
if ( NULL != pPhysicalDestAddr )
{
// Call IfslDMA->DMAPhysicalCopyMem()
// to perform the memory copy using the DMA hardware
if ( TRUE == IfslDMA->DMAPhysicalCopyMem(pPhysicalSrcAddr,
pPhysicalDestAddr,lTestSize) )
{
// Success - Do something with the copied data
}
else
{
// Fallback and use CPU Copy instead (or do something else)
// Since we allocated the memory buffers using the FslDMA API,
// which returns the Physical address to that memory, and the
// IExec->CopyMemQuick() function expects the Virtual address,
// we first need to obtain the Virtual address for the Physical
// ones (using the FslDMA API again) before we can call our
// fallback copy function.
CONST_APTR pVirtualSrcAddr = NULL;
APTR pVirtualDestAddr = NULL;
pVirtualSrcAddr = IfslDMA->DMAGetVirtualAddress((APTR)pPhysicalSrcAddr);
pVirtualDestAddr = IfslDMA->DMAGetVirtualAddress(pPhysicalDestAddr);
IExec->CopyMemQuick(pVirtualSrcAddr,pVirtualDestAddr,lTestSize);
}
// We *must* use DMAFreePhysicalMemory() to free the memory
// that we allocated with DMAAllocPhysicalMemory()
IfslDMA->DMAFreePhysicalMemory(pPhysicalDestAddr);
}
// We *must* use DMAFreePhysicalMemory() to free the memory
// that we allocated with DMAAllocPhysicalMemory()
IfslDMA->DMAFreePhysicalMemory((APTR)pPhysicalSrcAddr);
}
}
</syntaxhighlight>

==== Obtaining the fsldma.resource ====

Breaking the above example down the first thing we do is include the interface header for the fsldma.resource and obtain the resource itself.

<syntaxhighlight>
#include <interfaces/fsldma.h>
struct fslDMAIFace *IfslDMA = IExec->OpenResource(FSLDMA_NAME);
</syntaxhighlight>

==== Allocating DMA Compliant Memory ====

Once we have successfully obtained the DMA resource we can directly use its API. The next step we need to do is to allocate some memory '''which we know is DMA compliant''' for use by the resource. The easiest way to accomplish this is to use the IfslDMA->DMAAllocPhysicalMemory() function. This will automatically take care of ensuring the memory that is returned is properly aligned, contiguous, cache-inhibited and coherent.

We use the Tags version of the allocate memory function first so we can allocate a block of memory for our source buffer and fill it with some test value (in this case the byte value 0xB3).

<syntaxhighlight>
pPhysicalSrcAddr = (CONST_APTR)IfslDMA->DMAAllocPhysicalMemoryTags(lTestSize,
FSLDMA_APM_ClearWithValue, 0xB3,
TAG_END);
</syntaxhighlight>

We also need a destination buffer for our test. Since it only needs to start out being cleared (filled with zeroes), we can use the simplest form of the allocate memory function here as the allocated memory is cleared by default.

<syntaxhighlight>
pPhysicalDestAddr = IfslDMA->DMAAllocPhysicalMemory(lTestSize);
</syntaxhighlight>

==== The core function - Copy Physical Memory ====

Now that we have two DMA Compliant memory buffers available we can get to the heart of the API usage and make the call to IfslDMA->DMAPhysicalCopyMem().

<syntaxhighlight>
IfslDMA->DMAPhysicalCopyMem(pPhysicalSrcAddr,pPhysicalDestAddr,lTestSize);
</syntaxhighlight>

Looking at the full [[#Example usage|Example]] source above you can see that the DMAPhysicalCopyMem() call returns a Boolean value to indicate success or failure. Therefore, TRUE will be returned after the DMA hardware had completed copying the requested data (blocking call) and FALSE will be returned if a problem occurred.

Since the memory buffers we are using were allocated using the FslDMA API and our transfer size was greater than zero and less than or equal to the total size of either buffer, (in others words a legal copy request), there is '''very''' little chance that the DMAPhysicalCopyMem() function will fail. In fact, about the only reason the DMA hardware would fail to handle a legal transaction would be if the physical RAM installed in the system was faulty.

So even though it is extremely unlikely for our DMA copy to have failed and returned FALSE, let's take a look at how we might handle the failure. In other words, falling back and using a CPU based copy function instead to complete the data move.

Since we are reverting back to using a normal system copy memory function here, we first need to obtain the ''Virtual Addresses'' to both our source and destination buffers. This is accomplished by using the DMAGetVirtualAddress() function and passing in the Physical Address that was returned by DMAAllocPhysicalMemory().

<syntaxhighlight>
CONST_APTR pVirtualSrcAddr = NULL;
APTR pVirtualDestAddr = NULL;
pVirtualSrcAddr = IfslDMA->DMAGetVirtualAddress((APTR)pPhysicalSrcAddr);
pVirtualDestAddr = IfslDMA->DMAGetVirtualAddress(pPhysicalDestAddr);
</syntaxhighlight>

Now that we have the Virtual Address equivalents to the Physical Addresses that were returned by DMAAllocPhysicalMemory(), we can proceed to call the Exec CopyMemQuick() function to complete the copy. Here we can only trust that the IExec->CopyMemQuick() call can not fail since it does not return a result code.

<syntaxhighlight>
IExec->CopyMemQuick(pVirtualSrcAddr,pVirtualDestAddr,lTestSize);
</syntaxhighlight>

==== Cleaning up - Freeing DMA Compliant memory ====

It is essential that you free any memory that was allocated using the DMAAllocPhysicalMemory() function using the corresponding DMAFreePhysicalMemory() call. The reason for this is two-fold; first because additional resource tracking is maintained by the FslDMA API whenever it allocates memory which must itself be released, and second because the ''Physical Address'' to the memory is returned by the allocate call and not the ''Virtual Address'', so if you attempt to pass the address returned by DMAAllocPhysicalMemory() directly into IExec->FreeVec() it would likely result in a crash.

<syntaxhighlight>
IfslDMA->DMAFreePhysicalMemory(pPhysicalSrcAddr);
IfslDMA->DMAFreePhysicalMemory(pPhysicalDestAddr);
</syntaxhighlight>

== Performance ==

Testing DMA memory copies vs their CPU based equivalent indicates that the DMA hardware on all three models (X5000/20, X5000/40 and A1222) move data approximately two to three times faster than the CPU does so alone.

It should also be noted that these tests were performed when the CPU was effectively idle. CPU memory copy operations scale down roughly equal with the CPU actively scaling up. So the more the CPU is doing, the longer it takes to complete the memory copy.

Conversely, DMA memory copy operation times are far more predictable as they use the same amount of (minimal) CPU overhead for each copy, and the actual time it takes the DMA hardware to complete the transaction can be calculated to range from all the DMA Channels being idle, to all DMA Channels being busy at once and data moves arbitrating between channels every 1024 bytes.

=== Optimal use of the DMA Engine ===

To gain the best performance from the DMA Engines, block sizes of 256 bytes or more should be used.
Also, if possible the size should be an even multiple of at least 4 bytes.

Additionally the memory blocks (source and destination) should be aligned to start on a 64 Byte boundary.
Alignment requirements are one of items taken care of for you by the DMAAllocPhysicalMemory() function.

The DMA Engine can and does handle misaligned and odd sized data blocks by first shifting the minimum
required bytes to correct the alignment, then taking smaller chunks of data until the largest chunk of
the block can be moved. It can also handle copies of as little as one byte (don't do this).

However, this does degrade performance.

In general, the larger the data block the better.

DMA Resource

2019-11-20T16:29:43Z

Jamie Krueger: /* When to use the DMA Engine */

== DMA Engine ==

Some hardware targets include a DMA engine which can be used for general purpose copying. This article describes the DMA engines available and how to use them.

=== Hardware Features ===

The Direct Memory Access (DMA) Engines found in the NXP/Freescale p5020, p5040 and p1022 System On a Chip (SoC)s, as found in the AmigaONE X5000/20, X5000/40 and A1222 respectively, are quite flexible and powerful. Each of these chips contains two distinct engines with four data channels each. This provides the ability to have a total of eight DMA Channels working at once, with up to two DMA transactions actually being executed at the same time (one on each of the two DMA Engines).

Further, each of the four DMA Channels found in a DMA Engine may be individually programmed to handle either; a single transaction, a ''Chain'' of transactions, or even ''Lists'' of ''Chains'' of transactions. The DMA Engines automatically arbitrate control between each DMA Channel following programmed bandwidth settings for each Channel (typically 1024 bytes).

This means that after completing a transfer of 1024 bytes (for example), the hardware will consider switching to the next Channel to allow it to move another block of data, and so on in a round-robin fashion. If all other DMA Channels on a given DMA Engine are idle when arbitration would take place, the hardware will not arbitrate control to another Channel, but simply continue processing the transaction(s) for the Channel it is on.

=== DMA Copy Memory - Execution Flow Diagram ===

[[File:DMACopyMem-Diagram.png]]

=== What a call to perform a DMA copy does internally ===

As shown in the above diagram, when the user makes a call to request a memory copy be performed by the DMA hardware, the next available DMA Channel is selected for use and a DMA Transaction (source, destination and size) is constructed. The DMA Transaction is then programmed into the DMA Engine which owns the available DMA Channel.

At this point the calling task will Wait() until it hears the transaction has been completed. It will then return to the caller with the result. This provides a basic ''blocking'' function, which only returns to the caller once that data has been copied. This single tasking behavior is the simplest to use and what is normally expected by most applications using a memory copy function.

=== Diagram of multitasking DMA Copies ===

[[File:DMACopyMem-Multitasking-Diagram.png]]

=== How multiple simultaneous DMA copies are handled ===

When multiple user calls requesting a DMA copy arrive at once, each one is handed to a dedicated DMA Channel handling task for processing. As the diagram above demonstrates, there are two separate DMA Engines available, each with four channels that may be programmed at the same time. The hardware will then arbitrate the actual data move across these channels according to their respective bandwidth settings (usually 1024 bytes).

In the diagram above, a separate color indicates a distinct data path from the caller through the DMA hardware to the system RAM. A dashed line of the matching color indicates an Interrupt line signaling the respective DMA Channel Handler with the completion of the transaction. The handler task then signals back to the original caller, which returns to the user with a success or failure result.

All eight DMA Channels can handle each a single block transaction or an entire chain of block transactions before it signals completion and returns to the original caller. If all eight DMA Channels are busy processing their requested transactions when further DMA copy requests arrive, they will each be assigned a DMA Channel to wait on (managed via a Mutex lock on each Channel) and will block until allowed to add their DMA transaction to the Channel's queue.

== fsldma.resource ==

The fsldma.resource API is provided automatically in the kernel for all supported machines (Currently the AmigaONE X5000/20, X5000/40 and A1222).

=== The FslDMA API ===

The API provided by the fsldma.resource breaks down into three main parts:
:* Memory management
:* Copy Memory functions
:* Utility / Miscellaneous

==== Memory Management Functions ====

The FslDMA resource API provides convenience functions for the allocation and freeing of '''DMA Compliant''' blocks of memory. Two functions are provided for this purpose; DMAAllocPhysicalMemory() and DMAFreePhysicalMemory().

The memory allocation function also includes two Tags based versions of the call to allow for addition variables to be passed into the call using a variable set of Tags or fixed TagList. Currently the only supported Tag is ''FSLDMA_APM_ClearWithValue'', which is the equivalent to the IExec->AllocVecTagList() function's AVT_ClearWithValue tag. If the FSLDMA_APM_ClearWithValue tag is not provided then the requested memory block is cleared with zeroes by default before being returned. DMAAllocPhysicalMemory() returns the ''Physical'' Address pointer to the allocated memory or NULL if it is unable to allocate the requested memory.

<syntaxhighlight>
APTR DMAAllocPhysicalMemoryTagList( uint32 lSize, const struct TagItem *tags );
APTR DMAAllocPhysicalMemoryTags( uint32 lSize, uint32 Tag1, ... );
APTR DMAAllocPhysicalMemory( uint32 lSize );
</syntaxhighlight>

The corresponding function to allocating a DMA Compliant memory block is DMAFreePhysicalMemory(). Any memory allocated using DMAAllocPhysicalMemory() must be eventually freed using DMAFreePhysicalMemory().

<syntaxhighlight>
void DMAFreePhysicalMemory( APTR pPhysicalMemoryBlock );
</syntaxhighlight>

==== Copy Memory Functions ====

Two API calls make up the core of the FslDMA API; DMAPhysicalCopyMem() and DMACopyMem().
Both of these calls will "block" (not return to the user) until after the requested transfer has either succeeded or failed. A value of TRUE is returned upon success and FALSE if an error occurred.

<syntaxhighlight>
BOOL DMAPhysicalCopyMem( CONST_APTR pPhysicalSourceBuffer, APTR pPhysicalDestBuffer, uint32 lBufferSize );
BOOL DMACopyMem( CONST_APTR pSourceBuffer, APTR pDestBuffer, uint32 lBufferSize );
</syntaxhighlight>

As the name implies the first (and core version) of the copy memory functions, DMAPhysicalCopyMem(), accepts the Physical Addresses to the source and destination buffers (as returned by DMAAllocPhysicalMemory()), along with an unsigned 32-Bit value for the amount of bytes that should be copied (lBuffsize must be greater than zero(0) and no more than the maximum size of the source and destination buffers).

DMAPhysicalCopyMem() is the most direct an efficient means of using the DMA hardware to effect a single memory copy. The DMACopyMem() function is provided as an alternative way to request a DMA transfer by passing in the ''Virtual Addresses'' to the source and destination buffers instead of the Physical Addresses. DMACopyMem() will attempt to determine if the supplied memory buffers are DMA Compliant and if so it will internally use DMAPhysicalCopyMem() to handle the transaction. If DMACopyMem() determines that the supplied memory is '''not''' DMA Compliant it will return FALSE and no data copy will occur.

In theory any ''contiguous'' block of memory from 1 Byte up to 4GB in size may be transferred using either one of these calls. In practice the DMA hardware can directly accept memory blocks up to FSLDMA_MAXBLOCK_SIZE (or 64MB - 1 Byte). Therefore any data blocks greater than FSLDMA_MAXBLOCK_SIZE will automatically be feed to the DMA hardware in a series of smaller chunks. For maximum efficiency transfer sizes should be at least 256 Bytes in size and be an even multiple of 64 Bytes. Odd sizes are handled by the hardware but will degrade performance.

If you are transferring many large blocks of data in series and wish to manually send them to the FslDMA API's memory copy functions one block at a time, then setting your block sizes to FSLDMA_OPTIMAL_BLKSIZE (or 64 MB - 64 Bytes) and exclusively using DMAPhysicalCopyMem() will provide the fastest transfer speeds will the least amount of CPU overhead.

==== Utility / Miscellaneous Functions ====

The last section to the FslDMA API provides a single convenience function call; DMAGetVirtualAddress().

<syntaxhighlight>
APTR DMAGetVirtualAddress( APTR pPhysicalAddress );
</syntaxhighlight>

The DMAGetVirtualAddress() function returns the Virtual memory location for the Physical memory location that was itself allocated and returned by the DMAAllocPhysicalMemory() function. DMAGetVirtualAddress() will not work on physical addresses returned by IMMU->GetPhysicalAddress() on memory not allocated using DMAAllocPhysicalMemory().

The main purpose of this function (other then debugging purposes) is to provide the "normal" Virtual Address of memory allocated by the FslDMA API for use by functions that expect "normal" Virtual address locations; for example IExec->CopyMemQuick().

==== Further reference - The fsldma.resource AutoDoc ====

See the [[http://wiki.amigaos.net/amiga/autodocs/fsldmares.doc.txt fsldma.resource AutoDoc]] file for more details on each API call.

=== Example usage ===
<syntaxhighlight>
#include <interfaces/fsldma.h>
// Obtain the fsldma.resource
struct fslDMAIFace *IfslDMA = IExec->OpenResource(FSLDMA_NAME);
if ( NULL != IfslDMA )
{
uint32 lTestSize = 1024;
CONST_APTR pPhysicalSrcAddr = NULL;
APTR pPhysicalDestAddr = NULL;
// Allocate the Source Buffer (for DMA)
// and set the contents to 0xB3 (just an example value)
pPhysicalSrcAddr = (CONST_APTR)IfslDMA->DMAAllocPhysicalMemoryTags(lTestSize,
FSLDMA_APM_ClearWithValue, 0xB3,
TAG_END);
if ( NULL != pPhysicalSrcAddr )
{
// Allocate the Destination Buffer (for DMA)
// - contents will by cleared by default
pPhysicalDestAddr = IfslDMA->DMAAllocPhysicalMemory(lTestSize);
if ( NULL != pPhysicalDestAddr )
{
// Call IfslDMA->DMAPhysicalCopyMem()
// to perform the memory copy using the DMA hardware
if ( TRUE == IfslDMA->DMAPhysicalCopyMem(pPhysicalSrcAddr,
pPhysicalDestAddr,lTestSize) )
{
// Success - Do something with the copied data
}
else
{
// Fallback and use CPU Copy instead (or do something else)
// Since we allocated the memory buffers using the FslDMA API,
// which returns the Physical address to that memory, and the
// IExec->CopyMemQuick() function expects the Virtual address,
// we first need to obtain the Virtual address for the Physical
// ones (using the FslDMA API again) before we can call our
// fallback copy function.
CONST_APTR pVirtualSrcAddr = NULL;
APTR pVirtualDestAddr = NULL;
pVirtualSrcAddr = IfslDMA->DMAGetVirtualAddress((APTR)pPhysicalSrcAddr);
pVirtualDestAddr = IfslDMA->DMAGetVirtualAddress(pPhysicalDestAddr);
IExec->CopyMemQuick(pVirtualSrcAddr,pVirtualDestAddr,lTestSize);
}
// We *must* use DMAFreePhysicalMemory() to free the memory
// that we allocated with DMAAllocPhysicalMemory()
IfslDMA->DMAFreePhysicalMemory(pPhysicalDestAddr);
}
// We *must* use DMAFreePhysicalMemory() to free the memory
// that we allocated with DMAAllocPhysicalMemory()
IfslDMA->DMAFreePhysicalMemory((APTR)pPhysicalSrcAddr);
}
}
</syntaxhighlight>

==== Obtaining the fsldma.resource ====

Breaking the above example down the first thing we do is include the interface header for the fsldma.resource and obtain the resource itself.

<syntaxhighlight>
#include <interfaces/fsldma.h>
struct fslDMAIFace *IfslDMA = IExec->OpenResource(FSLDMA_NAME);
</syntaxhighlight>

==== Allocating DMA Compliant Memory ====

Once we have successfully obtained the DMA resource we can directly use its API. The next step we need to do is to allocate some memory '''which we know is DMA compliant''' for use by the resource. The easiest way to accomplish this is to use the IfslDMA->DMAAllocPhysicalMemory() function. This will automatically take care of ensuring the memory that is returned is properly aligned, contiguous, cache-inhibited and coherent.

We use the Tags version of the allocate memory function first so we can allocate a block of memory for our source buffer and fill it with some test value (in this case the byte value 0xB3).

<syntaxhighlight>
pPhysicalSrcAddr = (CONST_APTR)IfslDMA->DMAAllocPhysicalMemoryTags(lTestSize,
FSLDMA_APM_ClearWithValue, 0xB3,
TAG_END);
</syntaxhighlight>

We also need a destination buffer for our test. Since it only needs to start out being cleared (filled with zeroes), we can use the simplest form of the allocate memory function here as the allocated memory is cleared by default.

<syntaxhighlight>
pPhysicalDestAddr = IfslDMA->DMAAllocPhysicalMemory(lTestSize);
</syntaxhighlight>

==== The core function - Copy Physical Memory ====

Now that we have two DMA Compliant memory buffers available we can get to the heart of the API usage and make the call to IfslDMA->DMAPhysicalCopyMem().

<syntaxhighlight>
IfslDMA->DMAPhysicalCopyMem(pPhysicalSrcAddr,pPhysicalDestAddr,lTestSize);
</syntaxhighlight>

Looking at the full [[#Example usage|Example]] source above you can see that the DMAPhysicalCopyMem() call returns a Boolean value to indicate success or failure. Therefore, TRUE will be returned after the DMA hardware had completed copying the requested data (blocking call) and FALSE will be returned if a problem occurred.

Since the memory buffers we are using were allocated using the FslDMA API and our transfer size was greater than zero and less than or equal to the total size of either buffer, (in others words a legal copy request), there is '''very''' little chance that the DMAPhysicalCopyMem() function will fail. In fact, about the only reason the DMA hardware would fail to handle a legal transaction would be if the physical RAM installed in the system was faulty.

So even though it is extremely unlikely for our DMA copy to have failed and returned FALSE, let's take a look at how we might handle the failure. In other words, falling back and using a CPU based copy function instead to complete the data move.

Since we are reverting back to using a normal system copy memory function here, we first need to obtain the ''Virtual Addresses'' to both our source and destination buffers. This is accomplished by using the DMAGetVirtualAddress() function and passing in the Physical Address that was returned by DMAAllocPhysicalMemory().

<syntaxhighlight>
CONST_APTR pVirtualSrcAddr = NULL;
APTR pVirtualDestAddr = NULL;
pVirtualSrcAddr = IfslDMA->DMAGetVirtualAddress((APTR)pPhysicalSrcAddr);
pVirtualDestAddr = IfslDMA->DMAGetVirtualAddress(pPhysicalDestAddr);
</syntaxhighlight>

Now that we have the Virtual Address equivalents to the Physical Addresses that were returned by DMAAllocPhysicalMemory(), we can proceed to call the Exec CopyMemQuick() function to complete the copy. Here we can only trust that the IExec->CopyMemQuick() call can not fail since it does not return a result code.

<syntaxhighlight>
IExec->CopyMemQuick(pVirtualSrcAddr,pVirtualDestAddr,lTestSize);
</syntaxhighlight>

==== Cleaning up - Freeing DMA Compliant memory ====

It is essential that you free any memory that was allocated using the DMAAllocPhysicalMemory() function using the corresponding DMAFreePhysicalMemory() call. The reason for this is two-fold; first because additional resource tracking is maintained by the FslDMA API whenever it allocates memory which must itself be released, and second because the ''Physical Address'' to the memory is returned by the allocate call and not the ''Virtual Address'', so if you attempt to pass the address returned by DMAAllocPhysicalMemory() directly into IExec->FreeVec() it would likely result in a crash.

<syntaxhighlight>
IfslDMA->DMAFreePhysicalMemory(pPhysicalSrcAddr);
IfslDMA->DMAFreePhysicalMemory(pPhysicalDestAddr);
</syntaxhighlight>

== Performance ==

Testing DMA memory copies vs their CPU based equivalent indicates that the DMA hardware on all three models (X5000/20, X5000/40 and A1222) move data approximately two to three times faster than the CPU does so alone.

It should also be noted that these tests were performed when the CPU was effectively idle. CPU memory copy operations scale down roughly equal with the CPU actively scaling up. So the more the CPU is doing, the longer it takes to complete the memory copy.

Conversely, DMA memory copy operation times are far more predictable as they use the same amount of (minimal) CPU overhead for each copy, and the actual time it takes the DMA hardware to complete the transaction can be calculated to range from all the DMA Channels being idle, to all DMA Channels being busy at once and data moves arbitrating between channels every 1024 bytes.

=== Optimal use of the DMA Engine ===

To gain the best performance from the DMA Engines, block sizes of 256 bytes or more should be used.
Also, if possible the size should be an even multiple of at least 4 bytes.

Additionally the memory blocks (source and destination) should be aligned to start on a 64 Byte boundary.
Alignment requirements are one of items taken care of for you by the DMAAllocPhysicalMemory() function.

The DMA Engine can and does handle misaligned and odd sized data blocks by first shifting the minimum
required bytes to correct the alignment, then taking smaller chunks of data until the largest chunk of
the block can be moved. It can also handle copies of as little as one byte (don't do this).

However, this does degrade performance.

In general, the larger the data block the better.

=== When not to use the DMA Engine ===

DMA Resource

2019-11-18T18:56:49Z

Jamie Krueger:

== DMA Engine ==

Some hardware targets include a DMA engine which can be used for general purpose copying. This article describes the DMA engines available and how to use them.

=== Hardware Features ===

The Direct Memory Access (DMA) Engines found in the NXP/Freescale p5020, p5040 and p1022 System On a Chip (SoC)s, as found in the AmigaONE X5000/20, X5000/40 and A1222 respectively, are quite flexible and powerful. Each of these chips contains two distinct engines with four data channels each. This provides the ability to have a total of eight DMA Channels working at once, with up to two DMA transactions actually being executed at the same time (one on each of the two DMA Engines).

Further, each of the four DMA Channels found in a DMA Engine may be individually programmed to handle either; a single transaction, a ''Chain'' of transactions, or even ''Lists'' of ''Chains'' of transactions. The DMA Engines automatically arbitrate control between each DMA Channel following programmed bandwidth settings for each Channel (typically 1024 bytes).

This means that after completing a transfer of 1024 bytes (for example), the hardware will consider switching to the next Channel to allow it to move another block of data, and so on in a round-robin fashion. If all other DMA Channels on a given DMA Engine are idle when arbitration would take place, the hardware will not arbitrate control to another Channel, but simply continue processing the transaction(s) for the Channel it is on.

=== DMA Copy Memory - Execution Flow Diagram ===

[[File:DMACopyMem-Diagram.png]]

=== What a call to perform a DMA copy does internally ===

As shown in the above diagram, when the user makes a call to request a memory copy be performed by the DMA hardware, the next available DMA Channel is selected for use and a DMA Transaction (source, destination and size) is constructed. The DMA Transaction is then programmed into the DMA Engine which owns the available DMA Channel.

At this point the calling task will Wait() until it hears the transaction has been completed. It will then return to the caller with the result. This provides a basic ''blocking'' function, which only returns to the caller once that data has been copied. This single tasking behavior is the simplest to use and what is normally expected by most applications using a memory copy function.

=== Diagram of multitasking DMA Copies ===

[[File:DMACopyMem-Multitasking-Diagram.png]]

=== How multiple simultaneous DMA copies are handled ===

When multiple user calls requesting a DMA copy arrive at once, each one is handed to a dedicated DMA Channel handling task for processing. As the diagram above demonstrates, there are two separate DMA Engines available, each with four channels that may be programmed at the same time. The hardware will then arbitrate the actual data move across these channels according to their respective bandwidth settings (usually 1024 bytes).

In the diagram above, a separate color indicates a distinct data path from the caller through the DMA hardware to the system RAM. A dashed line of the matching color indicates an Interrupt line signaling the respective DMA Channel Handler with the completion of the transaction. The handler task then signals back to the original caller, which returns to the user with a success or failure result.

All eight DMA Channels can handle each a single block transaction or an entire chain of block transactions before it signals completion and returns to the original caller. If all eight DMA Channels are busy processing their requested transactions when further DMA copy requests arrive, they will each be assigned a DMA Channel to wait on (managed via a Mutex lock on each Channel) and will block until allowed to add their DMA transaction to the Channel's queue.

== fsldma.resource ==

The fsldma.resource API is provided automatically in the kernel for all supported machines (Currently the AmigaONE X5000/20, X5000/40 and A1222).

=== The FslDMA API ===

The API provided by the fsldma.resource breaks down into three main parts:
:* Memory management
:* Copy Memory functions
:* Utility / Miscellaneous

==== Memory Management Functions ====

The FslDMA resource API provides convenience functions for the allocation and freeing of '''DMA Compliant''' blocks of memory. Two functions are provided for this purpose; DMAAllocPhysicalMemory() and DMAFreePhysicalMemory().

The memory allocation function also includes two Tags based versions of the call to allow for addition variables to be passed into the call using a variable set of Tags or fixed TagList. Currently the only supported Tag is ''FSLDMA_APM_ClearWithValue'', which is the equivalent to the IExec->AllocVecTagList() function's AVT_ClearWithValue tag. If the FSLDMA_APM_ClearWithValue tag is not provided then the requested memory block is cleared with zeroes by default before being returned. DMAAllocPhysicalMemory() returns the ''Physical'' Address pointer to the allocated memory or NULL if it is unable to allocate the requested memory.

<syntaxhighlight>
APTR DMAAllocPhysicalMemoryTagList( uint32 lSize, const struct TagItem *tags );
APTR DMAAllocPhysicalMemoryTags( uint32 lSize, uint32 Tag1, ... );
APTR DMAAllocPhysicalMemory( uint32 lSize );
</syntaxhighlight>

The corresponding function to allocating a DMA Compliant memory block is DMAFreePhysicalMemory(). Any memory allocated using DMAAllocPhysicalMemory() must be eventually freed using DMAFreePhysicalMemory().

<syntaxhighlight>
void DMAFreePhysicalMemory( APTR pPhysicalMemoryBlock );
</syntaxhighlight>

==== Copy Memory Functions ====

Two API calls make up the core of the FslDMA API; DMAPhysicalCopyMem() and DMACopyMem().
Both of these calls will "block" (not return to the user) until after the requested transfer has either succeeded or failed. A value of TRUE is returned upon success and FALSE if an error occurred.

<syntaxhighlight>
BOOL DMAPhysicalCopyMem( CONST_APTR pPhysicalSourceBuffer, APTR pPhysicalDestBuffer, uint32 lBufferSize );
BOOL DMACopyMem( CONST_APTR pSourceBuffer, APTR pDestBuffer, uint32 lBufferSize );
</syntaxhighlight>

As the name implies the first (and core version) of the copy memory functions, DMAPhysicalCopyMem(), accepts the Physical Addresses to the source and destination buffers (as returned by DMAAllocPhysicalMemory()), along with an unsigned 32-Bit value for the amount of bytes that should be copied (lBuffsize must be greater than zero(0) and no more than the maximum size of the source and destination buffers).

DMAPhysicalCopyMem() is the most direct an efficient means of using the DMA hardware to effect a single memory copy. The DMACopyMem() function is provided as an alternative way to request a DMA transfer by passing in the ''Virtual Addresses'' to the source and destination buffers instead of the Physical Addresses. DMACopyMem() will attempt to determine if the supplied memory buffers are DMA Compliant and if so it will internally use DMAPhysicalCopyMem() to handle the transaction. If DMACopyMem() determines that the supplied memory is '''not''' DMA Compliant it will return FALSE and no data copy will occur.

In theory any ''contiguous'' block of memory from 1 Byte up to 4GB in size may be transferred using either one of these calls. In practice the DMA hardware can directly accept memory blocks up to FSLDMA_MAXBLOCK_SIZE (or 64MB - 1 Byte). Therefore any data blocks greater than FSLDMA_MAXBLOCK_SIZE will automatically be feed to the DMA hardware in a series of smaller chunks. For maximum efficiency transfer sizes should be at least 256 Bytes in size and be an even multiple of 64 Bytes. Odd sizes are handled by the hardware but will degrade performance.

If you are transferring many large blocks of data in series and wish to manually send them to the FslDMA API's memory copy functions one block at a time, then setting your block sizes to FSLDMA_OPTIMAL_BLKSIZE (or 64 MB - 64 Bytes) and exclusively using DMAPhysicalCopyMem() will provide the fastest transfer speeds will the least amount of CPU overhead.

==== Utility / Miscellaneous Functions ====

The last section to the FslDMA API provides a single convenience function call; DMAGetVirtualAddress().

<syntaxhighlight>
APTR DMAGetVirtualAddress( APTR pPhysicalAddress );
</syntaxhighlight>

The DMAGetVirtualAddress() function returns the Virtual memory location for the Physical memory location that was itself allocated and returned by the DMAAllocPhysicalMemory() function. DMAGetVirtualAddress() will not work on physical addresses returned by IMMU->GetPhysicalAddress() on memory not allocated using DMAAllocPhysicalMemory().

The main purpose of this function (other then debugging purposes) is to provide the "normal" Virtual Address of memory allocated by the FslDMA API for use by functions that expect "normal" Virtual address locations; for example IExec->CopyMemQuick().

==== Further reference - The fsldma.resource AutoDoc ====

See the [[http://wiki.amigaos.net/amiga/autodocs/fsldmares.doc.txt fsldma.resource AutoDoc]] file for more details on each API call.

=== Example usage ===
<syntaxhighlight>
#include <interfaces/fsldma.h>
// Obtain the fsldma.resource
struct fslDMAIFace *IfslDMA = IExec->OpenResource(FSLDMA_NAME);
if ( NULL != IfslDMA )
{
uint32 lTestSize = 1024;
CONST_APTR pPhysicalSrcAddr = NULL;
APTR pPhysicalDestAddr = NULL;
// Allocate the Source Buffer (for DMA)
// and set the contents to 0xB3 (just an example value)
pPhysicalSrcAddr = (CONST_APTR)IfslDMA->DMAAllocPhysicalMemoryTags(lTestSize,
FSLDMA_APM_ClearWithValue, 0xB3,
TAG_END);
if ( NULL != pPhysicalSrcAddr )
{
// Allocate the Destination Buffer (for DMA)
// - contents will by cleared by default
pPhysicalDestAddr = IfslDMA->DMAAllocPhysicalMemory(lTestSize);
if ( NULL != pPhysicalDestAddr )
{
// Call IfslDMA->DMAPhysicalCopyMem()
// to perform the memory copy using the DMA hardware
if ( TRUE == IfslDMA->DMAPhysicalCopyMem(pPhysicalSrcAddr,
pPhysicalDestAddr,lTestSize) )
{
// Success - Do something with the copied data
}
else
{
// Fallback and use CPU Copy instead (or do something else)
// Since we allocated the memory buffers using the FslDMA API,
// which returns the Physical address to that memory, and the
// IExec->CopyMemQuick() function expects the Virtual address,
// we first need to obtain the Virtual address for the Physical
// ones (using the FslDMA API again) before we can call our
// fallback copy function.
CONST_APTR pVirtualSrcAddr = NULL;
APTR pVirtualDestAddr = NULL;
pVirtualSrcAddr = IfslDMA->DMAGetVirtualAddress((APTR)pPhysicalSrcAddr);
pVirtualDestAddr = IfslDMA->DMAGetVirtualAddress(pPhysicalDestAddr);
IExec->CopyMemQuick(pVirtualSrcAddr,pVirtualDestAddr,lTestSize);
}
// We *must* use DMAFreePhysicalMemory() to free the memory
// that we allocated with DMAAllocPhysicalMemory()
IfslDMA->DMAFreePhysicalMemory(pPhysicalDestAddr);
}
// We *must* use DMAFreePhysicalMemory() to free the memory
// that we allocated with DMAAllocPhysicalMemory()
IfslDMA->DMAFreePhysicalMemory((APTR)pPhysicalSrcAddr);
}
}
</syntaxhighlight>

==== Obtaining the fsldma.resource ====

Breaking the above example down the first thing we do is include the interface header for the fsldma.resource and obtain the resource itself.

<syntaxhighlight>
#include <interfaces/fsldma.h>
struct fslDMAIFace *IfslDMA = IExec->OpenResource(FSLDMA_NAME);
</syntaxhighlight>

==== Allocating DMA Compliant Memory ====

Once we have successfully obtained the DMA resource we can directly use its API. The next step we need to do is to allocate some memory '''which we know is DMA compliant''' for use by the resource. The easiest way to accomplish this is to use the IfslDMA->DMAAllocPhysicalMemory() function. This will automatically take care of ensuring the memory that is returned is properly aligned, contiguous, cache-inhibited and coherent.

We use the Tags version of the allocate memory function first so we can allocate a block of memory for our source buffer and fill it with some test value (in this case the byte value 0xB3).

<syntaxhighlight>
pPhysicalSrcAddr = (CONST_APTR)IfslDMA->DMAAllocPhysicalMemoryTags(lTestSize,
FSLDMA_APM_ClearWithValue, 0xB3,
TAG_END);
</syntaxhighlight>

We also need a destination buffer for our test. Since it only needs to start out being cleared (filled with zeroes), we can use the simplest form of the allocate memory function here as the allocated memory is cleared by default.

<syntaxhighlight>
pPhysicalDestAddr = IfslDMA->DMAAllocPhysicalMemory(lTestSize);
</syntaxhighlight>

==== The core function - Copy Physical Memory ====

Now that we have two DMA Compliant memory buffers available we can get to the heart of the API usage and make the call to IfslDMA->DMAPhysicalCopyMem().

<syntaxhighlight>
IfslDMA->DMAPhysicalCopyMem(pPhysicalSrcAddr,pPhysicalDestAddr,lTestSize);
</syntaxhighlight>

Looking at the full [[#Example usage|Example]] source above you can see that the DMAPhysicalCopyMem() call returns a Boolean value to indicate success or failure. Therefore, TRUE will be returned after the DMA hardware had completed copying the requested data (blocking call) and FALSE will be returned if a problem occurred.

Since the memory buffers we are using were allocated using the FslDMA API and our transfer size was greater than zero and less than or equal to the total size of either buffer, (in others words a legal copy request), there is '''very''' little chance that the DMAPhysicalCopyMem() function will fail. In fact, about the only reason the DMA hardware would fail to handle a legal transaction would be if the physical RAM installed in the system was faulty.

So even though it is extremely unlikely for our DMA copy to have failed and returned FALSE, let's take a look at how we might handle the failure. In other words, falling back and using a CPU based copy function instead to complete the data move.

Since we are reverting back to using a normal system copy memory function here, we first need to obtain the ''Virtual Addresses'' to both our source and destination buffers. This is accomplished by using the DMAGetVirtualAddress() function and passing in the Physical Address that was returned by DMAAllocPhysicalMemory().

<syntaxhighlight>
CONST_APTR pVirtualSrcAddr = NULL;
APTR pVirtualDestAddr = NULL;
pVirtualSrcAddr = IfslDMA->DMAGetVirtualAddress((APTR)pPhysicalSrcAddr);
pVirtualDestAddr = IfslDMA->DMAGetVirtualAddress(pPhysicalDestAddr);
</syntaxhighlight>

Now that we have the Virtual Address equivalents to the Physical Addresses that were returned by DMAAllocPhysicalMemory(), we can proceed to call the Exec CopyMemQuick() function to complete the copy. Here we can only trust that the IExec->CopyMemQuick() call can not fail since it does not return a result code.

<syntaxhighlight>
IExec->CopyMemQuick(pVirtualSrcAddr,pVirtualDestAddr,lTestSize);
</syntaxhighlight>

==== Cleaning up - Freeing DMA Compliant memory ====

It is essential that you free any memory that was allocated using the DMAAllocPhysicalMemory() function using the corresponding DMAFreePhysicalMemory() call. The reason for this is two-fold; first because additional resource tracking is maintained by the FslDMA API whenever it allocates memory which must itself be released, and second because the ''Physical Address'' to the memory is returned by the allocate call and not the ''Virtual Address'', so if you attempt to pass the address returned by DMAAllocPhysicalMemory() directly into IExec->FreeVec() it would likely result in a crash.

<syntaxhighlight>
IfslDMA->DMAFreePhysicalMemory(pPhysicalSrcAddr);
IfslDMA->DMAFreePhysicalMemory(pPhysicalDestAddr);
</syntaxhighlight>

== Performance ==

Testing DMA memory copies vs their CPU based equivalent indicates that the DMA hardware on all three models (X5000/20, X5000/40 and A1222) move data approximately two to three times faster than the CPU does so alone.

It should also be noted that these tests were performed when the CPU was effectively idle. CPU memory copy operations scale down roughly equal with the CPU actively scaling up. So the more the CPU is doing, the longer it takes to complete the memory copy.

Conversely, DMA memory copy operation times are far more predictable as they use the same amount of (minimal) CPU overhead for each copy, and the actual time it takes the DMA hardware to complete the transaction can be calculated to range from all the DMA Channels being idle, to all DMA Channels being busy at once and data moves arbitrating between channels every 1024 bytes.

=== When to use the DMA Engine ===

=== When not to use the DMA Engine ===

DMA Resource

2019-11-16T02:14:20Z

Jamie Krueger: /* How multiple simultaneous DMA copies are handled */

DMA Resource

2019-11-16T02:11:18Z

Jamie Krueger: /* How multiple simultaneous DMA copies are handled */

== DMA Engine ==

Some hardware targets include a DMA engine which can be used for general purpose copying. This article describes the DMA engines available and how to use them.

=== Hardware Features ===

The Direct Memory Access (DMA) Engines found in the NXP/Freescale p5020, p5040 and p1022 System On a Chip (SoC)s, as found in the AmigaONE X5000/20, X5000/40 and A1222 respectively, are quite flexible and powerful. Each of these chips contains two distinct engines with four data channels each. This provides the ability to have a total of eight DMA Channels working at once, with up to two DMA transactions actually being executed at the same time (one on each of the two DMA Engines).

Further, each of the four DMA Channels found in a DMA Engine may be individually programmed to handle either; a single transaction, a ''Chain'' of transactions, or even ''Lists'' of ''Chains'' of transactions. The DMA Engines automatically arbitrate control between each DMA Channel following programmed bandwidth settings for each Channel (typically 1024 bytes).

This means that after completing a transfer of 1024 bytes (for example), the hardware will consider switching to the next Channel to allow it to move another block of data, and so on in a round-robin fashion. If all other DMA Channels on a given DMA Engine are idle when arbitration would take place, the hardware will not arbitrate control to another Channel, but simply continue processing the transaction(s) for the Channel it is on.

=== DMA Copy Memory - Execution Flow Diagram ===

[[File:DMACopyMem-Diagram.png]]

=== What a call to perform a DMA copy does internally ===

As shown in the above diagram, when the user makes a call to request a memory copy be performed by the DMA hardware, the next available DMA Channel is selected for use and a DMA Transaction (source, destination and size) is constructed. The DMA Transaction is then programmed into the DMA Engine which owns the available DMA Channel.

At this point the calling task will Wait() until it hears the transaction has been completed. It will then return to the caller with the result. This provides a basic ''blocking'' function, which only returns to the caller once that data has been copied. This single tasking behavior is the simplest to use and what is normally expected by most applications using a memory copy function.

=== Diagram of multitasking DMA Copies ===

[[File:DMACopyMem-Multitasking-Diagram.png]]

=== How multiple simultaneous DMA copies are handled ===

When multiple user calls requesting a DMA copy arrive at once, each one is handed to a dedicated DMA Channel handling task for processing. As the diagram above demonstrates, there are two separate DMA Engines available, each with four channels that may be programmed at the same time. The hardware will then arbitrate the actual data move across these channels according to their respective bandwidth settings (usually 1024 bytes).

In the diagram above, a separate color indicates a distinct data path from the caller through the DMA hardware to the system RAM. A dashed line of the matching color indicates an Interrupt signaling the DMA Channel Handler tasks with the completion of the transaction. The handler task then signals back to the original caller, which returns to the user with a success or failure result.

All eight DMA Channels can handle each a single block transaction or an entire chain of block transactions before it singles completion and returns to the original caller. If all eight DMA Channels are busy processing their requested transactions when further DMA copy requests arrive, they will each be assigned a DMA Channel to wait on (managed via a Mutex lock on each Channel) and will block until allowed to add their DMA transaction to the Channel's queue.

== fsldma.resource ==

The fsldma.resource API is provided automatically in the kernel for all supported machines (Currently the AmigaONE X5000/20, X5000/40 and A1222).

=== The FslDMA API ===

The API provided by the fsldma.resource breaks down into three main parts:
:* Memory management
:* Copy Memory functions
:* Utility / Miscellaneous

==== Memory Management Functions ====

The FslDMA resource API provides convenience functions for the allocation and freeing of '''DMA Compliant''' blocks of memory. Two functions are provided for this purpose; DMAAllocPhysicalMemory() and DMAFreePhysicalMemory().

The memory allocation function also includes two Tags based versions of the call to allow for addition variables to be passed into the call using a variable set of Tags or fixed TagList. Currently the only supported Tag is ''FSLDMA_APM_ClearWithValue'', which is the equivalent to the IExec->AllocVecTagList() function's AVT_ClearWithValue tag. If the FSLDMA_APM_ClearWithValue tag is not provided then the requested memory block is cleared with zeroes by default before being returned. DMAAllocPhysicalMemory() returns the ''Physical'' Address pointer to the allocated memory or NULL if it is unable to allocate the requested memory.

<syntaxhighlight>
APTR DMAAllocPhysicalMemoryTagList( uint32 lSize, const struct TagItem *tags );
APTR DMAAllocPhysicalMemoryTags( uint32 lSize, uint32 Tag1, ... );
APTR DMAAllocPhysicalMemory( uint32 lSize );
</syntaxhighlight>

The corresponding function to allocating a DMA Compliant memory block is DMAFreePhysicalMemory(). Any memory allocated using DMAAllocPhysicalMemory() must be eventually freed using DMAFreePhysicalMemory().

<syntaxhighlight>
void DMAFreePhysicalMemory( APTR pPhysicalMemoryBlock );
</syntaxhighlight>

==== Copy Memory Functions ====

Two API calls make up the core of the FslDMA API; DMAPhysicalCopyMem() and DMACopyMem().
Both of these calls will "block" (not return to the user) until after the requested transfer has either succeeded or failed. A value of TRUE is returned upon success and FALSE if an error occurred.

<syntaxhighlight>
BOOL DMAPhysicalCopyMem( CONST_APTR pPhysicalSourceBuffer, APTR pPhysicalDestBuffer, uint32 lBufferSize );
BOOL DMACopyMem( CONST_APTR pSourceBuffer, APTR pDestBuffer, uint32 lBufferSize );
</syntaxhighlight>

As the name implies the first (and core version) of the copy memory functions, DMAPhysicalCopyMem(), accepts the Physical Addresses to the source and destination buffers (as returned by DMAAllocPhysicalMemory()), along with an unsigned 32-Bit value for the amount of bytes that should be copied (lBuffsize must be greater than zero(0) and no more than the maximum size of the source and destination buffers).

DMAPhysicalCopyMem() is the most direct an efficient means of using the DMA hardware to effect a single memory copy. The DMACopyMem() function is provided as an alternative way to request a DMA transfer by passing in the ''Virtual Addresses'' to the source and destination buffers instead of the Physical Addresses. DMACopyMem() will attempt to determine if the supplied memory buffers are DMA Compliant and if so it will internally use DMAPhysicalCopyMem() to handle the transaction. If DMACopyMem() determines that the supplied memory is '''not''' DMA Compliant it will return FALSE and no data copy will occur.

In theory any ''contiguous'' block of memory from 1 Byte up to 4GB in size may be transferred using either one of these calls. In practice the DMA hardware can directly accept memory blocks up to FSLDMA_MAXBLOCK_SIZE (or 64MB - 1 Byte). Therefore any data blocks greater than FSLDMA_MAXBLOCK_SIZE will automatically be feed to the DMA hardware in a series of smaller chunks. For maximum efficiency transfer sizes should be at least 256 Bytes in size and be an even multiple of 64 Bytes. Odd sizes are handled by the hardware but will degrade performance.

If you are transferring many large blocks of data in series and wish to manually send them to the FslDMA API's memory copy functions one block at a time, then setting your block sizes to FSLDMA_OPTIMAL_BLKSIZE (or 64 MB - 64 Bytes) and exclusively using DMAPhysicalCopyMem() will provide the fastest transfer speeds will the least amount of CPU overhead.

==== Utility / Miscellaneous Functions ====

The last section to the FslDMA API provides a single convenience function call; DMAGetVirtualAddress().

<syntaxhighlight>
APTR DMAGetVirtualAddress( APTR pPhysicalAddress );
</syntaxhighlight>

The DMAGetVirtualAddress() function returns the Virtual memory location for the Physical memory location that was itself allocated and returned by the DMAAllocPhysicalMemory() function. DMAGetVirtualAddress() will not work on physical addresses returned by IMMU->GetPhysicalAddress() on memory not allocated using DMAAllocPhysicalMemory().

The main purpose of this function (other then debugging purposes) is to provide the "normal" Virtual Address of memory allocated by the FslDMA API for use by functions that expect "normal" Virtual address locations; for example IExec->CopyMemQuick().

==== Further reference - The fsldma.resource AutoDoc ====

See the [[http://wiki.amigaos.net/amiga/autodocs/fsldmares.doc.txt fsldma.resource AutoDoc]] file for more details on each API call.

=== Example usage ===
<syntaxhighlight>
#include <interfaces/fsldma.h>
// Obtain the fsldma.resource
struct fslDMAIFace *IfslDMA = IExec->OpenResource(FSLDMA_NAME);
if ( NULL != IfslDMA )
{
uint32 lTestSize = 1024;
CONST_APTR pPhysicalSrcAddr = NULL;
APTR pPhysicalDestAddr = NULL;
// Allocate the Source Buffer (for DMA)
// and set the contents to 0xB3 (just an example value)
pPhysicalSrcAddr = (CONST_APTR)IfslDMA->DMAAllocPhysicalMemoryTags(lTestSize,
FSLDMA_APM_ClearWithValue, 0xB3,
TAG_END);
if ( NULL != pPhysicalSrcAddr )
{
// Allocate the Destination Buffer (for DMA)
// - contents will by cleared by default
pPhysicalDestAddr = IfslDMA->DMAAllocPhysicalMemory(lTestSize);
if ( NULL != pPhysicalDestAddr )
{
// Call IfslDMA->DMAPhysicalCopyMem()
// to perform the memory copy using the DMA hardware
if ( TRUE == IfslDMA->DMAPhysicalCopyMem(pPhysicalSrcAddr,
pPhysicalDestAddr,lTestSize) )
{
// Success - Do something with the copied data
}
else
{
// Fallback and use CPU Copy instead (or do something else)
// Since we allocated the memory buffers using the FslDMA API,
// which returns the Physical address to that memory, and the
// IExec->CopyMemQuick() function expects the Virtual address,
// we first need to obtain the Virtual address for the Physical
// ones (using the FslDMA API again) before we can call our
// fallback copy function.
CONST_APTR pVirtualSrcAddr = NULL;
APTR pVirtualDestAddr = NULL;
pVirtualSrcAddr = IfslDMA->DMAGetVirtualAddress((APTR)pPhysicalSrcAddr);
pVirtualDestAddr = IfslDMA->DMAGetVirtualAddress(pPhysicalDestAddr);
IExec->CopyMemQuick(pVirtualSrcAddr,pVirtualDestAddr,lTestSize);
}
// We *must* use DMAFreePhysicalMemory() to free the memory
// that we allocated with DMAAllocPhysicalMemory()
IfslDMA->DMAFreePhysicalMemory(pPhysicalDestAddr);
}
// We *must* use DMAFreePhysicalMemory() to free the memory
// that we allocated with DMAAllocPhysicalMemory()
IfslDMA->DMAFreePhysicalMemory((APTR)pPhysicalSrcAddr);
}
}
</syntaxhighlight>

==== Obtaining the fsldma.resource ====

Breaking the above example down the first thing we do is include the interface header for the fsldma.resource and obtain the resource itself.

<syntaxhighlight>
#include <interfaces/fsldma.h>
struct fslDMAIFace *IfslDMA = IExec->OpenResource(FSLDMA_NAME);
</syntaxhighlight>

==== Allocating DMA Compliant Memory ====

Once we have successfully obtained the DMA resource we can directly use its API. The next step we need to do is to allocate some memory '''which we know is DMA compliant''' for use by the resource. The easiest way to accomplish this is to use the IfslDMA->DMAAllocPhysicalMemory() function. This will automatically take care of ensuring the memory that is returned is properly aligned, contiguous, cache-inhibited and coherent.

We use the Tags version of the allocate memory function first so we can allocate a block of memory for our source buffer and fill it with some test value (in this case the byte value 0xB3).

<syntaxhighlight>
pPhysicalSrcAddr = (CONST_APTR)IfslDMA->DMAAllocPhysicalMemoryTags(lTestSize,
FSLDMA_APM_ClearWithValue, 0xB3,
TAG_END);
</syntaxhighlight>

We also need a destination buffer for our test. Since it only needs to start out being cleared (filled with zeroes), we can use the simplest form of the allocate memory function here as the allocated memory is cleared by default.

<syntaxhighlight>
pPhysicalDestAddr = IfslDMA->DMAAllocPhysicalMemory(lTestSize);
</syntaxhighlight>

==== The core function - Copy Physical Memory ====

Now that we have two DMA Compliant memory buffers available we can get to the heart of the API usage and make the call to IfslDMA->DMAPhysicalCopyMem().

<syntaxhighlight>
IfslDMA->DMAPhysicalCopyMem(pPhysicalSrcAddr,pPhysicalDestAddr,lTestSize);
</syntaxhighlight>

Looking at the full [[#Example usage|Example]] source above you can see that the DMAPhysicalCopyMem() call returns a Boolean value to indicate success or failure. Therefore, TRUE will be returned after the DMA hardware had completed copying the requested data (blocking call) and FALSE will be returned if a problem occurred.

Since the memory buffers we are using were allocated using the FslDMA API and our transfer size was greater than zero and less than or equal to the total size of either buffer, (in others words a legal copy request), there is '''very''' little chance that the DMAPhysicalCopyMem() function will fail. In fact, about the only reason the DMA hardware would fail to handle a legal transaction would be if the physical RAM installed in the system was faulty.

So even though it is extremely unlikely for our DMA copy to have failed and returned FALSE, let's take a look at how we might handle the failure. In other words, falling back and using a CPU based copy function instead to complete the data move.

Since we are reverting back to using a normal system copy memory function here, we first need to obtain the ''Virtual Addresses'' to both our source and destination buffers. This is accomplished by using the DMAGetVirtualAddress() function and passing in the Physical Address that was returned by DMAAllocPhysicalMemory().

<syntaxhighlight>
CONST_APTR pVirtualSrcAddr = NULL;
APTR pVirtualDestAddr = NULL;
pVirtualSrcAddr = IfslDMA->DMAGetVirtualAddress((APTR)pPhysicalSrcAddr);
pVirtualDestAddr = IfslDMA->DMAGetVirtualAddress(pPhysicalDestAddr);
</syntaxhighlight>

Now that we have the Virtual Address equivalents to the Physical Addresses that were returned by DMAAllocPhysicalMemory(), we can proceed to call the Exec CopyMemQuick() function to complete the copy. Here we can only trust that the IExec->CopyMemQuick() call can not fail since it does not return a result code.

<syntaxhighlight>
IExec->CopyMemQuick(pVirtualSrcAddr,pVirtualDestAddr,lTestSize);
</syntaxhighlight>

==== Cleaning up - Freeing DMA Compliant memory ====

It is essential that you free any memory that was allocated using the DMAAllocPhysicalMemory() function using the corresponding DMAFreePhysicalMemory() call. The reason for this is two-fold; first because additional resource tracking is maintained by the FslDMA API whenever it allocates memory which must itself be released, and second because the ''Physical Address'' to the memory is returned by the allocate call and not the ''Virtual Address'', so if you attempt to pass the address returned by DMAAllocPhysicalMemory() directly into IExec->FreeVec() it would likely result in a crash.

<syntaxhighlight>
IfslDMA->DMAFreePhysicalMemory(pPhysicalSrcAddr);
IfslDMA->DMAFreePhysicalMemory(pPhysicalDestAddr);
</syntaxhighlight>

DMA Resource

2019-11-16T02:05:46Z

Jamie Krueger: /* How multiple simultaneous DMA copies are handled */

== DMA Engine ==

Some hardware targets include a DMA engine which can be used for general purpose copying. This article describes the DMA engines available and how to use them.

=== Hardware Features ===

The Direct Memory Access (DMA) Engines found in the NXP/Freescale p5020, p5040 and p1022 System On a Chip (SoC)s, as found in the AmigaONE X5000/20, X5000/40 and A1222 respectively, are quite flexible and powerful. Each of these chips contains two distinct engines with four data channels each. This provides the ability to have a total of eight DMA Channels working at once, with up to two DMA transactions actually being executed at the same time (one on each of the two DMA Engines).

Further, each of the four DMA Channels found in a DMA Engine may be individually programmed to handle either; a single transaction, a ''Chain'' of transactions, or even ''Lists'' of ''Chains'' of transactions. The DMA Engines automatically arbitrate control between each DMA Channel following programmed bandwidth settings for each Channel (typically 1024 bytes).

This means that after completing a transfer of 1024 bytes (for example), the hardware will consider switching to the next Channel to allow it to move another block of data, and so on in a round-robin fashion. If all other DMA Channels on a given DMA Engine are idle when arbitration would take place, the hardware will not arbitrate control to another Channel, but simply continue processing the transaction(s) for the Channel it is on.

=== DMA Copy Memory - Execution Flow Diagram ===

[[File:DMACopyMem-Diagram.png]]

=== What a call to perform a DMA copy does internally ===

As shown in the above diagram, when the user makes a call to request a memory copy be performed by the DMA hardware, the next available DMA Channel is selected for use and a DMA Transaction (source, destination and size) is constructed. The DMA Transaction is then programmed into the DMA Engine which owns the available DMA Channel.

At this point the calling task will Wait() until it hears the transaction has been completed. It will then return to the caller with the result. This provides a basic ''blocking'' function, which only returns to the caller once that data has been copied. This single tasking behavior is the simplest to use and what is normally expected by most applications using a memory copy function.

=== Diagram of multitasking DMA Copies ===

[[File:DMACopyMem-Multitasking-Diagram.png]]

=== How multiple simultaneous DMA copies are handled ===

When multiple user calls requesting a DMA copy arrive at once, each one is handed to a dedicated DMA Channel handling task for processing. As the diagram above demonstrates, there are two separate DMA Engines available, each with four channels that may be programmed at the same time. The hardware will then arbitrate the actual data move across these channels according to their respective bandwidth settings (usually 1024 bytes).

In the diagram above, a separate color indicates a distinct data path from the caller through the DMA hardware to the system RAM. A dashed line of the matching color indicates an Interrupt signaling the DMA Channel Handler tasks with the completion of the transaction. The handler task then signals back to the original caller, which returns to the user with a success or failure result.

== fsldma.resource ==

The fsldma.resource API is provided automatically in the kernel for all supported machines (Currently the AmigaONE X5000/20, X5000/40 and A1222).

=== The FslDMA API ===

The API provided by the fsldma.resource breaks down into three main parts:
:* Memory management
:* Copy Memory functions
:* Utility / Miscellaneous

==== Memory Management Functions ====

The FslDMA resource API provides convenience functions for the allocation and freeing of '''DMA Compliant''' blocks of memory. Two functions are provided for this purpose; DMAAllocPhysicalMemory() and DMAFreePhysicalMemory().

The memory allocation function also includes two Tags based versions of the call to allow for addition variables to be passed into the call using a variable set of Tags or fixed TagList. Currently the only supported Tag is ''FSLDMA_APM_ClearWithValue'', which is the equivalent to the IExec->AllocVecTagList() function's AVT_ClearWithValue tag. If the FSLDMA_APM_ClearWithValue tag is not provided then the requested memory block is cleared with zeroes by default before being returned. DMAAllocPhysicalMemory() returns the ''Physical'' Address pointer to the allocated memory or NULL if it is unable to allocate the requested memory.

<syntaxhighlight>
APTR DMAAllocPhysicalMemoryTagList( uint32 lSize, const struct TagItem *tags );
APTR DMAAllocPhysicalMemoryTags( uint32 lSize, uint32 Tag1, ... );
APTR DMAAllocPhysicalMemory( uint32 lSize );
</syntaxhighlight>

The corresponding function to allocating a DMA Compliant memory block is DMAFreePhysicalMemory(). Any memory allocated using DMAAllocPhysicalMemory() must be eventually freed using DMAFreePhysicalMemory().

<syntaxhighlight>
void DMAFreePhysicalMemory( APTR pPhysicalMemoryBlock );
</syntaxhighlight>

==== Copy Memory Functions ====

Two API calls make up the core of the FslDMA API; DMAPhysicalCopyMem() and DMACopyMem().
Both of these calls will "block" (not return to the user) until after the requested transfer has either succeeded or failed. A value of TRUE is returned upon success and FALSE if an error occurred.

<syntaxhighlight>
BOOL DMAPhysicalCopyMem( CONST_APTR pPhysicalSourceBuffer, APTR pPhysicalDestBuffer, uint32 lBufferSize );
BOOL DMACopyMem( CONST_APTR pSourceBuffer, APTR pDestBuffer, uint32 lBufferSize );
</syntaxhighlight>

As the name implies the first (and core version) of the copy memory functions, DMAPhysicalCopyMem(), accepts the Physical Addresses to the source and destination buffers (as returned by DMAAllocPhysicalMemory()), along with an unsigned 32-Bit value for the amount of bytes that should be copied (lBuffsize must be greater than zero(0) and no more than the maximum size of the source and destination buffers).

DMAPhysicalCopyMem() is the most direct an efficient means of using the DMA hardware to effect a single memory copy. The DMACopyMem() function is provided as an alternative way to request a DMA transfer by passing in the ''Virtual Addresses'' to the source and destination buffers instead of the Physical Addresses. DMACopyMem() will attempt to determine if the supplied memory buffers are DMA Compliant and if so it will internally use DMAPhysicalCopyMem() to handle the transaction. If DMACopyMem() determines that the supplied memory is '''not''' DMA Compliant it will return FALSE and no data copy will occur.

In theory any ''contiguous'' block of memory from 1 Byte up to 4GB in size may be transferred using either one of these calls. In practice the DMA hardware can directly accept memory blocks up to FSLDMA_MAXBLOCK_SIZE (or 64MB - 1 Byte). Therefore any data blocks greater than FSLDMA_MAXBLOCK_SIZE will automatically be feed to the DMA hardware in a series of smaller chunks. For maximum efficiency transfer sizes should be at least 256 Bytes in size and be an even multiple of 64 Bytes. Odd sizes are handled by the hardware but will degrade performance.

If you are transferring many large blocks of data in series and wish to manually send them to the FslDMA API's memory copy functions one block at a time, then setting your block sizes to FSLDMA_OPTIMAL_BLKSIZE (or 64 MB - 64 Bytes) and exclusively using DMAPhysicalCopyMem() will provide the fastest transfer speeds will the least amount of CPU overhead.

==== Utility / Miscellaneous Functions ====

The last section to the FslDMA API provides a single convenience function call; DMAGetVirtualAddress().

<syntaxhighlight>
APTR DMAGetVirtualAddress( APTR pPhysicalAddress );
</syntaxhighlight>

The DMAGetVirtualAddress() function returns the Virtual memory location for the Physical memory location that was itself allocated and returned by the DMAAllocPhysicalMemory() function. DMAGetVirtualAddress() will not work on physical addresses returned by IMMU->GetPhysicalAddress() on memory not allocated using DMAAllocPhysicalMemory().

The main purpose of this function (other then debugging purposes) is to provide the "normal" Virtual Address of memory allocated by the FslDMA API for use by functions that expect "normal" Virtual address locations; for example IExec->CopyMemQuick().

==== Further reference - The fsldma.resource AutoDoc ====

See the [[http://wiki.amigaos.net/amiga/autodocs/fsldmares.doc.txt fsldma.resource AutoDoc]] file for more details on each API call.

=== Example usage ===
<syntaxhighlight>
#include <interfaces/fsldma.h>
// Obtain the fsldma.resource
struct fslDMAIFace *IfslDMA = IExec->OpenResource(FSLDMA_NAME);
if ( NULL != IfslDMA )
{
uint32 lTestSize = 1024;
CONST_APTR pPhysicalSrcAddr = NULL;
APTR pPhysicalDestAddr = NULL;
// Allocate the Source Buffer (for DMA)
// and set the contents to 0xB3 (just an example value)
pPhysicalSrcAddr = (CONST_APTR)IfslDMA->DMAAllocPhysicalMemoryTags(lTestSize,
FSLDMA_APM_ClearWithValue, 0xB3,
TAG_END);
if ( NULL != pPhysicalSrcAddr )
{
// Allocate the Destination Buffer (for DMA)
// - contents will by cleared by default
pPhysicalDestAddr = IfslDMA->DMAAllocPhysicalMemory(lTestSize);
if ( NULL != pPhysicalDestAddr )
{
// Call IfslDMA->DMAPhysicalCopyMem()
// to perform the memory copy using the DMA hardware
if ( TRUE == IfslDMA->DMAPhysicalCopyMem(pPhysicalSrcAddr,
pPhysicalDestAddr,lTestSize) )
{
// Success - Do something with the copied data
}
else
{
// Fallback and use CPU Copy instead (or do something else)
// Since we allocated the memory buffers using the FslDMA API,
// which returns the Physical address to that memory, and the
// IExec->CopyMemQuick() function expects the Virtual address,
// we first need to obtain the Virtual address for the Physical
// ones (using the FslDMA API again) before we can call our
// fallback copy function.
CONST_APTR pVirtualSrcAddr = NULL;
APTR pVirtualDestAddr = NULL;
pVirtualSrcAddr = IfslDMA->DMAGetVirtualAddress((APTR)pPhysicalSrcAddr);
pVirtualDestAddr = IfslDMA->DMAGetVirtualAddress(pPhysicalDestAddr);
IExec->CopyMemQuick(pVirtualSrcAddr,pVirtualDestAddr,lTestSize);
}
// We *must* use DMAFreePhysicalMemory() to free the memory
// that we allocated with DMAAllocPhysicalMemory()
IfslDMA->DMAFreePhysicalMemory(pPhysicalDestAddr);
}
// We *must* use DMAFreePhysicalMemory() to free the memory
// that we allocated with DMAAllocPhysicalMemory()
IfslDMA->DMAFreePhysicalMemory((APTR)pPhysicalSrcAddr);
}
}
</syntaxhighlight>

==== Obtaining the fsldma.resource ====

Breaking the above example down the first thing we do is include the interface header for the fsldma.resource and obtain the resource itself.

<syntaxhighlight>
#include <interfaces/fsldma.h>
struct fslDMAIFace *IfslDMA = IExec->OpenResource(FSLDMA_NAME);
</syntaxhighlight>

==== Allocating DMA Compliant Memory ====

Once we have successfully obtained the DMA resource we can directly use its API. The next step we need to do is to allocate some memory '''which we know is DMA compliant''' for use by the resource. The easiest way to accomplish this is to use the IfslDMA->DMAAllocPhysicalMemory() function. This will automatically take care of ensuring the memory that is returned is properly aligned, contiguous, cache-inhibited and coherent.

We use the Tags version of the allocate memory function first so we can allocate a block of memory for our source buffer and fill it with some test value (in this case the byte value 0xB3).

<syntaxhighlight>
pPhysicalSrcAddr = (CONST_APTR)IfslDMA->DMAAllocPhysicalMemoryTags(lTestSize,
FSLDMA_APM_ClearWithValue, 0xB3,
TAG_END);
</syntaxhighlight>

We also need a destination buffer for our test. Since it only needs to start out being cleared (filled with zeroes), we can use the simplest form of the allocate memory function here as the allocated memory is cleared by default.

<syntaxhighlight>
pPhysicalDestAddr = IfslDMA->DMAAllocPhysicalMemory(lTestSize);
</syntaxhighlight>

==== The core function - Copy Physical Memory ====

Now that we have two DMA Compliant memory buffers available we can get to the heart of the API usage and make the call to IfslDMA->DMAPhysicalCopyMem().

<syntaxhighlight>
IfslDMA->DMAPhysicalCopyMem(pPhysicalSrcAddr,pPhysicalDestAddr,lTestSize);
</syntaxhighlight>

Looking at the full [[#Example usage|Example]] source above you can see that the DMAPhysicalCopyMem() call returns a Boolean value to indicate success or failure. Therefore, TRUE will be returned after the DMA hardware had completed copying the requested data (blocking call) and FALSE will be returned if a problem occurred.

Since the memory buffers we are using were allocated using the FslDMA API and our transfer size was greater than zero and less than or equal to the total size of either buffer, (in others words a legal copy request), there is '''very''' little chance that the DMAPhysicalCopyMem() function will fail. In fact, about the only reason the DMA hardware would fail to handle a legal transaction would be if the physical RAM installed in the system was faulty.

So even though it is extremely unlikely for our DMA copy to have failed and returned FALSE, let's take a look at how we might handle the failure. In other words, falling back and using a CPU based copy function instead to complete the data move.

Since we are reverting back to using a normal system copy memory function here, we first need to obtain the ''Virtual Addresses'' to both our source and destination buffers. This is accomplished by using the DMAGetVirtualAddress() function and passing in the Physical Address that was returned by DMAAllocPhysicalMemory().

<syntaxhighlight>
CONST_APTR pVirtualSrcAddr = NULL;
APTR pVirtualDestAddr = NULL;
pVirtualSrcAddr = IfslDMA->DMAGetVirtualAddress((APTR)pPhysicalSrcAddr);
pVirtualDestAddr = IfslDMA->DMAGetVirtualAddress(pPhysicalDestAddr);
</syntaxhighlight>

Now that we have the Virtual Address equivalents to the Physical Addresses that were returned by DMAAllocPhysicalMemory(), we can proceed to call the Exec CopyMemQuick() function to complete the copy. Here we can only trust that the IExec->CopyMemQuick() call can not fail since it does not return a result code.

<syntaxhighlight>
IExec->CopyMemQuick(pVirtualSrcAddr,pVirtualDestAddr,lTestSize);
</syntaxhighlight>

==== Cleaning up - Freeing DMA Compliant memory ====

It is essential that you free any memory that was allocated using the DMAAllocPhysicalMemory() function using the corresponding DMAFreePhysicalMemory() call. The reason for this is two-fold; first because additional resource tracking is maintained by the FslDMA API whenever it allocates memory which must itself be released, and second because the ''Physical Address'' to the memory is returned by the allocate call and not the ''Virtual Address'', so if you attempt to pass the address returned by DMAAllocPhysicalMemory() directly into IExec->FreeVec() it would likely result in a crash.

<syntaxhighlight>
IfslDMA->DMAFreePhysicalMemory(pPhysicalSrcAddr);
IfslDMA->DMAFreePhysicalMemory(pPhysicalDestAddr);
</syntaxhighlight>

DMA Resource

2019-11-16T01:55:48Z

Jamie Krueger: /* Diagram of multitasking DMA Copies */

== DMA Engine ==

Some hardware targets include a DMA engine which can be used for general purpose copying. This article describes the DMA engines available and how to use them.

=== Hardware Features ===

The Direct Memory Access (DMA) Engines found in the NXP/Freescale p5020, p5040 and p1022 System On a Chip (SoC)s, as found in the AmigaONE X5000/20, X5000/40 and A1222 respectively, are quite flexible and powerful. Each of these chips contains two distinct engines with four data channels each. This provides the ability to have a total of eight DMA Channels working at once, with up to two DMA transactions actually being executed at the same time (one on each of the two DMA Engines).

Further, each of the four DMA Channels found in a DMA Engine may be individually programmed to handle either; a single transaction, a ''Chain'' of transactions, or even ''Lists'' of ''Chains'' of transactions. The DMA Engines automatically arbitrate control between each DMA Channel following programmed bandwidth settings for each Channel (typically 1024 bytes).

This means that after completing a transfer of 1024 bytes (for example), the hardware will consider switching to the next Channel to allow it to move another block of data, and so on in a round-robin fashion. If all other DMA Channels on a given DMA Engine are idle when arbitration would take place, the hardware will not arbitrate control to another Channel, but simply continue processing the transaction(s) for the Channel it is on.

=== DMA Copy Memory - Execution Flow Diagram ===

[[File:DMACopyMem-Diagram.png]]

=== What a call to perform a DMA copy does internally ===

As shown in the above diagram, when the user makes a call to request a memory copy be performed by the DMA hardware, the next available DMA Channel is selected for use and a DMA Transaction (source, destination and size) is constructed. The DMA Transaction is then programmed into the DMA Engine which owns the available DMA Channel.

At this point the calling task will Wait() until it hears the transaction has been completed. It will then return to the caller with the result. This provides a basic ''blocking'' function, which only returns to the caller once that data has been copied. This single tasking behavior is the simplest to use and what is normally expected by most applications using a memory copy function.

=== Diagram of multitasking DMA Copies ===

[[File:DMACopyMem-Multitasking-Diagram.png]]

=== How multiple simultaneous DMA copies are handled ===

== fsldma.resource ==

The fsldma.resource API is provided automatically in the kernel for all supported machines (Currently the AmigaONE X5000/20, X5000/40 and A1222).

=== The FslDMA API ===

The API provided by the fsldma.resource breaks down into three main parts:
:* Memory management
:* Copy Memory functions
:* Utility / Miscellaneous

==== Memory Management Functions ====

The FslDMA resource API provides convenience functions for the allocation and freeing of '''DMA Compliant''' blocks of memory. Two functions are provided for this purpose; DMAAllocPhysicalMemory() and DMAFreePhysicalMemory().

The memory allocation function also includes two Tags based versions of the call to allow for addition variables to be passed into the call using a variable set of Tags or fixed TagList. Currently the only supported Tag is ''FSLDMA_APM_ClearWithValue'', which is the equivalent to the IExec->AllocVecTagList() function's AVT_ClearWithValue tag. If the FSLDMA_APM_ClearWithValue tag is not provided then the requested memory block is cleared with zeroes by default before being returned. DMAAllocPhysicalMemory() returns the ''Physical'' Address pointer to the allocated memory or NULL if it is unable to allocate the requested memory.

<syntaxhighlight>
APTR DMAAllocPhysicalMemoryTagList( uint32 lSize, const struct TagItem *tags );
APTR DMAAllocPhysicalMemoryTags( uint32 lSize, uint32 Tag1, ... );
APTR DMAAllocPhysicalMemory( uint32 lSize );
</syntaxhighlight>

The corresponding function to allocating a DMA Compliant memory block is DMAFreePhysicalMemory(). Any memory allocated using DMAAllocPhysicalMemory() must be eventually freed using DMAFreePhysicalMemory().

<syntaxhighlight>
void DMAFreePhysicalMemory( APTR pPhysicalMemoryBlock );
</syntaxhighlight>

==== Copy Memory Functions ====

Two API calls make up the core of the FslDMA API; DMAPhysicalCopyMem() and DMACopyMem().
Both of these calls will "block" (not return to the user) until after the requested transfer has either succeeded or failed. A value of TRUE is returned upon success and FALSE if an error occurred.

<syntaxhighlight>
BOOL DMAPhysicalCopyMem( CONST_APTR pPhysicalSourceBuffer, APTR pPhysicalDestBuffer, uint32 lBufferSize );
BOOL DMACopyMem( CONST_APTR pSourceBuffer, APTR pDestBuffer, uint32 lBufferSize );
</syntaxhighlight>

As the name implies the first (and core version) of the copy memory functions, DMAPhysicalCopyMem(), accepts the Physical Addresses to the source and destination buffers (as returned by DMAAllocPhysicalMemory()), along with an unsigned 32-Bit value for the amount of bytes that should be copied (lBuffsize must be greater than zero(0) and no more than the maximum size of the source and destination buffers).

DMAPhysicalCopyMem() is the most direct an efficient means of using the DMA hardware to effect a single memory copy. The DMACopyMem() function is provided as an alternative way to request a DMA transfer by passing in the ''Virtual Addresses'' to the source and destination buffers instead of the Physical Addresses. DMACopyMem() will attempt to determine if the supplied memory buffers are DMA Compliant and if so it will internally use DMAPhysicalCopyMem() to handle the transaction. If DMACopyMem() determines that the supplied memory is '''not''' DMA Compliant it will return FALSE and no data copy will occur.

In theory any ''contiguous'' block of memory from 1 Byte up to 4GB in size may be transferred using either one of these calls. In practice the DMA hardware can directly accept memory blocks up to FSLDMA_MAXBLOCK_SIZE (or 64MB - 1 Byte). Therefore any data blocks greater than FSLDMA_MAXBLOCK_SIZE will automatically be feed to the DMA hardware in a series of smaller chunks. For maximum efficiency transfer sizes should be at least 256 Bytes in size and be an even multiple of 64 Bytes. Odd sizes are handled by the hardware but will degrade performance.

If you are transferring many large blocks of data in series and wish to manually send them to the FslDMA API's memory copy functions one block at a time, then setting your block sizes to FSLDMA_OPTIMAL_BLKSIZE (or 64 MB - 64 Bytes) and exclusively using DMAPhysicalCopyMem() will provide the fastest transfer speeds will the least amount of CPU overhead.

==== Utility / Miscellaneous Functions ====

The last section to the FslDMA API provides a single convenience function call; DMAGetVirtualAddress().

<syntaxhighlight>
APTR DMAGetVirtualAddress( APTR pPhysicalAddress );
</syntaxhighlight>

The DMAGetVirtualAddress() function returns the Virtual memory location for the Physical memory location that was itself allocated and returned by the DMAAllocPhysicalMemory() function. DMAGetVirtualAddress() will not work on physical addresses returned by IMMU->GetPhysicalAddress() on memory not allocated using DMAAllocPhysicalMemory().

The main purpose of this function (other then debugging purposes) is to provide the "normal" Virtual Address of memory allocated by the FslDMA API for use by functions that expect "normal" Virtual address locations; for example IExec->CopyMemQuick().

==== Further reference - The fsldma.resource AutoDoc ====

See the [[http://wiki.amigaos.net/amiga/autodocs/fsldmares.doc.txt fsldma.resource AutoDoc]] file for more details on each API call.

=== Example usage ===
<syntaxhighlight>
#include <interfaces/fsldma.h>
// Obtain the fsldma.resource
struct fslDMAIFace *IfslDMA = IExec->OpenResource(FSLDMA_NAME);
if ( NULL != IfslDMA )
{
uint32 lTestSize = 1024;
CONST_APTR pPhysicalSrcAddr = NULL;
APTR pPhysicalDestAddr = NULL;
// Allocate the Source Buffer (for DMA)
// and set the contents to 0xB3 (just an example value)
pPhysicalSrcAddr = (CONST_APTR)IfslDMA->DMAAllocPhysicalMemoryTags(lTestSize,
FSLDMA_APM_ClearWithValue, 0xB3,
TAG_END);
if ( NULL != pPhysicalSrcAddr )
{
// Allocate the Destination Buffer (for DMA)
// - contents will by cleared by default
pPhysicalDestAddr = IfslDMA->DMAAllocPhysicalMemory(lTestSize);
if ( NULL != pPhysicalDestAddr )
{
// Call IfslDMA->DMAPhysicalCopyMem()
// to perform the memory copy using the DMA hardware
if ( TRUE == IfslDMA->DMAPhysicalCopyMem(pPhysicalSrcAddr,
pPhysicalDestAddr,lTestSize) )
{
// Success - Do something with the copied data
}
else
{
// Fallback and use CPU Copy instead (or do something else)
// Since we allocated the memory buffers using the FslDMA API,
// which returns the Physical address to that memory, and the
// IExec->CopyMemQuick() function expects the Virtual address,
// we first need to obtain the Virtual address for the Physical
// ones (using the FslDMA API again) before we can call our
// fallback copy function.
CONST_APTR pVirtualSrcAddr = NULL;
APTR pVirtualDestAddr = NULL;
pVirtualSrcAddr = IfslDMA->DMAGetVirtualAddress((APTR)pPhysicalSrcAddr);
pVirtualDestAddr = IfslDMA->DMAGetVirtualAddress(pPhysicalDestAddr);
IExec->CopyMemQuick(pVirtualSrcAddr,pVirtualDestAddr,lTestSize);
}
// We *must* use DMAFreePhysicalMemory() to free the memory
// that we allocated with DMAAllocPhysicalMemory()
IfslDMA->DMAFreePhysicalMemory(pPhysicalDestAddr);
}
// We *must* use DMAFreePhysicalMemory() to free the memory
// that we allocated with DMAAllocPhysicalMemory()
IfslDMA->DMAFreePhysicalMemory((APTR)pPhysicalSrcAddr);
}
}
</syntaxhighlight>

==== Obtaining the fsldma.resource ====

Breaking the above example down the first thing we do is include the interface header for the fsldma.resource and obtain the resource itself.

<syntaxhighlight>
#include <interfaces/fsldma.h>
struct fslDMAIFace *IfslDMA = IExec->OpenResource(FSLDMA_NAME);
</syntaxhighlight>

==== Allocating DMA Compliant Memory ====

Once we have successfully obtained the DMA resource we can directly use its API. The next step we need to do is to allocate some memory '''which we know is DMA compliant''' for use by the resource. The easiest way to accomplish this is to use the IfslDMA->DMAAllocPhysicalMemory() function. This will automatically take care of ensuring the memory that is returned is properly aligned, contiguous, cache-inhibited and coherent.

We use the Tags version of the allocate memory function first so we can allocate a block of memory for our source buffer and fill it with some test value (in this case the byte value 0xB3).

<syntaxhighlight>
pPhysicalSrcAddr = (CONST_APTR)IfslDMA->DMAAllocPhysicalMemoryTags(lTestSize,
FSLDMA_APM_ClearWithValue, 0xB3,
TAG_END);
</syntaxhighlight>

We also need a destination buffer for our test. Since it only needs to start out being cleared (filled with zeroes), we can use the simplest form of the allocate memory function here as the allocated memory is cleared by default.

<syntaxhighlight>
pPhysicalDestAddr = IfslDMA->DMAAllocPhysicalMemory(lTestSize);
</syntaxhighlight>

==== The core function - Copy Physical Memory ====

Now that we have two DMA Compliant memory buffers available we can get to the heart of the API usage and make the call to IfslDMA->DMAPhysicalCopyMem().

<syntaxhighlight>
IfslDMA->DMAPhysicalCopyMem(pPhysicalSrcAddr,pPhysicalDestAddr,lTestSize);
</syntaxhighlight>

Looking at the full [[#Example usage|Example]] source above you can see that the DMAPhysicalCopyMem() call returns a Boolean value to indicate success or failure. Therefore, TRUE will be returned after the DMA hardware had completed copying the requested data (blocking call) and FALSE will be returned if a problem occurred.

Since the memory buffers we are using were allocated using the FslDMA API and our transfer size was greater than zero and less than or equal to the total size of either buffer, (in others words a legal copy request), there is '''very''' little chance that the DMAPhysicalCopyMem() function will fail. In fact, about the only reason the DMA hardware would fail to handle a legal transaction would be if the physical RAM installed in the system was faulty.

So even though it is extremely unlikely for our DMA copy to have failed and returned FALSE, let's take a look at how we might handle the failure. In other words, falling back and using a CPU based copy function instead to complete the data move.

Since we are reverting back to using a normal system copy memory function here, we first need to obtain the ''Virtual Addresses'' to both our source and destination buffers. This is accomplished by using the DMAGetVirtualAddress() function and passing in the Physical Address that was returned by DMAAllocPhysicalMemory().

<syntaxhighlight>
CONST_APTR pVirtualSrcAddr = NULL;
APTR pVirtualDestAddr = NULL;
pVirtualSrcAddr = IfslDMA->DMAGetVirtualAddress((APTR)pPhysicalSrcAddr);
pVirtualDestAddr = IfslDMA->DMAGetVirtualAddress(pPhysicalDestAddr);
</syntaxhighlight>

Now that we have the Virtual Address equivalents to the Physical Addresses that were returned by DMAAllocPhysicalMemory(), we can proceed to call the Exec CopyMemQuick() function to complete the copy. Here we can only trust that the IExec->CopyMemQuick() call can not fail since it does not return a result code.

<syntaxhighlight>
IExec->CopyMemQuick(pVirtualSrcAddr,pVirtualDestAddr,lTestSize);
</syntaxhighlight>

==== Cleaning up - Freeing DMA Compliant memory ====

It is essential that you free any memory that was allocated using the DMAAllocPhysicalMemory() function using the corresponding DMAFreePhysicalMemory() call. The reason for this is two-fold; first because additional resource tracking is maintained by the FslDMA API whenever it allocates memory which must itself be released, and second because the ''Physical Address'' to the memory is returned by the allocate call and not the ''Virtual Address'', so if you attempt to pass the address returned by DMAAllocPhysicalMemory() directly into IExec->FreeVec() it would likely result in a crash.

<syntaxhighlight>
IfslDMA->DMAFreePhysicalMemory(pPhysicalSrcAddr);
IfslDMA->DMAFreePhysicalMemory(pPhysicalDestAddr);
</syntaxhighlight>

DMA Resource

2019-11-16T01:52:03Z

Jamie Krueger: /* Diagram of multitasking DMA Copies */

== DMA Engine ==

Some hardware targets include a DMA engine which can be used for general purpose copying. This article describes the DMA engines available and how to use them.

=== Hardware Features ===

The Direct Memory Access (DMA) Engines found in the NXP/Freescale p5020, p5040 and p1022 System On a Chip (SoC)s, as found in the AmigaONE X5000/20, X5000/40 and A1222 respectively, are quite flexible and powerful. Each of these chips contains two distinct engines with four data channels each. This provides the ability to have a total of eight DMA Channels working at once, with up to two DMA transactions actually being executed at the same time (one on each of the two DMA Engines).

Further, each of the four DMA Channels found in a DMA Engine may be individually programmed to handle either; a single transaction, a ''Chain'' of transactions, or even ''Lists'' of ''Chains'' of transactions. The DMA Engines automatically arbitrate control between each DMA Channel following programmed bandwidth settings for each Channel (typically 1024 bytes).

This means that after completing a transfer of 1024 bytes (for example), the hardware will consider switching to the next Channel to allow it to move another block of data, and so on in a round-robin fashion. If all other DMA Channels on a given DMA Engine are idle when arbitration would take place, the hardware will not arbitrate control to another Channel, but simply continue processing the transaction(s) for the Channel it is on.

=== DMA Copy Memory - Execution Flow Diagram ===

[[File:DMACopyMem-Diagram.png]]

=== What a call to perform a DMA copy does internally ===

As shown in the above diagram, when the user makes a call to request a memory copy be performed by the DMA hardware, the next available DMA Channel is selected for use and a DMA Transaction (source, destination and size) is constructed. The DMA Transaction is then programmed into the DMA Engine which owns the available DMA Channel.

At this point the calling task will Wait() until it hears the transaction has been completed. It will then return to the caller with the result. This provides a basic ''blocking'' function, which only returns to the caller once that data has been copied. This single tasking behavior is the simplest to use and what is normally expected by most applications using a memory copy function.

=== Diagram of multitasking DMA Copies ===

[[File:DMACopyMem-Multitasking-Diagram.png]]

=== How multiple simultaneous DMA copies are handled ===

== fsldma.resource ==

The fsldma.resource API is provided automatically in the kernel for all supported machines (Currently the AmigaONE X5000/20, X5000/40 and A1222).

=== The FslDMA API ===

The API provided by the fsldma.resource breaks down into three main parts:
:* Memory management
:* Copy Memory functions
:* Utility / Miscellaneous

==== Memory Management Functions ====

The FslDMA resource API provides convenience functions for the allocation and freeing of '''DMA Compliant''' blocks of memory. Two functions are provided for this purpose; DMAAllocPhysicalMemory() and DMAFreePhysicalMemory().

The memory allocation function also includes two Tags based versions of the call to allow for addition variables to be passed into the call using a variable set of Tags or fixed TagList. Currently the only supported Tag is ''FSLDMA_APM_ClearWithValue'', which is the equivalent to the IExec->AllocVecTagList() function's AVT_ClearWithValue tag. If the FSLDMA_APM_ClearWithValue tag is not provided then the requested memory block is cleared with zeroes by default before being returned. DMAAllocPhysicalMemory() returns the ''Physical'' Address pointer to the allocated memory or NULL if it is unable to allocate the requested memory.

<syntaxhighlight>
APTR DMAAllocPhysicalMemoryTagList( uint32 lSize, const struct TagItem *tags );
APTR DMAAllocPhysicalMemoryTags( uint32 lSize, uint32 Tag1, ... );
APTR DMAAllocPhysicalMemory( uint32 lSize );
</syntaxhighlight>

The corresponding function to allocating a DMA Compliant memory block is DMAFreePhysicalMemory(). Any memory allocated using DMAAllocPhysicalMemory() must be eventually freed using DMAFreePhysicalMemory().

<syntaxhighlight>
void DMAFreePhysicalMemory( APTR pPhysicalMemoryBlock );
</syntaxhighlight>

==== Copy Memory Functions ====

Two API calls make up the core of the FslDMA API; DMAPhysicalCopyMem() and DMACopyMem().
Both of these calls will "block" (not return to the user) until after the requested transfer has either succeeded or failed. A value of TRUE is returned upon success and FALSE if an error occurred.

<syntaxhighlight>
BOOL DMAPhysicalCopyMem( CONST_APTR pPhysicalSourceBuffer, APTR pPhysicalDestBuffer, uint32 lBufferSize );
BOOL DMACopyMem( CONST_APTR pSourceBuffer, APTR pDestBuffer, uint32 lBufferSize );
</syntaxhighlight>

As the name implies the first (and core version) of the copy memory functions, DMAPhysicalCopyMem(), accepts the Physical Addresses to the source and destination buffers (as returned by DMAAllocPhysicalMemory()), along with an unsigned 32-Bit value for the amount of bytes that should be copied (lBuffsize must be greater than zero(0) and no more than the maximum size of the source and destination buffers).

DMAPhysicalCopyMem() is the most direct an efficient means of using the DMA hardware to effect a single memory copy. The DMACopyMem() function is provided as an alternative way to request a DMA transfer by passing in the ''Virtual Addresses'' to the source and destination buffers instead of the Physical Addresses. DMACopyMem() will attempt to determine if the supplied memory buffers are DMA Compliant and if so it will internally use DMAPhysicalCopyMem() to handle the transaction. If DMACopyMem() determines that the supplied memory is '''not''' DMA Compliant it will return FALSE and no data copy will occur.

In theory any ''contiguous'' block of memory from 1 Byte up to 4GB in size may be transferred using either one of these calls. In practice the DMA hardware can directly accept memory blocks up to FSLDMA_MAXBLOCK_SIZE (or 64MB - 1 Byte). Therefore any data blocks greater than FSLDMA_MAXBLOCK_SIZE will automatically be feed to the DMA hardware in a series of smaller chunks. For maximum efficiency transfer sizes should be at least 256 Bytes in size and be an even multiple of 64 Bytes. Odd sizes are handled by the hardware but will degrade performance.

If you are transferring many large blocks of data in series and wish to manually send them to the FslDMA API's memory copy functions one block at a time, then setting your block sizes to FSLDMA_OPTIMAL_BLKSIZE (or 64 MB - 64 Bytes) and exclusively using DMAPhysicalCopyMem() will provide the fastest transfer speeds will the least amount of CPU overhead.

==== Utility / Miscellaneous Functions ====

The last section to the FslDMA API provides a single convenience function call; DMAGetVirtualAddress().

<syntaxhighlight>
APTR DMAGetVirtualAddress( APTR pPhysicalAddress );
</syntaxhighlight>

The DMAGetVirtualAddress() function returns the Virtual memory location for the Physical memory location that was itself allocated and returned by the DMAAllocPhysicalMemory() function. DMAGetVirtualAddress() will not work on physical addresses returned by IMMU->GetPhysicalAddress() on memory not allocated using DMAAllocPhysicalMemory().

The main purpose of this function (other then debugging purposes) is to provide the "normal" Virtual Address of memory allocated by the FslDMA API for use by functions that expect "normal" Virtual address locations; for example IExec->CopyMemQuick().

==== Further reference - The fsldma.resource AutoDoc ====

See the [[http://wiki.amigaos.net/amiga/autodocs/fsldmares.doc.txt fsldma.resource AutoDoc]] file for more details on each API call.

=== Example usage ===
<syntaxhighlight>
#include <interfaces/fsldma.h>
// Obtain the fsldma.resource
struct fslDMAIFace *IfslDMA = IExec->OpenResource(FSLDMA_NAME);
if ( NULL != IfslDMA )
{
uint32 lTestSize = 1024;
CONST_APTR pPhysicalSrcAddr = NULL;
APTR pPhysicalDestAddr = NULL;
// Allocate the Source Buffer (for DMA)
// and set the contents to 0xB3 (just an example value)
pPhysicalSrcAddr = (CONST_APTR)IfslDMA->DMAAllocPhysicalMemoryTags(lTestSize,
FSLDMA_APM_ClearWithValue, 0xB3,
TAG_END);
if ( NULL != pPhysicalSrcAddr )
{
// Allocate the Destination Buffer (for DMA)
// - contents will by cleared by default
pPhysicalDestAddr = IfslDMA->DMAAllocPhysicalMemory(lTestSize);
if ( NULL != pPhysicalDestAddr )
{
// Call IfslDMA->DMAPhysicalCopyMem()
// to perform the memory copy using the DMA hardware
if ( TRUE == IfslDMA->DMAPhysicalCopyMem(pPhysicalSrcAddr,
pPhysicalDestAddr,lTestSize) )
{
// Success - Do something with the copied data
}
else
{
// Fallback and use CPU Copy instead (or do something else)
// Since we allocated the memory buffers using the FslDMA API,
// which returns the Physical address to that memory, and the
// IExec->CopyMemQuick() function expects the Virtual address,
// we first need to obtain the Virtual address for the Physical
// ones (using the FslDMA API again) before we can call our
// fallback copy function.
CONST_APTR pVirtualSrcAddr = NULL;
APTR pVirtualDestAddr = NULL;
pVirtualSrcAddr = IfslDMA->DMAGetVirtualAddress((APTR)pPhysicalSrcAddr);
pVirtualDestAddr = IfslDMA->DMAGetVirtualAddress(pPhysicalDestAddr);
IExec->CopyMemQuick(pVirtualSrcAddr,pVirtualDestAddr,lTestSize);
}
// We *must* use DMAFreePhysicalMemory() to free the memory
// that we allocated with DMAAllocPhysicalMemory()
IfslDMA->DMAFreePhysicalMemory(pPhysicalDestAddr);
}
// We *must* use DMAFreePhysicalMemory() to free the memory
// that we allocated with DMAAllocPhysicalMemory()
IfslDMA->DMAFreePhysicalMemory((APTR)pPhysicalSrcAddr);
}
}
</syntaxhighlight>

==== Obtaining the fsldma.resource ====

Breaking the above example down the first thing we do is include the interface header for the fsldma.resource and obtain the resource itself.

<syntaxhighlight>
#include <interfaces/fsldma.h>
struct fslDMAIFace *IfslDMA = IExec->OpenResource(FSLDMA_NAME);
</syntaxhighlight>

==== Allocating DMA Compliant Memory ====

Once we have successfully obtained the DMA resource we can directly use its API. The next step we need to do is to allocate some memory '''which we know is DMA compliant''' for use by the resource. The easiest way to accomplish this is to use the IfslDMA->DMAAllocPhysicalMemory() function. This will automatically take care of ensuring the memory that is returned is properly aligned, contiguous, cache-inhibited and coherent.

We use the Tags version of the allocate memory function first so we can allocate a block of memory for our source buffer and fill it with some test value (in this case the byte value 0xB3).

<syntaxhighlight>
pPhysicalSrcAddr = (CONST_APTR)IfslDMA->DMAAllocPhysicalMemoryTags(lTestSize,
FSLDMA_APM_ClearWithValue, 0xB3,
TAG_END);
</syntaxhighlight>

We also need a destination buffer for our test. Since it only needs to start out being cleared (filled with zeroes), we can use the simplest form of the allocate memory function here as the allocated memory is cleared by default.

<syntaxhighlight>
pPhysicalDestAddr = IfslDMA->DMAAllocPhysicalMemory(lTestSize);
</syntaxhighlight>

==== The core function - Copy Physical Memory ====

Now that we have two DMA Compliant memory buffers available we can get to the heart of the API usage and make the call to IfslDMA->DMAPhysicalCopyMem().

<syntaxhighlight>
IfslDMA->DMAPhysicalCopyMem(pPhysicalSrcAddr,pPhysicalDestAddr,lTestSize);
</syntaxhighlight>

Looking at the full [[#Example usage|Example]] source above you can see that the DMAPhysicalCopyMem() call returns a Boolean value to indicate success or failure. Therefore, TRUE will be returned after the DMA hardware had completed copying the requested data (blocking call) and FALSE will be returned if a problem occurred.

Since the memory buffers we are using were allocated using the FslDMA API and our transfer size was greater than zero and less than or equal to the total size of either buffer, (in others words a legal copy request), there is '''very''' little chance that the DMAPhysicalCopyMem() function will fail. In fact, about the only reason the DMA hardware would fail to handle a legal transaction would be if the physical RAM installed in the system was faulty.

So even though it is extremely unlikely for our DMA copy to have failed and returned FALSE, let's take a look at how we might handle the failure. In other words, falling back and using a CPU based copy function instead to complete the data move.

Since we are reverting back to using a normal system copy memory function here, we first need to obtain the ''Virtual Addresses'' to both our source and destination buffers. This is accomplished by using the DMAGetVirtualAddress() function and passing in the Physical Address that was returned by DMAAllocPhysicalMemory().

<syntaxhighlight>
CONST_APTR pVirtualSrcAddr = NULL;
APTR pVirtualDestAddr = NULL;
pVirtualSrcAddr = IfslDMA->DMAGetVirtualAddress((APTR)pPhysicalSrcAddr);
pVirtualDestAddr = IfslDMA->DMAGetVirtualAddress(pPhysicalDestAddr);
</syntaxhighlight>

Now that we have the Virtual Address equivalents to the Physical Addresses that were returned by DMAAllocPhysicalMemory(), we can proceed to call the Exec CopyMemQuick() function to complete the copy. Here we can only trust that the IExec->CopyMemQuick() call can not fail since it does not return a result code.

<syntaxhighlight>
IExec->CopyMemQuick(pVirtualSrcAddr,pVirtualDestAddr,lTestSize);
</syntaxhighlight>

==== Cleaning up - Freeing DMA Compliant memory ====

It is essential that you free any memory that was allocated using the DMAAllocPhysicalMemory() function using the corresponding DMAFreePhysicalMemory() call. The reason for this is two-fold; first because additional resource tracking is maintained by the FslDMA API whenever it allocates memory which must itself be released, and second because the ''Physical Address'' to the memory is returned by the allocate call and not the ''Virtual Address'', so if you attempt to pass the address returned by DMAAllocPhysicalMemory() directly into IExec->FreeVec() it would likely result in a crash.

<syntaxhighlight>
IfslDMA->DMAFreePhysicalMemory(pPhysicalSrcAddr);
IfslDMA->DMAFreePhysicalMemory(pPhysicalDestAddr);
</syntaxhighlight>

DMA Resource

2019-11-16T01:48:36Z

Jamie Krueger: /* What a call to perform a DMA copy does internally */

== DMA Engine ==

Some hardware targets include a DMA engine which can be used for general purpose copying. This article describes the DMA engines available and how to use them.

=== Hardware Features ===

The Direct Memory Access (DMA) Engines found in the NXP/Freescale p5020, p5040 and p1022 System On a Chip (SoC)s, as found in the AmigaONE X5000/20, X5000/40 and A1222 respectively, are quite flexible and powerful. Each of these chips contains two distinct engines with four data channels each. This provides the ability to have a total of eight DMA Channels working at once, with up to two DMA transactions actually being executed at the same time (one on each of the two DMA Engines).

Further, each of the four DMA Channels found in a DMA Engine may be individually programmed to handle either; a single transaction, a ''Chain'' of transactions, or even ''Lists'' of ''Chains'' of transactions. The DMA Engines automatically arbitrate control between each DMA Channel following programmed bandwidth settings for each Channel (typically 1024 bytes).

This means that after completing a transfer of 1024 bytes (for example), the hardware will consider switching to the next Channel to allow it to move another block of data, and so on in a round-robin fashion. If all other DMA Channels on a given DMA Engine are idle when arbitration would take place, the hardware will not arbitrate control to another Channel, but simply continue processing the transaction(s) for the Channel it is on.

=== DMA Copy Memory - Execution Flow Diagram ===

[[File:DMACopyMem-Diagram.png]]

=== What a call to perform a DMA copy does internally ===

As shown in the above diagram, when the user makes a call to request a memory copy be performed by the DMA hardware, the next available DMA Channel is selected for use and a DMA Transaction (source, destination and size) is constructed. The DMA Transaction is then programmed into the DMA Engine which owns the available DMA Channel.

At this point the calling task will Wait() until it hears the transaction has been completed. It will then return to the caller with the result. This provides a basic ''blocking'' function, which only returns to the caller once that data has been copied. This single tasking behavior is the simplest to use and what is normally expected by most applications using a memory copy function.

=== Diagram of multitasking DMA Copies ===

[[File:DMACopyMem-Multitasking-Diagram.png]]

=== How multiple simultaneous DMA copies are handled ===

== fsldma.resource ==

The fsldma.resource API is provided automatically in the kernel for all supported machines (Currently the AmigaONE X5000/20, X5000/40 and A1222).

=== The FslDMA API ===

The API provided by the fsldma.resource breaks down into three main parts:
:* Memory management
:* Copy Memory functions
:* Utility / Miscellaneous

==== Memory Management Functions ====

The FslDMA resource API provides convenience functions for the allocation and freeing of '''DMA Compliant''' blocks of memory. Two functions are provided for this purpose; DMAAllocPhysicalMemory() and DMAFreePhysicalMemory().

The memory allocation function also includes two Tags based versions of the call to allow for addition variables to be passed into the call using a variable set of Tags or fixed TagList. Currently the only supported Tag is ''FSLDMA_APM_ClearWithValue'', which is the equivalent to the IExec->AllocVecTagList() function's AVT_ClearWithValue tag. If the FSLDMA_APM_ClearWithValue tag is not provided then the requested memory block is cleared with zeroes by default before being returned. DMAAllocPhysicalMemory() returns the ''Physical'' Address pointer to the allocated memory or NULL if it is unable to allocate the requested memory.

<syntaxhighlight>
APTR DMAAllocPhysicalMemoryTagList( uint32 lSize, const struct TagItem *tags );
APTR DMAAllocPhysicalMemoryTags( uint32 lSize, uint32 Tag1, ... );
APTR DMAAllocPhysicalMemory( uint32 lSize );
</syntaxhighlight>

The corresponding function to allocating a DMA Compliant memory block is DMAFreePhysicalMemory(). Any memory allocated using DMAAllocPhysicalMemory() must be eventually freed using DMAFreePhysicalMemory().

<syntaxhighlight>
void DMAFreePhysicalMemory( APTR pPhysicalMemoryBlock );
</syntaxhighlight>

==== Copy Memory Functions ====

Two API calls make up the core of the FslDMA API; DMAPhysicalCopyMem() and DMACopyMem().
Both of these calls will "block" (not return to the user) until after the requested transfer has either succeeded or failed. A value of TRUE is returned upon success and FALSE if an error occurred.

<syntaxhighlight>
BOOL DMAPhysicalCopyMem( CONST_APTR pPhysicalSourceBuffer, APTR pPhysicalDestBuffer, uint32 lBufferSize );
BOOL DMACopyMem( CONST_APTR pSourceBuffer, APTR pDestBuffer, uint32 lBufferSize );
</syntaxhighlight>

As the name implies the first (and core version) of the copy memory functions, DMAPhysicalCopyMem(), accepts the Physical Addresses to the source and destination buffers (as returned by DMAAllocPhysicalMemory()), along with an unsigned 32-Bit value for the amount of bytes that should be copied (lBuffsize must be greater than zero(0) and no more than the maximum size of the source and destination buffers).

DMAPhysicalCopyMem() is the most direct an efficient means of using the DMA hardware to effect a single memory copy. The DMACopyMem() function is provided as an alternative way to request a DMA transfer by passing in the ''Virtual Addresses'' to the source and destination buffers instead of the Physical Addresses. DMACopyMem() will attempt to determine if the supplied memory buffers are DMA Compliant and if so it will internally use DMAPhysicalCopyMem() to handle the transaction. If DMACopyMem() determines that the supplied memory is '''not''' DMA Compliant it will return FALSE and no data copy will occur.

In theory any ''contiguous'' block of memory from 1 Byte up to 4GB in size may be transferred using either one of these calls. In practice the DMA hardware can directly accept memory blocks up to FSLDMA_MAXBLOCK_SIZE (or 64MB - 1 Byte). Therefore any data blocks greater than FSLDMA_MAXBLOCK_SIZE will automatically be feed to the DMA hardware in a series of smaller chunks. For maximum efficiency transfer sizes should be at least 256 Bytes in size and be an even multiple of 64 Bytes. Odd sizes are handled by the hardware but will degrade performance.

If you are transferring many large blocks of data in series and wish to manually send them to the FslDMA API's memory copy functions one block at a time, then setting your block sizes to FSLDMA_OPTIMAL_BLKSIZE (or 64 MB - 64 Bytes) and exclusively using DMAPhysicalCopyMem() will provide the fastest transfer speeds will the least amount of CPU overhead.

==== Utility / Miscellaneous Functions ====

The last section to the FslDMA API provides a single convenience function call; DMAGetVirtualAddress().

<syntaxhighlight>
APTR DMAGetVirtualAddress( APTR pPhysicalAddress );
</syntaxhighlight>

The DMAGetVirtualAddress() function returns the Virtual memory location for the Physical memory location that was itself allocated and returned by the DMAAllocPhysicalMemory() function. DMAGetVirtualAddress() will not work on physical addresses returned by IMMU->GetPhysicalAddress() on memory not allocated using DMAAllocPhysicalMemory().

The main purpose of this function (other then debugging purposes) is to provide the "normal" Virtual Address of memory allocated by the FslDMA API for use by functions that expect "normal" Virtual address locations; for example IExec->CopyMemQuick().

==== Further reference - The fsldma.resource AutoDoc ====

See the [[http://wiki.amigaos.net/amiga/autodocs/fsldmares.doc.txt fsldma.resource AutoDoc]] file for more details on each API call.

=== Example usage ===
<syntaxhighlight>
#include <interfaces/fsldma.h>
// Obtain the fsldma.resource
struct fslDMAIFace *IfslDMA = IExec->OpenResource(FSLDMA_NAME);
if ( NULL != IfslDMA )
{
uint32 lTestSize = 1024;
CONST_APTR pPhysicalSrcAddr = NULL;
APTR pPhysicalDestAddr = NULL;
// Allocate the Source Buffer (for DMA)
// and set the contents to 0xB3 (just an example value)
pPhysicalSrcAddr = (CONST_APTR)IfslDMA->DMAAllocPhysicalMemoryTags(lTestSize,
FSLDMA_APM_ClearWithValue, 0xB3,
TAG_END);
if ( NULL != pPhysicalSrcAddr )
{
// Allocate the Destination Buffer (for DMA)
// - contents will by cleared by default
pPhysicalDestAddr = IfslDMA->DMAAllocPhysicalMemory(lTestSize);
if ( NULL != pPhysicalDestAddr )
{
// Call IfslDMA->DMAPhysicalCopyMem()
// to perform the memory copy using the DMA hardware
if ( TRUE == IfslDMA->DMAPhysicalCopyMem(pPhysicalSrcAddr,
pPhysicalDestAddr,lTestSize) )
{
// Success - Do something with the copied data
}
else
{
// Fallback and use CPU Copy instead (or do something else)
// Since we allocated the memory buffers using the FslDMA API,
// which returns the Physical address to that memory, and the
// IExec->CopyMemQuick() function expects the Virtual address,
// we first need to obtain the Virtual address for the Physical
// ones (using the FslDMA API again) before we can call our
// fallback copy function.
CONST_APTR pVirtualSrcAddr = NULL;
APTR pVirtualDestAddr = NULL;
pVirtualSrcAddr = IfslDMA->DMAGetVirtualAddress((APTR)pPhysicalSrcAddr);
pVirtualDestAddr = IfslDMA->DMAGetVirtualAddress(pPhysicalDestAddr);
IExec->CopyMemQuick(pVirtualSrcAddr,pVirtualDestAddr,lTestSize);
}
// We *must* use DMAFreePhysicalMemory() to free the memory
// that we allocated with DMAAllocPhysicalMemory()
IfslDMA->DMAFreePhysicalMemory(pPhysicalDestAddr);
}
// We *must* use DMAFreePhysicalMemory() to free the memory
// that we allocated with DMAAllocPhysicalMemory()
IfslDMA->DMAFreePhysicalMemory((APTR)pPhysicalSrcAddr);
}
}
</syntaxhighlight>

==== Obtaining the fsldma.resource ====

Breaking the above example down the first thing we do is include the interface header for the fsldma.resource and obtain the resource itself.

<syntaxhighlight>
#include <interfaces/fsldma.h>
struct fslDMAIFace *IfslDMA = IExec->OpenResource(FSLDMA_NAME);
</syntaxhighlight>

==== Allocating DMA Compliant Memory ====

Once we have successfully obtained the DMA resource we can directly use its API. The next step we need to do is to allocate some memory '''which we know is DMA compliant''' for use by the resource. The easiest way to accomplish this is to use the IfslDMA->DMAAllocPhysicalMemory() function. This will automatically take care of ensuring the memory that is returned is properly aligned, contiguous, cache-inhibited and coherent.

We use the Tags version of the allocate memory function first so we can allocate a block of memory for our source buffer and fill it with some test value (in this case the byte value 0xB3).

<syntaxhighlight>
pPhysicalSrcAddr = (CONST_APTR)IfslDMA->DMAAllocPhysicalMemoryTags(lTestSize,
FSLDMA_APM_ClearWithValue, 0xB3,
TAG_END);
</syntaxhighlight>

We also need a destination buffer for our test. Since it only needs to start out being cleared (filled with zeroes), we can use the simplest form of the allocate memory function here as the allocated memory is cleared by default.

<syntaxhighlight>
pPhysicalDestAddr = IfslDMA->DMAAllocPhysicalMemory(lTestSize);
</syntaxhighlight>

==== The core function - Copy Physical Memory ====

Now that we have two DMA Compliant memory buffers available we can get to the heart of the API usage and make the call to IfslDMA->DMAPhysicalCopyMem().

<syntaxhighlight>
IfslDMA->DMAPhysicalCopyMem(pPhysicalSrcAddr,pPhysicalDestAddr,lTestSize);
</syntaxhighlight>

Looking at the full [[#Example usage|Example]] source above you can see that the DMAPhysicalCopyMem() call returns a Boolean value to indicate success or failure. Therefore, TRUE will be returned after the DMA hardware had completed copying the requested data (blocking call) and FALSE will be returned if a problem occurred.

Since the memory buffers we are using were allocated using the FslDMA API and our transfer size was greater than zero and less than or equal to the total size of either buffer, (in others words a legal copy request), there is '''very''' little chance that the DMAPhysicalCopyMem() function will fail. In fact, about the only reason the DMA hardware would fail to handle a legal transaction would be if the physical RAM installed in the system was faulty.

So even though it is extremely unlikely for our DMA copy to have failed and returned FALSE, let's take a look at how we might handle the failure. In other words, falling back and using a CPU based copy function instead to complete the data move.

Since we are reverting back to using a normal system copy memory function here, we first need to obtain the ''Virtual Addresses'' to both our source and destination buffers. This is accomplished by using the DMAGetVirtualAddress() function and passing in the Physical Address that was returned by DMAAllocPhysicalMemory().

<syntaxhighlight>
CONST_APTR pVirtualSrcAddr = NULL;
APTR pVirtualDestAddr = NULL;
pVirtualSrcAddr = IfslDMA->DMAGetVirtualAddress((APTR)pPhysicalSrcAddr);
pVirtualDestAddr = IfslDMA->DMAGetVirtualAddress(pPhysicalDestAddr);
</syntaxhighlight>

Now that we have the Virtual Address equivalents to the Physical Addresses that were returned by DMAAllocPhysicalMemory(), we can proceed to call the Exec CopyMemQuick() function to complete the copy. Here we can only trust that the IExec->CopyMemQuick() call can not fail since it does not return a result code.

<syntaxhighlight>
IExec->CopyMemQuick(pVirtualSrcAddr,pVirtualDestAddr,lTestSize);
</syntaxhighlight>

==== Cleaning up - Freeing DMA Compliant memory ====

It is essential that you free any memory that was allocated using the DMAAllocPhysicalMemory() function using the corresponding DMAFreePhysicalMemory() call. The reason for this is two-fold; first because additional resource tracking is maintained by the FslDMA API whenever it allocates memory which must itself be released, and second because the ''Physical Address'' to the memory is returned by the allocate call and not the ''Virtual Address'', so if you attempt to pass the address returned by DMAAllocPhysicalMemory() directly into IExec->FreeVec() it would likely result in a crash.

<syntaxhighlight>
IfslDMA->DMAFreePhysicalMemory(pPhysicalSrcAddr);
IfslDMA->DMAFreePhysicalMemory(pPhysicalDestAddr);
</syntaxhighlight>

File:DMACopyMem-Multitasking-Diagram.png

2019-11-16T01:46:38Z

Jamie Krueger: DMA Engine diagram of multiple simultaneous memory copy calls.

DMA Engine diagram of multiple simultaneous memory copy calls.

DMA Resource

2019-11-16T00:19:49Z

Jamie Krueger: /* What a call to perform a DMA copy does internally */

== DMA Engine ==

Some hardware targets include a DMA engine which can be used for general purpose copying. This article describes the DMA engines available and how to use them.

=== Hardware Features ===

The Direct Memory Access (DMA) Engines found in the NXP/Freescale p5020, p5040 and p1022 System On a Chip (SoC)s, as found in the AmigaONE X5000/20, X5000/40 and A1222 respectively, are quite flexible and powerful. Each of these chips contains two distinct engines with four data channels each. This provides the ability to have a total of eight DMA Channels working at once, with up to two DMA transactions actually being executed at the same time (one on each of the two DMA Engines).

Further, each of the four DMA Channels found in a DMA Engine may be individually programmed to handle either; a single transaction, a ''Chain'' of transactions, or even ''Lists'' of ''Chains'' of transactions. The DMA Engines automatically arbitrate control between each DMA Channel following programmed bandwidth settings for each Channel (typically 1024 bytes).

This means that after completing a transfer of 1024 bytes (for example), the hardware will consider switching to the next Channel to allow it to move another block of data, and so on in a round-robin fashion. If all other DMA Channels on a given DMA Engine are idle when arbitration would take place, the hardware will not arbitrate control to another Channel, but simply continue processing the transaction(s) for the Channel it is on.

=== DMA Copy Memory - Execution Flow Diagram ===

[[File:DMACopyMem-Diagram.png]]

=== What a call to perform a DMA copy does internally ===

As shown in the above diagram, when the user makes a call to request a memory copy be performed by the DMA hardware, the next available DMA Channel is selected for use and a DMA Transaction (source, destination and size) is constructed. The DMA Transaction is then programmed into the DMA Engine which owns the available DMA Channel.

At this point the calling task will Wait() until it hears the transaction has been completed. It will then return to the caller with the result. This provides a basic ''blocking'' function, which only returns to the caller once that data has been copied. This single tasking behavior is the simplest to use and what is normally expected by most applications using a memory copy function.

== fsldma.resource ==

The fsldma.resource API is provided automatically in the kernel for all supported machines (Currently the AmigaONE X5000/20, X5000/40 and A1222).

=== The FslDMA API ===

The API provided by the fsldma.resource breaks down into three main parts:
:* Memory management
:* Copy Memory functions
:* Utility / Miscellaneous

==== Memory Management Functions ====

The FslDMA resource API provides convenience functions for the allocation and freeing of '''DMA Compliant''' blocks of memory. Two functions are provided for this purpose; DMAAllocPhysicalMemory() and DMAFreePhysicalMemory().

The memory allocation function also includes two Tags based versions of the call to allow for addition variables to be passed into the call using a variable set of Tags or fixed TagList. Currently the only supported Tag is ''FSLDMA_APM_ClearWithValue'', which is the equivalent to the IExec->AllocVecTagList() function's AVT_ClearWithValue tag. If the FSLDMA_APM_ClearWithValue tag is not provided then the requested memory block is cleared with zeroes by default before being returned. DMAAllocPhysicalMemory() returns the ''Physical'' Address pointer to the allocated memory or NULL if it is unable to allocate the requested memory.

<syntaxhighlight>
APTR DMAAllocPhysicalMemoryTagList( uint32 lSize, const struct TagItem *tags );
APTR DMAAllocPhysicalMemoryTags( uint32 lSize, uint32 Tag1, ... );
APTR DMAAllocPhysicalMemory( uint32 lSize );
</syntaxhighlight>

The corresponding function to allocating a DMA Compliant memory block is DMAFreePhysicalMemory(). Any memory allocated using DMAAllocPhysicalMemory() must be eventually freed using DMAFreePhysicalMemory().

<syntaxhighlight>
void DMAFreePhysicalMemory( APTR pPhysicalMemoryBlock );
</syntaxhighlight>

==== Copy Memory Functions ====

Two API calls make up the core of the FslDMA API; DMAPhysicalCopyMem() and DMACopyMem().
Both of these calls will "block" (not return to the user) until after the requested transfer has either succeeded or failed. A value of TRUE is returned upon success and FALSE if an error occurred.

<syntaxhighlight>
BOOL DMAPhysicalCopyMem( CONST_APTR pPhysicalSourceBuffer, APTR pPhysicalDestBuffer, uint32 lBufferSize );
BOOL DMACopyMem( CONST_APTR pSourceBuffer, APTR pDestBuffer, uint32 lBufferSize );
</syntaxhighlight>

As the name implies the first (and core version) of the copy memory functions, DMAPhysicalCopyMem(), accepts the Physical Addresses to the source and destination buffers (as returned by DMAAllocPhysicalMemory()), along with an unsigned 32-Bit value for the amount of bytes that should be copied (lBuffsize must be greater than zero(0) and no more than the maximum size of the source and destination buffers).

DMAPhysicalCopyMem() is the most direct an efficient means of using the DMA hardware to effect a single memory copy. The DMACopyMem() function is provided as an alternative way to request a DMA transfer by passing in the ''Virtual Addresses'' to the source and destination buffers instead of the Physical Addresses. DMACopyMem() will attempt to determine if the supplied memory buffers are DMA Compliant and if so it will internally use DMAPhysicalCopyMem() to handle the transaction. If DMACopyMem() determines that the supplied memory is '''not''' DMA Compliant it will return FALSE and no data copy will occur.

In theory any ''contiguous'' block of memory from 1 Byte up to 4GB in size may be transferred using either one of these calls. In practice the DMA hardware can directly accept memory blocks up to FSLDMA_MAXBLOCK_SIZE (or 64MB - 1 Byte). Therefore any data blocks greater than FSLDMA_MAXBLOCK_SIZE will automatically be feed to the DMA hardware in a series of smaller chunks. For maximum efficiency transfer sizes should be at least 256 Bytes in size and be an even multiple of 64 Bytes. Odd sizes are handled by the hardware but will degrade performance.

If you are transferring many large blocks of data in series and wish to manually send them to the FslDMA API's memory copy functions one block at a time, then setting your block sizes to FSLDMA_OPTIMAL_BLKSIZE (or 64 MB - 64 Bytes) and exclusively using DMAPhysicalCopyMem() will provide the fastest transfer speeds will the least amount of CPU overhead.

==== Utility / Miscellaneous Functions ====

The last section to the FslDMA API provides a single convenience function call; DMAGetVirtualAddress().

<syntaxhighlight>
APTR DMAGetVirtualAddress( APTR pPhysicalAddress );
</syntaxhighlight>

The DMAGetVirtualAddress() function returns the Virtual memory location for the Physical memory location that was itself allocated and returned by the DMAAllocPhysicalMemory() function. DMAGetVirtualAddress() will not work on physical addresses returned by IMMU->GetPhysicalAddress() on memory not allocated using DMAAllocPhysicalMemory().

The main purpose of this function (other then debugging purposes) is to provide the "normal" Virtual Address of memory allocated by the FslDMA API for use by functions that expect "normal" Virtual address locations; for example IExec->CopyMemQuick().

==== Further reference - The fsldma.resource AutoDoc ====

See the [[http://wiki.amigaos.net/amiga/autodocs/fsldmares.doc.txt fsldma.resource AutoDoc]] file for more details on each API call.

=== Example usage ===
<syntaxhighlight>
#include <interfaces/fsldma.h>
// Obtain the fsldma.resource
struct fslDMAIFace *IfslDMA = IExec->OpenResource(FSLDMA_NAME);
if ( NULL != IfslDMA )
{
uint32 lTestSize = 1024;
CONST_APTR pPhysicalSrcAddr = NULL;
APTR pPhysicalDestAddr = NULL;
// Allocate the Source Buffer (for DMA)
// and set the contents to 0xB3 (just an example value)
pPhysicalSrcAddr = (CONST_APTR)IfslDMA->DMAAllocPhysicalMemoryTags(lTestSize,
FSLDMA_APM_ClearWithValue, 0xB3,
TAG_END);
if ( NULL != pPhysicalSrcAddr )
{
// Allocate the Destination Buffer (for DMA)
// - contents will by cleared by default
pPhysicalDestAddr = IfslDMA->DMAAllocPhysicalMemory(lTestSize);
if ( NULL != pPhysicalDestAddr )
{
// Call IfslDMA->DMAPhysicalCopyMem()
// to perform the memory copy using the DMA hardware
if ( TRUE == IfslDMA->DMAPhysicalCopyMem(pPhysicalSrcAddr,
pPhysicalDestAddr,lTestSize) )
{
// Success - Do something with the copied data
}
else
{
// Fallback and use CPU Copy instead (or do something else)
// Since we allocated the memory buffers using the FslDMA API,
// which returns the Physical address to that memory, and the
// IExec->CopyMemQuick() function expects the Virtual address,
// we first need to obtain the Virtual address for the Physical
// ones (using the FslDMA API again) before we can call our
// fallback copy function.
CONST_APTR pVirtualSrcAddr = NULL;
APTR pVirtualDestAddr = NULL;
pVirtualSrcAddr = IfslDMA->DMAGetVirtualAddress((APTR)pPhysicalSrcAddr);
pVirtualDestAddr = IfslDMA->DMAGetVirtualAddress(pPhysicalDestAddr);
IExec->CopyMemQuick(pVirtualSrcAddr,pVirtualDestAddr,lTestSize);
}
// We *must* use DMAFreePhysicalMemory() to free the memory
// that we allocated with DMAAllocPhysicalMemory()
IfslDMA->DMAFreePhysicalMemory(pPhysicalDestAddr);
}
// We *must* use DMAFreePhysicalMemory() to free the memory
// that we allocated with DMAAllocPhysicalMemory()
IfslDMA->DMAFreePhysicalMemory((APTR)pPhysicalSrcAddr);
}
}
</syntaxhighlight>

==== Obtaining the fsldma.resource ====

Breaking the above example down the first thing we do is include the interface header for the fsldma.resource and obtain the resource itself.

<syntaxhighlight>
#include <interfaces/fsldma.h>
struct fslDMAIFace *IfslDMA = IExec->OpenResource(FSLDMA_NAME);
</syntaxhighlight>

==== Allocating DMA Compliant Memory ====

Once we have successfully obtained the DMA resource we can directly use its API. The next step we need to do is to allocate some memory '''which we know is DMA compliant''' for use by the resource. The easiest way to accomplish this is to use the IfslDMA->DMAAllocPhysicalMemory() function. This will automatically take care of ensuring the memory that is returned is properly aligned, contiguous, cache-inhibited and coherent.

We use the Tags version of the allocate memory function first so we can allocate a block of memory for our source buffer and fill it with some test value (in this case the byte value 0xB3).

<syntaxhighlight>
pPhysicalSrcAddr = (CONST_APTR)IfslDMA->DMAAllocPhysicalMemoryTags(lTestSize,
FSLDMA_APM_ClearWithValue, 0xB3,
TAG_END);
</syntaxhighlight>

We also need a destination buffer for our test. Since it only needs to start out being cleared (filled with zeroes), we can use the simplest form of the allocate memory function here as the allocated memory is cleared by default.

<syntaxhighlight>
pPhysicalDestAddr = IfslDMA->DMAAllocPhysicalMemory(lTestSize);
</syntaxhighlight>

==== The core function - Copy Physical Memory ====

Now that we have two DMA Compliant memory buffers available we can get to the heart of the API usage and make the call to IfslDMA->DMAPhysicalCopyMem().

<syntaxhighlight>
IfslDMA->DMAPhysicalCopyMem(pPhysicalSrcAddr,pPhysicalDestAddr,lTestSize);
</syntaxhighlight>

Looking at the full [[#Example usage|Example]] source above you can see that the DMAPhysicalCopyMem() call returns a Boolean value to indicate success or failure. Therefore, TRUE will be returned after the DMA hardware had completed copying the requested data (blocking call) and FALSE will be returned if a problem occurred.

Since the memory buffers we are using were allocated using the FslDMA API and our transfer size was greater than zero and less than or equal to the total size of either buffer, (in others words a legal copy request), there is '''very''' little chance that the DMAPhysicalCopyMem() function will fail. In fact, about the only reason the DMA hardware would fail to handle a legal transaction would be if the physical RAM installed in the system was faulty.

So even though it is extremely unlikely for our DMA copy to have failed and returned FALSE, let's take a look at how we might handle the failure. In other words, falling back and using a CPU based copy function instead to complete the data move.

Since we are reverting back to using a normal system copy memory function here, we first need to obtain the ''Virtual Addresses'' to both our source and destination buffers. This is accomplished by using the DMAGetVirtualAddress() function and passing in the Physical Address that was returned by DMAAllocPhysicalMemory().

<syntaxhighlight>
CONST_APTR pVirtualSrcAddr = NULL;
APTR pVirtualDestAddr = NULL;
pVirtualSrcAddr = IfslDMA->DMAGetVirtualAddress((APTR)pPhysicalSrcAddr);
pVirtualDestAddr = IfslDMA->DMAGetVirtualAddress(pPhysicalDestAddr);
</syntaxhighlight>

Now that we have the Virtual Address equivalents to the Physical Addresses that were returned by DMAAllocPhysicalMemory(), we can proceed to call the Exec CopyMemQuick() function to complete the copy. Here we can only trust that the IExec->CopyMemQuick() call can not fail since it does not return a result code.

<syntaxhighlight>
IExec->CopyMemQuick(pVirtualSrcAddr,pVirtualDestAddr,lTestSize);
</syntaxhighlight>

==== Cleaning up - Freeing DMA Compliant memory ====

It is essential that you free any memory that was allocated using the DMAAllocPhysicalMemory() function using the corresponding DMAFreePhysicalMemory() call. The reason for this is two-fold; first because additional resource tracking is maintained by the FslDMA API whenever it allocates memory which must itself be released, and second because the ''Physical Address'' to the memory is returned by the allocate call and not the ''Virtual Address'', so if you attempt to pass the address returned by DMAAllocPhysicalMemory() directly into IExec->FreeVec() it would likely result in a crash.

<syntaxhighlight>
IfslDMA->DMAFreePhysicalMemory(pPhysicalSrcAddr);
IfslDMA->DMAFreePhysicalMemory(pPhysicalDestAddr);
</syntaxhighlight>

DMA Resource

2019-11-16T00:16:06Z

Jamie Krueger: /* DMA Copy Memory - Execution Flow Diagram */

== DMA Engine ==

Some hardware targets include a DMA engine which can be used for general purpose copying. This article describes the DMA engines available and how to use them.

=== Hardware Features ===

The Direct Memory Access (DMA) Engines found in the NXP/Freescale p5020, p5040 and p1022 System On a Chip (SoC)s, as found in the AmigaONE X5000/20, X5000/40 and A1222 respectively, are quite flexible and powerful. Each of these chips contains two distinct engines with four data channels each. This provides the ability to have a total of eight DMA Channels working at once, with up to two DMA transactions actually being executed at the same time (one on each of the two DMA Engines).

Further, each of the four DMA Channels found in a DMA Engine may be individually programmed to handle either; a single transaction, a ''Chain'' of transactions, or even ''Lists'' of ''Chains'' of transactions. The DMA Engines automatically arbitrate control between each DMA Channel following programmed bandwidth settings for each Channel (typically 1024 bytes).

This means that after completing a transfer of 1024 bytes (for example), the hardware will consider switching to the next Channel to allow it to move another block of data, and so on in a round-robin fashion. If all other DMA Channels on a given DMA Engine are idle when arbitration would take place, the hardware will not arbitrate control to another Channel, but simply continue processing the transaction(s) for the Channel it is on.

=== DMA Copy Memory - Execution Flow Diagram ===

[[File:DMACopyMem-Diagram.png]]

=== What a call to perform a DMA copy does internally ===

As shown in the above diagram, when the user makes a call to request a memory copy be performed by the DMA hardware, the next available DMA Channel is selected for use and a DMA Transaction (source, destination and size) is constructed. The DMA Transaction is then programmed into the DMA Engine which owns the available DMA Channel.

At this point the calling task will Wait() until it hears the transaction has been completed. It will then return to the caller with the result.

== fsldma.resource ==

The fsldma.resource API is provided automatically in the kernel for all supported machines (Currently the AmigaONE X5000/20, X5000/40 and A1222).

=== The FslDMA API ===

The API provided by the fsldma.resource breaks down into three main parts:
:* Memory management
:* Copy Memory functions
:* Utility / Miscellaneous

==== Memory Management Functions ====

The FslDMA resource API provides convenience functions for the allocation and freeing of '''DMA Compliant''' blocks of memory. Two functions are provided for this purpose; DMAAllocPhysicalMemory() and DMAFreePhysicalMemory().

The memory allocation function also includes two Tags based versions of the call to allow for addition variables to be passed into the call using a variable set of Tags or fixed TagList. Currently the only supported Tag is ''FSLDMA_APM_ClearWithValue'', which is the equivalent to the IExec->AllocVecTagList() function's AVT_ClearWithValue tag. If the FSLDMA_APM_ClearWithValue tag is not provided then the requested memory block is cleared with zeroes by default before being returned. DMAAllocPhysicalMemory() returns the ''Physical'' Address pointer to the allocated memory or NULL if it is unable to allocate the requested memory.

<syntaxhighlight>
APTR DMAAllocPhysicalMemoryTagList( uint32 lSize, const struct TagItem *tags );
APTR DMAAllocPhysicalMemoryTags( uint32 lSize, uint32 Tag1, ... );
APTR DMAAllocPhysicalMemory( uint32 lSize );
</syntaxhighlight>

The corresponding function to allocating a DMA Compliant memory block is DMAFreePhysicalMemory(). Any memory allocated using DMAAllocPhysicalMemory() must be eventually freed using DMAFreePhysicalMemory().

<syntaxhighlight>
void DMAFreePhysicalMemory( APTR pPhysicalMemoryBlock );
</syntaxhighlight>

==== Copy Memory Functions ====

Two API calls make up the core of the FslDMA API; DMAPhysicalCopyMem() and DMACopyMem().
Both of these calls will "block" (not return to the user) until after the requested transfer has either succeeded or failed. A value of TRUE is returned upon success and FALSE if an error occurred.

<syntaxhighlight>
BOOL DMAPhysicalCopyMem( CONST_APTR pPhysicalSourceBuffer, APTR pPhysicalDestBuffer, uint32 lBufferSize );
BOOL DMACopyMem( CONST_APTR pSourceBuffer, APTR pDestBuffer, uint32 lBufferSize );
</syntaxhighlight>

As the name implies the first (and core version) of the copy memory functions, DMAPhysicalCopyMem(), accepts the Physical Addresses to the source and destination buffers (as returned by DMAAllocPhysicalMemory()), along with an unsigned 32-Bit value for the amount of bytes that should be copied (lBuffsize must be greater than zero(0) and no more than the maximum size of the source and destination buffers).

DMAPhysicalCopyMem() is the most direct an efficient means of using the DMA hardware to effect a single memory copy. The DMACopyMem() function is provided as an alternative way to request a DMA transfer by passing in the ''Virtual Addresses'' to the source and destination buffers instead of the Physical Addresses. DMACopyMem() will attempt to determine if the supplied memory buffers are DMA Compliant and if so it will internally use DMAPhysicalCopyMem() to handle the transaction. If DMACopyMem() determines that the supplied memory is '''not''' DMA Compliant it will return FALSE and no data copy will occur.

In theory any ''contiguous'' block of memory from 1 Byte up to 4GB in size may be transferred using either one of these calls. In practice the DMA hardware can directly accept memory blocks up to FSLDMA_MAXBLOCK_SIZE (or 64MB - 1 Byte). Therefore any data blocks greater than FSLDMA_MAXBLOCK_SIZE will automatically be feed to the DMA hardware in a series of smaller chunks. For maximum efficiency transfer sizes should be at least 256 Bytes in size and be an even multiple of 64 Bytes. Odd sizes are handled by the hardware but will degrade performance.

If you are transferring many large blocks of data in series and wish to manually send them to the FslDMA API's memory copy functions one block at a time, then setting your block sizes to FSLDMA_OPTIMAL_BLKSIZE (or 64 MB - 64 Bytes) and exclusively using DMAPhysicalCopyMem() will provide the fastest transfer speeds will the least amount of CPU overhead.

==== Utility / Miscellaneous Functions ====

The last section to the FslDMA API provides a single convenience function call; DMAGetVirtualAddress().

<syntaxhighlight>
APTR DMAGetVirtualAddress( APTR pPhysicalAddress );
</syntaxhighlight>

The DMAGetVirtualAddress() function returns the Virtual memory location for the Physical memory location that was itself allocated and returned by the DMAAllocPhysicalMemory() function. DMAGetVirtualAddress() will not work on physical addresses returned by IMMU->GetPhysicalAddress() on memory not allocated using DMAAllocPhysicalMemory().

The main purpose of this function (other then debugging purposes) is to provide the "normal" Virtual Address of memory allocated by the FslDMA API for use by functions that expect "normal" Virtual address locations; for example IExec->CopyMemQuick().

==== Further reference - The fsldma.resource AutoDoc ====

See the [[http://wiki.amigaos.net/amiga/autodocs/fsldmares.doc.txt fsldma.resource AutoDoc]] file for more details on each API call.

=== Example usage ===
<syntaxhighlight>
#include <interfaces/fsldma.h>
// Obtain the fsldma.resource
struct fslDMAIFace *IfslDMA = IExec->OpenResource(FSLDMA_NAME);
if ( NULL != IfslDMA )
{
uint32 lTestSize = 1024;
CONST_APTR pPhysicalSrcAddr = NULL;
APTR pPhysicalDestAddr = NULL;
// Allocate the Source Buffer (for DMA)
// and set the contents to 0xB3 (just an example value)
pPhysicalSrcAddr = (CONST_APTR)IfslDMA->DMAAllocPhysicalMemoryTags(lTestSize,
FSLDMA_APM_ClearWithValue, 0xB3,
TAG_END);
if ( NULL != pPhysicalSrcAddr )
{
// Allocate the Destination Buffer (for DMA)
// - contents will by cleared by default
pPhysicalDestAddr = IfslDMA->DMAAllocPhysicalMemory(lTestSize);
if ( NULL != pPhysicalDestAddr )
{
// Call IfslDMA->DMAPhysicalCopyMem()
// to perform the memory copy using the DMA hardware
if ( TRUE == IfslDMA->DMAPhysicalCopyMem(pPhysicalSrcAddr,
pPhysicalDestAddr,lTestSize) )
{
// Success - Do something with the copied data
}
else
{
// Fallback and use CPU Copy instead (or do something else)
// Since we allocated the memory buffers using the FslDMA API,
// which returns the Physical address to that memory, and the
// IExec->CopyMemQuick() function expects the Virtual address,
// we first need to obtain the Virtual address for the Physical
// ones (using the FslDMA API again) before we can call our
// fallback copy function.
CONST_APTR pVirtualSrcAddr = NULL;
APTR pVirtualDestAddr = NULL;
pVirtualSrcAddr = IfslDMA->DMAGetVirtualAddress((APTR)pPhysicalSrcAddr);
pVirtualDestAddr = IfslDMA->DMAGetVirtualAddress(pPhysicalDestAddr);
IExec->CopyMemQuick(pVirtualSrcAddr,pVirtualDestAddr,lTestSize);
}
// We *must* use DMAFreePhysicalMemory() to free the memory
// that we allocated with DMAAllocPhysicalMemory()
IfslDMA->DMAFreePhysicalMemory(pPhysicalDestAddr);
}
// We *must* use DMAFreePhysicalMemory() to free the memory
// that we allocated with DMAAllocPhysicalMemory()
IfslDMA->DMAFreePhysicalMemory((APTR)pPhysicalSrcAddr);
}
}
</syntaxhighlight>

==== Obtaining the fsldma.resource ====

Breaking the above example down the first thing we do is include the interface header for the fsldma.resource and obtain the resource itself.

<syntaxhighlight>
#include <interfaces/fsldma.h>
struct fslDMAIFace *IfslDMA = IExec->OpenResource(FSLDMA_NAME);
</syntaxhighlight>

==== Allocating DMA Compliant Memory ====

Once we have successfully obtained the DMA resource we can directly use its API. The next step we need to do is to allocate some memory '''which we know is DMA compliant''' for use by the resource. The easiest way to accomplish this is to use the IfslDMA->DMAAllocPhysicalMemory() function. This will automatically take care of ensuring the memory that is returned is properly aligned, contiguous, cache-inhibited and coherent.

We use the Tags version of the allocate memory function first so we can allocate a block of memory for our source buffer and fill it with some test value (in this case the byte value 0xB3).

<syntaxhighlight>
pPhysicalSrcAddr = (CONST_APTR)IfslDMA->DMAAllocPhysicalMemoryTags(lTestSize,
FSLDMA_APM_ClearWithValue, 0xB3,
TAG_END);
</syntaxhighlight>

We also need a destination buffer for our test. Since it only needs to start out being cleared (filled with zeroes), we can use the simplest form of the allocate memory function here as the allocated memory is cleared by default.

<syntaxhighlight>
pPhysicalDestAddr = IfslDMA->DMAAllocPhysicalMemory(lTestSize);
</syntaxhighlight>

==== The core function - Copy Physical Memory ====

Now that we have two DMA Compliant memory buffers available we can get to the heart of the API usage and make the call to IfslDMA->DMAPhysicalCopyMem().

<syntaxhighlight>
IfslDMA->DMAPhysicalCopyMem(pPhysicalSrcAddr,pPhysicalDestAddr,lTestSize);
</syntaxhighlight>

Looking at the full [[#Example usage|Example]] source above you can see that the DMAPhysicalCopyMem() call returns a Boolean value to indicate success or failure. Therefore, TRUE will be returned after the DMA hardware had completed copying the requested data (blocking call) and FALSE will be returned if a problem occurred.

Since the memory buffers we are using were allocated using the FslDMA API and our transfer size was greater than zero and less than or equal to the total size of either buffer, (in others words a legal copy request), there is '''very''' little chance that the DMAPhysicalCopyMem() function will fail. In fact, about the only reason the DMA hardware would fail to handle a legal transaction would be if the physical RAM installed in the system was faulty.

So even though it is extremely unlikely for our DMA copy to have failed and returned FALSE, let's take a look at how we might handle the failure. In other words, falling back and using a CPU based copy function instead to complete the data move.

Since we are reverting back to using a normal system copy memory function here, we first need to obtain the ''Virtual Addresses'' to both our source and destination buffers. This is accomplished by using the DMAGetVirtualAddress() function and passing in the Physical Address that was returned by DMAAllocPhysicalMemory().

<syntaxhighlight>
CONST_APTR pVirtualSrcAddr = NULL;
APTR pVirtualDestAddr = NULL;
pVirtualSrcAddr = IfslDMA->DMAGetVirtualAddress((APTR)pPhysicalSrcAddr);
pVirtualDestAddr = IfslDMA->DMAGetVirtualAddress(pPhysicalDestAddr);
</syntaxhighlight>

Now that we have the Virtual Address equivalents to the Physical Addresses that were returned by DMAAllocPhysicalMemory(), we can proceed to call the Exec CopyMemQuick() function to complete the copy. Here we can only trust that the IExec->CopyMemQuick() call can not fail since it does not return a result code.

<syntaxhighlight>
IExec->CopyMemQuick(pVirtualSrcAddr,pVirtualDestAddr,lTestSize);
</syntaxhighlight>

==== Cleaning up - Freeing DMA Compliant memory ====

It is essential that you free any memory that was allocated using the DMAAllocPhysicalMemory() function using the corresponding DMAFreePhysicalMemory() call. The reason for this is two-fold; first because additional resource tracking is maintained by the FslDMA API whenever it allocates memory which must itself be released, and second because the ''Physical Address'' to the memory is returned by the allocate call and not the ''Virtual Address'', so if you attempt to pass the address returned by DMAAllocPhysicalMemory() directly into IExec->FreeVec() it would likely result in a crash.

<syntaxhighlight>
IfslDMA->DMAFreePhysicalMemory(pPhysicalSrcAddr);
IfslDMA->DMAFreePhysicalMemory(pPhysicalDestAddr);
</syntaxhighlight>

DMA Resource

2019-11-16T00:02:36Z

Jamie Krueger:

== DMA Engine ==

Some hardware targets include a DMA engine which can be used for general purpose copying. This article describes the DMA engines available and how to use them.

=== Hardware Features ===

The Direct Memory Access (DMA) Engines found in the NXP/Freescale p5020, p5040 and p1022 System On a Chip (SoC)s, as found in the AmigaONE X5000/20, X5000/40 and A1222 respectively, are quite flexible and powerful. Each of these chips contains two distinct engines with four data channels each. This provides the ability to have a total of eight DMA Channels working at once, with up to two DMA transactions actually being executed at the same time (one on each of the two DMA Engines).

Further, each of the four DMA Channels found in a DMA Engine may be individually programmed to handle either; a single transaction, a ''Chain'' of transactions, or even ''Lists'' of ''Chains'' of transactions. The DMA Engines automatically arbitrate control between each DMA Channel following programmed bandwidth settings for each Channel (typically 1024 bytes).

This means that after completing a transfer of 1024 bytes (for example), the hardware will consider switching to the next Channel to allow it to move another block of data, and so on in a round-robin fashion. If all other DMA Channels on a given DMA Engine are idle when arbitration would take place, the hardware will not arbitrate control to another Channel, but simply continue processing the transaction(s) for the Channel it is on.

=== DMA Copy Memory - Execution Flow Diagram ===

[[File:DMACopyMem-Diagram.png]]

== fsldma.resource ==

The fsldma.resource API is provided automatically in the kernel for all supported machines (Currently the AmigaONE X5000/20, X5000/40 and A1222).

=== The FslDMA API ===

The API provided by the fsldma.resource breaks down into three main parts:
:* Memory management
:* Copy Memory functions
:* Utility / Miscellaneous

==== Memory Management Functions ====

The FslDMA resource API provides convenience functions for the allocation and freeing of '''DMA Compliant''' blocks of memory. Two functions are provided for this purpose; DMAAllocPhysicalMemory() and DMAFreePhysicalMemory().

The memory allocation function also includes two Tags based versions of the call to allow for addition variables to be passed into the call using a variable set of Tags or fixed TagList. Currently the only supported Tag is ''FSLDMA_APM_ClearWithValue'', which is the equivalent to the IExec->AllocVecTagList() function's AVT_ClearWithValue tag. If the FSLDMA_APM_ClearWithValue tag is not provided then the requested memory block is cleared with zeroes by default before being returned. DMAAllocPhysicalMemory() returns the ''Physical'' Address pointer to the allocated memory or NULL if it is unable to allocate the requested memory.

<syntaxhighlight>
APTR DMAAllocPhysicalMemoryTagList( uint32 lSize, const struct TagItem *tags );
APTR DMAAllocPhysicalMemoryTags( uint32 lSize, uint32 Tag1, ... );
APTR DMAAllocPhysicalMemory( uint32 lSize );
</syntaxhighlight>

The corresponding function to allocating a DMA Compliant memory block is DMAFreePhysicalMemory(). Any memory allocated using DMAAllocPhysicalMemory() must be eventually freed using DMAFreePhysicalMemory().

<syntaxhighlight>
void DMAFreePhysicalMemory( APTR pPhysicalMemoryBlock );
</syntaxhighlight>

==== Copy Memory Functions ====

Two API calls make up the core of the FslDMA API; DMAPhysicalCopyMem() and DMACopyMem().
Both of these calls will "block" (not return to the user) until after the requested transfer has either succeeded or failed. A value of TRUE is returned upon success and FALSE if an error occurred.

<syntaxhighlight>
BOOL DMAPhysicalCopyMem( CONST_APTR pPhysicalSourceBuffer, APTR pPhysicalDestBuffer, uint32 lBufferSize );
BOOL DMACopyMem( CONST_APTR pSourceBuffer, APTR pDestBuffer, uint32 lBufferSize );
</syntaxhighlight>

As the name implies the first (and core version) of the copy memory functions, DMAPhysicalCopyMem(), accepts the Physical Addresses to the source and destination buffers (as returned by DMAAllocPhysicalMemory()), along with an unsigned 32-Bit value for the amount of bytes that should be copied (lBuffsize must be greater than zero(0) and no more than the maximum size of the source and destination buffers).

DMAPhysicalCopyMem() is the most direct an efficient means of using the DMA hardware to effect a single memory copy. The DMACopyMem() function is provided as an alternative way to request a DMA transfer by passing in the ''Virtual Addresses'' to the source and destination buffers instead of the Physical Addresses. DMACopyMem() will attempt to determine if the supplied memory buffers are DMA Compliant and if so it will internally use DMAPhysicalCopyMem() to handle the transaction. If DMACopyMem() determines that the supplied memory is '''not''' DMA Compliant it will return FALSE and no data copy will occur.

In theory any ''contiguous'' block of memory from 1 Byte up to 4GB in size may be transferred using either one of these calls. In practice the DMA hardware can directly accept memory blocks up to FSLDMA_MAXBLOCK_SIZE (or 64MB - 1 Byte). Therefore any data blocks greater than FSLDMA_MAXBLOCK_SIZE will automatically be feed to the DMA hardware in a series of smaller chunks. For maximum efficiency transfer sizes should be at least 256 Bytes in size and be an even multiple of 64 Bytes. Odd sizes are handled by the hardware but will degrade performance.

If you are transferring many large blocks of data in series and wish to manually send them to the FslDMA API's memory copy functions one block at a time, then setting your block sizes to FSLDMA_OPTIMAL_BLKSIZE (or 64 MB - 64 Bytes) and exclusively using DMAPhysicalCopyMem() will provide the fastest transfer speeds will the least amount of CPU overhead.

==== Utility / Miscellaneous Functions ====

The last section to the FslDMA API provides a single convenience function call; DMAGetVirtualAddress().

<syntaxhighlight>
APTR DMAGetVirtualAddress( APTR pPhysicalAddress );
</syntaxhighlight>

The DMAGetVirtualAddress() function returns the Virtual memory location for the Physical memory location that was itself allocated and returned by the DMAAllocPhysicalMemory() function. DMAGetVirtualAddress() will not work on physical addresses returned by IMMU->GetPhysicalAddress() on memory not allocated using DMAAllocPhysicalMemory().

The main purpose of this function (other then debugging purposes) is to provide the "normal" Virtual Address of memory allocated by the FslDMA API for use by functions that expect "normal" Virtual address locations; for example IExec->CopyMemQuick().

==== Further reference - The fsldma.resource AutoDoc ====

See the [[http://wiki.amigaos.net/amiga/autodocs/fsldmares.doc.txt fsldma.resource AutoDoc]] file for more details on each API call.

=== Example usage ===
<syntaxhighlight>
#include <interfaces/fsldma.h>
// Obtain the fsldma.resource
struct fslDMAIFace *IfslDMA = IExec->OpenResource(FSLDMA_NAME);
if ( NULL != IfslDMA )
{
uint32 lTestSize = 1024;
CONST_APTR pPhysicalSrcAddr = NULL;
APTR pPhysicalDestAddr = NULL;
// Allocate the Source Buffer (for DMA)
// and set the contents to 0xB3 (just an example value)
pPhysicalSrcAddr = (CONST_APTR)IfslDMA->DMAAllocPhysicalMemoryTags(lTestSize,
FSLDMA_APM_ClearWithValue, 0xB3,
TAG_END);
if ( NULL != pPhysicalSrcAddr )
{
// Allocate the Destination Buffer (for DMA)
// - contents will by cleared by default
pPhysicalDestAddr = IfslDMA->DMAAllocPhysicalMemory(lTestSize);
if ( NULL != pPhysicalDestAddr )
{
// Call IfslDMA->DMAPhysicalCopyMem()
// to perform the memory copy using the DMA hardware
if ( TRUE == IfslDMA->DMAPhysicalCopyMem(pPhysicalSrcAddr,
pPhysicalDestAddr,lTestSize) )
{
// Success - Do something with the copied data
}
else
{
// Fallback and use CPU Copy instead (or do something else)
// Since we allocated the memory buffers using the FslDMA API,
// which returns the Physical address to that memory, and the
// IExec->CopyMemQuick() function expects the Virtual address,
// we first need to obtain the Virtual address for the Physical
// ones (using the FslDMA API again) before we can call our
// fallback copy function.
CONST_APTR pVirtualSrcAddr = NULL;
APTR pVirtualDestAddr = NULL;
pVirtualSrcAddr = IfslDMA->DMAGetVirtualAddress((APTR)pPhysicalSrcAddr);
pVirtualDestAddr = IfslDMA->DMAGetVirtualAddress(pPhysicalDestAddr);
IExec->CopyMemQuick(pVirtualSrcAddr,pVirtualDestAddr,lTestSize);
}
// We *must* use DMAFreePhysicalMemory() to free the memory
// that we allocated with DMAAllocPhysicalMemory()
IfslDMA->DMAFreePhysicalMemory(pPhysicalDestAddr);
}
// We *must* use DMAFreePhysicalMemory() to free the memory
// that we allocated with DMAAllocPhysicalMemory()
IfslDMA->DMAFreePhysicalMemory((APTR)pPhysicalSrcAddr);
}
}
</syntaxhighlight>

==== Obtaining the fsldma.resource ====

Breaking the above example down the first thing we do is include the interface header for the fsldma.resource and obtain the resource itself.

<syntaxhighlight>
#include <interfaces/fsldma.h>
struct fslDMAIFace *IfslDMA = IExec->OpenResource(FSLDMA_NAME);
</syntaxhighlight>

==== Allocating DMA Compliant Memory ====

Once we have successfully obtained the DMA resource we can directly use its API. The next step we need to do is to allocate some memory '''which we know is DMA compliant''' for use by the resource. The easiest way to accomplish this is to use the IfslDMA->DMAAllocPhysicalMemory() function. This will automatically take care of ensuring the memory that is returned is properly aligned, contiguous, cache-inhibited and coherent.

We use the Tags version of the allocate memory function first so we can allocate a block of memory for our source buffer and fill it with some test value (in this case the byte value 0xB3).

<syntaxhighlight>
pPhysicalSrcAddr = (CONST_APTR)IfslDMA->DMAAllocPhysicalMemoryTags(lTestSize,
FSLDMA_APM_ClearWithValue, 0xB3,
TAG_END);
</syntaxhighlight>

We also need a destination buffer for our test. Since it only needs to start out being cleared (filled with zeroes), we can use the simplest form of the allocate memory function here as the allocated memory is cleared by default.

<syntaxhighlight>
pPhysicalDestAddr = IfslDMA->DMAAllocPhysicalMemory(lTestSize);
</syntaxhighlight>

==== The core function - Copy Physical Memory ====

Now that we have two DMA Compliant memory buffers available we can get to the heart of the API usage and make the call to IfslDMA->DMAPhysicalCopyMem().

<syntaxhighlight>
IfslDMA->DMAPhysicalCopyMem(pPhysicalSrcAddr,pPhysicalDestAddr,lTestSize);
</syntaxhighlight>

Looking at the full [[#Example usage|Example]] source above you can see that the DMAPhysicalCopyMem() call returns a Boolean value to indicate success or failure. Therefore, TRUE will be returned after the DMA hardware had completed copying the requested data (blocking call) and FALSE will be returned if a problem occurred.

Since the memory buffers we are using were allocated using the FslDMA API and our transfer size was greater than zero and less than or equal to the total size of either buffer, (in others words a legal copy request), there is '''very''' little chance that the DMAPhysicalCopyMem() function will fail. In fact, about the only reason the DMA hardware would fail to handle a legal transaction would be if the physical RAM installed in the system was faulty.

So even though it is extremely unlikely for our DMA copy to have failed and returned FALSE, let's take a look at how we might handle the failure. In other words, falling back and using a CPU based copy function instead to complete the data move.

Since we are reverting back to using a normal system copy memory function here, we first need to obtain the ''Virtual Addresses'' to both our source and destination buffers. This is accomplished by using the DMAGetVirtualAddress() function and passing in the Physical Address that was returned by DMAAllocPhysicalMemory().

<syntaxhighlight>
CONST_APTR pVirtualSrcAddr = NULL;
APTR pVirtualDestAddr = NULL;
pVirtualSrcAddr = IfslDMA->DMAGetVirtualAddress((APTR)pPhysicalSrcAddr);
pVirtualDestAddr = IfslDMA->DMAGetVirtualAddress(pPhysicalDestAddr);
</syntaxhighlight>

Now that we have the Virtual Address equivalents to the Physical Addresses that were returned by DMAAllocPhysicalMemory(), we can proceed to call the Exec CopyMemQuick() function to complete the copy. Here we can only trust that the IExec->CopyMemQuick() call can not fail since it does not return a result code.

<syntaxhighlight>
IExec->CopyMemQuick(pVirtualSrcAddr,pVirtualDestAddr,lTestSize);
</syntaxhighlight>

==== Cleaning up - Freeing DMA Compliant memory ====

It is essential that you free any memory that was allocated using the DMAAllocPhysicalMemory() function using the corresponding DMAFreePhysicalMemory() call. The reason for this is two-fold; first because additional resource tracking is maintained by the FslDMA API whenever it allocates memory which must itself be released, and second because the ''Physical Address'' to the memory is returned by the allocate call and not the ''Virtual Address'', so if you attempt to pass the address returned by DMAAllocPhysicalMemory() directly into IExec->FreeVec() it would likely result in a crash.

<syntaxhighlight>
IfslDMA->DMAFreePhysicalMemory(pPhysicalSrcAddr);
IfslDMA->DMAFreePhysicalMemory(pPhysicalDestAddr);
</syntaxhighlight>

File:DMACopyMem-Diagram.png

2019-11-16T00:00:01Z

Jamie Krueger: Jamie Krueger uploaded a new version of File:DMACopyMem-Diagram.png

Diagram of DMA Engine's Copy Memory function (execution flow)

File:DMACopyMem-Diagram.png

2019-11-15T23:38:57Z

Jamie Krueger: Diagram of DMA Engine's Copy Memory function (execution flow)

Diagram of DMA Engine's Copy Memory function (execution flow)

DMA Resource

2019-11-13T02:17:23Z

Jamie Krueger: /* Obtaining the fsldma.resource */

== DMA Engine ==

Some hardware targets include a DMA engine which can be used for general purpose copying. This article describes the DMA engines available and how to use them.

=== Hardware Features ===

The Direct Memory Access (DMA) Engines found in the NXP/Freescale p5020, p5040 and p1022 System On a Chip (SoC)s, as found in the AmigaONE X5000/20, X5000/40 and A1222 respectively, are quite flexible and powerful. Each of these chips contains two distinct engines with four data channels each. This provides the ability to have a total of eight DMA Channels working at once, with up to two DMA transactions actually being executed at the same time (one on each of the two DMA Engines).

Further, each of the four DMA Channels found in a DMA Engine may be individually programmed to handle either; a single transaction, a ''Chain'' of transactions, or even ''Lists'' of ''Chains'' of transactions. The DMA Engines automatically arbitrate control between each DMA Channel following programmed bandwidth settings for each Channel (typically 1024 bytes).

This means that after completing a transfer of 1024 bytes (for example), the hardware will consider switching to the next Channel to allow it to move another block of data, and so on in a round-robin fashion. If all other DMA Channels on a given DMA Engine are idle when arbitration would take place, the hardware will not arbitrate control to another Channel, but simply continue processing the transaction(s) for the Channel it is on.

== fsldma.resource ==

The fsldma.resource API is provided automatically in the kernel for all supported machines (Currently the AmigaONE X5000/20, X5000/40 and A1222).

=== The FslDMA API ===

The API provided by the fsldma.resource breaks down into three main parts:
:* Memory management
:* Copy Memory functions
:* Utility / Miscellaneous

==== Memory Management Functions ====

The FslDMA resource API provides convenience functions for the allocation and freeing of '''DMA Compliant''' blocks of memory. Two functions are provided for this purpose; DMAAllocPhysicalMemory() and DMAFreePhysicalMemory().

The memory allocation function also includes two Tags based versions of the call to allow for addition variables to be passed into the call using a variable set of Tags or fixed TagList. Currently the only supported Tag is ''FSLDMA_APM_ClearWithValue'', which is the equivalent to the IExec->AllocVecTagList() function's AVT_ClearWithValue tag. If the FSLDMA_APM_ClearWithValue tag is not provided then the requested memory block is cleared with zeroes by default before being returned. DMAAllocPhysicalMemory() returns the ''Physical'' Address pointer to the allocated memory or NULL if it is unable to allocate the requested memory.

<syntaxhighlight>
APTR DMAAllocPhysicalMemoryTagList( uint32 lSize, const struct TagItem *tags );
APTR DMAAllocPhysicalMemoryTags( uint32 lSize, uint32 Tag1, ... );
APTR DMAAllocPhysicalMemory( uint32 lSize );
</syntaxhighlight>

The corresponding function to allocating a DMA Compliant memory block is DMAFreePhysicalMemory(). Any memory allocated using DMAAllocPhysicalMemory() must be eventually freed using DMAFreePhysicalMemory().

<syntaxhighlight>
void DMAFreePhysicalMemory( APTR pPhysicalMemoryBlock );
</syntaxhighlight>

==== Copy Memory Functions ====

Two API calls make up the core of the FslDMA API; DMAPhysicalCopyMem() and DMACopyMem().
Both of these calls will "block" (not return to the user) until after the requested transfer has either succeeded or failed. A value of TRUE is returned upon success and FALSE if an error occurred.

<syntaxhighlight>
BOOL DMAPhysicalCopyMem( CONST_APTR pPhysicalSourceBuffer, APTR pPhysicalDestBuffer, uint32 lBufferSize );
BOOL DMACopyMem( CONST_APTR pSourceBuffer, APTR pDestBuffer, uint32 lBufferSize );
</syntaxhighlight>

As the name implies the first (and core version) of the copy memory functions, DMAPhysicalCopyMem(), accepts the Physical Addresses to the source and destination buffers (as returned by DMAAllocPhysicalMemory()), along with an unsigned 32-Bit value for the amount of bytes that should be copied (lBuffsize must be greater than zero(0) and no more than the maximum size of the source and destination buffers).

DMAPhysicalCopyMem() is the most direct an efficient means of using the DMA hardware to effect a single memory copy. The DMACopyMem() function is provided as an alternative way to request a DMA transfer by passing in the ''Virtual Addresses'' to the source and destination buffers instead of the Physical Addresses. DMACopyMem() will attempt to determine if the supplied memory buffers are DMA Compliant and if so it will internally use DMAPhysicalCopyMem() to handle the transaction. If DMACopyMem() determines that the supplied memory is '''not''' DMA Compliant it will return FALSE and no data copy will occur.

In theory any ''contiguous'' block of memory from 1 Byte up to 4GB in size may be transferred using either one of these calls. In practice the DMA hardware can directly accept memory blocks up to FSLDMA_MAXBLOCK_SIZE (or 64MB - 1 Byte). Therefore any data blocks greater than FSLDMA_MAXBLOCK_SIZE will automatically be feed to the DMA hardware in a series of smaller chunks. For maximum efficiency transfer sizes should be at least 256 Bytes in size and be an even multiple of 64 Bytes. Odd sizes are handled by the hardware but will degrade performance.

If you are transferring many large blocks of data in series and wish to manually send them to the FslDMA API's memory copy functions one block at a time, then setting your block sizes to FSLDMA_OPTIMAL_BLKSIZE (or 64 MB - 64 Bytes) and exclusively using DMAPhysicalCopyMem() will provide the fastest transfer speeds will the least amount of CPU overhead.

==== Utility / Miscellaneous Functions ====

The last section to the FslDMA API provides a single convenience function call; DMAGetVirtualAddress().

<syntaxhighlight>
APTR DMAGetVirtualAddress( APTR pPhysicalAddress );
</syntaxhighlight>

The DMAGetVirtualAddress() function returns the Virtual memory location for the Physical memory location that was itself allocated and returned by the DMAAllocPhysicalMemory() function. DMAGetVirtualAddress() will not work on physical addresses returned by IMMU->GetPhysicalAddress() on memory not allocated using DMAAllocPhysicalMemory().

The main purpose of this function (other then debugging purposes) is to provide the "normal" Virtual Address of memory allocated by the FslDMA API for use by functions that expect "normal" Virtual address locations; for example IExec->CopyMemQuick().

==== Further reference - The fsldma.resource AutoDoc ====

See the [[http://wiki.amigaos.net/amiga/autodocs/fsldmares.doc.txt fsldma.resource AutoDoc]] file for more details on each API call.

=== Example usage ===
<syntaxhighlight>
#include <interfaces/fsldma.h>
// Obtain the fsldma.resource
struct fslDMAIFace *IfslDMA = IExec->OpenResource(FSLDMA_NAME);
if ( NULL != IfslDMA )
{
uint32 lTestSize = 1024;
CONST_APTR pPhysicalSrcAddr = NULL;
APTR pPhysicalDestAddr = NULL;
// Allocate the Source Buffer (for DMA)
// and set the contents to 0xB3 (just an example value)
pPhysicalSrcAddr = (CONST_APTR)IfslDMA->DMAAllocPhysicalMemoryTags(lTestSize,
FSLDMA_APM_ClearWithValue, 0xB3,
TAG_END);
if ( NULL != pPhysicalSrcAddr )
{
// Allocate the Destination Buffer (for DMA)
// - contents will by cleared by default
pPhysicalDestAddr = IfslDMA->DMAAllocPhysicalMemory(lTestSize);
if ( NULL != pPhysicalDestAddr )
{
// Call IfslDMA->DMAPhysicalCopyMem()
// to perform the memory copy using the DMA hardware
if ( TRUE == IfslDMA->DMAPhysicalCopyMem(pPhysicalSrcAddr,
pPhysicalDestAddr,lTestSize) )
{
// Success - Do something with the copied data
}
else
{
// Fallback and use CPU Copy instead (or do something else)
// Since we allocated the memory buffers using the FslDMA API,
// which returns the Physical address to that memory, and the
// IExec->CopyMemQuick() function expects the Virtual address,
// we first need to obtain the Virtual address for the Physical
// ones (using the FslDMA API again) before we can call our
// fallback copy function.
CONST_APTR pVirtualSrcAddr = NULL;
APTR pVirtualDestAddr = NULL;
pVirtualSrcAddr = IfslDMA->DMAGetVirtualAddress((APTR)pPhysicalSrcAddr);
pVirtualDestAddr = IfslDMA->DMAGetVirtualAddress(pPhysicalDestAddr);
IExec->CopyMemQuick(pVirtualSrcAddr,pVirtualDestAddr,lTestSize);
}
// We *must* use DMAFreePhysicalMemory() to free the memory
// that we allocated with DMAAllocPhysicalMemory()
IfslDMA->DMAFreePhysicalMemory(pPhysicalDestAddr);
}
// We *must* use DMAFreePhysicalMemory() to free the memory
// that we allocated with DMAAllocPhysicalMemory()
IfslDMA->DMAFreePhysicalMemory((APTR)pPhysicalSrcAddr);
}
}
</syntaxhighlight>

==== Obtaining the fsldma.resource ====

Breaking the above example down the first thing we do is include the interface header for the fsldma.resource and obtain the resource itself.

<syntaxhighlight>
#include <interfaces/fsldma.h>
struct fslDMAIFace *IfslDMA = IExec->OpenResource(FSLDMA_NAME);
</syntaxhighlight>

==== Allocating DMA Compliant Memory ====

Once we have successfully obtained the DMA resource we can directly use its API. The next step we need to do is to allocate some memory '''which we know is DMA compliant''' for use by the resource. The easiest way to accomplish this is to use the IfslDMA->DMAAllocPhysicalMemory() function. This will automatically take care of ensuring the memory that is returned is properly aligned, contiguous, cache-inhibited and coherent.

We use the Tags version of the allocate memory function first so we can allocate a block of memory for our source buffer and fill it with some test value (in this case the byte value 0xB3).

<syntaxhighlight>
pPhysicalSrcAddr = (CONST_APTR)IfslDMA->DMAAllocPhysicalMemoryTags(lTestSize,
FSLDMA_APM_ClearWithValue, 0xB3,
TAG_END);
</syntaxhighlight>

We also need a destination buffer for our test. Since it only needs to start out being cleared (filled with zeroes), we can use the simplest form of the allocate memory function here as the allocated memory is cleared by default.

<syntaxhighlight>
pPhysicalDestAddr = IfslDMA->DMAAllocPhysicalMemory(lTestSize);
</syntaxhighlight>

==== The core function - Copy Physical Memory ====

Now that we have two DMA Compliant memory buffers available we can get to the heart of the API usage and make the call to IfslDMA->DMAPhysicalCopyMem().

<syntaxhighlight>
IfslDMA->DMAPhysicalCopyMem(pPhysicalSrcAddr,pPhysicalDestAddr,lTestSize);
</syntaxhighlight>

Looking at the full [[#Example usage|Example]] source above you can see that the DMAPhysicalCopyMem() call returns a Boolean value to indicate success or failure. Therefore, TRUE will be returned after the DMA hardware had completed copying the requested data (blocking call) and FALSE will be returned if a problem occurred.

Since the memory buffers we are using were allocated using the FslDMA API and our transfer size was greater than zero and less than or equal to the total size of either buffer, (in others words a legal copy request), there is '''very''' little chance that the DMAPhysicalCopyMem() function will fail. In fact, about the only reason the DMA hardware would fail to handle a legal transaction would be if the physical RAM installed in the system was faulty.

So even though it is extremely unlikely for our DMA copy to have failed and returned FALSE, let's take a look at how we might handle the failure. In other words, falling back and using a CPU based copy function instead to complete the data move.

Since we are reverting back to using a normal system copy memory function here, we first need to obtain the ''Virtual Addresses'' to both our source and destination buffers. This is accomplished by using the DMAGetVirtualAddress() function and passing in the Physical Address that was returned by DMAAllocPhysicalMemory().

<syntaxhighlight>
CONST_APTR pVirtualSrcAddr = NULL;
APTR pVirtualDestAddr = NULL;
pVirtualSrcAddr = IfslDMA->DMAGetVirtualAddress((APTR)pPhysicalSrcAddr);
pVirtualDestAddr = IfslDMA->DMAGetVirtualAddress(pPhysicalDestAddr);
</syntaxhighlight>

Now that we have the Virtual Address equivalents to the Physical Addresses that were returned by DMAAllocPhysicalMemory(), we can proceed to call the Exec CopyMemQuick() function to complete the copy. Here we can only trust that the IExec->CopyMemQuick() call can not fail since it does not return a result code.

<syntaxhighlight>
IExec->CopyMemQuick(pVirtualSrcAddr,pVirtualDestAddr,lTestSize);
</syntaxhighlight>

==== Cleaning up - Freeing DMA Compliant memory ====

It is essential that you free any memory that was allocated using the DMAAllocPhysicalMemory() function using the corresponding DMAFreePhysicalMemory() call. The reason for this is two-fold; first because additional resource tracking is maintained by the FslDMA API whenever it allocates memory which must itself be released, and second because the ''Physical Address'' to the memory is returned by the allocate call and not the ''Virtual Address'', so if you attempt to pass the address returned by DMAAllocPhysicalMemory() directly into IExec->FreeVec() it would likely result in a crash.

<syntaxhighlight>
IfslDMA->DMAFreePhysicalMemory(pPhysicalSrcAddr);
IfslDMA->DMAFreePhysicalMemory(pPhysicalDestAddr);
</syntaxhighlight>

DMA Resource

2019-11-13T02:12:22Z

Jamie Krueger: /* Copy Memory Functions */

== DMA Engine ==

Some hardware targets include a DMA engine which can be used for general purpose copying. This article describes the DMA engines available and how to use them.

=== Hardware Features ===

The Direct Memory Access (DMA) Engines found in the NXP/Freescale p5020, p5040 and p1022 System On a Chip (SoC)s, as found in the AmigaONE X5000/20, X5000/40 and A1222 respectively, are quite flexible and powerful. Each of these chips contains two distinct engines with four data channels each. This provides the ability to have a total of eight DMA Channels working at once, with up to two DMA transactions actually being executed at the same time (one on each of the two DMA Engines).

Further, each of the four DMA Channels found in a DMA Engine may be individually programmed to handle either; a single transaction, a ''Chain'' of transactions, or even ''Lists'' of ''Chains'' of transactions. The DMA Engines automatically arbitrate control between each DMA Channel following programmed bandwidth settings for each Channel (typically 1024 bytes).

This means that after completing a transfer of 1024 bytes (for example), the hardware will consider switching to the next Channel to allow it to move another block of data, and so on in a round-robin fashion. If all other DMA Channels on a given DMA Engine are idle when arbitration would take place, the hardware will not arbitrate control to another Channel, but simply continue processing the transaction(s) for the Channel it is on.

== fsldma.resource ==

The fsldma.resource API is provided automatically in the kernel for all supported machines (Currently the AmigaONE X5000/20, X5000/40 and A1222).

=== The FslDMA API ===

The API provided by the fsldma.resource breaks down into three main parts:
:* Memory management
:* Copy Memory functions
:* Utility / Miscellaneous

==== Memory Management Functions ====

The FslDMA resource API provides convenience functions for the allocation and freeing of '''DMA Compliant''' blocks of memory. Two functions are provided for this purpose; DMAAllocPhysicalMemory() and DMAFreePhysicalMemory().

The memory allocation function also includes two Tags based versions of the call to allow for addition variables to be passed into the call using a variable set of Tags or fixed TagList. Currently the only supported Tag is ''FSLDMA_APM_ClearWithValue'', which is the equivalent to the IExec->AllocVecTagList() function's AVT_ClearWithValue tag. If the FSLDMA_APM_ClearWithValue tag is not provided then the requested memory block is cleared with zeroes by default before being returned. DMAAllocPhysicalMemory() returns the ''Physical'' Address pointer to the allocated memory or NULL if it is unable to allocate the requested memory.

<syntaxhighlight>
APTR DMAAllocPhysicalMemoryTagList( uint32 lSize, const struct TagItem *tags );
APTR DMAAllocPhysicalMemoryTags( uint32 lSize, uint32 Tag1, ... );
APTR DMAAllocPhysicalMemory( uint32 lSize );
</syntaxhighlight>

The corresponding function to allocating a DMA Compliant memory block is DMAFreePhysicalMemory(). Any memory allocated using DMAAllocPhysicalMemory() must be eventually freed using DMAFreePhysicalMemory().

<syntaxhighlight>
void DMAFreePhysicalMemory( APTR pPhysicalMemoryBlock );
</syntaxhighlight>

==== Copy Memory Functions ====

Two API calls make up the core of the FslDMA API; DMAPhysicalCopyMem() and DMACopyMem().
Both of these calls will "block" (not return to the user) until after the requested transfer has either succeeded or failed. A value of TRUE is returned upon success and FALSE if an error occurred.

<syntaxhighlight>
BOOL DMAPhysicalCopyMem( CONST_APTR pPhysicalSourceBuffer, APTR pPhysicalDestBuffer, uint32 lBufferSize );
BOOL DMACopyMem( CONST_APTR pSourceBuffer, APTR pDestBuffer, uint32 lBufferSize );
</syntaxhighlight>

As the name implies the first (and core version) of the copy memory functions, DMAPhysicalCopyMem(), accepts the Physical Addresses to the source and destination buffers (as returned by DMAAllocPhysicalMemory()), along with an unsigned 32-Bit value for the amount of bytes that should be copied (lBuffsize must be greater than zero(0) and no more than the maximum size of the source and destination buffers).

DMAPhysicalCopyMem() is the most direct an efficient means of using the DMA hardware to effect a single memory copy. The DMACopyMem() function is provided as an alternative way to request a DMA transfer by passing in the ''Virtual Addresses'' to the source and destination buffers instead of the Physical Addresses. DMACopyMem() will attempt to determine if the supplied memory buffers are DMA Compliant and if so it will internally use DMAPhysicalCopyMem() to handle the transaction. If DMACopyMem() determines that the supplied memory is '''not''' DMA Compliant it will return FALSE and no data copy will occur.

In theory any ''contiguous'' block of memory from 1 Byte up to 4GB in size may be transferred using either one of these calls. In practice the DMA hardware can directly accept memory blocks up to FSLDMA_MAXBLOCK_SIZE (or 64MB - 1 Byte). Therefore any data blocks greater than FSLDMA_MAXBLOCK_SIZE will automatically be feed to the DMA hardware in a series of smaller chunks. For maximum efficiency transfer sizes should be at least 256 Bytes in size and be an even multiple of 64 Bytes. Odd sizes are handled by the hardware but will degrade performance.

If you are transferring many large blocks of data in series and wish to manually send them to the FslDMA API's memory copy functions one block at a time, then setting your block sizes to FSLDMA_OPTIMAL_BLKSIZE (or 64 MB - 64 Bytes) and exclusively using DMAPhysicalCopyMem() will provide the fastest transfer speeds will the least amount of CPU overhead.

==== Utility / Miscellaneous Functions ====

The last section to the FslDMA API provides a single convenience function call; DMAGetVirtualAddress().

<syntaxhighlight>
APTR DMAGetVirtualAddress( APTR pPhysicalAddress );
</syntaxhighlight>

The DMAGetVirtualAddress() function returns the Virtual memory location for the Physical memory location that was itself allocated and returned by the DMAAllocPhysicalMemory() function. DMAGetVirtualAddress() will not work on physical addresses returned by IMMU->GetPhysicalAddress() on memory not allocated using DMAAllocPhysicalMemory().

The main purpose of this function (other then debugging purposes) is to provide the "normal" Virtual Address of memory allocated by the FslDMA API for use by functions that expect "normal" Virtual address locations; for example IExec->CopyMemQuick().

==== Further reference - The fsldma.resource AutoDoc ====

See the [[http://wiki.amigaos.net/amiga/autodocs/fsldmares.doc.txt fsldma.resource AutoDoc]] file for more details on each API call.

=== Example usage ===
<syntaxhighlight>
#include <interfaces/fsldma.h>
// Obtain the fsldma.resource
struct fslDMAIFace *IfslDMA = IExec->OpenResource(FSLDMA_NAME);
if ( NULL != IfslDMA )
{
uint32 lTestSize = 1024;
CONST_APTR pPhysicalSrcAddr = NULL;
APTR pPhysicalDestAddr = NULL;
// Allocate the Source Buffer (for DMA)
// and set the contents to 0xB3 (just an example value)
pPhysicalSrcAddr = (CONST_APTR)IfslDMA->DMAAllocPhysicalMemoryTags(lTestSize,
FSLDMA_APM_ClearWithValue, 0xB3,
TAG_END);
if ( NULL != pPhysicalSrcAddr )
{
// Allocate the Destination Buffer (for DMA)
// - contents will by cleared by default
pPhysicalDestAddr = IfslDMA->DMAAllocPhysicalMemory(lTestSize);
if ( NULL != pPhysicalDestAddr )
{
// Call IfslDMA->DMAPhysicalCopyMem()
// to perform the memory copy using the DMA hardware
if ( TRUE == IfslDMA->DMAPhysicalCopyMem(pPhysicalSrcAddr,
pPhysicalDestAddr,lTestSize) )
{
// Success - Do something with the copied data
}
else
{
// Fallback and use CPU Copy instead (or do something else)
// Since we allocated the memory buffers using the FslDMA API,
// which returns the Physical address to that memory, and the
// IExec->CopyMemQuick() function expects the Virtual address,
// we first need to obtain the Virtual address for the Physical
// ones (using the FslDMA API again) before we can call our
// fallback copy function.
CONST_APTR pVirtualSrcAddr = NULL;
APTR pVirtualDestAddr = NULL;
pVirtualSrcAddr = IfslDMA->DMAGetVirtualAddress((APTR)pPhysicalSrcAddr);
pVirtualDestAddr = IfslDMA->DMAGetVirtualAddress(pPhysicalDestAddr);
IExec->CopyMemQuick(pVirtualSrcAddr,pVirtualDestAddr,lTestSize);
}
// We *must* use DMAFreePhysicalMemory() to free the memory
// that we allocated with DMAAllocPhysicalMemory()
IfslDMA->DMAFreePhysicalMemory(pPhysicalDestAddr);
}
// We *must* use DMAFreePhysicalMemory() to free the memory
// that we allocated with DMAAllocPhysicalMemory()
IfslDMA->DMAFreePhysicalMemory((APTR)pPhysicalSrcAddr);
}
}
</syntaxhighlight>

==== Obtaining the fsldma.resource ====

Breaking this example down the first thing we do is include the interface header for the fsldma.resource and obtain the resource itself.

<syntaxhighlight>
#include <interfaces/fsldma.h>
struct fslDMAIFace *IfslDMA = IExec->OpenResource(FSLDMA_NAME);
</syntaxhighlight>

==== Allocating DMA Compliant Memory ====

Once we have successfully obtained the DMA resource we can directly use its API. The next step we need to do is to allocate some memory '''which we know is DMA compliant''' for use by the resource. The easiest way to accomplish this is to use the IfslDMA->DMAAllocPhysicalMemory() function. This will automatically take care of ensuring the memory that is returned is properly aligned, contiguous, cache-inhibited and coherent.

We use the Tags version of the allocate memory function first so we can allocate a block of memory for our source buffer and fill it with some test value (in this case the byte value 0xB3).

<syntaxhighlight>
pPhysicalSrcAddr = (CONST_APTR)IfslDMA->DMAAllocPhysicalMemoryTags(lTestSize,
FSLDMA_APM_ClearWithValue, 0xB3,
TAG_END);
</syntaxhighlight>

We also need a destination buffer for our test. Since it only needs to start out being cleared (filled with zeroes), we can use the simplest form of the allocate memory function here as the allocated memory is cleared by default.

<syntaxhighlight>
pPhysicalDestAddr = IfslDMA->DMAAllocPhysicalMemory(lTestSize);
</syntaxhighlight>

==== The core function - Copy Physical Memory ====

Now that we have two DMA Compliant memory buffers available we can get to the heart of the API usage and make the call to IfslDMA->DMAPhysicalCopyMem().

<syntaxhighlight>
IfslDMA->DMAPhysicalCopyMem(pPhysicalSrcAddr,pPhysicalDestAddr,lTestSize);
</syntaxhighlight>

Looking at the full [[#Example usage|Example]] source above you can see that the DMAPhysicalCopyMem() call returns a Boolean value to indicate success or failure. Therefore, TRUE will be returned after the DMA hardware had completed copying the requested data (blocking call) and FALSE will be returned if a problem occurred.

Since the memory buffers we are using were allocated using the FslDMA API and our transfer size was greater than zero and less than or equal to the total size of either buffer, (in others words a legal copy request), there is '''very''' little chance that the DMAPhysicalCopyMem() function will fail. In fact, about the only reason the DMA hardware would fail to handle a legal transaction would be if the physical RAM installed in the system was faulty.

So even though it is extremely unlikely for our DMA copy to have failed and returned FALSE, let's take a look at how we might handle the failure. In other words, falling back and using a CPU based copy function instead to complete the data move.

Since we are reverting back to using a normal system copy memory function here, we first need to obtain the ''Virtual Addresses'' to both our source and destination buffers. This is accomplished by using the DMAGetVirtualAddress() function and passing in the Physical Address that was returned by DMAAllocPhysicalMemory().

<syntaxhighlight>
CONST_APTR pVirtualSrcAddr = NULL;
APTR pVirtualDestAddr = NULL;
pVirtualSrcAddr = IfslDMA->DMAGetVirtualAddress((APTR)pPhysicalSrcAddr);
pVirtualDestAddr = IfslDMA->DMAGetVirtualAddress(pPhysicalDestAddr);
</syntaxhighlight>

Now that we have the Virtual Address equivalents to the Physical Addresses that were returned by DMAAllocPhysicalMemory(), we can proceed to call the Exec CopyMemQuick() function to complete the copy. Here we can only trust that the IExec->CopyMemQuick() call can not fail since it does not return a result code.

<syntaxhighlight>
IExec->CopyMemQuick(pVirtualSrcAddr,pVirtualDestAddr,lTestSize);
</syntaxhighlight>

==== Cleaning up - Freeing DMA Compliant memory ====

It is essential that you free any memory that was allocated using the DMAAllocPhysicalMemory() function using the corresponding DMAFreePhysicalMemory() call. The reason for this is two-fold; first because additional resource tracking is maintained by the FslDMA API whenever it allocates memory which must itself be released, and second because the ''Physical Address'' to the memory is returned by the allocate call and not the ''Virtual Address'', so if you attempt to pass the address returned by DMAAllocPhysicalMemory() directly into IExec->FreeVec() it would likely result in a crash.

<syntaxhighlight>
IfslDMA->DMAFreePhysicalMemory(pPhysicalSrcAddr);
IfslDMA->DMAFreePhysicalMemory(pPhysicalDestAddr);
</syntaxhighlight>

DMA Resource

2019-11-13T02:10:17Z

Jamie Krueger: /* Memory Management Functions */

== DMA Engine ==

Some hardware targets include a DMA engine which can be used for general purpose copying. This article describes the DMA engines available and how to use them.

=== Hardware Features ===

The Direct Memory Access (DMA) Engines found in the NXP/Freescale p5020, p5040 and p1022 System On a Chip (SoC)s, as found in the AmigaONE X5000/20, X5000/40 and A1222 respectively, are quite flexible and powerful. Each of these chips contains two distinct engines with four data channels each. This provides the ability to have a total of eight DMA Channels working at once, with up to two DMA transactions actually being executed at the same time (one on each of the two DMA Engines).

Further, each of the four DMA Channels found in a DMA Engine may be individually programmed to handle either; a single transaction, a ''Chain'' of transactions, or even ''Lists'' of ''Chains'' of transactions. The DMA Engines automatically arbitrate control between each DMA Channel following programmed bandwidth settings for each Channel (typically 1024 bytes).

This means that after completing a transfer of 1024 bytes (for example), the hardware will consider switching to the next Channel to allow it to move another block of data, and so on in a round-robin fashion. If all other DMA Channels on a given DMA Engine are idle when arbitration would take place, the hardware will not arbitrate control to another Channel, but simply continue processing the transaction(s) for the Channel it is on.

== fsldma.resource ==

The fsldma.resource API is provided automatically in the kernel for all supported machines (Currently the AmigaONE X5000/20, X5000/40 and A1222).

=== The FslDMA API ===

The API provided by the fsldma.resource breaks down into three main parts:
:* Memory management
:* Copy Memory functions
:* Utility / Miscellaneous

==== Memory Management Functions ====

The FslDMA resource API provides convenience functions for the allocation and freeing of '''DMA Compliant''' blocks of memory. Two functions are provided for this purpose; DMAAllocPhysicalMemory() and DMAFreePhysicalMemory().

The memory allocation function also includes two Tags based versions of the call to allow for addition variables to be passed into the call using a variable set of Tags or fixed TagList. Currently the only supported Tag is ''FSLDMA_APM_ClearWithValue'', which is the equivalent to the IExec->AllocVecTagList() function's AVT_ClearWithValue tag. If the FSLDMA_APM_ClearWithValue tag is not provided then the requested memory block is cleared with zeroes by default before being returned. DMAAllocPhysicalMemory() returns the ''Physical'' Address pointer to the allocated memory or NULL if it is unable to allocate the requested memory.

<syntaxhighlight>
APTR DMAAllocPhysicalMemoryTagList( uint32 lSize, const struct TagItem *tags );
APTR DMAAllocPhysicalMemoryTags( uint32 lSize, uint32 Tag1, ... );
APTR DMAAllocPhysicalMemory( uint32 lSize );
</syntaxhighlight>

The corresponding function to allocating a DMA Compliant memory block is DMAFreePhysicalMemory(). Any memory allocated using DMAAllocPhysicalMemory() must be eventually freed using DMAFreePhysicalMemory().

<syntaxhighlight>
void DMAFreePhysicalMemory( APTR pPhysicalMemoryBlock );
</syntaxhighlight>

==== Copy Memory Functions ====

Two API calls make up the core of the FslDMA API; DMAPhysicalCopyMem() and DMACopyMem().
Both of these calls will "block" (not return to the user) until after the requested transfer has either succeeded or failed.

<syntaxhighlight>
BOOL DMAPhysicalCopyMem( CONST_APTR pPhysicalSourceBuffer, APTR pPhysicalDestBuffer, uint32 lBufferSize );
BOOL DMACopyMem( CONST_APTR pSourceBuffer, APTR pDestBuffer, uint32 lBufferSize );
</syntaxhighlight>

As the name implies the first (and core version) of the copy memory functions, DMAPhysicalCopyMem(), accepts the Physical Addresses to the source and destination buffers (as returned by DMAAllocPhysicalMemory()), along with an unsigned 32-Bit value for the amount of bytes that should be copied (lBuffsize must be greater than zero(0) and no more than the maximum size of the source and destination buffers).

DMAPhysicalCopyMem() is the most direct an efficient means of using the DMA hardware to effect a single memory copy. The DMACopyMem() function is provided as an alternative way to request a DMA transfer by passing in the ''Virtual Addresses'' to the source and destination buffers instead of the Physical Addresses. DMACopyMem() will attempt to determine if the supplied memory buffers are DMA Compliant and if so it will internally use DMAPhysicalCopyMem() to handle the transaction. If DMACopyMem() determines that the supplied memory is '''not''' DMA Compliant it will return FALSE and no data copy will occur.

In theory any ''contiguous'' block of memory from 1 Byte up to 4GB in size may be transferred using either one of these calls. In practice the DMA hardware can directly accept memory blocks up to FSLDMA_MAXBLOCK_SIZE (or 64MB - 1 Byte). Therefore any data blocks greater than FSLDMA_MAXBLOCK_SIZE will automatically be feed to the DMA hardware in a series of smaller chunks. For maximum efficiency transfer sizes should be at least 256 Bytes in size and be an even multiple of 64 Bytes. Odd sizes are handled by the hardware but will degrade performance.

If you are transferring many large blocks of data in series and wish to manually send them to the FslDMA API's memory copy functions one block at a time, then setting your block sizes to FSLDMA_OPTIMAL_BLKSIZE (or 64 MB - 64 Bytes) and exclusively using DMAPhysicalCopyMem() will provide the fastest transfer speeds will the least amount of CPU overhead.

==== Utility / Miscellaneous Functions ====

The last section to the FslDMA API provides a single convenience function call; DMAGetVirtualAddress().

<syntaxhighlight>
APTR DMAGetVirtualAddress( APTR pPhysicalAddress );
</syntaxhighlight>

The DMAGetVirtualAddress() function returns the Virtual memory location for the Physical memory location that was itself allocated and returned by the DMAAllocPhysicalMemory() function. DMAGetVirtualAddress() will not work on physical addresses returned by IMMU->GetPhysicalAddress() on memory not allocated using DMAAllocPhysicalMemory().

The main purpose of this function (other then debugging purposes) is to provide the "normal" Virtual Address of memory allocated by the FslDMA API for use by functions that expect "normal" Virtual address locations; for example IExec->CopyMemQuick().

==== Further reference - The fsldma.resource AutoDoc ====

See the [[http://wiki.amigaos.net/amiga/autodocs/fsldmares.doc.txt fsldma.resource AutoDoc]] file for more details on each API call.

=== Example usage ===
<syntaxhighlight>
#include <interfaces/fsldma.h>
// Obtain the fsldma.resource
struct fslDMAIFace *IfslDMA = IExec->OpenResource(FSLDMA_NAME);
if ( NULL != IfslDMA )
{
uint32 lTestSize = 1024;
CONST_APTR pPhysicalSrcAddr = NULL;
APTR pPhysicalDestAddr = NULL;
// Allocate the Source Buffer (for DMA)
// and set the contents to 0xB3 (just an example value)
pPhysicalSrcAddr = (CONST_APTR)IfslDMA->DMAAllocPhysicalMemoryTags(lTestSize,
FSLDMA_APM_ClearWithValue, 0xB3,
TAG_END);
if ( NULL != pPhysicalSrcAddr )
{
// Allocate the Destination Buffer (for DMA)
// - contents will by cleared by default
pPhysicalDestAddr = IfslDMA->DMAAllocPhysicalMemory(lTestSize);
if ( NULL != pPhysicalDestAddr )
{
// Call IfslDMA->DMAPhysicalCopyMem()
// to perform the memory copy using the DMA hardware
if ( TRUE == IfslDMA->DMAPhysicalCopyMem(pPhysicalSrcAddr,
pPhysicalDestAddr,lTestSize) )
{
// Success - Do something with the copied data
}
else
{
// Fallback and use CPU Copy instead (or do something else)
// Since we allocated the memory buffers using the FslDMA API,
// which returns the Physical address to that memory, and the
// IExec->CopyMemQuick() function expects the Virtual address,
// we first need to obtain the Virtual address for the Physical
// ones (using the FslDMA API again) before we can call our
// fallback copy function.
CONST_APTR pVirtualSrcAddr = NULL;
APTR pVirtualDestAddr = NULL;
pVirtualSrcAddr = IfslDMA->DMAGetVirtualAddress((APTR)pPhysicalSrcAddr);
pVirtualDestAddr = IfslDMA->DMAGetVirtualAddress(pPhysicalDestAddr);
IExec->CopyMemQuick(pVirtualSrcAddr,pVirtualDestAddr,lTestSize);
}
// We *must* use DMAFreePhysicalMemory() to free the memory
// that we allocated with DMAAllocPhysicalMemory()
IfslDMA->DMAFreePhysicalMemory(pPhysicalDestAddr);
}
// We *must* use DMAFreePhysicalMemory() to free the memory
// that we allocated with DMAAllocPhysicalMemory()
IfslDMA->DMAFreePhysicalMemory((APTR)pPhysicalSrcAddr);
}
}
</syntaxhighlight>

==== Obtaining the fsldma.resource ====

Breaking this example down the first thing we do is include the interface header for the fsldma.resource and obtain the resource itself.

<syntaxhighlight>
#include <interfaces/fsldma.h>
struct fslDMAIFace *IfslDMA = IExec->OpenResource(FSLDMA_NAME);
</syntaxhighlight>

==== Allocating DMA Compliant Memory ====

Once we have successfully obtained the DMA resource we can directly use its API. The next step we need to do is to allocate some memory '''which we know is DMA compliant''' for use by the resource. The easiest way to accomplish this is to use the IfslDMA->DMAAllocPhysicalMemory() function. This will automatically take care of ensuring the memory that is returned is properly aligned, contiguous, cache-inhibited and coherent.

We use the Tags version of the allocate memory function first so we can allocate a block of memory for our source buffer and fill it with some test value (in this case the byte value 0xB3).

<syntaxhighlight>
pPhysicalSrcAddr = (CONST_APTR)IfslDMA->DMAAllocPhysicalMemoryTags(lTestSize,
FSLDMA_APM_ClearWithValue, 0xB3,
TAG_END);
</syntaxhighlight>

We also need a destination buffer for our test. Since it only needs to start out being cleared (filled with zeroes), we can use the simplest form of the allocate memory function here as the allocated memory is cleared by default.

<syntaxhighlight>
pPhysicalDestAddr = IfslDMA->DMAAllocPhysicalMemory(lTestSize);
</syntaxhighlight>

==== The core function - Copy Physical Memory ====

Now that we have two DMA Compliant memory buffers available we can get to the heart of the API usage and make the call to IfslDMA->DMAPhysicalCopyMem().

<syntaxhighlight>
IfslDMA->DMAPhysicalCopyMem(pPhysicalSrcAddr,pPhysicalDestAddr,lTestSize);
</syntaxhighlight>

Looking at the full [[#Example usage|Example]] source above you can see that the DMAPhysicalCopyMem() call returns a Boolean value to indicate success or failure. Therefore, TRUE will be returned after the DMA hardware had completed copying the requested data (blocking call) and FALSE will be returned if a problem occurred.

Since the memory buffers we are using were allocated using the FslDMA API and our transfer size was greater than zero and less than or equal to the total size of either buffer, (in others words a legal copy request), there is '''very''' little chance that the DMAPhysicalCopyMem() function will fail. In fact, about the only reason the DMA hardware would fail to handle a legal transaction would be if the physical RAM installed in the system was faulty.

So even though it is extremely unlikely for our DMA copy to have failed and returned FALSE, let's take a look at how we might handle the failure. In other words, falling back and using a CPU based copy function instead to complete the data move.

Since we are reverting back to using a normal system copy memory function here, we first need to obtain the ''Virtual Addresses'' to both our source and destination buffers. This is accomplished by using the DMAGetVirtualAddress() function and passing in the Physical Address that was returned by DMAAllocPhysicalMemory().

<syntaxhighlight>
CONST_APTR pVirtualSrcAddr = NULL;
APTR pVirtualDestAddr = NULL;
pVirtualSrcAddr = IfslDMA->DMAGetVirtualAddress((APTR)pPhysicalSrcAddr);
pVirtualDestAddr = IfslDMA->DMAGetVirtualAddress(pPhysicalDestAddr);
</syntaxhighlight>

Now that we have the Virtual Address equivalents to the Physical Addresses that were returned by DMAAllocPhysicalMemory(), we can proceed to call the Exec CopyMemQuick() function to complete the copy. Here we can only trust that the IExec->CopyMemQuick() call can not fail since it does not return a result code.

<syntaxhighlight>
IExec->CopyMemQuick(pVirtualSrcAddr,pVirtualDestAddr,lTestSize);
</syntaxhighlight>

==== Cleaning up - Freeing DMA Compliant memory ====

It is essential that you free any memory that was allocated using the DMAAllocPhysicalMemory() function using the corresponding DMAFreePhysicalMemory() call. The reason for this is two-fold; first because additional resource tracking is maintained by the FslDMA API whenever it allocates memory which must itself be released, and second because the ''Physical Address'' to the memory is returned by the allocate call and not the ''Virtual Address'', so if you attempt to pass the address returned by DMAAllocPhysicalMemory() directly into IExec->FreeVec() it would likely result in a crash.

<syntaxhighlight>
IfslDMA->DMAFreePhysicalMemory(pPhysicalSrcAddr);
IfslDMA->DMAFreePhysicalMemory(pPhysicalDestAddr);
</syntaxhighlight>

DMA Resource

2019-11-13T02:01:27Z

Jamie Krueger: /* Hardware Features */

== DMA Engine ==

Some hardware targets include a DMA engine which can be used for general purpose copying. This article describes the DMA engines available and how to use them.

=== Hardware Features ===

The Direct Memory Access (DMA) Engines found in the NXP/Freescale p5020, p5040 and p1022 System On a Chip (SoC)s, as found in the AmigaONE X5000/20, X5000/40 and A1222 respectively, are quite flexible and powerful. Each of these chips contains two distinct engines with four data channels each. This provides the ability to have a total of eight DMA Channels working at once, with up to two DMA transactions actually being executed at the same time (one on each of the two DMA Engines).

Further, each of the four DMA Channels found in a DMA Engine may be individually programmed to handle either; a single transaction, a ''Chain'' of transactions, or even ''Lists'' of ''Chains'' of transactions. The DMA Engines automatically arbitrate control between each DMA Channel following programmed bandwidth settings for each Channel (typically 1024 bytes).

This means that after completing a transfer of 1024 bytes (for example), the hardware will consider switching to the next Channel to allow it to move another block of data, and so on in a round-robin fashion. If all other DMA Channels on a given DMA Engine are idle when arbitration would take place, the hardware will not arbitrate control to another Channel, but simply continue processing the transaction(s) for the Channel it is on.

== fsldma.resource ==

The fsldma.resource API is provided automatically in the kernel for all supported machines (Currently the AmigaONE X5000/20, X5000/40 and A1222).

=== The FslDMA API ===

The API provided by the fsldma.resource breaks down into three main parts:
:* Memory management
:* Copy Memory functions
:* Utility / Miscellaneous

==== Memory Management Functions ====

The FslDMA resource API provides convenience functions for the allocation and freeing of '''DMA Compliant''' blocks of memory. Two functions are provided for this purpose; DMAAllocPhysicalMemory() and DMAFreePhysicalMemory().

The memory allocation function also includes two Tags based versions of the call to allow for addition variables to be passed into the call using a variable set of Tags or fixed TagList. Currently the only supported Tag is ''FSLDMA_APM_ClearWithValue'', which is the equivalent to the IExec->AllocVecTagList() function's AVT_ClearWithValue tag. If the FSLDMA_APM_ClearWithValue tag is not provided then the requested memory block is cleared with zeroes by default before being returned.

<syntaxhighlight>
APTR DMAAllocPhysicalMemoryTagList( uint32 lSize, const struct TagItem *tags );
APTR DMAAllocPhysicalMemoryTags( uint32 lSize, uint32 Tag1, ... );
APTR DMAAllocPhysicalMemory( uint32 lSize );
</syntaxhighlight>

The corresponding function to allocating a DMA Compliant memory block is DMAFreePhysicalMemory(). Any memory allocated using DMAAllocPhysicalMemory() must be eventually freed using DMAFreePhysicalMemory().

<syntaxhighlight>
void DMAFreePhysicalMemory( APTR pPhysicalMemoryBlock );
</syntaxhighlight>

==== Copy Memory Functions ====

Two API calls make up the core of the FslDMA API; DMAPhysicalCopyMem() and DMACopyMem().
Both of these calls will "block" (not return to the user) until after the requested transfer has either succeeded or failed.

<syntaxhighlight>
BOOL DMAPhysicalCopyMem( CONST_APTR pPhysicalSourceBuffer, APTR pPhysicalDestBuffer, uint32 lBufferSize );
BOOL DMACopyMem( CONST_APTR pSourceBuffer, APTR pDestBuffer, uint32 lBufferSize );
</syntaxhighlight>

As the name implies the first (and core version) of the copy memory functions, DMAPhysicalCopyMem(), accepts the Physical Addresses to the source and destination buffers (as returned by DMAAllocPhysicalMemory()), along with an unsigned 32-Bit value for the amount of bytes that should be copied (lBuffsize must be greater than zero(0) and no more than the maximum size of the source and destination buffers).

DMAPhysicalCopyMem() is the most direct an efficient means of using the DMA hardware to effect a single memory copy. The DMACopyMem() function is provided as an alternative way to request a DMA transfer by passing in the ''Virtual Addresses'' to the source and destination buffers instead of the Physical Addresses. DMACopyMem() will attempt to determine if the supplied memory buffers are DMA Compliant and if so it will internally use DMAPhysicalCopyMem() to handle the transaction. If DMACopyMem() determines that the supplied memory is '''not''' DMA Compliant it will return FALSE and no data copy will occur.

In theory any ''contiguous'' block of memory from 1 Byte up to 4GB in size may be transferred using either one of these calls. In practice the DMA hardware can directly accept memory blocks up to FSLDMA_MAXBLOCK_SIZE (or 64MB - 1 Byte). Therefore any data blocks greater than FSLDMA_MAXBLOCK_SIZE will automatically be feed to the DMA hardware in a series of smaller chunks. For maximum efficiency transfer sizes should be at least 256 Bytes in size and be an even multiple of 64 Bytes. Odd sizes are handled by the hardware but will degrade performance.

If you are transferring many large blocks of data in series and wish to manually send them to the FslDMA API's memory copy functions one block at a time, then setting your block sizes to FSLDMA_OPTIMAL_BLKSIZE (or 64 MB - 64 Bytes) and exclusively using DMAPhysicalCopyMem() will provide the fastest transfer speeds will the least amount of CPU overhead.

==== Utility / Miscellaneous Functions ====

The last section to the FslDMA API provides a single convenience function call; DMAGetVirtualAddress().

<syntaxhighlight>
APTR DMAGetVirtualAddress( APTR pPhysicalAddress );
</syntaxhighlight>

The DMAGetVirtualAddress() function returns the Virtual memory location for the Physical memory location that was itself allocated and returned by the DMAAllocPhysicalMemory() function. DMAGetVirtualAddress() will not work on physical addresses returned by IMMU->GetPhysicalAddress() on memory not allocated using DMAAllocPhysicalMemory().

The main purpose of this function (other then debugging purposes) is to provide the "normal" Virtual Address of memory allocated by the FslDMA API for use by functions that expect "normal" Virtual address locations; for example IExec->CopyMemQuick().

==== Further reference - The fsldma.resource AutoDoc ====

See the [[http://wiki.amigaos.net/amiga/autodocs/fsldmares.doc.txt fsldma.resource AutoDoc]] file for more details on each API call.

=== Example usage ===
<syntaxhighlight>
#include <interfaces/fsldma.h>
// Obtain the fsldma.resource
struct fslDMAIFace *IfslDMA = IExec->OpenResource(FSLDMA_NAME);
if ( NULL != IfslDMA )
{
uint32 lTestSize = 1024;
CONST_APTR pPhysicalSrcAddr = NULL;
APTR pPhysicalDestAddr = NULL;
// Allocate the Source Buffer (for DMA)
// and set the contents to 0xB3 (just an example value)
pPhysicalSrcAddr = (CONST_APTR)IfslDMA->DMAAllocPhysicalMemoryTags(lTestSize,
FSLDMA_APM_ClearWithValue, 0xB3,
TAG_END);
if ( NULL != pPhysicalSrcAddr )
{
// Allocate the Destination Buffer (for DMA)
// - contents will by cleared by default
pPhysicalDestAddr = IfslDMA->DMAAllocPhysicalMemory(lTestSize);
if ( NULL != pPhysicalDestAddr )
{
// Call IfslDMA->DMAPhysicalCopyMem()
// to perform the memory copy using the DMA hardware
if ( TRUE == IfslDMA->DMAPhysicalCopyMem(pPhysicalSrcAddr,
pPhysicalDestAddr,lTestSize) )
{
// Success - Do something with the copied data
}
else
{
// Fallback and use CPU Copy instead (or do something else)
// Since we allocated the memory buffers using the FslDMA API,
// which returns the Physical address to that memory, and the
// IExec->CopyMemQuick() function expects the Virtual address,
// we first need to obtain the Virtual address for the Physical
// ones (using the FslDMA API again) before we can call our
// fallback copy function.
CONST_APTR pVirtualSrcAddr = NULL;
APTR pVirtualDestAddr = NULL;
pVirtualSrcAddr = IfslDMA->DMAGetVirtualAddress((APTR)pPhysicalSrcAddr);
pVirtualDestAddr = IfslDMA->DMAGetVirtualAddress(pPhysicalDestAddr);
IExec->CopyMemQuick(pVirtualSrcAddr,pVirtualDestAddr,lTestSize);
}
// We *must* use DMAFreePhysicalMemory() to free the memory
// that we allocated with DMAAllocPhysicalMemory()
IfslDMA->DMAFreePhysicalMemory(pPhysicalDestAddr);
}
// We *must* use DMAFreePhysicalMemory() to free the memory
// that we allocated with DMAAllocPhysicalMemory()
IfslDMA->DMAFreePhysicalMemory((APTR)pPhysicalSrcAddr);
}
}
</syntaxhighlight>

==== Obtaining the fsldma.resource ====

Breaking this example down the first thing we do is include the interface header for the fsldma.resource and obtain the resource itself.

<syntaxhighlight>
#include <interfaces/fsldma.h>
struct fslDMAIFace *IfslDMA = IExec->OpenResource(FSLDMA_NAME);
</syntaxhighlight>

==== Allocating DMA Compliant Memory ====

Once we have successfully obtained the DMA resource we can directly use its API. The next step we need to do is to allocate some memory '''which we know is DMA compliant''' for use by the resource. The easiest way to accomplish this is to use the IfslDMA->DMAAllocPhysicalMemory() function. This will automatically take care of ensuring the memory that is returned is properly aligned, contiguous, cache-inhibited and coherent.

We use the Tags version of the allocate memory function first so we can allocate a block of memory for our source buffer and fill it with some test value (in this case the byte value 0xB3).

<syntaxhighlight>
pPhysicalSrcAddr = (CONST_APTR)IfslDMA->DMAAllocPhysicalMemoryTags(lTestSize,
FSLDMA_APM_ClearWithValue, 0xB3,
TAG_END);
</syntaxhighlight>

We also need a destination buffer for our test. Since it only needs to start out being cleared (filled with zeroes), we can use the simplest form of the allocate memory function here as the allocated memory is cleared by default.

<syntaxhighlight>
pPhysicalDestAddr = IfslDMA->DMAAllocPhysicalMemory(lTestSize);
</syntaxhighlight>

==== The core function - Copy Physical Memory ====

Now that we have two DMA Compliant memory buffers available we can get to the heart of the API usage and make the call to IfslDMA->DMAPhysicalCopyMem().

<syntaxhighlight>
IfslDMA->DMAPhysicalCopyMem(pPhysicalSrcAddr,pPhysicalDestAddr,lTestSize);
</syntaxhighlight>

Looking at the full [[#Example usage|Example]] source above you can see that the DMAPhysicalCopyMem() call returns a Boolean value to indicate success or failure. Therefore, TRUE will be returned after the DMA hardware had completed copying the requested data (blocking call) and FALSE will be returned if a problem occurred.

Since the memory buffers we are using were allocated using the FslDMA API and our transfer size was greater than zero and less than or equal to the total size of either buffer, (in others words a legal copy request), there is '''very''' little chance that the DMAPhysicalCopyMem() function will fail. In fact, about the only reason the DMA hardware would fail to handle a legal transaction would be if the physical RAM installed in the system was faulty.

So even though it is extremely unlikely for our DMA copy to have failed and returned FALSE, let's take a look at how we might handle the failure. In other words, falling back and using a CPU based copy function instead to complete the data move.

Since we are reverting back to using a normal system copy memory function here, we first need to obtain the ''Virtual Addresses'' to both our source and destination buffers. This is accomplished by using the DMAGetVirtualAddress() function and passing in the Physical Address that was returned by DMAAllocPhysicalMemory().

<syntaxhighlight>
CONST_APTR pVirtualSrcAddr = NULL;
APTR pVirtualDestAddr = NULL;
pVirtualSrcAddr = IfslDMA->DMAGetVirtualAddress((APTR)pPhysicalSrcAddr);
pVirtualDestAddr = IfslDMA->DMAGetVirtualAddress(pPhysicalDestAddr);
</syntaxhighlight>

Now that we have the Virtual Address equivalents to the Physical Addresses that were returned by DMAAllocPhysicalMemory(), we can proceed to call the Exec CopyMemQuick() function to complete the copy. Here we can only trust that the IExec->CopyMemQuick() call can not fail since it does not return a result code.

<syntaxhighlight>
IExec->CopyMemQuick(pVirtualSrcAddr,pVirtualDestAddr,lTestSize);
</syntaxhighlight>

==== Cleaning up - Freeing DMA Compliant memory ====

It is essential that you free any memory that was allocated using the DMAAllocPhysicalMemory() function using the corresponding DMAFreePhysicalMemory() call. The reason for this is two-fold; first because additional resource tracking is maintained by the FslDMA API whenever it allocates memory which must itself be released, and second because the ''Physical Address'' to the memory is returned by the allocate call and not the ''Virtual Address'', so if you attempt to pass the address returned by DMAAllocPhysicalMemory() directly into IExec->FreeVec() it would likely result in a crash.

<syntaxhighlight>
IfslDMA->DMAFreePhysicalMemory(pPhysicalSrcAddr);
IfslDMA->DMAFreePhysicalMemory(pPhysicalDestAddr);
</syntaxhighlight>

DMA Resource

2019-11-13T01:54:26Z

Jamie Krueger: /* Hardware Features */

== DMA Engine ==

Some hardware targets include a DMA engine which can be used for general purpose copying. This article describes the DMA engines available and how to use them.

=== Hardware Features ===

The Direct Memory Access (DMA) Engines found in the NXP/Freescale p5020, p5040 and p1022 System On a Chip (SoC)s, as found in the AmigaONE X5000/20, X5000/40 and A1222 respectively, are quite flexible and powerful. Each of these chips contains two distinct engines with four data channels each. This provides the ability to have a total of eight DMA Channels working at once, with up to two DMA transactions actually being executed at the same time (one on each of the two DMA Engines).

Further, each of the four DMA Channels found in a DMA Engine may be individually programmed to handle either; a single transaction, a ''Chain'' of transactions, or even ''Lists'' of ''Chains'' of transactions. The DMA Engines automatically arbitrate between each DMA Channel following programmed bandwidth settings for each Channel (typically 1024 bytes).

This means that after completing a transfer of 1024 bytes (for example), the hardware will consider switching to the next Channel to allow it to move another block of data, and so on in a round-robin fashion. If all other DMA Channels on a given DMA Engine are idle when arbitration would take place, the hardware will not arbitrate and simply continue processing the transaction(s) for the Channel it is on.

== fsldma.resource ==

The fsldma.resource API is provided automatically in the kernel for all supported machines (Currently the AmigaONE X5000/20, X5000/40 and A1222).

=== The FslDMA API ===

The API provided by the fsldma.resource breaks down into three main parts:
:* Memory management
:* Copy Memory functions
:* Utility / Miscellaneous

==== Memory Management Functions ====

The FslDMA resource API provides convenience functions for the allocation and freeing of '''DMA Compliant''' blocks of memory. Two functions are provided for this purpose; DMAAllocPhysicalMemory() and DMAFreePhysicalMemory().

The memory allocation function also includes two Tags based versions of the call to allow for addition variables to be passed into the call using a variable set of Tags or fixed TagList. Currently the only supported Tag is ''FSLDMA_APM_ClearWithValue'', which is the equivalent to the IExec->AllocVecTagList() function's AVT_ClearWithValue tag. If the FSLDMA_APM_ClearWithValue tag is not provided then the requested memory block is cleared with zeroes by default before being returned.

<syntaxhighlight>
APTR DMAAllocPhysicalMemoryTagList( uint32 lSize, const struct TagItem *tags );
APTR DMAAllocPhysicalMemoryTags( uint32 lSize, uint32 Tag1, ... );
APTR DMAAllocPhysicalMemory( uint32 lSize );
</syntaxhighlight>

The corresponding function to allocating a DMA Compliant memory block is DMAFreePhysicalMemory(). Any memory allocated using DMAAllocPhysicalMemory() must be eventually freed using DMAFreePhysicalMemory().

<syntaxhighlight>
void DMAFreePhysicalMemory( APTR pPhysicalMemoryBlock );
</syntaxhighlight>

==== Copy Memory Functions ====

Two API calls make up the core of the FslDMA API; DMAPhysicalCopyMem() and DMACopyMem().
Both of these calls will "block" (not return to the user) until after the requested transfer has either succeeded or failed.

<syntaxhighlight>
BOOL DMAPhysicalCopyMem( CONST_APTR pPhysicalSourceBuffer, APTR pPhysicalDestBuffer, uint32 lBufferSize );
BOOL DMACopyMem( CONST_APTR pSourceBuffer, APTR pDestBuffer, uint32 lBufferSize );
</syntaxhighlight>

As the name implies the first (and core version) of the copy memory functions, DMAPhysicalCopyMem(), accepts the Physical Addresses to the source and destination buffers (as returned by DMAAllocPhysicalMemory()), along with an unsigned 32-Bit value for the amount of bytes that should be copied (lBuffsize must be greater than zero(0) and no more than the maximum size of the source and destination buffers).

DMAPhysicalCopyMem() is the most direct an efficient means of using the DMA hardware to effect a single memory copy. The DMACopyMem() function is provided as an alternative way to request a DMA transfer by passing in the ''Virtual Addresses'' to the source and destination buffers instead of the Physical Addresses. DMACopyMem() will attempt to determine if the supplied memory buffers are DMA Compliant and if so it will internally use DMAPhysicalCopyMem() to handle the transaction. If DMACopyMem() determines that the supplied memory is '''not''' DMA Compliant it will return FALSE and no data copy will occur.

In theory any ''contiguous'' block of memory from 1 Byte up to 4GB in size may be transferred using either one of these calls. In practice the DMA hardware can directly accept memory blocks up to FSLDMA_MAXBLOCK_SIZE (or 64MB - 1 Byte). Therefore any data blocks greater than FSLDMA_MAXBLOCK_SIZE will automatically be feed to the DMA hardware in a series of smaller chunks. For maximum efficiency transfer sizes should be at least 256 Bytes in size and be an even multiple of 64 Bytes. Odd sizes are handled by the hardware but will degrade performance.

If you are transferring many large blocks of data in series and wish to manually send them to the FslDMA API's memory copy functions one block at a time, then setting your block sizes to FSLDMA_OPTIMAL_BLKSIZE (or 64 MB - 64 Bytes) and exclusively using DMAPhysicalCopyMem() will provide the fastest transfer speeds will the least amount of CPU overhead.

==== Utility / Miscellaneous Functions ====

The last section to the FslDMA API provides a single convenience function call; DMAGetVirtualAddress().

<syntaxhighlight>
APTR DMAGetVirtualAddress( APTR pPhysicalAddress );
</syntaxhighlight>

The DMAGetVirtualAddress() function returns the Virtual memory location for the Physical memory location that was itself allocated and returned by the DMAAllocPhysicalMemory() function. DMAGetVirtualAddress() will not work on physical addresses returned by IMMU->GetPhysicalAddress() on memory not allocated using DMAAllocPhysicalMemory().

The main purpose of this function (other then debugging purposes) is to provide the "normal" Virtual Address of memory allocated by the FslDMA API for use by functions that expect "normal" Virtual address locations; for example IExec->CopyMemQuick().

==== Further reference - The fsldma.resource AutoDoc ====

See the [[http://wiki.amigaos.net/amiga/autodocs/fsldmares.doc.txt fsldma.resource AutoDoc]] file for more details on each API call.

=== Example usage ===
<syntaxhighlight>
#include <interfaces/fsldma.h>
// Obtain the fsldma.resource
struct fslDMAIFace *IfslDMA = IExec->OpenResource(FSLDMA_NAME);
if ( NULL != IfslDMA )
{
uint32 lTestSize = 1024;
CONST_APTR pPhysicalSrcAddr = NULL;
APTR pPhysicalDestAddr = NULL;
// Allocate the Source Buffer (for DMA)
// and set the contents to 0xB3 (just an example value)
pPhysicalSrcAddr = (CONST_APTR)IfslDMA->DMAAllocPhysicalMemoryTags(lTestSize,
FSLDMA_APM_ClearWithValue, 0xB3,
TAG_END);
if ( NULL != pPhysicalSrcAddr )
{
// Allocate the Destination Buffer (for DMA)
// - contents will by cleared by default
pPhysicalDestAddr = IfslDMA->DMAAllocPhysicalMemory(lTestSize);
if ( NULL != pPhysicalDestAddr )
{
// Call IfslDMA->DMAPhysicalCopyMem()
// to perform the memory copy using the DMA hardware
if ( TRUE == IfslDMA->DMAPhysicalCopyMem(pPhysicalSrcAddr,
pPhysicalDestAddr,lTestSize) )
{
// Success - Do something with the copied data
}
else
{
// Fallback and use CPU Copy instead (or do something else)
// Since we allocated the memory buffers using the FslDMA API,
// which returns the Physical address to that memory, and the
// IExec->CopyMemQuick() function expects the Virtual address,
// we first need to obtain the Virtual address for the Physical
// ones (using the FslDMA API again) before we can call our
// fallback copy function.
CONST_APTR pVirtualSrcAddr = NULL;
APTR pVirtualDestAddr = NULL;
pVirtualSrcAddr = IfslDMA->DMAGetVirtualAddress((APTR)pPhysicalSrcAddr);
pVirtualDestAddr = IfslDMA->DMAGetVirtualAddress(pPhysicalDestAddr);
IExec->CopyMemQuick(pVirtualSrcAddr,pVirtualDestAddr,lTestSize);
}
// We *must* use DMAFreePhysicalMemory() to free the memory
// that we allocated with DMAAllocPhysicalMemory()
IfslDMA->DMAFreePhysicalMemory(pPhysicalDestAddr);
}
// We *must* use DMAFreePhysicalMemory() to free the memory
// that we allocated with DMAAllocPhysicalMemory()
IfslDMA->DMAFreePhysicalMemory((APTR)pPhysicalSrcAddr);
}
}
</syntaxhighlight>

==== Obtaining the fsldma.resource ====

Breaking this example down the first thing we do is include the interface header for the fsldma.resource and obtain the resource itself.

<syntaxhighlight>
#include <interfaces/fsldma.h>
struct fslDMAIFace *IfslDMA = IExec->OpenResource(FSLDMA_NAME);
</syntaxhighlight>

==== Allocating DMA Compliant Memory ====

Once we have successfully obtained the DMA resource we can directly use its API. The next step we need to do is to allocate some memory '''which we know is DMA compliant''' for use by the resource. The easiest way to accomplish this is to use the IfslDMA->DMAAllocPhysicalMemory() function. This will automatically take care of ensuring the memory that is returned is properly aligned, contiguous, cache-inhibited and coherent.

We use the Tags version of the allocate memory function first so we can allocate a block of memory for our source buffer and fill it with some test value (in this case the byte value 0xB3).

<syntaxhighlight>
pPhysicalSrcAddr = (CONST_APTR)IfslDMA->DMAAllocPhysicalMemoryTags(lTestSize,
FSLDMA_APM_ClearWithValue, 0xB3,
TAG_END);
</syntaxhighlight>

We also need a destination buffer for our test. Since it only needs to start out being cleared (filled with zeroes), we can use the simplest form of the allocate memory function here as the allocated memory is cleared by default.

<syntaxhighlight>
pPhysicalDestAddr = IfslDMA->DMAAllocPhysicalMemory(lTestSize);
</syntaxhighlight>

==== The core function - Copy Physical Memory ====

Now that we have two DMA Compliant memory buffers available we can get to the heart of the API usage and make the call to IfslDMA->DMAPhysicalCopyMem().

<syntaxhighlight>
IfslDMA->DMAPhysicalCopyMem(pPhysicalSrcAddr,pPhysicalDestAddr,lTestSize);
</syntaxhighlight>

Looking at the full [[#Example usage|Example]] source above you can see that the DMAPhysicalCopyMem() call returns a Boolean value to indicate success or failure. Therefore, TRUE will be returned after the DMA hardware had completed copying the requested data (blocking call) and FALSE will be returned if a problem occurred.

Since the memory buffers we are using were allocated using the FslDMA API and our transfer size was greater than zero and less than or equal to the total size of either buffer, (in others words a legal copy request), there is '''very''' little chance that the DMAPhysicalCopyMem() function will fail. In fact, about the only reason the DMA hardware would fail to handle a legal transaction would be if the physical RAM installed in the system was faulty.

So even though it is extremely unlikely for our DMA copy to have failed and returned FALSE, let's take a look at how we might handle the failure. In other words, falling back and using a CPU based copy function instead to complete the data move.

Since we are reverting back to using a normal system copy memory function here, we first need to obtain the ''Virtual Addresses'' to both our source and destination buffers. This is accomplished by using the DMAGetVirtualAddress() function and passing in the Physical Address that was returned by DMAAllocPhysicalMemory().

<syntaxhighlight>
CONST_APTR pVirtualSrcAddr = NULL;
APTR pVirtualDestAddr = NULL;
pVirtualSrcAddr = IfslDMA->DMAGetVirtualAddress((APTR)pPhysicalSrcAddr);
pVirtualDestAddr = IfslDMA->DMAGetVirtualAddress(pPhysicalDestAddr);
</syntaxhighlight>

Now that we have the Virtual Address equivalents to the Physical Addresses that were returned by DMAAllocPhysicalMemory(), we can proceed to call the Exec CopyMemQuick() function to complete the copy. Here we can only trust that the IExec->CopyMemQuick() call can not fail since it does not return a result code.

<syntaxhighlight>
IExec->CopyMemQuick(pVirtualSrcAddr,pVirtualDestAddr,lTestSize);
</syntaxhighlight>

==== Cleaning up - Freeing DMA Compliant memory ====

It is essential that you free any memory that was allocated using the DMAAllocPhysicalMemory() function using the corresponding DMAFreePhysicalMemory() call. The reason for this is two-fold; first because additional resource tracking is maintained by the FslDMA API whenever it allocates memory which must itself be released, and second because the ''Physical Address'' to the memory is returned by the allocate call and not the ''Virtual Address'', so if you attempt to pass the address returned by DMAAllocPhysicalMemory() directly into IExec->FreeVec() it would likely result in a crash.

<syntaxhighlight>
IfslDMA->DMAFreePhysicalMemory(pPhysicalSrcAddr);
IfslDMA->DMAFreePhysicalMemory(pPhysicalDestAddr);
</syntaxhighlight>

Autodocs:Main

2019-11-13T01:47:03Z

Jamie Krueger:

The autodocs are included in the latest [[SDK_FAQ|AmigaOS SDK]] and are also available as text files below:

* [http://wiki.amigaos.net/amiga/autodocs/a1floppy.doc.txt a1floppy.doc]
* [http://wiki.amigaos.net/amiga/autodocs/a1serial_dev.doc.txt a1serial_dev.doc]
* [http://wiki.amigaos.net/amiga/autodocs/AI_Driver.doc.txt AI_Driver.doc]
* [http://wiki.amigaos.net/amiga/autodocs/amigaguide.doc.txt amigaguide.doc]
* [http://wiki.amigaos.net/amiga/autodocs/amigaguide_dtc.doc.txt amigaguide_dtc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/AmigaInput.doc.txt AmigaInput.doc]
* [http://wiki.amigaos.net/amiga/autodocs/amiga_lib.doc.txt amiga_lib.doc]
* [http://wiki.amigaos.net/amiga/autodocs/animation_dtc.doc.txt animation_dtc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/application.doc.txt application.doc]
* [http://wiki.amigaos.net/amiga/autodocs/arexx_cl.doc.txt arexx_cl.doc]
* [http://wiki.amigaos.net/amiga/autodocs/asl.doc.txt asl.doc]
* [http://wiki.amigaos.net/amiga/autodocs/audio.doc.txt audio.doc]
* [http://wiki.amigaos.net/amiga/autodocs/battclock.doc.txt battclock.doc]
* [http://wiki.amigaos.net/amiga/autodocs/battmem.doc.txt battmem.doc]
* [http://wiki.amigaos.net/amiga/autodocs/bevel_ic.doc.txt bevel_ic.doc]
* [http://wiki.amigaos.net/amiga/autodocs/biosversion.doc.txt biosversion.doc]
* [http://wiki.amigaos.net/amiga/autodocs/bitmap_ic.doc.txt bitmap_ic.doc]
* [http://wiki.amigaos.net/amiga/autodocs/bsdsocket.doc.txt bsdsocket.doc]
* [http://wiki.amigaos.net/amiga/autodocs/btree.doc.txt btree.doc]
* [http://wiki.amigaos.net/amiga/autodocs/bullet.doc.txt bullet.doc]
* [http://wiki.amigaos.net/amiga/autodocs/button_gc.doc.txt button_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/camd.doc.txt camd.doc]
* [http://wiki.amigaos.net/amiga/autodocs/cardres.doc.txt cardres.doc]
* [http://wiki.amigaos.net/amiga/autodocs/cd.doc.txt cd.doc]
* [http://wiki.amigaos.net/amiga/autodocs/checkbox_gc.doc.txt checkbox_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/chooser_gc.doc.txt chooser_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/cia.doc.txt cia.doc]
* [http://wiki.amigaos.net/amiga/autodocs/clicktab_gc.doc.txt clicktab_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/clipboard.doc.txt clipboard.doc]
* [http://wiki.amigaos.net/amiga/autodocs/colorwheel_gc.doc.txt colorwheel_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/commodities.doc.txt commodities.doc]
* [http://wiki.amigaos.net/amiga/autodocs/console.doc.txt console.doc]
* [http://wiki.amigaos.net/amiga/autodocs/datatypes.doc.txt datatypes.doc]
* [http://wiki.amigaos.net/amiga/autodocs/datebrowser_gc.doc.txt datebrowser_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/ddebug_lib.doc.txt ddebug_lib.doc]
* [http://wiki.amigaos.net/amiga/autodocs/debug_lib.doc.txt debug_lib.doc]
* [http://wiki.amigaos.net/amiga/autodocs/diffview_gc.doc.txt diffview_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/disk.doc.txt disk.doc]
* [http://wiki.amigaos.net/amiga/autodocs/diskfont.doc.txt diskfont.doc]
* [http://wiki.amigaos.net/amiga/autodocs/diskio.doc.txt diskio.doc]
* [http://wiki.amigaos.net/amiga/autodocs/docky.doc.txt docky.doc]
* [http://wiki.amigaos.net/amiga/autodocs/dos.doc.txt dos.doc]
* [http://wiki.amigaos.net/amiga/autodocs/dos.dospackets.doc.txt dos.dospackets.doc]
* [http://wiki.amigaos.net/amiga/autodocs/dos.obsolete.doc.txt dos.obsolete.doc]
* [http://wiki.amigaos.net/amiga/autodocs/drawlist_ic.doc.txt drawlist_ic.doc]
* [http://wiki.amigaos.net/amiga/autodocs/elf.doc.txt elf.doc]
* [http://wiki.amigaos.net/amiga/autodocs/exec.doc.txt exec.doc]
* [http://wiki.amigaos.net/amiga/autodocs/expansion.doc.txt expansion.doc]
* [http://wiki.amigaos.net/amiga/autodocs/filesysbox.doc.txt filesysbox.doc]
* [http://wiki.amigaos.net/amiga/autodocs/filesysres.doc.txt filesysres.doc]
* [http://wiki.amigaos.net/amiga/autodocs/filler_ic.doc.txt filler_ic.doc]
* [http://wiki.amigaos.net/amiga/autodocs/fillrect_ic.doc.txt fillrect_ic.doc]
* [http://wiki.amigaos.net/amiga/autodocs/frame_ic.doc.txt frame_ic.doc]
* [http://wiki.amigaos.net/amiga/autodocs/frbutton_gc.doc.txt frbutton_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/fsldmares.doc.txt fsldmares.doc]
* [http://wiki.amigaos.net/amiga/autodocs/fuelgauge_gc.doc.txt fuelgauge_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/gadget_gc.doc.txt gadget_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/gadtools.doc.txt gadtools.doc]
* [http://wiki.amigaos.net/amiga/autodocs/gameport.doc.txt gameport.doc]
* [http://wiki.amigaos.net/amiga/autodocs/Gameport_pci.doc.txt Gameport_pci.doc]
* [http://wiki.amigaos.net/amiga/autodocs/gauge_ic.doc.txt gauge_ic.doc]
* [http://wiki.amigaos.net/amiga/autodocs/getcolor_gc.doc.txt getcolor_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/getfile_gc.doc.txt getfile_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/getfont_gc.doc.txt getfont_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/getscreenmode_gc.doc.txt getscreenmode_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/glyph_ic.doc.txt glyph_ic.doc]
* [http://wiki.amigaos.net/amiga/autodocs/gradientslider_gc.doc.txt gradientslider_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/graphics.doc.txt graphics.doc]
* [http://wiki.amigaos.net/amiga/autodocs/group_gc.doc.txt group_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/hunk.doc.txt hunk.doc]
* [http://wiki.amigaos.net/amiga/autodocs/ibutton_gc.doc.txt ibutton_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/icon.doc.txt icon.doc]
* [http://wiki.amigaos.net/amiga/autodocs/iconmodule.doc.txt iconmodule.doc]
* [http://wiki.amigaos.net/amiga/autodocs/ic_cl.doc.txt ic_cl.doc]
* [http://wiki.amigaos.net/amiga/autodocs/iffparse.doc.txt iffparse.doc]
* [http://wiki.amigaos.net/amiga/autodocs/image_ic.doc.txt image_ic.doc]
* [http://wiki.amigaos.net/amiga/autodocs/input.doc.txt input.doc]
* [http://wiki.amigaos.net/amiga/autodocs/integer_gc.doc.txt integer_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/intuition.doc.txt intuition.doc]
* [http://wiki.amigaos.net/amiga/autodocs/iscroller_gc.doc.txt iscroller_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/istring_gc.doc.txt istring_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/itext_ic.doc.txt itext_ic.doc]
* [http://wiki.amigaos.net/amiga/autodocs/keyboard.doc.txt keyboard.doc]
* [http://wiki.amigaos.net/amiga/autodocs/keymap.doc.txt keymap.doc]
* [http://wiki.amigaos.net/amiga/autodocs/label_ic.doc.txt label_ic.doc]
* [http://wiki.amigaos.net/amiga/autodocs/layers.doc.txt layers.doc]
* [http://wiki.amigaos.net/amiga/autodocs/layout_gc.doc.txt layout_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/libamiga_a.doc.txt libamiga_a.doc]
* [http://wiki.amigaos.net/amiga/autodocs/listbrowser_gc.doc.txt listbrowser_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/locale.doc.txt locale.doc]
* [http://wiki.amigaos.net/amiga/autodocs/lowlevel.doc.txt lowlevel.doc]
* [http://wiki.amigaos.net/amiga/autodocs/mathffp.doc.txt mathffp.doc]
* [http://wiki.amigaos.net/amiga/autodocs/mathieeedoubbas.doc.txt mathieeedoubbas.doc]
* [http://wiki.amigaos.net/amiga/autodocs/mathieeedoubtrans.doc.txt mathieeedoubtrans.doc]
* [http://wiki.amigaos.net/amiga/autodocs/mathieeesingbas.doc.txt mathieeesingbas.doc]
* [http://wiki.amigaos.net/amiga/autodocs/mathieeesingtrans.doc.txt mathieeesingtrans.doc]
* [http://wiki.amigaos.net/amiga/autodocs/mathtrans.doc.txt mathtrans.doc]
* [http://wiki.amigaos.net/amiga/autodocs/menu_cl.doc.txt menu_cl.doc]
* [http://wiki.amigaos.net/amiga/autodocs/misc.doc.txt misc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/model_cl.doc.txt model_cl.doc]
* [http://wiki.amigaos.net/amiga/autodocs/narrator.doc.txt narrator.doc]
* [http://wiki.amigaos.net/amiga/autodocs/nonvolatile.doc.txt nonvolatile.doc]
* [http://wiki.amigaos.net/amiga/autodocs/openfirmware.doc.txt openfirmware.doc]
* [http://wiki.amigaos.net/amiga/autodocs/page_gc.doc.txt page_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/palette_gc.doc.txt palette_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/parallel.doc.txt parallel.doc]
* [http://wiki.amigaos.net/amiga/autodocs/partition_gc.doc.txt partition_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/penmap_ic.doc.txt penmap_ic.doc]
* [http://wiki.amigaos.net/amiga/autodocs/performancemonitor.doc.txt performancemonitor.doc]
* [http://wiki.amigaos.net/amiga/autodocs/Picasso96API.doc.txt Picasso96API.doc]
* [http://wiki.amigaos.net/amiga/autodocs/picture_dtc.doc.txt picture_dtc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/pointer_cl.doc.txt pointer_cl.doc]
* [http://wiki.amigaos.net/amiga/autodocs/popupmenu_cl.doc.txt popupmenu_cl.doc]
* [http://wiki.amigaos.net/amiga/autodocs/potgo.doc.txt potgo.doc]
* [http://wiki.amigaos.net/amiga/autodocs/printer.doc.txt printer.doc]
* [http://wiki.amigaos.net/amiga/autodocs/prop_gc.doc.txt prop_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/radiobutton_gc.doc.txt radiobutton_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/realtime.doc.txt realtime.doc]
* [http://wiki.amigaos.net/amiga/autodocs/requester_cl.doc.txt requester_cl.doc]
* [http://wiki.amigaos.net/amiga/autodocs/resource.doc.txt resource.doc]
* [http://wiki.amigaos.net/amiga/autodocs/rexxsyslib.doc.txt rexxsyslib.doc]
* [http://wiki.amigaos.net/amiga/autodocs/root_cl.doc.txt root_cl.doc]
* [http://wiki.amigaos.net/amiga/autodocs/scroller_gc.doc.txt scroller_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/serial_dev.doc.txt serial_dev.doc]
* [http://wiki.amigaos.net/amiga/autodocs/sketchboard_gc.doc.txt sketchboard_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/slider_gc.doc.txt slider_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/sound_dtc.doc.txt sound_dtc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/space_gc.doc.txt space_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/speedbar_gc.doc.txt speedbar_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/string_gc.doc.txt string_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/sys_ic.doc.txt sys_ic.doc]
* [http://wiki.amigaos.net/amiga/autodocs/tapedeck_gc.doc.txt tapedeck_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/textclip.doc.txt textclip.doc]
* [http://wiki.amigaos.net/amiga/autodocs/texteditor_gc.doc.txt texteditor_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/text_dtc.doc.txt text_dtc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/timer.doc.txt timer.doc]
* [http://wiki.amigaos.net/amiga/autodocs/timesync.doc.txt timesync.doc]
* [http://wiki.amigaos.net/amiga/autodocs/timezone.doc.txt timezone.doc]
* [http://wiki.amigaos.net/amiga/autodocs/trackdisk.doc.txt trackdisk.doc]
* [http://wiki.amigaos.net/amiga/autodocs/translator.doc.txt translator.doc]
* [http://wiki.amigaos.net/amiga/autodocs/usbfd.doc.txt usbfd.doc]
* [http://wiki.amigaos.net/amiga/autodocs/usbhcd.doc.txt usbhcd.doc]
* [http://wiki.amigaos.net/amiga/autodocs/usbresource.doc.txt usbresource.doc]
* [http://wiki.amigaos.net/amiga/autodocs/usbsys.doc.txt usbsys.doc]
* [http://wiki.amigaos.net/amiga/autodocs/utility.doc.txt utility.doc]
* [http://wiki.amigaos.net/amiga/autodocs/virtual_gc.doc.txt virtual_gc.doc]
* [http://wiki.amigaos.net/amiga/autodocs/warp3d.doc.txt warp3d.doc]
* [http://wiki.amigaos.net/amiga/autodocs/window_cl.doc.txt window_cl.doc]
* [http://wiki.amigaos.net/amiga/autodocs/workbench.doc.txt workbench.doc]
* [http://wiki.amigaos.net/amiga/autodocs/xenares.doc.txt xenares.doc]
* [http://wiki.amigaos.net/amiga/autodocs/z.doc.txt z.doc]

DMA Resource

2019-11-13T01:46:12Z

Jamie Krueger:

== DMA Engine ==

Some hardware targets include a DMA engine which can be used for general purpose copying. This article describes the DMA engines available and how to use them.

=== Hardware Features ===

The Direct Memory Access (DMA) Engines found in the NXP/Freescale p5020, p5040 and p1022 System On a Chip (SoC)s, found in the AmigaONE X5000/20, X5000/40 and A1222 respectively, are quite flexible and powerful. Each of these chips contains two distinct engines with four data channels each. This provides the ability to have a total of eight DMA Channels working at once, with up to two DMA transactions actually being executed at the same time (one on each of the two DMA Engines).

Further, each of the four DMA Channels found in a DMA Engine may be individually programmed to handle either; a single transaction, a ''Chain'' of transactions, or even ''Lists'' of ''Chains'' of transactions. The DMA Engines automatically arbitrate between each DMA Channel following programmed bandwidth settings for each Channel (typically 1024 bytes).

This means that after completing a transfer of 1024 bytes (for example), the hardware will consider switching to the next Channel to allow it to move another block of data, and so on in a round-robin fashion. If all other DMA Channels on a given DMA Engine are idle when arbitration would take place, the hardware will not arbitrate and simply continue processing the transaction(s) for the Channel it is on.

== fsldma.resource ==

The fsldma.resource API is provided automatically in the kernel for all supported machines (Currently the AmigaONE X5000/20, X5000/40 and A1222).

=== The FslDMA API ===

The API provided by the fsldma.resource breaks down into three main parts:
:* Memory management
:* Copy Memory functions
:* Utility / Miscellaneous

==== Memory Management Functions ====

The FslDMA resource API provides convenience functions for the allocation and freeing of '''DMA Compliant''' blocks of memory. Two functions are provided for this purpose; DMAAllocPhysicalMemory() and DMAFreePhysicalMemory().

The memory allocation function also includes two Tags based versions of the call to allow for addition variables to be passed into the call using a variable set of Tags or fixed TagList. Currently the only supported Tag is ''FSLDMA_APM_ClearWithValue'', which is the equivalent to the IExec->AllocVecTagList() function's AVT_ClearWithValue tag. If the FSLDMA_APM_ClearWithValue tag is not provided then the requested memory block is cleared with zeroes by default before being returned.

<syntaxhighlight>
APTR DMAAllocPhysicalMemoryTagList( uint32 lSize, const struct TagItem *tags );
APTR DMAAllocPhysicalMemoryTags( uint32 lSize, uint32 Tag1, ... );
APTR DMAAllocPhysicalMemory( uint32 lSize );
</syntaxhighlight>

The corresponding function to allocating a DMA Compliant memory block is DMAFreePhysicalMemory(). Any memory allocated using DMAAllocPhysicalMemory() must be eventually freed using DMAFreePhysicalMemory().

<syntaxhighlight>
void DMAFreePhysicalMemory( APTR pPhysicalMemoryBlock );
</syntaxhighlight>

==== Copy Memory Functions ====

Two API calls make up the core of the FslDMA API; DMAPhysicalCopyMem() and DMACopyMem().
Both of these calls will "block" (not return to the user) until after the requested transfer has either succeeded or failed.

<syntaxhighlight>
BOOL DMAPhysicalCopyMem( CONST_APTR pPhysicalSourceBuffer, APTR pPhysicalDestBuffer, uint32 lBufferSize );
BOOL DMACopyMem( CONST_APTR pSourceBuffer, APTR pDestBuffer, uint32 lBufferSize );
</syntaxhighlight>

As the name implies the first (and core version) of the copy memory functions, DMAPhysicalCopyMem(), accepts the Physical Addresses to the source and destination buffers (as returned by DMAAllocPhysicalMemory()), along with an unsigned 32-Bit value for the amount of bytes that should be copied (lBuffsize must be greater than zero(0) and no more than the maximum size of the source and destination buffers).

DMAPhysicalCopyMem() is the most direct an efficient means of using the DMA hardware to effect a single memory copy. The DMACopyMem() function is provided as an alternative way to request a DMA transfer by passing in the ''Virtual Addresses'' to the source and destination buffers instead of the Physical Addresses. DMACopyMem() will attempt to determine if the supplied memory buffers are DMA Compliant and if so it will internally use DMAPhysicalCopyMem() to handle the transaction. If DMACopyMem() determines that the supplied memory is '''not''' DMA Compliant it will return FALSE and no data copy will occur.

In theory any ''contiguous'' block of memory from 1 Byte up to 4GB in size may be transferred using either one of these calls. In practice the DMA hardware can directly accept memory blocks up to FSLDMA_MAXBLOCK_SIZE (or 64MB - 1 Byte). Therefore any data blocks greater than FSLDMA_MAXBLOCK_SIZE will automatically be feed to the DMA hardware in a series of smaller chunks. For maximum efficiency transfer sizes should be at least 256 Bytes in size and be an even multiple of 64 Bytes. Odd sizes are handled by the hardware but will degrade performance.

If you are transferring many large blocks of data in series and wish to manually send them to the FslDMA API's memory copy functions one block at a time, then setting your block sizes to FSLDMA_OPTIMAL_BLKSIZE (or 64 MB - 64 Bytes) and exclusively using DMAPhysicalCopyMem() will provide the fastest transfer speeds will the least amount of CPU overhead.

==== Utility / Miscellaneous Functions ====

The last section to the FslDMA API provides a single convenience function call; DMAGetVirtualAddress().

<syntaxhighlight>
APTR DMAGetVirtualAddress( APTR pPhysicalAddress );
</syntaxhighlight>

The DMAGetVirtualAddress() function returns the Virtual memory location for the Physical memory location that was itself allocated and returned by the DMAAllocPhysicalMemory() function. DMAGetVirtualAddress() will not work on physical addresses returned by IMMU->GetPhysicalAddress() on memory not allocated using DMAAllocPhysicalMemory().

The main purpose of this function (other then debugging purposes) is to provide the "normal" Virtual Address of memory allocated by the FslDMA API for use by functions that expect "normal" Virtual address locations; for example IExec->CopyMemQuick().

==== Further reference - The fsldma.resource AutoDoc ====

See the [[http://wiki.amigaos.net/amiga/autodocs/fsldmares.doc.txt fsldma.resource AutoDoc]] file for more details on each API call.

=== Example usage ===
<syntaxhighlight>
#include <interfaces/fsldma.h>
// Obtain the fsldma.resource
struct fslDMAIFace *IfslDMA = IExec->OpenResource(FSLDMA_NAME);
if ( NULL != IfslDMA )
{
uint32 lTestSize = 1024;
CONST_APTR pPhysicalSrcAddr = NULL;
APTR pPhysicalDestAddr = NULL;
// Allocate the Source Buffer (for DMA)
// and set the contents to 0xB3 (just an example value)
pPhysicalSrcAddr = (CONST_APTR)IfslDMA->DMAAllocPhysicalMemoryTags(lTestSize,
FSLDMA_APM_ClearWithValue, 0xB3,
TAG_END);
if ( NULL != pPhysicalSrcAddr )
{
// Allocate the Destination Buffer (for DMA)
// - contents will by cleared by default
pPhysicalDestAddr = IfslDMA->DMAAllocPhysicalMemory(lTestSize);
if ( NULL != pPhysicalDestAddr )
{
// Call IfslDMA->DMAPhysicalCopyMem()
// to perform the memory copy using the DMA hardware
if ( TRUE == IfslDMA->DMAPhysicalCopyMem(pPhysicalSrcAddr,
pPhysicalDestAddr,lTestSize) )
{
// Success - Do something with the copied data
}
else
{
// Fallback and use CPU Copy instead (or do something else)
// Since we allocated the memory buffers using the FslDMA API,
// which returns the Physical address to that memory, and the
// IExec->CopyMemQuick() function expects the Virtual address,
// we first need to obtain the Virtual address for the Physical
// ones (using the FslDMA API again) before we can call our
// fallback copy function.
CONST_APTR pVirtualSrcAddr = NULL;
APTR pVirtualDestAddr = NULL;
pVirtualSrcAddr = IfslDMA->DMAGetVirtualAddress((APTR)pPhysicalSrcAddr);
pVirtualDestAddr = IfslDMA->DMAGetVirtualAddress(pPhysicalDestAddr);
IExec->CopyMemQuick(pVirtualSrcAddr,pVirtualDestAddr,lTestSize);
}
// We *must* use DMAFreePhysicalMemory() to free the memory
// that we allocated with DMAAllocPhysicalMemory()
IfslDMA->DMAFreePhysicalMemory(pPhysicalDestAddr);
}
// We *must* use DMAFreePhysicalMemory() to free the memory
// that we allocated with DMAAllocPhysicalMemory()
IfslDMA->DMAFreePhysicalMemory((APTR)pPhysicalSrcAddr);
}
}
</syntaxhighlight>

==== Obtaining the fsldma.resource ====

Breaking this example down the first thing we do is include the interface header for the fsldma.resource and obtain the resource itself.

<syntaxhighlight>
#include <interfaces/fsldma.h>
struct fslDMAIFace *IfslDMA = IExec->OpenResource(FSLDMA_NAME);
</syntaxhighlight>

==== Allocating DMA Compliant Memory ====

Once we have successfully obtained the DMA resource we can directly use its API. The next step we need to do is to allocate some memory '''which we know is DMA compliant''' for use by the resource. The easiest way to accomplish this is to use the IfslDMA->DMAAllocPhysicalMemory() function. This will automatically take care of ensuring the memory that is returned is properly aligned, contiguous, cache-inhibited and coherent.

We use the Tags version of the allocate memory function first so we can allocate a block of memory for our source buffer and fill it with some test value (in this case the byte value 0xB3).

<syntaxhighlight>
pPhysicalSrcAddr = (CONST_APTR)IfslDMA->DMAAllocPhysicalMemoryTags(lTestSize,
FSLDMA_APM_ClearWithValue, 0xB3,
TAG_END);
</syntaxhighlight>

We also need a destination buffer for our test. Since it only needs to start out being cleared (filled with zeroes), we can use the simplest form of the allocate memory function here as the allocated memory is cleared by default.

<syntaxhighlight>
pPhysicalDestAddr = IfslDMA->DMAAllocPhysicalMemory(lTestSize);
</syntaxhighlight>

==== The core function - Copy Physical Memory ====

Now that we have two DMA Compliant memory buffers available we can get to the heart of the API usage and make the call to IfslDMA->DMAPhysicalCopyMem().

<syntaxhighlight>
IfslDMA->DMAPhysicalCopyMem(pPhysicalSrcAddr,pPhysicalDestAddr,lTestSize);
</syntaxhighlight>

Looking at the full [[#Example usage|Example]] source above you can see that the DMAPhysicalCopyMem() call returns a Boolean value to indicate success or failure. Therefore, TRUE will be returned after the DMA hardware had completed copying the requested data (blocking call) and FALSE will be returned if a problem occurred.

Since the memory buffers we are using were allocated using the FslDMA API and our transfer size was greater than zero and less than or equal to the total size of either buffer, (in others words a legal copy request), there is '''very''' little chance that the DMAPhysicalCopyMem() function will fail. In fact, about the only reason the DMA hardware would fail to handle a legal transaction would be if the physical RAM installed in the system was faulty.

So even though it is extremely unlikely for our DMA copy to have failed and returned FALSE, let's take a look at how we might handle the failure. In other words, falling back and using a CPU based copy function instead to complete the data move.

Since we are reverting back to using a normal system copy memory function here, we first need to obtain the ''Virtual Addresses'' to both our source and destination buffers. This is accomplished by using the DMAGetVirtualAddress() function and passing in the Physical Address that was returned by DMAAllocPhysicalMemory().

<syntaxhighlight>
CONST_APTR pVirtualSrcAddr = NULL;
APTR pVirtualDestAddr = NULL;
pVirtualSrcAddr = IfslDMA->DMAGetVirtualAddress((APTR)pPhysicalSrcAddr);
pVirtualDestAddr = IfslDMA->DMAGetVirtualAddress(pPhysicalDestAddr);
</syntaxhighlight>

Now that we have the Virtual Address equivalents to the Physical Addresses that were returned by DMAAllocPhysicalMemory(), we can proceed to call the Exec CopyMemQuick() function to complete the copy. Here we can only trust that the IExec->CopyMemQuick() call can not fail since it does not return a result code.

<syntaxhighlight>
IExec->CopyMemQuick(pVirtualSrcAddr,pVirtualDestAddr,lTestSize);
</syntaxhighlight>

==== Cleaning up - Freeing DMA Compliant memory ====

It is essential that you free any memory that was allocated using the DMAAllocPhysicalMemory() function using the corresponding DMAFreePhysicalMemory() call. The reason for this is two-fold; first because additional resource tracking is maintained by the FslDMA API whenever it allocates memory which must itself be released, and second because the ''Physical Address'' to the memory is returned by the allocate call and not the ''Virtual Address'', so if you attempt to pass the address returned by DMAAllocPhysicalMemory() directly into IExec->FreeVec() it would likely result in a crash.

<syntaxhighlight>
IfslDMA->DMAFreePhysicalMemory(pPhysicalSrcAddr);
IfslDMA->DMAFreePhysicalMemory(pPhysicalDestAddr);
</syntaxhighlight>

DMA Resource

2019-11-13T01:37:50Z

Jamie Krueger:

== DMA Engine ==

Some hardware targets include a DMA engine which can be used for general purpose copying. This article describes the DMA engines available and how to use them.

=== Hardware Features ===

The Direct Memory Access (DMA) Engines found in the NXP/Freescale p5020, p5040 and p1022 System On a Chip (SoC)s, found in the AmigaONE X5000/20, X5000/40 and A1222 respectively, are quite flexible and powerful. Each of these chips contains two distinct engines with four data channels each. This provides the ability to have a total of eight DMA Channels working at once, with up to two DMA transactions actually being executed at the same time (one on each of the two DMA Engines).

Further, each of the four DMA Channels found in a DMA Engine may be individually programmed to handle either; a single transaction, a ''Chain'' of transactions, or even ''Lists'' of ''Chains'' of transactions. The DMA Engines automatically arbitrate between each DMA Channel following programmed bandwidth settings for each Channel (typically 1024 bytes).

This means that after completing a transfer of 1024 bytes (for example), the hardware will consider switching to the next Channel to allow it to move another block of data, and so on in a round-robin fashion. If all other DMA Channels on a given DMA Engine are idle when arbitration would take place, the hardware will not arbitrate and simply continue processing the transaction(s) for the Channel it is on.

== fsldma.resource ==

The fsldma.resource API is provided automatically in the kernel for all supported machines (Currently the AmigaONE X5000/20, X5000/40 and A1222).

=== The FslDMA API ===

The API provided by the fsldma.resource breaks down into three main parts:
:* Memory management
:* Copy Memory functions
:* Utility / Miscellaneous

==== Memory Management Functions ====

The FslDMA resource API provides convenience functions for the allocation and freeing of '''DMA Compliant''' blocks of memory. Two functions are provided for this purpose; DMAAllocPhysicalMemory() and DMAFreePhysicalMemory().

The memory allocation function also includes two Tags based versions of the call to allow for addition variables to be passed into the call using a variable set of Tags or fixed TagList. Currently the only supported Tag is ''FSLDMA_APM_ClearWithValue'', which is the equivalent to the IExec->AllocVecTagList() function's AVT_ClearWithValue tag. If the FSLDMA_APM_ClearWithValue tag is not provided then the requested memory block is cleared with zeroes by default before being returned.

<syntaxhighlight>
APTR DMAAllocPhysicalMemoryTagList( uint32 lSize, const struct TagItem *tags );
APTR DMAAllocPhysicalMemoryTags( uint32 lSize, uint32 Tag1, ... );
APTR DMAAllocPhysicalMemory( uint32 lSize );
</syntaxhighlight>

The corresponding function to allocating a DMA Compliant memory block is DMAFreePhysicalMemory(). Any memory allocated using DMAAllocPhysicalMemory() must be eventually freed using DMAFreePhysicalMemory().

<syntaxhighlight>
void DMAFreePhysicalMemory( APTR pPhysicalMemoryBlock );
</syntaxhighlight>

==== Copy Memory Functions ====

Two API calls make up the core of the FslDMA API; DMAPhysicalCopyMem() and DMACopyMem().
Both of these calls will "block" (not return to the user) until after the requested transfer has either succeeded or failed.

<syntaxhighlight>
BOOL DMAPhysicalCopyMem( CONST_APTR pPhysicalSourceBuffer, APTR pPhysicalDestBuffer, uint32 lBufferSize );
BOOL DMACopyMem( CONST_APTR pSourceBuffer, APTR pDestBuffer, uint32 lBufferSize );
</syntaxhighlight>

As the name implies the first (and core version) of the copy memory functions, DMAPhysicalCopyMem(), accepts the Physical Addresses to the source and destination buffers (as returned by DMAAllocPhysicalMemory()), along with an unsigned 32-Bit value for the amount of bytes that should be copied (lBuffsize must be greater than zero(0) and no more than the maximum size of the source and destination buffers).

DMAPhysicalCopyMem() is the most direct an efficient means of using the DMA hardware to effect a single memory copy. The DMACopyMem() function is provided as an alternative way to request a DMA transfer by passing in the ''Virtual Addresses'' to the source and destination buffers instead of the Physical Addresses. DMACopyMem() will attempt to determine if the supplied memory buffers are DMA Compliant and if so it will internally use DMAPhysicalCopyMem() to handle the transaction. If DMACopyMem() determines that the supplied memory is '''not''' DMA Compliant it will return FALSE and no data copy will occur.

In theory any ''contiguous'' block of memory from 1 Byte up to 4GB in size may be transferred using either one of these calls. In practice the DMA hardware can directly accept memory blocks up to FSLDMA_MAXBLOCK_SIZE (or 64MB - 1 Byte). Therefore any data blocks greater than FSLDMA_MAXBLOCK_SIZE will automatically be feed to the DMA hardware in a series of smaller chunks. For maximum efficiency transfer sizes should be at least 256 Bytes in size and be an even multiple of 64 Bytes. Odd sizes are handled by the hardware but will degrade performance.

If you are transferring many large blocks of data in series and wish to manually send them to the FslDMA API's memory copy functions one block at a time, then setting your block sizes to FSLDMA_OPTIMAL_BLKSIZE (or 64 MB - 64 Bytes) and exclusively using DMAPhysicalCopyMem() will provide the fastest transfer speeds will the least amount of CPU overhead.

==== Utility / Miscellaneous Functions ====

The last section to the FslDMA API provides a single convenience function call; DMAGetVirtualAddress().

<syntaxhighlight>
APTR DMAGetVirtualAddress( APTR pPhysicalAddress );
</syntaxhighlight>

The DMAGetVirtualAddress() function returns the Virtual memory location for the Physical memory location that was itself allocated and returned by the DMAAllocPhysicalMemory() function. DMAGetVirtualAddress() will not work on physical addresses returned by IMMU->GetPhysicalAddress() on memory not allocated using DMAAllocPhysicalMemory().

The main purpose of this function (other then debugging purposes) is to provide the "normal" Virtual Address of memory allocated by the FslDMA API for use by functions that expect "normal" Virtual address locations; for example IExec->CopyMemQuick().

=== Example usage ===
<syntaxhighlight>
#include <interfaces/fsldma.h>
// Obtain the fsldma.resource
struct fslDMAIFace *IfslDMA = IExec->OpenResource(FSLDMA_NAME);
if ( NULL != IfslDMA )
{
uint32 lTestSize = 1024;
CONST_APTR pPhysicalSrcAddr = NULL;
APTR pPhysicalDestAddr = NULL;
// Allocate the Source Buffer (for DMA)
// and set the contents to 0xB3 (just an example value)
pPhysicalSrcAddr = (CONST_APTR)IfslDMA->DMAAllocPhysicalMemoryTags(lTestSize,
FSLDMA_APM_ClearWithValue, 0xB3,
TAG_END);
if ( NULL != pPhysicalSrcAddr )
{
// Allocate the Destination Buffer (for DMA)
// - contents will by cleared by default
pPhysicalDestAddr = IfslDMA->DMAAllocPhysicalMemory(lTestSize);
if ( NULL != pPhysicalDestAddr )
{
// Call IfslDMA->DMAPhysicalCopyMem()
// to perform the memory copy using the DMA hardware
if ( TRUE == IfslDMA->DMAPhysicalCopyMem(pPhysicalSrcAddr,
pPhysicalDestAddr,lTestSize) )
{
// Success - Do something with the copied data
}
else
{
// Fallback and use CPU Copy instead (or do something else)
// Since we allocated the memory buffers using the FslDMA API,
// which returns the Physical address to that memory, and the
// IExec->CopyMemQuick() function expects the Virtual address,
// we first need to obtain the Virtual address for the Physical
// ones (using the FslDMA API again) before we can call our
// fallback copy function.
CONST_APTR pVirtualSrcAddr = NULL;
APTR pVirtualDestAddr = NULL;
pVirtualSrcAddr = IfslDMA->DMAGetVirtualAddress((APTR)pPhysicalSrcAddr);
pVirtualDestAddr = IfslDMA->DMAGetVirtualAddress(pPhysicalDestAddr);
IExec->CopyMemQuick(pVirtualSrcAddr,pVirtualDestAddr,lTestSize);
}
// We *must* use DMAFreePhysicalMemory() to free the memory
// that we allocated with DMAAllocPhysicalMemory()
IfslDMA->DMAFreePhysicalMemory(pPhysicalDestAddr);
}
// We *must* use DMAFreePhysicalMemory() to free the memory
// that we allocated with DMAAllocPhysicalMemory()
IfslDMA->DMAFreePhysicalMemory((APTR)pPhysicalSrcAddr);
}
}
</syntaxhighlight>

==== Obtaining the fsldma.resource ====

Breaking this example down the first thing we do is include the interface header for the fsldma.resource and obtain the resource itself.

<syntaxhighlight>
#include <interfaces/fsldma.h>
struct fslDMAIFace *IfslDMA = IExec->OpenResource(FSLDMA_NAME);
</syntaxhighlight>

==== Allocating DMA Compliant Memory ====

Once we have successfully obtained the DMA resource we can directly use its API. The next step we need to do is to allocate some memory '''which we know is DMA compliant''' for use by the resource. The easiest way to accomplish this is to use the IfslDMA->DMAAllocPhysicalMemory() function. This will automatically take care of ensuring the memory that is returned is properly aligned, contiguous, cache-inhibited and coherent.

We use the Tags version of the allocate memory function first so we can allocate a block of memory for our source buffer and fill it with some test value (in this case the byte value 0xB3).

<syntaxhighlight>
pPhysicalSrcAddr = (CONST_APTR)IfslDMA->DMAAllocPhysicalMemoryTags(lTestSize,
FSLDMA_APM_ClearWithValue, 0xB3,
TAG_END);
</syntaxhighlight>

We also need a destination buffer for our test. Since it only needs to start out being cleared (filled with zeroes), we can use the simplest form of the allocate memory function here as the allocated memory is cleared by default.

<syntaxhighlight>
pPhysicalDestAddr = IfslDMA->DMAAllocPhysicalMemory(lTestSize);
</syntaxhighlight>

==== The core function - Copy Physical Memory ====

Now that we have two DMA Compliant memory buffers available we can get to the heart of the API usage and make the call to IfslDMA->DMAPhysicalCopyMem().

<syntaxhighlight>
IfslDMA->DMAPhysicalCopyMem(pPhysicalSrcAddr,pPhysicalDestAddr,lTestSize);
</syntaxhighlight>

Looking at the full [[#Example usage|Example]] source above you can see that the DMAPhysicalCopyMem() call returns a Boolean value to indicate success or failure. Therefore, TRUE will be returned after the DMA hardware had completed copying the requested data (blocking call) and FALSE will be returned if a problem occurred.

Since the memory buffers we are using were allocated using the FslDMA API and our transfer size was greater than zero and less than or equal to the total size of either buffer, (in others words a legal copy request), there is '''very''' little chance that the DMAPhysicalCopyMem() function will fail. In fact, about the only reason the DMA hardware would fail to handle a legal transaction would be if the physical RAM installed in the system was faulty.

So even though it is extremely unlikely for our DMA copy to have failed and returned FALSE, let's take a look at how we might handle the failure. In other words, falling back and using a CPU based copy function instead to complete the data move.

Since we are reverting back to using a normal system copy memory function here, we first need to obtain the ''Virtual Addresses'' to both our source and destination buffers. This is accomplished by using the DMAGetVirtualAddress() function and passing in the Physical Address that was returned by DMAAllocPhysicalMemory().

<syntaxhighlight>
CONST_APTR pVirtualSrcAddr = NULL;
APTR pVirtualDestAddr = NULL;
pVirtualSrcAddr = IfslDMA->DMAGetVirtualAddress((APTR)pPhysicalSrcAddr);
pVirtualDestAddr = IfslDMA->DMAGetVirtualAddress(pPhysicalDestAddr);
</syntaxhighlight>

Now that we have the Virtual Address equivalents to the Physical Addresses that were returned by DMAAllocPhysicalMemory(), we can proceed to call the Exec CopyMemQuick() function to complete the copy. Here we can only trust that the IExec->CopyMemQuick() call can not fail since it does not return a result code.

<syntaxhighlight>
IExec->CopyMemQuick(pVirtualSrcAddr,pVirtualDestAddr,lTestSize);
</syntaxhighlight>

==== Cleaning up - Freeing DMA Compliant memory ====

It is essential that you free any memory that was allocated using the DMAAllocPhysicalMemory() function using the corresponding DMAFreePhysicalMemory() call. The reason for this is two-fold; first because additional resource tracking is maintained by the FslDMA API whenever it allocates memory which must itself be released, and second because the ''Physical Address'' to the memory is returned by the allocate call and not the ''Virtual Address'', so if you attempt to pass the address returned by DMAAllocPhysicalMemory() directly into IExec->FreeVec() it would likely result in a crash.

<syntaxhighlight>
IfslDMA->DMAFreePhysicalMemory(pPhysicalSrcAddr);
IfslDMA->DMAFreePhysicalMemory(pPhysicalDestAddr);
</syntaxhighlight>

DMA Resource

2019-11-13T01:37:10Z

Jamie Krueger: /* Utility / Miscellaneous Functions */

== DMA Engine ==

Some hardware targets include a DMA engine which can be used for general purpose copying. This article describes the DMA engines available and how to use them.

=== Hardware Features ===

The Direct Memory Access (DMA) Engines found in the NXP/Freescale p5020, p5040 and p1022 System On a Chip (SoC)s, found in the AmigaONE X5000/20, X5000/40 and A1222 respectively, are quite flexible and powerful. Each of these chips contains two distinct engines with four data channels each. This provides the ability to have a total of eight DMA Channels working at once, with up to two DMA transactions actually being executed at the same time (one on each of the two DMA Engines).

Further, each of the four DMA Channels found in a DMA Engine may be individually programmed to handle either; a single transaction, a ''Chain'' of transactions, or even ''Lists'' of ''Chains'' of transactions. The DMA Engines automatically arbitrate between each DMA Channel following programmed bandwidth settings for each Channel (typically 1024 bytes).

This means that after completing a transfer of 1024 bytes (for example), the hardware will consider switching to the next Channel to allow it to move another block of data, and so on in a round-robin fashion. If all other DMA Channels on a given DMA Engine are idle when arbitration would take place, the hardware will not arbitrate and simply continue processing the transaction(s) for the Channel it is on.

== fsldma.resource ==

The fsldma.resource API is provided automatically in the kernel for all supported machines (Currently the AmigaONE X5000/20, X5000/40 and A1222).

=== The FslDMA API ===

The API provided by the fsldma.resource breaks down into three main parts:
:* Memory management
:* Copy Memory functions
:* Utility / Miscellaneous

==== Memory Management Functions ====

The FslDMA resource API provides convenience functions for the allocation and freeing of '''DMA Compliant''' blocks of memory. Two functions are provided for this purpose; DMAAllocPhysicalMemory() and DMAFreePhysicalMemory().

The memory allocation function also includes two Tags based versions of the call to allow for addition variables to be passed into the call using a variable set of Tags or fixed TagList. Currently the only supported Tag is ''FSLDMA_APM_ClearWithValue'', which is the equivalent to the IExec->AllocVecTagList() function's AVT_ClearWithValue tag. If the FSLDMA_APM_ClearWithValue tag is not provided then the requested memory block is cleared with zeroes by default before being returned.

<syntaxhighlight>
APTR DMAAllocPhysicalMemoryTagList( uint32 lSize, const struct TagItem *tags );
APTR DMAAllocPhysicalMemoryTags( uint32 lSize, uint32 Tag1, ... );
APTR DMAAllocPhysicalMemory( uint32 lSize );
</syntaxhighlight>

The corresponding function to allocating a DMA Compliant memory block is DMAFreePhysicalMemory(). Any memory allocated using DMAAllocPhysicalMemory() must be eventually freed using DMAFreePhysicalMemory().

<syntaxhighlight>
void DMAFreePhysicalMemory( APTR pPhysicalMemoryBlock );
</syntaxhighlight>

==== Copy Memory Functions ====

Two API calls make up the core of the FslDMA API; DMAPhysicalCopyMem() and DMACopyMem().
Both of these calls will "block" (not return to the user) until after the requested transfer has either succeeded or failed.

<syntaxhighlight>
BOOL DMAPhysicalCopyMem( CONST_APTR pPhysicalSourceBuffer, APTR pPhysicalDestBuffer, uint32 lBufferSize );
BOOL DMACopyMem( CONST_APTR pSourceBuffer, APTR pDestBuffer, uint32 lBufferSize );
</syntaxhighlight>

As the name implies the first (and core version) of the copy memory functions, DMAPhysicalCopyMem(), accepts the Physical Addresses to the source and destination buffers (as returned by DMAAllocPhysicalMemory()), along with an unsigned 32-Bit value for the amount of bytes that should be copied (lBuffsize must be greater than zero(0) and no more than the maximum size of the source and destination buffers).

DMAPhysicalCopyMem() is the most direct an efficient means of using the DMA hardware to effect a single memory copy. The DMACopyMem() function is provided as an alternative way to request a DMA transfer by passing in the ''Virtual Addresses'' to the source and destination buffers instead of the Physical Addresses. DMACopyMem() will attempt to determine if the supplied memory buffers are DMA Compliant and if so it will internally use DMAPhysicalCopyMem() to handle the transaction. If DMACopyMem() determines that the supplied memory is '''not''' DMA Compliant it will return FALSE and no data copy will occur.

In theory any ''contiguous'' block of memory from 1 Byte up to 4GB in size may be transferred using either one of these calls. In practice the DMA hardware can directly accept memory blocks up to FSLDMA_MAXBLOCK_SIZE (or 64MB - 1 Byte). Therefore any data blocks greater than FSLDMA_MAXBLOCK_SIZE will automatically be feed to the DMA hardware in a series of smaller chunks. For maximum efficiency transfer sizes should be at least 256 Bytes in size and be an even multiple of 64 Bytes. Odd sizes are handled by the hardware but will degrade performance.

If you are transferring many large blocks of data in series and wish to manually send them to the FslDMA API's memory copy functions one block at a time, then setting your block sizes to FSLDMA_OPTIMAL_BLKSIZE (or 64 MB - 64 Bytes) and exclusively using DMAPhysicalCopyMem() will provide the fastest transfer speeds will the least amount of CPU overhead.

==== Utility / Miscellaneous Functions ====

The last section to the FslDMA API provides a single convenience function call; DMAGetVirtualAddress().

<syntaxhilight>
APTR DMAGetVirtualAddress( APTR pPhysicalAddress );
</syntaxhilight>

The DMAGetVirtualAddress() function returns the Virtual memory location for the Physical memory location that was itself allocated and returned by the DMAAllocPhysicalMemory() function. DMAGetVirtualAddress() will not work on physical addresses returned by IMMU->GetPhysicalAddress() on memory not allocated using DMAAllocPhysicalMemory().

The main purpose of this function (other then debugging purposes) is to provide the "normal" Virtual Address of memory allocated by the FslDMA API for use by functions that expect "normal" Virtual address locations; for example IExec->CopyMemQuick().

=== Example usage ===
<syntaxhighlight>
#include <interfaces/fsldma.h>
// Obtain the fsldma.resource
struct fslDMAIFace *IfslDMA = IExec->OpenResource(FSLDMA_NAME);
if ( NULL != IfslDMA )
{
uint32 lTestSize = 1024;
CONST_APTR pPhysicalSrcAddr = NULL;
APTR pPhysicalDestAddr = NULL;
// Allocate the Source Buffer (for DMA)
// and set the contents to 0xB3 (just an example value)
pPhysicalSrcAddr = (CONST_APTR)IfslDMA->DMAAllocPhysicalMemoryTags(lTestSize,
FSLDMA_APM_ClearWithValue, 0xB3,
TAG_END);
if ( NULL != pPhysicalSrcAddr )
{
// Allocate the Destination Buffer (for DMA)
// - contents will by cleared by default
pPhysicalDestAddr = IfslDMA->DMAAllocPhysicalMemory(lTestSize);
if ( NULL != pPhysicalDestAddr )
{
// Call IfslDMA->DMAPhysicalCopyMem()
// to perform the memory copy using the DMA hardware
if ( TRUE == IfslDMA->DMAPhysicalCopyMem(pPhysicalSrcAddr,
pPhysicalDestAddr,lTestSize) )
{
// Success - Do something with the copied data
}
else
{
// Fallback and use CPU Copy instead (or do something else)
// Since we allocated the memory buffers using the FslDMA API,
// which returns the Physical address to that memory, and the
// IExec->CopyMemQuick() function expects the Virtual address,
// we first need to obtain the Virtual address for the Physical
// ones (using the FslDMA API again) before we can call our
// fallback copy function.
CONST_APTR pVirtualSrcAddr = NULL;
APTR pVirtualDestAddr = NULL;
pVirtualSrcAddr = IfslDMA->DMAGetVirtualAddress((APTR)pPhysicalSrcAddr);
pVirtualDestAddr = IfslDMA->DMAGetVirtualAddress(pPhysicalDestAddr);
IExec->CopyMemQuick(pVirtualSrcAddr,pVirtualDestAddr,lTestSize);
}
// We *must* use DMAFreePhysicalMemory() to free the memory
// that we allocated with DMAAllocPhysicalMemory()
IfslDMA->DMAFreePhysicalMemory(pPhysicalDestAddr);
}
// We *must* use DMAFreePhysicalMemory() to free the memory
// that we allocated with DMAAllocPhysicalMemory()
IfslDMA->DMAFreePhysicalMemory((APTR)pPhysicalSrcAddr);
}
}
</syntaxhighlight>

==== Obtaining the fsldma.resource ====

Breaking this example down the first thing we do is include the interface header for the fsldma.resource and obtain the resource itself.

<syntaxhighlight>
#include <interfaces/fsldma.h>
struct fslDMAIFace *IfslDMA = IExec->OpenResource(FSLDMA_NAME);
</syntaxhighlight>

==== Allocating DMA Compliant Memory ====

Once we have successfully obtained the DMA resource we can directly use its API. The next step we need to do is to allocate some memory '''which we know is DMA compliant''' for use by the resource. The easiest way to accomplish this is to use the IfslDMA->DMAAllocPhysicalMemory() function. This will automatically take care of ensuring the memory that is returned is properly aligned, contiguous, cache-inhibited and coherent.

We use the Tags version of the allocate memory function first so we can allocate a block of memory for our source buffer and fill it with some test value (in this case the byte value 0xB3).

<syntaxhighlight>
pPhysicalSrcAddr = (CONST_APTR)IfslDMA->DMAAllocPhysicalMemoryTags(lTestSize,
FSLDMA_APM_ClearWithValue, 0xB3,
TAG_END);
</syntaxhighlight>

We also need a destination buffer for our test. Since it only needs to start out being cleared (filled with zeroes), we can use the simplest form of the allocate memory function here as the allocated memory is cleared by default.

<syntaxhighlight>
pPhysicalDestAddr = IfslDMA->DMAAllocPhysicalMemory(lTestSize);
</syntaxhighlight>

==== The core function - Copy Physical Memory ====

Now that we have two DMA Compliant memory buffers available we can get to the heart of the API usage and make the call to IfslDMA->DMAPhysicalCopyMem().

<syntaxhighlight>
IfslDMA->DMAPhysicalCopyMem(pPhysicalSrcAddr,pPhysicalDestAddr,lTestSize);
</syntaxhighlight>

Looking at the full [[#Example usage|Example]] source above you can see that the DMAPhysicalCopyMem() call returns a Boolean value to indicate success or failure. Therefore, TRUE will be returned after the DMA hardware had completed copying the requested data (blocking call) and FALSE will be returned if a problem occurred.

Since the memory buffers we are using were allocated using the FslDMA API and our transfer size was greater than zero and less than or equal to the total size of either buffer, (in others words a legal copy request), there is '''very''' little chance that the DMAPhysicalCopyMem() function will fail. In fact, about the only reason the DMA hardware would fail to handle a legal transaction would be if the physical RAM installed in the system was faulty.

So even though it is extremely unlikely for our DMA copy to have failed and returned FALSE, let's take a look at how we might handle the failure. In other words, falling back and using a CPU based copy function instead to complete the data move.

Since we are reverting back to using a normal system copy memory function here, we first need to obtain the ''Virtual Addresses'' to both our source and destination buffers. This is accomplished by using the DMAGetVirtualAddress() function and passing in the Physical Address that was returned by DMAAllocPhysicalMemory().

<syntaxhighlight>
CONST_APTR pVirtualSrcAddr = NULL;
APTR pVirtualDestAddr = NULL;
pVirtualSrcAddr = IfslDMA->DMAGetVirtualAddress((APTR)pPhysicalSrcAddr);
pVirtualDestAddr = IfslDMA->DMAGetVirtualAddress(pPhysicalDestAddr);
</syntaxhighlight>

Now that we have the Virtual Address equivalents to the Physical Addresses that were returned by DMAAllocPhysicalMemory(), we can proceed to call the Exec CopyMemQuick() function to complete the copy. Here we can only trust that the IExec->CopyMemQuick() call can not fail since it does not return a result code.

<syntaxhighlight>
IExec->CopyMemQuick(pVirtualSrcAddr,pVirtualDestAddr,lTestSize);
</syntaxhighlight>

==== Cleaning up - Freeing DMA Compliant memory ====

It is essential that you free any memory that was allocated using the DMAAllocPhysicalMemory() function using the corresponding DMAFreePhysicalMemory() call. The reason for this is two-fold; first because additional resource tracking is maintained by the FslDMA API whenever it allocates memory which must itself be released, and second because the ''Physical Address'' to the memory is returned by the allocate call and not the ''Virtual Address'', so if you attempt to pass the address returned by DMAAllocPhysicalMemory() directly into IExec->FreeVec() it would likely result in a crash.

<syntaxhighlight>
IfslDMA->DMAFreePhysicalMemory(pPhysicalSrcAddr);
IfslDMA->DMAFreePhysicalMemory(pPhysicalDestAddr);
</syntaxhighlight>

DMA Resource

2019-11-13T01:28:28Z

Jamie Krueger: /* Copy Memory Functions */

DMA Resource

2019-11-13T01:26:40Z

Jamie Krueger: /* Copy Memory Functions */

DMA Resource

2019-11-13T01:24:29Z

Jamie Krueger: /* Copy Memory Functions */

DMA Resource

2019-11-13T01:23:12Z

Jamie Krueger: /* Copy Memory Functions */

DMA Resource

2019-11-13T00:54:57Z

Jamie Krueger: