Data Structures
struct	Engine_Attrs
	Attributes of an Engine. More...
struct	Engine_AlgInfo
	Properties of an Engine algorithm. More...
struct	Engine_DllAlgDesc
	Discriptor for a dynamically loaded codec. A dynamic library for a codec must export a function that fills in a structure of this type. More...
struct	Engine_DllAlgParams
	This structure is passed to `Engine_addAlg()`, and contains parameters to create a dynamic codec with. More...
Defines
#define	Engine_MODNAME "ti.sdo.ce.Engine"
	Name to pass to Diags_setMask() to enable logging for Engine functions. For example, Diags_setMask(Engine_MODNAME"+EX1234567"); turns on all Log statements in this module. Diags_setMask() must be called after initialization to take effect.
#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_DllAlgDesc	Engine_DllAlgDesc
	Discriptor for a dynamically loaded codec. 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_DllAlgParams	Engine_DllAlgParams
	This structure is passed to `Engine_addAlg()`, and contains parameters to create a dynamic codec with.
Functions
Void	CERuntime_exit (Void)
	Exit the Codec Engine Runtime.
Void	CERuntime_init (Void)
	Initialize the Codec Engine Runtime.
Engine_Error	Engine_add (String engineName, String remoteName)
	Add an Engine to the database of engines that can be opened with Engine_open()
Engine_Error	Engine_addAlg (Engine_Handle engine, String location, Engine_DllAlgParams *pAlgParams)
	Dynamically add an algorithm to an Engine instance.
Engine_Error	Engine_removeAlg (Engine_Handle engine, String name)
	Dynamically remove an algorithm from an Engine instance.
Void	Engine_close (Engine_Handle engine)
	Close an Engine.
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.
Int	Engine_getCpuLoad (Engine_Handle engine)
	Get Server's cpu usage in percent.
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.
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.
Int	Engine_setTrace (Engine_Handle engine, String mask)
	Set Server's trace mask.
Variables
Engine_Attrs	Engine_ATTRS
	Default engine attributes.

Define Documentation

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

Name to pass to Diags_setMask() to enable logging for Engine functions. For example, Diags_setMask(Engine_MODNAME"+EX1234567"); turns on all Log statements in this module. Diags_setMask() must be called after initialization to take 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_open() and Engine_ATTRS.

typedef struct Engine_AlgInfo Engine_AlgInfo

Properties of an Engine algorithm.

See also:: Engine_getAlgInfo()

typedef struct Engine_DllAlgDesc Engine_DllAlgDesc

Discriptor for a dynamically loaded codec. 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_DllAlgParams Engine_DllAlgParams

This structure is passed to Engine_addAlg(), and contains parameters to create a dynamic codec with.

See also:: Engine_addAlg().

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.

See also:: CERuntime_exit()

Engine_Error Engine_add	(	String	engineName,
		String	remoteName
	)

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

Parameters:

[in]	engineName	The name of the engine to create. This must not be NULL.
[in]	remoteName	The name of the remote server to load (if any).

Return values:

Engine_EINVAL	Bad parameter passed.
Engine_EINUSE	An engine with the given 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 engineName.

See also:: Engine_remove()

Engine_Error Engine_addAlg	(	Engine_Handle	engine,
		String	location,
		Engine_DllAlgParams *	pAlgParams
	)

Dynamically add an algorithm to an Engine instance.

Parameters:

[in]	engine	The handle to an engine, previously acquired by a call to Engine_open().
[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.
[in]	pAlgParams	Parameters describing the algorithm being added.

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

Remarks:: This API is not yet supported.; If there is an existing algorithm in the engine already named name, an error will be returned.

Return values:

Engine_EOK	Success.
Engine_EINUSE	`attrs.name` is in use.

See also:: Engine_open(); Engine_removeAlg()

Engine_Error Engine_removeAlg	(	Engine_Handle	engine,
		String	name
	)

Dynamically remove an algorithm from an Engine instance.

Parameters:

[in]	engine	The handle to an engine, previously acquired by a call to Engine_open().
[in]	name	Name of the algorithm to remove.

Remarks:: This API is not yet supported.

Return values:

Engine_EOK	Success.
Engine_ENOTFOUND	`name` could not be found in `engine`.

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.

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

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

Int Engine_getCpuLoad ( Engine_Handle engine )

Get Server's cpu usage in percent.

Deprecated:: This service has been replaced by Server_getCpuLoad() to better indicate that this API is not intended for obtaining the current processor's CPU load, rather it obtains the CPU load of a remote Server.

Parameters:

[in] engine The handle to the opened engine.

Return values:

integer between 0-100 indicating percentage of time the Server is processing measured over a period of approximately 1 second. If the load is unavailable, a negative value is returned.

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_ENOTAVAIL The CPU load can not be computed.

See also:: Server_getCpuLoad()

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:: 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.

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

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

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:: 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.

Default attrs.

Codec Engine Runtime

Data Structures

Defines

Typedefs

Functions

Variables

Define Documentation

Typedef Documentation

Function Documentation

Variable Documentation