Codec Engine Server Interface

Data Structures

struct  Server_AlgInfo
 Properties of a Server algorithm. More...
struct  Server_MemStat
 Information for a memory heap of a remote DSP server. More...

Defines

#define Server_GTNAME   "CS"
 Trace name for the Server module.
#define Server_MAXSEGNAMELENGTH   32
 Maximum number of characters used in memory segment names.

Typedefs

typedef struct Server_Obj * Server_Handle
 Opaque handle to the server for an engine.

Enumerations

enum  Server_Status {
  Server_EOK = 0,
  Server_ENOSERVER = 1,
  Server_ENOMEM = 2,
  Server_ERUNTIME = 3,
  Server_EINVAL = 4,
  Server_EWRONGSTATE = 5,
  Server_EINUSE = 6,
  Server_ENOTFOUND = 7,
  Server_EFAIL = 8
}
 

Server error code.

More...

Functions

Server_Status Server_connectTrace (Server_Handle server, Int *token)
 Connect to server for purposes of collecting trace and/or LOG data.
Server_Status Server_disconnectTrace (Server_Handle server, Int token)
 Disconnect from server when finished collecting trace and/or LOG data.
Int Server_fwriteTrace (Server_Handle server, String prefix, FILE *out)
 Write Server's trace buffer to specifed file stream.
Int Server_getAlgInfo (Server_Handle server, Int algNum, Server_AlgInfo *algInfo)
 Get information about an algorithm on the remote server.
Int Server_getCpuLoad (Server_Handle server)
 Get Server's CPU usage in percent.
Server_Status Server_getMemStat (Server_Handle server, Int segNum, Server_MemStat *memStat)
 Get information on a memory heap segment of a remote DSP server.
Server_Status Server_getNumAlgs (Server_Handle server, Int *numAlgs)
 Get the number of codecs on the remote DSP server.
Server_Status Server_getNumMemSegs (Server_Handle server, Int *numSegs)
 Get the number of memory heap segments of a remote DSP server.
Server_Status Server_redefineHeap (Server_Handle server, String name, Uint32 base, Uint32 size)
 Set the base address and size of a remote DSP server heap.
Server_Status Server_restoreHeap (Server_Handle server, String name)
 Set the base address and size of a remote DSP server heap back to their original values.
Int Server_setTrace (Server_Handle server, String mask)
 Set Server's trace mask.

Define Documentation

#define Server_GTNAME   "CS"

Trace name for the Server module.

#define Server_MAXSEGNAMELENGTH   32

Maximum number of characters used in memory segment names.


Typedef Documentation

typedef struct Server_Obj* Server_Handle

Opaque handle to the server for an engine.


Enumeration Type Documentation

Server error code.

Enumerator:
Server_EOK 

Success.

Server_ENOSERVER 

Engine has no server.

Server_ENOMEM 

Unable to allocate memory.

Server_ERUNTIME 

Internal runtime failure.

Server_EINVAL 

Bad value passed to function.

Server_EWRONGSTATE 

Server is not in the correct state to execute the requested function.

Server_EINUSE 

Server call did not succeed because a because a required resource is in use.

Server_ENOTFOUND 

An entity was not found

Server_EFAIL 

Unknown failure


Function Documentation

Server_Status Server_connectTrace ( Server_Handle  server,
Int *  token 
)

Connect to server for purposes of collecting trace and/or LOG data.

Parameters:
[in] server Server handle obtained from Engine_getServer().
[in] token Address to store connection token. This token should be specified in the companion call to Server_disconnectTrace().
Return values:
Server_EOK Success, trace token was acquired.
Server_EINUSE A connection for server trace is already established.
Server_ERUNTIME An internal runtime error occurred.
Precondition:
server is non-NULL.
token is non-NULL.
See also:
Server_disconnectTrace().
Server_Status Server_disconnectTrace ( Server_Handle  server,
Int  token 
)

Disconnect from server when finished collecting trace and/or LOG data.

Parameters:
[in] server Server handle obtained from Engine_getServer().
[in] token Connection token (as obtained from earlier, companion call to Server_connectTrace()).
Return values:
Server_EOK Success.
Server_ERUNTIME An internal runtime error occurred.
Precondition:
server is non-NULL.
See also:
Server_connectTrace().
Int Server_fwriteTrace ( Server_Handle  server,
String  prefix,
FILE *  out 
)

Write Server's trace buffer to specifed file stream.

