aboutsummaryrefslogtreecommitdiffstats
path: root/README
blob: b52b5719fc5e41ad051a17f94b7cd2d60cf8332f (plain) (blame)
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
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
****************************** LIBDCE README ******************************

The libDCE component provides an interface for applications running on the
MPU (HLOS) to invoke the Codec Engine APIs on the remote core (IPU). It
enables the Video Encode/Decode Usecases. Apart from the exposed CE APIs,
it provides a memplugin utility to allocate memory that can be read/written
from the remote IPU core.

This ReadMe file comprises:
1. LibDCE Build Information
   a. For QNX
   b. For Linux
   c. For Android
2. Supported API information
   a. Codec Engine APIs
   b. libDCE APIs
3. API call flow
   a. Decoder Application
4. Version Info of Headers included in packages folder

****************************** BUILD INFO *****************************

########################### For QNX ###########################

Exporting QNX variables:
export QNX_ROOT=/opt/qnx650
export QNX_HOST=${QNX_ROOT}/host/linux/x86
export LD_LIBRARY_PATH=${QNX_HOST}/usr/lib
export QNX_TARGET=${QNX_ROOT}/target/qnx6
export MAKEFLAGS=-I${QNX_TARGET}/usr/include
export QNX_CONFIGURATION=/etc/qnx
export QNX_JAVAHOME=${QNX_ROOT}/_jvm
export PATH=${QNX_HOST}/usr/bin:${PATH}:${QNX_CONFIGURATION}/bin
export QNX_USERNAME=<registered email-id at QNX> //not important
eval `qconfig -n "QNX Software Development Platform 6.5.0" -e`

If previous eval doesn't work, that is it doesn't output the following:
"
export QNX_HOST="/opt/qnx650/host/linux/x86";
export QNX_TARGET="/opt/qnx650/target/qnx6";
export PATH="/opt/qnx650/host/linux/x86/usr/bin:/opt/qnx650/host/linux/x86/bin:/opt/qnx650/host/
linux/x86/sbin:/opt/qnx650/host/linux/x86/usr/sbin:/opt/qnx650/host/linux/x86/usr/photon/appbuilder:
/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/etc/qnx/bin:/etc/qnx/bin:
/opt/qnx650:/etc/qnx/bin:/etc/qnx/bin:/etc/qnx/bin:/etc/qnx/bin";
export LD_LIBRARY_PATH="/opt/qnx650/host/linux/x86/usr/lib";
export MAKEFLAGS="-I/opt/qnx650/target/qnx6/usr/include";
"

then try:
/opt/qnx650/host/linux/x86/usr/bin/qconfig -n "QNX Software Development Platform 6.5.0" -e

Exporting LIBDCE variables:
export IPCHEADERS=<path to IPC Headers>
export INSTALL_ROOT=<path for copying output binaries>
export QCONF_OVERRIDE=<absolute path to libdce/nto/qconf-override.mk>

For IPCHEADERS - Headers should be at:
$(IPCHEADERS)/usr/include/memmgr
$(IPCHEADERS)/usr/include/ti/syslink/
$(IPCHEADERS)/usr/include/ti/ipc/mm
$(IPCHEADERS)/usr/include/ti/shmemallocator
$(IPCHEADERS)/usr/include/

Building:
make install

Clean:
make clean

Location of Binaries:
INSTALL_ROOT/armle-v7/usr/lib/libdce.so
INSTALL_ROOT/armle-v7/usr/lib/libdce.so.1
INSTALL_ROOT/armle-v7/bin/dce_test
INSTALL_ROOT/armle-v7/bin/dce_enc_test


########################## For Linux ##########################

Exporting LIBDCE variables:
export IPC_HEADERS=<path to IPC Headers> (MmRpc.h)

Building:

    user@target:~/libdce# ./autogen.sh --prefix=/usr
    This will check for required packages, compiler,
    headers and generates the Makefile. --prefix=/usr
    will confirure the install directory to /usr

    user@target:~/libdce# make
    Running make will build the library. It generates
    the shared objects, static library, libdce.la
    file for linking (Used by libtool) and
    libdce.pc used for querying using pkg-config.

    user@target:~/libdce# make install
    Installs the library files(libdce.so*, libdce.a,
    libdce.la) to $(--prefix)/lib.
    Installs libdce.pc to $(--prefix)/lib/pkgconfig
    Installs libdce.h and required headers to
    $(--prefix)/include/dce/

