IALG_Fxns Struct Reference

Defines the fields and methods that must be supplied by all XDAIS algorithms. More...

#include <ialg.h>

Collaboration diagram for IALG_Fxns:

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.

@param[in]  handle          Algorithm instance handle.  This is a pointer
                            to an initialized IALG_Obj structure.  Its
                            value is identical to the
                            <tt>memTab[0].base</tt>.
@param[in]  memTab          Array of allocated buffers.
@param[in]  parent          Handle of algorithm's parent instance.
@param[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.

@remarks    @c handle is a pointer to an initialized IALG_Obj structure.
            Its value is identical to the <tt>memTab[0].base</tt>.

@remarks    @c 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().

@remarks    @c 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.

@remarks    @c 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.

@remarks    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.

@remarks    The algorithm <b>must not</b> 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 <i>another</i> 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.

@remarks    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.

@remarks    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.

@par Example:

@code 
    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);
    }
@endcode

@pre        @c 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.

@pre        @c handle must be a valid handle for the algorithm's
            instance object; i.e., <tt>handle == memTab[0].base</tt> and
            @c handle->fxns is initialized to point to the
            appropriate IALG_Fxns structure.

@pre        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).

@pre        If the prior call to algAlloc() has not assigned a non-NULL
            base address to an #IALG_WRITEONCE @c memTab entry,
            the client must provide the memory resource with the
            requested size and alignment.

@pre        If the prior call to algAlloc() returned a non-NULL parent
            functions pointer, then the parent handle, @c parent,
            must be a valid handle to an instance object created
            via that function pointer.

@pre        No other algorithm method is currently being run on this
            instance.  This method never preempts any other method
            on the same instance.

@pre        If @c 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.

@pre        If the prior call to algAlloc() assigned a non-NULL base
            address to an #IALG_WRITEONCE @c 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.

@pre        The buffer pointed to in @c memTab[0] is initialized
            with a pointer to the appropriate IALG_Fxns structure
            followed by all 0s.

@post       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.

@post       All subsequent memory accesses to the #IALG_WRITEONCE
            buffers by this algorithm instance will be read-only.

@post       If the algorithm has implemented the IDMA2 interface,
            the dmaGetChannels() operation can be called.

@retval     #IALG_EOK       \copybrief IALG_EOK

Successful return status code.

Return values:

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:

• cetools/packages/ti/xdais/ialg.h