ACPY3 (C64P)

Data Structures

struct  ACPY3_Params
 DMA transfer specific parameters. Defines the configuration of a logical channel. More...

Defines

#define ACPY3_GTNAME   "ti.sdo.fc.acpy3"

Enumerations

enum  ACPY3_ParamField16b {
  ACPY3_PARAMFIELD_ELEMENTSIZE = 8,
  ACPY3_PARAMFIELD_NUMELEMENTS = 10,
  ACPY3_PARAMFIELD_ELEMENTINDEX_SRC = 16,
  ACPY3_PARAMFIELD_ELEMENTINDEX_DST = 18,
  ACPY3_PARAMFIELD_FRAMEINDEX_SRC = 24,
  ACPY3_PARAMFIELD_FRAMEINDEX_DST = 26,
  ACPY3_PARAMFIELD_NUMFRAMES = 28
}
 

ACPY3 16-bit param field structure. These values are passed to ACPY3_fastConfigure16b() to indicate the field of the ACPY3_Params structure to be changed.

More...
enum  ACPY3_ParamField32b {
  ACPY3_PARAMFIELD_SRCADDR = 4,
  ACPY3_PARAMFIELD_DSTADDR = 12,
  ACPY3_PARAMFIELD_ELEMENTINDEXES = 16,
  ACPY3_PARAMFIELD_FRAMEINDEXES = 24
}
 

ACPY3 32-bit param field structure. These values are passed to ACPY3_fastConfigure32b() to indicate the field of the ACPY3_Params structure to be changed.

More...
enum  ACPY3_TransferType {
  ACPY3_1D1D,
  ACPY3_1D2D,
  ACPY3_2D1D,
  ACPY3_2D2D
}
 

ACPY3 DMA Transfer Types:.

More...

Functions

Void ACPY3_configure (IDMA3_Handle handle, ACPY3_Params *params, short transferNo)
 Functions called by the framework for allocating and initializing the channel state.
Void ACPY3_fastConfigure16b (IDMA3_Handle handle, ACPY3_ParamField16b fieldId, unsigned short value, short transferNo)
 Modify the 16-bit DMA transfer parameter, indicated by the parameter field id, fieldId, of the current channel settings.
Void ACPY3_fastConfigure32b (IDMA3_Handle handle, ACPY3_ParamField32b fieldId, Uns value, short transferNo)
 Modify the 32-bit DMA transfer parameter, indicated by the parameter field id, fieldId, of the current channel settings.
Void ACPY3_setFinal (IDMA3_Handle handle, short transferNo)
 Indicate that a given transfer will be the last in a sequence of linked transfers.
Void ACPY3_fastSetFinal (IDMA3_Handle handle, short transferNo)
 Indicate that a given transfer will be the last in a sequence of linked transfers.
Void ACPY3_start (IDMA3_Handle handle)
 Submit a single or linked transfer using the most recently configured transfer parameter settings.
Void ACPY3_wait (IDMA3_Handle handle)
 Wait for all data transfers on a logical channel to complete.
Void ACPY3_waitLinked (IDMA3_Handle handle, unsigned short waitId)
 Wait for an individual transfer in a Linked transfer to finish.
Bool ACPY3_complete (IDMA3_Handle handle)
 Check to see if all dma transfers on logical channel are finished.
Bool ACPY3_completeLinked (IDMA3_Handle handle, unsigned short waitId)
 Non-blocking query to check completion of an individual transfer in a Linked transfer.
Void ACPY3_activate (IDMA3_Handle handle)
 Activate the given channel.
Void ACPY3_deactivate (IDMA3_Handle handle)
 Deactivates the given channel.
Void ACPY3_init (Void)
 Initialize the ACPY3 module. Called by framework.
Void ACPY3_exit (Void)
 Finalization of the ACPY3 module.

Variables

IDMA3_ProtocolObj ACPY3_PROTOCOL



enum  ACPY3_INSTR_HookType {
  ACPY3_INSTR_START_ENTER = 0,
  ACPY3_INSTR_START_EXIT,
  ACPY3_INSTR_WAIT_ENTER,
  ACPY3_INSTR_WAIT_EXIT
}
 