Clean:

    user@target:~/libdce# make clean
    This will clean the build. Run make to build.
    user@target:~/libdce# make distclean
    This will clean the build and remove Makefiles.
    Follow build steps above to build again.

######################### For Android #########################

Project clone:
    This project is included into Android manifest and cloned into Android Filesystem.

Building:
    "make" at Android root level will build libdce libraries along with filesystem.
    for individual component building, execute the below command

    cd mydroid/hardware/ti/omap4xxx
    mm

Location of binary:
    libdce.so is created at mydroid/out/target/product/jacinto6evm/system/lib/


******************************* API DETAILS *******************************

######################### Codec Engine APIs #########################

/*==================================================================*/
/** Engine_open        : Codec Engine Exposed API to open
 *                       Codec Engine.
 * @ param name  [in]  : Name of Encoder or Decoder codec.
 * @ param attrs [in]  : Pointer to Engine Attributes structure.
                         NULL is valid.
 * @ param ec    [out] : Pointer to Engine Error structure for Codec
 *                       to write error code. NULL is valid.
 * @ return            : Codec Engine Handle is returned to be used
 *                       to create codec.
 *                       In case of error, NULL is returned.
 */
Engine_Handle Engine_open(String name, Engine_Attrs *attrs, Engine_Error *ec)


######################### VIDDEC3 APIs #########################
/*==================================================================*/
/** VIDDEC3_create      : Create Decoder codec.
 *
 * @ param engine  [in] : Engine Handle obtained in Engine_open() call.
 * @ param name    [in] : Name of Decoder codec.
 * @ param params  [in] : Pointer to Static parameters structure of codec
 *                        allocated using dce_alloc() API.
 * @ return             : Codec Handle is returned to be used for
 *                        future CE calls.
 *                        In case of error, NULL is returned.
 */
VIDDEC3_Handle VIDDEC3_create(Engine_Handle engine, String name,
                              VIDDEC3_Params *params)


/*==================================================================*/
/** VIDDEC3_control       : Codec control call.
 *
 * @ param codec     [in] : Codec Handle obtained in VIDDEC3_create() call.
 * @ param id        [in] : Command id for XDM control operation.
 * @ param dynParams [in] : Pointer to dynamic parameters structure
 *                          of codec allocated using dce_alloc() API.
 * @ param status   [out] : Pointer to status parameters structure
 *                          of codec allocated using dce_alloc() API.
 *                          If 'id' is XDM_GETVERSION, then
 *                          status->data.buf should have a pointer to a
 *                          buffer allocated through dce_alloc() API.
 * @ return               : DCE error status of control call is returned.
 *                #DCE_EOK              [0]  : Success.
 *                #DCE_EXDM_FAIL        [-1] : XDM Failure.
 *                #DCE_EXDM_UNSUPPORTED [-3] : Unsupported XDM request.
 *                #DCE_EIPC_CALL_FAIL   [-5] : MmRpc Call failed.
 *                #DCE_EINVALID_INPUT   [-6] : Invalid Inputs.
 */
XDAS_Int32 VIDDEC3_control(VIDDEC3_Handle codec, VIDDEC3_Cmd id,
                           VIDDEC3_DynamicParams *dynParams, VIDDEC3_Status *status)


