Data Structures
struct	Engine_Attrs
	Attributes of an Engine. More...
struct	Engine_AlgInfo
	Properties of an Engine algorithm. More...
struct	Engine_AlgInfo2
	Properties of an Engine algorithm. More...
struct	Engine_AlgDesc
	Descriptor for an alg. This object can be passed to `Engine_addAlg()`, to dynamically add an alg to an engine. More...
struct	Engine_DllAlgDesc
	Descriptor for a dynamically loaded alg. A dynamic library for a codec must export a function that fills in a structure of this type. More...
struct	Engine_Desc
	This structure is passed to `Engine_add()`, and contains parameters to specify an engine. More...
Defines
#define	CE_NULL_algs NULL
#define	CE_DECLARE_TYPE(name, types)
	Macros for runtime configuration. These macros can be used to create a static table of algorithms. However, the preferred method of building engine and alg tables, is to use the run-time APIs, Engine_add() and Engine_addAlg().
#define	CE_LOCAL_ALG(name, algName, ialgFxns, idma3Fxns, iresFxns, groupId, memType)
	Generates a structure containing data for a local algorithm.
#define	CE_LOCAL_ALG2(algName, ialgFxns, idma3Fxns, iresFxns, groupId, memType, types)
	Generates a structure containing data for a local algorithm. This macro takes a 'types' string as an argument to avoid having to use the CE_DECLARE_TYPES() macro call.
#define	CE_DECLARE_LOCAL_ALG(name, algName, ialgFxns, idma3Fxns, iresFxns, groupId, memType, types)
	Generates a static variable of type Engine_AlgDesc. It is used in this manner:
#define	CE_BEGIN_ALG_TABLE(name) static Engine_AlgDesc CE_##name##_algs[] = {
	Use this macro and the CE_END_ALG_TABLE() macro around CE_LOCAL_ALG() to generate an algorithm table for an engine.
#define	CE_END_ALG_TABLE(name)
	Use this macro after CE_BEGIN_ALG_TABLE() and CE_LOCAL_ALG() for generating an algorithm table for an engine.
#define	CE_ENGINE(algTab, engName, serverName, memMap, useExtLoader, heapId)
	Generates a structure containing data for an engine.
#define	CE_BEGIN_ENGINE_TABLE(name)
	Use this macro and the CE_END_ENGINE_TABLE() macro around CE_ENGINE() to generate an engine table for the application.
#define	CE_END_ENGINE_TABLE(name)
	Use this macro and the CE_BEGIN_ENGINE_TABLE() macro around CE_ENGINE() to generate an engine table for the application.
#define	Engine_MODNAME "ti.sdo.ce.Engine"
	Name to pass to Diags_setMask() to enable logging for Engine functions.
#define	Engine_EOK 0
#define	Engine_EEXIST 1
#define	Engine_ENOMEM 2
#define	Engine_EDSPLOAD 3
#define	Engine_ENOCOMM 4
#define	Engine_ENOSERVER 5
#define	Engine_ECOMALLOC 6
#define	Engine_ERUNTIME 7
#define	Engine_ECODECCREATE 8
#define	Engine_ECODECSTART 9
#define	Engine_EINVAL 10
#define	Engine_EBADSERVER 11
#define	Engine_ENOTAVAIL 12
#define	Engine_EWRONGSTATE 13
#define	Engine_EINUSE 14
#define	Engine_ENOTFOUND 15
#define	Engine_ETIMEOUT 16
#define	Engine_GETALGDESCFXN "GetEngineAlgDesc"
	Name of function that a dynamically loaded codec must supply.
Typedefs
typedef struct Engine_Obj *	Engine_Handle
	Opaque handle to an engine.
typedef Int	Engine_Error
	Engine error code.
typedef struct Engine_Attrs	Engine_Attrs
	Attributes of an Engine.
typedef struct Engine_AlgInfo	Engine_AlgInfo
	Properties of an Engine algorithm.
typedef struct Engine_AlgInfo2	Engine_AlgInfo2
	Properties of an Engine algorithm.
typedef enum Engine_CachedMemType	Engine_CachedMemType
	Engine Cacheable Memory types.
typedef struct Engine_AlgDesc	Engine_AlgDesc
	Descriptor for an alg. This object can be passed to `Engine_addAlg()`, to dynamically add an alg to an engine.
typedef struct Engine_DllAlgDesc	Engine_DllAlgDesc
	Descriptor for a dynamically loaded alg. A dynamic library for a codec must export a function that fills in a structure of this type.
typedef Int(*	Engine_GetAlgDescFxn )(Engine_DllAlgDesc *dllAlgDesc)
	Prototype of function that must be supplied by a dynamic codec library to fill in a `Engine_DllAlgDesc` structure.
typedef struct Engine_Desc	Engine_Desc
	This structure is passed to `Engine_add()`, and contains parameters to specify an engine.
Enumerations
enum	Engine_CachedMemType { Engine_USECACHEDMEM_DEFAULT = -1, Engine_USECACHEDMEM_NONCACHED = 0, Engine_USECACHEDMEM_CACHED = 1 }
	Engine Cacheable Memory types. More...
Functions
Void	CERuntime_exit (Void)
	Exit the Codec Engine Runtime.
Void	CERuntime_init (Void)
	Initialize the Codec Engine Runtime.
Engine_Error	Engine_addStubFxns (String fxnsName, IALG_Fxns *fxns)
	Register stub functions through which a remote algorithm can be called.
Engine_Error	Engine_add (Engine_Desc *pDesc)
	Add an Engine to the database of engines that can be opened with Engine_open()
Engine_Error	Engine_addAlg (String name, Engine_Handle engine, String location, Engine_AlgDesc *pAlgDesc)
	Dynamically add an algorithm to an Engine.
Engine_Error	Engine_removeAlg (String name, Engine_Handle engine, String algName)
	Dynamically remove an algorithm that was added to an Engine with Engine_addAlg().
Void	Engine_close (Engine_Handle engine)
	Close an Engine.
