Getting Started Guide for DM8168 Z3 RPS
Introduction
On this page you are going to find all the necessary information to start from scratch to use the RidgeRun SDK on your DM8168 Z3 module. In the following sections we assume that you have already downloaded the EZSDK version 5.02.02.60 and that you have installed the toolchain 2009q1-203 from codesourcery as well as your DM8168 SDK following the steps on The RidgeRun installation guide.
The first section of this guide shows you how to install the EZSDK for DM8168 on your computer and how to configure a TFTP and NFS server. Subsequently, the second section contains instructions about how to configure the RidgeRun's SDK to create a SD card with all software components (uboot, kernel and filesystem) needed to boot to Linux Shell in your Z3 hardware. Using this SD card in the third and fourth section of this guide, you will be able to install on NAND images created by the SDK for kernel, uboot as well as your filesystem (JFFS2, UBI, NFS are available). Using the SD card created on the second section to flash the SDK in your module is just an option because you could try to use the installer of the RidgeRun's SDK with the uboot version that is running by default in a new Z3 module, however, we cannot guaranty that it will work as we expect, hence, we recommend to use the SD card instead. Additionally, how to run opemax demos to encode and decode 1080p/h264 videos and some pipelines using gstreamer + openMax are shown. The last section of this page contains useful information about two new commands added by RidgeRun in uboot in order to handle tarballs and do copies from NAND to NAND.
On the rest of this document, we refer as $(DEVDIR) to the path where the RidgeRun SDK for DM8168 is installed
Basic preliminary work
Installing the EZSDK
1. Set the ezsdk binary as executable and set correct permissions
sudo chmod 777 ezsdk_dm816x-evm_5_02_02_60_setuplinux
2. Install EZSDK. For ubuntu versions different than Ubuntu 10.04 LTS 32-bit you will need to add the --forcehost argument to install it:
./ezsdk_dm816x-evm_5_02_02_60_setuplinux --forcehost
note: During the EZSDK installation process you will be asked for the toolchain's path, assuming that you installed it on /opt, the path that you need to provide is /opt/codesourcery/arm-2009q1/bin/
Setting up serial access to the Linux console
You use the serial port to control u-boot and Linux. The picocom terminal emulator work well for this purpose.
Setting up a TFTP server
If you are planning to use the SDK's installer to install images generated by the SDK in NAND, installing a TFTP server you will speed up downloads to the target hardware by using TFTP.
Setting up an NFS server
For application development, it is convenient to use root NFS mount file system for the target hardware. This allows you to rebuild your application on the host and immediately run the application on the target hardware with no interveining steps. You host PC needs to be configured as a NFS server for this in order to work properly.
Booting from a SD card
Setting up your Z3 module to boot from SD card
In order to boot from a SD card you need to set the MMC as the first boot device to try in the DM8168 boot sequence, this can be done configuring a correct BTMODE through the header called J20 in your Z3 module (see Fig. 1)
| 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | |short | open | open | open | open | open | open | open |
Configuring SDK to deploy firmware to a SD card
This section describes how to configure the DM8168's SDK to deploy all basic firmware components (kernel, uboot and MLO) into a bootable SD card. The RidgeRun SDK support several filesystem types (JFFS2, NFS, etc) however in this case we are going to use it on the SD card as well.
1. Set your environment variables
cd $(DEVDIR) `make env`
2. Open a make config menu
make config
running make config your SDK is going to download all basic packages needed by the SDK build system.
3. Go to Installer Configuration submenu and configure your installer as is shown in Fig.2
Using the Firmware deployment mode submenu you can set how to deploy your kernel, uboot and filesystem image into your target board. There are three options in this submenu: Attached board on communication port, Deploy all the firmware to an SD card and Create an SD card installer for flash memory.
- Attached board on communication port will allow you to send images to your target board using a serial port or a TFTP server, more details about this option are explained in the next section.
- Deploy all the firmware to an SD card tells to the installer that it must create the needed partitions on a SD card located in SD device on Linux host (please be sure that the option called Flash SD card image into loopback file instead of real SD is not selected) and that it have to install there the software's images generated by the SDK.
- Create an SD card installer for flash memory is going to create and SD card with all the logic and software's images needed to flash your NAND from the SD card.
4. Go to File System Configuration submenu and configure your filesystem as is shown in Fig.3
5. Compile your SDK
make
Installing SDK's firmware to a SD card
Once you have built your SDK, you need to install it on the SD card running make install, but before to issue this command you need to unmount your SD card, otherwise the SDK won't let you install it (in order to avoid to erase information in some of your hard disks). Let's suppose that the environment variable called $(SDNAME) contains your mount point's name.
umount /media/$(SDNAME) cd $(DEVDIR) make install
you will be asked to confirm the device that you are going to partition and format, please enter yes if it is correct. After this, the SDK will start to create a bootable SD card
Now you are ready to test your SDK booting from a SD card. Two partitions were created by the SDK: boot partition which contains the kernel, uboot and MLO image and the rootfs partition with your file system. It's important to notice that the environment of uboot is located in a *.txt file in the partition called boot, which allows you to modify it easily.
Booting from NAND
This section describes how to configure the DM8168's SDK to install the SDK's firmware in NAND as well as how to set up your Z3 module to boot from NAND. First, we are going to start flashing uboot in NAND using the SD card created in the above section, once uboot is running properly from NAND, we can start installing the kernel and finally your filesystem.
Configuring SDK to install firmware in NAND
1. Set your environment variables
cd $(DEVDIR) `make env`
2. Open a make config menu
make config
3. Go to Installer Configuration submenu and configure your installer as is shown in Fig.4
In this case, you must use the Attached board on communication port method, this will allow you to install all your firmware directly in nand by means of a serial port or by ethernet using a TFTP server. Here we are going to use a TFTP server and telnet as our communication method with the target board.
3.1 Go to the Communication method with the target board and select Telnet-serial adaptor
3.2 Configure the protocol to transfer images as TFTP
3.3 Set the IP address of your host machine in IP address of telnet-serial adaptor
3.4 Set the port number that you assigned in the telnet configuration file to the serial port where your Z3 module is connected in Network port of telnet-serial adaptor
4. Close the make config menu and save your changes.
Configuring your Filesystem type
The RidgeRun SDK for DM8168 Z3 RPS supports different filesystem types: UBI, JFFS, NFS and also as we mentioned before you can use it in your SD card as well. In this tutorial we are going to use UBI as our default filesystem.
1. Set your environment variables
cd $(DEVDIR) `make env`
2. Open a make config menu
make config
3. Go to the File System Configuration->File system image target and choose UBIFS volume. Please be sure that UBIFS sub-page size is set to 512.
4. Save your changes and compile your SDK
make
Flashing uboot, kernel and filesystem in NAND
1.Boot the RidgeRun SDK using the SD card created in the first section of this guide and stop the uboot countdown. Close your Picocom, minicom or telnet session.
U-Boot 2010.06 (Oct 05 2011 - 13:19:40) DRAM: 1 GiB Using default environment Hit any key to stop autoboot: 0 mmc1 is available reading u-boot.bin 181324 bytes read ## Starting application at 0x80800000 ... U-Boot 2010.06 (Oct 05 2011 - 13:20:03) TI8168-GP rev 1.1 ARM clk: 987MHz DDR clk: 675MHz I2C: ready DRAM: 1 GiB NAND: 256 MiB *** Warning - booting from SD, using default environment Net: <ethaddr> not set. Reading from E-fuse Detected MACID:64:7b:d4:62:e2:22 Ethernet PHY: GENERIC (x001cc914) @ 0x01 DaVinci EMAC Hit any key to stop autoboot: 0 Z3-DM8168-MOD#
2.Run make installbootloader to install uboot in NAND
make installbootloader
There is a known issue running the make installbootloader command when your Z3 module is initially running uboot from a SD card, in this case you will see the following error once the installer has flashed your uboot in NAND:
Ridgerun Linux SDK
Board configuration: DM8168 Z3 Module
Multi-core machine, using 6 out of 8 cores for building
Installation system of uboot images over TFTP for host <yourIPaddress>
Be sure u-boot is running on <yourIpAddress>:<yourTelnetPort> and no process (like termnet) is using it
Press return to continue...
Performing handshake with u-boot...
Trying to identify NAND block size... detected 0x20000
Trying to identify NAND Page size... detected 2048
Loading upgrade bootloader...
Uboot <= setenv bootcmd
Uboot <= saveenv
Configuring the network...
Uboot <= setenv autoload no
Uboot <= dhcp
Uboot <= setenv serverip <yourTFTPServerIP>
Uboot <= setenv autostart no
cp -f $(DEVDIR)/images/bootloader /srv/tftp/bootloader.$(USER).$(DEVDIRNAME).dm8168
Uboot <= tftp 0x82000000 bootloader.$(USER).$(DEVDIRNAME).dm8168
Running upgrade bootloader...
Uboot <= icache off
Uboot => go 0x82000000
Performing handshake with u-boot...
Restoring previous bootcmd value
Uboot <= setenv bootcmd 'if mmc init 0; then if run loadbootenv ; then run importbootenv ; if test -n ${uenvcmd} ; then run uenvcmd; fi ;fi ;else run nandboot;fi'
Uboot <= saveenv
Building UBOOT_MIN image for flash...
Building U-boot image for flash...
Loading UBOOT_MIN
Configuring the network...
Uboot <= setenv autoload no
Uboot <= dhcp
Uboot <= setenv serverip <yourTFTPServerIP>
Uboot <= setenv autostart no
cp -f $(DEVDIR)/images/u-boot.noxip.bin /srv/tftp/u-boot.noxip.bin.$(USER).$(DEVDIRNAME).dm8168
Uboot <= tftp 0x82000000 u-boot.noxip.bin.$(USER).$(DEVDIRNAME).dm8168
Erasing UBOOT_MIN flash space...
Uboot <= nand erase 0x0 0x40000
Uboot <= nandecc hw 2
Uboot <= nand write 0x82000000 0x0 0x40000
Uboot <= nandecc sw
Loading U-Boot
Configuring the network...
Uboot <= setenv autoload no
Uboot <= dhcp
Uboot <= setenv serverip <yourTFTPServerIP>
Uboot <= setenv autostart no
cp -f $(DEVDIR)/images/bootloader.nandbin /srv/tftp/bootloader.nandbin.$(USER).$(DEVDIRNAME).dm8168
Uboot <= tftp 0x82000000 bootloader.nandbin.$(USER).$(DEVDIRNAME).dm8168
Erasing U-Boot flash space...
Uboot <= nand erase 0x40000 0x40000
Uboot <= nand write 0x82000000 0x40000 0x40000
Restarting u-boot
Error: failed to detect u-boot restarting.
make: *** [installbootloader] Error 255
However, uboot is flashed in nand properly. Please ignore this error, this will be fixed in the next release.
3.Turn off your Z3 module and configure it to boot from NAND (please see Setting up your Z3 module to boot from NAND). Turn on your module and repeat step 1.
4. Now, to install your kernel and filesytem run make install
make install
Now you have installed all the SDK components in your DM8168 Z3 module and you should be able to boot to Linux shell and see the logo of RigeRun on the HDMI output. The RidgeRun SDK for DM8168 Z3 module loads automatically all the firmware and kernel modules needed to use the video processor subsystem.
Setting up your Z3 module to boot from NAND
In order to boot from a NAND you need to set it as the first boot device to try in the DM8168 boot sequence, this can be done configuring a correct BTMODE through the header called J20 in your Z3 module (see Fig. 5)
| 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | | open | open | short | open | short | open | open | short |
OpenMax Demos
To run the openMax's demos that are located by default in your filesystem in a directory called omx you need to run first the following commands in your Z3 module
Video initialization
echo 0 > /sys/devices/platform/vpss/graphics0/enabled echo 0 > /sys/devices/platform/vpss/graphics1/enabled echo 0 > /sys/devices/platform/vpss/graphics2/enabled
note: To run the decode display/encode demo with a 1080p video we recommend to use your filesystem by NFS due to the size of the input and output file.
Decode display demo
This demo is the decode-display demo included in the EZSDK. It takes an input file encoded in H264, decodes the stream and sends the output to the HDMI output
./omx/decode_display_a8host_debug.xv5T -i inputFile.h264 -w 1920 -h 1080 -f 60 -g 0
Using Gstreamer
Some examples of use of GStreamer to implement basic multimedia pipelines can be found at DM81xx GStreamer Pipelines - SDK 2011Q2. Please be aware that in order to display video you need to do the Video initialization
Additional uboot commands
Description
In this page you are going to find information about additional commands added by RidgeRun in uboot for the DM816x, the main functions of these commands are:
1. Copy a block of data from NAND to NAND and decompress the data (gz or bz) on the fly if that is specified in the command
nand copy dest src size [gz|bz] - Read data from one section of flash, optionally decompress it, and write it to another section of flash
dest - destination flash address, must be even sector boundary
src - source flash address, must be even sector boundary. If data is compressed, then all header data will be stored here, as in the beginning of a bz2 archive
size - number of source bytes to copy; does not have to be even sector boundary; destination size may be larger if source is compressed
[gz|bz] - decompression algorithm
gz: MIME type application/x-gzip
bz: MIME type application/x-bzip2
Furthermore, we added a nand md5sum command that can be used to verify the integrity of the data that was copied in nand
nand md5sum src size [gz|bz] - Calculate the md5 sum for a region of flash, optionally decompressing the data
2. Add the ability to handle tarballs in uboot, list the content of the tarball, cat a desired file that is contained in the tarball, computes the md5sum of the desired tarball or load the tarball from a SD or USB drive, decompress it, take the desired file and write it to NAND. Currently in these commands just gz decompression algorithm is supported and soon we are going to add bz.
tar - tar archive
Usage:
tar list fat <interface> <dev[:part]> <tarfilename> [<alg>]
tar cat fat <interface> <dev[:part]> <tarfilename> <filename> [<alg>]
tar md5sum fat <interface> <dev[:part]> <tarfilename> <filename> [<alg>]
tar write_nand fat <interface> <dev[:part]> <tarfilename> <filename> <off> [<alg>]
Parameters:
<interface> :== file system interface name
<dev[:part]> :== file system device and partition number
<tarfilename> :== name of tarball file on the specified storage media
<filename> :== name of file of interest which is contained in the tarball
<off> :== destination NAND address
<alg> :== [gz] - decompression algorithm
gz: MIME type application/x-gzip
Configuring SDK to use tar commands
Due to limitations in the DM8168, the size of uboot cannot exceed 255KB (more info here). However, the tar commands increase the uboot size to ~300KB, due to this limitation we have implemented a model based in two stages to handle uboot. First, the SDK creates a uboot.min (<255KB) which doesn't have the tar commands, this uboot is loaded by the ROM code in the DM8186 without problems and performs the initialization of the board. Subsequently, this uboot.min loads a second uboot (~300KB) which contains all the logic to implement the tar commands. Please notice that this process adds ~1second to the boot process.
The Ridgerun SDK has logic to handle this approach based in two stages (including the installation process), in order to enabled the two stage model please follow this steps:
1. Open the make config menu
cd $DEVDIR make config
2. Enable two stages model
Location: │
-> Bootloader Configuration
[*] Enable two stages model for uboot
3. Close the make config menu and save your changes
note: It is important to mention that if you are NOT using the two stages model in uboot you must verify that the definition CONFIG_CMD_TAR is not present in your uboot configuration file ($DEVIDR/u-boot-2010.06/src/include/configs/dm8168_z3.h)
Examples
In this section you are going to find examples about how to use the additional commands provided by RidgeRun.
Please notice that the tar commands can be used to load files from a SD card or from a USB drive, it is important to mention that if you want to load the tarball from the SD card you need to initialize the SD card running the following command:
Z3-DM8168-MOD# mmc init 0 mmc0 is availableMoreover, if you want to use a USB drive you need to initialize it with:Z3-DM8168-MOD# usb reset (Re)start USB... USB: scanning bus for devices... 1 USB Device(s) found scanning bus for storage devices... 1 Storage Device(s) found:RidgeRun 2011Q2 SDK User Guide :EZSDK Memory Map :OMX EZSDK Examples :TMS320DM816x DaVinci Digital Media Processor :Technical Reference Manual