/*==================================================================*/
/** VIDDEC3_process      : Decode process call.
 *
 * @ param codec   [in]  : Codec Handle obtained in VIDDEC3_create() call.
 * @ param inBufs  [in]  : Pointer to Input Buffer Descriptor structure
 *                         of codec allocated using dce_alloc() API.
 *                         inBufs->descs[0].buf should have a virtual pointer
 *                         to the Input Buffer in QNX. In Linux, it
 *                         should have a DMA Buf FD to the Input Buffer.
 *                         In Android, it should have the memheader pointer
 *                         and the memheader->offset should have
 *                         the offset for the actual data within the input buffer;
 *                         memheader->offset = pInBufHeader->nOffset;
 * @ param outBufs [in]  : Pointer to Output Buffer Descriptor structure
 *                         of codec allocated using dce_alloc() API.
 *                         outBufs->descs[0].buf and outBufs->descs[1].buf
 *                         should have virtual pointers to the Output
 *                         Luma and Chroma Buffers respectively in QNX.
 *                         In Linux these fields should have
 *                         DMA Buf FDs to the Output Buffers. In Android
 *                         these fields should have the memheader pointer,
 *                         and the memheader->offset should have the offset
 *                         for the actual data with in the outbuffer.
 * @ param inArgs  [in]  : Pointer to Input Arguments structure
 *                         of codec allocated using dce_alloc() API.
 * @ param outArgs [out] : Pointer to Output Arguments structure
 *                         of codec allocated using dce_alloc() API.
 * @ return              : DCE error status of process call is returned.
 *                #DCE_EOK              [0]  : Success.
 *                #DCE_EXDM_FAIL        [-1] : XDM Failure.
 *                #DCE_EXDM_UNSUPPORTED [-3] : Unsupported XDM request.
 *                #DCE_EIPC_CALL_FAIL   [-5] : MmRpc Call failed.
 *                #DCE_EINVALID_INPUT   [-6] : Invalid Inputs.
 */
XDAS_Int32 VIDDEC3_process(VIDDEC3_Handle codec,
                           XDM2_BufDesc *inBufs, XDM2_BufDesc *outBufs,
                           VIDDEC3_InArgs *inArgs, VIDDEC3_OutArgs *outArgs)


/*===============================================================*/
/** VIDDEC3_delete       : Delete Decode codec instance.
 *
 * @ param codec  [in]   : Codec Handle obtained in VIDDEC3_create() call.
 * @ return : NIL.
 */
Void VIDDEC3_delete(VIDDEC3_Handle codec)


######################### VIDDENC2 APIs #########################
/*==================================================================*/
/** VIDENC2_create      : Create Encoder codec.
 *
 * @ param engine  [in] : Engine Handle obtained in Engine_open() call.
 * @ param name    [in] : Name of Encoder codec.
 * @ param params  [in] : Pointer to Static parameters structure of codec
 *                        allocated using dce_alloc() API.
 * @ return             : Codec Handle is returned to be used for
 *                        future CE calls.
 *                        In case of error, NULL is returned.
 */
VIDENC2_Handle VIDENC2_create(Engine_Handle engine, String name,
                              VIDENC2_Params *params)


/*==================================================================*/
/** VIDENC2_control       : Codec control call.
 *
 * @ param codec     [in] : Codec Handle obtained in VIDENC2_create() call.
 * @ param id        [in] : Command id for XDM control operation.
 * @ param dynParams [in] : Pointer to dynamic parameters structure
 *                          of codec allocated using dce_alloc() API.
 * @ param status   [out] : Pointer to status parameters structure
 *                          of codec allocated using dce_alloc() API.
 *                          If 'id' is XDM_GETVERSION, then
 *                          status->data.buf should have a pointer to a
 *                          buffer allocated through dce_alloc() API.
 * @ return               : DCE error status of control call is returned.
 *                #DCE_EOK              [0]  : Success.
 *                #DCE_EXDM_FAIL        [-1] : XDM Failure.
 *                #DCE_EXDM_UNSUPPORTED [-3] : Unsupported XDM request.
 *                #DCE_EIPC_CALL_FAIL   [-5] : MmRpc Call failed.
 *                #DCE_EINVALID_INPUT   [-6] : Invalid Inputs.
 */
XDAS_Int32 VIDENC2_control(VIDENC2_Handle codec, VIDENC2_Cmd id,
                           VIDENC2_DynamicParams *dynParams, VIDENC2_Status *status)


