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