IALG_Fxns Struct Reference
[IALG - XDAIS Algorithm Interface]

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

Void* IALG_Fxns::implementationId

Unique pointer that identifies the module implementing this interface.

Void(* IALG_Fxns::algActivate)(IALG_Handle handle)

Notification to the algorithm that its memory is "active" and algorithm processing methods may be called.

Parameters:

[in] handle Handle to an algorithm instance.

Remarks:

algActivate() initializes any of the instance's scratch buffers using the persistent memory that is part of the algorithm's instance object.

The implementation of algActivate() (and algDeactivate()) is required if the algorithm requests memory of type IALG_SCRATCH.

The algActivate() method should only be implemented if a module wants to factor out initialization code that can be executed once prior to processing multiple consecutive frames of data.

If a module does not implement this method, the algActivate() field in the module's static function table (of type IALG_Fxns) must be set to NULL. This is equivalent to the following implementation:

      Void algActivate(IALG_Handle handle)
      {
      }

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().

Int(* IALG_Fxns::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.

Parameters:

`[in]`	params	Algorithm specific attributes.
`[out]`	parentFxns	Parent algorithm functions.
`[out]`	memTab	array of memory records.

Remarks:: algAlloc() returns a table of memory records that describe the size, alignment, type and memory space of all buffers required by an algorithm (including the algorithm's instance object itself). If successful, this function returns a positive non-zero value indicating the number of records initialized. This function can never initialize more memory records than the number returned by algNumAlloc().; If algNumAlloc() is not implemented, the maximum number of initialized memory records is IALG_DEFMEMRECS.; The first argument to algAlloc() is a pointer to the creation parameters for the instance of the algorithm object to be created. This pointer is algorithm-specific; i.e., it points to a structure that is defined by each particular algorithm. This pointer may be NULL; however, in this case, algAlloc() must assume default creation parameters and must not fail.; The second argument to algAlloc() is an optional parameter. algAlloc() may return a pointer to its parent's IALG functions. If this output value is assigned a non-NULL value, the client must create the parent instance object using the designated IALG functions pointer. The parent instance object must then be passed to algInit().; algAlloc() may be called at any time and it must be idempotent; i.e., it can be called repeatedly without any side effects, and always returns the same result.; Algorithms are encouraged to return (and document!) clear, algorithm-specific error codes from algAlloc(). Create-time failures are a common integration issue, and the clearer a return value, the sooner the algorithm integrator can identify and resolve the issue.

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()

Int(* IALG_Fxns::algControl)(IALG_Handle handle, IALG_Cmd cmd, IALG_Status *status)

Algorithm specific control and status.

Parameters:

`[in]`	handle	Algorithm instance handle.
`[in]`	cmd	Algorithm specific command.
`[out]`	status	Algorithm specific status.

Remarks:

algControl() sends an algorithm specific command, cmd, and an input/output status buffer pointer to an algorithm's instance object.

In preemptive execution environments, algControl() may preempt a module's other metods (for example, its processing methods).

The implementation of algControl() is optional. If a module does not implement this method, the algControl() field in the module's static function table (of type IALG_Fxns) must be set to NULL. This is equivalent to the following implementation:

      Void algControl(IALG_Handle handle, IALG_Cmd cmd, IALG_Status *status)
      {
          return (IALG_EFAIL);
      }

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()

Void(* IALG_Fxns::algDeactivate)(IALG_Handle handle)

Save all persistent data to non-scratch memory.

Parameters:

[in] handle Algorithm instance handle.

Remarks:

algDeactivate() saves any persistent information to non-scratch buffers using the persistent memory that is part of the algorithm's instance object.

handle is used by the algorithm to identify the various buffers that must be saved prior to the next cycle of algActivate() and processing.

The implementation of algDeactivate() (and algActivate()) is required if the algorithm requests memory of type IALG_SCRATCH.

The algDeactivate() method is only implemented if a module wants to factor out initialization code that can be executed once prior to processing multiple consecutive frames of data.

If a module does not implement this method, the algDeactivate() field in the module's static function table (of type IALG_Fxns) must be set to NULL. This is equivalent to the following implementation:

      Void algDeactivate(IALG_Handle 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()

Int(* IALG_Fxns::algFree)(IALG_Handle handle, IALG_MemRec *memTab)

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.

Remarks:: algFree() returns a table of memory records that describe the base address, size, alignment, type and memory space of all buffers previously allocated for the algorithm's instance (including the algorithm's instance object itself) specified by handle. This function always returns a positive non-zero value indicating the number of records initialized. This function can never initialize more memory records than the value returned by algNumAlloc().

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()

Int(* IALG_Fxns::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.

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.

Remarks:: algInit() performs all initialization necessary to complete the run-time creation of an algorithm's instance object. After a successful return from algInit(), the algorithm's instance object is ready to be used to process data.; handle is a pointer to an initialized IALG_Obj structure. Its value is identical to the memTab[0].base.; memTab is a table of memory records that describe the base address, size, alignment, type, and memory space of all buffers allocated for an algorithm instance (including the algorithm's instance object itself). The number of initialized records is identical to the number returned by a prior call to algAlloc().; parent is a handle to another algorithm instance object. This parameter is often NULL; indicating that no parent object exists. This parameter allows clients to create a shared algorithm instance object and pass it to other algorithm instances. For example, a parent instance object might contain global read-only tables that are used by several instances of a vocoder.; params is a pointer to algorithm-specific parameters that are necessary for the creation and initialization of the instance object. This pointer points to the same parameters passed to the algAlloc() operation. However, this pointer may be NULL. In this case, algInit(), must assume default creation parameters.; Algorithms are encouraged to return (and document!) clear, algorithm-specific error codes from algInit(). Create-time failures are a common integration issue, and the clearer a return value, the sooner the algorithm integrator can identify and resolve the issue.; The algorithm must not access any scratch resources, memory or otherwise, until it has been activated (see algActivate()). A common error is to initialize scratch resources during algInit(). This is an error as another algorithm, or instance of the same algorithm, may be active when this instance's algInit() is called. This algorithm must not access scratch resources until it is active.; The client is not required to satisfy the IALG_MemSpace attribute of the requested memory. Note however that C6000 algorithms that use DMA may strictly require the client to satisfy its on-chip memory requirements and may not function correctly otherwise.; The client may allocate the requested IALG_WRITEONCE buffers once (or never, if the algorithm has assigned a base address in the prior call to algAlloc) and use the same buffers to initialize multiple instances of the same algorithm that are created with identical 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)) {
              // unsupported off-chip memory, return documented error code
              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()

Void(* IALG_Fxns::algMoved)(IALG_Handle handle, const IALG_MemRec *memTab, IALG_Handle parent, const IALG_Params *params)

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.

Remarks:: algMoved() performs any reinitialization necessary to insure that, if an algorithm's instance object has been moved by the client, all internal data references are recomputed.; The implementation of algMoved() is optional. However, it is highly recommended that this method be implemented. If a module does not implement this method, the algMoved() field in the module's static function table (of type IALG_Fxns) must be set to NULL. This is equivalent to asserting that the algorithm's instance objects cannot be moved.

Int(* IALG_Fxns::algNumAlloc)(Void)

Number of memory allocation requests required.

Remarks:

algNumAlloc() returns the maximum number of memory allocation requests that the algAlloc() method requires. This operation allows clients to allocate sufficient space to call the algAlloc() method or fail because insufficient space exists to support the creation of the algorithm's instance object. algNumAlloc() may be called at any time, and it must be idempotent; i.e., it can be called repeatedly without any side effects, and always returns the same result.

algNumAlloc() is optional; if it is not implemented, the maximum number of memory records for algAlloc() is assumed to be IALG_DEFMEMRECS. This is equivalent to the following implementation:

      Void algNumAlloc(Void)
      {
          return (IALG_DEFNUMRECS);
      }

If a module does not implement this method, the algNumAlloc() field in the module's static function table (of type IALG_Fxns) must be set to NULL.

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:

      #define NUMBUF 3
      extern IALG_Fxns *subAlg;

      Int algNumAlloc(Void)
      {
          return (NUMBUF + subAlg->algNumAlloc());
      }

      Int algAlloc(const IALG_Params *p, struct IALG_Fxns **pFxns,
              IALG_MemRec memTab)
      {
          Int n;

          ...

          n = subAlg->algAlloc(0, memTab);
          return (n + NUMBUF);
      }

See also:: algAlloc()

The documentation for this struct was generated from the following file:

ialg.h

IALG_Fxns Struct Reference [IALG - XDAIS Algorithm Interface]

Data Fields

Detailed Description

Field Documentation

IALG_Fxns Struct Reference
[IALG - XDAIS Algorithm Interface]