Primary instrumentation hook function names.

More...
enum  ACPY3_INSTR_ExtendedHookType {
  ACPY3_INSTR_WAITLINKED_ENTER,
  ACPY3_INSTR_WAITLINKED_EXIT,
  ACPY3_INSTR_ACTIVATE_ENTER,
  ACPY3_INSTR_ACTIVATE_EXIT,
  ACPY3_INSTR_DEACTIVATE_ENTER,
  ACPY3_INSTR_DEACTIVATE_EXIT,
  ACPY3_INSTR_COMPLETE_ENTER,
  ACPY3_INSTR_COMPLETE_EXIT,
  ACPY3_INSTR_COMPLETELINKED_ENTER,
  ACPY3_INSTR_COMPLETELINKED_EXIT,
  ACPY3_INSTR_CONFIGURE_ENTER,
  ACPY3_INSTR_CONFIGURE_EXIT,
  ACPY3_INSTR_FASTCONFIGURE16_ENTER,
  ACPY3_INSTR_FASTCONFIGURE16_EXIT,
  ACPY3_INSTR_FASTCONFIGURE32_ENTER,
  ACPY3_INSTR_FASTCONFIGURE32_EXIT,
  ACPY3_INSTR_SETFINAL_ENTER,
  ACPY3_INSTR_SETFINAL_EXIT,
  ACPY3_INSTR_SETFASTFINAL_ENTER,
  ACPY3_INSTR_SETFASTFINAL_EXIT,
  ACPY3_INSTR_INIT_ENTER,
  ACPY3_INSTR_INIT_EXIT,
  ACPY3_INSTR_EXIT_ENTER,
  ACPY3_INSTR_EXIT_EXIT
}
 

Extended instrumentation hook function names.

More...
Void ACPY3_INSTR_registerHooks (IDMA3_Handle handle, ACPY3_INSTR_Hooks *hooks, ACPY3_INSTR_ExtendedHooks *extended_hooks)
 Registering the hook functions for instrumentation.
Void ACPY3_INSTR_unregisterHooks (IDMA3_Handle handle)
 Un-registering the hook functions for instrumentation.
#define ACPY3_INSTR_NUMHOOKS   4
 Number of primary instrumentation hook functions.
#define ACPY3_INSTR_NUMEXTENDEDHOOKS   22
typedef void(* ACPY3_INSTR_HookFxn )(IDMA3_Handle handle, void *param)
 Function signature for hook instrumentation function.

Detailed Description

The ACPY3 module provides a comprehensive list of DMA operations an algorithm can perform on logical DMA channels it acquires through the IDMA3 protocol. Example of ACPY3 operations include channel configuration, DMA transfer scheduling, and DMA transfer synchronization.

Remarks:
For additional information, please refer to the "Using DMA with Framework Components for 'C64x+" document.

Define Documentation

#define ACPY3_GTNAME   "ti.sdo.fc.acpy3"
#define ACPY3_INSTR_NUMHOOKS   4

Number of primary instrumentation hook functions.

#define ACPY3_INSTR_NUMEXTENDEDHOOKS   22

Typedef Documentation

typedef void(* ACPY3_INSTR_HookFxn)(IDMA3_Handle handle, void *param)

Function signature for hook instrumentation function.

Enumeration Type Documentation

enum ACPY3_ParamField16b

ACPY3 16-bit param field structure. These values are passed to ACPY3_fastConfigure16b() to indicate the field of the ACPY3_Params structure to be changed.

Enumerator:
ACPY3_PARAMFIELD_ELEMENTSIZE 
ACPY3_PARAMFIELD_NUMELEMENTS 
ACPY3_PARAMFIELD_ELEMENTINDEX_SRC 
ACPY3_PARAMFIELD_ELEMENTINDEX_DST 
ACPY3_PARAMFIELD_FRAMEINDEX_SRC 
ACPY3_PARAMFIELD_FRAMEINDEX_DST 
ACPY3_PARAMFIELD_NUMFRAMES 
enum ACPY3_ParamField32b