/*==================================================================*/
/** VIDENC2_process      : Encode process call.
 *
 * @ param codec   [in]  : Codec Handle obtained in VIDENC2_create() call.
 * @ param inBufs  [in]  : Pointer to Input Buffer Descriptor structure
 *                         of codec allocated using dce_alloc() API.
 *                         inBufs->planeDesc[0].buf and inBufs->planeDesc[1].buf
 *                         should have virtual pointers to the Output
 *                         Luma and Chroma Buffers respectively in QNX.
 *                         In Linux/Android, these fields should have
 *                         DMA Buf FDs to the Output Buffers.
 * @ param outBufs [in]  : Pointer to Output Buffer Descriptor structure
 *                         of codec allocated using dce_alloc() API.
 *                         OutBufs->descs[0].buf should have a virtual pointer
 *                         to the Input Buffer in QNX. In Linux/Android, it
 *                         should have a DMA Buf FD to the Input Buffer.
 * @ param inArgs  [in]  : Pointer to Input Arguments structure
 *                         of codec allocated using dce_alloc() API.
 * @ param outArgs [out] : Pointer to Output Arguments structure
 *                         of codec allocated using dce_alloc() API.
 * @ return              : DCE error status of process call is returned.
 *                #DCE_EOK              [0]  : Success.
 *                #DCE_EXDM_FAIL        [-1] : XDM Failure.
 *                #DCE_EXDM_UNSUPPORTED [-3] : Unsupported XDM request.
 *                #DCE_EIPC_CALL_FAIL   [-5] : MmRpc Call failed.
 *                #DCE_EINVALID_INPUT   [-6] : Invalid Inputs.
 */
XDAS_Int32 VIDENC2_process(VIDENC2_Handle codec,
                           IVIDEO2_BufDesc *inBufs, XDM2_BufDesc *outBufs,
                           VIDENC2_InArgs *inArgs, VIDENC2_OutArgs *outArgs)


/*===============================================================*/
/** VIDENC2_delete       : Delete Encode codec instance.
 *
 * @ param codec  [in]   : Codec Handle obtained in VIDENC2_create() call.
 * @ return : NIL.
 */
Void VIDENC2_delete(VIDENC2_Handle codec)


/*==================================================================*/
/** Engine_close       : Codec Engine Exposed API to Close Engine.
 *
 * @ param engine [in] : Engine Handle obtained in Engine_open() call.
 */
Void Engine_close(Engine_Handle engine)


############################ libDCE APIs ############################

/*==================================================================*/
/** dce_alloc          : Allocate the Data structures passed to
 *                       codec-engine APIs except Input/Output buffers.
 * @ param sz    [in]  : Size of memory to be allocated.
 * @ return            : Pointer to allocated memory.
 */
void *dce_alloc(int sz)


/*==================================================================*/
/** dce_free           : Free the Data structures passed to codec-engine APIs
 *                       allocated through the dce_alloc() API.
 * @ param ptr   [in]  : Pointer to allocated memory.
 */
void dce_free(void *ptr)


/*================ The below APIs are LINUX specifc ================*/
/*==================================================================*/
/** dce_init           : Initialize DCE. Only Linux applications
 *                       should call this API.
 * @ return            : Pointer to omap_device structure.
 */
void *dce_init(void)


/*===============================================================*/
/** dce_deinit         : Deinitialize DCE. Only Linux applications
 *                       should call this API.
 * @ param dev    [in] : Pointer to omap_device structure.
 */
void dce_deinit(void *dev)


/*===============================================================*/
/** dce_buf_lock          : Pin or lock Tiler Buffers which would be
 *                          used by the codec as reference buffers.
 *                          Only Linux applications should call this API.
 * @ param num    [in]    : Number of buffers to be locked.
 * @ param handle [in]    : Pointer to array of DMA Buf FDs of the
 *                          buffers to be locked.
 * @ return               : DCE error status is returned.
 *                #DCE_EOK              [0]  : Success.
 *                #DCE_EOUT_OF_MEMORY   [-2] : Out of Shared/Tiler Memory.
 *                #DCE_EIPC_CALL_FAIL   [-5] : MmRpc Call failed.
 *                #DCE_EINVALID_INPUT   [-6] : Invalid Inputs.
 */
int dce_buf_lock(int num, size_t *handle)


/*===============================================================*/
/** dce_buf_unlock       : Unpin or unlock Tiler Buffers which were
 *                         locked to be used by the codec as
 *                         reference buffers. Only Linux
 *                         applications should call this API.
 * @ param num    [in]   : Number of buffers to be unlocked.
 * @ param handle [in]   : Pointer to array of DMA Buf FDs of
 *                         the buffers to be unlocked.
 * @ return              : DCE error status is returned.
 *                #DCE_EOK              [0]  : Success.
 *                #DCE_EXDM_FAIL        [-1] : XDM Failure.
 *                #DCE_EOUT_OF_MEMORY   [-2] : Out of Shared/Tiler Memory.
 *                #DCE_EXDM_UNSUPPORTED [-3] : Unsupported XDM request.
 *                #DCE_EIPC_CALL_FAIL   [-5] : MmRpc Call failed.
 *                #DCE_EINVALID_INPUT   [-6] : Invalid Inputs.
 */
