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 * ======== noCommName ========
58 * Create a Comm which doesn't pollute the Comm namespace.
59 *
60 * Some ipc implementations (not all!) support creating an unnamed
61 * Comm. DSP Link is adding support for this, the WinCE port will have
62 * support before the Linux port. To help bridge the gap until all
63 * Link ports have this feature, and so we continue to work with Link
64 * releases that don't have this feature, CE is temporarily introducing
65 * this `noCommName` boolean.
66 *
67 * The default behavior is "as before", but for users that require
68 * unnamed Comm creates (e.g. kernel mode WinCE users), they can set
69 * this config param to `true` - on ipc ports that support it(!).
70 *
71 * The intent is to remove this `noCommName config param as soon as
72 * all Link ports support it, so don't get attached to it!
73 *
74 * @_nodoc
75 */
76 config Bool noCommName = false;
77
78 /*!
79 * ======== AlgDesc ========
80 * Algorithm descriptor
81 *
82 * Each engine "contains" multiple algorithms described by AlgDesc
83 * structures.
84 *
85 * @field(name) This string specifies the "local" name used by the
86 * application to identify the algorithm to instantiate
87 * @field(mod) This field is a module reference that identifies the
88 * actual module implementing the algorithm to instantiate
89 * @field(local) If true, the algorithm should be instantiated on the
90 * "local" CPU; otherwise the server will create an
91 * instance of the algorithm identifed by `mod`.
92 * @field(groupId) This id specifies which resource sharing group
93 * this codec will be placed into. This 'group' concept
94 * is used by the framework to ensure algorithms in the
95 * same group don't pre-empt each other and corrupt the
96 * shared resources.
97 *
98 * Note that this parameter is ignored if `local` is not
99 * TRUE.
100 */
101 struct AlgDesc {
102 String name; /*! Alg nick-name */
103 ICodec.Module mod; /*! The alg implementation */
104 Bool local; /*! Run algorithm locally */
105 Int groupId; /*! Alg group ID for sharing resources */
106 };
107
108 /*!
109 * ======== createFromServer ========
110 * Create an Engine from a Server package
111 *
112 * Given a Server package and an executable in that package, this method
113 * creates an Engine instance and initializes it from details in the
114 * Server provided.
115 *
116 * An Engine instance created this way has all the codecs that exist
117 * in the Server executable - with codec names matching the names
118 * configured into the Server, and is configured to use an appropriate
119 * memory map and other DSP-specific info.
120 *
121 * Example usage:
122 * @p(code)
123 * var myEngine = Engine.createFromServer("video_copy",
124 * "./video_copy.x64P",
125 * "ti.sdo.ce.examples.servers.video_copy");
126 *
127 * @param(engineName) Name to be used for the engine created
128 * @param(serverExecutable) Path to the server executable (including the
129 * executable), relative from server package
130 * @param(serverPackage) Name of the server package
131 *
132 * @a(returns) An Engine instance of the same type as
133 * if {@link #create create()} were called.
134 */
135 function createFromServer(engineName, serverExecutable, serverPackage);
136
137
138 /*!
139 * ======== getDspMemTableFromServer ========
140 * Get a remote processor's memory table from a Server package
141 *
142 * Given a Server package and an executable in that package, this method
143 * returns an object that contains the Server's memory map details.
144 *
145 * For example:
146 * @p(code)
147 * myEngine.armDspLinkConfig.memTable =
148 * Engine.getDspMemTableFromServer(
149 * "./video_copy.x64P",
150 * "ti.sdo.ce.examples.servers.video_copy" );
151 *
152 * @p
153 * There is no need to use this method when the preferred
154 * {@link #createFromServer createFromServer()} method is used first.
155 *
156 * @param(serverExecutable) Path to the server executable (including the
157 * executable), relative from server package
158 * @param(serverPackage) Name of the server package
159 *
160 * @a(returns) A DSP memory table "map" object, of type
161 * ti.sdo.ce.osal.Global.
162 * ArmDspLinkConfigMemTableEntry[string]
163 *
164 * @see createFromServer
165 */
166 function getDspMemTableFromServer(serverExecutable, serverPackage);
167
168 /*!
169 * ======== close ========
170 * Internal close method (see package.xs)
171 * @_nodoc
172 */
173 function close();
174
175 /*!
176 * ======== validate ========
177 * Internal validate method (see package.xs)
178 * @_nodoc
179 */
180 function validate();
181
182 /*!
183 * ======== usesIDMA3 ========
184 * Returns true if there is an engine with a local alg that implements
185 * idma3Fxns. This function is used to determine whether or not DMAN3
186 * library needs to be linked in.
187 *
188 * @_nodoc
189 */
190 bool usesIDMA3();
191
192 /*!
193 * ======== usesIRES ========
194 * Returns true if there is an engine with a local alg that implements
195 * iresFxns. This function is used to determine whether or not RMAN
196 * library needs to be linked in.
197 *
198 * @_nodoc
199 */
200 bool usesIRES();
201
202 /*!
203 * ======== hasServer ========
204 * Returns true if there is an engine with a remote alg, or an engine
205 * that uses a server.
206 *
207 * @_nodoc
208 */
209 bool hasServer();
210
211 instance:
212
213 /*!
214 * ======== create ========
215 * Create Engine instance
216 *
217 * Parameters:
218 * @p(dlist)
219 * - `name`
220 * Name of this engine; this name is used by clients via the
221 * `Engine_open()` API to identify the collection of algorithms
222 * available.
223 *
224 * - `algs`
225 * Array of algorithms this engine supports
226 *
227 * - `server`
228 * Optional name of the DSP Server; this name is used (if
229 * necessary) to load and start any associated DSP CPUs required
230 * to support this Engine instance
231 */
232 create(String name, AlgDesc algs[]);
233
234 /*!
235 * ======== name ========
236 * Name of this engine.
237 *
238 * This string provided by the application in the `Engine_open()` call.
239 */
240 config String name;
241
242 /*!
243 * ======== algs ========
244 * Array of algorithms available in an Engine
245 *
246 * An array of algorithms which this Engine instance provides. A mix
247 * of local and remote algorithms can be specified in this array.
248 *
249 * {@link #createFromServer createFromServer()} can be used to populate
250 * this array with algorithms configured into a remote Server.
251 *
252 * @see createFromServer
253 */
254 config AlgDesc algs[];
255
256 /*!
257 * ======== server ========
258 * Optional name of the remote server.
259 *
260 * This parameter is only necessary when there are algorithms configured
261 * to run remotely - i.e., their `local` field is set to false.
262 *
263 * Engines containing these remote algorithms will need to set
264 * this `server` parameter to the name of the binary which should
265 * be loaded on the remote processor.
266 */
267 config String server;
268
269 /*!
270 * ======== armDspLinkConfig ========
271 * ARM-side DSP Link configuration
272 *
273 * The ARM-side DSP Link configuration. If left undefined will revert to
274 * ti.sdo.ce.ipc.DEFAULT_ARMDSPLINKCONFIG, but with a warning
275 *
276 * Applies only to CE configurations where
277 * osal.Global.runtimeEnv == DSPLINK_LINUX
278 *
279 * @p
280 * There is no need to use this method when the preferred
281 * {@link #createFromServer createFromServer()} method is used first.
282 *
283 * @see createFromServer
284 */
285 config ti.sdo.ce.ipc.IIpc.ArmDspLinkConfig armDspLinkConfig;
286
287 /*!
288 * ======== linkCfg ========
289 * Optional name of DSP Link configuration.
290 *
291 * This parameter is only needed when LAD is used to
292 * arbitrate control of the DSP server
293 */
294 config String linkCfg;
295 }
296 297 298 299
300