ACPY3 32-bit param field structure. These values are passed to ACPY3_fastConfigure32b() to indicate the field of the ACPY3_Params structure to be changed.

Enumerator:
ACPY3_PARAMFIELD_SRCADDR 
ACPY3_PARAMFIELD_DSTADDR 
ACPY3_PARAMFIELD_ELEMENTINDEXES 
ACPY3_PARAMFIELD_FRAMEINDEXES 
enum ACPY3_TransferType

ACPY3 DMA Transfer Types:.

Note that all transfers can be specified using the ACPY3_2D2D transfer type, and providing element and frame indices for both source and destination. However, the other transfer types are provided to simplify configuration when applicable. For example, when using the ACPY3_1D2D transfer type, you do not need to set the source element and frame indices in the ACPY3_Params structure.

Enumerator:
ACPY3_1D1D 

Only one element is copied from source to destination. The size of the element is specified in the elementSize field of ACPY3_Params

ACPY3_1D2D 

After each element is copied to destination, the source and destination of the next element to copy is updated as follows:

  • src = src + element size
  • dst = dst + destination element index

After an entire frame is copied (the frame size specified by the numElements field of ACPY3_Params), the source and destination of the next frame to copy are given by:

  • src = src + element size
  • dst = start of frame + destination frame index
ACPY3_2D1D 

This is similar to ACPY3_1D2D, except that source and destination are updated after an element is copied, as follows:

  • src = src + source element index
  • dst = dst + element size

After an entire frame is copied by:

  • src = start of frame + source frame index
  • dst = dst + element size
ACPY3_2D2D 

This transfer type combines ACPY3_1D2D and ACPY3_2D1D, so that source and destination are updated after an element is copied by:

  • src = src + source element index
  • dst = dst + destination element index

After a frame is copied by:

  • src = start of frame + source frame index
  • dst = start of frame + destination frame index
enum ACPY3_INSTR_HookType

Primary instrumentation hook function names.

Enumerator:
ACPY3_INSTR_START_ENTER 
ACPY3_INSTR_START_EXIT 
ACPY3_INSTR_WAIT_ENTER 
ACPY3_INSTR_WAIT_EXIT 
enum ACPY3_INSTR_ExtendedHookType

Extended instrumentation hook function names.

Enumerator:
ACPY3_INSTR_WAITLINKED_ENTER 
ACPY3_INSTR_WAITLINKED_EXIT 
ACPY3_INSTR_ACTIVATE_ENTER 
ACPY3_INSTR_ACTIVATE_EXIT 
ACPY3_INSTR_DEACTIVATE_ENTER 
ACPY3_INSTR_DEACTIVATE_EXIT 
ACPY3_INSTR_COMPLETE_ENTER 
ACPY3_INSTR_COMPLETE_EXIT 
ACPY3_INSTR_COMPLETELINKED_ENTER 
ACPY3_INSTR_COMPLETELINKED_EXIT 
ACPY3_INSTR_CONFIGURE_ENTER 
ACPY3_INSTR_CONFIGURE_EXIT 
ACPY3_INSTR_FASTCONFIGURE16_ENTER 
ACPY3_INSTR_FASTCONFIGURE16_EXIT 
ACPY3_INSTR_FASTCONFIGURE32_ENTER 
ACPY3_INSTR_FASTCONFIGURE32_EXIT 
ACPY3_INSTR_SETFINAL_ENTER 
ACPY3_INSTR_SETFINAL_EXIT 
ACPY3_INSTR_SETFASTFINAL_ENTER 
ACPY3_INSTR_SETFASTFINAL_EXIT 
ACPY3_INSTR_INIT_ENTER 
ACPY3_INSTR_INIT_EXIT 
ACPY3_INSTR_EXIT_ENTER 
ACPY3_INSTR_EXIT_EXIT 

Function Documentation

Void ACPY3_configure ( IDMA3_Handle  handle,
ACPY3_Params *  params,
short  transferNo 
)

Functions called by the framework for allocating and initializing the channel state.

Configure all DMA transfer settings for the logical channel.

