aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
Diffstat (limited to 'packages/codec_engine/ti/sdo/ce/Engine.h')
-rw-r--r--packages/codec_engine/ti/sdo/ce/Engine.h1584
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
60extern "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 */
95typedef struct Engine_Obj *Engine_Handle;
96
97/**
98 * @brief Engine error code
99 */
100typedef 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 */
133typedef 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 */
148typedef 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 */
160typedef 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 */
179typedef 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 */
194extern Engine_Attrs Engine_ATTRS; /**< Default attrs. */
195
196/** @cond INTERNAL */
197
198typedef 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 */
210typedef 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 */
227typedef 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 */
352typedef 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 */
407typedef 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 */
420typedef 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 */
477typedef 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 */
491typedef 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 */
500typedef 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 */
509extern Engine_AlgCreateAttrs Engine_ALGCREATEATTRS;
510
511/*
512 * ======== Engine_config ========
513 */
514extern 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 */
564extern 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 */
606extern 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 */
703extern 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 */
734extern Engine_Error Engine_removeAlg(String name, Engine_Handle engine,
735 String algName);
736
737/** @cond INTERNAL */
738
739/*
740 * ======== Engine_call ========
741 */
742extern Int Engine_call(Engine_Node node, Comm_Msg *msg);
743
744/*
745 * ======== Engine_callAsync ========
746 */
747extern Int Engine_callAsync(Engine_Node node, Comm_Msg *msg);
748
749/*
750 * ======== Engine_callWait ========
751 */
752extern Int Engine_callWait(Engine_Node node, Comm_Msg *msg, UInt timeout);
753
754/*
755 * ======== Engine_ctrlNode ========
756 */
757extern 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 */
779extern 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 */
810extern 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 */
847extern 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 */
855extern 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 */
873extern 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 */
890extern Engine_Error Engine_getAlgNumRecs(Engine_Node node, Int *numRecs);
891
892/*
893 * ======== Engine_getConstName ========
894 */
895extern String Engine_getConstName(Engine_Handle engine, String name,
896 String type);
897
898/*
899 * ======== Engine_getFxns ========
900 */
901extern 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 */
908extern Int Engine_getMemId(Engine_Handle engine);
909
910/*
911 * ======== Engine_getLocalEngine ========
912 */
913extern Engine_Handle Engine_getLocalEngine(Void);
914
915/*
916 * ======== Engine_getEngine ========
917 */
918extern Engine_Handle Engine_getEngine(Engine_Node node);
919
920/*
921 * ======== Engine_getMemStat ========
922 */
923extern Engine_Error Engine_getMemStat(Server_Handle server, Int segNum,
924 Engine_MemStat *stat);
925
926/*
927 * ======== Engine_getNumMemSegs ========
928 */
929extern Engine_Error Engine_getNumMemSegs(Server_Handle server, Int *numSegs);
930
931/*
932 * ======== Engine_getNumEngines ========
933 */
934extern Int Engine_getNumEngines();
935
936/*
937 * ======== Engine_getProcId ========
938 */
939extern String Engine_getProcId(Engine_Handle engine);
940
941/*
942 * ======== Engine_hasServer ========
943 */
944extern Bool Engine_hasServer(Engine_Handle engine);
945
946/*
947 * ======== Engine_init ========
948 */
949extern 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 */
978extern 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 */
990extern 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 */
1007extern Void Engine_initDesc(Engine_Desc *pDesc);
1008
1009/** @cond INTERNAL */
1010
1011/*
1012 * ======== Engine_getRemoteVisa ========
1013 */
1014extern UInt32 Engine_getRemoteVisa(Engine_Node node);
1015
1016/*
1017 * ======== Engine_getCodecClassConfig ========
1018 */
1019extern Ptr Engine_getCodecClassConfig(Engine_Handle engine, String name,
1020 String type);
1021
1022/*
1023 * ======== Engine_getNodeQueues ========
1024 */
1025extern Void Engine_getNodeQueues(Engine_Node node, Comm_Id *stdIn, Comm_Handle *stdOut);
1026
1027
1028/*
1029 * ======== Engine_initFromServer ========
1030 */
1031extern Engine_Error Engine_initFromServer(Engine_Handle engine);
1032
1033
1034/*
1035 * ======== Engine_redefineHeap ========
1036 */
1037extern Engine_Error Engine_redefineHeap(Server_Handle server, String name,
1038 Uint32 base, Uint32 size);
1039
1040/*
1041 * ======== Engine_releaseTraceToken ========
1042 */
1043extern Bool Engine_releaseTraceToken(Server_Handle server);
1044
1045/*
1046 * ======== Engine_requestTraceToken ========
1047 */
1048extern Engine_Error Engine_requestTraceToken(Server_Handle server);
1049
1050/*
1051 * ======== Engine_restoreHeap ========
1052 */
1053extern 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 */
1106extern 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 */
1137extern 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 */
1176extern 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 */
1230extern 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 */
1266extern 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 */
1299extern 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 */
1318extern 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 */
1334extern 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 */
1363extern 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 */
1408extern 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 */
1431extern 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 */
1466extern 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 */
1489extern 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 */
1532extern 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 */
1560extern Int Engine_setTrace(Engine_Handle engine, String mask);
1561
1562
1563/** @cond INTERNAL */
1564
1565/*
1566 * ======== Engine_getDesc ========
1567 * Internal for testing.
1568 */
1569extern 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