README

= About Distributed Codec Engine - RPMSG =

DCE is a library to remotely invoke the hw accellerated codecs on IVA-HD via a syslink/rcm shim layer.  This provides access to the [http://processors.wiki.ti.com/index.php/Category:Codec_Engine Codec Engine] codec interface on the coprocessor (ducati/M3) from the host.

It is similar in purpose to remote codec engine, although at the time RCE was not supported on OMAP4430, and DCE was a simple way to get the same result.  They should be roughly interchangeable from the user's perspective, with the caveat that the DCE user should use <code>dce_alloc()</code> and <code>dce_free()</code> to allocate/free the control structures that are passed by pointer to CE APIs.

DCE is used by:
* [http://git.mansr.com/?p=omapfbplay omapfbplay]
* [http://github.com/robclark/gst-ducati gst-ducati]

If you are using DCE (for anything that can be revealed publicly) let me know and I'll add a link.

:Note: look in the README file for the latest version of this document, in particular for the required versions of various dependent components and tools, as these can change over time

A pre-built ducati appm3 image (''dce_app_m3.xem3'') is found in the firmware directory.  The ''Notify_MPUSYS_reroute_Test_Core0.xem3'' from syslink build should be used for sysm3 image.  The ''dce_app_m3.xem3'' replaces the official OpenMAX ''base_image_app_m3.xem3''.


= How To Build =

These instructions are assuming you are cross-compiling on a linux machine for ducati/M3 coprocessor side and natively building the linux/A9 host side (although the instructions for cross-compiling the host side are roughly the same).

The following gives an example of how to build.  I don't claim that it is the best or only way.  But these are the versions I am currently using:

* TMS470/ARM Code Generation Tools (CGT) - 4.9.0
* XDC tools - 3.22.03.41
* BIOS (the RTOS) - 6.32.01.38
* Codec Engine (CE) - 3.20.00.16
* Framework Component (FC) - 3.20.00.22
* XDAIS - 7.23.00.06
* HDVICP2 API and HDVICP2_CODECS - 1.00.000
* sysbios-rpmsg - commit-id [https://github.com/ohadbc/sysbios-rpmsg/commit/885db2a4f8ae20f89ef6574e29632433e7e7de4c 885db2a4f8ae20f89ef6574e29632433e7e7de4c]
* libdce

On linux side, the following versions are used:

* kernel ... 3.1-rc7 plus omapdrm and omapdce
** for now I am using: [https://github.com/robclark/kernel-omap4/tree/rpmsg git://github.com/robclark/kernel-omap4.git rpmsg branch]
* libdce userspace:  rpmsg branch


== Building Ducati/M3 Side ==

=== Install TMS470/ARM Compiler ===

Install Code Generation Tools (CGT) from:

* https://www-a.ti.com/downloads/sds_support/CodeGenerationTools.htm

See http://software-dl.ti.com/dsps/dsps_registered_sw/sdo_ccstudio/codegen/TMS470/4.9.5/exports/ti_cgt_tms470_4.9.5_setup_linux_x86.bin

Install to ''$HOME/ducati/ti_cgt_tms470_<version>''

=== Install XDC tools ===

Download XDC tools from:

* http://software-dl.ti.com/dsps/dsps_public_sw/sdo_sb/targetcontent/rtsc

Install to ''$HOME/ducati/xdctools_<version>''

=== Install BIOS ===

Download BIOS (the RTOS) from:

* http://software-dl.ti.com/dsps/dsps_public_sw/sdo_sb/targetcontent/bios/sysbios/index.html

Install to ''$HOME/ducati/bios_<version>''

=== Install Codec Engine ===

Download Codec Engine (CE) from:

* http://software-dl.ti.com/dsps/dsps_public_sw/sdo_sb/targetcontent/ce/

The lite version is fine.  Install to ''$HOME/ducati/codec_engine_<version>''

=== Install Framework Components ===

Download Framework Components (FC) from:

* http://software-dl.ti.com/dsps/dsps_public_sw/sdo_sb/targetcontent/fc

The lite version without fctools is fine.  Install to ''$HOME/ducati/framework_components_<version>''

=== Install XDAIS ===

Download XDAIS from:

* http://software-dl.ti.com/dsps/dsps_public_sw/sdo_sb/targetcontent/xdais/index.html

Untar to ''$HOME/ducati/xdais_<version>''

=== Install HDVICP2 library codecs ===

Install HDCICP2 plus desired codecs from:

* http://software-dl.ti.com/dsps/dsps_public_sw/codecs/HDVICP2/index_FDS.html

Install to ''$HOME/ducati/'', and then untar each of the .tar files that were installed.

  cd $HOME/ducati
  for f in ivahd_*.tar; do
    untar xf $f
  done

You should end up with:

* ''$HOME/ducati/ivahd_hdvicp20api_01_00_00_19_production''
* ''$HOME/ducati/ivahd_h264dec_01_00_00_00_production''
* ''$HOME/ducati/ivahd_mpeg2vdec_01_00_00_00_production''
* ''$HOME/ducati/ivahd_jpegvdec_01_00_00_00_production''

=== Setup Environment ===

Setup environment variables needed for the build steps:

 dir="$HOME/ducati"
 export TMS470CGTOOLPATH="$dir/ti_cgt_tms470_4_9_0"
 export TMS470_C_DIR="$TMS470CGTOOLPATH/include;$TMS470CGTOOLPATH/lib"
 XDCPATH=""
 for f in $dir/*/packages $dir/*/cetools/packages $dir/sysbios-rpmsg/src; do
   XDCPATH="$XDCPATH$f;"
 done
 export XDCPATH
 export XDCROOT="$dir/xdctools_3_22_03_41"
 export XDCARGS="profile=release"

Note: if you are using different version numbers, the paths would have to be adjusted accordingly.

=== Build RPMSG ===

Clone ''rpmsg'' tree in ''$HOME/ducati/sysbios-rpmsg''

 cd $HOME/ducati
 git clone git://github.com/ohadbc/sysbios-rpmsg.git
 cd sysbios-rpmsg

Build rpmsg:

 $XDCROOT/xdc clean -Pr src
 $XDCROOT/xdc -k -P `$XDCROOT/bin/xdcpkg src/ti |  egrep -v -e "/tests|/apps" | xargs`

Note: If you change ''rpmsg'', you need to rebuild ''libdce''.

=== Build DCE ===

Add the bios-syslink package into the already set ''XDCPATH'' variable

 export XDCPATH="$XDCPATH;$HOME/ducati/bios-syslink/packages"

Clone ''libdce'' tree in ''$HOME/ducati/libdce''

 cd $HOME/ducati
 git clone git://github.com/robclark/libdce.git
 cd libdce
 git checkout --track -b rpmsg origin/rpmsg

Build ducati firmware:t://github.com/robclark/libdce.git
 
 $XDCROOT/xdc clean -Pr ducati
 $XDCROOT/xdc -k -Pr ducati

Copy ducati/ti/dce/ti_platform_omap4430_core0/debug/ducati-m3-core0.xem3 to your filesystem at /lib/firmware/ducati-m3-core0.xem3

== Building Linux/A9 side: ==

Standard autotools build for cortex-a9 side userspace components.

* kernel: 3.1-rc7 kernel
** git://github.com/robclark/kernel-omap4.git
** branch: rpmsg
* libdce: 
** git://github.com/robclark/libdce.git
** branch: rpmsg

== Build DCE userspace ==

If building natively, clone ''libdce'' tree.  Otherwise, if cross-compiling, you can use the same copy you cloned on your PC when you built ''dce_app_m3.xem3''.

 cd libdce
 ./autogen --prefix=/usr
 make -j4
 sudo make install

= Useful Links =

* http://www.omappedia.org/wiki/Syslink_Project
* http://www.omappedia.org/wiki/Syslink_3   -  the future..

= TODO =

* update instructions about syslink and TILER version dependencies.. and add instructions for building ducati image.
* migrate to syslink v3.0