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