Parameters:
[in] handle IDMA3 channel handle.
[in] params DMA transfer specific parameters used to configure this logical DMA channel.
[in] transferNo Indicates the individual transfer to be configured using the passed 'params'
Precondition:
channel must be in active state
params->waitId != (numWaits - 1), unless configuring the last transfer.
valid IDMA_Obj handle
handle->protocol == &ACPY3_PROTOCOL
0 <= transferNo < originally requested number of transfers
Void ACPY3_fastConfigure16b ( IDMA3_Handle  handle,
ACPY3_ParamField16b  fieldId,
unsigned short  value,
short  transferNo 
)

Modify the 16-bit DMA transfer parameter, indicated by the parameter field id, fieldId, of the current channel settings.

Parameters:
[in] handle IDMA3 channel handle.
[in] fieldId Indicates which of the parameters is to be modified.
[in] value New value of the parameter to be modified.
[in] transferNo Indicates which transfer the parameters correspond to (same value that would be passed to ACPY3_configure()). logical DMA handle and environment (env, envSize) fields.
Precondition:
Algorithm instance must be in "active" state using IALG interface.
Channel must be in "active" state.
Remarks:
Once a channel has been configured once with ACPY3_configure(), ACPY3_fastConfigure16b() can be used to update any of the 16-bit parameter fields, for example, the number of elements in a frame to be transferred.
Both an inlined version and a non-inlined version of this function are supported. To use the inlined version, add the line #define ACPY3_FASTCONFIGURE16B_INLINE or #define ACPY3_INLINE_ALL to the source file where this function is used. The #define must go above the line, #include <acpy3.h>. By default, this function will not be inlined. Another alternative is to define the macro in the build option of the file or of the project file.
  • When _ACPY3_DIRTY_BITS is 0, this function requires 8 ticks.
  • When _ACPY3_DIRTY_BITS is 1, this function requires 14 ticks.
Void ACPY3_fastConfigure32b ( IDMA3_Handle  handle,
ACPY3_ParamField32b  fieldId,
Uns  value,
short  transferNo 
)

Modify the 32-bit DMA transfer parameter, indicated by the parameter field id, fieldId, of the current channel settings.

Parameters:
[in] handle IDMA3 channel handle.
[in] fieldId Indicates which of the parameters is to be modified.
[in] value New value of the parameter to be modified.
[in] transferNo Indicates which transfer the parameters correspond to (same value that would be passed to ACPY3_configure()). logical DMA handle and environment (env, envSize) fields.
Precondition:
handle must be a valid channel handle.
Algorithm instance must be in "active" state using IALG interface.
Channel must be in 'active' state.
Remarks:
Once a channel has been configured once with ACPY3_configure(), ACPY3_fastConfigure32b() can be used to update any of the 32-bit parameter fields, for example, the source address of the data to be transferred.
Both an inlined version and a non-inlined version of this function are supported. To use the inlined version, add the line #define ACPY3_FASTCONFIGURE32B_INLINE or #define ACPY3_INLINE_ALL to the source file where this function is used. The #define must go above the line, #include <acpy3.h>. By default, this function will not be inlined. Another alternative is to define the macro in the build option of the file or of the project file.
  • When _ACPY3_DIRTY_BITS is 0, this function requires 8 ticks.
  • When _ACPY3_DIRTY_BITS is 1, this function requires 14 ticks.
Void ACPY3_setFinal ( IDMA3_Handle  handle,
short  transferNo 
)

Indicate that a given transfer will be the last in a sequence of linked transfers.

This API can be used to dynamically change the number of transfers in a linked transfers. Any waitId previously associated with given transfer "transferNo" will be replaced with the waitId 'numWaits - 1' since ACPY3_wait() uses this waitId to check for transfer completion.

Parameters:
[in] handle IDMA3 channel handle.
[in] transferNo Indicates which transfer that will be the last in the set of linked transfers. (This is the same value that was passed to ACPY3_configure()).
Remarks:
This API can be used if a channel was created to transfer numTransfers linked transfers, but at some point, it may be that fewer transfers than numTransfers should be started.
Both an inlined version and a non-inlined version of this function are supported. To use the inlined version, add the line #define ACPY3_SETFINAL_INLINE or #define ACPY3_INLINE_ALL to the source file where this function is used. The #define must go above the line, #include <acpy3.h>. By default, this function will not be inlined. Another alternative is to define the macro in the build option of the file or of the project file.
  • When _ACPY3_DIRTY_BITS is 0, this routine requires 66 ticks.
  • When _ACPY3_DIRTY_BITS is 1, this routine requires 66 ticks.
