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 /*!
125 * ======== getDspMemTableFromServer ========
126 * Get a remote processor's memory table from a Server package
127 *
128 * Given a Server package and an executable in that package, this method
129 * returns an object that contains the Server's memory map details.
130 *
131 * For example:
132 * @p(code)
133 * myEngine.armDspLinkConfig.memTable =
134 * Engine.getDspMemTableFromServer(
135 * "./video_copy.x64P",
136 * "ti.sdo.ce.examples.servers.video_copy" );
137 *
138 * @p
139 * There is no need to use this method when the preferred
140 * {@link #createFromServer createFromServer()} method is used first.
141 *
142 * @param(serverExecutable) Path to the server executable (including the
143 * executable), relative from server package
144 * @param(serverPackage) Name of the server package
145 *
146 * @a(returns) A DSP memory table "map" object, of type
147 * ti.sdo.ce.osal.Global.
148 * ArmDspLinkConfigMemTableEntry[string]
149 *
150 * @see createFromServer
151 */
152 function getDspMemTableFromServer(serverExecutable, serverPackage);
153
154 /*!
155 * ======== close ========
156 * Internal close method (see package.xs)
157 * @_nodoc
158 */
159 function close();
160
161 /*!
162 * ======== validate ========
163 * Internal validate method (see package.xs)
164 * @_nodoc
165 */
166 function validate();
167
168 /*!
169 * ======== usesIDMA3 ========
170 * Returns true if there is an engine with a local alg that implements
171 * idma3Fxns. This function is used to determine whether or not DMAN3
172 * library needs to be linked in.
173 *
174 * @_nodoc
175 */
176 bool usesIDMA3();
177
178 /*!
179 * ======== usesIRES ========
180 * Returns true if there is an engine with a local alg that implements
181 * iresFxns. This function is used to determine whether or not RMAN
182 * library needs to be linked in.
183 *
184 * @_nodoc
185 */
186 bool usesIRES();
187
188 /*!
189 * ======== hasServer ========
190 * Returns true if there is an engine with a remote alg, or an engine
191 * that uses a server.
192 *
193 * @_nodoc
194 */
195 bool hasServer();
196
197 instance:
198
199 /*!
200 * ======== create ========
201 * Create Engine instance
202 *
203 * Parameters:
204 * @p(dlist)
205 * - `name`
206 * Name of this engine; this name is used by clients via the
207 * `Engine_open()` API to identify the collection of algorithms
208 * available.
209 *
210 * - `algs`
211 * Array of algorithms this engine supports
212 *
213 * - `server`
214 * Optional name of the DSP Server; this name is used (if
215 * necessary) to load and start any associated DSP CPUs required
216 * to support this Engine instance
217 */
218 create(String name, AlgDesc algs[]);
219
220 /*!
221 * ======== name ========
222 * Name of the Engine
223 *
224 * This string provided by the application in the `Engine_open()` call.
225 */
226 config String name;
227
228 /*!
229 * ======== algs ========
230 * Array of algorithms available in the Engine
231 *
232 * An array of algorithms which this Engine instance provides. A mix
233 * of local and remote algorithms can be specified in this array.
234 *
235 * {@link #createFromServer createFromServer()} can be used to populate
236 * this array with algorithms configured into a remote Server.
237 *
238 * @see createFromServer
239 */
240 config AlgDesc algs[];
241
242 /*!
243 * ======== server ========
244 * Optional name of a remote Server
245 *
246 * This parameter is only necessary when there are algorithms configured
247 * to run remotely - i.e., their `local` field is set to false.
248 *
249 * Engines containing these remote algorithms will need to set
250 * this `server` parameter to the name of the binary which should
251 * be loaded on the remote processor.
252 */
253 config String server;
254
255 /*!
256 * ======== heapId ========
257 * Optional heap id to be used for this Engine
258 *
259 * This is used internally, for example, by Comm_alloc().
260 */
261 config UInt32 heapId;
262
263 /*!
264 * ======== armDspLinkConfig ========
265 * Optional GPP-side Link configuration
266 *
267 * The ARM-side DSP Link configuration. If left undefined will revert to
268 * ti.sdo.ce.ipc.DEFAULT_ARMDSPLINKCONFIG, but with a warning
269 *
270 * Applies only to CE configurations where
271 * osal.Global.runtimeEnv == DSPLINK_LINUX
272 *
273 * @p
274 * There is no need to use this method when the preferred
275 * {@link #createFromServer createFromServer()} method is used first.
276 *
277 * @see createFromServer
278 */
279 config ti.sdo.ce.ipc.IIpc.ArmDspLinkConfig armDspLinkConfig;
280
281 /*!
282 * ======== useExtLoader ========
283 * In the case where the Engine has a remote server, @c useExtLoader
284 * specifies whether or not an external loader is used to load the
285 * server.
286 * If @c useExtLoader is set to false, Codec Engine will load the
287 * server when the Engine is opened. Otherwise, it will be assumed
288 * that the server has already been loaded.
289 */
290 config Bool useExtLoader = false;
291
292 /*!
293 * ======== memMap ========
294 * Optional name of file containing slave processor's memory map.
295 *
296 * This parameter is only needed when Codec Engine will be loading
297 * the slave processor.
298 */
299 config String memMap;
300 }
301 302 303 304
305