[DOC] Update ReadMe
[glsdk/libdce2.git] / README
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()
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)
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