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 * ======== ICodec ========
40 * Codec Engine algorithm interface
41 *
42 * All codecs supported by the codec engine must implement this interface.
43 * This interface provides the Codec Engine runtime the following information:
44 * @p(nlist)
45 * - How much stack space is required by the algorithm during instance
46 * creation (so the runtime can allocate an appropriate stack).
47 * - How much stack space is required by the algorithm during execution
48 * (so the runtime can allocate an appropriate stack).
49 * - The algorithm's entry points for the IALG interface (so the runtime
50 * can lookup the algorithm's functions based on a string name).
51 * - The algorithm's entry points for the optional IDMA3 interface
52 * (so the runtime can allocate DMA resources for the algorithm at
53 * runtime).
54 * - The entry points for "stubs" and "skeletons" in the case that the
55 * algorithm is to be run on a remote processor.
56 * - The size of scratch memory required by the algorithm.
57 * @p
58 */
59 metaonly interface ICodec
60 {
61 /*!
62 * ======== isLocal ========
63 * Require this codec to run "locally"
64 *
65 * This configuration parameter determines whether or not the
66 * application requires the codec's library in order to link.
67 * For example, this parameter is set to false in the case that
68 * the application is running on a different CPU than the codec.
69 *
70 * @_nodoc
71 */
72 config Bool isLocal = true;
73
74 /*!
75 * ======== ialgFxns ========
76 * Name of xDAIS alg function table
77 *
78 * All xDAIS algorithms must define an IALG_Fxns structure that
79 * contains implementations of the IALG methods. This configuration
80 * parameter is simply the extern name of this structure.
81 */
82 readonly config String ialgFxns;
83
84 /*!
85 * ======== idma3Fxns ========
86 * Name of xDAIS alg IDMA3 Interface function table
87 *
88 * All xDAIS algorithms that use DMA must define an IDMA3_Fxns structure
89 * containing the pointers to functions implementatng the IDMA3 interface.
90 * If algorithm does not use DMA this structure does not have to be
91 * defined.
92 *
93 * This configuration parameter is simply the extern name of this
94 * structure when defined, null otherwise.
95 */
96 readonly config String idma3Fxns;
97
98 /*!
99 * ======== iresFxns ========
100 * Name of xDAIS alg IRES Interface function table
101 *
102 * All xDAIS algorithms that use an IRES resource must define an
103 * IRES_Fxns structure containing the pointers to functions
104 * implementatng the IRES interface.
105 * If algorithm does not use an IRES resource this structure does not
106 * have to be defined.
107 *
108 * This configuration parameter is simply the extern name of this
109 * structure when defined, null otherwise.
110 *
111 * @see #ialgFxns
112 * @see #idma3Fxns
113 */
114 readonly config String iresFxns;
115
116 /*!
117 * ======== serverFxns ========
118 * Name of skeleton fxn table
119 *
120 * All algorithm's that can run on a remote processor must specify a set
121 * of "stub" functions that marshall arguments to send to the remote
122 * process that runs corresponding "skeletons" to do the actual
123 * processing. This configuration parameter defines the entry point for
124 * this algorithm's the skeletons (which run on the remote processor).
125 *
126 * This is generally not configured by application or server config
127 * scripts, but rather by developers of VISA-like API class extensions.
128 * However, an application or server integrator could use this config
129 * param to configure in custom serverFxns.
130 *
131 * @see #stubFxns
132 */
133 config String serverFxns;
134
135 /*!
136 * ======== stubFxns ========
137 * Name of stubs fxn table
138 *
139 * All algorithm's that can run on a remote processor must specify a set
140 * of "stub" functions that marshall arguments to send to the remote
141 * process that runs corresponding "skeletons" to do the actual
142 * processing. This configuration parameter defines the entry point for
143 * this algorithm's the stubs (which run on the local processor).
144 *
145 * This is generally not configured by application or server config
146 * scripts, but rather by developers of VISA-like API class extensions.
147 * However, an application or server integrator could use this config
148 * param to configure in custom stubFxns.
149 *
150 * @see #serverFxns
151 */
152 config String stubFxns;
153
154 /*!
155 * ======== rpcProtocolVersion ========
156 * Version of the Protocol used between the stubFxns and the serverFxns.
157 *
158 * This is set by a particular implementation of a stub/skeleton RPC pair,
159 * and is used at runtime to ensure the protocol matches. This is
160 * important, for example, to ensure that the protocol used by skeletons
161 * built into a server matches that used by the stubs built into the
162 * application. Specifically, this is typically changed when the
163 * marshalling/unmarshalling message format changes.
164 *
165 * This is generally not configured by application or server config
166 * scripts, but rather by developers of VISA-like API class extensions.
167 *
168 * This rpcProtocolVersion is built into the local application executable,
169 * as well as the remote server's executable.
170 *
171 * Developers of class extensions should ensure this config parameter is
172 * set appropriately by each release of their stubs/skeletons. If a new
173 * protocol is introduced, implying that updating both would result in
174 * error, the number should be incremented.
175 *
176 * There is no "backward-compatibility" requirement in rpcProtocolVersion.
177 * If the version is different, regardless of whether it's larger or
178 * smaller, the creation of algorithms of this class will fail.
179 */
180 readonly config Int rpcProtocolVersion;
181
182 /*!
183 * ======== uuid =======
184 * Unique algorithm implementation ID
185 *
186 * This integer must be a unique ID for every algorithm in a "system",
187 * where the "system" includes all possible DSP Servers.
188 *
189 * This id is used by the Codec Engine APIs to identify the algorithm
190 * implementation that will create an instance on a DSP Server.
191 *
192 * If a codec doesn't explicitly configure this parameter, a "very likely
193 * unique" ID will be generated. It is recommended that codecs not
194 * explicitly configure this parameter, and leave it to the system.
195 */
196 config Int uuid;
197
198 /*!
199 * ======== frameRate ========
200 * Smallest supported frame rate (frames / second)
201 *
202 * This is used to compute a default priority assignment for algorithm
203 * threads in a DSP Server.
204 *
205 * @_nodoc
206 */
207 readonly config Int frameRate;
208
209 /*!
210 * ======== codecClassConfigurable ========
211 * Flag indicating whether there are 'special' runtime config params
212 *
213 * True if the class to which the codec belongs (VISA, or custom if not
214 * a VISA) has some special run-time config params
215 *
216 * @_nodoc
217 */
218 readonly config Bool codecClassConfigurable;
219
220 /*!
221 * ======== useCache ========
222 * Flag indicating whether the framework should provide cached memory
223 *
224 * If set to true, the alg's memory requests will be allocated from
225 * cacheable memory. If set to false, the memory will be allocated from
226 * non-cached memory. If left unset, the
227 * ti.sdo.ce.alg.Algorithm.useCache flag will determine whether the
228 * alg's memory will be allocated from cached or non-cached memory.
229 */
230 config Bool useCache;
231
232 /*!
233 * ======== getCreationStackSize ========
234 * Get the maximum required stack size (in octets) for this algorithm
235 * during algorithm instance creation.
236 *
237 * This method is called during DSP Server configuration and is used to
238 * ensure that the instance creation thread on the server has sufficient
239 * stackspace to instantiate the algorithm. This stack size is typically
240 * the greater of the stack sizes required by the algorithm's
241 * algNumAlloc(), algAlloc(), or algInit() methods.
242 */
243 Int getCreationStackSize(xdc.cfg.Program.Module prog);
244
245 /*!
246 * ======== getDaramScratchSize ========
247 * Get the maximum scratch size (in octets) required for this algorithm
248 * from DARAM space.
249 *
250 * This method is called during DSP Server configuration and is used to
251 * ensure that sufficient scratch space is configured for the specified
252 * set of algorithms.
253 */
254 Int getDaramScratchSize(xdc.cfg.Program.Module prog);
255
256 /*!
257 * ======== getSaramScratchSize ========
258 * Get the maximum scratch size (in octets) required for this algorithm
259 * from SARAM space.
260 *
261 * This method is called during DSP Server configuration and is used to
262 * ensure that sufficient scratch space is configured for the specified
263 * set of algorithms.
264 */
265 Int getSaramScratchSize(xdc.cfg.Program.Module prog);
266
267 /*!
268 * ======== getStackSize ========
269 * Get the maximum stack size (in octets) required for this algorithm
270 * during its execution phase.
271 *
272 * This method is called during DSP Server configuration and is used to
273 * ensure that threads on the server have sufficient stackspace to run
274 * the algorithm.
275 */
276 Int getStackSize(xdc.cfg.Program.Module prog);
277
278 /*!
279 * ======== getUUID ========
280 * Get a uuid for this codec
281 *
282 * This method is used to get the uuid rather than reading the uuid
283 * config parameter; this allows the algorithm producer to let the
284 * system generate a uuid from the algorithm's name.
285 *
286 * Individual algorithm's should not implement this methods; the default
287 * (base) implementation provided in the ti.sdo.ce package should be
288 * sufficient.
289 *
290 * @_nodoc
291 */
292 Int getUUID();
293 }
294 295 296 297
298