ialg.h

TI Algorithm Soft Kit 5.10 仅包括实例及其原代码

/* 
 *  Copyright 2006
 *  Texas Instruments Incorporated
 *
 *  All rights reserved.  Property of Texas Instruments Incorporated
 *  Restricted rights to use, duplicate or disclose this code are
 *  granted through contract.
 * 
 */

/**
 *  @file       ti/xdais/ialg.h
 *
 *  @brief      This header defines all types, constants, and functions
 *              defined by xDAIS for algorithms.
 */
/**
 *  @defgroup   ti_xdais_IALG   IALG - xDAIS Algorithm Interface
 *
 *  This is the xDAIS IALG interface.
 */

#ifndef ti_xdais_IALG_
#define ti_xdais_IALG_

#ifdef __cplusplus
extern "C" {
#endif

/** @ingroup    ti_xdais_IALG */
/*@{*/

/*---------------------------*/
/*    TYPES AND CONSTANTS    */
/*---------------------------*/

#define IALG_DEFMEMRECS 4   /**< Default number of memory records. */
#define IALG_OBJMEMREC  0   /**< Memory record index of instance object. */
#define IALG_SYSCMD     256 /**< Minimum "system" IALG_Cmd value. */

#define IALG_EOK        0   /**< Successful return status code. */
#define IALG_EFAIL      -1  /**< Unspecified error return status code. */

/**
 *  @brief      Memory attributes.
 */
typedef enum IALG_MemAttrs {
    IALG_SCRATCH,           /**< Scratch memory. */
    IALG_PERSIST,           /**< Persistent memory. */
    IALG_WRITEONCE          /**< Write-once persistent memory. */
} IALG_MemAttrs;

#define IALG_MPROG  0x0008  /**< Program memory space bit. */
#define IALG_MXTRN  0x0010  /**< External memory space bit. */

/**
 *  @brief      Defined memory spaces.
 */
/*
 *  ======== IALG_MemSpace ========
 */
typedef enum IALG_MemSpace {
    IALG_EPROG =            /**< External program memory */
        IALG_MPROG | IALG_MXTRN,

    IALG_IPROG =            /**< Internal program memory */
        IALG_MPROG,

    IALG_ESDATA =           /**< Off-chip data memory (accessed sequentially) */
        IALG_MXTRN + 0,

    IALG_EXTERNAL =         /**< Off-chip data memory (accessed randomly) */
        IALG_MXTRN + 1,

    IALG_DARAM0 = 0,        /**< Dual access on-chip data memory */
    IALG_DARAM1 = 1,        /**< Block 1, if independant blocks required */

    IALG_SARAM  = 2,        /**< Single access on-chip data memory */
    IALG_SARAM0 = 2,        /**< Block 0, equivalent to IALG_SARAM */
    IALG_SARAM1 = 3,        /**< Block 1, if independant blocks required */

    IALG_DARAM2 = 4,        /**< Block 2, if a 3rd independent block required */
    IALG_SARAM2 = 5         /**< Block 2, if a 3rd independent block required */
} IALG_MemSpace;

/*
 *  ======== IALG_isProg ========
 */
#define IALG_isProg(s) (        \
    (((int)(s)) & IALG_MPROG)   \
)

/*
 *  ======== IALG_isOffChip ========
 */
#define IALG_isOffChip(s) (     \
    (((int)(s)) & IALG_MXTRN)   \
)


/**
 *  @brief      Memory records.
 */
typedef struct IALG_MemRec {
    Uns             size;       /**< Size in MAU of allocation */
    Int             alignment;  /**< Alignment requirement (MAU) */
    IALG_MemSpace   space;      /**< Allocation space */
    IALG_MemAttrs   attrs;      /**< Memory attributes */
    Void            *base;      /**< Base address of allocated buf */
} IALG_MemRec;


/**
 *  @brief      Algorithm instance object definition.
 *
 *  @remarks    All xDAIS algorithm instance objects <b>must</b> have this
 *              structure as their first element.  However, they do not
 *              need to initialize it; initialization of this sub-structure
 *              is done by the "framework".
 */
typedef struct IALG_Obj {
    struct IALG_Fxns *fxns;     /**< Pointer to IALG function table. */
} IALG_Obj;


/**
 *  @brief      Handle to an algorithm instance object.
 */
typedef struct IALG_Obj *IALG_Handle;


/**
 *  @brief      Algorithm instance creation parameters.
 *
 *  @remarks    All XDAS algorithm parameter structures <b>must</b> have a this
 *              as their first element.
 */
typedef struct IALG_Params {
    Int size;       /**< Number of MAU in the structure */
} IALG_Params;


/**
 *  @brief      Pointer to algorithm specific status structure.
 *
 *  @remarks    All xDAIS algorithm parameter structures <b>must</b> have this
 *              as their first element.
 */
typedef struct IALG_Status {
    Int size;       /**< Number of MAU in the structure */
} IALG_Status;


/**
 *  @brief      Algorithm specific command.
 *
 *  @remarks    This command is used in conjunction with IALG_Status to get
 *              and set algorithm specific attributes via the algControl()
 *               method.
 */
typedef unsigned int IALG_Cmd;


/**
 *  @brief      Defines the fields and methods that must be supplied by all
 *              xDAIS algorithms.
 */
/*
 *      algAlloc()        - apps call this to query the algorithm about
 *                          its memory requirements. Must be non-NULL.
 *      algControl()      - algorithm specific control operations.  May be
 *                          NULL; NULL => no operations supported.
 *      algDeactivate()   - notification that current instance is about to
 *                          be "deactivated".  May be NULL; NULL => do nothing.
 *      algFree()         - query algorithm for memory to free when removing
 *                          an instance.  Must be non-NULL.
 *      algInit()         - apps call this to allow the algorithm to
 *                          initialize memory requested via algAlloc().  Must
 *                          be non-NULL.
 *      algMoved()        - apps call this whenever an algorithms object or
 *                          any pointer parameters are moved in real-time.
 *                          May be NULL; NULL => object can not be moved.
 *      algNumAlloc()     - query algorithm for number of memory requests.
 *                          May be NULL; NULL => number of mem recs is less
 *                          then IALG_DEFMEMRECS.
 */
typedef struct IALG_Fxns {
/**
 *  @brief      Unique pointer that identifies the module
 *              implementing this interface.
 */
    Void    *implementationId;

/**
 *  @brief      Notification to the algorithm that its memory
 *              is "active" and algorithm processing methods
 *              may be called.
 *
 *  @param[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.
 *
 *  @remarks    The implementation of algActivate() is optional.  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.
 *
 *  @remarks    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 @c NULL.  This is equivalent to
 *              the following implementation:
 *  @code
 *      Void algActivate(IALG_Handle handle)
 *      {
 *      }
 *  @endcode
 *
 *  @pre        algActivate() can only be called after a successful return
 *              from algInit().
 *
 *  @pre        @c handle must be a valid handle for the algorithm's
 *              instance object.
 *
 *  @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 the algorithm has implemented the IDMA2 interface,
 *              algActivate() can only be called after a successful return
 *              from dmaInit().
 *
 *  @post       All methods related to the algorithm may now be executed
 *              by client (subject to algorithm specific restrictions).
 *
 *  @sa         algDeactivate().
 */
    Void    (*algActivate)(IALG_Handle handle);

/**
 *  @brief      Apps call this to query the algorithm about
 *              its memory requirements.  Must be non-NULL.
 *
 *  @param[in]  params          Algorithm specific attributes.
 *  @param[out] parentFxns      Parent algorithm functions.
 *  @param[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().
 *
 *  @remarks    If algNumAlloc() is not implemented, the maximum number
 *              of initialized memory records is #IALG_DEFMEMRECS.
 *
 *  @remarks    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 @c NULL; however, in this case, algAlloc()
 *              must assume default creation parameters and must not fail.
 *
 *  @remarks    The second argument to algAlloc() is an optional parameter.