packages/ti/sdo/ce/alg/alg.h

   1 /*
   2  * Copyright (c) 2013, Texas Instruments Incorporated
   3  * All rights reserved.
   4  *
   5  * Redistribution and use in source and binary forms, with or without
   6  * modification, are permitted provided that the following conditions
   7  * are met:
   8  *
   9  * *  Redistributions of source code must retain the above copyright
  10  *    notice, this list of conditions and the following disclaimer.
  11  *
  12  * *  Redistributions in binary form must reproduce the above copyright
  13  *    notice, this list of conditions and the following disclaimer in the
  14  *    documentation and/or other materials provided with the distribution.
  15  *
  16  * *  Neither the name of Texas Instruments Incorporated nor the names of
  17  *    its contributors may be used to endorse or promote products derived
  18  *    from this software without specific prior written permission.
  19  *
  20  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  21  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
  22  * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  23  * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
  24  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  25  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  26  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
  27  * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
  28  * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
  29  * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
  30  * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  31  *
  32  */
  33 /*
  34  *  ======== alg.h ========
  35  */
  36 #ifndef ti_sdo_ce_alg_ALG_
  37 #define ti_sdo_ce_alg_ALG_
  38
  39 #include <ti/xdais/ialg.h>
  40
  41 #ifdef __cplusplus
  42 extern "C" {
  43 #endif
  44
  45 /**
  46  * @brief       Name to pass to Diags_setMask() to enable logging for ALG
  47  *              functions. For example,
  48  *                  Diags_setMask(ALG_MODNAME"+EX1234567");
  49  *              turns on all Log statements in this module.
  50  *              Diags_setMask() must be called after initialization to take
  51  *              effect.
  52  */
  53 #define ALG_MODNAME "ti.sdo.ce.alg"
  54
  55 #define ALG_GTNAME "ti.sdo.ce.alg"
  56
  57 /*
  58  *  ======== ALG_Handle ========
  59  */
  60 /**
  61  *  @brief      This handle type is used to reference all ALG instance objects.
  62  */
  63 typedef IALG_Handle ALG_Handle;
  64
  65 /*
  66  *  ======== ALG_activate ========
  67  */
  68 /**
  69  *  @brief      Restore all shared persistant data associated with algorithm
  70  *              object.
  71  *
  72  *  @param[in] groupId  Group which @c alg is associated with.
  73  *  @param[in] alg      Handle of algorithm to activate.
  74  *
  75  *  @todo       Typically handles are the first params passed to a fxn.
  76  *  @todo       Could we store the groupId in the alg handle at create time
  77  *              so we don't need to supply it to ALG_delete()?
  78  */
  79 extern Void ALG_activate(Int groupId, ALG_Handle alg);
  80
  81 /*
  82  *  ======== ALG_addGroup ========
  83  */
  84 /**
  85  *  @brief      Do any initialization necessary to use a particular scratch
  86  *              group. If there are no algorithms built into the app that
  87  *              are in a given scratch group, no locks will be created for
  88  *              that scratch group. If a dynamically loaded codec is to be
  89  *              run in a scratch group, there must be a lock for that scratch
  90  *              group. This function will create the lock, in case it has not
  91  *              been created yet, otherwise it will increment a reference
  92  *              count.
  93  *
  94  *  @param[in]  groupId     Scratch group number.
  95  *
  96  *  @pre        ALG_init() must have been called.
  97  *  @pre        Calls to this function must be synchronized.
  98  *
  99  *  @retval     TRUE        Success.
 100  *  @retval     FALSE       An error has occurred.
 101  *
 102  *  @sa         ALG_removeGroup()
 103  */
 104 extern Bool ALG_addGroup(Int groupId);
 105
 106 /*
 107  *  ======== ALG_control ========
 108  */
 109 /**
 110  *  @brief      Control algorithm object.
 111  */
 112 extern Int ALG_control(ALG_Handle alg, IALG_Cmd cmd, IALG_Status *sptr);
 113
 114 /**
 115  *  @brief      Algorithm Cacheable Memory types.
 116  *
 117  *  @enumWarning
 118  */
 119 typedef enum ALG_CachedMemType {
 120     ALG_USECACHEDMEM_DEFAULT = -1,  /**< Use default cache setting */
 121     ALG_USECACHEDMEM_NONCACHED = 0, /**< Use non-cached memory */
 122     ALG_USECACHEDMEM_CACHED = 1     /**< Use cached memory */
 123 } ALG_CachedMemType;
 124
 125
 126 /*
 127  *  ======== ALG_create ========
 128  */
 129 /**
 130  *  @brief      Create algorithm object and initialize its memory.
 131  *
 132  *  @param[in]  groupId         Group which alg should be created in.
 133  *  @param[in]  fxns            IALG function table
 134  *  @param[in]  p               Parent alg
 135  *  @param[in]  prms            Creation parameters
 136  *  @param[in]  useCachedMem    Indicates whether the memory should be
 137  *                              cached or not.
 138  *
 139  *  @retval     NULL            Failed to create algorithm
 140  *  @retval     non-NULL        Success - algorithm handle is returned
 141  *
 142  *  @sa         ALG_delete()
 143  */
 144 extern ALG_Handle ALG_create(Int groupId, IALG_Fxns *fxns, IALG_Handle p,
 145         IALG_Params *prms, UInt32 useCachedMem);
 146
 147 /*
 148  *  ======== ALG_deactivate ========
 149  */
 150 /**
 151  *  @brief      Save all shared persistant data associated with algorithm
 152  *              object to some non-shared persistant memory.
 153  *
 154  *  @param[in] groupId  Group which @c alg is associated with.
 155  *  @param[in] alg      Handle of algorithm to deactivate.
 156  *
 157  *  @todo       Typically handles are the first params passed to a fxn.
 158  *  @todo       Could we store the groupId in the alg handle at create time
 159  *              so we don't need to supply it to ALG_delete()?
 160  */
 161 extern Void ALG_deactivate(Int groupId, ALG_Handle alg);
 162
 163 /*
 164  *  ======== ALG_delete ========
 165  */
 166 /**
 167  *  @brief      Delete algorithm object and release its memory.
 168  *
 169  *  @param[in]  groupId         groupId which @c alg is associated with.
 170  *  @param[in]  alg             Handle of algorithm to delete.
 171  *  @param[in]  useCachedMem    Indicates whether memory was cached or not.
 172  *
 173  *  @todo       Typically handles are the first params passed to a fxn.
 174  *  @todo       Could we store the groupId in the alg handle at create time
 175  *              so we don't need to supply it to ALG_delete()?
 176  */
 177 extern Void ALG_delete(Int groupId, ALG_Handle alg, UInt32 useCachedMem);
 178
 179 /*
 180  *  ======== ALG_acquireLock ========
 181  */
 182 /**
 183  *  @brief      Acquire the scratch group lock by the algorithm.
 184  *
 185  *  @param[in]  groupId         groupId which @c alg is associated with.
 186  *  @param[in]  alg             handle of algorithm trying to acquire the lock.
 187  *
 188  *  @todo       Typically handles are the first params passed to a fxn.
 189  *  @todo       Could we store the groupId in the alg handle at create time
 190  *              so we don't need to supply it to ALG_delete()?
 191  */
 192 extern Void ALG_acquireLock(Int groupId, IALG_Handle alg);
 193
 194
 195 /*
 196  *  ======== ALG_releaseLock ========
 197  */
 198 /**
 199  *  @brief      Release the scratch group lock held by this algorithm.
 200  *
 201  *  @param[in]  groupId         groupId which @c alg is associated with.
 202  *  @param[in]  alg             handle of algorithm releasing the lock.
 203  *
 204  *  @todo       Typically handles are the first params passed to a fxn.
 205  *  @todo       Could we store the groupId in the alg handle at create time
 206  *              so we don't need to supply it to ALG_delete()?
 207  */
 208
 209 extern Void ALG_releaseLock(Int groupId, IALG_Handle alg);
 210
 211 /*
 212  *  ======== ALG_removeGroup ========
 213  */
 214 /**
 215  *  @brief      Do any de-initialization necessary when a particular scratch
 216  *              group is no longer needed. If a dynamically loaded codec is
 217  *              unloaded, this function should be called to indicate that
 218  *              the scratch group that the codec ran in is no longer needed.
 219  *              This function will decrement a reference count, and if 0,
 220  *              remove any locks for the group.
 221  *
 222  *  @param[in]  groupId     Scratch group number.
 223  *
 224  *  @pre        ALG_init() must have been called.
 225  *
 226  *  @sa         ALG_addGroup()
 227  */
 228 extern Void ALG_removeGroup(Int groupId);
 229
 230 /*
 231  *  ======== ALG_exit ========
 232  *  Module finalization
 233  */
 234 extern Void ALG_exit(Void);
 235
 236 /*
 237  *  ======== ALG_init ========
 238  *  Module initialization
 239  */
 240 extern Void ALG_init(Void);
 241
 242 #ifdef __cplusplus
 243 }
 244 #endif
 245
 246 #endif