Precondition:
Valid channel handle.
Channel must be in 'active' state.
Postcondition:
transferNo's waitId is set to 'numWaits - 1'
Any previously associated waitId with the old "final" transfer is cleared. As a consequence applications may need to call ACPY3_configure() to restore the appropriate waitId.
Void ACPY3_fastSetFinal ( IDMA3_Handle  handle,
short  transferNo 
)

Indicate that a given transfer will be the last in a sequence of linked transfers.

This API can be used to dynamically change the number of transfers in a linked transfers. Any waitId previously This function is only usable when the handle only has a single waitId. Otherwise is works exactly the same as ACPY3_setFinal. It just runs much faster.

Parameters:
[in] handle IDMA3 channel handle.
[in] transferNo Indicates which transfer that will be the last in the set of linked transfers. (This is the same value that was passed to ACPY3_configure()).
Remarks:
This API can be used if a channel was created to transfer numTransfers linked transfers, but at some point, it may be that fewer transfers than numTransfers should be started.
Both an inlined version and a non-inlined version of this function are supported. To use the inlined version, add the line #define ACPY3_FASTSETFINAL_INLINE or #define ACPY3_INLINE_ALL to the source file where this function is used. The #define must go above the line, #include <acpy3.h>. By default, this function will not be inlined. Another alternative is to define the macro in the build option of the file or of the project file.
ACPY3_fastSetFinal() does the work of ACPY3_setFinal() but assumes that there is only 1 TCC allocated to the handle. It is very much optimized compared to ACPY3_setFinal().
  • When _ACPY3_DIRTY_BITS is 0, this routine requires 15 ticks.
  • When _ACPY3_DIRTY_BITS is 1, this routine requires 21 ticks.
Precondition:
Valid channel handle.
Channel must be in 'active' state.
Postcondition:
transferNo's waitId is set to 'numWaits - 1'
Void ACPY3_start ( IDMA3_Handle  handle  ) 

Submit a single or linked transfer using the most recently configured transfer parameter settings.

Parameters:
[in] handle IDMA3 channel handle.
Precondition:
Valid channel handle.
Channel must be in 'active' state.
Channel must be in 'configured' state.
Postcondition:
handle->transferPending = TRUE
Remarks:
Both an inlined version and a non-inlined version of this function are supported. To use the inlined version, add the line #define ACPY3_START_INLINE or #define ACPY3_INLINE_ALL to the source file where this function is used. The #define must go above the line, #include <acpy3.h>. By default, this function will not be inlined. Another alternative is to define the macro in the build option of the file or of the project file.
ACPY3_start() requires the following number of ticks:

Number of Linked Transfers

ACPY3_DIRTY_BITS=0

ACPY3_DIRTY_BITS=1

1, 2, or 3

89

101

4, 8, 12, or 16

92

110

all other numbers

149

167

Void ACPY3_wait ( IDMA3_Handle  handle  ) 

Wait for all data transfers on a logical channel to complete.

ACPY3_wait() uses waitId 'numWaits - 1' to wait for the completion of all transfers. Therefore, this waitId should not be used to configure any intermediate transfers.

Parameters:
[in] handle IDMA3 channel handle.
Precondition:
Valid channel handle
Channel must be in 'active' state.
Postcondition:
handle->transferPending = FALSE
Remarks:
This function will not return until all the data transfers on the given channel have completed.
Both an inlined version and a non-inlined version of this function are supported. To use the inlined version, add the line #define ACPY3_WAIT_INLINE or #define ACPY3_INLINE_ALL to the source file where this function is used. The #define must go above the line, #include <acpy3.h>. By default, this function will not be inlined. Another alternative is to define the macro in the build option of the file or of the project file.
Void ACPY3_waitLinked ( IDMA3_Handle  handle,
unsigned short  waitId 
)

