Defines the fields and methods that must be supplied by all XDAIS algorithms.
More...
#include <ialg.h>
Data Fields |
Void * | implementationId |
| Unique pointer that identifies the module implementing this interface.
|
Void(* | algActivate )(IALG_Handle handle) |
| Notification to the algorithm that its memory is "active" and algorithm processing methods may be called.
|
Int(* | algAlloc )(const IALG_Params *params, struct IALG_Fxns **parentFxns, IALG_MemRec *memTab) |
| Apps call this to query the algorithm about its memory requirements. Must be non-NULL.
|
Int(* | algControl )(IALG_Handle handle, IALG_Cmd cmd, IALG_Status *status) |
| Algorithm specific control and status.
|
Void(* | algDeactivate )(IALG_Handle handle) |
| Save all persistent data to non-scratch memory.
|
Int(* | algFree )(IALG_Handle handle, IALG_MemRec *memTab) |
| Apps call this to allow the algorithm to initialize memory requested via algAlloc(). Must be non-NULL.
|
Int(* | algInit )(IALG_Handle handle, const IALG_MemRec *memTab, IALG_Handle parent, const IALG_Params *params) |
| Initialize an algorithm's instance object. Must be non-NULL.
|
Void(* | algMoved )(IALG_Handle handle, const IALG_MemRec *memTab, IALG_Handle parent, const IALG_Params *params) |
| Notify algorithm instance that instance memory has been relocated.
|
Int(* | algNumAlloc )(Void) |
| Number of memory allocation requests required.
|
Detailed Description
Defines the fields and methods that must be supplied by all XDAIS algorithms.
Field Documentation
Unique pointer that identifies the module implementing this interface.
Notification to the algorithm that its memory is "active" and algorithm processing methods may be called.
- Parameters:
-
[in] | handle | Handle to an algorithm instance. |
- Precondition:
- algActivate() can only be called after a successful return from algInit().
-
handle
must be a valid handle for the algorithm's instance object.
-
No other algorithm method is currently being run on this instance. This method never preempts any other method on the same instance.
-
If the algorithm has implemented the IDMA2 interface, algActivate() can only be called after a successful return from dmaInit().
- Postcondition:
- All methods related to the algorithm may now be executed by client (subject to algorithm specific restrictions).
- See also:
- algDeactivate().
Apps call this to query the algorithm about its memory requirements. Must be non-NULL.
- Parameters:
-
[in] | params | Algorithm specific attributes. |
[out] | parentFxns | Parent algorithm functions. |
[out] | memTab | array of memory records. |
- Precondition:
- The number of memory records in the array
memTab
[] is no less than the number returned by algNumAlloc().
-
*parentFxns
is a valid pointer to an IALG_Fxns pointer variable.
- Postcondition:
- If the algorithm needs a parent object to be created, the pointer
*parentFxns
is set to a non-NULL value that points to a valid IALG_Fxns structure, the parent's IALG implementation. Otherwise, this pointer is not set. algAlloc() may elect to ignore the parentFxns
pointer altogether.
-
For each memory descriptor in memTab with an IALG_WRITEONCE attribute, the algorithm has either set the base field to a non-NULL value, which is the address of a statically allocated and initialized memory buffer of the indicated 'size', or has set the base field to
NULL
, thereby requiring the memory for the buffer to be provided by the client.
-
Exactly
n
elements of the memTab
[] array are initialized, where n
is the return value from this operation.
-
For each memory descriptor in
memTab
with an IALG_PERSIST or IALG_SCRATCH attribute, the algorithm does not set its base field.
-
memTab
[0] defines the memory required for the instance's object and this object's first field is an IALG_Obj structure.
-
memTab
[0] is requested as persistent memory.
- See also:
- algFree()
Algorithm specific control and status.
- Parameters:
-
[in] | handle | Algorithm instance handle. |
[in] | cmd | Algorithm specific command. |
[out] | status | Algorithm specific status. |
- Precondition:
- algControl() can only be called after a successful return from algInit().
-
handle
must be a valid handle for the algorithm's instance object.
-
Algorithm specific
cmd
values are always less than IALG_SYSCMD.
- Postcondition:
- If the
cmd
value is not recognized by the algorithm, the return value is not equal to IALG_EOK.
- See also:
- algInit()
Save all persistent data to non-scratch memory.
- Parameters:
-
[in] | handle | Algorithm instance handle. |
- Precondition:
- algDeactivate() can only be called after a successful return from algInit().
-
The instance object is currently "active"; i.e., all instance memory is active and if an algActivate() method is defined, it has been called.
-
handle
must be a valid handle for the algorithm's instance object.
-
No other algorithm method is currently being run on this instance. This method never preempts any other method on the same instance.
- Postcondition:
- No methods related to the algorithm may now be executed by the client; only algActivate() or algFree() may be called.
-
All instance scratch memory may be safely overwritten.
- See also:
- algActivate()
Apps call this to allow the algorithm to initialize memory requested via algAlloc(). Must be non-NULL.
- Parameters:
-
[in] | handle | Algorithm instance handle. |
[out] | memTab | Output array of memory records. |
- Precondition:
- The
memTab
[] array contains at least algNumAlloc() records.
-
handle
must be a valid handle for the algorithm's instance object.
-
If the prior call to algAlloc() returned a non-NULL parent functions pointer, then the parent instance must be an active instance object created via that function pointer.
-
No other agorithm method is currently being run on this instance. This method never preempts any other method on the same instance.
- Postcondition:
memTab
[] contains pointers to all of the memory passed to the algorithm via algInit().
-
The size and alignment fields contain the same values passed to the client via algAlloc(); i.e., if the client makes changes to the values returned via algAlloc() and passes these new values to algInit(), the algorithm is not responsible for retaining any such changes.
- See also:
- algAlloc()
Initialize an algorithm's instance object. Must be non-NULL.
- Parameters:
-
[in] | handle | Algorithm instance handle. This is a pointer to an initialized IALG_Obj structure. Its value is identical to the memTab[0].base . |
[in] | memTab | Array of allocated buffers. |
[in] | parent | Handle of algorithm's parent instance. |
[in] | params | Pointer to algorithm's instance parameters. |
- Example:
typedef struct EncoderObj {
IALG_Obj ialgObj;
int workBuf;
Int workBufLen;
... ;
} EncoderObj;
Int algInit(IALG_Handle handle, IALG_MemRec memTab[],
IALG_Handle parent, IALG_Params *params)
{
EncoderObj *inst = (EncoderObj *)handle;
EncoderParams *encParams = (EncoderParams *)params;
if (encParams == NULL) {
encParams = MYDEFAULTPARAMS;
}
if (IALG_isOffChip(memTab[1].space)) {
return (MYMOD_MYVENDOR_EUNSUPPORTEDOFFCHIPWORKBUF);
}
inst->workBuf = memTab[1].base;
inst->workBufLen = encParams->frameDuration * 8;
...
return (IALG_EOK);
}
- Precondition:
memTab
contains pointers to non-overlapping buffers with the size and alignment requested via a prior call to algAlloc(). In addition, the algorithm parameters, params, passed to algAlloc() are identical to those passed to this operation.
-
handle
must be a valid handle for the algorithm's instance object; i.e., handle == memTab[0].base
and handle->fxns
is initialized to point to the appropriate IALG_Fxns structure.
-
The prior call to algAlloc() using same creation params must have returned value > 1. This pre-condition ensures that any create-time parameter validation can be done once (in algAlloc()), and is not required to be done in algInit(). Note that algInit() can, and should, validate any algorithm- specific requirements on resources received (e.g. internal memory, etc).
-
If the prior call to algAlloc() has not assigned a non-NULL base address to an IALG_WRITEONCE
memTab
entry, the client must provide the memory resource with the requested size and alignment.
-
If the prior call to algAlloc() returned a non-NULL parent functions pointer, then the parent handle,
parent
, must be a valid handle to an instance object created via that function pointer.
-
No other algorithm method is currently being run on this instance. This method never preempts any other method on the same instance.
-
If
parent
is non-NULL, no other method is currently being run on the parent instance; i.e., this method never preempts any other method on the parent instance.
-
If the prior call to algAlloc() assigned a non-NULL base address to an IALG_WRITEONCE
memTab
[] entry, the client may pass back the same address in the base field without allocating additional memory for that persistent write-once buffer. Alternatively, the client may treat IALG_WRITEONCE buffers in the same way as IALG_PERSIST buffers; by allocating new memory and granting it to the algorithm using the base field.
-
The buffer pointed to in
memTab
[0] is initialized with a pointer to the appropriate IALG_Fxns structure followed by all 0s.
- Postcondition:
- With the exception of any initialization performed by algActivate() and any optional auxilary interface initialization functions (such as IRES and IDMA3), all of the instance's persistent and write-once memory is initialized and the object is ready to be used.
-
All subsequent memory accesses to the IALG_WRITEONCE buffers by this algorithm instance will be read-only.
-
If the algorithm has implemented the IDMA2 interface, the dmaGetChannels() operation can be called.
- Return values:
-
IALG_EOK | Successful return status code.
|
IALG_EFAIL | Unspecified error return status code.
|
Custom error | Algorithm-specific error - see algorithm's documentation. |
- See also:
- algAlloc()
-
algMoved()
Notify algorithm instance that instance memory has been relocated.
- Parameters:
-
[in] | handle | Algorithm instance handle. |
[in] | memTab | Array of allocated buffers. |
[in] | parent | Handle of algorithm's parent instance. |
[in] | params | Pointer to algorithm's instance parameters. |
Number of memory allocation requests required.
- Postcondition:
- The return value from algNumAlloc() is always greater than or equal to one and always equals or exceeds the value returned by algAlloc().
- Example:
- See also:
- algAlloc()
The documentation for this struct was generated from the following file: