1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32
33 /*!
34 * ======== Engine ========
35 * Engine Configuration interface
36 */
37 @Template("./Engine.xdt")
38
39 metaonly module Engine {
40
41 /*!
42 * ======== local ========
43 * Default engine used by clients of the VISA API's that pass NULL for
44 * the engine handle
45 *
46 * @_nodoc
47 */
48 config Engine.Instance local;
49
50 /*!
51 * ======== MAXGROUPID ========
52 * Maximum group id.
53 */
54 const Int MAXGROUPID = 20;
55
56
57 /*!
58 * ======== initFromServer ========
59 * Allow alg tables of engines with a remote server to be populated by
60 * querying the server.
61 */
62 config Bool initFromServer = true;
63
64 /*!
65 * ======== AlgDesc ========
66 * Algorithm descriptor
67 *
68 * Each engine "contains" multiple algorithms described by AlgDesc
69 * structures.
70 *
71 * @field(name) This string specifies the "local" name used by the
72 * application to identify the algorithm to instantiate
73 * @field(mod) This field is a module reference that identifies the
74 * actual module implementing the algorithm to instantiate
75 * @field(local) If true, the algorithm should be instantiated on the
76 * "local" CPU; otherwise the server will create an
77 * instance of the algorithm identifed by `mod`.
78 * @field(groupId) This id specifies which resource sharing group
79 * this codec will be placed into. This 'group' concept
80 * is used by the framework to ensure algorithms in the
81 * same group don't pre-empt each other and corrupt the
82 * shared resources.
83 *
84 * Note that this parameter is ignored if `local` is not
85 * TRUE.
86 */
87 struct AlgDesc {
88 String name; /*! Alg nick-name */
89 ICodec.Module mod; /*! The alg implementation */
90 Bool local; /*! Run algorithm locally */
91 Int groupId; /*! Alg group ID for sharing resources */
92 };
93
94 /*!
95 * ======== createFromServer ========
96 * Create an Engine from a Server package
97 *
98 * Given a Server package and an executable in that package, this method
99 * creates an Engine instance and initializes it from details in the
100 * Server provided.
101 *
102 * An Engine instance created this way has all the codecs that exist
103 * in the Server executable - with codec names matching the names
104 * configured into the Server, and is configured to use an appropriate
105 * memory map and other DSP-specific info.
106 *
107 * Example usage:
108 * @p(code)
109 * var myEngine = Engine.createFromServer("video_copy",
110 * "./video_copy.x64P",
111 * "ti.sdo.ce.examples.servers.video_copy");
112 *
113 * @param(engineName) Name to be used for the engine created
114 * @param(serverExecutable) Path to the server executable (including the
115 * executable), relative from server package
116 * @param(serverPackage) Name of the server package
117 *
118 * @a(returns) An Engine instance of the same type as
119 * if {@link #create create()} were called.
120 */
121 function createFromServer(engineName, serverExecutable, serverPackage);
122
123 /*!
124 * ======== close ========
125 * Internal close method (see package.xs)
126 * @_nodoc
127 */
128 function close();
129
130 /*!
131 * ======== validate ========
132 * Internal validate method (see package.xs)
133 * @_nodoc
134 */
135 function validate();
136
137 /*!
138 * ======== usesIRES ========
139 * Returns true if there is an engine with a local alg that implements
140 * iresFxns. This function is used to determine whether or not RMAN
141 * library needs to be linked in.
142 *
143 * @_nodoc
144 */
145 bool usesIRES();
146
147 /*!
148 * ======== hasServer ========
149 * Returns true if there is an engine with a remote alg, or an engine
150 * that uses a server.
151 *
152 * @_nodoc
153 */
154 bool hasServer();
155
156 instance:
157
158 /*!
159 * ======== create ========
160 * Create Engine instance
161 *
162 * Parameters:
163 * @p(dlist)
164 * - `name`
165 * Name of this engine; this name is used by clients via the
166 * `Engine_open()` API to identify the collection of algorithms
167 * available.
168 *
169 * - `algs`
170 * Array of algorithms this engine supports
171 *
172 * - `server`
173 * Optional name of the DSP Server; this name is used (if
174 * necessary) to load and start any associated DSP CPUs required
175 * to support this Engine instance
176 */
177 create(String name, AlgDesc algs[]);
178
179 /*!
180 * ======== name ========
181 * Name of the Engine
182 *
183 * This string provided by the application in the `Engine_open()` call.
184 */
185 config String name;
186
187 /*!
188 * ======== algs ========
189 * Array of algorithms available in the Engine
190 *
191 * An array of algorithms which this Engine instance provides. A mix
192 * of local and remote algorithms can be specified in this array.
193 *
194 * {@link #createFromServer createFromServer()} can be used to populate
195 * this array with algorithms configured into a remote Server.
196 *
197 * @see createFromServer
198 */
199 config AlgDesc algs[];
200
201 /*!
202 * ======== server ========
203 * Optional name of a remote Server
204 *
205 * This parameter is only necessary when there are algorithms configured
206 * to run remotely - i.e., their `local` field is set to false.
207 *
208 * Engines containing these remote algorithms will need to set
209 * this `server` parameter to the name of the binary which should
210 * be loaded on the remote processor.
211 */
212 config String server;
213
214 /*!
215 * ======== heapId ========
216 * Optional heap id to be used for this Engine
217 *
218 * This is used internally, for example, by Comm_alloc().
219 */
220 config UInt32 heapId;
221
222 /*!
223 * ======== useExtLoader ========
224 * In the case where the Engine has a remote server, @c useExtLoader
225 * specifies whether or not an external loader is used to load the
226 * server.
227 * If @c useExtLoader is set to false, Codec Engine will load the
228 * server when the Engine is opened. Otherwise, it will be assumed
229 * that the server has already been loaded.
230 */
231 config Bool useExtLoader = false;
232
233 /*!
234 * ======== memMap ========
235 * Optional name of file containing slave processor's memory map.
236 *
237 * This parameter is only needed when Codec Engine will be loading
238 * the slave processor.
239 */
240 config String memMap;
241 }
242 243 244 245
246