Void	Engine_initAlgDesc (Engine_AlgDesc *pAlgDesc)
	Initialize an Engine_AlgDesc structure with default values.
Void	Engine_initAttrs (Engine_Attrs *pAttrs)
	Initialize an Engine_Attrs structure with default values.
Void	Engine_initDesc (Engine_Desc *pDesc)
	Initialize an Engine_Desc structure with default values.
Engine_Handle	Engine_open (String name, Engine_Attrs attrs, Engine_Error ec)
	Open an Engine.
Int	Engine_fwriteTrace (Engine_Handle engine, String prefix, FILE *out)
	Write Server's trace buffer to specifed file stream.
Engine_Error	Engine_getAlgInfo (String name, Engine_AlgInfo *algInfo, Int index)
	Get details of an algorithm configured into an engine.
Engine_Error	Engine_getAlgInfo2 (String name, Engine_Handle engine, Engine_AlgInfo2 *algInfo2, Int index)
	Get details of an algorithm.
Engine_Error	Engine_getDesc (String name, Engine_Desc *desc)
	Fill in an Engine_Desc structure with the values of the Engine descriptor for an Engine.
Engine_Error	Engine_getLastError (Engine_Handle engine)
	Get error code of the last failed operation.
String	Engine_getName (Engine_Handle engine)
	Get the name of an opened engine.
Engine_Error	Engine_getNumAlgs (String name, Int *numAlgs)
	Get the number of algorithms configured into an Engine.
Engine_Error	Engine_getNumAlgs2 (String name, Engine_Handle engine, Int *numAlgs)
	Get the number of algorithms statically configured into an engine or the total number of algorithms both statically configured and dynamically added through server information when the engine was opened.
Server_Handle	Engine_getServer (Engine_Handle engine)
	Get handle to an Engine's Server.
UInt32	Engine_getUsedMem (Engine_Handle engine)
	Get Server's total memory usage.
Engine_Error	Engine_remove (String engineName)
	Remove an engine from the list of engines that can be opened.
Engine_Error	Engine_setDesc (String name, Engine_Desc *desc)
	Set values for an Engine's descriptor. This function should only be called when the Engine has not yet been opened.
Int	Engine_setTrace (Engine_Handle engine, String mask)
	Set Server's trace mask.
Variables
Engine_Attrs	Engine_ATTRS
	Default engine attributes.

Define Documentation

#define CE_NULL_algs NULL

#define CE_DECLARE_TYPE	(	name,
		types
	)

Value:

\
static String typeTab_##name [] = {          \
    types,                                   \
    NULL                                     \
};                                           \
                                             \

Macros for runtime configuration. These macros can be used to create a static table of algorithms. However, the preferred method of building engine and alg tables, is to use the run-time APIs, Engine_add() and Engine_addAlg().

See also:: Engine_add(); Engine_addAlg() Declare an inheritanc hierarchy for an algorithm.

Parameters:

[in]	name	This is a symbol that will be associated with the `types` argument. It will be used to generate an internal variable name, so don't use the same name for two different calls to `CE_DECLARE_TYPE()`. `name` should be used in CE_LOCAL_ALG() to associate an alg to `types`.
[in]	types	This is a ';' separated string of inheritance hierarchies. It is used to identify the codec class of an algorithm. For example, the declaration: `CE_DECLARE_TYPE`(mydecoder, "ti.sdo.ce.speech1.ISPHDEC1") indicates that mydecoder (a name that will be used in CE_LOCAL_ALG() to declare a speech decoder), inherits the ti.sdo.ce.speech1.ISPHDEC1 interface.

Another example is the following: CE_DECLARE_TYPE(decoder, "ti.sdo.ce.video.IVIDDEC;ti.sdo.ce.test.xvideo.IVIDE") This says that the decoder inherits the ti.sdo.ce.test.xvideo.IVIDE interface, which in turn inherits the ti.sdo.ce.video.IVIDDEC interface.

Deprecated:: No need to use this macro when using CE_LOCAL_ALG2

See also:: CE_LOCAL_ALG2()

#define CE_LOCAL_ALG	(	name,
		algName,
		ialgFxns,
		idma3Fxns,
		iresFxns,
		groupId,
		memType
	)

Value:

\
    { algName,        /* name */             \
      {0},            /* uuid */             \
      ialgFxns,       /* ialgFxns */         \
      idma3Fxns,      /* idma3Fxns */        \
      typeTab_##name, /* typeTab */          \
      TRUE,           /* isLocal */          \
      groupId,        /* groupId */          \
      0,              /* protocol */         \
      iresFxns,       /* iresFxns */         \
      NULL,           /* stub/skel params */ \
      memType,        /* cached mem type */  \
      NULL,           /* type - typeTab[0] will be used instead */ \
    },

Generates a structure containing data for a local algorithm.

Parameters:

[in]	name	This symbol is used to associate the algorithm with one of the `types` passed to `CE_DECLARE_TYPE()`.
[in]	algName	This is the string name that the applicaion will use to create the algorithm, for example, "sphenc1_copy".
[in]	ialgFxns	The address of the IALG_Fxns table for the algorithm.
[in]	idma3Fxns	The address of the algorithm's IDMA3_Fxns table, if it has one, otherwise NULL.
[in]	iresFxns	If the algorithm uses IRES, the address of its IRES_Fxns table, otherwise NULL.
[in]	groupId	Scratch group Id of algorithm.
[in]	memType	The type of memory (cached, non-cached, or whatever the default is), to allocate for the algorithm. Choose from the following values for memType:

Engine_USECACHEDMEM_DEFAULT - default memory allocation Engine_USECACHEDMEM_NONCACHED - non-cached memory allocation Engine_USECACHEDMEM_CACHED - cached memory allocation

Example Usage:

      CE_BEGIN_ALG_TABLE(engineName)
          CE_LOCAL_ALG(name_1, ...)
          CE_LOCAL_ALG(name_2, ...)
          ...
          CE_LOCAL_ALG(name_n, ...)
      CE_END_ALG_TABLE(engineName)