Wait for an individual transfer in a Linked transfer to finish.

Parameters:
[in] handle IDMA3 channel handle.
[in] waitId The waitId for the transfer to wait on, that was passed in the ACPY3_Params to ACPY3_configure().
Precondition:
Valid channel handle
Channel must be in 'active' state.
0 <= waitId < originally requested number of waitId
Channel contains one transfer T, i-th transfer, such that i < handle->numPaRams and T configured with given waitId.
Remarks:
This function will not return until the data transfer that was configured with 'waitId' has completed.
Bool ACPY3_complete ( IDMA3_Handle  handle  ) 

Check to see if all dma transfers on logical channel are finished.

Parameters:
[in] handle IDMA3 channel handle.
Return values:
TRUE No transfers are pending (i.e., ACPY3_wait() has been called since last ACPY3_start()), or all transfers on this channel have completed.
FALSE One or more transfers on this channel have not completed.
Precondition:
Valid channel handle
Channel must be in 'active' state.
Remarks:
This function will not wait for data transfers to complete, but will return immediately with completion status.
There is no need to call ACPY3_wait() once ACPY3_complete() returns TRUE.
Both an inlined version and a non-inlined version of this function are supported. To use the inlined version, add the line #define ACPY3_COMPLETE_INLINE or #define ACPY3_INLINE_ALL to the source file where this function is used. The #define must go above the line, #include <acpy3.h>. By default, this function will not be inlined. Another alternative is to define the macro in the build option of the file or of the project file.
Bool ACPY3_completeLinked ( IDMA3_Handle  handle,
unsigned short  waitId 
)

Non-blocking query to check completion of an individual transfer in a Linked transfer.

Parameters:
[in] handle IDMA3 channel handle.
[in] waitId The waitId for the transfer to check for completion, that was passed in the ACPY3_Params to ACPY3_configure().
Return values:
TRUE No transfers are pending (i.e., ACPY3_wait() has been called since last ACPY3_start()), or the individual transfer that was configured with waitId has completed.
FALSE The transfer configured with waitId has not completed.
Precondition:
Valid channel handle.
waitId < handle->numTccs
Channel must be in 'active' state.
Remarks:
This function will not wait for the data transfer to complete, but will return immediately with completion status.
There is no need to call ACPY3_waitLinked() once ACPY3_completeLinked() returns TRUE.
Void ACPY3_activate ( IDMA3_Handle  handle  ) 

Activate the given channel.

Parameters:
[in] handle IDMA3 channel handle.
Precondition:
handle must be a valid channel handle.
Algorithm instance must be in "active" state using IALG interface.
Postcondition:
Channel is in 'active' state, any ACPY3 APIs can be called using this handle.
handle->transferPending == FALSE
Void ACPY3_deactivate ( IDMA3_Handle  handle  ) 

Deactivates the given channel.

Parameters:
[in] handle IDMA3 channel handle.
Precondition:
handle must be a valid channel handle.
Channel must be in 'active' state.
Algorithm instance must be in 'active' state using IALG interface
Postcondition:
Channel is in 'deactivated' state.
Void ACPY3_init ( Void   ) 

Initialize the ACPY3 module. Called by framework.

Void ACPY3_exit ( Void   ) 

Finalization of the ACPY3 module.

Void ACPY3_INSTR_registerHooks ( IDMA3_Handle  handle,
ACPY3_INSTR_Hooks *  hooks,
ACPY3_INSTR_ExtendedHooks *  extended_hooks 
)

Registering the hook functions for instrumentation.

Parameters:
[in] handle IDMA3 channel handle.
[in] hooks Primary instrumentation hook functions array
[in] extended_hooks Extended instrumentation hook functions array
Void ACPY3_INSTR_unregisterHooks ( IDMA3_Handle  handle  ) 

Un-registering the hook functions for instrumentation.

Parameters:
[in] handle IDMA3 channel handle.

Variable Documentation

IDMA3_ProtocolObj ACPY3_PROTOCOL
Copyright 2010, Texas Instruments Incorporated