1 /*
2 * Copyright (c) 2013, Texas Instruments Incorporated
3 * All rights reserved.
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions
7 * are met:
8 *
9 * * Redistributions of source code must retain the above copyright
10 * notice, this list of conditions and the following disclaimer.
11 *
12 * * Redistributions in binary form must reproduce the above copyright
13 * notice, this list of conditions and the following disclaimer in the
14 * documentation and/or other materials provided with the distribution.
15 *
16 * * Neither the name of Texas Instruments Incorporated nor the names of
17 * its contributors may be used to endorse or promote products derived
18 * from this software without specific prior written permission.
19 *
20 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
21 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
22 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
23 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
24 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
25 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
26 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
27 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
28 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
29 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
30 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31 *
32 */
33 /*
34 * ======== audenc.h ========
35 */
36 /**
37 * @file ti/sdo/ce/audio/audenc.h
38 *
39 * @brief The AUDENC audio encoder interface. Provides the user an
40 * interface to create and interact with XDAIS algorithms that are
41 * compliant with the XDM-defined IAUDENC audio encoder interface.
42 */
43 /**
44 * @defgroup ti_sdo_ce_audio_AUDENC AUDENC - Audio Encoder Interface
45 *
46 * This is the audio encoder codec interface. Several of the data
47 * types in this API are specified by the XDM IAUDENC interface; please see
48 * the XDM documentation for those details.
49 */
51 #ifndef ti_sdo_ce_audio_AUDENC_
52 #define ti_sdo_ce_audio_AUDENC_
54 #ifdef __cplusplus
55 extern "C" {
56 #endif
58 /*
59 * By definition, this interface is 0.9 XDM. Before including xdm.h,
60 * define XDM_INCLUDE_DOT9_SUPPORT
61 */
62 #ifndef XDM_INCLUDE_DOT9_SUPPORT
63 #define XDM_INCLUDE_DOT9_SUPPORT
64 #endif
65 #include <ti/xdais/dm/xdm.h>
66 #include <ti/xdais/dm/iaudenc.h>
68 #include <ti/sdo/ce/Engine.h>
69 #include <ti/sdo/ce/visa.h>
70 #include <ti/sdo/ce/skel.h>
72 /** @ingroup ti_sdo_ce_audio_AUDENC */
73 /*@{*/
75 #define AUDENC_EOK IAUDENC_EOK /**< @copydoc IAUDENC_EOK */
76 #define AUDENC_EFAIL IAUDENC_EFAIL /**< @copydoc IAUDENC_EFAIL */
77 #define AUDENC_ERUNTIME IAUDENC_ERUNTIME /**< @copydoc IAUDENC_ERUNTIME */
78 #define AUDENC_ETIMEOUT VISA_ETIMEOUT /**< @copydoc VISA_ETIMEOUT */
79 #define AUDENC_FOREVER VISA_FOREVER /**< @copydoc VISA_FOREVER */
81 /**
82 * @brief The VISA type
83 */
84 #define AUDENC_VISATYPE "ti.sdo.ce.audio.IAUDENC"
86 /**
87 * @brief Name of stub functions. Use this name when registering the
88 * AUDENC_STUBS functions with Engine_addStubFxns.
89 *
90 * @sa Engine_addStubFxns
91 */
92 #define AUDENC_STUBSNAME "AUDENC_STUBS"
94 /**
95 * @brief Opaque handle to a AUDENC codec.
96 */
97 typedef VISA_Handle AUDENC_Handle;
99 typedef IAUDENC_Params AUDENC_Params; /**< @copydoc IAUDENC_Params */
101 typedef IAUDENC_InArgs AUDENC_InArgs; /**< @copydoc IAUDENC_InArgs */
102 typedef IAUDENC_OutArgs AUDENC_OutArgs; /**< @copydoc IAUDENC_OutArgs */
103 typedef IAUDENC_Cmd AUDENC_Cmd; /**< @copydoc IAUDENC_Cmd */
104 typedef IAUDENC_Status AUDENC_Status; /**< @copydoc IAUDENC_Status */
106 /** @copydoc IAUDENC_DynamicParams */
107 typedef IAUDENC_DynamicParams AUDENC_DynamicParams;
110 /** @cond INTERNAL */
112 /**
113 * @brief An implementation of the skel interface; the skeleton side
114 * of the stubs.
115 */
116 extern SKEL_Fxns AUDENC_SKEL;
118 /**
119 * @brief Implementation of the IAUDENC interface that is run remotely.
120 */
121 extern IAUDENC_Fxns AUDENC_STUBS;
123 /** @endcond */
126 /*
127 * ======== AUDENC_control ========
128 */
129 /**
130 * @brief Execute the control() method in this instance of an audio
131 * encoder algorithm.
132 *
133 * @param[in] handle Handle to a created audio encoder instance.
134 * @param[in] id Command id for XDM control operation.
135 * @param[in] params Runtime control parameters used for encoding.
136 * @param[out] status Status info upon completion of encode operation.
137 *
138 * @pre @c handle is a valid (non-NULL) audio encoder handle
139 * and the audio encoder is in the created state.
140 *
141 * @retval #AUDENC_EOK Success.
142 * @retval #AUDENC_EFAIL Failure.
143 * @retval #AUDENC_ERUNTIME Internal Runtime Error.
144 *
145 * @remark This is a blocking call, and will return after the control
146 * command has been executed.
147 *
148 * @remark If an error is returned, @c status->extendedError may
149 * indicate further details about the error. See
150 * #AUDDEC_Status::extendedError for details.
151 *
152 * @sa AUDENC_create()
153 * @sa AUDENC_delete()
154 * @sa IAUDENC_Fxns::control() - the reflected algorithm interface,
155 * which may contain further usage
156 * details.
157 */
158 extern Int32 AUDENC_control(AUDENC_Handle handle, AUDENC_Cmd id,
159 AUDENC_DynamicParams *params, AUDENC_Status *status);
162 /*
163 * ======== AUDENC_create ========
164 */
165 /**
166 * @brief Create an instance of an audio encoder algorithm.
167 *
168 * Instance handles must not be concurrently accessed by multiple threads;
169 * each thread must either obtain its own handle (via AUDENC_create()) or
170 * explicitly serialize access to a shared handle.
171 *
172 * @param[in] e Handle to an opened engine.
173 * @param[in] name String identifier of the type of audio encoder.
174 * to create.
175 * @param[in] params Creation parameters.
176 *
177 * @retval NULL An error has occurred.
178 * @retval non-NULL The handle to the newly created audio encoder
179 * instance.
180 *
181 * @remarks @c params is optional. If it's not supplied, codec-specific
182 * default params will be used.
183 *
184 * @remark Depending on the configuration of the engine opened, this
185 * call may create a local or remote instance of the audio
186 * encoder.
187 *
188 * @codecNameRemark
189 *
190 * @sa Engine_open()
191 * @sa AUDENC_delete()
192 */
193 extern AUDENC_Handle AUDENC_create(Engine_Handle e, String name,
194 AUDENC_Params *params);
197 /*
198 * ======== AUDENC_delete ========
199 */
200 /**
201 * @brief Delete the instance of an audio encoder algorithm.
202 *
203 * @param[in] handle Handle to a created audio encoder instance.
204 *
205 * @remark Depending on the configuration of the engine opened, this
206 * call may delete a local or remote instance of the audio
207 * encoder.
208 *
209 * @pre @c handle is a valid (non-NULL) handle which is
210 * in the created state.
211 *
212 * @post All resources allocated as part of the AUDENC_create()
213 * operation (memory, DMA channels, etc.) are freed.
214 *
215 * @sa AUDENC_create()
216 */
217 extern Void AUDENC_delete(AUDENC_Handle handle);
220 /*
221 * ======== AUDENC_process ========
222 */
223 /**
224 * @brief Execute the process() method in this instance of an audio
225 * encoder algorithm.
226 *
227 * @param[in] handle Handle to a created audio encoder instance.
228 * @param[in] inBufs A buffer descriptor containing input buffers.
229 * @param[out] outBufs A buffer descriptor containing output buffers.
230 * @param[in] inArgs Input Arguments.
231 * @param[out] outArgs Output Arguments.
232 *
233 * @pre @c handle is a valid (non-NULL) audio encoder handle
234 * and the audio encoder is in the created state.
235 *
236 * @retval #AUDENC_EOK Success.
237 * @retval #AUDENC_EFAIL Failure.
238 * @retval #AUDENC_ERUNTIME Internal Runtime Error.
239 *
240 * @remark Since the AUDENC encoder contains support for asynchronous
241 * buffer submission and retrieval, this API becomes known as
242 * synchronous in nature.
243 *
244 * @remark This is a blocking call, and will return after the data
245 * has been encoded.
246 *
247 * @remark The buffers supplied to AUDENC_process() may have constraints
248 * put on them. For example, in dual-processor, shared memory
249 * architectures, where the codec is running on a remote
250 * processor, the buffers may need to be physically contiguous.
251 * Additionally, the remote processor may place restrictions on
252 * buffer alignment.
253 *
254 * @remark If an error is returned, @c outArgs->extendedError may
255 * indicate further details about the error. See
256 * #AUDENC_OutArgs::extendedError for details.
257 *
258 * @sa AUDENC_create()
259 * @sa AUDENC_delete()
260 * @sa AUDENC_control()
261 * @sa AUDENC_processAsync()
262 * @sa AUDENC_processWait()
263 * @sa IAUDENC_Fxns::process() - the reflected algorithm interface,
264 * which may contain further usage
265 * details.
266 */
267 extern Int32 AUDENC_process(AUDENC_Handle handle,
268 XDM_BufDesc *inBufs, XDM_BufDesc *outBufs,
269 AUDENC_InArgs *inArgs, AUDENC_OutArgs *outArgs);
272 /*
273 * ======== AUDENC_processAsync ========
274 */
275 /**
276 * @brief Perform asynchronous submission to this instance of a audio
277 * encoder algorithm.
278 *
279 * @param[in] handle Handle to a created audio encoder instance.
280 * @param[in] inBufs A buffer descriptor containing input buffers.
281 * @param[out] outBufs A buffer descriptor containing output buffers.
282 * @param[in] inArgs Input Arguments.
283 * @param[out] outArgs Output Arguments.
284 *
285 * @pre @c handle is a valid (non-NULL) audio encoder handle
286 * and the audio encoder is in the created state.
287 *
288 * @retval #AUDENC_EOK Success.
289 * @retval #AUDENC_EFAIL Failure.
290 * @retval #AUDENC_ERUNTIME Internal Runtime Error.
291 *
292 * @remark This API is the asynchronous counterpart to the process()
293 * method. It allows for buffer and argument submission without
294 * waiting for retrieval. A response is retrieved using the
295 * AUDENC_processWait() API.
296 *
297 * @remark The buffers supplied to AUDENC_processAsync() may have
298 * constraints put on them. For example, in dual-processor,
299 * shared memory architectures, where the codec is running on a
300 * remote processor, the buffers may need to be physically
301 * contiguous. Additionally, the remote processor may place
302 * restrictions on buffer alignment.
303 *
304 * @sa AUDENC_create()
305 * @sa AUDENC_delete()
306 * @sa AUDENC_control()
307 * @sa AUDENC_process()
308 * @sa AUDENC_processWait()
309 * @sa IAUDENC_Fxns::process()
310 * @sa IAUDENC_Fxns::process() - the reflected algorithm interface,
311 * which may contain further usage
312 * details.
313 */
314 extern XDAS_Int32 AUDENC_processAsync(AUDENC_Handle handle, XDM_BufDesc *inBufs,
315 XDM_BufDesc *outBufs, IAUDENC_InArgs *inArgs, IAUDENC_OutArgs *outArgs);
318 /*
319 * ======== AUDENC_processWait ========
320 */
321 /**
322 * @brief Wait for a return message from a previous invocation of
323 * AUDENC_processAsync() in this instance of an audio encoder
324 * algorithm.
325 *
326 * @param[in] handle Handle to a created audio encoder instance.
327 * @param[in] inBufs A buffer descriptor containing input buffers.
328 * @param[out] outBufs A buffer descriptor containing output buffers.
329 * @param[in] inArgs Input Arguments.
330 * @param[out] outArgs Output Arguments.
331 * @param[in] timeout Amount of "time" to wait (from 0 -> AUDENC_FOREVER)
332 *
333 * @pre @c handle is a valid (non-NULL) audio encoder handle
334 * and the audio encoder is in the created state.
335 *
336 * @retval #AUDENC_EOK Success.
337 * @retval #AUDENC_EFAIL Failure.
338 * @retval #AUDENC_ERUNTIME Internal Runtime Error.
339 * @retval #AUDENC_ETIMEOUT Operation timed out.
340 *
341 * @remark This is a blocking call, and will return after the data
342 * has been decoded.
343 *
344 * @remark "Polling" is supported by using a timeout of 0. Waiting
345 * forever is supported by using a timeout of #AUDENC_FOREVER.
346 *
347 * @remark There must have previously been an invocation of the
348 * AUDENC_processAsync() API.
349 *
350 * @remark The buffers supplied to AUDENC_processAsync() may have
351 * constraints put on them. For example, in dual-processor,
352 * shared memory architectures, where the codec is running on a
353 * remote processor, the buffers may need to be physically
354 * contiguous. Additionally, the remote processor may place
355 * restrictions on buffer alignment.
356 *
357 * @sa AUDENC_create()
358 * @sa AUDENC_delete()
359 * @sa AUDENC_control()
360 * @sa AUDENC_process()
361 * @sa AUDENC_processAsync()
362 */
363 extern XDAS_Int32 AUDENC_processWait(AUDENC_Handle handle, XDM_BufDesc *inBufs,
364 XDM_BufDesc *outBufs, IAUDENC_InArgs *inArgs, IAUDENC_OutArgs *outArgs,
365 UInt timeout);
368 /*@}*/
370 #ifdef __cplusplus
371 }
372 #endif
374 #endif