Remarks:: This macro must be called between the CE_BEGIN_ALG_TABLE() and CE_END_ALG_TABLE() macro calls.

Deprecated:: Use CE_LOCAL_ALG2 instaead.

See also:: CE_DECLARE_TYPE; CE_BEGIN_ALG_TABLE

#define CE_LOCAL_ALG2	(	algName,
		ialgFxns,
		idma3Fxns,
		iresFxns,
		groupId,
		memType,
		types
	)

Value:

\
    { algName,        /* name */             \
      {0},            /* uuid */             \
      ialgFxns,       /* ialgFxns */         \
      idma3Fxns,      /* idma3Fxns */        \
      NULL,           /* typeTab */          \
      TRUE,           /* isLocal */          \
      groupId,        /* groupId */          \
      0,              /* protocol */         \
      iresFxns,       /* iresFxns */         \
      NULL,           /* stub/skel params */ \
      memType,        /* cached mem type */  \
      types,          /* types */            \
    },

Generates a structure containing data for a local algorithm. This macro takes a 'types' string as an argument to avoid having to use the CE_DECLARE_TYPES() macro call.

Parameters:

[in]	algName	This is the string name that the applicaion will use to create the algorithm, for example, "sphenc1_copy".
[in]	ialgFxns	The address of the IALG_Fxns table for the algorithm.
[in]	idma3Fxns	The address of the algorithm's IDMA3_Fxns table, if it has one, otherwise NULL.
[in]	iresFxns	If the algorithm uses IRES, the address of its IRES_Fxns table, otherwise NULL.
[in]	groupId	Scratch group Id of algorithm.
[in]	memType	The type of memory (cached, non-cached, or whatever the default is), to allocate for the algorithm. Choose from the following values for memType:

Engine_USECACHEDMEM_DEFAULT - default memory allocation Engine_USECACHEDMEM_NONCACHED - non-cached memory allocation Engine_USECACHEDMEM_CACHED - cached memory allocation

Parameters:

[in] types The ';' separated string of inheritance hierarchies. This must be constant in order to initialize the structure.

Example Usage:

      CE_BEGIN_ALG_TABLE(engineName)
          CE_LOCAL_ALG(name_1, ...)
          CE_LOCAL_ALG(name_2, ...)
          ...
          CE_LOCAL_ALG(name_n, ...)
      CE_END_ALG_TABLE(engineName)

Remarks:: This macro must be called between the CE_BEGIN_ALG_TABLE() and CE_END_ALG_TABLE() macro calls.

See also:: CE_DECLARE_TYPE; CE_BEGIN_ALG_TABLE

#define CE_DECLARE_LOCAL_ALG	(	name,
		algName,
		ialgFxns,
		idma3Fxns,
		iresFxns,
		groupId,
		memType,
		types
	)

Value:

static Engine_AlgDesc  name = \
                                             \
    { algName,        /* name */             \
      {0},            /* uuid */             \
      ialgFxns,       /* ialgFxns */         \
      idma3Fxns,      /* idma3Fxns */        \
      NULL,           /* typeTab */          \
      TRUE,           /* isLocal */          \
      groupId,        /* groupId */          \
      0,              /* protocol */         \
      iresFxns,       /* iresFxns */         \
      NULL,           /* stub/skel params */ \
      memType,        /* cached mem type */  \
      types,           /* type - typeTab[0] will be used instead */ \
    };

Generates a static variable of type Engine_AlgDesc. It is used in this manner:

Parameters:

[in]	name	The name to be given to the static Engine_AlgDesc variable.
[in]	algName	This is the string name that the applicaion will use to create the algorithm, for example, "sphenc1_copy".
[in]	ialgFxns	The address of the IALG_Fxns table for the algorithm.
[in]	idma3Fxns	The address of the algorithm's IDMA3_Fxns table, if it has one, otherwise NULL.
[in]	iresFxns	If the algorithm uses IRES, the address of its IRES_Fxns table, otherwise NULL.
[in]	groupId	Scratch group Id of algorithm.
[in]	memType	The type of memory (cached, non-cached, or whatever the default is), to allocate for the algorithm. Choose from the following values for memType:

Engine_USECACHEDMEM_DEFAULT - default memory allocation Engine_USECACHEDMEM_NONCACHED - non-cached memory allocation Engine_USECACHEDMEM_CACHED - cached memory allocation

Parameters:

[in] types The ';' separated string of inheritance hierarchies. This must be constant in order to initialize the structure.

Example Usage:

      CE_DECLARE_LOCAL_ALG(algName, )

      main()
      {
          ...
          status = Engine_addAlgDesc(engine, algName);
          ...
      }

#define CE_BEGIN_ALG_TABLE ( name ) static Engine_AlgDesc CE_##name##_algs[] = {

Use this macro and the CE_END_ALG_TABLE() macro around CE_LOCAL_ALG() to generate an algorithm table for an engine.

Parameters:

[in] name A symbol used to generate internal variable names. Use the same name in CE_END_ALG_TABLE(), and in the call to CE_ENGINE(), to associate an engine with this algorithm table.

Example Usage:

      CE_BEGIN_ALG_TABLE(engineAlgTab)
          CE_LOCAL_ALG(name_1, ...)
          CE_LOCAL_ALG(name_2, ...)
          ...
          CE_LOCAL_ALG(name_n, ...)
      CE_END_ALG_TABLE(engineAlgTab)

See also:: CE_END_ALG_TABLE(); CE_ENGINE()

#define CE_END_ALG_TABLE ( name )

Value:

{NULL},                    \
};

Use this macro after CE_BEGIN_ALG_TABLE() and CE_LOCAL_ALG() for generating an algorithm table for an engine.

Parameters:

[in] name This must be the same symbol name passed to the previous CE_BEGIN_ALG_TABLE() call.

