PM: adding suspend/resume support
[gstreamer-omap:libdce.git] / README
1 = About Distributed Codec Engine - RPMSG =
2
3 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.
4
5 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.
6
7 DCE is used by:
8 * [http://git.mansr.com/?p=omapfbplay omapfbplay]
9 * [http://github.com/robclark/gst-ducati gst-ducati]
10
11 If you are using DCE (for anything that can be revealed publicly) let me know and I'll add a link.
12
13 :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
14
15 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''.
16
17
18 = How To Build =
19
20 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).
21
22 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:
23
24 * TMS470/ARM Code Generation Tools (CGT) - 4.9.0
25 * XDC tools - 3.22.03.41
26 * BIOS (the RTOS) - 6.32.01.38
27 * Codec Engine (CE) - 3.20.00.16
28 * Framework Component (FC) - 3.20.00.22
29 * XDAIS - 7.23.00.06
30 * HDVICP2 API and HDVICP2_CODECS - 1.00.000
31 * sysbios-rpmsg - commit-id [https://github.com/ohadbc/sysbios-rpmsg/commit/885db2a4f8ae20f89ef6574e29632433e7e7de4c 885db2a4f8ae20f89ef6574e29632433e7e7de4c]
32 * libdce
33
34 On linux side, the following versions are used:
35
36 * kernel ... 3.1-rc7 plus omapdrm and omapdce
37 ** for now I am using: [https://github.com/robclark/kernel-omap4/tree/rpmsg git://github.com/robclark/kernel-omap4.git rpmsg branch]
38 * libdce userspace:  rpmsg branch
39
40
41 == Building Ducati/M3 Side ==
42
43 === Install TMS470/ARM Compiler ===
44
45 Install Code Generation Tools (CGT) from:
46
47 * https://www-a.ti.com/downloads/sds_support/CodeGenerationTools.htm
48
49 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
50
51 Install to ''$HOME/ducati/ti_cgt_tms470_<version>''
52
53 === Install XDC tools ===
54
55 Download XDC tools from:
56
57 * http://software-dl.ti.com/dsps/dsps_public_sw/sdo_sb/targetcontent/rtsc
58
59 Install to ''$HOME/ducati/xdctools_<version>''
60
61 === Install BIOS ===
62
63 Download BIOS (the RTOS) from:
64
65 * http://software-dl.ti.com/dsps/dsps_public_sw/sdo_sb/targetcontent/bios/sysbios/index.html
66
67 Install to ''$HOME/ducati/bios_<version>''
68
69 === Install Codec Engine ===
70
71 Download Codec Engine (CE) from:
72
73 * http://software-dl.ti.com/dsps/dsps_public_sw/sdo_sb/targetcontent/ce/
74
75 The lite version is fine.  Install to ''$HOME/ducati/codec_engine_<version>''
76
77 === Install Framework Components ===
78
79 Download Framework Components (FC) from:
80
81 * http://software-dl.ti.com/dsps/dsps_public_sw/sdo_sb/targetcontent/fc
82
83 The lite version without fctools is fine.  Install to ''$HOME/ducati/framework_components_<version>''
84
85 === Install XDAIS ===
86
87 Download XDAIS from:
88
89 * http://software-dl.ti.com/dsps/dsps_public_sw/sdo_sb/targetcontent/xdais/index.html
90
91 Untar to ''$HOME/ducati/xdais_<version>''
92
93 === Install HDVICP2 library codecs ===
94
95 Install HDCICP2 plus desired codecs from:
96
97 * http://software-dl.ti.com/dsps/dsps_public_sw/codecs/HDVICP2/index_FDS.html
98
99 Install to ''$HOME/ducati/'', and then untar each of the .tar files that were installed.
100
101   cd $HOME/ducati
102   for f in ivahd_*.tar; do
103     untar xf $f
104   done
105
106 You should end up with:
107
108 * ''$HOME/ducati/ivahd_hdvicp20api_01_00_00_19_production''
109 * ''$HOME/ducati/ivahd_h264dec_01_00_00_00_production''
110 * ''$HOME/ducati/ivahd_mpeg2vdec_01_00_00_00_production''
111 * ''$HOME/ducati/ivahd_jpegvdec_01_00_00_00_production''
112
113 === Setup Environment ===
114
115 Setup environment variables needed for the build steps:
116
117  dir="$HOME/ducati"
118  export TMS470CGTOOLPATH="$dir/ti_cgt_tms470_4_9_0"
119  export TMS470_C_DIR="$TMS470CGTOOLPATH/include;$TMS470CGTOOLPATH/lib"
120  XDCPATH=""
121  for f in $dir/*/packages $dir/*/cetools/packages $dir/sysbios-rpmsg/src; do
122    XDCPATH="$XDCPATH$f;"
123  done
124  export XDCPATH
125  export XDCROOT="$dir/xdctools_3_22_03_41"
126  export XDCARGS="profile=release"
127
128 Note: if you are using different version numbers, the paths would have to be adjusted accordingly.
129
130 === Build RPMSG ===
131
132 Clone ''rpmsg'' tree in ''$HOME/ducati/sysbios-rpmsg''
133
134  cd $HOME/ducati
135  git clone git://github.com/ohadbc/sysbios-rpmsg.git
136  cd sysbios-rpmsg
137
138 Build rpmsg:
139
140  $XDCROOT/xdc clean -Pr src
141  $XDCROOT/xdc -k -P `$XDCROOT/bin/xdcpkg src/ti |  egrep -v -e "/tests|/apps" | xargs`
142
143 Note: If you change ''rpmsg'', you need to rebuild ''libdce''.
144
145 === Build DCE ===
146
147 Add the bios-syslink package into the already set ''XDCPATH'' variable
148
149  export XDCPATH="$XDCPATH;$HOME/ducati/bios-syslink/packages"
150
151 Clone ''libdce'' tree in ''$HOME/ducati/libdce''
152
153  cd $HOME/ducati
154  git clone git://github.com/robclark/libdce.git
155  cd libdce
156  git checkout --track -b rpmsg origin/rpmsg
157
158 Build ducati firmware:t://github.com/robclark/libdce.git
159  
160  $XDCROOT/xdc clean -Pr ducati
161  $XDCROOT/xdc -k -Pr ducati
162
163 Copy ducati/ti/dce/ti_platform_omap4430_core0/debug/ducati-m3-core0.xem3 to your filesystem at /lib/firmware/ducati-m3-core0.xem3
164
165 == Building Linux/A9 side: ==
166
167 Standard autotools build for cortex-a9 side userspace components.
168
169 * kernel: 3.1-rc7 kernel
170 ** git://github.com/robclark/kernel-omap4.git
171 ** branch: rpmsg
172 * libdce: 
173 ** git://github.com/robclark/libdce.git
174 ** branch: rpmsg
175
176 == Build DCE userspace ==
177
178 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''.
179
180  cd libdce
181  ./autogen --prefix=/usr
182  make -j4
183  sudo make install
184
185 = Useful Links =
186
187 * http://www.omappedia.org/wiki/Syslink_Project
188 * http://www.omappedia.org/wiki/Syslink_3   -  the future..
189
190 = TODO =
191
192 * update instructions about syslink and TILER version dependencies.. and add instructions for building ducati image.
193 * migrate to syslink v3.0