Parameters:
[in] server Server handle, obtained from Engine_getServer().
[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 An open FILE stream used to output the Server's trace characters.
Return values:
Integer number of characters copied to the specified FILE stream.
Precondition:
server is non-NULL.
Corresponding engine is in the open state.
Postcondition:
In the event a negative value is returned, Engine_getLastError() will return the value:
  • Engine_ERUNTIME Either an internal runtime error occured or the underlying server error occured.
Int Server_getAlgInfo ( Server_Handle  server,
Int  algNum,
Server_AlgInfo algInfo 
)

Get information about an algorithm on the remote server.

Parameters:
[in] server Server handle, obtained from Engine_getServer().
[in] algNum Index of algorithm.
[out] algInfo Location to store algorithm info.
Return values:
Server_EOK Success.
Server_ENOTFOUND algNum is out of range.
Server_ERUNTIME Internal runtime error occurred.
Precondition:
server is non-NULL.
algNum is between 0 and the number of algorithms returned by Server_getNumAlgs().
algInfo is non-NULL
Postcondition:
On success, algInfo will contain information about the algorithms algNum on the DSP.
See also:
Server_getNumAlgs().
Int Server_getCpuLoad ( Server_Handle  server  ) 

Get Server's CPU usage in percent.

Parameters:
[in] server Server handle, obtained from Engine_getServer().
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:
server is non-NULL.
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 an underlying server error occured.
  • Engine_EINVAL The Server handle is not valid.
Server_Status Server_getMemStat ( Server_Handle  server,
Int  segNum,
Server_MemStat memStat 
)

Get information on a memory heap segment of a remote DSP server.

Parameters:
[in] server Server handle obtained from Engine_getServer().
[in] segNum The heap number of a segment on the DSP.
[out] memStat Structure to store memory segment information.
Return values:
Server_EOK Success.
Server_ENOTFOUND segNum is out of range.
Server_ERUNTIME Internal runtime error occurred.
Precondition:
server is non-NULL.
memStat is non-NULL.
Postcondition:
On success, memStat will contain information about the memory heap segNum on the DSP.
See also:
Server_getNumMemSegs().
Server_Status Server_getNumAlgs ( Server_Handle  server,
Int *  numAlgs 
)

Get the number of codecs on the remote DSP server.

Parameters:
[in] server Server handle obtained from Engine_getServer().
[out] numAlgs The number of algs available on the DSP server.
Return values:
Server_EOK Success.
Server_ERUNTIME Internal runtime error occurred.
Precondition:
server is non-NULL.
numAlgs is non-NULL.
Postcondition:
On success, numAlgs will contain the number of codecs on the DSP.
Server_Status Server_getNumMemSegs ( Server_Handle  server,
Int *  numSegs 
)

Get the number of memory heap segments of a remote DSP server.

Parameters:
[in] server Server handle obtained from Engine_getServer().
[out] numSegs The number of heap segments of the DSP server.
Return values:
Server_EOK Success.
Server_ERUNTIME Internal runtime error occurred.
Precondition:
server is non-NULL.
numSegs is non-NULL.
Postcondition:
On success, numSegs will contain the number of memory heaps on the DSP.
See also:
Server_getMemStat().
Server_Status Server_redefineHeap ( Server_Handle  server,
String  name,
Uint32  base,
Uint32  size 
)

Set the base address and size of a remote DSP server heap.

This API is used to move and/or resize a named heap of the remote DSP server. The address passed to this API is a DSP address and the memory from base to base + size must be contiguous in physical memory. The size of the heap should be given in DSP MADUs (minimum addressable data units). The name of the heap can be at most Server_MAXSEGNAMELENGTH characters long.

For example, in the case of DM644x, suppose that an application wants to allocate a block of memory on the GPP to be used by the DSP server for the memory segment named "DDRALGHEAP". A block of physically contiguous memory could be obtained by Memory_alloc() and the corresponding DSP address obtained with Memory_getBufferPhysicalAddress(). This DSP address and the size of the block could then be passed to Server_redefineHeap(). For example:

      Server_redefineHeap(server, "DDRALGHEAP", base, size);

This function can only be called when there is no memory currently allocated in the heap (since the heap cannot be changed if it is being used).

Parameters:
[in] server Server handle obtained from Engine_getServer().
[in] name Name of heap to be redefined.
[in] base Base address for algorithm heap.
[in] size Size (DSP MADUs) of new heap.
Return values:
Server_EOK Success.
Server_ERUNTIME Internal runtime error occurred.
Server_ENOTFOUND No heap with the specified name was found.
Server_EINVAL Changing to the new base and size would cause an overlap with another heap.
Server_EINUSE Memory is currently allocated in the heap.
Precondition:
server is non-NULL.
base is a DSP address of a physically contiguous block of memory.
base is aligned on an 8-byte boundary.
Postcondition:
On success, the server's algorithm heap base will have been set to base, and the size will have been set to size.
See also:
Server_restoreHeap().
Server_Status Server_restoreHeap ( Server_Handle  server,
String  name 
)

Set the base address and size of a remote DSP server heap back to their original values.

This function resets the base address and size of a named heap of the remote server, back to their values before the first call to Server_redefineHeap() was made. The name of the heap can be at most Server_MAXSEGNAMELENGTH characters long, otherwise this function will return Server_ENOTFOUND.

As with Server_redefineHeap(), this function can only be called when no memory is currently allocated from the heap (as the heap cannot be changed if it is being used).

Parameters:
[in] server Server handle obtained through Engine_getServer().
[in] name Name of the heap to be restored.
Return values:
Server_EOK Success.
Server_ERUNTIME Internal runtime error occurred.
Server_ENOTFOUND No heap with the specified name was found.
Server_EINVAL Changing back to the original base and size would cause an overlap with another heap.
Server_EINUSE Memory is currently allocated in the heap.
Precondition:
server is non-NULL.
Postcondition:
On success, the server's algorithm heap base and size will have been reset to their original value.
See also:
Server_redefineHeap().
Int Server_setTrace ( Server_Handle  server,
String  mask 
)

Set Server's trace mask.

Parameters:
[in] server Server handle obtained through Engine_getServer().
[in] mask Trace mask, e.g. "*=01234567"
Return values:
Server_EOK Success.
Server_EINUSE A connection for server trace is already established.
Server_ENOSERVER No server for the engine.
Server_ERUNTIME Internal runtime error occurred.
Precondition:
server is non-NULL.
Corresponding 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 GT_set().
See also:
GT_set()
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines

Copyright 2010, Texas Instruments Incorporated