diff options
Diffstat (limited to 'packages/codec_engine/ti/sdo/ce/Engine.h')
-rw-r--r-- | packages/codec_engine/ti/sdo/ce/Engine.h | 1584 |
1 files changed, 1584 insertions, 0 deletions
diff --git a/packages/codec_engine/ti/sdo/ce/Engine.h b/packages/codec_engine/ti/sdo/ce/Engine.h new file mode 100644 index 0000000..936c61f --- /dev/null +++ b/packages/codec_engine/ti/sdo/ce/Engine.h | |||
@@ -0,0 +1,1584 @@ | |||
1 | /* | ||
2 | * Copyright 2013 by Texas Instruments Incorporated. | ||
3 | * | ||
4 | */ | ||
5 | |||
6 | /* | ||
7 | * Copyright (c) 2013, Texas Instruments Incorporated | ||
8 | * All rights reserved. | ||
9 | * | ||
10 | * Redistribution and use in source and binary forms, with or without | ||
11 | * modification, are permitted provided that the following conditions | ||
12 | * are met: | ||
13 | * | ||
14 | * * Redistributions of source code must retain the above copyright | ||
15 | * notice, this list of conditions and the following disclaimer. | ||
16 | * | ||
17 | * * Redistributions in binary form must reproduce the above copyright | ||
18 | * notice, this list of conditions and the following disclaimer in the | ||
19 | * documentation and/or other materials provided with the distribution. | ||
20 | * | ||
21 | * * Neither the name of Texas Instruments Incorporated nor the names of | ||
22 | * its contributors may be used to endorse or promote products derived | ||
23 | * from this software without specific prior written permission. | ||
24 | * | ||
25 | * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" | ||
26 | * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, | ||
27 | * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR | ||
28 | * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR | ||
29 | * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, | ||
30 | * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, | ||
31 | * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; | ||
32 | * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, | ||
33 | * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR | ||
34 | * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, | ||
35 | * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. | ||
36 | * | ||
37 | */ | ||
38 | /* | ||
39 | * ======== Engine.h ======== | ||
40 | */ | ||
41 | |||
42 | /** | ||
43 | * @file ti/sdo/ce/Engine.h | ||
44 | * | ||
45 | * @brief The Codec Engine Runtime. | ||
46 | * | ||
47 | * @remarks Provides the user an interface to | ||
48 | * open and manipulate an Engine which can instantiate | ||
49 | * and communicate with XDAIS algorithms that run either | ||
50 | * on the local CPU or on a "remote" Server. | ||
51 | */ | ||
52 | /** | ||
53 | * @addtogroup CODECENGINE Codec Engine Runtime | ||
54 | */ | ||
55 | |||
56 | #ifndef Engine_ | ||
57 | #define Engine_ | ||
58 | |||
59 | #ifdef __cplusplus | ||
60 | extern "C" { | ||
61 | #endif | ||
62 | |||
63 | |||
64 | #include <ti/sdo/ce/ServerDefs.h> | ||
65 | #include <ti/sdo/ce/ipc/Comm.h> | ||
66 | #include <ti/xdais/ialg.h> | ||
67 | #include <ti/sdo/ce/node/node.h> | ||
68 | |||
69 | #include <stddef.h> /* def of size_t */ | ||
70 | #include <stdio.h> /* def of FILE * */ | ||
71 | |||
72 | /** @ingroup CODECENGINE */ | ||
73 | /*@{*/ | ||
74 | |||
75 | /** | ||
76 | * @brief Name to pass to Diags_setMask() to enable logging for Engine | ||
77 | * functions. | ||
78 | * | ||
79 | * @par Example Usage: | ||
80 | * The following code turns on all Log statements in the Engine | ||
81 | * module. | ||
82 | * @code | ||
83 | * Diags_setMask(Engine_MODNAME "+EX1234567"); | ||
84 | * @endcode | ||
85 | * | ||
86 | * @remarks Using Diags_setMask() to enable Engine Logging must be called | ||
87 | * after CERuntime_init() (which creates and initializes the | ||
88 | * Engine trace mask) to have any effect. | ||
89 | */ | ||
90 | #define Engine_MODNAME "ti.sdo.ce.Engine" | ||
91 | |||
92 | /** | ||
93 | * @brief Opaque handle to an engine. | ||
94 | */ | ||
95 | typedef struct Engine_Obj *Engine_Handle; | ||
96 | |||
97 | /** | ||
98 | * @brief Engine error code | ||
99 | */ | ||
100 | typedef Int Engine_Error; | ||
101 | |||
102 | #define Engine_EOK 0 /**< Success. */ | ||
103 | #define Engine_EEXIST 1 /**< Name does not exist. */ | ||
104 | #define Engine_ENOMEM 2 /**< Unable to allocate memory. */ | ||
105 | #define Engine_EDSPLOAD 3 /**< Unable to load the DSP. */ | ||
106 | #define Engine_ENOCOMM 4 /**< Unable to create a comm connection to | ||
107 | * the DSP. | ||
108 | */ | ||
109 | #define Engine_ENOSERVER 5 /**< Unable to locate the server on the DSP. */ | ||
110 | #define Engine_ECOMALLOC 6 /**< Unable to allocate communication buffer. */ | ||
111 | #define Engine_ERUNTIME 7 /**< Internal engine runtime failure. */ | ||
112 | #define Engine_ECODECCREATE 8 /**< Creation of the Codec failed. */ | ||
113 | #define Engine_ECODECSTART 9 /**< Start of the Codec failed. For codecs | ||
114 | * which are implemented as a thread, this | ||
115 | * implies that the codec thread of execution | ||
116 | * failed to start. | ||
117 | */ | ||
118 | #define Engine_EINVAL 10 /**< Bad paramater passed to method. */ | ||
119 | #define Engine_EBADSERVER 11 /**< Incompatible server specified. */ | ||
120 | #define Engine_ENOTAVAIL 12 /**< Service not available. */ | ||
121 | #define Engine_EWRONGSTATE 13 /**< Call can not be made at this time. */ | ||
122 | #define Engine_EINUSE 14 /**< Call can't be made at this time because | ||
123 | * a required name/resource is in use. | ||
124 | */ | ||
125 | #define Engine_ENOTFOUND 15 /**< Entity was not found. */ | ||
126 | #define Engine_ETIMEOUT 16 /**< Timeout-based operation timed out. */ | ||
127 | |||
128 | /** @cond INTERNAL */ | ||
129 | |||
130 | /** | ||
131 | * @brief Opaque handle to a node. | ||
132 | */ | ||
133 | typedef struct Engine_NodeObj *Engine_Node; | ||
134 | |||
135 | /** | ||
136 | * @brief Special value for timeout parameter of Engine_callWait() | ||
137 | */ | ||
138 | #define Engine_FOREVER Comm_FOREVER | ||
139 | |||
140 | /** @endcond */ | ||
141 | |||
142 | /** | ||
143 | * @brief Attributes of an Engine | ||
144 | * | ||
145 | * @sa Engine_initAttrs(). | ||
146 | * @sa Engine_open(). | ||
147 | */ | ||
148 | typedef struct Engine_Attrs { | ||
149 | String procId; /**< id of the processor that runs the server; only | ||
150 | * needed in the case that there's more than one | ||
151 | * processor that can provide the same server. | ||
152 | */ | ||
153 | } Engine_Attrs; | ||
154 | |||
155 | /** | ||
156 | * @brief Properties of an Engine algorithm | ||
157 | * | ||
158 | * @sa Engine_getAlgInfo() | ||
159 | */ | ||
160 | typedef struct Engine_AlgInfo { | ||
161 | Int algInfoSize; /**< Size of this structure. */ | ||
162 | String name; /**< Name of algorithm. */ | ||
163 | String *typeTab; /**< Inheritance hierarchy. */ | ||
164 | Bool isLocal; /**< If TRUE, run locally. */ | ||
165 | } Engine_AlgInfo; | ||
166 | |||
167 | /** | ||
168 | * @brief Properties of an Engine algorithm. | ||
169 | * | ||
170 | * @remarks This structure is identical to Engine_AlgInfo except that the | ||
171 | * @c typeTab array of strings is replaced by a single string | ||
172 | * called @c types. The string, @c types, represents a ';' | ||
173 | * separated list of inheritance hierarchies of the algorithm, | ||
174 | * for example, | ||
175 | * "ti.sdo.ce.video.IVIDDEC;ti.sdo.ce.test.xvideo.IVIDE". | ||
176 | * | ||
177 | * @sa Engine_getAlgInfo2() | ||
178 | */ | ||
179 | typedef struct Engine_AlgInfo2 { | ||
180 | Int algInfoSize; /**< Size of this structure. */ | ||
181 | String name; /**< Name of algorithm. */ | ||
182 | String types; /**< Inheritance hierarchy. */ | ||
183 | Bool isLocal; /**< If TRUE, run locally. */ | ||
184 | } Engine_AlgInfo2; | ||
185 | |||
186 | /** | ||
187 | * @brief Default engine attributes. | ||
188 | * | ||
189 | * @deprecated Engine_ATTRS is no longer recommended. Please use | ||
190 | * Engine_initAttrs() instead. | ||
191 | * | ||
192 | * @sa Engine_initAttrs() | ||
193 | */ | ||
194 | extern Engine_Attrs Engine_ATTRS; /**< Default attrs. */ | ||
195 | |||
196 | /** @cond INTERNAL */ | ||
197 | |||
198 | typedef Int Engine_Ctrl; | ||
199 | |||
200 | #define Engine_CEXIT 0 | ||
201 | #define Engine_MAXSEGNAMELENGTH 32 | ||
202 | |||
203 | /** @endcond */ | ||
204 | |||
205 | /** | ||
206 | * @brief Engine Cacheable Memory types. | ||
207 | * | ||
208 | * @enumWarning | ||
209 | */ | ||
210 | typedef enum Engine_CachedMemType { | ||
211 | Engine_USECACHEDMEM_DEFAULT = -1, /**< Use default cache setting */ | ||
212 | Engine_USECACHEDMEM_NONCACHED = 0, /**< Use non-cached memory */ | ||
213 | Engine_USECACHEDMEM_CACHED = 1 /**< Use cached memory */ | ||
214 | } Engine_CachedMemType; | ||
215 | |||
216 | |||
217 | /* | ||
218 | * ======== Engine_AlgDesc ======== | ||
219 | */ | ||
220 | /** | ||
221 | * @brief Descriptor for an alg. This object can be passed to | ||
222 | * @c Engine_addAlg(), to dynamically add an alg to an engine. | ||
223 | * | ||
224 | * @sa Engine_initAlgDesc() | ||
225 | * @sa Engine_addAlg() | ||
226 | */ | ||
227 | typedef struct Engine_AlgDesc { | ||
228 | /** | ||
229 | * @brief The name of the algorithm. This is used by the application | ||
230 | * when instantiating an instance of the algorithm through one | ||
231 | * of the VISA APIs. | ||
232 | */ | ||
233 | String name; | ||
234 | |||
235 | NODE_Uuid uuid; /**< Id of alg if running on remote target. No need | ||
236 | * to set this field. | ||
237 | */ | ||
238 | |||
239 | /** | ||
240 | * @brief The address of the XDAIS alg function table. | ||
241 | * All XDAIS algorithms must define an IALG_Fxns structure that | ||
242 | * contains implementations of the IALG methods. This field | ||
243 | * is simply the address of this structure. | ||
244 | */ | ||
245 | IALG_Fxns *fxns; | ||
246 | |||
247 | /** | ||
248 | * @brief The address of the IDMA3_Fxns function table, if the algorithm | ||
249 | * uses DMA. If the algorithm does not use DMA, this field should | ||
250 | * set to NULL. | ||
251 | * @idmaDeprecated | ||
252 | */ | ||
253 | Ptr idmaFxns; | ||
254 | |||
255 | String *typeTab; /**< inheritance hierarchy - Do not modify. */ | ||
256 | |||
257 | /** | ||
258 | * @brief If true, the algorithm will be instantiated on the | ||
259 | * "local" CPU. Otherwise the server will create an | ||
260 | * instance of the algorithm. | ||
261 | */ | ||
262 | Bool isLocal; | ||
263 | |||
264 | /** | ||
265 | * @brief This id specifies which resource sharing group that this | ||
266 | * alg will be placed into. This 'group' concept | ||
267 | * is used by the framework to ensure algorithms in the | ||
268 | * same group don't pre-empt each other and corrupt the | ||
269 | * shared resources. | ||
270 | * This parameter will be ignored if @c isLocal is FALSE. | ||
271 | */ | ||
272 | Int groupId; | ||
273 | |||
274 | Int rpcProtocolVersion; /**< Protocol version. Do not modify */ | ||
275 | |||
276 | /** | ||
277 | * @brief Address of the XDAIS alg IRES Interface function table | ||
278 | * All XDAIS algorithms that use an IRES resource must define an | ||
279 | * IRES_Fxns structure containing the pointers to functions | ||
280 | * implementatng the IRES interface. | ||
281 | * If the algorithm does not use an IRES resource this field | ||
282 | * should be set to NULL. | ||
283 | */ | ||
284 | Ptr iresFxns; | ||
285 | |||
286 | /** | ||
287 | * @brief Codec class configuration data, if any. | ||
288 | */ | ||
289 | Void *codecClassConfig; | ||
290 | |||
291 | /** | ||
292 | * @brief Indicates the type of memory the alg's memory requests will | ||
293 | * be allocated from. | ||
294 | * The alg's memory will be allocated from cached memory, if | ||
295 | * memType = Engine_USECACHEDMEM_CACHED, | ||
296 | * from non-cached memory, if | ||
297 | * memType = Engine_USECACHEDMEM_NONCACHED, | ||
298 | * Otherwise, if | ||
299 | * memType = Engine_USECACHEDMEM_DEFAULT, | ||
300 | * memory allocations will be determined by the value of | ||
301 | * ti_sdo_ce_alg_Algorithm_useCache (cached, if TRUE, non-cached, | ||
302 | * if FALSE). | ||
303 | * | ||
304 | * @sa Engine_CachedMemType | ||
305 | */ | ||
306 | Engine_CachedMemType memType; /**< Memory type for alg's mem reqs. */ | ||
307 | |||
308 | /** | ||
309 | * @brief A string idicating the type(s) of algorithm this is. | ||
310 | * This should be a ';' separated string of inherited types. | ||
311 | * In most cases, @c types will just be set to the VISA type | ||
312 | * defined in the Codec Engine algorithm interface header | ||
313 | * file included by the algorithm, depending on the XDM interface | ||
314 | * the algorithm implements. | ||
315 | * | ||
316 | * For example, if the algorithm implements the ISPHDEC1 | ||
317 | * interface as defined by XDM, @c types should be set | ||
318 | * to | ||
319 | * @c SPHDEC1_VISATYPE | ||
320 | * (defined as "ti.sdo.ce.speech1.ISPHDEC1" in the header file | ||
321 | * ti/sdo/ce/speech1/sphdec1.h). | ||
322 | * | ||
323 | * Another example to illustrate multiple typss specified in | ||
324 | * @c typss, if the algorithm implements the (made-up) | ||
325 | * interface, ti.sdo.ce.test.xvideo.IVIDE, which in turn | ||
326 | * implements the IVIDDEC interface, we could then set @c types | ||
327 | * to | ||
328 | * VIDDEC_VISATYPE";ti.sdo.ce.test.xvideo.IVIDE" | ||
329 | * or | ||
330 | * "ti.sdo.ce.test.xvideo.IVIDE;"VIDDEC_VISATYPE | ||
331 | */ | ||
332 | String types; | ||
333 | } Engine_AlgDesc; | ||
334 | |||
335 | |||
336 | /** | ||
337 | * @brief Name of function that a dynamically loaded codec must supply. | ||
338 | */ | ||
339 | #define Engine_GETALGDESCFXN "GetEngineAlgDesc" | ||
340 | |||
341 | /* | ||
342 | * ======== Engine_DllAlgDesc ======== | ||
343 | * An alg that will be dynamically loaded must have a descriptor of this type. | ||
344 | */ | ||
345 | /** | ||
346 | * @brief Descriptor for a dynamically loaded alg. A dynamic library | ||
347 | * for a codec must export a function that fills in a structure | ||
348 | * of this type. | ||
349 | * | ||
350 | * @sa Engine_GetAlgDescFxn | ||
351 | */ | ||
352 | typedef struct Engine_DllAlgDesc { | ||
353 | /** | ||
354 | * @brief Pointer to codec's IALG_Fxns. This can not be NULL. | ||
355 | */ | ||
356 | IALG_Fxns *fxns; | ||
357 | |||
358 | /** | ||
359 | * @brief Pointer to codec's IDMA3_Fxns table. If the codec does not | ||
360 | * use DMA, this should be NULL. | ||
361 | */ | ||
362 | Ptr idmaFxns; | ||
363 | |||
364 | /** | ||
365 | * @brief Pointer to codec's IRES_Fxns function table. This should be | ||
366 | * NULL if the codec does not implement the IRES_Fxns. | ||
367 | */ | ||
368 | Ptr iresFxns; | ||
369 | |||
370 | /** | ||
371 | * @brief Inheritance hierarchy of codec. This is a ';' separated | ||
372 | * string that lists the interfaces inherited by the code. For | ||
373 | * example: | ||
374 | * | ||
375 | * "ti.sdo.ce.speech1.ISPHDEC1" | ||
376 | * | ||
377 | * or, in the case where a test IVIDE interface inherits IVIDDEC: | ||
378 | * | ||
379 | * "ti.sdo.ce.video.IVIDDEC;ti.sdo.ce.test.xvideo.IVIDE" | ||
380 | * | ||
381 | */ | ||
382 | String types; | ||
383 | |||
384 | /** | ||
385 | * @brief codec class config data, if any. | ||
386 | * | ||
387 | * @todo Figure out what this is. | ||
388 | */ | ||
389 | Void *codecClassConfig; | ||
390 | } Engine_DllAlgDesc; | ||
391 | |||
392 | |||
393 | /* | ||
394 | * ======== Engine_GetAlgDescFxn ======== | ||
395 | * A dynamically loaded codec library must supply a function of this type to | ||
396 | * get properties of the library's algorithm. | ||
397 | */ | ||
398 | /** | ||
399 | * @brief Prototype of function that must be supplied by a dynamic | ||
400 | * codec library to fill in a @c Engine_DllAlgDesc structure. | ||
401 | * | ||
402 | * @remarks This function will be called by @c Engine_addAlg() to fill | ||
403 | * in the dynamic codec's descriptor. | ||
404 | * | ||
405 | * @sa Engine_DllAlgDesc | ||
406 | */ | ||
407 | typedef Int (*Engine_GetAlgDescFxn)(Engine_DllAlgDesc *dllAlgDesc); | ||
408 | |||
409 | |||
410 | /* | ||
411 | * ======== Engine_Desc ======== | ||
412 | */ | ||
413 | /** | ||
414 | * @brief This structure is passed to @c Engine_add(), and contains | ||
415 | * parameters to specify an engine. | ||
416 | * | ||
417 | * @sa Engine_add() | ||
418 | * @sa Engine_open() | ||
419 | */ | ||
420 | typedef struct Engine_Desc { | ||
421 | String name; /**< Name of the Engine | ||
422 | * | ||
423 | * @remarks This must not be NULL | ||
424 | */ | ||
425 | Engine_AlgDesc *algTab; /**< No longer used, set to NULL */ | ||
426 | String remoteName; /**< Name of Server image, if applicable | ||
427 | * | ||
428 | * @remarks If this Engine has no remote | ||
429 | * algorithms, this can be NULL. | ||
430 | * | ||
431 | * @remarks On SysLink-based systems, this | ||
432 | * is the name of a file, and is | ||
433 | * passed unchanged to | ||
434 | * ProcMgr_load(). | ||
435 | */ | ||
436 | String memMap; /**< Name of a file containing the slave | ||
437 | * memory map | ||
438 | * | ||
439 | * @remarks If this Engine has no remote | ||
440 | * algorithms, this can be NULL. | ||
441 | * | ||
442 | * @remarks If the remote algorithms are | ||
443 | * on a Server whos MMU is not | ||
444 | * enabled, this can be NULL. | ||
445 | * | ||
446 | * @remarks The format of this file matches | ||
447 | * the SysLink format described at | ||
448 | * http://processors.wiki.ti.com/index.php/SysLink_MMU_Support | ||
449 | * | ||
450 | * @remarks If useExtLoader is FALSE, this | ||
451 | * field can be NULL. | ||
452 | */ | ||
453 | Bool useExtLoader; /**< Indicates whether the Server containing | ||
454 | * any remote algorithms will be loaded using | ||
455 | * an external loader (e.g. SysLink's | ||
456 | * slaveloader) | ||
457 | * | ||
458 | * @remarks If @c useExtLoader is TRUE, | ||
459 | * Engine_open() will not load | ||
460 | * the slave. | ||
461 | * | ||
462 | * @remarks If @c useExtLoader is FALSE, | ||
463 | * Engine_open() will load the | ||
464 | * Server with the file specified | ||
465 | * by @c remoteName. | ||
466 | */ | ||
467 | Int numAlgs; /**< No longer used, set to zero */ | ||
468 | Int heapId; /**< No longer used, set to zero */ | ||
469 | } Engine_Desc; | ||
470 | |||
471 | |||
472 | /** @cond INTERNAL */ | ||
473 | |||
474 | /* | ||
475 | * ======== Engine_AlgCreateAttrs ======== | ||
476 | */ | ||
477 | typedef struct Engine_AlgCreateAttrs { | ||
478 | Bool useExtHeap; /**< Use a single external heap for alg's | ||
479 | * memory requests if TRUE, otherwise attempt | ||
480 | * to honor the alg's algAlloc() function for | ||
481 | * memory heap assignments. | ||
482 | */ | ||
483 | Int priority; /**< Alg instance priority (-1: use value from | ||
484 | * configuration). */ | ||
485 | } Engine_AlgCreateAttrs; | ||
486 | |||
487 | |||
488 | /* | ||
489 | * ======== Engine_Config ======== | ||
490 | */ | ||
491 | typedef struct Engine_Config { | ||
492 | Engine_Desc *engineTab; | ||
493 | String localEngine; | ||
494 | } Engine_Config; | ||
495 | |||
496 | /* | ||
497 | * ======== Engine_MemStat ======== | ||
498 | * This structure must match Server_MemStat. | ||
499 | */ | ||
500 | typedef struct Engine_MemStat { | ||
501 | Char name[Engine_MAXSEGNAMELENGTH + 1]; /* Name of memory segment */ | ||
502 | Uint32 base; /* Base address of memory segment */ | ||
503 | Uint32 size; /* Original size of the memory segment. */ | ||
504 | Uint32 used; /* Number of bytes used. */ | ||
505 | Uint32 maxBlockLen; /* Size of the largest contiguous free block. */ | ||
506 | } Engine_MemStat; | ||
507 | |||
508 | /* Default alg create attributes */ | ||
509 | extern Engine_AlgCreateAttrs Engine_ALGCREATEATTRS; | ||
510 | |||
511 | /* | ||
512 | * ======== Engine_config ======== | ||
513 | */ | ||
514 | extern Engine_Config Engine_config; | ||
515 | |||
516 | /** @endcond */ | ||
517 | |||
518 | |||
519 | /* | ||
520 | * ======== Engine_addStubFxns ======== | ||
521 | */ | ||
522 | /** | ||
523 | * @brief Register stub functions through which a remote algorithm | ||
524 | * can be called | ||
525 | * | ||
526 | * @param[in] fxnsName The name of the stub function table (e.g. | ||
527 | * "UNIVERSAL_STUBS") | ||
528 | * @param[in] fxns Address of stub function table | ||
529 | * (e.g. &UNIVERSAL_STUBS) | ||
530 | * | ||
531 | * @pre As with all Codec Engine API's, CERuntime_init() must have | ||
532 | * previously been called. | ||
533 | * | ||
534 | * @remarks This service is not necessary if you configure your Engine | ||
535 | * at build/config time using Engine.createFromServer(). | ||
536 | * When using Engine.createFromServer(), the appropriate | ||
537 | * alg-specific stubs are added to the system automatically. | ||
538 | * | ||
539 | * @remarks When on an RTOS (e.g. SYS/BIOS), the stubs registered are | ||
540 | * available to all Engines in the system. When on a HLOS | ||
541 | * (e.g. Linux, WinCE), the stubs registered are available to | ||
542 | * all Engines in the calling application's process. | ||
543 | * | ||
544 | * @remarks The symbol passed to the @c fxns argument can often be found | ||
545 | * in the class-specific VISA header file (e.g. UNIVERSAL_STUBS | ||
546 | * is declared in ti/sdo/ce/universal/universal.h). | ||
547 | * | ||
548 | * @remarks For example, to register "UNIVERSAL_STUBS" for use by an | ||
549 | * IUNIVERSAL-compliant algorithm at runtime, you can | ||
550 | * do the following: | ||
551 | * @code | ||
552 | * #include <ti/sdo/ce/Engine.h> | ||
553 | * #include <ti/sdo/ce/universal/universal.h> | ||
554 | * | ||
555 | * Engine_register("UNIVERSAL_STUBS", | ||
556 | * (IALG_Fxns *)&UNIVERSAL_STUBS); | ||
557 | * @endcode | ||
558 | * | ||
559 | * @retval Engine_EOK Success. | ||
560 | * @retval Engine_ENOMEM Memory allocation failed. | ||
561 | * | ||
562 | * @sa Engine_open() | ||
563 | */ | ||
564 | extern Engine_Error Engine_addStubFxns(String fxnsName, IALG_Fxns *fxns); | ||
565 | |||
566 | /* | ||
567 | * ======== Engine_add ======== | ||
568 | */ | ||
569 | /** | ||
570 | * @brief Add an Engine to the database of engines that can be opened with | ||
571 | * Engine_open() | ||
572 | * | ||
573 | * @param[in] pDesc The handle of an Engine Descriptor object. | ||
574 | * Before setting the fields of pDesc, it must | ||
575 | * first be initialized with @c Engine_initDesc(). | ||
576 | * | ||
577 | * @retval Engine_EINVAL Bad parameter passed, such as @c pDesc = NULL, | ||
578 | * or @c pDesc->name = NULL. | ||
579 | * @retval Engine_EINUSE An engine with the name @c pDesc->name already | ||
580 | * exists. | ||
581 | * @retval Engine_ENOMEM A memory allocation failed. | ||
582 | * @retval Engine_EOK Success. | ||
583 | * | ||
584 | * @pre As with all Codec Engine API's, CERuntime_init() must have | ||
585 | * previously been called. | ||
586 | * | ||
587 | * @post If the return value is Engine_EOK, Engine_open() can be | ||
588 | * called with @c pDesc->name. | ||
589 | * | ||
590 | * @par Example Usage: | ||
591 | * @code | ||
592 | * #include <ti/sdo/ce/Engine.h> | ||
593 | * | ||
594 | * Engine_Desc desc; | ||
595 | * | ||
596 | * Engine_initDesc(&desc); | ||
597 | * | ||
598 | * desc.name = "myEngine"; | ||
599 | * desc.remoteName = "myServer.x64P"; | ||
600 | * Engine_add(&desc); | ||
601 | * @endcode | ||
602 | * | ||
603 | * @sa Engine_remove() | ||
604 | * @sa Engine_open() | ||
605 | */ | ||
606 | extern Engine_Error Engine_add(Engine_Desc *pDesc); | ||
607 | |||
608 | /* | ||
609 | * ======== Engine_addAlg ======== | ||
610 | */ | ||
611 | /** | ||
612 | * @brief Dynamically add an algorithm to an Engine. | ||
613 | * | ||
614 | * @remarks If the Engine has not been opened, the name of the Engine is | ||
615 | * used, otherwise, a handle to the opened Engine. If the Engine | ||
616 | * has been opened, the added alg will only be accessible to the | ||
617 | * caller of this function. Either one or the other, but not | ||
618 | * both, of @c name and @c engine should be non-NULL. | ||
619 | * | ||
620 | * @param[in] name The name of the engine. @c name is | ||
621 | * specified in the engine configuration, or | ||
622 | * the name of an engine added with | ||
623 | * @c Engine_add(). This can only be non-NULL if | ||
624 | * the engine is not opened, otherwise, use | ||
625 | * an engine handle and set @c name to NULL. | ||
626 | * @param[in] engine The handle of an engine returned by | ||
627 | * Engine_open(). If @c engine is non-NULL, set | ||
628 | * @c name to NULL. | ||
629 | * @param[in] location String identifying the location of the | ||
630 | * algorithm. Often this is a file name, but for | ||
631 | * systems without a file system, it may be a | ||
632 | * system-specific string identifier. This may | ||
633 | * be NULL if the algorithm is built into the | ||
634 | * executable. | ||
635 | * @param[in] pAlgDesc Parameters describing the algorithm being | ||
636 | * added. Before setting the fields of this | ||
637 | * structure, it should first be initialized | ||
638 | * with @c Engine_initAlgDesc(), to set all | ||
639 | * fields to default values. | ||
640 | * If location is non-NULL (a dynamic library), | ||
641 | * then the following fields of pAlgDesc must | ||
642 | * be specified: | ||
643 | * pAlgDesc->name | ||
644 | * pAlgDesc->isLocal | ||
645 | * pAlgDesc->groupId | ||
646 | * All other Engine_AlgDesc fields will be | ||
647 | * from the dynamic library. | ||
648 | * If location is NULL (not a dynamic library), | ||
649 | * the user must set the following fields of | ||
650 | * pAlgDesc: | ||
651 | * pAlgDesc->name | ||
652 | * pAlgDesc->fxns | ||
653 | * pAlgDesc->idmaFxns, if applicable | ||
654 | * pAlgDesc->iresFxns, if applicable | ||
655 | * pAlgDesc->isLocal | ||
656 | * pAlgDesc->groupId | ||
657 | * pAlgDesc->types | ||
658 | * | ||
659 | * @pre As with all Codec Engine API's, CERuntime_init() must have | ||
660 | * previously been called. | ||
661 | * | ||
662 | * @pre @c engine is a valid (non-NULL) engine handle which is | ||
663 | * in the open state. | ||
664 | * | ||
665 | * @remarks If there is an existing algorithm in the engine already named | ||
666 | * @c name, an error will be returned. | ||
667 | * | ||
668 | * @retval Engine_EOK Success. | ||
669 | * @retval Engine_EINUSE The Engine @c name is non-NULL, and the | ||
670 | * Engine is open. | ||
671 | * @retval Engine_EINVAL @c pAlgDesc or @c pAlgDesc->name is NULL. | ||
672 | * @retval Engine_EINVAL Both @c name and @c engine are NULL. Ensure | ||
673 | * one of these is non-NULL. | ||
674 | * @retval Engine_EINVAL Both @c name and @c engine are non-NULL. | ||
675 | * Ensure that one of these is NULL. | ||
676 | * @retval Engine_EEXIST There is no engine with the given name. | ||
677 | * @retval Engine_EINUSE The name of the alg in @c pAlgDesc->name is | ||
678 | * already in use. | ||
679 | * @par Example Usage: | ||
680 | * @code | ||
681 | * #include <ti/sdo/ce/Engine.h> | ||
682 | * | ||
683 | * Engine_AlgDesc desc; | ||
684 | * | ||
685 | * Engine_initAlgDesc(&desc); | ||
686 | * | ||
687 | * desc.groupId = 2; | ||
688 | * desc.isLocal = TRUE; | ||
689 | * desc.fxns = &UNIVERSALCOPY_TI_IUNIVERSALCOPY; | ||
690 | * desc.idmaFxns = NULL; | ||
691 | * desc.iresFxns = NULL; | ||
692 | * desc.memType = Engine_USECACHEDMEM_DEFAULT; | ||
693 | * desc.types = UNIVERSAL_VISATYPE; | ||
694 | * | ||
695 | * status = Engine_addAlg("myEngine", NULL, NULL, &desc); | ||
696 | * | ||
697 | * @endcode | ||
698 | * | ||
699 | * @sa Engine_initAlgDesc() | ||
700 | * @sa Engine_open() | ||
701 | * @sa Engine_removeAlg() | ||
702 | */ | ||
703 | extern Engine_Error Engine_addAlg(String name, Engine_Handle engine, | ||
704 | String location, Engine_AlgDesc *pAlgDesc); | ||
705 | |||
706 | /* | ||
707 | * ======== Engine_removeAlg ======== | ||
708 | */ | ||
709 | /** | ||
710 | * @brief Dynamically remove an algorithm that was added to an Engine | ||
711 | * with Engine_addAlg(). | ||
712 | * | ||
713 | * @remarks The same values of the parameters @c name and @c engine that | ||
714 | * were passed to Engine_addAlg() should be used here. In | ||
715 | * particular, if @c name was used to add the alg, all handles to | ||
716 | * the engine must be closed before calling Engine_removeAlg(). | ||
717 | * | ||
718 | * | ||
719 | * @param[in] name The name of the engine or NULL, that was | ||
720 | * passed to Engine_addAlg(). | ||
721 | * @param[in] engine The handle to an engine, previously acquired | ||
722 | * by a call to Engine_open(), or NULL, that was | ||
723 | * used in Engine_addAlg(). | ||
724 | * @param[in] algName Name of the algorithm to remove. | ||
725 | * | ||
726 | * @retval Engine_EOK Success. | ||
727 | * @retval Engine_EEXIST The engine @c name does not exist. | ||
728 | * @retval Engine_ENOTFOUND @c algName could not be found in @c engine. | ||
729 | * @retval Engine_EINUSE The Engine @c name is still open. | ||
730 | * | ||
731 | * @sa Engine_open() | ||
732 | * @sa Engine_addAlg() | ||
733 | */ | ||
734 | extern Engine_Error Engine_removeAlg(String name, Engine_Handle engine, | ||
735 | String algName); | ||
736 | |||
737 | /** @cond INTERNAL */ | ||
738 | |||
739 | /* | ||
740 | * ======== Engine_call ======== | ||
741 | */ | ||
742 | extern Int Engine_call(Engine_Node node, Comm_Msg *msg); | ||
743 | |||
744 | /* | ||
745 | * ======== Engine_callAsync ======== | ||
746 | */ | ||
747 | extern Int Engine_callAsync(Engine_Node node, Comm_Msg *msg); | ||
748 | |||
749 | /* | ||
750 | * ======== Engine_callWait ======== | ||
751 | */ | ||
752 | extern Int Engine_callWait(Engine_Node node, Comm_Msg *msg, UInt timeout); | ||
753 | |||
754 | /* | ||
755 | * ======== Engine_ctrlNode ======== | ||
756 | */ | ||
757 | extern Int Engine_ctrlNode(Engine_Node node, Comm_Msg *msg, Engine_Ctrl code); | ||
758 | |||
759 | /** @endcond */ | ||
760 | |||
761 | /* | ||
762 | * ======== Engine_close ======== | ||
763 | */ | ||
764 | /** | ||
765 | * @brief Close an Engine | ||
766 | * | ||
767 | * @param[in] engine The handle to an engine, previously acquired | ||
768 | * by a call to Engine_open(). | ||
769 | * | ||
770 | * @pre @c engine must not be referenced by any algorithm instance | ||
771 | * objects; i.e., you must first delete all algorithm instances | ||
772 | * associated with @c engine before closing it. | ||
773 | * | ||
774 | * @pre @c engine is a valid (non-NULL) engine handle which is | ||
775 | * in the open state. | ||
776 | * | ||
777 | * @sa Engine_open() | ||
778 | */ | ||
779 | extern Void Engine_close(Engine_Handle engine); | ||
780 | |||
781 | /** @cond INTERNAL */ | ||
782 | /* | ||
783 | * ======== Engine_createNode ======== | ||
784 | */ | ||
785 | /** | ||
786 | * @brief Create a remote algorithm | ||
787 | * | ||
788 | * @param[in] engine The handle to an engine, previously acquired | ||
789 | * by a call to Engine_open(). | ||
790 | * @param[in] name Name of the algorithm to create. | ||
791 | * @param[in] msgSize Size of the internal message required to | ||
792 | * communicate with the remote algorithm. | ||
793 | * @param[in] nodeAttrs Creation parameters for the remote algorithm. | ||
794 | * @param[in] attrs Attributes used by the framework for creating | ||
795 | * the remote algorithm. | ||
796 | * | ||
797 | * @pre @c engine is a valid (non-NULL) engine handle which is | ||
798 | * in the open state. | ||
799 | * | ||
800 | * @remarks Engine_createNode2() was added after Engine_createNode() to | ||
801 | * support more use cases. Engine_createNode() is a wrapper | ||
802 | * around Engine_createNode2(), and is maintained for compatibility. | ||
803 | * | ||
804 | * @retval NULL Failure | ||
805 | * @retval non-NULL A handle to the created remote algorithm. | ||
806 | * | ||
807 | * @sa Engine_createNode2() | ||
808 | * @sa Engine_deleteNode() | ||
809 | */ | ||
810 | extern Engine_Node Engine_createNode(Engine_Handle engine, String name, | ||
811 | size_t msgSize, IALG_Params *nodeAttrs, Engine_AlgCreateAttrs *attrs); | ||
812 | |||
813 | |||
814 | /* | ||
815 | * ======== Engine_createNode2 ======== | ||
816 | */ | ||
817 | /** | ||
818 | * @brief Create a remote algorithm | ||
819 | * | ||
820 | * @param[in] engine The handle to an engine, previously acquired | ||
821 | * by a call to Engine_open(). | ||
822 | * @param[in] name Name of the algorithm to create. | ||
823 | * @param[in] msgSize Size of the internal message required to | ||
824 | * communicate with the remote algorithm. | ||
825 | * @param[in] nodeAttrs Creation parameters for the remote algorithm. | ||
826 | * @param[in] nodeAttrsSize Size of @c nodeAttrs. | ||
827 | * @param[in] attrs Attributes used by the framework for creating | ||
828 | * the remote algorithm. | ||
829 | * | ||
830 | * @pre @c engine is a valid (non-NULL) engine handle which is | ||
831 | * in the open state. | ||
832 | * | ||
833 | * @remarks Engine_createNode() is the preferred method to create remote | ||
834 | * algorithms. However, some algorithm interfaces incorrectly | ||
835 | * fail to provide a size field of type "Int" as the first field | ||
836 | * in their creation parameters, which the XDAIS spec defines. | ||
837 | * This service allows the creation of remote algorithms where the | ||
838 | * size of the creation params is specified "some other way" than | ||
839 | * the XDAIS spec defines. | ||
840 | * | ||
841 | * @retval NULL Failure | ||
842 | * @retval non-NULL A handle to the created remote algorithm. | ||
843 | * | ||
844 | * @sa Engine_createNode() | ||
845 | * @sa Engine_deleteNode() | ||
846 | */ | ||
847 | extern Engine_Node Engine_createNode2(Engine_Handle engine, String name, | ||
848 | size_t msgSize, IALG_Params *nodeAttrs, Int nodeAttrsSize, | ||
849 | Engine_AlgCreateAttrs *attrs); | ||
850 | |||
851 | |||
852 | /* | ||
853 | * ======== Engine_deleteNode ======== | ||
854 | */ | ||
855 | extern Void Engine_deleteNode(Engine_Node node); | ||
856 | |||
857 | /* | ||
858 | * ======== Engine_getAlgMemRecs ======== | ||
859 | */ | ||
860 | /** | ||
861 | * @brief Get the IALG_MemRecs used by an algorithm | ||
862 | * | ||
863 | * @param[in] node Handle to an algorithm instance. | ||
864 | * @param[out] memTab Location to store the IALG_MemRecs. | ||
865 | * @param[in] size Maximum number of IALG_MemRecs to put in memTab array. | ||
866 | * @param[out] numRecs Actual number of IALG_MemRecs copied into memTab array. | ||
867 | * | ||
868 | * @retval Engine_EOK Success. | ||
869 | * @retval Engine_ERUNTIME Failure. | ||
870 | * | ||
871 | * @sa Engine_getAlgNumRecs() | ||
872 | */ | ||
873 | extern Engine_Error Engine_getAlgMemRecs(Engine_Node node, IALG_MemRec *memTab, Int size, | ||
874 | Int *numRecs); | ||
875 | |||
876 | /* | ||
877 | * ======== Engine_getAlgNumRecs ======== | ||
878 | */ | ||
879 | /** | ||
880 | * @brief Get the number of IALG_MemRecs used by a remote algorithm | ||
881 | * | ||
882 | * @param[in] node Handle to an algorithm instance. | ||
883 | * @param[out] numRecs Location to store the number of IALG_MemRecs used. | ||
884 | * | ||
885 | * @retval Engine_EOK Success. | ||
886 | * @retval Engine_ERUNTIME Failure. | ||
887 | * | ||
888 | * @sa Engine_getAlgMemRecs() | ||
889 | */ | ||
890 | extern Engine_Error Engine_getAlgNumRecs(Engine_Node node, Int *numRecs); | ||
891 | |||
892 | /* | ||
893 | * ======== Engine_getConstName ======== | ||
894 | */ | ||
895 | extern String Engine_getConstName(Engine_Handle engine, String name, | ||
896 | String type); | ||
897 | |||
898 | /* | ||
899 | * ======== Engine_getFxns ======== | ||
900 | */ | ||
901 | extern IALG_Fxns *Engine_getFxns(Engine_Handle svr, String name, String type, | ||
902 | Bool *isLocal, Ptr *idmaFxns, Ptr *iresFxns, Int *groupId, | ||
903 | Engine_CachedMemType *memType); | ||
904 | |||
905 | /* | ||
906 | * ======== Engine_getMemId ======== | ||
907 | */ | ||
908 | extern Int Engine_getMemId(Engine_Handle engine); | ||
909 | |||
910 | /* | ||
911 | * ======== Engine_getLocalEngine ======== | ||
912 | */ | ||
913 | extern Engine_Handle Engine_getLocalEngine(Void); | ||
914 | |||
915 | /* | ||
916 | * ======== Engine_getEngine ======== | ||
917 | */ | ||
918 | extern Engine_Handle Engine_getEngine(Engine_Node node); | ||
919 | |||
920 | /* | ||
921 | * ======== Engine_getMemStat ======== | ||
922 | */ | ||
923 | extern Engine_Error Engine_getMemStat(Server_Handle server, Int segNum, | ||
924 | Engine_MemStat *stat); | ||
925 | |||
926 | /* | ||
927 | * ======== Engine_getNumMemSegs ======== | ||
928 | */ | ||
929 | extern Engine_Error Engine_getNumMemSegs(Server_Handle server, Int *numSegs); | ||
930 | |||
931 | /* | ||
932 | * ======== Engine_getNumEngines ======== | ||
933 | */ | ||
934 | extern Int Engine_getNumEngines(); | ||
935 | |||
936 | /* | ||
937 | * ======== Engine_getProcId ======== | ||
938 | */ | ||
939 | extern String Engine_getProcId(Engine_Handle engine); | ||
940 | |||
941 | /* | ||
942 | * ======== Engine_hasServer ======== | ||
943 | */ | ||
944 | extern Bool Engine_hasServer(Engine_Handle engine); | ||
945 | |||
946 | /* | ||
947 | * ======== Engine_init ======== | ||
948 | */ | ||
949 | extern Void Engine_init(Void); | ||
950 | |||
951 | |||
952 | /** @endcond */ | ||
953 | |||
954 | /* | ||
955 | * ======== Engine_initAlgDesc ======== | ||
956 | */ | ||
957 | /** | ||
958 | * @brief Initialize an Engine_AlgDesc structure with default values. | ||
959 | * | ||
960 | * @param[in] pAlgDesc Location of Engine_AlgDesc object to initialize. | ||
961 | * The fields of pAlgDesc will be set to the following: | ||
962 | * | ||
963 | * pAlgDesc->name = NULL; | ||
964 | * pAlgDesc->uuid.data = 0; | ||
965 | * pAlgDesc->fxns = NULL; | ||
966 | * pAlgDesc->idmaFxns = NULL; | ||
967 | * pAlgDesc->typeTab = NULL; | ||
968 | * pAlgDesc->isLocal = TRUE; | ||
969 | * pAlgDesc->groupId = 0; | ||
970 | * pAlgDesc->rpcProtocolVersion = 0; | ||
971 | * pAlgDesc->iresFxns = NULL; | ||
972 | * pAlgDesc->codecClassConfig = NULL; | ||
973 | * pAlgDesc->memType = Engine_USECACHEDMEM_DEFAULT; | ||
974 | * pAlgDesc->types = NULL; | ||
975 | * | ||
976 | * @sa Engine_addAlg() | ||
977 | */ | ||
978 | extern Void Engine_initAlgDesc(Engine_AlgDesc *pAlgDesc); | ||
979 | |||
980 | /* | ||
981 | * ======== Engine_initAttrs ======== | ||
982 | */ | ||
983 | /** | ||
984 | * @brief Initialize an Engine_Attrs structure with default values. | ||
985 | * | ||
986 | * @param[in] pAttrs Location of Engine_Attrs object to initialize. | ||
987 | * | ||
988 | * @sa Engine_open() | ||
989 | */ | ||
990 | extern Void Engine_initAttrs(Engine_Attrs *pAttrs); | ||
991 | |||
992 | /* | ||
993 | * ======== Engine_initDesc ======== | ||
994 | */ | ||
995 | /** | ||
996 | * @brief Initialize an Engine_Desc structure with default values. | ||
997 | * | ||
998 | * @param[in] pDesc Location of Engine_Desc object to initialize. | ||
999 | * The fields of pDesc will be set to the following: | ||
1000 | * | ||
1001 | * pDesc->name = NULL; | ||
1002 | * pDesc->remoteName = NULL; | ||
1003 | * pDesc->heapId = 0; | ||
1004 | * | ||
1005 | * @sa Engine_add() | ||
1006 | */ | ||
1007 | extern Void Engine_initDesc(Engine_Desc *pDesc); | ||
1008 | |||
1009 | /** @cond INTERNAL */ | ||
1010 | |||
1011 | /* | ||
1012 | * ======== Engine_getRemoteVisa ======== | ||
1013 | */ | ||
1014 | extern UInt32 Engine_getRemoteVisa(Engine_Node node); | ||
1015 | |||
1016 | /* | ||
1017 | * ======== Engine_getCodecClassConfig ======== | ||
1018 | */ | ||
1019 | extern Ptr Engine_getCodecClassConfig(Engine_Handle engine, String name, | ||
1020 | String type); | ||
1021 | |||
1022 | /* | ||
1023 | * ======== Engine_getNodeQueues ======== | ||
1024 | */ | ||
1025 | extern Void Engine_getNodeQueues(Engine_Node node, Comm_Id *stdIn, Comm_Handle *stdOut); | ||
1026 | |||
1027 | |||
1028 | /* | ||
1029 | * ======== Engine_initFromServer ======== | ||
1030 | */ | ||
1031 | extern Engine_Error Engine_initFromServer(Engine_Handle engine); | ||
1032 | |||
1033 | |||
1034 | /* | ||
1035 | * ======== Engine_redefineHeap ======== | ||
1036 | */ | ||
1037 | extern Engine_Error Engine_redefineHeap(Server_Handle server, String name, | ||
1038 | Uint32 base, Uint32 size); | ||
1039 | |||
1040 | /* | ||
1041 | * ======== Engine_releaseTraceToken ======== | ||
1042 | */ | ||
1043 | extern Bool Engine_releaseTraceToken(Server_Handle server); | ||
1044 | |||
1045 | /* | ||
1046 | * ======== Engine_requestTraceToken ======== | ||
1047 | */ | ||
1048 | extern Engine_Error Engine_requestTraceToken(Server_Handle server); | ||
1049 | |||
1050 | /* | ||
1051 | * ======== Engine_restoreHeap ======== | ||
1052 | */ | ||
1053 | extern Engine_Error Engine_restoreHeap(Server_Handle server, String name); | ||
1054 | |||
1055 | /** @endcond */ | ||
1056 | |||
1057 | /* | ||
1058 | * ======== Engine_open ======== | ||
1059 | */ | ||
1060 | /** | ||
1061 | * @brief Open an Engine | ||
1062 | * | ||
1063 | * The handle returned may be used to create one or more instances of an | ||
1064 | * algorithm contained in the specified Engine. | ||
1065 | * | ||
1066 | * An Engine may be opened more than once; each open returns a unique | ||
1067 | * handle that can be used to create algorithm instances or get status of the | ||
1068 | * Engine. | ||
1069 | * | ||
1070 | * Engine handles must not be concurrently accessed by multiple threads; each | ||
1071 | * thread must either obtain its own handle (via Engine_open()) or explicitly | ||
1072 | * serialize access to a shared handle. | ||
1073 | * | ||
1074 | * @param[in] name The name of the engine to open. @c name is | ||
1075 | * specified in the engine configuration. | ||
1076 | * @param[in] attrs Attributes for the open engine. | ||
1077 | * @param[out] ec Optional output error code | ||
1078 | * | ||
1079 | * @retval NULL An error has occurred. | ||
1080 | * @retval non-NULL The handle to the opened engine. | ||
1081 | * | ||
1082 | * @pre @c name is a non-NULL string. | ||
1083 | * | ||
1084 | * @pre @c name is a valid, pre-configured name of an engine. | ||
1085 | * | ||
1086 | * @pre As with all Codec Engine API's, CERuntime_init() must have | ||
1087 | * previously been called. | ||
1088 | * | ||
1089 | * @post If the return handle is NULL and @c ec is non-NULL, @c *ec | ||
1090 | * is set to a non-zero value indicating the cause of the failure. | ||
1091 | * | ||
1092 | * @post If @c ec is non-NULL, the Engine_Error value is set to one of | ||
1093 | * the following values: | ||
1094 | * - #Engine_EOK success | ||
1095 | * - #Engine_EEXIST name does not exist | ||
1096 | * - #Engine_ENOMEM can't allocate memory | ||
1097 | * - #Engine_EDSPLOAD can't load the DSP | ||
1098 | * - #Engine_ENOCOMM can't create a comm connection to DSP | ||
1099 | * - #Engine_ENOSERVER can't locate the server on the DSP | ||
1100 | * - #Engine_ECOMALLOC can't allocate communication buffer | ||
1101 | * | ||
1102 | * @sa Engine_close() | ||
1103 | * @sa Engine_add() | ||
1104 | * @sa Engine_remove() | ||
1105 | */ | ||
1106 | extern Engine_Handle Engine_open(String name, Engine_Attrs *attrs, | ||
1107 | Engine_Error *ec); | ||
1108 | |||
1109 | /* | ||
1110 | * ======== Engine_fwriteTrace ======== | ||
1111 | */ | ||
1112 | /** | ||
1113 | * @brief Write Server's trace buffer to specifed file stream | ||
1114 | * | ||
1115 | * @param[in] engine The handle to the opened engine. | ||
1116 | * | ||
1117 | * @param[in] prefix A string to prepend to each line output; this | ||
1118 | * allows one to easily identify trace from the | ||
1119 | * server from the application's trace, for | ||
1120 | * example. | ||
1121 | * @param[in] out A open FILE stream used to output the | ||
1122 | * Server's trace characters. | ||
1123 | * | ||
1124 | * @retval Integer number of characters copied to the specified | ||
1125 | * FILE stream. | ||
1126 | * | ||
1127 | * @pre @c engine is a valid (non-NULL) engine handle and the engine | ||
1128 | * is in the open state. | ||
1129 | * | ||
1130 | * @post In the event a negative value is returned, | ||
1131 | * Engine_getLastError() will return one of the following values: | ||
1132 | * - #Engine_ERUNTIME Either an internal runtime error | ||
1133 | * occured or the underlying server | ||
1134 | * error occured. | ||
1135 | * - #Engine_EINUSE Server trace resource is already in use. | ||
1136 | */ | ||
1137 | extern Int Engine_fwriteTrace(Engine_Handle engine, String prefix, FILE *out); | ||
1138 | |||
1139 | /* | ||
1140 | * ======== Engine_getAlgInfo ======== | ||
1141 | */ | ||
1142 | /** | ||
1143 | * @brief Get details of an algorithm configured into an engine | ||
1144 | * | ||
1145 | * @param[in] name The name of the engine. @c name is | ||
1146 | * specified in the engine configuration. | ||
1147 | * @param[out] algInfo Structure to store algorithm details. The | ||
1148 | * @c algInfoSize field of this structure must | ||
1149 | * be set to @c sizeof(Engine_AlgInfo) by the | ||
1150 | * application. | ||
1151 | * @param[out] index The index of the algorithm to get the information. | ||
1152 | * | ||
1153 | * @retval Engine_EOK Success. | ||
1154 | * @retval Engine_EEXIST There is no engine with the given name. | ||
1155 | * @retval Engine_ENOTFOUND @c index is greater than or equal to the | ||
1156 | * total number of algorithms configured for | ||
1157 | * the engine, or @c index < 0. | ||
1158 | * @retval Engine_EINVAL The value of @c algInfoSize passed to this | ||
1159 | * function does not match the CE library's | ||
1160 | * @c sizeof(Engine_AlgInfo). | ||
1161 | * | ||
1162 | * @pre @c name is a non-NULL string. | ||
1163 | * | ||
1164 | * @pre @c algInfo is non-NULL. | ||
1165 | * | ||
1166 | * @pre As with all Codec Engine API's, CERuntime_init() must have | ||
1167 | * previously been called. | ||
1168 | * | ||
1169 | * @post If @c name is a valid engine name and 0 <= @c index < the | ||
1170 | * total number of algorithms configured for the engine, then | ||
1171 | * @c algInfo will contain the information for the engine's | ||
1172 | * ith (i = @c index) algorithm. | ||
1173 | * | ||
1174 | * @sa Engine_getNumAlgs() | ||
1175 | */ | ||
1176 | extern Engine_Error Engine_getAlgInfo(String name, Engine_AlgInfo *algInfo, | ||
1177 | Int index); | ||
1178 | |||
1179 | /* | ||
1180 | * ======== Engine_getAlgInfo2 ======== | ||
1181 | */ | ||
1182 | /** | ||
1183 | * @brief Get details of an algorithm. | ||
1184 | * | ||
1185 | * @param[in] name The name of the engine. @c name is | ||
1186 | * specified in the engine configuration. This | ||
1187 | * may be NULL if @c engine contains a valid | ||
1188 | * engine handle. | ||
1189 | * @param[in] engine The handle of an engine returned by Engine_open(). | ||
1190 | * If this is NULL, only information for a static | ||
1191 | * alg can be obtained. | ||
1192 | * @param[out] algInfo2 Structure to store algorithm details. The | ||
1193 | * @c algInfoSize field of this structure must | ||
1194 | * be set to @c sizeof(Engine_AlgInfo2) by the | ||
1195 | * application. | ||
1196 | * @param[out] index The index of the algorithm to get the information. | ||
1197 | * | ||
1198 | * @retval Engine_EOK Success. | ||
1199 | * @retval Engine_EEXIST There is no engine with the given name. | ||
1200 | * @retval Engine_ENOTFOUND @c index is greater than or equal to the | ||
1201 | * total number of algorithms configured for | ||
1202 | * the engine, or @c index < 0. | ||
1203 | * @retval Engine_EINVAL The value of @c algInfoSize passed to this | ||
1204 | * function does not match the CE library's | ||
1205 | * @c sizeof(Engine_AlgInfo2). | ||
1206 | * | ||
1207 | * @pre @c name is a non-NULL string or @c engine is non-NULL. | ||
1208 | * | ||
1209 | * @pre @c algInfo2 is non-NULL. | ||
1210 | * | ||
1211 | * @pre As with all Codec Engine API's, CERuntime_init() must have | ||
1212 | * previously been called. | ||
1213 | * | ||
1214 | * @post If @c name is a valid engine name and 0 <= @c index < the | ||
1215 | * total number of algorithms configured for the engine, then | ||
1216 | * @c algInfo2 will contain the information for the engine's | ||
1217 | * ith (i = @c index) algorithm. | ||
1218 | * | ||
1219 | * @remarks This service supports algorithms statically configured into | ||
1220 | * an Engine at build/config time, or algorithms that have been | ||
1221 | * dynamically added to an opened engine. If the Engine has not | ||
1222 | * been opened yet, the name of the Engine is used to get the | ||
1223 | * statically configured alg. If the Engine has been opened, the | ||
1224 | * Engine handle can be used to get either information for a | ||
1225 | * statically configured alg, or a remote alg that was added when | ||
1226 | * the server was queried during Engine_open(). | ||
1227 | * | ||
1228 | * @sa Engine_getNumAlgs2(). | ||
1229 | */ | ||
1230 | extern Engine_Error Engine_getAlgInfo2(String name, Engine_Handle engine, | ||
1231 | Engine_AlgInfo2 *algInfo2, Int index); | ||
1232 | |||
1233 | |||
1234 | /** @cond INTERNAL */ | ||
1235 | /* | ||
1236 | * ======== Engine_getCpuLoad ======== | ||
1237 | */ | ||
1238 | /** | ||
1239 | * @brief Get Server's cpu usage in percent | ||
1240 | * | ||
1241 | * @deprecated This service has been replaced by Server_getCpuLoad() | ||
1242 | * to better indicate that this API is not intended for | ||
1243 | * obtaining the current processor's CPU load, rather it | ||
1244 | * obtains the CPU load of a remote Server. | ||
1245 | * | ||
1246 | * @param[in] engine The handle to the opened engine. | ||
1247 | * | ||
1248 | * @retval integer between 0-100 indicating percentage | ||
1249 | * of time the Server is processing measured | ||
1250 | * over a period of approximately 1 second. If | ||
1251 | * the load is unavailable, a negative value is | ||
1252 | * returned. | ||
1253 | * | ||
1254 | * @pre @c engine is a valid (non-NULL) engine handle and the engine | ||
1255 | * is in the open state. | ||
1256 | * | ||
1257 | * @post In the event a negative value is returned, | ||
1258 | * Engine_getLastError() will return one of the following values: | ||
1259 | * - #Engine_ERUNTIME Either an internal runtime error | ||
1260 | * occured or the underlying server | ||
1261 | * error occured. | ||
1262 | * - #Engine_ENOTAVAIL The CPU load can not be computed. | ||
1263 | * | ||
1264 | * @sa Server_getCpuLoad() | ||
1265 | */ | ||
1266 | extern Int Engine_getCpuLoad(Engine_Handle engine); | ||
1267 | |||
1268 | /** @endcond */ | ||
1269 | |||
1270 | |||
1271 | /* | ||
1272 | * ======== Engine_getDesc ======== | ||
1273 | */ | ||
1274 | /** | ||
1275 | * @brief Fill in an Engine_Desc structure with the values of the | ||
1276 | * Engine descriptor for an Engine. | ||
1277 | * | ||
1278 | * @param[in] name The name of the Engine. @c name is | ||
1279 | * specified in the engine configuration or a | ||
1280 | * a name that was passed to @c Engine_add(). | ||
1281 | * @param[out] desc The structure where the descriptor of the | ||
1282 | * Engine specified by @c name will be copied to. | ||
1283 | * | ||
1284 | * @retval Engine_EOK Success. | ||
1285 | * @retval Engine_EEXIST There is no engine with the given name. | ||
1286 | * | ||
1287 | * @pre @c name is a non-NULL string. | ||
1288 | * | ||
1289 | * @pre @c desc is non-NULL. | ||
1290 | * | ||
1291 | * @pre As with all Codec Engine API's, CERuntime_init() must have | ||
1292 | * previously been called. | ||
1293 | * | ||
1294 | * @post If @c name is a valid engine name, then desc will contain | ||
1295 | * the descriptor of the engine @c name. | ||
1296 | * | ||
1297 | * @sa Engine_setDesc(). | ||
1298 | */ | ||
1299 | extern Engine_Error Engine_getDesc(String name, Engine_Desc *desc); | ||
1300 | |||
1301 | /* | ||
1302 | * ======== Engine_getLastError ======== | ||
1303 | */ | ||
1304 | /** | ||
1305 | * @brief Get error code of the last failed operation | ||
1306 | * | ||
1307 | * @param[in] engine The handle to the opened engine. | ||
1308 | * | ||
1309 | * @retval error code (Engine_Error) of the last failed | ||
1310 | * engine operation. | ||
1311 | * | ||
1312 | * @pre As with all Codec Engine API's, CERuntime_init() must have | ||
1313 | * previously been called. | ||
1314 | * | ||
1315 | * @pre @c engine is a valid (non-NULL) engine handle and the engine | ||
1316 | * is in the open state. | ||
1317 | */ | ||
1318 | extern Engine_Error Engine_getLastError(Engine_Handle engine); | ||
1319 | |||
1320 | /* | ||
1321 | * ======== Engine_getName ======== | ||
1322 | */ | ||
1323 | /** | ||
1324 | * @brief Get the name of an opened engine | ||
1325 | * | ||
1326 | * @param[in] engine The handle to the opened engine. | ||
1327 | * | ||
1328 | * @pre As with all Codec Engine API's, CERuntime_init() must have | ||
1329 | * previously been called. | ||
1330 | * | ||
1331 | * @retval NULL An error has occurred. | ||
1332 | * @retval non-NULL The name of the opened engine. | ||
1333 | */ | ||
1334 | extern String Engine_getName(Engine_Handle engine); | ||
1335 | |||
1336 | |||
1337 | /* | ||
1338 | * ======== Engine_getNumAlgs ======== | ||
1339 | */ | ||
1340 | /** | ||
1341 | * @brief Get the number of algorithms configured into an Engine | ||
1342 | * | ||
1343 | * @param[in] name The name of the Engine. @c name is | ||
1344 | * specified in the engine configuration. | ||
1345 | * @param[out] numAlgs The number of algorithms that are configured | ||
1346 | * in the given engine. | ||
1347 | * | ||
1348 | * @retval Engine_EOK Success. | ||
1349 | * @retval Engine_EEXIST There is no engine with the given name. | ||
1350 | * | ||
1351 | * @pre @c name is a non-NULL string. | ||
1352 | * | ||
1353 | * @pre @c numAlgs is non-NULL. | ||
1354 | * | ||
1355 | * @pre As with all Codec Engine API's, CERuntime_init() must have | ||
1356 | * previously been called. | ||
1357 | * | ||
1358 | * @post If @c name is a valid engine name, then numAlgs will contain | ||
1359 | * the number of algorithms configured for the given engine. | ||
1360 | * | ||
1361 | * @sa Engine_getAlgs(). | ||
1362 | */ | ||
1363 | extern Engine_Error Engine_getNumAlgs(String name, Int *numAlgs); | ||
1364 | |||
1365 | /* | ||
1366 | * ======== Engine_getNumAlgs2 ======== | ||
1367 | */ | ||
1368 | /** | ||
1369 | * @brief Get the number of algorithms statically configured into an engine | ||
1370 | * or the total number of algorithms both statically configured and | ||
1371 | * dynamically added through server information when the engine was | ||
1372 | * opened. | ||
1373 | * | ||
1374 | * @param[in] name The name of the engine. @c name is | ||
1375 | * specified in the engine configuration. @c name | ||
1376 | * can be NULL, if @c engine is a valid | ||
1377 | * Engine_Handle. | ||
1378 | * @param[in] engine The handle of an engine returned by | ||
1379 | * Engine_open(). If @c engine is NULL, @c name | ||
1380 | * must be non-NULL, and only the number of | ||
1381 | * statically configured algorithms will be | ||
1382 | * returned in @c numAlgs. | ||
1383 | * specified in the engine configuration. | ||
1384 | * @param[out] numAlgs The number of algorithms that are configured | ||
1385 | * in the given engine. | ||
1386 | * | ||
1387 | * @retval Engine_EOK Success. | ||
1388 | * @retval Engine_EEXIST There is no engine with the given name. | ||
1389 | * | ||
1390 | * @pre @c name is a non-NULL string or @c engine is non-NULL. | ||
1391 | * | ||
1392 | * @pre @c numAlgs is non-NULL. | ||
1393 | * | ||
1394 | * @pre As with all Codec Engine API's, CERuntime_init() must have | ||
1395 | * previously been called. | ||
1396 | * | ||
1397 | * @post If @c name is a valid engine name, then numAlgs will contain | ||
1398 | * the number of algorithms configured for the given engine. | ||
1399 | * | ||
1400 | * @remarks If the engine has a server, but was not configured with | ||
1401 | * Engine.createFromServer() number of remote algorithms (if any) | ||
1402 | * that were statically configured into the engine, will be | ||
1403 | * counted twice: once for the static alg table, and once for | ||
1404 | * the information queried from the server. | ||
1405 | * | ||
1406 | * @sa Engine_getAlgs(). | ||
1407 | */ | ||
1408 | extern Engine_Error Engine_getNumAlgs2(String name, Engine_Handle engine, | ||
1409 | Int *numAlgs); | ||
1410 | |||
1411 | /* | ||
1412 | * ======== Engine_getServer ======== | ||
1413 | */ | ||
1414 | /** | ||
1415 | * @brief Get handle to an Engine's Server | ||
1416 | * | ||
1417 | * This function returns the handle to an Engines server, that can be used | ||
1418 | * with Server APIs to obtain information from and control the remote DSP | ||
1419 | * server. | ||
1420 | * | ||
1421 | * @param[in] engine The handle to the opened engine. | ||
1422 | * | ||
1423 | * @retval Handle to engine's server. | ||
1424 | * | ||
1425 | * @pre As with all Codec Engine API's, CERuntime_init() must have | ||
1426 | * previously been called. | ||
1427 | * | ||
1428 | * @pre @c engine is a valid (non-NULL) engine handle and the engine | ||
1429 | * is in the open state. | ||
1430 | */ | ||
1431 | extern Server_Handle Engine_getServer(Engine_Handle engine); | ||
1432 | |||
1433 | |||
1434 | /* | ||
1435 | * ======== Engine_getUsedMem ======== | ||
1436 | */ | ||
1437 | /** | ||
1438 | * @brief Get Server's total memory usage | ||
1439 | * | ||
1440 | * @deprecated This service has been replaced by Server_getMemStat() | ||
1441 | * to better indicate that this API is not intended for | ||
1442 | * obtaining the current processor's memory statistics, | ||
1443 | * rather it obtains the memory statistics of a remote | ||
1444 | * Server. Also, Server_getMemStat() provides more granularity | ||
1445 | * than Engine_getUsedMem(). | ||
1446 | * | ||
1447 | * @param[in] engine The handle to the opened engine. | ||
1448 | * | ||
1449 | * @retval Total amount of used memory (in MAUs). If the amount is not | ||
1450 | * available, 0 is returned and the reason can be retrieved via | ||
1451 | * Engine_getLastError(). | ||
1452 | * | ||
1453 | * @pre As with all Codec Engine API's, CERuntime_init() must have | ||
1454 | * previously been called. | ||
1455 | * | ||
1456 | * @pre @c engine is a valid (non-NULL) engine handle and the engine | ||
1457 | * is in the open state. | ||
1458 | * | ||
1459 | * @post in the event that 0 is returned, Engine_getLastError() will | ||
1460 | * return one of the following values: | ||
1461 | * - #Engine_ERUNTIME Either an internal runtime error | ||
1462 | * occured or the underlying server | ||
1463 | * error occured. | ||
1464 | * - #Engine_ENOTAVAIL The memory usage can not be computed. | ||
1465 | */ | ||
1466 | extern UInt32 Engine_getUsedMem(Engine_Handle engine); | ||
1467 | |||
1468 | |||
1469 | /* | ||
1470 | * ======== Engine_remove ======== | ||
1471 | */ | ||
1472 | /** | ||
1473 | * @brief Remove an engine from the list of engines that can be opened | ||
1474 | * | ||
1475 | * @param[in] engineName The name of the engine to be removed. | ||
1476 | * | ||
1477 | * @pre As with all Codec Engine API's, CERuntime_init() must have | ||
1478 | * previously been called. | ||
1479 | * | ||
1480 | * @pre @c engineName is non-NULL. | ||
1481 | * | ||
1482 | * @retval Engine_EINUSE The engine cannot be removed because | ||
1483 | * an instance of it is still opened. | ||
1484 | * @retval Engine_EEXIST No engine by this name exists. | ||
1485 | * @retval Engine_EOK Success. | ||
1486 | * | ||
1487 | * @sa Engine_add() | ||
1488 | */ | ||
1489 | extern Engine_Error Engine_remove(String engineName); | ||
1490 | |||
1491 | |||
1492 | /* | ||
1493 | * ======== Engine_setDesc ======== | ||
1494 | */ | ||
1495 | /** | ||
1496 | * @brief Set values for an Engine's descriptor. This function should | ||
1497 | * only be called when the Engine has not yet been opened. | ||
1498 | * | ||
1499 | * @param[in] name The name of the Engine. @c name is | ||
1500 | * specified in the engine configuration or a | ||
1501 | * a name that was passed to @c Engine_add(). | ||
1502 | * @param[in] desc The structure where descriptor values for the | ||
1503 | * Engine specified by @c name will be copied | ||
1504 | * from. | ||
1505 | * | ||
1506 | * @retval Engine_EOK Success. | ||
1507 | * @retval Engine_EEXIST There is no engine with the given name. | ||
1508 | * @retval Engine_EINUSE The Engine @c name has already been opened. | ||
1509 | * | ||
1510 | * @pre @c name is a non-NULL string. | ||
1511 | * | ||
1512 | * @pre @c desc is non-NULL. | ||
1513 | * | ||
1514 | * @pre As with all Codec Engine API's, CERuntime_init() must have | ||
1515 | * previously been called. | ||
1516 | * | ||
1517 | * @post If @c name is a valid engine name, then the desscriptor for | ||
1518 | * the engine @c name will have been updated with values from | ||
1519 | * @c desc. | ||
1520 | * | ||
1521 | * @remarks Use @c Engine_getDesc() to fill in the descriptor, override | ||
1522 | * the fields you want to change, and then pass the descriptor | ||
1523 | * to Engine_setDesc(). | ||
1524 | * Only the following fields of the Engine_Desc are allowed to | ||
1525 | * be modified: | ||
1526 | * @c memMap | ||
1527 | * @c useExtLoader | ||
1528 | * @c heapId | ||
1529 | * | ||
1530 | * @sa Engine_getDesc(). | ||
1531 | */ | ||
1532 | extern Engine_Error Engine_setDesc(String name, Engine_Desc *desc); | ||
1533 | |||
1534 | |||
1535 | /* | ||
1536 | * ======== Engine_setTrace ======== | ||
1537 | */ | ||
1538 | /** | ||
1539 | * @brief Set Server's trace mask | ||
1540 | * | ||
1541 | * @param[in] engine The handle to the opened engine. | ||
1542 | * @param[in] mask Trace mask, e.g. "*=01234567" | ||
1543 | * | ||
1544 | * @retval Engine_ENOSERVER No server for this engine. | ||
1545 | * @retval Engine_EINUSE Trace resource is already in use. | ||
1546 | * @retval Engine_ERUNTIME Internal runtime error has occurred. | ||
1547 | * | ||
1548 | * @pre As with all Codec Engine API's, CERuntime_init() must have | ||
1549 | * previously been called. | ||
1550 | * | ||
1551 | * @pre @c engine is a valid (non-NULL) engine handle and the engine | ||
1552 | * is in the open state. | ||
1553 | * | ||
1554 | * @remarks This only sets the trace for a remote server. To change | ||
1555 | * the trace mask for the application-side of the framework, | ||
1556 | * use Diags_setMask(), or Diags_setMaskMeta(). | ||
1557 | * | ||
1558 | * @sa xdc.runtime.Diags | ||
1559 | */ | ||
1560 | extern Int Engine_setTrace(Engine_Handle engine, String mask); | ||
1561 | |||
1562 | |||
1563 | /** @cond INTERNAL */ | ||
1564 | |||
1565 | /* | ||
1566 | * ======== Engine_getDesc ======== | ||
1567 | * Internal for testing. | ||
1568 | */ | ||
1569 | extern Engine_Desc *_Engine_getDesc(Int i); | ||
1570 | |||
1571 | /** @endcond */ | ||
1572 | |||
1573 | /*@}*/ | ||
1574 | |||
1575 | #ifdef __cplusplus | ||
1576 | } | ||
1577 | #endif | ||
1578 | |||
1579 | #endif | ||
1580 | /* | ||
1581 | * @(#) ti.sdo.ce; 1, 0, 6,3; 6-13-2013 00:10:03; /db/atree/library/trees/ce/ce-w08/src/ xlibrary | ||
1582 | |||
1583 | */ | ||
1584 | |||