summaryrefslogblamecommitdiffstats
path: root/README
blob: 1d637613ecd4d6f2f0dc11203cc80dedede1536f (plain) (tree)
1
2
3
4
5
6
7
8
9
                                                                           
 
                                                                          





                                                                           
                           












                                                                       

                        
                           







                                                                








                                                                

                           


                                                                     







                                           






                                                                           
         
                            

      
                          




                                         


                                      


                                                               
    


         
















                                                     


      




                                                   


                                                               

                                                                                      
 


                                                                                   
 

                                   
 

                                                                              


































































                                                                                    
                                                                   
                                                                        

                                                                           

                                                                                  




                                                                          




                                                                           


















































































































                                                                                    
            



                                                                            
                                                                                    



















































































                                                                                        
                                                                            
      
                                       

                                      
                                           

             
                        
                        
                        




                        
****************************** 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:
## FOR QNX 6.5.0 SP1 SDP ##
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

## FOR QNX 6.6.0 SDP ##
export QNX_ROOT=/opt/qnx660
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=/opt/qnx660/.qnx
export PATH=${QNX_HOST}/usr/bin:${PATH}:${QNX_CONFIGURATION}/bin

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/

To turn on DEBUG:
Update common.mk
   From:
      CCFLAGS+=-O2 -DBUILDOS_QNX=1 -DDCE_DEBUG_ENABLE=1 -DDCE_DEBUG_LEVEL=1
   To:
      CCFLAGS+=-O2 -DBUILDOS_QNX=1 -DDCE_DEBUG_ENABLE=1 -DDCE_DEBUG_LEVEL=3

Building:
make -f Makefile.qnx install

Clean:
make -f Makefile.qnx 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:
None

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 ############################

See libdce.h


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

// For example of a Decoder Application - using CE video3 interfaces to IPU (IVA-HD)
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 ***********
******** Version might not match due to no change in the interfaces ********
Tools:
XDC version  : xdctools_3_50_03_33_core
CE version   : codec_engine_3_24_00_08
XDAIS version: xdais_7_24_00_04
FC version: framework_components_3_40_02_07

IVAHD_Codecs:
H.264 Enc  : 02.00.09.01
MPEG-4 Enc : 01.00.02.01
MJPEG Enc  : 01.00.17.01
H.264 Dec  : 02.00.21.01
MPEG-4 Dec : 01.00.15.01
MPEG-2 Dec : 01.00.17.01
VC-1 Dec   : 01.00.02.05
MJPEG Dec  : 01.00.16.01