Example Usage:

      CE_BEGIN_ALG_TABLE(engineAlgTab)
          CE_LOCAL_ALG(name_1, ...)
          CE_LOCAL_ALG(name_2, ...)
          ...
          CE_LOCAL_ALG(name_n, ...)
      CE_END_ALG_TABLE(engineAlgTab)

See also:: CE_BEGIN_ALG_TABLE; CE_ENGINE

#define CE_ENGINE	(	algTab,
		engName,
		serverName,
		memMap,
		useExtLoader,
		heapId
	)

Value:

{ engName,            /* engine name */                      \
      CE_##algTab##_algs, /* alg table */                        \
      serverName,         /* optional server name */             \
      NULL,               /* memMap */                           \
      0,                  /* useExtLoader */                     \
      0,                  /* # of algs (filled in at runtime) */ \
      heapId              /* heapId */                           \
    },

Generates a structure containing data for an engine.

Parameters:

[in]	algTab	Symbol to associate an alg table to this engine. Use the name passed to CE_BEGIN_ALG_TABLE() to associate that alg table with this engine.
[in]	engName	The name of the engine to open
[in]	serverName	The name of the Server image to load (if any). On SysLink-based systems, this is the name of a file and is passed unchanged to ProcMgr_Load().
[in]	memMap	The name of a memory map (if any). On SysLink-based systems, this file is used to map slave memory into the MMU using ProcMgr_map().
[in]	useExtLoader	Set to TRUE if an external loader will be used to load the server. If set to FALSE, Codec Engine will load the server when the Engine is opened.
[in]	heapId	Optional heap id to be used for this Engine. This is used internally, for example, by Comm_alloc(). Use a value of 0 for heapId as the default.

Remarks:: This macro must be called between the CE_BEGIN_ENGINE_TABLE() and CE_END_ENGINE_TABLE() macro calls.

Example Usage:

      CE_BEGIN_ENGINE_TABLE(name)
          CE_ENGINE(algTab_0, "engine_0", NULL, 0)
          CE_ENGINE(algTab_1, "engine_1", "server.x64P", 0)
      CE_END_ENGINE_TABLE(name)

See also:: CE_BEGIN_ALG_TABLE; CE_BEGIN_ENGINE_TABLE

#define CE_BEGIN_ENGINE_TABLE ( name )

Value:

static Engine_AlgDesc _localAlgs_000[] = {    \
    {NULL},                                   \
};                                            \
                                              \
static Engine_Desc name##_000[] = {

Use this macro and the CE_END_ENGINE_TABLE() macro around CE_ENGINE() to generate an engine table for the application.

The usage is: CE_BEGIN_ENGINE_TABLE(name) CE_ENGINE(algTab_1, ...) CE_ENGINE(algTab_2, ...) ... CE_ENGINE(algTab_n, ...) CE_END_ENGINE_TABLE(name)

Parameters:

[in] name A symbol used to generate internal variable names. Use the same name in CE_END_ENGINE_TABLE().

See also:: CE_END_ENGINE_TABLE; CE_ENGINE

#define CE_END_ENGINE_TABLE ( name )

Value:

{"local",                                 \
     _localAlgs_000,                          \
     NULL,                                    \
     NULL,                                    \
     0,                                       \
    },                                        \
    {NULL, NULL, NULL, NULL, 0}               \
};                                            \
                                              \
Engine_Config Engine_config = {               \
    name##_000,                               \
    "local"                                   \
};

Use this macro and the CE_BEGIN_ENGINE_TABLE() macro around CE_ENGINE() to generate an engine table for the application.

The usage is: CE_BEGIN_ENGINE_TABLE(name) CE_ENGINE(algTab_1, ...) CE_ENGINE(algTab_2, ...) ... CE_ENGINE(algTab_n, ...) CE_END_ENGINE_TABLE(name)

Parameters:

[in] name A symbol used to generate internal variable names. Use the same name in CE_BEGIN_ENGINE_TABLE().

See also:: CE_BEGIN_ENGINE_TABLE; CE_ENGINE

#define Engine_MODNAME "ti.sdo.ce.Engine"

Name to pass to Diags_setMask() to enable logging for Engine functions.

Example Usage:

The following code turns on all Log statements in the Engine module.

     Diags_setMask(Engine_MODNAME "+EX1234567");

Remarks:: Using Diags_setMask() to enable Engine Logging must be called after CERuntime_init() (which creates and initializes the Engine trace mask) to have any effect.

#define Engine_EOK 0

Success.

#define Engine_EEXIST 1

Name does not exist.

#define Engine_ENOMEM 2

Unable to allocate memory.

#define Engine_EDSPLOAD 3

Unable to load the DSP.

#define Engine_ENOCOMM 4

Unable to create a comm connection to the DSP.

#define Engine_ENOSERVER 5

Unable to locate the server on the DSP.

#define Engine_ECOMALLOC 6

Unable to allocate communication buffer.

#define Engine_ERUNTIME 7

Internal engine runtime failure.

#define Engine_ECODECCREATE 8

Creation of the Codec failed.

#define Engine_ECODECSTART 9

Start of the Codec failed. For codecs which are implemented as a thread, this implies that the codec thread of execution failed to start.

#define Engine_EINVAL 10

Bad paramater passed to method.

#define Engine_EBADSERVER 11

Incompatible server specified.

#define Engine_ENOTAVAIL 12

Service not available.

#define Engine_EWRONGSTATE 13

Call can not be made at this time.

#define Engine_EINUSE 14

Call can't be made at this time because a required name/resource is in use.

#define Engine_ENOTFOUND 15

Entity was not found.

#define Engine_ETIMEOUT 16

Timeout-based operation timed out.

#define Engine_GETALGDESCFXN "GetEngineAlgDesc"

Name of function that a dynamically loaded codec must supply.

Typedef Documentation

typedef struct Engine_Obj* Engine_Handle

Opaque handle to an engine.

typedef Int Engine_Error

Engine error code.

typedef struct Engine_Attrs Engine_Attrs

Attributes of an Engine.

See also:: Engine_initAttrs().; Engine_open().

