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