int dce_buf_unlock(int num, size_t *handle)


/*===============================================================*/
/** dce_get_fd         : Get OMAP DRM File Descriptor. Only Linux
 *                       applications should call this API.
 * @ return            : OMAP DRM File Descriptor.
 */
int dce_get_fd()


/*===============================================================*/
/** dce_set_fd         : Set OMAP DRM File Descriptor. Only Linux
 *                       applications should call this API.
 * @ param fd    [in]  : OMAP DRM File Descriptor.
 */
void dce_set_fd(int fd)


******************************* API call flow ******************************

// For a Decoder Application
If (BUILDOS_LINUX) {
    dev = dce_init()
}
    engine = Engine_open(String name, Engine_Attrs *attrs, Engine_Error *ec)

    params = *dce_alloc(int sz)
    Fill params

    codec = VIDDEC3_create(Engine_Handle engine, String name,
                              VIDDEC3_Params *params)

    dynParams = *dce_alloc(int sz)
    Fill dynParams
    status = *dce_alloc(int sz)

    XDAS_Int32 VIDDEC3_control(VIDDEC3_Handle codec, VIDDEC3_Cmd id,
                               VIDDEC3_DynamicParams *dynParams, VIDDEC3_Status *status)

    inBufs = *dce_alloc(int sz)
    Fill inBufs
    outBufs = *dce_alloc(int sz)
    Fill outBufs
    inArgs = *dce_alloc(int sz)
    Fill inArgs
    outArgs = *dce_alloc(int sz)
    Fill outArgs

    while(end of stream) {
        if(BUILDOS_QNX) {

            inBufs->descs[0].buf = virtual pointer of Input Buffer
            outBufs->descs[0].buf = virtual pointer of Output Luma Buffer
            outBufs->descs[1].buf = virtual pointer of Output Chroma Buffer

        } else if (BUILDOS_LINUX || BUILDOS_ANDROID) {

            inBufs->descs[0].buf = DMA Buf FD of Input Buffer

            if( Output Buffer == MultiPlanar ) {
                outBufs->descs[0].buf = DMA Buf FD of Output Luma Buffer
                outBufs->descs[1].buf = DMA Buf FD of Output Chroma Buffer

            } else {          // Output Buffer is Single Planar
                outBufs->descs[0].buf = DMA Buf FD of Output Luma Buffer
                outBufs->descs[1].buf = DMA Buf FD of Output Luma Buffer +
                                        Offset of Chroma Buffer
            }
        }

        if (BUILDOS_LINUX) {
            handle <- (inArgs.inputID).DMA_Buf_FD of Luma [and/or] chroma
            dce_buf_lock(int num, size_t *handle)
        }

        XDAS_Int32 VIDDEC3_process(VIDDEC3_Handle codec,
                                   XDM2_BufDesc *inBufs, XDM2_BufDesc *outBufs,
                                   VIDDEC3_InArgs *inArgs, VIDDEC3_OutArgs *outArgs)

        if (BUILDOS_LINUX) {
            handle <- (outArgs.freeBufID).DMA_Buf_FD of Luma [and/or] chroma
            dce_buf_unlock(int num, size_t *handle)
        }

    }

    Void VIDDEC3_delete(VIDDEC3_Handle codec)

    Void Engine_close(Engine_Handle engine)

If (BUILDOS_LINUX) {
    dce_deinit(dev)
}

    dce_free(params)
    dce_free(dynParams)
    dce_free(status)
    dce_free(inBufs)
    dce_free(outBufs)
    dce_free(inArgs)
    dce_free(outArgs)



************ Version Info of Headers included in packages folder ***********

Tools:
XDC version  : xdctools_3_25_04_88
CE version   : codec_engine_3_24_00_08
XDAIS version: xdais_7_24_00_04
FC version: framework_components_3_24_02_15

IVAHD_Codecs:
H.264 Enc  : 02.00.07.01
H.264 Dec  : 02.00.15.01
MJPEG Dec  : 01.00.12.01
MPEG-2 Dec : 01.00.13.01
MPEG-4 Enc : 01.00.02.01
MPEG-4 Dec : 01.00.14.01
VC-1 Dec   : 01.00.00.11