typedef struct Engine_AlgInfo Engine_AlgInfo

Properties of an Engine algorithm.

See also:: Engine_getAlgInfo()

typedef struct Engine_AlgInfo2 Engine_AlgInfo2

Properties of an Engine algorithm.

Remarks:: This structure is identical to Engine_AlgInfo except that the typeTab array of strings is replaced by a single string called types. The string, types, represents a ';' separated list of inheritance hierarchies of the algorithm, for example, "ti.sdo.ce.video.IVIDDEC;ti.sdo.ce.test.xvideo.IVIDE".

See also:: Engine_getAlgInfo2()

typedef enum Engine_CachedMemType Engine_CachedMemType

Engine Cacheable Memory types.

Remarks:: This enumeration data type should not be used for storage, but rather only for its constant values.

typedef struct Engine_AlgDesc Engine_AlgDesc

Descriptor for an alg. This object can be passed to Engine_addAlg(), to dynamically add an alg to an engine.

See also:: Engine_initAlgDesc(); Engine_addAlg()

typedef struct Engine_DllAlgDesc Engine_DllAlgDesc

Descriptor for a dynamically loaded alg. A dynamic library for a codec must export a function that fills in a structure of this type.

See also:: Engine_GetAlgDescFxn

typedef Int(* Engine_GetAlgDescFxn)(Engine_DllAlgDesc *dllAlgDesc)

Prototype of function that must be supplied by a dynamic codec library to fill in a Engine_DllAlgDesc structure.

Remarks:: This function will be called by Engine_addAlg() to fill in the dynamic codec's descriptor.

See also:: Engine_DllAlgDesc

typedef struct Engine_Desc Engine_Desc

This structure is passed to Engine_add(), and contains parameters to specify an engine.

See also:: Engine_add(); Engine_open()

Enumeration Type Documentation

enum Engine_CachedMemType

Engine Cacheable Memory types.

Remarks:: This enumeration data type should not be used for storage, but rather only for its constant values.

Enumerator:

Engine_USECACHEDMEM_DEFAULT	Use default cache setting
Engine_USECACHEDMEM_NONCACHED	Use non-cached memory
Engine_USECACHEDMEM_CACHED	Use cached memory

Function Documentation

Void CERuntime_exit ( Void )

Exit the Codec Engine Runtime.

Remarks:: This function finalizes the Codec Engine modules used in the current configuration.

See also:: CERuntime_init()

Void CERuntime_init ( Void )

Initialize the Codec Engine Runtime.

Remarks:: This function must be called prior to using any Codec Engine APIs; it initializes all Codec Engine modules used in the the current configuration.; Note that this must be called for both applications and [if applicable] Servers.; For Servers, this is typically called from main().

Precondition:: For Servers, Ipc_start() must be called prior to calling CERuntime_init(). See the examples' main() implementation for reference.

See also:: CERuntime_exit()

Engine_Error Engine_addStubFxns	(	String	fxnsName,
		IALG_Fxns *	fxns
	)

Register stub functions through which a remote algorithm can be called.

Parameters:

[in]	fxnsName	The name of the stub function table (e.g. "UNIVERSAL_STUBS")
[in]	fxns	Address of stub function table (e.g. &UNIVERSAL_STUBS)

Precondition:: As with all Codec Engine API's, CERuntime_init() must have previously been called.

Remarks:

This service is not necessary if you configure your Engine at build/config time using Engine.createFromServer(). When using Engine.createFromServer(), the appropriate alg-specific stubs are added to the system automatically.

When on an RTOS (e.g. SYS/BIOS), the stubs registered are available to all Engines in the system. When on a HLOS (e.g. Linux, WinCE), the stubs registered are available to all Engines in the calling application's process.

The symbol passed to the fxns argument can often be found in the class-specific VISA header file (e.g. UNIVERSAL_STUBS is declared in ti/sdo/ce/universal/universal.h).

For example, to register "UNIVERSAL_STUBS" for use by an IUNIVERSAL-compliant algorithm at runtime, you can do the following:

      #include <ti/sdo/ce/Engine.h>
      #include <ti/sdo/ce/universal/universal.h>

      Engine_register("UNIVERSAL_STUBS",
              (IALG_Fxns *)&UNIVERSAL_STUBS);

Return values:

Engine_EOK	Success.
Engine_ENOMEM	Memory allocation failed.

See also:: Engine_open()

Engine_Error Engine_add ( Engine_Desc * pDesc )

Add an Engine to the database of engines that can be opened with Engine_open()

Parameters:

[in] pDesc The handle of an Engine Descriptor object. Before setting the fields of pDesc, it must first be initialized with Engine_initDesc().

Return values:

Engine_EINVAL	Bad parameter passed, such as `pDesc` = NULL, or `pDesc->name` = NULL.
Engine_EINUSE	An engine with the name `pDesc->name` already exists.
Engine_ENOMEM	A memory allocation failed.
Engine_EOK	Success.

Precondition:: As with all Codec Engine API's, CERuntime_init() must have previously been called.

Postcondition:: If the return value is Engine_EOK, Engine_open() can be called with pDesc->name.

Example Usage:

      #include <ti/sdo/ce/Engine.h>

      Engine_Desc desc;

      Engine_initDesc(&desc);

      desc.name = "myEngine";
      desc.remoteName = "myServer.x64P";
      Engine_add(&desc);

See also:: Engine_remove(); Engine_open()

Engine_Error Engine_addAlg	(	String	name,
		Engine_Handle	engine,
		String	location,
		Engine_AlgDesc *	pAlgDesc
	)

Dynamically add an algorithm to an Engine.

Remarks:: If the Engine has not been opened, the name of the Engine is used, otherwise, a handle to the opened Engine. If the Engine has been opened, the added alg will only be accessible to the caller of this function. Either one or the other, but not both, of name and engine should be non-NULL.

Parameters:

