1 ****************************** LIBDCE README ******************************
3 The libDCE component provides an interface for applications running on the
4 MPU (HLOS) to invoke the Codec Engine APIs on the remote core (IPU). It
5 enables the Video Encode/Decode Usecases. Apart from the exposed CE APIs,
6 it provides a memplugin utility to allocate memory that can be read/written
7 from the remote IPU core.
9 This ReadMe file comprises:
10 1. LibDCE Build Information
11 a. For QNX
12 b. For Linux
13 c. For Android
14 2. Supported API information
15 a. Codec Engine APIs
16 b. libDCE APIs
17 3. API call flow
18 a. Decoder Application
19 4. Version Info of Headers included in packages folder
21 ****************************** BUILD INFO *****************************
23 ########################### For QNX ###########################
25 Exporting QNX variables:
26 export QNX_ROOT=/opt/qnx650
27 export QNX_HOST=${QNX_ROOT}/host/linux/x86
28 export LD_LIBRARY_PATH=${QNX_HOST}/usr/lib
29 export QNX_TARGET=${QNX_ROOT}/target/qnx6
30 export MAKEFLAGS=-I${QNX_TARGET}/usr/include
31 export QNX_CONFIGURATION=/etc/qnx
32 export QNX_JAVAHOME=${QNX_ROOT}/_jvm
33 export PATH=${QNX_HOST}/usr/bin:${PATH}:${QNX_CONFIGURATION}/bin
34 export QNX_USERNAME=<registered email-id at QNX> //not important
35 eval `qconfig -n "QNX Software Development Platform 6.5.0" -e`
37 If previous eval doesn't work, that is it doesn't output the following:
38 "
39 export QNX_HOST="/opt/qnx650/host/linux/x86";
40 export QNX_TARGET="/opt/qnx650/target/qnx6";
41 export PATH="/opt/qnx650/host/linux/x86/usr/bin:/opt/qnx650/host/linux/x86/bin:/opt/qnx650/host/
42 linux/x86/sbin:/opt/qnx650/host/linux/x86/usr/sbin:/opt/qnx650/host/linux/x86/usr/photon/appbuilder:
43 /usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/etc/qnx/bin:/etc/qnx/bin:
44 /opt/qnx650:/etc/qnx/bin:/etc/qnx/bin:/etc/qnx/bin:/etc/qnx/bin";
45 export LD_LIBRARY_PATH="/opt/qnx650/host/linux/x86/usr/lib";
46 export MAKEFLAGS="-I/opt/qnx650/target/qnx6/usr/include";
47 "
49 then try:
50 /opt/qnx650/host/linux/x86/usr/bin/qconfig -n "QNX Software Development Platform 6.5.0" -e
52 Exporting LIBDCE variables:
53 export IPCHEADERS=<path to IPC Headers>
54 export INSTALL_ROOT=<path for copying output binaries>
55 export QCONF_OVERRIDE=<absolute path to libdce/nto/qconf-override.mk>
57 For IPCHEADERS - Headers should be at:
58 $(IPCHEADERS)/usr/include/memmgr
59 $(IPCHEADERS)/usr/include/ti/syslink/
60 $(IPCHEADERS)/usr/include/ti/ipc/mm
61 $(IPCHEADERS)/usr/include/ti/shmemallocator
62 $(IPCHEADERS)/usr/include/
64 Building:
65 make install
67 Clean:
68 make clean
70 Location of Binaries:
71 INSTALL_ROOT/armle-v7/usr/lib/libdce.so
72 INSTALL_ROOT/armle-v7/usr/lib/libdce.so.1
73 INSTALL_ROOT/armle-v7/bin/dce_test
74 INSTALL_ROOT/armle-v7/bin/dce_enc_test
77 ########################## For Linux ##########################
79 Exporting LIBDCE variables:
80 export IPC_HEADERS=<path to IPC Headers> (MmRpc.h)
82 Building:
84 user@target:~/libdce# ./autogen.sh --prefix=/usr
85 This will check for required packages, compiler,
86 headers and generates the Makefile. --prefix=/usr
87 will confirure the install directory to /usr
89 user@target:~/libdce# make
90 Running make will build the library. It generates
91 the shared objects, static library, libdce.la
92 file for linking (Used by libtool) and
93 libdce.pc used for querying using pkg-config.
95 user@target:~/libdce# make install
96 Installs the library files(libdce.so*, libdce.a,
97 libdce.la) to $(--prefix)/lib.
98 Installs libdce.pc to $(--prefix)/lib/pkgconfig
99 Installs libdce.h and required headers to
100 $(--prefix)/include/dce/
102 Clean:
104 user@target:~/libdce# make clean
105 This will clean the build. Run make to build.
106 user@target:~/libdce# make distclean
107 This will clean the build and remove Makefiles.
108 Follow build steps above to build again.
110 ######################### For Android #########################
117 ******************************* API DETAILS *******************************
119 ######################### Codec Engine APIs #########################
121 /*==================================================================*/
122 /** Engine_open : Codec Engine Exposed API to open
123 * Codec Engine.
124 * @ param name [in] : Name of Encoder or Decoder codec.
125 * @ param attrs [in] : Pointer to Engine Attributes structure.
126 NULL is valid.
127 * @ param ec [out] : Pointer to Engine Error structure for Codec
128 * to write error code. NULL is valid.
129 * @ return : Codec Engine Handle is returned to be used
130 * to create codec.
131 * In case of error, NULL is returned.
132 */
133 Engine_Handle Engine_open(String name, Engine_Attrs *attrs, Engine_Error *ec)
136 ######################### VIDDEC3 APIs #########################
137 /*==================================================================*/
138 /** VIDDEC3_create : Create Decoder codec.
139 *
140 * @ param engine [in] : Engine Handle obtained in Engine_open() call.
141 * @ param name [in] : Name of Decoder codec.
142 * @ param params [in] : Pointer to Static parameters structure of codec
143 * allocated using dce_alloc() API.
144 * @ return : Codec Handle is returned to be used for
145 * future CE calls.
146 * In case of error, NULL is returned.
147 */
148 VIDDEC3_Handle VIDDEC3_create(Engine_Handle engine, String name,
149 VIDDEC3_Params *params)
152 /*==================================================================*/
153 /** VIDDEC3_control : Codec control call.
154 *
155 * @ param codec [in] : Codec Handle obtained in VIDDEC3_create() call.
156 * @ param id [in] : Command id for XDM control operation.
157 * @ param dynParams [in] : Pointer to dynamic parameters structure
158 * of codec allocated using dce_alloc() API.
159 * @ param status [out] : Pointer to status parameters structure
160 * of codec allocated using dce_alloc() API.
161 * If 'id' is XDM_GETVERSION, then
162 * status->data.buf should have a pointer to a
163 * buffer allocated through dce_alloc() API.
164 * @ return : DCE error status of control call is returned.
165 * #DCE_EOK [0] : Success.
166 * #DCE_EXDM_FAIL [-1] : XDM Failure.
167 * #DCE_EXDM_UNSUPPORTED [-3] : Unsupported XDM request.
168 * #DCE_EIPC_CALL_FAIL [-5] : MmRpc Call failed.
169 * #DCE_EINVALID_INPUT [-6] : Invalid Inputs.
170 */
171 XDAS_Int32 VIDDEC3_control(VIDDEC3_Handle codec, VIDDEC3_Cmd id,
172 VIDDEC3_DynamicParams *dynParams, VIDDEC3_Status *status)
175 /*==================================================================*/
176 /** VIDDEC3_process : Decode process call.
177 *
178 * @ param codec [in] : Codec Handle obtained in VIDDEC3_create() call.
179 * @ param inBufs [in] : Pointer to Input Buffer Descriptor structure
180 * of codec allocated using dce_alloc() API.
181 * inBufs->descs[0].buf should have a virtual pointer
182 * to the Input Buffer in QNX. In Linux/Android, it
183 * should have a DMA Buf FD to the Input Buffer.
184 * @ param outBufs [in] : Pointer to Output Buffer Descriptor structure
185 * of codec allocated using dce_alloc() API.
186 * outBufs->descs[0].buf and outBufs->descs[1].buf
187 * should have virtual pointers to the Output
188 * Luma and Chroma Buffers respectively in QNX.
189 * In Linux/Android, these fields should have
190 * DMA Buf FDs to the Output Buffers.
191 * @ param inArgs [in] : Pointer to Input Arguments structure
192 * of codec allocated using dce_alloc() API.
193 * @ param outArgs [out] : Pointer to Output Arguments structure
194 * of codec allocated using dce_alloc() API.
195 * @ return : DCE error status of process call is returned.
196 * #DCE_EOK [0] : Success.
197 * #DCE_EXDM_FAIL [-1] : XDM Failure.
198 * #DCE_EXDM_UNSUPPORTED [-3] : Unsupported XDM request.
199 * #DCE_EIPC_CALL_FAIL [-5] : MmRpc Call failed.
200 * #DCE_EINVALID_INPUT [-6] : Invalid Inputs.
201 */
202 XDAS_Int32 VIDDEC3_process(VIDDEC3_Handle codec,
203 XDM2_BufDesc *inBufs, XDM2_BufDesc *outBufs,
204 VIDDEC3_InArgs *inArgs, VIDDEC3_OutArgs *outArgs)
207 /*===============================================================*/
208 /** VIDDEC3_delete : Delete Decode codec instance.
209 *
210 * @ param codec [in] : Codec Handle obtained in VIDDEC3_create() call.
211 * @ return : NIL.
212 */
213 Void VIDDEC3_delete(VIDDEC3_Handle codec)
216 ######################### VIDDENC2 APIs #########################
217 /*==================================================================*/
218 /** VIDENC2_create : Create Encoder codec.
219 *
220 * @ param engine [in] : Engine Handle obtained in Engine_open() call.
221 * @ param name [in] : Name of Encoder codec.
222 * @ param params [in] : Pointer to Static parameters structure of codec
223 * allocated using dce_alloc() API.
224 * @ return : Codec Handle is returned to be used for
225 * future CE calls.
226 * In case of error, NULL is returned.
227 */
228 VIDENC2_Handle VIDENC2_create(Engine_Handle engine, String name,
229 VIDENC2_Params *params)
232 /*==================================================================*/
233 /** VIDENC2_control : Codec control call.
234 *
235 * @ param codec [in] : Codec Handle obtained in VIDENC2_create() call.
236 * @ param id [in] : Command id for XDM control operation.
237 * @ param dynParams [in] : Pointer to dynamic parameters structure
238 * of codec allocated using dce_alloc() API.
239 * @ param status [out] : Pointer to status parameters structure
240 * of codec allocated using dce_alloc() API.
241 * If 'id' is XDM_GETVERSION, then
242 * status->data.buf should have a pointer to a
243 * buffer allocated through dce_alloc() API.
244 * @ return : DCE error status of control call is returned.
245 * #DCE_EOK [0] : Success.
246 * #DCE_EXDM_FAIL [-1] : XDM Failure.
247 * #DCE_EXDM_UNSUPPORTED [-3] : Unsupported XDM request.
248 * #DCE_EIPC_CALL_FAIL [-5] : MmRpc Call failed.
249 * #DCE_EINVALID_INPUT [-6] : Invalid Inputs.
250 */
251 XDAS_Int32 VIDENC2_control(VIDENC2_Handle codec, VIDENC2_Cmd id,
252 VIDENC2_DynamicParams *dynParams, VIDENC2_Status *status)
255 /*==================================================================*/
256 /** VIDENC2_process : Encode process call.
257 *
258 * @ param codec [in] : Codec Handle obtained in VIDENC2_create() call.
259 * @ param inBufs [in] : Pointer to Input Buffer Descriptor structure
260 * of codec allocated using dce_alloc() API.
261 * inBufs->planeDesc[0].buf and inBufs->planeDesc[1].buf
262 * should have virtual pointers to the Output
263 * Luma and Chroma Buffers respectively in QNX.
264 * In Linux/Android, these fields should have
265 * DMA Buf FDs to the Output Buffers.
266 * @ param outBufs [in] : Pointer to Output Buffer Descriptor structure
267 * of codec allocated using dce_alloc() API.
268 * OutBufs->descs[0].buf should have a virtual pointer
269 * to the Input Buffer in QNX. In Linux/Android, it
270 * should have a DMA Buf FD to the Input Buffer.
271 * @ param inArgs [in] : Pointer to Input Arguments structure
272 * of codec allocated using dce_alloc() API.
273 * @ param outArgs [out] : Pointer to Output Arguments structure
274 * of codec allocated using dce_alloc() API.
275 * @ return : DCE error status of process call is returned.
276 * #DCE_EOK [0] : Success.
277 * #DCE_EXDM_FAIL [-1] : XDM Failure.
278 * #DCE_EXDM_UNSUPPORTED [-3] : Unsupported XDM request.
279 * #DCE_EIPC_CALL_FAIL [-5] : MmRpc Call failed.
280 * #DCE_EINVALID_INPUT [-6] : Invalid Inputs.
281 */
282 XDAS_Int32 VIDENC2_process(VIDENC2_Handle codec,
283 IVIDEO2_BufDesc *inBufs, XDM2_BufDesc *outBufs,
284 VIDENC2_InArgs *inArgs, VIDENC2_OutArgs *outArgs)
287 /*===============================================================*/
288 /** VIDENC2_delete : Delete Encode codec instance.
289 *
290 * @ param codec [in] : Codec Handle obtained in VIDENC2_create() call.
291 * @ return : NIL.
292 */
293 Void VIDENC2_delete(VIDENC2_Handle codec)
296 /*==================================================================*/
297 /** Engine_close : Codec Engine Exposed API to Close Engine.
298 *
299 * @ param engine [in] : Engine Handle obtained in Engine_open() call.
300 */
301 Void Engine_close(Engine_Handle engine)
304 ############################ libDCE APIs ############################
306 /*==================================================================*/
307 /** dce_alloc : Allocate the Data structures passed to
308 * codec-engine APIs except Input/Output buffers.
309 * @ param sz [in] : Size of memory to be allocated.
310 * @ return : Pointer to allocated memory.
311 */
312 void *dce_alloc(int sz)
315 /*==================================================================*/
316 /** dce_free : Free the Data structures passed to codec-engine APIs
317 * allocated through the dce_alloc() API.
318 * @ param ptr [in] : Pointer to allocated memory.
319 */
320 void dce_free(void *ptr)
323 /*================ The below APIs are LINUX specifc ================*/
324 /*==================================================================*/
325 /** dce_init : Initialize DCE. Only Linux applications
326 * should call this API.
327 * @ return : Pointer to omap_device structure.
328 */
329 void *dce_init(void)
332 /*===============================================================*/
333 /** dce_deinit : Deinitialize DCE. Only Linux applications
334 * should call this API.
335 * @ param dev [in] : Pointer to omap_device structure.
336 */
337 void dce_deinit(void *dev)
340 /*===============================================================*/
341 /** dce_buf_lock : Pin or lock Tiler Buffers which would be
342 * used by the codec as reference buffers.
343 * Only Linux applications should call this API.
344 * @ param num [in] : Number of buffers to be locked.
345 * @ param handle [in] : Pointer to array of DMA Buf FDs of the
346 * buffers to be locked.
347 * @ return : DCE error status is returned.
348 * #DCE_EOK [0] : Success.
349 * #DCE_EOUT_OF_MEMORY [-2] : Out of Shared/Tiler Memory.
350 * #DCE_EIPC_CALL_FAIL [-5] : MmRpc Call failed.
351 * #DCE_EINVALID_INPUT [-6] : Invalid Inputs.
352 */
353 int dce_buf_lock(int num, size_t *handle)
356 /*===============================================================*/
357 /** dce_buf_unlock : Unpin or unlock Tiler Buffers which were
358 * locked to be used by the codec as
359 * reference buffers. Only Linux
360 * applications should call this API.
361 * @ param num [in] : Number of buffers to be unlocked.
362 * @ param handle [in] : Pointer to array of DMA Buf FDs of
363 * the buffers to be unlocked.
364 * @ return : DCE error status is returned.
365 * #DCE_EOK [0] : Success.
366 * #DCE_EXDM_FAIL [-1] : XDM Failure.
367 * #DCE_EOUT_OF_MEMORY [-2] : Out of Shared/Tiler Memory.
368 * #DCE_EXDM_UNSUPPORTED [-3] : Unsupported XDM request.
369 * #DCE_EIPC_CALL_FAIL [-5] : MmRpc Call failed.
370 * #DCE_EINVALID_INPUT [-6] : Invalid Inputs.
371 */
372 int dce_buf_unlock(int num, size_t *handle)
375 /*===============================================================*/
376 /** dce_get_fd : Get OMAP DRM File Descriptor. Only Linux
377 * applications should call this API.
378 * @ return : OMAP DRM File Descriptor.
379 */
380 int dce_get_fd()
383 /*===============================================================*/
384 /** dce_set_fd : Set OMAP DRM File Descriptor. Only Linux
385 * applications should call this API.
386 * @ param fd [in] : OMAP DRM File Descriptor.
387 */
388 void dce_set_fd(int fd)
391 ******************************* API call flow ******************************
393 // For a Decoder Application
394 If (BUILDOS_LINUX) {
395 dev = dce_init()
396 }
397 engine = Engine_open(String name, Engine_Attrs *attrs, Engine_Error *ec)
399 params = *dce_alloc(int sz)
400 Fill params
402 codec = VIDDEC3_create(Engine_Handle engine, String name,
403 VIDDEC3_Params *params)
405 dynParams = *dce_alloc(int sz)
406 Fill dynParams
407 status = *dce_alloc(int sz)
409 XDAS_Int32 VIDDEC3_control(VIDDEC3_Handle codec, VIDDEC3_Cmd id,
410 VIDDEC3_DynamicParams *dynParams, VIDDEC3_Status *status)
412 inBufs = *dce_alloc(int sz)
413 Fill inBufs
414 outBufs = *dce_alloc(int sz)
415 Fill outBufs
416 inArgs = *dce_alloc(int sz)
417 Fill inArgs
418 outArgs = *dce_alloc(int sz)
419 Fill outArgs
421 while(end of stream) {
422 if(BUILDOS_QNX) {
424 inBufs->descs[0].buf = virtual pointer of Input Buffer
425 outBufs->descs[0].buf = virtual pointer of Output Luma Buffer
426 outBufs->descs[1].buf = virtual pointer of Output Chroma Buffer
428 } else if (BUILDOS_LINUX || BUILDOS_ANDROID) {
430 inBufs->descs[0].buf = DMA Buf FD of Input Buffer
432 if( Output Buffer == MultiPlanar ) {
433 outBufs->descs[0].buf = DMA Buf FD of Output Luma Buffer
434 outBufs->descs[1].buf = DMA Buf FD of Output Chroma Buffer
436 } else { // Output Buffer is Single Planar
437 outBufs->descs[0].buf = DMA Buf FD of Output Luma Buffer
438 outBufs->descs[1].buf = DMA Buf FD of Output Luma Buffer +
439 Offset of Chroma Buffer
440 }
441 }
443 if (BUILDOS_LINUX) {
444 handle <- (inArgs.inputID).DMA_Buf_FD of Luma [and/or] chroma
445 dce_buf_lock(int num, size_t *handle)
446 }
448 XDAS_Int32 VIDDEC3_process(VIDDEC3_Handle codec,
449 XDM2_BufDesc *inBufs, XDM2_BufDesc *outBufs,
450 VIDDEC3_InArgs *inArgs, VIDDEC3_OutArgs *outArgs)
452 if (BUILDOS_LINUX) {
453 handle <- (outArgs.freeBufID).DMA_Buf_FD of Luma [and/or] chroma
454 dce_buf_unlock(int num, size_t *handle)
455 }
457 }
459 Void VIDDEC3_delete(VIDDEC3_Handle codec)
461 Void Engine_close(Engine_Handle engine)
463 If (BUILDOS_LINUX) {
464 dce_deinit(dev)
465 }
467 dce_free(params)
468 dce_free(dynParams)
469 dce_free(status)
470 dce_free(inBufs)
471 dce_free(outBufs)
472 dce_free(inArgs)
473 dce_free(outArgs)
477 ************ Version Info of Headers included in packages folder ***********
479 Tools:
480 XDC version : xdctools_3_25_02_70
481 CE version : codec_engine_3_24_00_08
482 XDAIS version: xdais_7_24_00_04
484 IVAHD_Codecs:
485 H.264 Dec : 02.00.13.00
486 MJPEG Dec : 01.00.11.01
487 MPEG-4 Dec : 01.00.13.00
488 VC-1 Dec : 01.00.00.11
489 MPEG-2 Dec : 01.00.12.00
490 SVC Dec : 00.06.00.00
491 H.264 Enc : 02.00.06.01
492 MJPEG Enc : 01.00.02.01
493 SVC Enc : 00.02.00.05