index 125be486342b7550d3f0417ff1a8df3dce2b3ee0..663126ffde0785d2ed8318c3cec1030ab3f6c689 100644 (file)
/*
- * Copyright (c) 2012, Texas Instruments Incorporated
+ * Copyright (c) 2012-2014, Texas Instruments Incorporated
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
* OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
* EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
- *
*/
/**
* @file ti/sdo/fc/dskt2/dskt2.h
* @brief Prepares a XDAIS algorithm instance object to start using its
* scratch memory.
*
- * DSKT2_activateAlg() performs all scratch memory initialization
- * for an algorithm's instance object. After a successful return
- * from DSKT2_activateAlg(), the algorithm's instance object is
- * ready to be used to process data.
- *
- * Unless the instance is already active, DSKT2_activateAlg()
- * uses the algorithm's IALG interface function algActivate to
- * initialize the algorithm instance's scratch buffers from
- * persistent data memory.
- *
- * DSKT2_activateAlg() must be called before any processing or
- * control methods of the algorithm instance can be called.
- *
- * DSKT2 maintains state information about current "active"
- * algorithm instances at run-time, so that it does not perform
- * unnecessary IALG "activation" calls when alg is already active.
- * As part of this optimization it may call the algDeactivate
- * method of the currently active algorithm instance in order to
- * activate this algorithm instance (alg).
- *
* @param[in] scratchMutexId scratch-group Id used to associate the instance
* with a scratch group. The value must be the
* same id used when creating this algorithm
* @post All of the instance's persistent and scratch memory is
* initialized and the object is ready to be used.
*
+ * @remarks DSKT2_activateAlg() performs all scratch memory initialization
+ * for an algorithm's instance object. After a successful return
+ * from DSKT2_activateAlg(), the algorithm's instance object is
+ * ready to be used to process data.
+ *
+ * @remarks Unless the instance is already active, DSKT2_activateAlg()
+ * uses the algorithm's IALG interface function algActivate to
+ * initialize the algorithm instance's scratch buffers from
+ * persistent data memory.
+ *
+ * @remarks DSKT2_activateAlg() must be called before any processing or
+ * control methods of the algorithm instance can be called.
+ *
+ * @remarks DSKT2 maintains state information about current "active"
+ * algorithm instances at run-time, so that it does not perform
+ * unnecessary IALG "activation" calls when alg is already active.
+ * As part of this optimization it may call the algDeactivate
+ * method of the currently active algorithm instance in order to
+ * activate this algorithm instance (alg).
+ *
* @remarks Caller ensures algorithms with the same @c scratchMutexId will
* not be activated simultaneously. Usually the scratch group id
* is associated to the priority of the task in which the
* @post If the cmd value is not recognized, the return value is not
* equal to IALG_EOK.
*
- * @note DSKT2_controlAlg() must be called only when the instance is in
+ * @remarks DSKT2_controlAlg() must be called only when the instance is in
* active state.
*
- * @note The implementation of the IALG algControl is optional by XDAIS
+ * @remarks The implementation of the IALG algControl is optional by XDAIS
* standard. DSKT2_controlAlg() makes proper checks to ensure
* correct operation even if the algorithm does not implement
* algControl().
/**
* @brief Creates and initializes a XDAIS algorithm instance object.
*
- * It uses the algorithm's IALG interface functions to query the
- * algorithm for its memory needs then allocates the memory for
- * the algorithm and calls the algorithm's algInit function to
- * let the new algorithm instance object initialize itself using
- * the allocated memory.
- *
- * DSKT2_createAlg() performs initialization necessary to complete
- * the run-time creation of an algorithm's instance object. After
- * a successful return from DSKT2_createAlg(), the algorithm's
- * instance object can be activated via a DSKT2_activateAlg()
- * before it can be used to process data.
- *
- * DSKT2_createAlg() tries to dynamically allocate instance memory
- * based on the IALG_MemSpace attribute of the requested memory.
- * Global DSKT2 configuration settings allow OEM to designate a
- * memory heap for each IALG_MemSpace. DSKT2_createAlg() attempts
- * to allocate memory in the requested space, but may search for
- * alternative heaps when preferred heap is not large enough.
- *
* @param[in] scratchMutexId Scratch-group Id for determining the shared
* scratch memory buffer. Value -1 is used to
* disable scratch sharing for this algorithm
* persistent memory is initialized and the object is ready to be
* used
*
- * @note The parent argument is a handle to another algorithm instance
+ * @remarks It uses the algorithm's IALG interface functions to query the
+ * algorithm for its memory needs then allocates the memory for
+ * the algorithm and calls the algorithm's algInit function to
+ * let the new algorithm instance object initialize itself using
+ * the allocated memory.
+ *
+ * @remarks DSKT2_createAlg() performs initialization necessary to complete
+ * the run-time creation of an algorithm's instance object. After
+ * a successful return from DSKT2_createAlg(), the algorithm's
+ * instance object can be activated via a DSKT2_activateAlg()
+ * before it can be used to process data.
+ *
+ * @remarks DSKT2_createAlg() tries to dynamically allocate instance memory
+ * based on the IALG_MemSpace attribute of the requested memory.
+ * Global DSKT2 configuration settings allow OEM to designate a
+ * memory heap for each IALG_MemSpace. DSKT2_createAlg() attempts
+ * to allocate memory in the requested space, but may search for
+ * alternative heaps when preferred heap is not large enough.
+ *
+ * @remarks The parent argument 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
* global read-only tables that are used by several instances of a
* vocoder.
*
- * @remark Caller need to ensure algorithms created with the same
+ * @remarks Caller need to ensure algorithms created with the same
* "scratchMutexId" will not execute simultaneously
*
- * @remark On failure all memory allocated during the call (used for
+ * @remarks On failure all memory allocated during the call (used for
* algorithm query, and portions of algorithm memory that were
* successfully allocated during the function) has been freed
* before DSKT2_createAlg() returns
*
- * @note The params argument is a pointer to algorithm-specific
+ * @remarks The params argument 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 algorithm's IALG algAlloc
* algorithm's IALG function algInit, must assume default creation
* parameters.
*
- * @note Mutual exclusion needs to be enforced by the application
+ * @remarks Mutual exclusion needs to be enforced by the application
* framework when executing this function.
- * This function assumes that the create phase of xDAIS algorithms * in the same scratch group will not be scheduled concurrently.
+ * This function assumes that the create phase of XDAIS algorithms
+ * in the same scratch group will not be scheduled concurrently.
*
**
* @sa DSKT2_activateAlg(), DSKT2_deactivateAlg(), DSKT2_freeAlg()
/**
* @brief Creates and initializes a XDAIS algorithm instance object.
*
- * It uses the algorithm's IALG interface functions to query the
- * algorithm for its memory needs then allocates the memory for
- * the algorithm and calls the algorithm's algInit function to
- * let the new algorithm instance object initialize itself using
- * the allocated memory.
- *
- * DSKT2_createAlg2() performs initialization necessary to complete
- * the run-time creation of an algorithm's instance object. After
- * a successful return from DSKT2_createAlg2(), the algorithm's
- * instance object can be activated via a DSKT2_activateAlg()
- * before it can be used to process data.
- *
- * DSKT2_createAlg2() tries to dynamically allocate instance memory
- * based on the IALG_MemSpace attribute of the requested memory.
- * Global DSKT2 configuration settings allow OEM to designate a
- * memory heap for each IALG_MemSpace. DSKT2_createAlg2() attempts
- * to allocate memory in the requested space, but may search for
- * alternative heaps when preferred heap is not large enough.
- *
- * DSKT2_createAlg2() will attempt to use the heap specified by
- * the input parameter, extHeapId, for all allocations in the
- * IALG_MemSpace, IALG_ESDATA. Furthermore, this holds for
- * any IALG_MemSpace that has been configured with the same
- * memory segment as IALG_ESDATA. e.g., if IALG_ESDATA and
- * IALG_SARAM3 have both been configured to use the heap in the
- * memory segment EXTMEM, then DSKT2_createAlg2() will attempt
- * to allocate memory requested in the spaces IALG_SARAM3
- * and IALG_ESDATA, from the heap, extHeapId.
- *
* @param[in] scratchMutexId Scratch-group Id for determining the shared
* scratch memory buffer. Value -1 is used to
* disable scratch sharing for this algorithm
* persistent memory is initialized and the object is ready to be
* used
*
- * @note The parent argument is a handle to another algorithm instance
+ * @remarks It uses the algorithm's IALG interface functions to query the
+ * algorithm for its memory needs then allocates the memory for
+ * the algorithm and calls the algorithm's algInit function to
+ * let the new algorithm instance object initialize itself using
+ * the allocated memory.
+ *
+ * @remarks DSKT2_createAlg2() performs initialization necessary to complete
+ * the run-time creation of an algorithm's instance object. After
+ * a successful return from DSKT2_createAlg2(), the algorithm's
+ * instance object can be activated via a DSKT2_activateAlg()
+ * before it can be used to process data.
+ *
+ * @remarks DSKT2_createAlg2() tries to dynamically allocate instance memory
+ * based on the IALG_MemSpace attribute of the requested memory.
+ * Global DSKT2 configuration settings allow OEM to designate a
+ * memory heap for each IALG_MemSpace. DSKT2_createAlg2() attempts
+ * to allocate memory in the requested space, but may search for
+ * alternative heaps when preferred heap is not large enough.
+ *
+ * @remarks DSKT2_createAlg2() will attempt to use the heap specified by
+ * the input parameter, extHeapId, for all allocations in the
+ * IALG_MemSpace, IALG_ESDATA. Furthermore, this holds for
+ * any IALG_MemSpace that has been configured with the same
+ * memory segment as IALG_ESDATA. e.g., if IALG_ESDATA and
+ * IALG_SARAM3 have both been configured to use the heap in the
+ * memory segment EXTMEM, then DSKT2_createAlg2() will attempt
+ * to allocate memory requested in the spaces IALG_SARAM3
+ * and IALG_ESDATA, from the heap, extHeapId.
+ *
+ * @remarks The parent argument 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
* global read-only tables that are used by several instances of a
* vocoder.
*
- * @note Mutual exclusion needs to be enforced by the application
+ * @remarks Mutual exclusion needs to be enforced by the application
* framework when executing this function.
- * This function assumes that the create phase of xDAIS algorithms * in the same scratch group will not be scheduled concurrently.
+ * This function assumes that the create phase of XDAIS algorithms
+ * in the same scratch group will not be scheduled concurrently.
*
- * @remark Caller need to ensure algorithms created with the same
+ * @remarks Caller need to ensure algorithms created with the same
* "scratchMutexId" will not execute simultaneously
*
- * @remark On failure all memory allocated during the call (used for
+ * @remarks On failure all memory allocated during the call (used for
* algorithm query, and portions of algorithm memory that were
* successfully allocated during the function) has been freed
* before DSKT2_createAlg() returns
*
- * @note The params argument is a pointer to algorithm-specific
+ * @remarks The params argument 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 algorithm's IALG algAlloc
* @brief Creates and initializes a XDAIS algorithm instance object,
* allocating all algorithm memory in external memory.
*
- * This API is very similar to DSKT2_createAlg(), in that
- * it uses the algorithm's IALG interface functions to query the
- * algorithm for its memory needs, allocates the memory for
- * the algorithm and calls the algorithm's algInit function to
- * let the new algorithm instance object initialize itself using
- * the allocated memory. Unlike DSKT2_createAlg(), however,
- * DSKT2_createAlgExt() will ignore the @c space field of the
- * @c IALG_MemRec table entries filled in by the algorithm's
- * algAlloc() function, and allocate all of the memory in the
- * memory segment that is mapped to DSKT2.ESDATA.
- *
- * After a successful return from DSKT2_createAlgExt(), the
- * algorithm's instance object can be activated via a
- * DSKT2_activateAlg() before it can be used to process data.
- *
- *
* @param[in] scratchId Scratch-group Id for determining the shared
* scratch memory buffer. Value -1 is used to
* disable scratch sharing for this algorithm
* persistent memory is initialized and the object is ready to be
* used
*
- * @note The parent argument is a handle to another algorithm instance
+ * @remarks This API is very similar to DSKT2_createAlg(), in that
+ * it uses the algorithm's IALG interface functions to query the
+ * algorithm for its memory needs, allocates the memory for
+ * the algorithm and calls the algorithm's algInit function to
+ * let the new algorithm instance object initialize itself using
+ * the allocated memory. Unlike DSKT2_createAlg(), however,
+ * DSKT2_createAlgExt() will ignore the @c space field of the
+ * @c IALG_MemRec table entries filled in by the algorithm's
+ * algAlloc() function, and allocate all of the memory in the
+ * memory segment that is mapped to DSKT2.ESDATA.
+ *
+ * @remarks After a successful return from DSKT2_createAlgExt(), the
+ * algorithm's instance object can be activated via a
+ * DSKT2_activateAlg() before it can be used to process data.
+ *
+ * @remarks The parent argument 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
* global read-only tables that are used by several instances of a
* vocoder.
*
- * @note Mutual exclusion needs to be enforced by the application
+ * @remarks Mutual exclusion needs to be enforced by the application
* framework when executing this function.
- * This function assumes that the create phase of xDAIS algorithms * in the same scratch group will not be scheduled concurrently.
+ * This function assumes that the create phase of XDAIS algorithms
+ * in the same scratch group will not be scheduled concurrently.
*
- * @remark Caller need to ensure algorithms created with the same
+ * @remarks Caller need to ensure algorithms created with the same
* "scratchMutexId" will not execute simultaneously
*
- * @remark On failure all memory allocated during the call (used for
+ * @remarks On failure all memory allocated during the call (used for
* algorithm query, and portions of algorithm memory that were
* successfully allocated during the function) has been freed
* before DSKT2_createAlg() returns
*
- * @note The params argument is a pointer to algorithm-specific
+ * @remarks The params argument 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 algorithm's IALG algAlloc
* @brief Prepares a XDAIS algorithm instance object to give up using
* its scratch memory
*
- * DSKT2_deactivateAlg() marks an algorithm's shared scratch
- * memory as available to other instances activation. After a
- * successful return from DSKT2_deactivateAlg(), the algorithm's
- * processing or control functions cannot be called to process
- * data.
- *
- * Object's deactivation logic involves calling the algorithm's
- * IALG interface function algDeactivate to save necessary data
- * from the algorithm instance's scratch buffers to its persistent
- * data memory.
- *
- * DSKT2_deactivateAlg() must be called after the last processing
- * or control methods of the algorithm instance, alg, during each
- * execute stage of its socket operation.
- *
- * DSKT2 maintains state information about current "active"
- * algorithm instances at run-time, so that it does not perform
- * unnecessary IALG "deactivation" calls. As part of this
- * optimization it may defer the deactivation of this algorithm
- * instance (alg) to a later stage, i.e. when DSKT2_activateAlg()
- * is called to activate another algorithm instance.
- *
* @param[in] scratchMutexId scratch-group Id used for determining the
* shared scratch memory.
* @param[in] alg IALG_Handle of the algorithm instance to be
*
* @pre DSKT2_activateAlg() must be called before calling this method
*
- * @note The implementation of the IALG algDeactivate is optional by
+ * @remarks DSKT2_deactivateAlg() marks an algorithm's shared scratch
+ * memory as available to other instances activation. After a
+ * successful return from DSKT2_deactivateAlg(), the algorithm's
+ * processing or control functions cannot be called to process
+ * data.
+ *
+ * @remarks Object's deactivation logic involves calling the algorithm's
+ * IALG interface function algDeactivate to save necessary data
+ * from the algorithm instance's scratch buffers to its persistent
+ * data memory.
+ *
+ * @remarks DSKT2_deactivateAlg() must be called after the last processing
+ * or control methods of the algorithm instance.
+ *
+ * @remarks DSKT2 maintains state information about current "active"
+ * algorithm instances at run-time, so that it does not perform
+ * unnecessary IALG "deactivation" calls. As part of this
+ * optimization it may defer the deactivation of this algorithm
+ * instance (alg) to a later stage, i.e. when DSKT2_activateAlg()
+ * is called to activate another algorithm instance.
+ *
+ * @remarks The implementation of the IALG algDeactivate is optional by
* XDAIS standard. So, the instance deactivation makes sense only
* when the method is implemented by the algorithm.
* DSKT2_deactivateAlg() makes proper checks to ensure correct
* @brief Deletes a XDAIS algorithm instance object and frees all
* persistent memory allocated for the instance object
*
- * A reference counting mechanism is implemented to free up
- * instance scratch memory so that when the last instance within a
- * scratch group is deleted all shared scratch memory allocated
- * for the group is reclaimed.
- *
- * DSKT2_freeAlg() must be called during delete stage of a
- * socket's operation to prevent memory leaks.
- *
* @param[in] scratchMutexId scratch-group Id used for determining the
* shared scratch memory. Must be the same Id
* used when algorithm instance is created
* @pre alg must be a valid handle for the algorithm's instance object
* returned by an earlier call to DSKT2_createAlg()
*
- * @note DSKT2 maintains allocation information about all algorithm
+ * @remarks A reference counting mechanism is implemented to free up
+ * instance scratch memory so that when the last instance within a
+ * scratch group is deleted all shared scratch memory allocated
+ * for the group is reclaimed.
+ *
+ * @remarks DSKT2 maintains allocation information about all algorithm
* instances created by DSKT2_createAlg(), so it does not call the
* instance algFree method before free'ing instance memory.
*
- * @note Mutual exclusion needs to be enforced by the application
+ * @remarks Mutual exclusion needs to be enforced by the application
* framework when executing this function.
- * This function assumes that the delete phase of xDAIS algorithms * in the same scratch group will not be scheduled concurrently.
+ * This function assumes that the delete phase of XDAIS algorithms
+ * in the same scratch group will not be scheduled concurrently.
*
* @sa DSKT2_createAlg()
*/
/**
* @brief Alocates memory from a DSKT2 shared scratch group buffer.
*
- * If a valid IALG_Handle is passed to this call, allocation is
- * done from the shared buffer in a non-overlapping manner from
- * memory already assigned to the algorithm
- *
* @param[in] alg IALG_Handle of the algorithm instance to be
* granted shared scratch memory. Could be NULL.
* @param[in] mutexId scratch-group Id used for determining the
* @retval TRUE Success
* @retval FALSE Failure
*
- * @pre If alg is a non-NULL value, then it must be a valid handle for
- * the algorithm's instance object returned by an earlier call to
- * DSKT2_createAlg()
+ * @pre If @c alg is not NULL, then it must be a valid handle for
+ * an algorithm instance returned by an earlier call to
+ * DSKT2_createAlg().
*
- * @note DSKT2 maintains allocation information about all algorithm
+ * @remarks If a valid IALG_Handle is passed to this call, allocation is
+ * done from the shared buffer in a non-overlapping manner from
+ * memory already assigned to the algorithm.
+ *
+ * @remarks DSKT2 maintains allocation information about all algorithm
* instances created by DSKT2_createAlg(), so it does not call the
- * instance algFree method before free'ing instance memory.
+ * instance algFree() method before free'ing instance memory.
*
* @sa DSKT2_freeScratch()
*/
/**
* @brief Alocates memory from a DSKT2 shared scratch group buffer.
*
- * If a valid IALG_Handle is passed to this call, allocation is
- * done from teh shared buffer in a non-overlapping manner from
- * memory already assigned to the algorithm
- *
* @param[in] mutexId scratch-group Id used for determining the
* shared scratch memory. Must be the same Id
* used when algorithm instance is created
* @pre Memory must have been allocated through a call
* to DSKT2_allocScratch
*
- * @note DSKT2 maintains allocation information about all algorithm
+ * @remarks If a valid IALG_Handle is passed to this call, allocation is
+ * done from teh shared buffer in a non-overlapping manner from
+ * memory already assigned to the algorithm
+ *
+ * @remarks DSKT2 maintains allocation information about all algorithm
* instances created by DSKT2_createAlg(), so it does not call the
* instance algFree method before free'ing instance memory.
*