[in]	name	The name of the engine. `name` is specified in the engine configuration, or the name of an engine added with `Engine_add()`. This can only be non-NULL if the engine is not opened, otherwise, use an engine handle and set `name` to NULL.
[in]	engine	The handle of an engine returned by Engine_open(). If `engine` is non-NULL, set `name` to NULL.
[in]	location	String identifying the location of the algorithm. Often this is a file name, but for systems without a file system, it may be a system-specific string identifier. This may be NULL if the algorithm is built into the executable.
[in]	pAlgDesc	Parameters describing the algorithm being added. Before setting the fields of this structure, it should first be initialized with `Engine_initAlgDesc()`, to set all fields to default values. If location is non-NULL (a dynamic library), then the following fields of pAlgDesc must be specified: pAlgDesc->name pAlgDesc->isLocal pAlgDesc->groupId All other Engine_AlgDesc fields will be from the dynamic library. If location is NULL (not a dynamic library), the user must set the following fields of pAlgDesc: pAlgDesc->name pAlgDesc->fxns pAlgDesc->idmaFxns, if applicable pAlgDesc->iresFxns, if applicable pAlgDesc->isLocal pAlgDesc->groupId pAlgDesc->types

Precondition:: As with all Codec Engine API's, CERuntime_init() must have previously been called.; engine is a valid (non-NULL) engine handle which is in the open state.

Remarks:: If there is an existing algorithm in the engine already named name, an error will be returned.

Return values:

Engine_EOK	Success.
Engine_EINUSE	The Engine `name` is non-NULL, and the Engine is open.
Engine_EINVAL	`pAlgDesc` or `pAlgDesc->name` is NULL.
Engine_EINVAL	Both `name` and `engine` are NULL. Ensure one of these is non-NULL.
Engine_EINVAL	Both `name` and `engine` are non-NULL. Ensure that one of these is NULL.
Engine_EEXIST	There is no engine with the given name.
Engine_EINUSE	The name of the alg in `pAlgDesc->name` is already in use.

Example Usage:

      #include <ti/sdo/ce/Engine.h>

      Engine_AlgDesc desc;

      Engine_initAlgDesc(&desc);

      desc.groupId = 2;
      desc.isLocal = TRUE;
      desc.fxns = &UNIVERSALCOPY_TI_IUNIVERSALCOPY;
      desc.idmaFxns = NULL;
      desc.iresFxns = NULL;
      desc.memType = Engine_USECACHEDMEM_DEFAULT;
      desc.types = UNIVERSAL_VISATYPE;

      status = Engine_addAlg("myEngine", NULL, NULL, &desc);

See also:: Engine_initAlgDesc(); Engine_open(); Engine_removeAlg()

Engine_Error Engine_removeAlg	(	String	name,
		Engine_Handle	engine,
		String	algName
	)

Dynamically remove an algorithm that was added to an Engine with Engine_addAlg().

Remarks:: The same values of the parameters name and engine that were passed to Engine_addAlg() should be used here. In particular, if name was used to add the alg, all handles to the engine must be closed before calling Engine_removeAlg().

Parameters:

[in]	name	The name of the engine or NULL, that was passed to Engine_addAlg().
[in]	engine	The handle to an engine, previously acquired by a call to Engine_open(), or NULL, that was used in Engine_addAlg().
[in]	algName	Name of the algorithm to remove.

Return values:

Engine_EOK	Success.
Engine_EEXIST	The engine `name` does not exist.
Engine_ENOTFOUND	`algName` could not be found in `engine`.
Engine_EINUSE	The Engine `name` is still open.

See also:: Engine_open(); Engine_addAlg()

Void Engine_close ( Engine_Handle engine )

Close an Engine.

Parameters:

[in] engine The handle to an engine, previously acquired by a call to Engine_open().

Precondition:: engine must not be referenced by any algorithm instance objects; i.e., you must first delete all algorithm instances associated with engine before closing it.; engine is a valid (non-NULL) engine handle which is in the open state.

See also:: Engine_open()

Void Engine_initAlgDesc ( Engine_AlgDesc * pAlgDesc )

Initialize an Engine_AlgDesc structure with default values.

Parameters:

[in] pAlgDesc Location of Engine_AlgDesc object to initialize. The fields of pAlgDesc will be set to the following:

pAlgDesc->name = NULL; pAlgDesc->uuid.data = 0; pAlgDesc->fxns = NULL; pAlgDesc->idmaFxns = NULL; pAlgDesc->typeTab = NULL; pAlgDesc->isLocal = TRUE; pAlgDesc->groupId = 0; pAlgDesc->rpcProtocolVersion = 0; pAlgDesc->iresFxns = NULL; pAlgDesc->codecClassConfig = NULL; pAlgDesc->memType = Engine_USECACHEDMEM_DEFAULT; pAlgDesc->types = NULL;

See also:: Engine_addAlg()

Void Engine_initAttrs ( Engine_Attrs * pAttrs )

Initialize an Engine_Attrs structure with default values.

Parameters:

[in] pAttrs Location of Engine_Attrs object to initialize.

See also:: Engine_open()

Void Engine_initDesc ( Engine_Desc * pDesc )

Initialize an Engine_Desc structure with default values.

Parameters:

[in] pDesc Location of Engine_Desc object to initialize. The fields of pDesc will be set to the following:

pDesc->name = NULL; pDesc->remoteName = NULL; pDesc->heapId = 0;

See also:: Engine_add()

Engine_Handle Engine_open	(	String	name,
		Engine_Attrs *	attrs,
		Engine_Error *	ec
	)

Open an Engine.

The handle returned may be used to create one or more instances of an algorithm contained in the specified Engine.

An Engine may be opened more than once; each open returns a unique handle that can be used to create algorithm instances or get status of the Engine.

Engine handles must not be concurrently accessed by multiple threads; each thread must either obtain its own handle (via Engine_open()) or explicitly serialize access to a shared handle.

Parameters:

[in]	name	The name of the engine to open. `name` is specified in the engine configuration.
[in]	attrs	Attributes for the open engine.
[out]	ec	Optional output error code

Return values:

NULL	An error has occurred.
non-NULL	The handle to the opened engine.

Precondition:: name is a non-NULL string.; name is a valid, pre-configured name of an engine.; As with all Codec Engine API's, CERuntime_init() must have previously been called.

Postcondition:

If the return handle is NULL and ec is non-NULL, *ec is set to a non-zero value indicating the cause of the failure.

If ec is non-NULL, the Engine_Error value is set to one of the following values:

Engine_EOK success
Engine_EEXIST name does not exist
Engine_ENOMEM can't allocate memory
Engine_EDSPLOAD can't load the DSP
Engine_ENOCOMM can't create a comm connection to DSP
Engine_ENOSERVER can't locate the server on the DSP
Engine_ECOMALLOC can't allocate communication buffer

See also:: Engine_close(); Engine_add(); Engine_remove()

Int Engine_fwriteTrace	(	Engine_Handle	engine,
		String	prefix,
		FILE *	out
	)

Write Server's trace buffer to specifed file stream.

Parameters:

[in]	engine	The handle to the opened engine.
[in]	prefix	A string to prepend to each line output; this allows one to easily identify trace from the server from the application's trace, for example.
[in]	out	A open FILE stream used to output the Server's trace characters.

Return values:

Integer number of characters copied to the specified FILE stream.

Precondition:: engine is a valid (non-NULL) engine handle and the engine is in the open state.

Postcondition:

In the event a negative value is returned, Engine_getLastError() will return one of the following values:

Engine_ERUNTIME Either an internal runtime error occured or the underlying server error occured.
Engine_EINUSE Server trace resource is already in use.

Engine_Error Engine_getAlgInfo	(	String	name,
		Engine_AlgInfo *	algInfo,
		Int	index
	)

Get details of an algorithm configured into an engine.

Parameters:

[in]	name	The name of the engine. `name` is specified in the engine configuration.
[out]	algInfo	Structure to store algorithm details. The `algInfoSize` field of this structure must be set to `sizeof(Engine_AlgInfo)` by the application.
[out]	index	The index of the algorithm to get the information.

Return values:

Engine_EOK	Success.
Engine_EEXIST	There is no engine with the given name.
Engine_ENOTFOUND	`index` is greater than or equal to the total number of algorithms configured for the engine, or `index` < 0.
Engine_EINVAL	The value of `algInfoSize` passed to this function does not match the CE library's `sizeof(Engine_AlgInfo)`.

Precondition:: name is a non-NULL string.; algInfo is non-NULL.; As with all Codec Engine API's, CERuntime_init() must have previously been called.

Postcondition:: If name is a valid engine name and 0 <= index < the total number of algorithms configured for the engine, then algInfo will contain the information for the engine's ith (i = index) algorithm.

See also:: Engine_getNumAlgs()

Engine_Error Engine_getAlgInfo2	(	String	name,
		Engine_Handle	engine,
		Engine_AlgInfo2 *	algInfo2,
		Int	index
	)

Get details of an algorithm.

Parameters:

[in]	name	The name of the engine. `name` is specified in the engine configuration. This may be NULL if `engine` contains a valid engine handle.
[in]	engine	The handle of an engine returned by Engine_open(). If this is NULL, only information for a static alg can be obtained.
[out]	algInfo2	Structure to store algorithm details. The `algInfoSize` field of this structure must be set to `sizeof(Engine_AlgInfo2)` by the application.
[out]	index	The index of the algorithm to get the information.

Return values:

Engine_EOK	Success.
Engine_EEXIST	There is no engine with the given name.
Engine_ENOTFOUND	`index` is greater than or equal to the total number of algorithms configured for the engine, or `index` < 0.
Engine_EINVAL	The value of `algInfoSize` passed to this function does not match the CE library's `sizeof(Engine_AlgInfo2)`.

Precondition:: name is a non-NULL string or engine is non-NULL.; algInfo2 is non-NULL.; As with all Codec Engine API's, CERuntime_init() must have previously been called.

Postcondition:: If name is a valid engine name and 0 <= index < the total number of algorithms configured for the engine, then algInfo2 will contain the information for the engine's ith (i = index) algorithm.

Remarks:: This service supports algorithms statically configured into an Engine at build/config time, or algorithms that have been dynamically added to an opened engine. If the Engine has not been opened yet, the name of the Engine is used to get the statically configured alg. If the Engine has been opened, the Engine handle can be used to get either information for a statically configured alg, or a remote alg that was added when the server was queried during Engine_open().

See also:: Engine_getNumAlgs2().

Engine_Error Engine_getDesc	(	String	name,
		Engine_Desc *	desc
	)

Fill in an Engine_Desc structure with the values of the Engine descriptor for an Engine.

Parameters:

[in]	name	The name of the Engine. `name` is specified in the engine configuration or a a name that was passed to `Engine_add()`.
[out]	desc	The structure where the descriptor of the Engine specified by `name` will be copied to.

Return values:

Engine_EOK	Success.
Engine_EEXIST	There is no engine with the given name.

Precondition:: name is a non-NULL string.; desc is non-NULL.; As with all Codec Engine API's, CERuntime_init() must have previously been called.

Postcondition:: If name is a valid engine name, then desc will contain the descriptor of the engine name.

See also:: Engine_setDesc().

Engine_Error Engine_getLastError ( Engine_Handle engine )

Get error code of the last failed operation.

Parameters:

[in] engine The handle to the opened engine.

Return values:

error code (Engine_Error) of the last failed engine operation.

Precondition:: As with all Codec Engine API's, CERuntime_init() must have previously been called.; engine is a valid (non-NULL) engine handle and the engine is in the open state.

String Engine_getName ( Engine_Handle engine )

Get the name of an opened engine.

Parameters:

[in] engine The handle to the opened engine.

Precondition:: As with all Codec Engine API's, CERuntime_init() must have previously been called.

Return values:

NULL	An error has occurred.
non-NULL	The name of the opened engine.

Engine_Error Engine_getNumAlgs	(	String	name,
		Int *	numAlgs
	)

Get the number of algorithms configured into an Engine.

Parameters:

[in]	name	The name of the Engine. `name` is specified in the engine configuration.
[out]	numAlgs	The number of algorithms that are configured in the given engine.

Return values:

Engine_EOK	Success.
Engine_EEXIST	There is no engine with the given name.

Precondition:: name is a non-NULL string.; numAlgs is non-NULL.; As with all Codec Engine API's, CERuntime_init() must have previously been called.

Postcondition:: If name is a valid engine name, then numAlgs will contain the number of algorithms configured for the given engine.

See also:: Engine_getAlgs().

Engine_Error Engine_getNumAlgs2	(	String	name,
		Engine_Handle	engine,
		Int *	numAlgs
	)

Get the number of algorithms statically configured into an engine or the total number of algorithms both statically configured and dynamically added through server information when the engine was opened.

Parameters:

[in]	name	The name of the engine. `name` is specified in the engine configuration. `name` can be NULL, if `engine` is a valid Engine_Handle.
[in]	engine	The handle of an engine returned by Engine_open(). If `engine` is NULL, `name` must be non-NULL, and only the number of statically configured algorithms will be returned in `numAlgs`. specified in the engine configuration.
[out]	numAlgs	The number of algorithms that are configured in the given engine.

Return values:

Engine_EOK	Success.
Engine_EEXIST	There is no engine with the given name.

Precondition:: name is a non-NULL string or engine is non-NULL.; numAlgs is non-NULL.; As with all Codec Engine API's, CERuntime_init() must have previously been called.

Postcondition:: If name is a valid engine name, then numAlgs will contain the number of algorithms configured for the given engine.

Remarks:: If the engine has a server, but was not configured with Engine.createFromServer() number of remote algorithms (if any) that were statically configured into the engine, will be counted twice: once for the static alg table, and once for the information queried from the server.

See also:: Engine_getAlgs().

Server_Handle Engine_getServer ( Engine_Handle engine )

Get handle to an Engine's Server.

This function returns the handle to an Engines server, that can be used with Server APIs to obtain information from and control the remote DSP server.

Parameters:

[in] engine The handle to the opened engine.

Return values:

Handle to engine's server.

Precondition:: As with all Codec Engine API's, CERuntime_init() must have previously been called.; engine is a valid (non-NULL) engine handle and the engine is in the open state.

UInt32 Engine_getUsedMem ( Engine_Handle engine )

Get Server's total memory usage.

Deprecated:: This service has been replaced by Server_getMemStat() to better indicate that this API is not intended for obtaining the current processor's memory statistics, rather it obtains the memory statistics of a remote Server. Also, Server_getMemStat() provides more granularity than Engine_getUsedMem().

Parameters:

[in] engine The handle to the opened engine.

Return values:

Total amount of used memory (in MAUs). If the amount is not available, 0 is returned and the reason can be retrieved via Engine_getLastError().

Precondition:: As with all Codec Engine API's, CERuntime_init() must have previously been called.; engine is a valid (non-NULL) engine handle and the engine is in the open state.

Postcondition:

in the event that 0 is returned, Engine_getLastError() will return one of the following values:

Engine_ERUNTIME Either an internal runtime error occured or the underlying server error occured.
Engine_ENOTAVAIL The memory usage can not be computed.

Engine_Error Engine_remove ( String engineName )

Remove an engine from the list of engines that can be opened.

Parameters:

[in] engineName The name of the engine to be removed.

Precondition:: As with all Codec Engine API's, CERuntime_init() must have previously been called.; engineName is non-NULL.

Return values:

Engine_EINUSE	The engine cannot be removed because an instance of it is still opened.
Engine_EEXIST	No engine by this name exists.
Engine_EOK	Success.

See also:: Engine_add()

Engine_Error Engine_setDesc	(	String	name,
		Engine_Desc *	desc
	)

Set values for an Engine's descriptor. This function should only be called when the Engine has not yet been opened.

Parameters:

[in]	name	The name of the Engine. `name` is specified in the engine configuration or a a name that was passed to `Engine_add()`.
[in]	desc	The structure where descriptor values for the Engine specified by `name` will be copied from.

Return values:

Engine_EOK	Success.
Engine_EEXIST	There is no engine with the given name.
Engine_EINUSE	The Engine `name` has already been opened.

Precondition:: name is a non-NULL string.; desc is non-NULL.; As with all Codec Engine API's, CERuntime_init() must have previously been called.

Postcondition:: If name is a valid engine name, then the desscriptor for the engine name will have been updated with values from desc.

Remarks:: Use Engine_getDesc() to fill in the descriptor, override the fields you want to change, and then pass the descriptor to Engine_setDesc(). Only the following fields of the Engine_Desc are allowed to be modified: memMap useExtLoader heapId

See also:: Engine_getDesc().

Int Engine_setTrace	(	Engine_Handle	engine,
		String	mask
	)

Set Server's trace mask.

Parameters:

[in]	engine	The handle to the opened engine.
[in]	mask	Trace mask, e.g. "*=01234567"

Return values:

Engine_ENOSERVER	No server for this engine.
Engine_EINUSE	Trace resource is already in use.
Engine_ERUNTIME	Internal runtime error has occurred.

Precondition:: As with all Codec Engine API's, CERuntime_init() must have previously been called.; engine is a valid (non-NULL) engine handle and the engine is in the open state.

Remarks:: This only sets the trace for a remote server. To change the trace mask for the application-side of the framework, use Diags_setMask(), or Diags_setMaskMeta().

See also:: xdc.runtime.Diags

Variable Documentation

Engine_Attrs Engine_ATTRS

Default engine attributes.

Deprecated:: Engine_ATTRS is no longer recommended. Please use Engine_initAttrs() instead.

See also:: Engine_initAttrs() Default attrs.

Codec Engine Runtime

Data Structures

Defines

Typedefs

Enumerations

Functions

Variables

Define Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation

Variable Documentation