Introduction

Welcome to the DRA7xx GLSDK Software Developer's Guide.

Thank you for choosing the DRA7xx evm for your application. The purpose of this guide is to get you going with developing software for the DRA7xx on a Linux development host only.

Note! All instructions in this guide are for Ubuntu 12.04. At this time, this is the only supported Linux host distribution for development.

Some commands are to be executed on the Linux development host, some on the Linux target and some on the u-boot (bootloader) prompt. The following conventions are used to distinguish the commands on a host and on the target:

host $ <this command is to be executed on the host>
target # <this command is to be executed on the target>
u-boot :> <this command is to be executed on the u-boot prompt>

Starting your software development

Setup up ARM linux development Environment on the host. Please refer to this link to see how to set one up.

Configuration of ARM Linux development Environment

Step 1: Install the GLSDK release on the host machine.

Download the GLSDK installer for your platform.
If necessary make the installer executable manually by executing:

host $ chmod +x ti-glsdk_dra7xx-evm_7_03_00_03_linux-installer.bin

Execute the installer on the host and follow the instructions:

host $ ./ti-glsdk_dra7xx-evm_7_03_00_03_linux-installer.bin

Step 2: Setup the GLSDK environment variable to the location where the GLSDK is installed (the following assumes that GLSDK was installed at default location):

host $ export GLSDK="${HOME}/ti-glsdk_dra7xx-evm_7_03_00_03"

Step 3: Setup the GLSDK on host
The GLSDK comes with a script for setting up your Ubuntu 12.04 LTS development host. It is an interactive script, but if you accept the defaults by pressing return you will use the recommended settings. This is recommended for first time users. Note that this script requires ethernet access as it will update your Ubuntu Linux development host with the packages required to develop using the GLSDK.
Note: Please make sure that the proxy settings are done for http, https, git, ftp and wget before proceeding further.
Execute the script in the GLSDK release directory using:

host $ cd ${GLSDK}
host $ ./setup.sh

The setup script would perform the following operations:

Installs all the necessary package on the host for the SDK.
Prepares the UART terminal to communicate with the target over Debug USB on Minicom. If you want to use a windows host for connecting to the target instead, see the #Setting_up_Tera_Term section
Setups the linaro cross compiler
Installs the dependencies for the repo tool.
Initialize the repo by pointing it to GLSDK release manifest location.

To start minicom on your Linux development host execute minicom -w (or Tera Term on Windows).

Step 4: Prepare SD card
To install the release image, you need a µSD Card (at least 4GB) with 2 partitions:

boot (vfat) partition.
rootfs (ext4 or ext3) partition.

The following procedure prepares the sdcard: (however, the user can choose to do it manually as well)

Plug an SD card reader to your PC and insert a µSD card. It must be at least 4GB size.
Identify which device corresponds to the SD card reader. sudo fdisk -l command can help you find out where the µSD Card is mapped. We will call it /dev/sdY here.

Note : If you are using NFS file system, then edit ${GLSDK}/board-support/pre-built-images/boot.script.sd, add "ip=dhcp" in bootargs.

Re-format your µSD card with this script mksdboot.sh from the bin directory in the GLSDK

$ sudo ${GLSDK}/bin/mksdboot.sh --device /dev/sdY --sdk ${GLSDK}

The above script would prepare the SD card with the prebuilt images and yocto filesystem for SD boot.

Step 5: Booting the board
To boot the board with the above created SD card, refer to the Quick Start Guide at the GLSDK download location (https://software-dl.ti.com/dsps/dsps_public_sw/glsdk/latest/index_FDS.html) to setup the board.
Then, power cycle the board and login with username as root.

Repo tool Usage

Starting source code development using repo tool

The GLSDK release uses the repo tool to effectively manage the different components of the GLSDK.

NOTE :

1: The first step to the repo tool is the repo initialization and this is done as part of the $GLSDK/setup.sh script

2: The repo tool is downloaded into the bin folder in the GLSDK directory. Please ensure that this path is updated in the environment variable as shown below

host $  export PATH=${GLSDK}/bin:$PATH

The GLSDK release contains a helper script that sets up the development environment. Run the script as shown below:

host $ cd ${GLSDK}
host $ ./bin/fetch-sources.sh

The script does the following:

Check for the repo tool.
Perform repo sync
Create a branch called glsdk_dev
Checkout the branch glsdk_dev

It is expected that the development is done on the glsdk_dev branch.

How to get updates

If there are changes in the remote repositories, it could be fetched using the same script.
However, please make note of these important points.

1. The script will fetch the latest changes, and switch back to the glsdk_dev branch.
2. The new updates from the remote, will be available in the master branch.
3. The decision on whether to merge the changes to the local branch or merge the local branch to the master is left to the developer

Building Yocto Filesystem

Please ensure that the setup.sh script is run as described in Starting your software development section and answer 'yes' to fetch-sources prompt.
Before building the filesystem, ensure that the svn, http, ftp and git proxies are set correctly. Refer to the following link for these settings https://wiki.yoctoproject.org/wiki/Working_Behind_a_Network_Proxy.

Add the Linaro cross-compile toolchain path in the PATH environment variable.

host $ export PATH=<Path to Linaro cross-compile toolchain>/bin:$PATH

Run this command to as a one-time setup for the yocto build

host $ cd $GLSDK
host $ ./bin/setup-yocto.sh

For building core sdk , run the build-core-sdk.sh passing machine name as an argument.

host $ cd yocto-layers

Create a downloads directory (if building using Yocto for the first time), where the Yocto build will place the downloads. Note the path of the directory.

host $ mkdir downloads

NOTE: Please pass the same downloads directory path to the following build-script when prompted

host $ ./build-core-sdk.sh dra7xx-evm

These scripts will build the arago-glsdk-multimedia-image.

After build is complete the generated images can be found in yocto-layers/build/arago-tmp-external-linaro-toolchain/deploy/images/

Generated images
Image name	Description
arago-glsdk-multimedia-image-<MACHINE-NAME>-<DATE>.rootfs.tar.gz	This is the filesystem tarball. Copy and extract it on the rootfs partition of the boot media.
zImage-<MACHINE-NAME>.bin	zImage for the machine. Copy as zImage in /boot folder of the rootfs partition.
zImage-<MACHINE-NAME>.dtb	Copy dra7-evm.dtb in boot partition. Or choose to copy the appropriate dtb based on the display and additional boards that are connected.
u-boot-<MACHINE-NAME>.img	Copy as u-boot.img in boot partition.

Note: The build does not generate a uenv.txt. You need to copy it from the prebuilt binaries in the release.

Modifying source code and rebuilding a component

Once the Yocto setup is complete developers would like to modify a certain component source code and rebuild it. The source code for the generic components like omapdrmtest can be found in ${GLSDK}/yocto-layers/build/arago-tmp-external-linaro-toolchain/work/cortexa15hf-vfp-neon-3.8-oe-linux-gnueabi/

Steps to rebuild:

1. Modify the source of the component in its work area

2. cd to yocto-layers

  host $ cd ${GLSDK}/yocto-layers

3. export PATH if not done previously:

  host $ export PATH=<Path to Linaro cross-compile toolchain>/bin:$PATH

4. Run one/combination of the folowing tasks:

a. To configure and compile with the latest changes in the work area:

  host $ ./build-specific-recipe.sh <MACHINE-NAME> -f -c configure <RECIPE-NAME>
  host $ ./build-specific-recipe.sh <MACHINE-NAME> -f -c compile <RECIPE-NAME>

For example, if the omapdrmtest source is modified and you want to generate only the binaries for dra7xx-evm, the compile task should suffice:

  host $ ./build-specific-recipe.sh <MACHINE-NAME> -f -c compile omapdrmtest

The binaries will be present in the same folder as the source files.

b. To generate .ipk package in addition to the binaries, following additional tasks need to be run after above steps:

  host $ ./build-specific-recipe.sh <MACHINE-NAME> -f -c install <RECIPE-NAME>
  host $ ./build-specific-recipe.sh <MACHINE-NAME> -f -c package <RECIPE-NAME>
  host $ ./build-specific-recipe.sh <MACHINE-NAME> -f -c package_write_ipk <RECIPE-NAME>

This will generate .ipk packages for the recipe. They can be found in the deploy-ipks folder of the work area of the recipe.
The .ipk packages can be copied and installed on the target by:

  target $ opkg install <PACKAGE-NAME>

This approach is useful in the case of recipes that generate a large number of binaries, that are difficult to copy manually, like gst-plugins-bad.

c. During building and debugging the kernel or kernel modules, the compile_kmodules task needs to be executed that generates kernel modules.

  host $ ./build-specific-recipe.sh <MACHINE-NAME> -f -c compile_kmodules <RECIPE-NAME>

For a complete set of tasks that a specific recipe executes during its build, please refer to the log.task_order in the temp folder of the component.
Pass the relevant tasks to build-specific-recipe.sh for required outcome.

5. For a robust solution , once the change in source area is tested with the above steps, please update the recipe.

a. create a patch of the change
b. copy it in the folder where the recipe is present
c. add the patch name in the SRC_URI variable in the recipe

The build-specific-recipe.sh recognizes the change in the recipe and builds it if required.

To build a specific component after recipe is updated, use the build-specific-recipe.sh

host $ ./build-specific-recipe.sh <MACHINE-NAME> <RECIPE NAME>

For example to build omapdrmtest:

 host $ ./build-specific-recipe.sh <MACHINE-NAME> omapdrmtest

MACHINE-NAME can be either omap5-evm or dra7xx-evm

To clean a specific component:

host $ ./clean-specific-recipe.sh <MACHINE-NAME> <RECIPE NAME>

GLSDK software overview

Overview of the GLSDK Software stack

The GLSDK contains many software components. Some are developed by Texas Instruments and some are developed in and by the open source community(White). TI contributes, and sometimes even maintains, some of these open source community projects, but the support model is different from a project developed solely by TI.

Running Examples

Running OMAP DRM DSS Examples

The drmclone, drmextended, and modetest examples demonstrates how to create a CRTC (i.e. FB) and display planes (overlays) on the CRTC. Additionally, drmtest demonstrates similar functionality as the previously mentioned demos, along with dynamic plane updates for 2 CRTCs.

Retrieve the omapdrm-tests source

> git clone https://github.com/tomba/omapdrm-tests.git

> cd omapdrm-tests

Run (or example planescale)

>./planescale==Graphics Demos from Command Line ==

The graphics driver and userspace libraries and binaries are distributed along with the SDK.

To execute the demos, the graphics driver must be initialised by running pvrsrvinit.

  target # pvrsrvinit

Please make sure the board is connected to atleast one display before running these demos.

Finding Connector ID

Note: Most of the applications used in the Demos would require the user to pass a connector id. A connector id is a number that is assigned to each of the display devices connected to the system. To get the list of the display devices connected and the corresponding connector id one can use the modetest application (shipped with the file system) as mentioned below:

  target #  modetest

Look for the display device for which the connector ID is required - such as HDMI, LCD etc.

Connectors:
id  encoder status      type    size (mm)   modes   encoders
4   3   connected   unknown 0x0     1   3
  modes:
    name refresh (Hz) hdisp hss hse htot vdisp vss vse vtot)
  1280x800 60 1280 1328 1360 1404 800 804 811 823 flags: nhsync, nvsync; type: preferred, driver
...
16  11  connected   HDMI-A  700x390     31  11
  modes:
    name refresh (Hz) hdisp hss hse htot vdisp vss vse vtot)
  1280x720 60 1280 1390 1430 1650 720 725 730 750 flags: phsync, pvsync; type: preferred, driver

Usually LCD is assigned 4 (800x480), HDMI is assigned 16 (multiple resolutions).

Finding Plane ID

To find the Plane ID, run the modetest command:

  target #  modetest

Look for the section called Planes. (Sample truncated output of the Planes section is given below)

Planes:
id      crtc    fb      CRTC x,y        x,y     gamma size
19      0       0       0,0             0,0     0
 formats: RG16 RX12 XR12 RA12 AR12 XR15 AR15 RG24 RX24 XR24 RA24 AR24 NV12 YUYV UYVY
 props:
 ...
20      0       0       0,0             0,0     0
 formats: RG16 RX12 XR12 RA12 AR12 XR15 AR15 RG24 RX24 XR24 RA24 AR24 NV12 YUYV UYVY
 props:
 ...

kmscube

Run kmscube on default display (LCD):

  target # kmscube

Run kmscube on secondary display (HDMI):

  target # kmscube -c <connector-id>
  target # kmscube -c 16 #Usually, the connector id for HDMI is 16.

Run kmscube on all connected displays (LCD & HDMI & FPDLink(optional)):

  target # kmscube -a

kmscube with video

A new demo has been added into the GLSDK starting with 6.10.00.01 release.This demo allows a video frame to be applied as a texture onto the surface of the kmscube. The user can invoke the demo by following the syntax below:

  target # viddec3test <path_to_the_file> --kmscube --connector <connector_number>

Run kmscube with video on default display (LCD):

  target # viddec3test <path_to_the_file> --kmscube

Run kmscube with video on secondary display (HDMI):

  target # viddec3test <path_to_the_file> --kmscube --connector 16 #Usually, the connector id for HDMI is 16.

Additionally, to change the field of view of the rotating cube, the user can specify the same on the command line like below:

  target # viddec3test <path_to_the_file> --kmscube --connector <connector_number> --fov <number>

Wayland/Weston

Starting from GLSDK 6.04, the supported Wayland/Weston version brings in the multiple display support in extended desktop mode and the ability to drag-and-drop windows from one display to the other.

To execute the demos, the graphics driver must be initialized by running pvrsrvinit if this has not been done earlier.

  target # pvrsrvinit

To launch weston, do the following:

On default display (LCD):

  target # weston --tty=1 --connector=4

On secondary display (HDMI):

  target # weston --tty=1 --connector=16

On the third display (FPD link):

  target # weston --tty=1 --connector=21

On all connected displays (LCD, HDMI and FPDLink):

  target # weston --tty=1

By default, the screensaver timeout is configured to 300 seconds.

The user can change the screensaver timeout using a command line option

 --idle-time=<number of seconds>

For example, to set timeout of 10 minutes and weston configured to display on all connectors, use the below command:

 weston --tty=1 --idle-time=600

To disable the screen timeout and to configure weston configured to display on all connectors, use the below command:

 weston --tty=1 --idle-time=0

If you face any issues with the above procedure, please refer GLSDK_FAQs#Unable_to_run_Weston_on_the_GLSDK_release for troubling shooting tips.

The filesystem comes with a preconfigured weston.ini file which will be located in /home/root/.config/weston.ini after running the initialization steps.

Running weston clients

There is one icon on the top right hand corner of the weston desktop window which has been configured for

weston-terminal

Clicking this icon should launch the applications on the Weston Desktop.

It is possible to add other icons by editing the weston.ini file.

There are several other applications that are included in the default filesystem. To invoke these applications, the user should launch the weston-terminal (top right hand corner of the desktop) and then invoke the client apps as described below from within the terminal window:

       wayland sh # /usr/bin/weston-flower
       wayland sh # /usr/bin/weston-clickdot
       wayland sh # /usr/bin/weston-cliptest
       wayland sh # /usr/bin/weston-dnd
       wayland sh # /usr/bin/weston-editor
       wayland sh # /usr/bin/weston-eventdemo
       wayland sh # /usr/bin/weston-image /usr/share/weston/terminal.png
       wayland sh # /usr/bin/weston-resizor
       wayland sh # /usr/bin/weston-simple-egl
       wayland sh # /usr/bin/weston-simple-shm
       wayland sh # /usr/bin/weston-simple-touch
       wayland sh # /usr/bin/weston-smoke
       wayland sh # /usr/bin/weston-info
       wayland sh # /usr/bin/weston-terminal

Running multimedia with Wayland sink

The GStreamer video sink for Wayland is the waylandsink. To use this video-sink for video playback:

  target # gst-launch-1.0 playbin uri=file://<path-to-file-name> video-sink=waylandsink

Exiting weston

Terminate all Weston clients before exiting Weston. If you have invoked Weston from the serial console, exit Weston by pressing Ctrl-C.

It is also possible to invoke Weston from the native console, exit Weston by using pressing Ctrl-Alt-Backspace.

IMG PowerVR Demos

The GLSDK filesystem comes packaged with example OpenGLES applications. The examples can be invoked using the below commands.

target # /opt/img-powervr-sdk/Examples/Advanced/OGLES2Coverflow
target # /opt/img-powervr-sdk/Examples/Advanced/OGLES2ChameleonMan
target # /opt/img-powervr-sdk/Examples/Advanced/OGLES2ExampleUI
target # /opt/img-powervr-sdk/Examples/Advanced/OGLES2Navigation

After you see the output on the display interface, hit q to terminate the application.

Using the PowerVR Tools

Please refer to http://community.imgtec.com/developers/powervr/graphics-sdk/ for additional details on the tools and detailed documentation.

The target file system includes tools such as PVRScope and PVRTrace recorder libraries from Imagination PowerVR SDK to profile and trace SGX activities. In addition, it also includes PVRPerfServerDeveloper toolfor Jacinto6 platform.

PVRTune

PVRPerfServerDeveloper tool can be used along with the PVRTune running on the PC to gather data on the SGX loading and activity threads. You can invoke the tool with the below command:

target # /opt/img-powervr-sdk/PVRHub/PVRPerfServer/PVRPerfServerDeveloper

PVRTrace

The default filesystem contains helper scripts to obtain the PVRTrace of the graphics application. This trace can then be played back on the PC using the PVRTrace Utility.

To start tracing, use the below commands as reference:

target # cp /opt/img-powervr-sdk/PVRHub/Scripts/start_tracing.sh ~/.
target # ./start_tracing.sh <log-filename> <application-to-be-traced>

Example:

target # ./start_tracing.sh westonapp weston-simple-egl

The above command will do the following:

Setup the required environment for the tracing
Create a directory under the current working directory called pvrtrace
Launch the application specified by the user
Start tracing the PVR Interactions and record the same to the log-filename

To end the tracing, user can invoke the Ctrl-C and the trace file path will be displayed.

The trace file can then be transferred to a PC and we can visualize the application using the host side PVRTrace utility. Please refer to the link at the beginning of this section for more details.

Running aplay and arecord application

To playback/record on the evm via headset/mic, please make sure the following amixer settings are done:

For playback via headset, enter the following at prompt target#

  amixer sset 'Left DAC Mux',0 'DAC_L2'
  amixer sset 'Right DAC Mux',0 'DAC_R2'
  amixer cset name='HP Playback Switch' On
  amixer cset name='Line Playback Switch' Off
  amixer cset name='PCM Playback Volume' 127

Once these settings are successful, use aplay application for playback:

  target #  aplay <path_to_example_audio>.wav

For recording via Mic In

  amixer cset name='Left PGA Mixer Mic3L Switch' On
  amixer cset name='Right PGA Mixer Mic3L Switch' On
  amixer cset name='Left PGA Mixer Line1L Switch' off
  amixer cset name='Right PGA Mixer Line1R Switch' off
  amixer cset name='PGA Capture Switch' on
  amixer cset name='PGA Capture Volume' 6

Once these settings are successful, use arecord to record

  target #  arecord -r 44.1 > <path_to_example_audio>.wav

Running viddec3test application

viddec3test is a demo application for decoder/video playback using hardware accelerators. The application currently runs on the kms display. The application requires the connector information for display. One can get the information of the display connected to the board by running the modetest application in the filesystem, as described above. To execute the application "modetest" make sure the display is connected to the board.

Running a decode on a display

To run a hardware decode on a display connected to the board, execute the following command:

  target #  viddec3test -s <connector_id>:<display resolution> filename --fps 30

e.g.: target # viddec3test -s 4:1920x1080 file.h264 --fps 30

Running single decode on dual displays

To run the output of a single decode on the dual displays. Please make sure both the displays are connected and get the information about the connectors and the resolution associated with it for both the displays from the modetest application.

  target #  viddec3test -s <connector_id_1>:<display resolution> -s <connector_id_2>:<display resolution> filename --fps 30

e.g.: target # viddec3test -s 4:1920x1080 -s 12:1024x768 file.h264 --fps 30

Running dual decode on dual displays

One can also run a dual decode and display their output on two different displays. Please make sure both the displays are connected and get the information about the connectors and the resolution associated with it for both the displays from the modetest application.

  target # viddec3test -s <connector_id_1>:<display resolution> filename1 -s <connector_id_2>:<display resolution> filename2

e.g.: target # viddec3test -s 4:1920x1080 file1.h264 -- -s 12:1024x768 file2.h264

Running DSP sample applications

DCE framework running on DSP1 supports C66x codecs with VIDDEC2 interface. In the current version of dspdce package, Universal_copy algorithm (with IUNIVERSAL interface) is invoked from dce VIDDEC2 interfaces. Universal_copy algorithm does simple input buffer to outbuffer memcopy. To integrate C66x codecs with VIDDEC2 interface, iuniversal interfaces needs to be replaced with ividdec2 interfaces in DCE framework.

The following are the applications that one could run from A15 to exercise the above on DSP:

copycodectest: This application is to test Universal_copy with VIDDEC2 interface. This application fills the input buffer with a number entered as argument and after process output buffer is tested for same pattern.

usage: copycodectest pattern.

Example:

  target # copycodectest 123

yuvcopytest: This applciation reads one frame of yuv of known width and height into input buffer. Luma output buffer after process call is sent to display to check if universal_copy running on DSP is properly copied to output buffer.
usage: yuvcopytest -s <connector_Id>:<mode> yuvfile -w width -h height

Example:

  target # yuvcopytest -s 4:800x480 input.yuv -w 1920 -h 1080

Running a gstreamer pipeline

GStreamer v1.2 is supported from GLSDK 7.00.00.04 onwards and GStreamer 0.10 is deprecated.

One can run an audio video file using the gstreamer playbin from the console. Currently, the supported Audio/video sink is kmssink, waylandsink and alsassink.

kmssink:
  target #  gst-launch-1.0 playbin uri=file:///<path_to_file> video-sink=kmssink audio-sink=alsasink

waylandsink:
  1. refer #Wayland/Weston to start the weston
  2. target #  gst-launch-1.0 playbin uri=file:///<path_to_file> video-sink=waylandsink audio-sink=alsasink

The following pipelines show how to use vpe for scaling, deinterlacing and color space conversion.

  1. Decode-> Deinterlace->Display
     target # gst-launch-1.0 -v filesrc location=example_interlaced_h264.mp4 ! qtdemux ! \
 h264parse ! ducatih264dec ! vpe ! kmssink

  2. Decode-> Scale->Display
     target # gst-launch-1.0 -v filesrc location=example_h264.mp4 ! qtdemux ! h264parse ! \
 ducatih264dec ! vpe ! 'video/x-raw, format=(string)NV12, width=(int)720, height=(int)480' ! kmssink

  3. Color space conversion:
     target # gst-launch-1.0 -v videotestsrc ! 'video/x-raw, format=(string)YUY2, width= \
 (int)1280, height=(int)720' ! vpe ! 'video/x-raw, format=(string)NV12, width=(int)720, height=(int)480' \
 ! kmssink

Note: 
  1. While using playbin for playing the stream, vpe plugin is automatically picked up for de-interlacing. However vpe cannot be used with playbin for scaling.
For utilizing scaling capabilities of vpe, using manual pipeline given above is recommended.
  2. From GLSDK 7.04.00.03, waylandsink can perform cropping from the cropping metadata set on buffers and does not require vpe plugin for cropping

The following pipelines show how to use v4l2src and ducatimpeg4enc elements to capture video from VIP and encode captured video respectively.

Capture and Display Fullscreen
  target #  gst-launch-1.0 v4l2src device=/dev/video1 num-buffers=1000 io-mode=4 ! 'video/x-raw, \
format=(string)YUY2, width=(int)1280, height=(int)720' ! vpe num-input-buffers=8 ! queue ! kmssink

Capture and Display to a window in wayland
  1. refer #Wayland/Weston to start the weston
  2. target #  gst-launch-1.0 v4l2src device=/dev/video1 num-buffers=1000 io-mode=4 ! 'video/x-raw, \
format=(string)YUY2, width=(int)1280, height=(int)720' ! vpe num-input-buffers=8 ! queue ! waylandsink

Capture and Encode into a MP4 file.
  target #  gst-launch-1.0 -e v4l2src device=/dev/video1 num-buffers=1000 io-mode=4 ! 'video/x-raw, \
format=(string)YUY2, width=(int)1280, height=(int)720, framerate=(fraction)30/1' ! vpe num-input-buffers=8 ! \
queue ! ducatimpeg4enc bitrate=4000 ! queue ! mpeg4videoparse ! qtmux ! filesink location=x.mp4

Capture and Encode and Display in parallel.
  target #  gst-launch-1.0 -e v4l2src device=/dev/video1 num-buffers=1000 io-mode=4 ! 'video/x-raw, \
format=(string)YUY2, width=(int)1280, height=(int)720, framerate=(fraction)30/1' ! vpe num-input-buffers=8 ! tee name=t  ! \
 queue ! ducatimpeg4enc bitrate=4000 ! queue ! mpeg4videoparse ! qtmux ! filesink location=x.mp4 t. ! queue ! kmssink

Note: For capturing in NV12 format use

 'video/x-raw, format=(string)NV12, width=(int)1280, height=(int)720'

Running VIP/VPE/CAL application

Video Input Port

Video Input Port is used to capture video frames from BT56/ BT601 Camera. Currently the VIP driver supports following features.

For more information on VIP driver and other features, please refer to https://processors.wiki.ti.com/index.php/GLSDK_VIP_driver

Standard V4L2 capture driver
Supports single planar buffers
Supports MMAP buffering method
Supports DMABUF based buffering method (GLSDK 6.04 onwards)
Supports V4L2 endpoint standard way of specifying camera nodes (GLSDK 6.04 onwards)
Supports captures upto 60FPS (GLSDK 6.04 onwards)
Multi instance capture - Currently only Vin1a, Vin2a, Vin3a, Vin5a supported (GLSDK 6.04 onwards)
Capture from a YUYV camera(8bit)
Capture from 24 bit RGB camera (GLSDK 6.04 onwards)
NV12 capture format (GLSDK 7.04 onwards)

Camera Adapter Layer

Camera Adapter Layer is used to capture video from CSI Camera. Currently the CAL driver supports following features.

Standard V4L2 capture driver
Supports single planar buffers
Supports MMAP buffering method
Supports DMABUF based buffering method (GLSDK 6.04 onwards)
Supports V4L2 endpoint standard way of specifying camera nodes (CSI bindings)
Multi instance capture - 4data lane phy0 + 2data lane phy1

Supported cameras

Camera Adapter Layer is used to capture video from CSI Camera. Currently the CAL driver supports following features. GLSDK release supports following sensors/cameras/video inputs:-

OV10635 sensor - YUYV sensor on Vision board
OV10635 sensor - YUYV sensor connected through LVDS (GLSDK 6.04 onwards)
OV10633 sensor - YUYV sensor connected on J6 EVM (GLSDK 6.04 onwards)
TVP5158 decoder - Support for decoding single channel analog video (GLSDK 6.04 onwards)
FPDlink - Output of FPDlink display can be used as a camera input source (GLSDK 6.04 onwards)
OV10640/OV490 - 720p CSI2 raw camera connected to OV490 ISP in YUYV format (GLSDK 7.04 onwards)

I2C2 v/s HDMI conflict (only in GLSDK 6.04)

On J6 EVM, i2c2 lines are pinmuxed with the HDMI DDC lines Before running VIP demos, please run following commands to enable I2C2

target# devmem2 0x4a003808 w 0x60000
target# devmem2 0x4a00380C w 0x60000
target# devmem2 0x4847C010 w 0x4
target# devmem2 0x4847C014 w 0x0

To restore HDMI DDC pins, run following commands

target# devmem2 0x4a003808 w 0x60001
target# devmem2 0x4a00380C w 0x60001
target# devmem2 0x4847C010 w 0x4
target# devmem2 0x4847C014 w 0x4

Processor SDK supports following sensors/cameras

mt9t111 camera sensor

Running dmabuftest

dmabuftest is a user space application which demonstrates capture display loopback. It can support multiple captures at the same time

Video buffers are allocated by libdrm and they are shared to VIP through dmabuf.

It interfaces with the VIP through standard v4l2 ioctls.

Arago filesystem from GLSDK release has dmabuftest app preinstalled.

To capture and display on the LCD screen, run following command target# dmabuftest -s 4:800x480 -d /dev/video1 -c 1280x720@YUYV

To capture and display on the HDMI display, run following command target# dmabuftest -s 12:1920x1200 -d /dev/video1 -c 1280x720@YUYV

To capture video in NV12 format, run following command (GLSDK 7.04 onwards)

target# dmabuftest -s 12:1920x1200 -d /dev/video1 -c 1280x720@NV12

Capturing from OV10633 onboard camera

GLSDK kernel driver for OV1063x cameras support OV10633 sensor.

Video capture can be verified from the OV10633 sensor as follows

Connect OV10633 sensor to the Leopard Imaging port on the J6 EVM
Reboot the board and enable i2c2 as given above
I2C device on Bus 2 slave address 0x37 should be probed successfully
VIP should register a V4L2 video device (e.g. /dev/video1) using this i2c device
Run dmabuftest with '1280x720@YUYV' as capture format

Capturing from OV10635 Vision board camera

GLSDK kernel driver for OV1063x cameras support OV10635 sensor.

Video capture can be verified from the OV10635 sensor as follows

Connect OV10635 sensor to the OVcam port on the Vision board
Change the SW3 switch setting on Vision board as SW3[1-8] = 01010101
Reboot the board and enable i2c2 as given above
I2C device on Bus 2 slave address 0x30 should be probed successfully
VIP should register a V4L2 video device (e.g. /dev/video1) using this i2c device
Run dmabuftest with '1280x720@YUYV' as capture format

Capturing through TVP decoder

GLSDK linux kernel supports TVP5158 NTSC/PAL decoder.

TVP5158 decoder is a TI chip which can decode upto 4 channels of NTSC/PAL analog video and multiplex it.

Currently, GLSDK 6.04 supports only 1 channel capture from TVP5158. From GLSDK 7.04 onwards, multichannel capture is supported. Change the fdtfile=dra7-evm-jamr3.dtb in uenv.txt

Video capture from 1 channel TVP5158 can be verified as follows.

Connect analog camera to the Vin1 port of the JAMR3 board
Change the SW2 switch setting on JAMR board as SW2[1-2] = [OFF, ON] - This is to select i2c4 for the IO expander
Reboot the board and enable i2c2 as given above
I2C device on Bus 2 slave address 0x58 should be probed successfully
VIP should register a V4L2 video device (e.g. /dev/video1) using this i2c device
Run dmabuftest with capture format of the analog camera (e.g. '720x240@YUYV')

Capturing through FPDlink camera

This is applicable only for 6.04.00.02 release

FPDlink camera is a device where a FPDlink deserializer can act as a camera.

On JAMR board, the FPDlink deserializer is connected to Vin1a of J6 EVM

GLSDK linux kernel has a dummy driver to control FPDlink camera

Video capture from FPDlink camera can be verified as follows.

Connect any FPDlink serializer to the JAMR board deserializer port through FPDlink cable
- Another J6 EVM can also be used to genereate FPDlink video and can be connected here
- Even loopback, where FPDlink transmitter of base board can be connected to this port
Apply patches http://review.omapzoom.org/35064 and http://review.omapzoom.org/35063 on linux kernel and rebuild
Reboot the board and enable i2c2 as given above
I2C device on Bus 2 slave address 0x20 should be probed successfully
- Note that this is a dummy driver, if this address conflict with anything else, please change in dts file
VIP should register a V4L2 video device (e.g. /dev/video1) using this i2c device
Run dmabuftest with capture format of FPDlink display (e.g. '1280x720@AR24')
- As FPDlink display transmits video in RGB format, in this case, Vin1a is configured for 24bit RGB data

Capturing through LVDS camera

LVDS camera is also a camera connected through a serializer and deserializer

GLSDK linux kernel has driver for FPDlink serializers and deserializers

For interfacing every LVDS camera with J6, an I2C slave for ser, deser and camera is needed. By default, all of the device tree nodes are disabled.

Following table shows mapping between all LVDS cameras on multi deserializer duaghter card for Vision Board.

LVDS camera    Camera address alias    Serializer address alias    Derializer address    VIP port

cam1           0x38                    0x74                        0x60                  Vin1a(VIP1 slice0 port A)
cam2           0x39                    0x75                        0x64                  Vin2a(VIP1 slice1 port A)
cam3           0x3A                    0x76                        0x68                  Vin3a(VIP2 slice0 port A)
cam4           0x3B                    0x77                        0x6C                  Vin5a(VIP3 slice0 port A)
cam5           0x3C                    0x78                        0x61                  Vin4b(VIP2 slice1 port B)
cam6           0x3D                    0x79                        0x69                  Vin6a(VIP3 slice1 port A)

Also, the ser/deser drivers fight with HDMI driver for using I2C lines as I2c vs DDC. Therefore, when using LVDS cameras, we need to disable HDMI.

To disable HDMI and enable all the LVDS cameras, apply the patches attached here.

For 6.04 release:- Enable_LVDS_Cameras.zip

For 6.10 release:- Enable_LVDS_Cameras.zip

For 7.00 release:- No need to disable HDMI, no extra patches needed. Change the fdtfile=dra7-evm-vision.dtb in uenv.txt

For 7.01 release:- No need to disable HDMI, no extra patches needed. Rebuild the DTB and bootloader with vision config. Change the fdtfile=dra7-evm-vision.dtb in uenv.txt

For 7.02 release:- No need to disable HDMI, no extra patches needed. Rebuild the DTB and bootloader with vision config. Change the fdtfile=dra7-evm-vision.dtb in uenv.txt

Video capture from LVDS camera can be verified as follows.

Connect a LVDS camera to cam1/2/3/4 port of Multides board.
Change the SW3 switch setting on Vision board as SW3[1-8] = 00100101
Apply attached patches on linux kernel and rebuild
I2C device on Bus 2 slave address (e.g. 0x38 for cam1) should be probed successfully
VIP should register a V4L2 video device (e.g. /dev/video1) using this i2c device
Run dmabuftest with '1280x720@YUYV' as capture format

Capturing through OV10640/OV490 CSI camera/ISP

GLSDK linux kernel supports CSI capture from OV10640 RAW camera and OV490 ISP.

CAL works on the CSI2 protocol and supports both raw and YUYV capture. GLSDK is verified with the OV10640 raw camera and OV490 ISP. TI-EVM has support for capturing via two CSI phys. - phy0 (4data lanes) and phy1 (2data lanes)

Video capture from OV490 can be verified as follows.

Connect OV10640 camera to the OV490 board
Connect the OV490 board to the TI-EVM via the CSI2 dual 490 adaptor board
I2C device on Bus 4 slave address 0x24 should be probed successfully
VIP should register a V4L2 video device (e.g. /dev/video1) using this i2c device
Run dmabuftest with capture format of the analog camera (e.g. '1280x720@YUYV')

Video Processing Engine(VPE)

VPE supports Scalar, Colour Space Conversion and Deinterlace.It uses V4L2 mem2mem API.

Supported Input formats: nv12, yuyv, uyvy

Supported Output formats: nv12, yuyv, uyvy, rgb24, bgr24, argb24, abgr24

Not Supported formats: yuv444, yvyu, vyuy, nv16, nv61, nv21

File to File

 testvpe

 Usage:
 <SRCfilename> <SRCWidth> <SRCHeight> <SRCFormat> <DSTfilename> <DSTWidth> <DSTHeight> <DSTformat> <interlace> <translen>

Note:

<interlace> : set 1, If input is interlaced and want deinterlaced(progressive) output. output height should be twice of input height.

Deinterlace(DI):-

target# testvpe frame-176-144-nv12-inp.yuv 176 144 nv12 progressive_output.nv12 176 288 nv12 1 1

Scalar(SC):-

target# testvpe frame-176-144-nv12-inp.yuv 176 144 nv12 frame-1920-1080-nv12-out.nv12 1920 1080 nv12 0 1

Colour Space Conversion(CSC):-

target# testvpe frame-720-240-yuyv-inp.yuv 720 240 yuyv frame-720-240-argb32-out.argb32 720 240 argb32 0 1

SC+CSC+DI:-

target# testvpe frame-720-240-yuyv-inp.yuv 720 240 yuyv frame-1920-1080-rgb24-dei-out.rgb24 1920 1080 rgb24 1 1

File to Display

 filevpedisplay

 Usage:
 <src_filename> <src_w> <src_h> <src_format> <dst_w> <dst_h> <dst_format> <top> <left> <w> <h> <inter> <trans> -s <conn_id>:<mode>

Input without crop:

target# filevpedisplay frame-176-144-nv12-inp.yuv 176 144 nv12 800 480 yuyv 0 0 176 144 0 1 -s 4:800x480

Input with crop:

target# filevpedisplay frame-176-144-nv12-inp.yuv 176 144 nv12 800 480 yuyv 16 32 128 128 0 1 -s 4:800x480

VIP-VPE-Display

Support for this is added from GLSDK 6.04 onwards Camera captures the frames, which are processed by VPE(SC, CSC, Dei) then displays on LCD/HDMI.

 capturevpedisplay

 Usage:
 <src_w> <src_h> <src_format> <dst_w> <dst_h> <dst_format> <inter> <trans> -s <conn_id>:<mode>

target# capturevpedisplay 640 480 yuyv 320 240 uyvy 0 1 -s 4:640x480 Template:Glsdk CAL

Running DSS application

DSS applications are omapdrm based. These will demonstrate the clone mode, extended mode, overlay window, z-order and alpha blending features. To demonstrate clone and extended mode, HDMI display must be connected to board. Application requires the supported mode information of connected displays and plane ids. One can get these information by running the modetest application in the filesystem.

  target #  modetest

Running drmclone application

This displays same test pattern on both LCD and HDMI (clone). Overlay window also displayed on LCD. To test clone mode, execute the following command:

  target #  drmclone -l <lcd_w>x<lcd_h> -p <plane_w>x<plane_h>:<x>+<y> -h <hdmi_w>x<hdmi_h>

e.g.: target # drmclone -l 1280x800 -p 320x240:0+0 -h 640x480

We can change position of overlay window by changing x+y values. eg. 240+120 will show @ center

Running drmextended application

This displays different test pattern on LCD and HDMI. Overlay window also displayed on LCD. To test extended mode, execute the following command:

  target # drmextended -l <lcd_w>x<lcd_h> -p <plane_w>x<plane_h>:<x>+<y> -h <hdmi_w>x<hdmi_h>

e.g.: target # drmextended -l 1280x800 -p 320x240:0+0 -h 640x480

Running drmzalpha application

Z-order:

It determines, which overlay window appears on top of the other.

Range: 0 to 3

lowest value for bottom

highest value for top

Alpha Blend:

It determines transparency level of image as a result of both global alpha & pre multiplied alpha value.

Global alpha range: 0 to 255

0 - fully transparent

127 - semi transparent

255 - fully opaque

Pre multipled alpha value: 0 or 1

0 - source is not premultiply with alpha

1 - source is premultiply with alpha

To test drmzalpha, execute the following command:

  target # drmzalpha -s <crtc_w>x<crtc_h> -w <plane1_id>:<z_val>:<glo_alpha>:<pre_mul_alpha> -w <plane2_id>:<z_val>:<glo_alpha>:<pre_mul_alpha>

e.g.: target # drmzalpha -s 1280x800 -w 19:1:255:1 -w 20:2:255:1

Testing with FPDLink Display setup

H/W setup

DRA7xx EVM + 12V supply for the EVM.
FPDLink Cable between DRA7xx and De-serilzer board (DS90UB928Q).
5V power supply for De-serializer board.
LCD Adapter board (DS90UH928Q) that sits on De-serializer board.
LCD Adapter cable which is between LCD panel and the Adapter board.
12V power supply for LCD Adapter board.
The actual LCD panel (LG101(10.1in) or AUO (7.1 in))
Please refer the picture which shows the overall setup attached here

Kernel Config shouldn't be necessary since the supported panels and fpdlink are built into the kernel

Kernel Configuration

    -> Device Drivers
      -> Graphics support
        -> OMAP2+ Display Subsystem support (OMAP2_DSS [=y])
          -> OMAP2/3 Display Device Drivers
            <*> LG101 LCD Panel
    -> Device Drivers
      -> Graphics support
        -> OMAP2+ Display Subsystem support (OMAP2_DSS [=y])
          -> OMAP2/3 Display Device Drivers
            <*> SERLINK
    -> Device Drivers
      -> Graphics support
        -> OMAP2+ Display Subsystem support (OMAP2_DSS [=y])
          -> OMAP2/3 Display Device Drivers
            <*> DSERLINK

Make CONFIG_NUM_CRTCS=3 and add the following line to dra7-evm.dts and dra7xx-evm-lcd10.dtsi (or dra7x-evm-lcd-osd.dtsi)

               aliases {
               display0 = &hdmi; 
               display1 = &fpd_disp;
                ...

Change status of disp_ser in dra7-evm.dts from "disabled" to "ok"

       disp_ser: serializer@1b {
               status = "ok";
               
                ...

Testing

On power-cycle, the EVM should boot and show the Tux Logo.
Given below is a snippet from the modetest - it should show the FPDLink Display connected via the following path. The connector-id, crtc-id or plane-ids may change based on the release or kernel version.

Encoders:
id      crtc    type    possible crtcs  possible clones
3       10      TMDS    0x00000003      0x00000000
11      14      TMDS    0x00000002      0x00000000 ---------------------------> FPDLink

Connectors:
id      encoder status          type    size (mm)       modes   encoders
4       3       connected       unknown 0x0             1       3
  modes:
        name refresh (Hz) hdisp hss hse htot vdisp vss vse vtot)
  800x480 60 800 841 890 931 480 493 497 526 flags: nhsync, nvsync; type: preferred, driver
  props:
        1 EDID:
                flags: immutable blob
                blobs:

                value:  2 DPMS:
                flags: enum
                enums: On=0 Standby=1 Suspend=2 Off=3
                value: 0
12      11      connected       unknown 0x0             1       11 -----------> FPDLink
  modes:
        name refresh (Hz) hdisp hss hse htot vdisp vss vse vtot)
  1280x800 57 1280 1312 1360 1440 800 804 807 814 flags: nhsync, nvsync; type: preferred, driver
  props:
        1 EDID:
                flags: immutable blob
                blobs:

                value:  2 DPMS:
                flags: enum
                enums: On=0 Standby=1 Suspend=2 Off=3
                value: 0

Configuring OSD 10.1 Display (Rev H board)

Set device tree file to "dra7-evm-lcd-osd.dtb"

Enable EDT_FT5x06 Touchscreen Controller

Edit file

board-support/linux/ti_config_fragments/connectivity.cfg

- CONFIG_TOUCHSCREEN_EDT_FT5X06=m + CONFIG_TOUCHSCREEN_EDT_FT5X06=y

Gsttestplayer

gsttestplayer is a gstreamer test application useful for testing some features not testable with gst-launch-1.0 such as:

Seek - Seeking to random points in a stream
Trick play - Playback at different speeds (fast forward, rewind)
Pause, Resume
Playing multiple streams simultaneously in the same process, in a loop or one after another.

Running gsttestplayer

Command line options:

  target # gsttestplayer -h
        Usage: gsttestplayer <options>
                -s <sinkname>    Specify the video sink name to be used, default: kmssink
                -n               Do not use VPE, implies no scaling
                -r <width>x<height> Resize the output to widthxheight, no scaling if left blank
                -a               Play with no A/V Sync
                -c <cmds file>   Non-interactive mode, reading commands from <cmds file>
                --help-gst                        Show GStreamer Options

Example: To use waylandsink and resize the output video to 800x400.

  target # gsttestplayer -s waylandsink -r 800x400

In normal mode, when -c option is not used, the application enters an command prompt at which the user enter various commands. Type "help" to print out the list of possible commands:

  target # gsttestplayer -s waylandsink -r 800x400
        Scaling output to 800x400
        Using videosink=waylandsink
        <Enter ip> help
        Commands available:
        start  <instance num> <filename/capture device>
        stop   <instance num>
        pause  <instance num>
        resume <instance num>
        seek   <instance num> <seek to time in seconds> <optional: playback speed>
        sleep  <sleep time in seconds>
        msleep <sleep time in milliseconds>
        rewind <line number> <rewind command file go to line number>
        exit
        <Enter ip>

Example commands:

start 0 KMS_MPEG4_D1.MP4  # Start playing the file "KMS_MPEG4_D1.MP4", using instance 0.
start 1 NTSC_h264.mp4     # Start playing the file "NTSC_h264.mp4" (simultaneously) using instance 1.
stop 0                    # Stop playback of instance 0.
seek 0 0 2                # Seek to "0"th second mark of the stream playing in instance 0,
                          #  and start playing back at speed 2x.
seek 0 300 -1             # Seek to "300"th second mark of the stream playing in instance 0,
                          #  and start playing back reserve at speed 1x.
start 2 /dev/video1       # Start capturing from /dev/video1 using the v4l2src plugin

All these commands could be put into a text file and given as input to gsttestplayer with the "-c" option. In this case, gsttestplayer runs non-interactively, reading commands from the text file one line after another. The commands sleep and rewind are useful for this mode, to introduce delays or to create a loop respectively.

Notes:

This application plays video only. Audio path is not used.
The input filename should have the correct file extension to indicate the type of file. The supported extensions are "mp4", "avi", "ts", "asf" & "wmv".
The input filename should contain the string "264", "mpeg2", "mpeg4" or "vc1"/"wmv" to indicate which video codec should be used for decoding - H.264, MPEG-2, MPEG-4 or Windows Media Video.
If the input filename is a video device which matches /dev/videoX pattern, v4l2src plugin would be used for video capture instead of playback.
Decode and capture can be run in parallel depending on the sink being used.

Running IPC examples

GLSDK includes makefile targets to ease the process of building IPC and the examples.

Target	Purpose
ipc_ipu	Build the libraries and examples for IPU0 and IPU1
ipc_dsp	Build the libraries and examples for the DSP1 and DSP2
ipc_mpu	Build the userspace libraries for A15 and the examples

You can directly build the IPU and DSP applications from the root of the GLSDK installation by running

host $ make ipc_ipu ipc_dsp

Build the A15 user space libraries requires that linux kernel is built as well. Please ensure the kernel is built by running

host $ make linux

and then

host $ make ipc_mpu

User space sample application

MessageQ is the user space API provided for IPC. The sample application for MessageQ consists of an application "MessageQApp" running on the A15 and corresponding binaries running on the remotecore. The below table shows the paths under which the remotecore binaries can be found and the expected path on the target file system.

Core	Binary path on host relative to $GLSDK/component-sources/ipc_xx	Binary path on target file system
DSP2	./packages/ti/ipc/tests/bin/ti_platforms_evmDRA7XX_dsp2/messageq_single.xe66	/lib/firmware/dra7-dsp2-fw.xe66
IPU2	./packages/ti/ipc/tests/bin/ti_platforms_evmDRA7XX_ipu2/messageq_single.xem4	/lib/firmware/dra7-ipu2-fw.xem4
IPU1	./packages/ti/ipc/tests/bin/ti_platforms_evmDRA7XX_ipu1/messageq_single.xem4	/lib/firmware/dra7-ipu1-fw.xem4
DSP1	./packages/ti/ipc/tests/bin/ti_platforms_evmDRA7XX_dsp1/messageq_single.xe66	/lib/firmware/dra7-dsp1-fw.xe66

MessageQApp can be found in the path ./linux/src/tests/.libs/MessageQApp from the ipc package root. Copy this file to /usr/bin on the target filesystem.

lad_dra7xx can be found in the path ./linux/src/daemon/.libs/lad_dra7xx from the ipc package root. Copy this file to /usr/bin on the target filesystem.

Boot the target and invoke the lad daemon

target # /usr/bin/lad_dra7xx

Sometimes the lad daemon may already be running at boot. Use the ps command to check if the lad daemon is already running. Please ensure that the lad daemon has not been started with the -g option.

Start the MessageQApp

target # /usr/bin/MessageQApp <number of messages> <core id>

The core id to be used is 1,2,3,4 for IPU2,IPU1,DSP2 and DSP1 respectively.

RPMsg client sample application

RPMsg is the kernel space IPC and the building block for the user space MessageQ IPC API. The below wiki page illustrates how to build and run an rpmsg Linux kernel space client to communicate with a slave processor (e.g. DSP, IPU, etc) using IPC's RPMsg module.

RPMsg_Kernel_Client_Application

Running basic Wifi tests

To run this test, you would need to have the Wilink COM module connected to the EVM.

Check if the wlan0 interface is showing up:

target # ifconfig -a

Bring up the wlan0 inteface:

target # ifconfig wlan0 up

Search for the available Wifi networks:

target # iw wlan0 scan | grep -i ssid

Running basic Bluetooth tests

To run this test, you would need to have the Wilink COM module connected to the EVM. Make sure that this module supports the Bluetooth.

target # hciconfig hci0 up
target # hciconfig -a

Turn on the Bluetooth on the device that you want to pair and make it discoverable, then run the following command:

target # hcitool scan

How to bring up the GNSS driver and sample application

WL8 GNSS driver that is compatible with GLSDK is now available as part of the click wrap license at the following location. https://www.ti.com/tool/wilink-sw

Users are requested to register and obtain the package.

The package contains the driver source and the required documentation.

The document "Bring up manual for WiLink8 GNSS driver on Linux" is the starting point that contains the instructions for compiling and trying the sample application.

NOTE: These instructions are known to work if the user starts with the GLSDK installer and compiles the Linux kernel using the instructions provided in the GLSDK Software Developers Guide.

Booting EVM with different modes

Choosing the correct device tree (GLSDK 7.00.00.04 onwards)

Booting Linux kernel needs to have a kernel image(zImage) and device tree blob(DTB) file. DTB file describes the hierarchy of the devices, and also describes various parameters about the devices.

Depending on which CPU board and application board you are trying to boot, there are different set of devices. For each permutation, there is a different DTB file describing all devices on baseboard as well as application board.

GLSDK release comes with most commonly used permutations of device trees. Following table shows the name of the device tree file to be used for each of the combination.

**Device tree file (DTB) options**
Board	DTB name
J6 EVM + 10inch LCD	dra7-evm-lcd10.dtb
J6 EVM + 7inch LCD	dra7-evm-lcd7.dtb
J6 EVM + 10inch LCD + Vision app board	dra7-evm-vision.dtb
J6 EVM + 10inch LCD + JAMR3 app board	dra7-evm-lcd10.dtb (Base board DTB works for JAMR3 as well)
J6eco EVM + 10inch LCD	dra72-evm-lcd10.dtb
J6eco EVM + 7inch LCD	dra72-evm-lcd7.dtb
J6eco EVM + 10inch LCD + JAMR3 app board	dra72-evm-lcd10.dtb (Base board DTB works for JAMR3 as well)

GLSDK bootloader tries to detect the platform (J6/J6eco) and assume But this can be overwritten via uenv.txt used by u-boot.

e.g. Add the following line in the uenv.txt file if booting a J6 EVM with 7inch LCD and JAMR3 app board.

fdtfile=dra7-evm-jamr3.dtb

Choosing the correct bootloader config (GLSDK 7.01.00.03 onwards)

GLSDK 7.01.00.03 onwards, all the padmux is performed from the first stage bootloader (MLO) instead of the kernel. Also, the bootloader takes care of configuring all the required PADs as well as the IOdelay configuration. Depending on the use case, boot loader needs to know the required pads to be configured at the boot time. Kernel would know the device information from DTB file but bootloader does not know which DTB file would be used by the kernel.

For this reason, we need to rebuild the bootloader (MLO) with a different config so that the appropriate PAD and IODELAY configuration is performed as required by the use case. GLSDK default bootloader works for most of the use cases.

When using vision use cases, rebuild the bootloader with dra7xx_evm_vision_config.

Use following commands to rebuild bootloader for vision use cases:-

 host $ make dra7xx_evm_vision_config
 host $ make

Supported Boot modes

The same U-Boot image shipped with the SDK can be used to boot the system in following different modes based on the boot switch settings:

MMC/SD
eMMC
Uart
QSPI
NAND

Using QSPI Boot

QSPI is a serial peripheral interface like SPI the major difference being the support for Quad read, uses 4 data lines for read compared to 2 lines used by the traditional SPI.

Supported boot modes

QSPI Production Boot mode
QSPI Development Boot mode

QSPI Production Boot Mode

This boot mode also called as 'spl_early_boot' in GLSDK

In this boot mode SPL(first stage of Uboot) directly boots the Linux kernel and if IPU late attach is enabled, it boots the IPU slave core
The executables - MLO, dtb, uImage & IPU are stored in QSPI flash memory. Refer the "Memory Layout" section for offset details.
eMMC partition 2 contains the filesystem & is mounted as rootfs.
Build MLO and u-boot.img for QSPI boot mode (use "dra7xx_evm_qspiboot_config").Rename MLO to "MLO.qspi" and u-boot.img to "u-boot.img.qspi". Note: The mk-qspi-boot.sh will look for MLO.qspi and u-boot.img.qspi while flashing to qspi device. Make sure file name is renamed correctly.

SYS BOOT Switch Settings

change the boot switches to QSPI boot mode as:

SW2[5:0] = 110110 for development (jump to u-boot)
SW2[5:0] = 110111 for production mode (jump to MLO->kernel)
Also
SW5.4 = 0 (OFF)

Memory Layout of QSPI Flash

+----------------+ 0x00000
|      MLO       |
|                |
+----------------+ 0x040000
|   u-boot.img   |
|                |
+----------------+ 0x140000
|   DRA7-evm.dtb |
+----------------+ 0x1c0000
|   u-boot env   |
+----------------+ 0x1d0000
|   u-boot env   |
|    (backup)    |
+----------------+ 0x1e0000
|                |
|     uImage     |
|                |
|                |
+----------------+ 0x9e0000
|                |
|     IPU exe    |
|                |
+----------------+

Add choosen node in DTSI file

In 'spl_early_boot' mode the kernel boot arguments are get passed through DTB 'chosen' node. Add a 'chosen' node into dra7.dtsi file and generate the DRA7-evm.dtb file.

chosen
{
  bootargs = "elevator=noop console=ttyO0,115200n8 root=<rootfs> rw rootwait earlyprintk fixrtc omapdrm.num_crtc=2
  consoleblank=0  cma=64M rootfstype=ext4";
};
where <rootfs> can be /dev/mmcblk0p2 for eMMC or /dev/mmcblk1p2 for mmc/sd.

Flashing the Image to QSPI from linux

The mk-qspi-boot.sh will be available at home direcotry of GLSDK filesystem. The mk-qspi-boot.sh runs on the target. It reads the binaries (MLO.qspi, u-boot.img.qspi, kernel/dtb, ipu images) from MMC/SD and flashes into QSPI flash memory at appropriate partition described in above table. For 'spl_early_boot'. Also format & flash the rootfs into eMMC parition 2.

Usage:
target#mk-qspi-boot.sh --device1  --device2 --bootmode

--device1 - devfs entry for qspi flash as char device node
			e.g /dev/mtd

--device2 - devfs entry for eMMC flash as block device node
			e.g /dev/mmcblk1

--bootmode - 'spl_early_boot' & 'two_stage_boot'
			 spl_early_boot - ROM=>SPL=>uImage
			 two_stage_boot - ROM=>SPL=>u-boot.img=>uImage
e.g
target#: mk-qspi-boot.sh --device1 /dev/mtd --device2 /dev/mmcblk1 --bootmode spl_early_boot

Note: Defualt DTB is dra7-evm-lcd10.dtb. Do change DTB in script if you want to boot the board with different device tree.

QSPI Development Boot Mode

This boot mode also called as 'two_stage_boot' in GLSDK

In this boot mode SPL(first stage of Uboot) brings-up u-boot.img(second part of u-boot) and if IPU late attach is enabled, it also boots the IPU slave core
The second stage of u-boot, then, loads & boots the Linux kernel.
Build MLO and u-boot.img for QSPI boot mode (use "dra7xx_evm_qspiboot_config").Rename MLO to MLO.qspi and u-boot.img to u-boot.img.qspi
Only MLO and u-boot.img are stored in QSPI flash memory.
DTB & uImage are stored in MMC/SD boot parition.
IPU executable is stored in <mmc_rootfs>/lib/firmware/dra7-ipu2-fw.xem4.
The rootfs is mounted from MMC/SD partition 2

SYS BOOT Switch Settings

change the boot switches to QSPI boot mode as:

SW2[5:0] = 100110 for development (jump to u-boot)
SW2[5:0] = 100111 for production mode (single stage)
Also,
SW5.4 = 0 (OFF)

Flashing UBoot to QSPI from linux

The mk-qspi-boot.sh will be available at home direcotry of GLSDK filesystem. The mk-qspi-boot.sh runs on the target . It reads the executables from MMC/SD & flashes into QSPI flash memory for 'two_stage_boot'

target#mk-qspi-boot.sh --device1  --device2 --bootmode

--device1 - devfs entry for qspi flash as char device node
			e.g /dev/mtd

--device2 - devfs entry for eMMC flash as block device node
			e.g /dev/mmcblk1

--bootmode - 'spl_early_boot' & 'two_stage_boot'
			 spl_early_boot - ROM=>SPL=>uImage
			 two_stage_boot - ROM=>SPL=>u-boot.img=>uImage
e.g
target#: mk-qspi-boot.sh --device1 /dev/mtd --device2 /dev/mmcblk1 --bootmode two_stage_boot

Note: Defualt DTB is dra7-evm-lcd10.dtb. Do change DTB in script if you want to boot the board with different device tree.

Also QSPI flash can be accessed from kernel through MTD device.

Following commands demonstrate how to flash MLO and u-boot from SD card to QSPI.

target# mount /dev/mmcblk1p1 /mnt
target# cat /proc/mtd
target# flash_erase -N /dev/mtd0 0 1
target# flash_erase -N /dev/mtd4 0 16
target# mtd_debug write /dev/mtd0 0x0 $(ls -l /mnt/MLO {{!}} awk '{ print $5 }') /mnt/MLO
target# mtd_debug write /dev/mtd4 0x0 $(ls -l /mnt/u-boot.img {{!}} awk '{ print $5 }') /mnt/u-boot.img

Flashing UBoot to QSPI from UBoot

UBoot can be flashed to QSPI from any boot mode, here we are using MMC boot mode as an example
Boot from SD card and at the U-Boot prompt, Choose the mmc card to read from

uboot# mmc dev 0
uboot# mmc0 is current device

Probe the flash to see if there is a device connected,

NOTE: Do NOT copy-paste the commands, please type them at the prompt

 # sf probe 0
 SF: Detected S25FL256S with page size 64 KiB, total 32 MiB, mapped at 5c000000

Erase flash before writing the bin

NOTE: Do NOT copy-paste the commands, please type them at the prompt

 # sf erase <offset> +<size>
 where,
  offset - qspi flash offset address start from 0.
  size   - erase region size. This is automatically rounded up to the block size.
 # sf write <memory address> <offset> <len>
 where,
   memory-address - source data to read from
   offset - qspi offset location to write
   len    - length of the data to be written

Load the MLO.qspi (to offset 0x0) and u-boot-qspi.img(to offset 0x40000) to QSPI flash

Flashing MLO to QSPI
uboot# fatload mmc 0 0x82000000 MLO.qspi
uboot# sf erase 0 +${filesize}
uboot# sf write 0x82000000 0x0 ${filesize}

Flashing u-boot.img to QSPI
uboot# fatload mmc 0 0x83000000 u-boot-qspi.img
uboot# sf erase 40000 60000;
uboot# sf write 0x83000000 0x40000 0x60000

Build kernel to create uImage and dtb files. Load the uImage(to offset 1e0000) and DTB files (to offset 140000) to QSPI flash

Flashing kernel(uImage) to QSPI
uboot# fatload mmc 0 0x82000000 uImage
uboot# sf erase 1e0000 500000;
uboot# sf write 82000000 1e0000 500000;

Flashing dtb file to QSPI
uboot# fatload mmc 0 0x83000000 <dtb file>
uboot# sf erase 140000 20000;
uboot# sf write 0x83000000 0x140000 0x20000

After reset, you should be able to boot from QSPI flash.

NOTE: QSPI_4 boot mode is not supported on PG1.0.

Using eMMC Boot

eMMC boot method is the same as MMC/SD flashing and booting procedure. MMC/SD card must be formatted with the correct partitions prior to flashing any device. Once the MMC/SD is configured it will contain two separate partitions that will be used to boot the device. The FAT32 partition is used for uboot (MLO,u-boot.img,boot.scr, boot.scr.eMMC) and kernel (uImage, dtb file). The ext4 partitions is used for the actual file system. Once both of these are loaded onto an MMC/SD the device can boot up and run the selected file system

Boot switches for eMMC boot

change the boot switches for eMMC boot mode as:

SYSBOOT [0-15] (SW2[1-8],SW3[1-8]): 0100 0100 1000 0001

USERCONFIG[1-10] (SW5): 0010 1000 00 
O - OFF
1 - ON

Partitioning and formatting eMMC

Using eMMC is similar to using SD card. eMMC is an Embedded device. So we have to partition and format the the eMMC using kernel utility(fdisk, mkfs.msdos, mkfs.ext4) and that available in FileSystem. To partition and format eMMC, considering /dev/mmcblk1 is eMMC device, then use the following script

Note: Edit mk-eMMC-boot.sh file and make sure uenv-emmc.txt is copied to eMMC boot partition. 
 cp /tmp/sdk/$$/mmc_boot/uenv-emmc.txt /tmp/sdk/$$/emmc_boot/uenv.txt

./mk-eMMC-boot.sh --device /dev/mmcblk1

Once done, remove MMC/SD & reboot the device.now board should boot from eMMC.

Using UART boot

The GLSDK release for DRA7xx does not support boot over UART out of the box. The purpose of this template is to provide details on how to add UART-boot support on top of GLSDK release.

Boot over UART is tested on a rev D DRA7xx EVM. The ROM code can boot from UART3. By default the EVM supports UART1. Hence it is mandatory to do a hardware change to work with UART-boot.

Hardware Changes for UART-boot support

Populate resistor R776 and R777 with 50 ohm resistor.

Serial port configuration

DRA7xx EVM comes with onboard USB-to-serial converter. The USB cable supplied with the EVM can be used to connect the EVM to a host. The mini-USB end of the cable should be connected to 'J1 Terminal' connector on the EVM.

For correct operation the serial terminal software should be configured with the following settings:

* Baud rate: 115200
* Data bits: 8
* Parity: None
* Stop bits: 1
* Flow control: None
* Transmit delay: 0 msec/char, 100 msec/line

NOTE: Ensure that version 4.67 or later of Teraterm is installed. The implementation of the kermit protocol in Teraterm is not reliable in older versions. The latest version of Teraterm can be downloaded from here.

Boot Switch Settings

SW2[5:0] = 010011

Other than this,

SW5.5 = OFF for UART3 support.
        (Default = ON for UART1)

Note: Apart from this patch following changes should be taken note of:
1. dra7xx_evm_uart3_config should be used instead of dra7xx_evm_config while rebuilding u-boot.
   For this replace following line in GLSDK's Rules.make file:
   DEFAULT_UBOOT_CONFIG=dra7xx_evm_config
   to
   DEFAULT_UBOOT_CONFIG=dra7xx_evm_uart3_config

2. CONFIG_SPL_TEXT_BASE in include/configs/omap5_common.h should be manually changed from 0x40300350 to 0x40300000 for UART-boot.
   In memory boot mode ROM code transfers MLO to location OCMC_RAM1 base+offset (CONFIG_SPL_TEXT_BASE = 0x40300000+350).
   In peripheral boot mode ROM code transfers MLO to location OCMC_RAM1 base (0x40300000).
   UART-boot will not work without changing this address.

UART protocol used at various phases

ROM Code -> MLO :- binary transfer, UART3: 115.2 Kbps, 8 bits, even parity, 1 stop-bit, no flow control

MLO -> u-boot:- YModem protocol, UART3: 115.2 Kbps, 8 bits, none parity, 1 stop-bit, no flow control

u-boot -> Linux :- Kermit protocol, UART3: 115.2 Kbps, 8 bits, none parity, 1 stop-bit, no flow control

Software & Tools

The following software is needed:

- MLO & u-boot should be built for DRA7xx.

Note:
For MLO use the spl/u-boot-spl.bin file. The difference between u-boot-spl.bin and MLO is that
 u-boot-spl.bin does not contain header information. Peripheral boot needs an MLO without header.
For u-boot use u-boot.img file (and not u-boot.bin file)

- The serial-boot.pl script for transferring MLO.

Please note that this perl script is dependent on the perl Device::SerialPort module.

Perl can be downloaded from here. Let's say Perl is downloaded on Windows machine at location c:\perl.

For SerialPort module download following files from here to c:\perl

Win32-SerialPort-0.22-PPM510.tar.gz
Win32-SerialPort-0.22-PPM512.tar.gz
Win32-SerialPort-0.22-PPM514.tar.gz
Win32-SerialPort-0.22-PPM516.tar.gz
Win32-SerialPort-0.22-PPM56.tar.gz
Win32-SerialPort-0.22-PPM58.tar.gz
Win32-SerialPort.ppd

Open a cmd and cd c:\perl, run

 ppm install Win32-SerialPort.ppd

- Teraterm on Windows machine.

Boot Over UART Procedure

Loading 1st state(MLO) over UART

1. Set boot mode switch SW2 and SW5.5 as per Boot_Switch_Settings

2. Switch ON EVM with UART boot mode.

3. Open Teraterm on Windows machine and set serial port to 115.2 Kbps, 8 bits, even parity, 1 stop-bit, no flow control

4. Ensure that “VA!” characters appear on TeraTerm window continuously

5. Close the teraterm window

6. Open cmd and execute the serial-boot.pl script as follows:

 ./serial-boot.pl -p <serial-device> -s <path>/u-boot-spl.bin 

For example:
 ./serial-boot.pl -p com26 -s c:\temp\u-boot-spl.bin

You can add debug option to see debug messages when running this script
 ./serial-boot.pl -p com26 -s c:\temp\u-boot-spl.bin -d 1

Note:- If the serial-boot.pl doesn't wait for you to reset the board and if it continues saying "Board Detected" let it continue (dont reset the board here) once  done rerun the script 
       with the same paramaeters now it should actually wait for you to reset.

Note: serial-boot.pl script, after opening the COM port takes care of setting it to 115.2 Kbps, 8 bits, even parity, 1 stop-bit

7. The script will ask you to reset the EVM

8. Press "Reset button" on EVM to initiate image download

9. The download is completed when you see "Second file download completed" message.

10.After image is successfully downloaded, the ROM code will boot it.

11.MLO will then be waiting to receive u-boot over ymodem.

Note: You will NOT be able to see the MLO logs on console as teraterm is closed.

Loading 2nd stage(u-boot) over UART

The moment the serial script execution is over,

1. Open Teraterm

2. Choose File -> Transfer -> YModem -> Send

3. Select the 2nd stage u-boot image “u-boot.img” built earlier and click “OPEN” button

4. Wait for download to complete

5. u-boot will start its execution once download is completed

6. Interrupt the boot to get 2nd Stage u-boot prompt

DRA752 EVM#

Note: MLO waits to receive u-boot for maximum timeout period of 20sec. So do not fail to start u-boot transfer within 20 sec.
The actual transfer of u-boot starts after ~4-5 secs of opening the u-boot.img file.

Loading dra7-evm.dtb over UART

1. Run following command on u-boot prompt

DRA752 EVM# loadb 0x825f0000

2. Choose File -> Transfer -> Kermit -> Send

3. Select "dra7-evm.dtb" click “OPEN” button

4. Wait for download to complete

Loading uImage over UART

1. Run following command on u-boot prompt

DRA752 EVM# loadb 0x80300000

2. Choose File -> Transfer -> Kermit -> Send

3. Select "uImage" click “OPEN” button

4. Wait for download to complete

5. You can check whether uImage is downloaded properly using

iminfo

Booting uImage

Run following command on u-boot prompt

setenv bootargs 'elevator=noop console=ttyO0,115200n8 root=/dev/mmcblk0p2 rw rootwait earlyprintk fixrtc'
setenv fdt_high 0x84000000
bootm 0x80300000 - 0x825f0000

Note: 
Linux Kernel by default uses UART1 for console logs. 
In order to switch to UART3 as a default console use 'console=ttyO2' in the bootargs.
e.g. setenv bootargs 'elevator=noop console=ttyO2,115200n8 root=/dev/mmcblk0p2 rw rootwait earlyprintk fixrtc'
 
The final console where login prompt gets displayed is decided by the filesystem.
Some filesystems read the default console being used while booting up(as in bootargs) and activate that as the final console.
Some filesystems do not have this flexibility and will have a fixed final console, e.g. ttyO0.

Based on the filesystem you use to boot the kernel, the login prompt will either get displayed directly or you will have to slide SW5.5=ON to see it.

Booting Secure DRA7xx Devices SD/eMMC

Note: This feature is applicable only for GLSDK 6.03 & GLSDK7.2 release onwards

The GLSDK u-boot supports booting the secure devices. In order to boot the secure DRA7xx devices, at minimum, the MLO binary must be signed and formatted properly with the necessary keys and certificates. If extended boot authentication is used, a special u-boot build is required and the u-boot.img, kernel and DTB files must also be signed. Signing is done using the IFT tools (contact local sales representative to get M-Shield-Dk/IFT tools). This process can be used with test secure (HS) devices with the TI dummey key. The sequence of authentication of images for HS devices as follows. The initial authentication is done by RM code and is required. The last 2 steps are optional and constitute extended secure boot authentication.

ROM -> PKC – ROM code authenticates Public Key Certificate against Root eFuse key
ROM -> PPA – ROM code authenticates Primary Protected Application and loads to secure RAM and executes
ROM->MLO - ROM code loads and authenticates MLO
MLO->u-boot - The MLO authenticate u-boot
u-boot->kernel & dtb - The u-boot authenticates kernel and dtb file

In any stage if authentication fails, then device will enter a deadloop.

Note:
For GLSDK6.X release ${GLSDK}/bin/ift-sign-image.sh script used for signing 

For GLSDK7.2 release ${MSHIELD_DK_DIR}/ift/ift-image-sign.sh script used for signing

Install Mshield-DK

Install Mshield-DK tool and set the path to "MSHIELD_DK_DIR" environment variable corresponding to the version you installed (LITE, STD, for FULL).

 #export MSHIELD_DK_DIR="${HOME}/omap-mshield-lite"

Signing the Images

The mshield-dk 4.3.2 is used for testing GLSDK7.2 release and mshield-dk 4.4.1 is supported GLSDK7.03.00.04 onward.
The signed MLO and u-boot.img will created when dra7xx_hs_evm_config config used to build u-boot.
The kernel/dtb files shall be signed if CONFIG_SECURE_IMAGE_AUTH and CONFIG_SECURE_DTB_AUTH is defined in u-boot.

Usage:

#{MSHIELD_DK_DIR}/ift/ift-image-sign.sh <dra7xx or dra72x> <input-file> <output-file>
example:
#{MSHIELD_DK_DIR}/ift/ift-image-sign.sh dra7xx arch/arm/boot/zImage zImage.signed
#{MSHIELD_DK_DIR}/ift/ift-image-sign.sh dra7xx arch/arm/boot/dts/<dtb-file> <dtb-file>.signed

Enabling/Disable of Kernel/DTB authentication in U-Boot

The kernel/dtb authentication can be enabled or disabled by defining or undefining below defines in file include/configs/dra7xx_evm.h.

#define CONFIG_SECURE_IMAGE_AUTH
#define CONFIG_SECURE_DTB_AUTH

Signing MLO

Use the ift-sign-image.sh shell script to sign the MLO. This step is mandatory for secure devices and adds the Table of Contents (ToC), Signed Public Key Certificate (PKC) and signed PPA and formats the image as required. Note: you may have to edit this shell script to include appropriate key files(.pem) to sign the image.

 #${GLSDK}/bin/ift-sign-image.sh -mlo -dra7xx

This command will use spl/u-boot-spl.bin and create signed MLO.

Copy MLO to SD boot partition.

#cp MLO /media/boot/

Building u-boot for extended authentication of secure devices

The defconfig "dra7xx_evm_hs_config" is used to compile the u-boot. Use below command to compile u-boot binaries

 #make ARCH=arm CROSS_COMPILE=arm-arago-linux-gnueabihf- distclean
 #make ARCH=arm CROSS_COMPILE=arm-arago-linux-gnueabihf- <defconfig>
 <defconfig> is  dra7xx_evm_hs_config for GLSDK6.X release.
 <defconfig> is  dra7xx_hs_evm_config for GLSDK7.X release.

When using the instructions above, a modified version of u-boot(u-boot.img.signed)is build that will authenticate the kernel and dtb and, in addition, the u-boot.img.that is created will be signed. By default, the key with ISW signing rights will also be used to sign the uboot image as well as the kernel and dtb. If you want to use a different key from the PKC, please modify the makefile and scripts accordingly.

Copy u-boot.img.signed (rename to u-boot.img) to SD boot partition.

#cp u-boot.img.signed /media/boot/u-boot.img

Signing kernel images & dtb for secure devices

After the kernel is built, issue the below command to sign the kernel image (zImage) and dra7-evm.dtb file. The shell script will use zImage to create signed uImage.

 #${GLSDK}/bin/ift-sign-image.sh -kernel arch/arm/boot/zImage

The uImage.signed will be created in the current directory.

 #${GLSDK}/bin/ift-sign-image.sh -dtb arch/arm/boot/dts/dra7-evm.dtb

The arch/arm/boot/dts/dra7-evm.dtb.signed will be created.

copy the signed images to SD boot partition

 #cp uImage.signed /media/boot/uImage
 #cp dra7-evm.dtb.signed /media/boot/dra7-evm.dtb

booting the HS device

Insert the sd card to secure dra7xx(HS) EVM and reset the board. If the board is not booting then check signing procedure and make sure right keys (.pem) for the HS device is used

USB DRD (Dual Role Device) Support

The GLSDK kernel (6.04.x onwards) supports DRD feature, Where USB ports has capable of switching between device mode or host mode dynamically based on the usb cable type connected.

If host-type (A-type) usb cable is connected, the port switched to host mode.
If device-type (B-type) usb cable is connected, the port switched to device mode.

Note:

edit /usr/bin/usb1-rules.sh(for USB1) /usr/bin/usb2-rules.sh(for USB2) and to include the <gadget-module>.ko to unload and load during role switch.
Refer DRD support for more information.
Refer drive-vbus-using-gpio in order to drive the vbus using gpio.

Device Firmware Upgrade (DFU)

The Device Firmware Upgrade (DFU) feature is used to program or flash the firmware to memory devices such as eMMC/MMCSD/QSPI/NOR/NAND/RAM devices. Currently the u-boot has DFU support only for eMMC, MMC/SD and RAM devices. DFU feature is supported in GLSDK7.02 release.

DFU Supported Devices in u-boot

eMMC
MMC/SD
RAM

Using USB peripheral boot mode for flashing eMMC of fresh/factory boards

This method is used to flash the binary images from ubuntu Host PC (using dfu-utils tool) to EVM using usb cable using Device Firmware Update (DFU) feature. This is used to flash the eMMC to fresh/factory boards.
Use default "dra7xx_evm_usbboot_defconfig" to build spl/u-boot-spl.bin

make dra7xx_evm_usbboot_defconfig
make

For detailed procedure please refer to application note at Flashing_binaries_to_the_factory_boards_using_Device_Firmware_Upgrade_(DFU).pdf

DFU Usage from u-boot

Use default "dra7xx_evm_defconfig" to build MLO and u-boot.img.

make dra7xx_evm_defconfig
make

Connect the EVM with Ubuntu Host through micro USB device cable (USB1 port on EVM).

From target u-boot prompt

Reset the default environment variable

# env default -a

set the dfu_alt_info environment variable to emmc dfu settings

# setenv dfu_alt_info ${dfu_alt_info_emmc}
# pri dfu_alt_info_emmc
dfu_alt_info_emmc=rawemmc raw 0 3751936;boot part 1 1;rootfs part 1 2;MLO fat 1 1;MLO.raw raw 0x100 0x100;u-boot.img.raw raw 0x200 0x
400;spl-os-args.raw raw 0x80 0x80;spl-os-image.raw raw 0x900 0x2000;spl-os-args fat 1 1;spl-os-image fat 1 1;u-boot.img fat 1 1;uEnv.
txt fat 1 1

Run DFU command chosing eMMC as memory device

dfu <usb controller number> mmc <1-eMMC, 0-mmc/sd>

# dfu 0 mmc 1
set_config: high speed config #1: usb_dnload

From PC host side (Ubuntu)

To list the available partition to load the file.

# sudo dfu-util -l
dfu-util 0.5
(C) 2005-2008 by Weston Schmidt, Harald Welte and OpenMoko Inc.
(C) 2010-2011 Tormod Volden (DfuSe support)
This program is Free Software and has ABSOLUTELY NO WARRANTY
dfu-util does currently only support DFU version 1.0
Found DFU: [0403:bd00] devnum=0, cfg=1, intf=0, alt=0, name="rawemmc"
Found DFU: [0403:bd00] devnum=0, cfg=1, intf=0, alt=1, name="boot"
Found DFU: [0403:bd00] devnum=0, cfg=1, intf=0, alt=2, name="rootfs"
Found DFU: [0403:bd00] devnum=0, cfg=1, intf=0, alt=3, name="MLO"
Found DFU: [0403:bd00] devnum=0, cfg=1, intf=0, alt=4, name="MLO.raw"
Found DFU: [0403:bd00] devnum=0, cfg=1, intf=0, alt=5, name="u-boot.img.raw"
Found DFU: [0403:bd00] devnum=0, cfg=1, intf=0, alt=6, name="spl-os-args.raw"
Found DFU: [0403:bd00] devnum=0, cfg=1, intf=0, alt=7, name="spl-os-image.raw"
Found DFU: [0403:bd00] devnum=0, cfg=1, intf=0, alt=8, name="spl-os-args"
Found DFU: [0403:bd00] devnum=0, cfg=1, intf=0, alt=9, name="spl-os-image"
Found DFU: [0403:bd00] devnum=0, cfg=1, intf=0, alt=10, name="u-boot.img"
Found DFU: [0403:bd00] devnum=0, cfg=1, intf=0, alt=11, name="uEnv.txt

The above list shows list of dfu partitions or file name.

Flashing rawemmc partition

The "rawemmc" partition is used to update the disk image to raw eMMC sector 0. This is used to flash the eMMC to fresh boards. Please refer to section Using USB peripheral boot mode

Update existing MLO and u-boot.img of eMMC boot partition (vfat)

This method is used to update the MLO/u-boot.img files in boot(vfat) partion of eMMC

To update the MLO file

#sudo dfu-util -D MLO -c 1 -i 0 -a 3

To update the u-boot.img file

#sudo dfu-util -D u-boot.img -c 1 -i 0 -a 10

Update existing boot and rootfs partition (ext4) of eMMC

This method is used to update the existing boot partition (vfat) or rootfs partition (ext4) images in eMMC

To update the boot partition disk image

#sudo dfu-util -D boot.img -c 1 -i 0 -a 1

To update the rootfs partition disk image

#sudo dfu-util -D rootfs.img -c 1 -i 0 -a 2

Steps to create boot (vfat) and rootfs (ext4) raw disk image

In order to create raw boot and rootfs disk image along with partition structure follow the steps mentioned below.

Insert the mmc/sd card to Ubuntu PC, the size of sdcard shall be less than or equal to size of eMMC populated in EVM.
Prepare mmc/sd card mentioned in step4 of GLSDK User Guide. By default the mksdboot.sh script creates two partitions, 64MB of boot partition with vfat filesystem and remaining size of sd card with rootfs partition with ext4 filesystem.
After sd card is created with boot and rootfs partition, mount the sdcard to update uenv.txt and overwrite uenv.txt by uenv-emmc.txt in "boot" partition. Copy any additional files required to boot/rootfs partition.

 #mount /dev/sdY1 /media/boot
 #mount /dev/sdY2 /media/rootfs
 #cp /media/boot/uenv-emmc.c /media/boot/uenv.txt
 #sync

Create the vfat raw boot disk image along with partition structure

#dd if=/dev/<sdY1> of=boot.img bs=1M &

Create the ext4 raw rootfs disk image along with partition structure

#dd if=/dev/<sdY2> of=rootfs.img bs=1M &

Flashing/Upgrading custom file to eMMC vfat/ext4 partition

1. If eMMC device is not partitoned, then first the eMMC device must be partitioned to vfat or ext4 filesystem. ReferFlashing_binaries_to_the_factory_boards_using_Device_Firmware_Upgrade_(DFU).pdf
2. Once the eMMC device has been paritioned to vfat/ext4, user can write into existing file or partition. For example as shown in above list of dfu interfaces, user can upgrade the MLO or u-boot.img file from ubuntu PC. The alternate interface number 3 need to selected for upgrading MLO, and 10 need to selected for u-boot.img.

#sudo dfu-util -D MLO -c 1 -i 0 -a 3
#sudo dfu-util -D u-boot.img -c 1 -i 0 -a 10

Adding a custom file to DFU configuration

1. Add a custom/new file to the root directory of existing rootfs(ext4) or boot(vfat) partition of sdcard and flash the filesystem raw disk images to eMMC. For example consider the file zImage, dra7-evm-lcd10.dtb is added to root directory of rootfs(ext4) and README file in boot(vfat) partition. Make sure file read/write permission is set.
2. From u-boot source repository, edit the file include/configs/ti_omap5_common.h, add a new entry to DFU_ALT_INFO_EMMC macro.

#define DFU_ALT_INFO_EMMC \
       "dfu_alt_info_emmc=" \
       "rawemmc raw 0 3751936;" \
       "boot part 1 1;" \
       "rootfs part 1 2;" \
       "MLO fat 1 1;" \
       "ZImage ext4 1 2;" \
       "dra7-evm-lcd10.dtb ext4 1 2;" \
       "README fat 1 1;" \
       "MLO.raw raw 0x100 0x100;" \
       "u-boot.img.raw raw 0x200 0x400;" \
       "spl-os-args.raw raw 0x80 0x80;" \
       "spl-os-image.raw raw 0x900 0x2000;" \
       "spl-os-args fat 1 1;" \
       "spl-os-image fat 1 1;" \
       "u-boot.img fat 1 1;" \
       "uEnv.txt fat 1 1\0"

3. Edit include/configs/dra7xx_evm.h and include below configs

CONFIG_EXT4_WRITE
CONFIG_CMD_EXT4_WRITE

4. Compile the u-boot to create MLO, u-boot.img and load MLO/u-boot.img to EVM
5. Execute "dfu-util -l" from PC host, the new interfaces added will be listed

#sudo dfu-util -l
dfu-util 0.5
(C) 2005-2008 by Weston Schmidt, Harald Welte and OpenMoko Inc.
(C) 2010-2011 Tormod Volden (DfuSe support)
This program is Free Software and has ABSOLUTELY NO WARRANTY
dfu-util does currently only support DFU version 1.0
Found DFU: [0403:bd00] devnum=0, cfg=1, intf=0, alt=0, name="rawemmc"
Found DFU: [0403:bd00] devnum=0, cfg=1, intf=0, alt=1, name="boot"
Found DFU: [0403:bd00] devnum=0, cfg=1, intf=0, alt=2, name="rootfs"
Found DFU: [0403:bd00] devnum=0, cfg=1, intf=0, alt=3, name="MLO"
Found DFU: [0403:bd00] devnum=0, cfg=1, intf=0, alt=4, name="zImage"
Found DFU: [0403:bd00] devnum=0, cfg=1, intf=0, alt=5, name="dra7-evm-lcd10.dtb"
Found DFU: [0403:bd00] devnum=0, cfg=1, intf=0, alt=6, name="README"
Found DFU: [0403:bd00] devnum=0, cfg=1, intf=0, alt=7, name="MLO.raw"
Found DFU: [0403:bd00] devnum=0, cfg=1, intf=0, alt=8, name="u-boot.img.raw"
Found DFU: [0403:bd00] devnum=0, cfg=1, intf=0, alt=9, name="spl-os-args.raw"
Found DFU: [0403:bd00] devnum=0, cfg=1, intf=0, alt=10, name="spl-os-image.raw"
Found DFU: [0403:bd00] devnum=0, cfg=1, intf=0, alt=11, name="spl-os-args"
Found DFU: [0403:bd00] devnum=0, cfg=1, intf=0, alt=12, name="spl-os-image"
Found DFU: [0403:bd00] devnum=0, cfg=1, intf=0, alt=13, name="u-boot.img"
Found DFU: [0403:bd00] devnum=0, cfg=1, intf=0, alt=14, name="uEnv.txt"

6. Now you can upgrade the new added files by chosing the respective alternate interface number (alt=<number>)

Upgrade the zImage
#sudo dfu-util -c 1 -i 0 -a 4 -D zImage

Upgrade the dra7-evm-lcd10.dtb
#sudo dfu-util -c 1 -i 0 -a 4 -D dra7-evm-lcd10.dtb

Using dfu-utils from Windows PC Host

Follow the below steps to install the dfu-tools.
1. Download the dfu-utils dfu-util-0.6-win32.zip.bz2 and unzip to some folder (say c:\dfu)
2. Download the zdaig application and execute zdaig application, install winUSB driver.
3. Go through DFU section mentioned above for setup the EVM for DFU.

Note: For flashing fresh boards, refer to peripheral usb boot mode section.
The initial bootloader (u-boot-spl.bin) shall be loaded to EVM using usbboot tool running from Ubuntu Host PC. 
For more details refer Flashing_binaries_to_the_factory_boards_using_Device_Firmware_Upgrade_(DFU).pdf

4. Connect the EVM (running DFU) to windows PC through superspeed usb cable. Windows host will detect the EVM as "download gadget".
5. Copy required binary files to flash c:\dfu folder. Open command prompt and execute dfu-util.exe.

c:\dfu> dfu-util –l   
This will list all dfu interfaces

6. Follow DFU section mentioned above for flashing the binaries to eMMC.

c:\dfu> dfu-util -D <file-name> -c 1 -i 0 -a <alt number>

IPC

The table below shows the remote cores and their corresponding definitions in the kernel dtsi files ($GLSDK/board-support/linux/arch/arm/boot/dts/dra7.dtsi, and dra74x.dtsi), as well as the argument to be used in the loading/unloading commands.

Remote Core	Definition in dtsi file	Argument in loading/unloading
IPU1	ipu@58820000	58820000.ipu
IPU2	ipu@55020000	55020000.ipu
DSP1	dsp@40800000	40800000.dsp
DSP2	dsp@41000000	41000000.dsp

For example, the argument of 55020000.ipu corresponds to IPU2 as can be seen from dra7.dtsi.

   ipu2: ipu@55020000 {
        compatible = "ti,dra7-rproc-ipu";

In the sections below, 55020000.ipu will be used as the example. For a specific use case, please select the corresponding argument which is applicable.

Unloading and loading remotecores at runtime

It is possible to unload and reload a remotecore at runtime from Linux using the sysfs interface.

target $ cd /sys/bus/platform/drivers/omap-rproc/ 
target $ echo 55020000.ipu > unbind 
target $ echo 55020000.ipu > bind

The echo 55020000.ipu > unbind command tears down the communication channels between the A15 and the remotecore and unloads the remotecore. Any application level shutdown that needs to be performed needs to be handled by the system integrator.

The echo 55020000.ipu > bind loads the appropriate firmware binary onto the remotecore.

Changing the remotecore binary at runtime

To change the remotecore binary at runtime

Unload the remotecore using unbind.
Change the remotecore binary in the firmware folder. Default location is /lib/firmware on the target filesystem.
Load the remotecore using bind.

target $ cd /sys/bus/platform/drivers/omap-rproc/
target $ echo 55020000.ipu > unbind
target $ cp /home/root/new-binary.xem4 /lib/firmware/dra7-ipu2-fw.xem4
target $ echo 55020000.ipu > bind

If it is desirable to avoid overwriting the existing remote binaries, the method of symbolic links can be used instead of direct copy. For example, Processor SDK provides two types of DSP remotecore binaries: one for DSPDCE (dra7-dsp1-fw.xe66.dspdce-fw) and another one for OpenCL (dra7-dsp1-fw.xe66.opencl-monitor). dra7-dsp1-fw.xe66 is created as a symbolic link by default pointing to the OpenCL binary. When it is needed to switch to DSPDCE, the symbolic link of dra7-dsp1-fw.xe66 can be updated pointing to dra7-dsp1-fw.xe66.dspdce-fw.

target $ cd /sys/bus/platform/drivers/omap-rproc/
target $ echo 40800000.dsp > unbind
target $ rm /lib/firmware/dra7-dsp1-fw.xe66
target $ ln -s /lib/firmware/dra7-dsp1-fw.xe66.dspdce-fw /lib/firmware/dra7-dsp1-fw.xe66
target $ echo 40800000.dsp > bind

After the switch, copycodectest application can be run to verify that DSPDCE firmware is loaded. This application fills the input buffer with a number entered as the argument and after process the output buffer is tested for the same pattern.

usage: copycodectest pattern.

Example:

 target # copycodectest 123

Sample console output:

  root@am57xx-evm:~# copycodectest 123
  0x22070: Opening Engine..
  Created dsp_universalCopy
  Fill input buffer with pattern 123
  Verifing the UniversalCopy algorithm
  copycodectest executed successfully

Loading firmware during initial boot without using udev

During the default GLSDK boot, firmware is supplied to the kernel by udev. Starting the udev service on boot causes a few seconds increase in boot time. In cases where a quick boot is required, the user may not start the udev service in boot. In such cases, firmware can be supplied to the kernel using the sysfs interface. An example script is shown below.

FW_NAMES="dra7-dsp1-fw.xe66 dra7-dsp2-fw.xe66 dra7-ipu1-fw.xem4 dra7-ipu2-fw.xem4"
for FW in $FW_NAMES ; do
    echo 1 > /sys/class/firmware/$FW/loading
    cat /lib/firmware/$FW > /sys/class/firmware/$FW/data
    echo 0 > /sys/class/firmware/$FW/loading
done

Handling the IPU bitbanding region

The ARM Cortex-M4 memory map includes a bit-banding region of memory from 0x4000:0000 to 0x400F:FFFF and 0x4200:0000 to 0x43FF:FFFF. Here is a Cortex-M4 memory map picture from ARM:

http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.dui0553a/CHDBIJJE.html

Many Vayu components running on the IPUs, including IPC, must access peripherals physically located in this bit-banding region. As a result, these accesses must be performed indirectly using a virtual memory address, mapped using the IPU's AMMU.

Many of the components aligned on mapping this memory using one Large AMMU page that maps 512M of physical memory beginning at 0x4000:0000 to virtual memory beginning at 0x6000:0000. Then the components (by default) access the peripherals using the 0x6XXX:XXXX address space.

IPC specifics

IPC follows the convention of, by default, accessing memory physically located at 0x4XXX:XXXX using virtual memory at 0x6XXX:XXXX. You can see an example of this here - note the mailbox addresses configured here are in the 06XXX:XXXX range:

http://git.ti.com/cgit/cgit.cgi/ipc/ipcdev.git/tree/packages/ti/sdo/ipc/family/vayu/InterruptIpu.xs

In that same file, you can see that these addresses are configurable, and the default 0x6XXX:XXXX addresses are only used if other addresses haven't already been configured by the system integrator (e.g. in a .cfg script). Users can override these default mailbox addresses using the ti.sdo.ipc.family.vayu.InterruptIpu module's mailboxBaseAddr[] array, documented here:

https://software-dl.ti.com/dsps/dsps_public_sw/sdo_sb/targetcontent/ipc/latest/docs/cdoc/ti/sdo/ipc/family/vayu/InterruptIpu.html#metamailbox.Base.Addr

Using the Late attach functionality

To satisfy the startup time requirements of specific use cases, one may need the boot loader to boot a remote core before booting the A15 with the linux kernel. The kernel then attaches to the already booted remote core for further communication. We refer to this feature as the "Early Boot - Late Attach" functionality. The "Early Boot" functionality is provided by the boot loader. The "Late Attach" functionality is a feature of the Linux Kernel. This functionality was added to GLSDK from v6.04. It has been reworked to support migration to the 3.14 kernel in GLSDK v7.0.

Below are the steps required to test early boot late attach functionality.

Configuring U-Boot

Please define the macro CONFIG_LATE_ATTACH in the file u-boot/include/configs/dra7xx_evm.h. Change the lines

#undef CONFIG_LATE_ATTACH

#ifdef CONFIG_LATE_ATTACH

to

#define CONFIG_LATE_ATTACH

#ifdef CONFIG_LATE_ATTACH

and rebuilt u-boot using the configuration dra7xx_evm_config.

Building the Linux kernel device tree

Linux kernel contains the "Late Attach" feature builtin. The feature is enabled or disabled on a per remote core basis at boot time through device tree node attributes. To enable "Late Attach" for a remote core, 3 attributes need to be set on the remote core and each of the timer, mmu nodes used by the remotecore. These three attributes are

ti,late-attach
ti,no-idle-on-init
ti,no-reset-on-init.

These three attributes together signal to the kernel that

Late attach feature is in use for the remote core.
The remotecore and other nodes have been configured and are in use before the kernel boot. These should not be reset or idled during kernel boot.

The Linux kernel tree delivered with GLSDK includes a dts file that shows how to enable late attach feature for IPU2 on a DRA7xx evm with 7" LCD. This file was built in the following manner. The timers used by IPU2 are found from $GLSDK/board-support/linux/arch/arm/boot/dts/dra7-evm.dts

&ipu2 {
    status = "okay";
    memory-region = <&ipu2_cma_pool>;
    mboxes = <&mailbox6 &mbox_ipu2_legacy>;
    timers = <&timer3>;
    watchdog-timers = <&timer4>, <&timer9>;
};

The MMU used by IPU2 can be found from $GLSDK/board-support/linux/arch/arm/boot/dts/dra7.dtsi.

        ipu2: ipu@55020000 {
            compatible = "ti,dra7-rproc-ipu";
            reg = <0x55020000 0x10000>;
            reg-names = "l2ram";
            ti,hwmods = "ipu2";
            iommus = <&mmu_ipu2>;
            ti,rproc-standby-info = <0x4a008920>;
            status = "disabled";
        };

IPU2 uses timer3 to supply the OS tick and timer4 and timer9 as watchdog timers. IPU2 also uses an MMU referred to as mmu_ipu2 in the device tree. All of these nodes including the IPU2 node need to have the three attributes described above set.

The file $GLSDK/board-support/linux/arch/arm/boot/dts/dra7-evm-lcd7-late-attach.dts has the full example. This file is structured such that it includes an existing configuration first

#include "dra7-evm-lcd7.dts"

and sets only the atrributes required for enabling late attach functionality.

Late attach can be enabled for other remotecores by setting the late attach atributes on the corresponding device tree nodes. Late attach can be enabled for other hardware configurations by choosing a different base .dts file. e.g. If the EVM has a 10" lcd instead of 7" LCD, you can change the include to "dra7-evm-lcd10.dts" instead of "dra7-evm-lcd7.dts".

Build the .dtb file and use it for linux boot instead of the regular dtb file.

Boot setup

Configure the EVM for boot from SD card.
Use the MLO and u-boot.img built above with the early boot functionality enabled.
Use the dtb file built with the late attach functionality enabled.
Copy the IPU2 binary into the boot partition of the SD card. The IPU2 binary can be found in /lib/firmware/dra7-ipu2-fw.xem4 on the target filesystem.

Boot the board and test the IPU2 functionality as you would normally do. You will not notice any difference in the functionality except that the IPU2 was already loaded and running before the Linux Kernel was booted.

Confirming Late attach functionality

There is no default indication of whether late attach feature is in use or not. This is by design as use of late attach should be invisible to the user. For debug purposes, enable the DEBUG flag on drivers/remoteproc/omap_remoteproc.c during kernel compilation. If late attach functionality is in use, additional traces will now show up in the dmesg logs.

root@dra7xx-evm:~# dmesg | grep late-attach
[ 2.609644] omap-rproc 55020000.ipu: device will be late-attached.

Customizing Early Boot for a Usecase

The Early boot code in U-Boot does the necessary configuration to bring up a remotecore. This includes the timers and the MMUs. It does not configure any other peripherals by default. Some usecases may require additional peripheral configuration before running the remotecore. U-Boot includes placeholder functions that can be populated for this purpose. These can be found in the file $GLSDK/board-support/u-boot/board/ti/dra7xx/evm.c.

/*
 * If the remotecore binary expects any peripherals to be setup before it has
 * booted, configure them here.
 *
 * These functions are left empty by default as their operation is usecase
 * specific.
 */

u32 ipu1_config_peripherals(u32 core_id, struct rproc *cfg)
{
    return 0;
}

u32 ipu2_config_peripherals(u32 core_id, struct rproc *cfg)
{
    return 0;
}

u32 dsp1_config_peripherals(u32 core_id, struct rproc *cfg)
{
    return 0;
}

u32 dsp2_config_peripherals(u32 core_id, struct rproc *cfg)
{
    return 0;
}

Validation and Limitations

Late attach functionality has been validated for all the remotecores IPU2,IPU1,DSP1 and DSP2. However there is the following limitation.

U-Boot has only been updated to load remotecore binaries from the boot partition of the SD card or eMMC.

Debug guide

A more detailed user guide of Early Boot and Late Attach functionality can be found at Early Boot and Late Attach in Linux

Using the Early video decode example

Early Video decode is not supported in the GLSDK 7.0 EA release.

Changing MPU Frequency (DVFS)

DRA7xx supports running MPU (CPU0/1) at more than one frequency.
User may chose to run at different frequencies based on performance requirements for the application/use-case targeted.
The Data Manual contains all the frequencies supported by the Hardware and the GLSDK Datasheet available with current release contains details of supported frequencies in the Software.
Please refer to the following wiki for details on how to change CPU frequency and voltage DVFS UserGuide

SOC Performance monitoring tools

Introduction

The SOC Performance monitoring tools are a set of tools that are included in the default GLSDK filesystem that allow the user to visualize various SOC parameters real-time on the screen.
Currently, there are two tools and a suite of scripts and utilities to use them.

soc-performance-monitor
soc-ddr-bw-visualize

Both these applications are Wayland applications and need to be invoked after running Weston.

These tools bring in the capability to visualize the following:

DDR BW Utilization
1. Overall DDR BW Usage
2. Split of the traffic between the two EMIF's
3. A real time "top" like functionality that depicts the list of "Top 6" initiators generating the traffic.
Voltage of the various rails
Frequency of the various cores
Temperature (read from on die temperature sensors)
CPU Load information of the various processor cores including the GPU.
Boot time results (requires rebuild of u-boot and kernel), refer instructions below.
Power plot (Will be available soon. Note that this requires board modification on the EVM)

Getting started

Prepare the card with GLSDK 7.04 or later.
Boot up
Start weston

target # pvrsrvinit
target # weston --tty=1 --connector=16 --idle-time=0 &

Copy the required scripts into a temporary folder (this is to allow you to experiment with the settings later)

target # mkdir temp
target # cd temp
target # cp /etc/glsdkstatcoll/* .
target # cp /etc/visualization_scripts/* .

You should see the following file in the directory after the above operation.

target # ls -al
drwxr-xr-x    2 root     root          4096 Mar 22 18:01 .
drwxr-xr-x    3 root     root          4096 Mar 22 18:01 ..
-rw-r--r--    1 root     root           114 Mar 22 18:01 config.ini
-rw-r--r--    1 root     root           265 Mar 22 18:01 dummy_boot_time_results.sh
-rw-r--r--    1 root     root           419 Mar 22 18:01 dummy_cpu_load.sh
-rw-r--r--    1 root     root           899 Mar 22 18:01 getFrequency.sh
-rw-r--r--    1 root     root          2293 Mar 22 18:01 getTemp.sh
-rw-r--r--    1 root     root           371 Mar 22 18:01 getVoltage.sh
-rw-r--r--    1 root     root           254 Mar 22 18:01 initiators.cfg
-rw-r--r--    1 root     root           143 Mar 22 18:01 list-boot-times.sh
-rw-r--r--    1 root     root           367 Mar 22 18:01 send_boot_times_to_monitor.sh
-rw-r--r--    1 root     root           496 Mar 22 18:01 soc_performance_monitor.cfg
-rw-r--r--    1 root     root           133 Mar 22 18:01 start_visualization_test.sh

Running the soc-performance-monitor, this tool has two pre-requisites.

The name of the fifo configured in the file soc_performance_monitor.cfg needs to be created
The file soc_performance_monitor.cfg should be present in the current directory. This should be done in the above steps.

Creating the fifo (mentioned in the soc_performance_monitor.cfg)

target # mkfifo /tmp/socfifo

Run the tool for various performance metrics

target # soc-performance-monitor &

Run the tool for DDR BW Visualization

target # mkfifo /tmp/statcollfifo
target # soc-ddr-bw-visualizer &

The following sections will talk about the how to populate the data into tools and further controls that are possible.

Quick guide to available plugins

Plugins are the entities (scripts/native binaries) that can be used to send commands to the SOC Performance Monitoring tools.

The main intent of this is to separate the visualization engine from the data collection part and allow full configuration of the application.

When the application (soc-performance-monitor) is invoked, it starts up with the default data which is set to zero. To populate the real values, the user can use the scripts provided in the prebuilt filesystem.

Temperature data

The temperature data is read from the on-die temperature registers and sent to the visualization tool. The GLSDK file system comes with a script that does this functionality.

target # sh getTemp.sh

Invoking the above command will populate the temperature table with the current temperature.

Voltage data

The voltage data is read from the omapconf utility and then parsing out the required information to be later sent to the visualization tool. The GLSDK file system comes with a script that does this functionality.

target # sh getVoltage.sh

Invoking the above command will populate the Temperature table with the configured voltage for the various rails.

Frequency data

The frequency data is read from the omapconf utility and then parsing out the required information to be later sent to the visualization tool. The GLSDK file system comes with a script that does this functionality.

target # sh getFrequency.sh

Invoking the above command will populate the Frequency table with the configured frequency for the various cores.

CPU Load information

The CPU load information need individual plugin modules for each of the cores. This is envisioned to be different for different systems. The default GLSDK filesystem contains the plugins required for reading the MPU(A15) and the GPU(SGX544 MP2). Other plugins for measuring the loads for the IPU1, IPU2, DSP1 and DSP2 will be available at a later time.

Measuring the MPU load

The filesystem is populated with a binary which is called "mpuload" that reads the /proc/stat interface and derives the load. The user can run the utility in the background with the

target # mpuload FIFO 

Example usage:

target # mpuload /tmp/socfifo 1000 &

After running this binary the MPU load in the Bar Graph of the CPU load will be updated dynamically at an interval of 1 second.

Measuring the GPU load

The filesystem is populated with a binary called as "pvrscope" that reads the SGX registers via a library called libPVRScopeDeveloper.a This utility invokes the APIs provided by IMG as part of the Imagination PowerVR SDK and then populates the required FIFO.

Usage instructions:

target # pvrscope <option> <time_seconds>

options: 
          -f    write into the FIFO (/tmp/socfifo)
          -c    output to console

time:
          1-n   specified in seconds
          0     run forever

After running this utility, the GPU load in the BAR Graph of the CPU load area will be updated at an interval of 1 second.

Boot time measurement

To collect boot time benchmark information for use with the visualization tool, kernel and u-boot need to be patched. Instructions to obtain and apply the patches and flashing procedure are available at #Build instructions for boot time measurements. To display the boot time information in the boot time table, please run the below command.

target # readproc;sh send_boot_times_to_monitor.sh

The measurements displayed can be customized by modifying 'soc_performance_monitor.cfg' and 'send_boot_times_to_monitor.sh'.

Order of execution

The performance visualization tools have to be executed in the following order.

Launch weston
Create required FIFOs
Configure the .cfg file to suit the required settings
Run the soc-performance-monitor and/or soc-ddr-bw-visualizer
Run the plugins to populate data

Config file format

The config file has the following format.
There are 3 different kinds of sections that can be defined, please refer to the particular section for more details.

The generic format is:

[SECTION_NAME]
VALUE_1
VALUE_2
..
..
VALUE_N
SPECIAL VALUE
<blank line>

Types of sections

GLOBAL
TABLE
BAR GRAPH

GLOBAL section:

The SECTION_NAME is specified as GLOBAL followed by a sequence of key value pairs.

[GLOBAL]
KEY_1=VALUE_1
KEY_2=VALUE_2
..
..
KEY_n=VALUE_n
<blank>

Global configurations

The list of recognized global values are:

REFRESH_TIME_USECS
FIFO
MAX_HEIGHT
MAX_WIDTH
X_POS
Y_POS

REFRESH_TIME_USECS:

This will dictate the interval at which the utility is going to run.
The value is specified in micro seconds
This value decides a major trade-off, lower rate will increase the CPU load and GPU load.
The ideal value is about 100000 usecs

FIFO:

The value of this field is the named pipe or fifo that can be used to communicate with the application.
User would need to create a fifo (application will prompt if it doesn't exist)

MAX_HEIGHT, MAX_WIDTH:

The width and height of the application.
This can be adjusted based on the number of tables and bar graph entities.

X_POS, Y_POS:

Decide the starting offset of the application.
Note that there are commands to move the application (Refer commands section).

TABLE section:

The section name can be one of the following:

BOOT_TIME
TEMPERATURE
VOLTAGE
FREQUENCY

[TABLE_NAME]
 VALUE_1
 VALUE_2
 ..
 ..
 VALUE_N
TITLE="TABLE TITLE",UNIT="unit to be displayed"
<blank line>

NOTE: The TITLE=list is a list of comma separated values and TITLE and UNIT are the only supported values.

BAR GRAPH section:

This section is the simplest section and does not allow much configuration other than the names and the title.
It follows the following format:

[GRAPH_NAME]
 VALUE_1
 VALUE_2
 ..
 ..
 VALUE_N
 TITLE OF THE GRAPH
 <blank line>

Commands:

The FIFO can be used to communicate with the soc-performance-monitor application and pass data from the command line or from other applications.
There are a few commands that have been implemented to aid in modifying the running application via the FIFO.

The commands in general have the following format:

"INSTRUCTION: DATA_1 ... DATA_N"

and they can be sent to the soc-performance-monitor by simply doing an echo:

echo "INSTRUCTION: DATA_1 ... DATA_N" > FIFO

The currently supported list of supported commands are:

MOVE
TABLE
CPULOAD

NOTE: To execute a sequence of commands in a sequence, it is advised that a delay of REFRESH_TIME_USECS be inserted between two commands.

MOVE command

The format of the MOVE command is:

"MOVE: x_position"

where x_position is a number with range (0, screen_resolution-1)

When this command is sent, the application will update the top left location of the application to the newly provided co-ordinate. NOTE: If the x_position is greater than screen width, it is not possible to bring the application back into focus.

Example: To set the location of the window to be aligned to the right edge of the 1080p screen and assuming MAX_WIDTH set to 500, the user can invoke the command below:

echo "MOVE: 1420" > /tmp/socfifo

TABLE command

The format of the TABLE command is:

"TABLE: ROW_NAME value unit"

When this command is issued, the tool will find a table entry with the ROW_NAME in Column 0 and then update the Column 1 of the table with "value unit"
If the ROW_NAME is not found, then this command will have no effect. Please note that this brings in a restriction that all the tables rows will need to have a unique name. In order to ensure this, the soc_performance_monitor.cfg file will have to be reviewed to ensure unique names.

Example: To update the FREQUENCY table for MPU, the user can send the following command:

echo "TABLE: FREQ_MPU 1500 MHz" > /tmp/socfifo

CPULOAD command

The format of the CPULOAD command is:

"CPULOAD: CORE_NAME value" > FIFO

 CORE_NAME has to be one of the names specified in the soc_performance_monitor.cfg.
 value is in the range 0 to 100

Usually, the CPULOAD command is invoked through an application monitors the load of a specific core.
In each system, the mechanism to retrieve the CPULOAD of a particular core can vary and it is for this reason that several plugins have been provided and serve as an example for further extension.

Example: To update the CPULOAD table for GPU, the user can send the following command:

echo "CPULOAD: GPU 87" > /tmp/socfifo

Executing in debug mode

To launch the application in debug mode for very verbose data on the internal working of the tool, launch the tool with the following option:

# soc-performance-monitor 1

Build instructions

The full source of the tool is available and the required recipes have been updated as part of the recipes and upstreamed to meta-glsdk.
Essentially, if the user builds the Yocto filesystem as documented in the GLSDK SDG, the tool will get recompiled as part of it.

The recipes that pick up the SOC Performance Tools, plugins and scripts are:

meta-glsdk/recipes-graphics/weston/weston_1.6.0.bbappend
meta-glsdk/recipes-graphics/glsdk-example-apps/glsdk-example-apps.bbappend

These are picked up by default, by the packagegroup-arago-glsdk-multimedia.bb and will be built when invoking the build.

Build instructions for boot time measurements

Boot time measurement

To collect boot time benchmark information for use with the visualization tool, kernel and u-boot need to be patched. The patches include changes to timestamp u-boot and kernel execution at various points and supply the information via the device tree.

Please apply the below patches in ascending order on kernel and u-boot.

Kernel Patches
Order	Commit message	Latest version of the patch	Version for GLSDK 7.04
1	dra7xx: add functions for timestamping execution	http://review.omapzoom.org/#/c/37192/	http://review.omapzoom.org/#/c/37192/2
2	dra7xx: timestamp various points in execution	http://review.omapzoom.org/#/c/37193/	http://review.omapzoom.org/#/c/37193/2

U-Boot Patches
Order	Commit message	Latest version of the patch	Version for GLSDK 7.04
1	dra7xx: add functions for timestamping	http://review.omapzoom.org/#/c/37194/	http://review.omapzoom.org/#/c/37194/2
2	spl: dra7xx: timestamp various points in execution	http://review.omapzoom.org/#/c/37195/	http://review.omapzoom.org/#/c/37195/2
3	spl: dra7xx: propagate boot time measurements via dtb in single stage boot	http://review.omapzoom.org/#/c/37196/	http://review.omapzoom.org/#/c/37196/2

Once the kernel and u-boot are built and the file system is updated, the EVM needs to be setup for single stage boot. In single stage boot, MLO directly loads kernel instead of loading u-boot. This speeds up the boot process by at least a second and allows passing benchmarking information from MLO to kernel via device tree.

To get started with single stage boot, create a uImage file from zImage using the below or appropriate command.

host $ mkimage -A arm -O linux -C none  -T kernel -a 0x80008000 -e 0x80008000 -n 'Linux uImage' -d zImage uImage

Choose the right device tree for your platform based on the hardware setup. Please refer to Choosing the right device tree for more details. Update the location of the root filesystem in the bootargs field in the device tree. This can be done from the kernel build or post the build by using the fdtput tool as below.

host $ fdtput dra7-evm-lcd10.dtb "/chosen" "bootargs" \
    console=ttyS0,115200n8 elevator=noop root=/dev/mmcblk0p2 rw rootwait fixrtc \
    omapdrm.num_crtc=2 consoleblank=0 cma=64M rootfstype=ext4 loglevel=0

For SD boot, place the uImage, MLO, u-boot.img and the device tree on the FAT partition of the SD card. When copying the device tree, please save it as dra7-evm.dtb on the FAT partition of the SD card. MLO only looks for the device tree file by this name in single stage boot irrespective of the processor variant or EVM setup.

For eMMC boot, place the uImage, MLO, u-boot.img and the device tree on the FAT partition of the eMMC card. When copying the device tree, please save it as dra7-evm.dtb on the FAT partition of the eMMC. MLO only looks for the device tree file by this name in single stage boot irrespective of the processor variant or EVM setup.

For QSPI boot, follow the flashing instructions as specified in Using QSPI Boot.

After flashing the binaries, switch the EVM to single stage boot mode by changing the SYSBOOT settings.

SYSBOOT settings for single stage boot
Boot device	SYSBOOT SW2[5:0]
SD	11 0000
eMMC	11 1000
QSPI4	11 0111

Reboot the EVM. You will notice MLO skipping U-Boot and loading uImage directly. After the boot is complete, the following nodes are visible in the /proc/device-tree/chosen directory on the target.

root@dra7xx-evm:/proc/device-tree/chosen# ls
bootargs                 m-dsp1start-time         m-spi-init-dur
k-cust-machine-dur       m-dsp2start-time         mmc1_pinctl4_iodelay
k-hwmod-dur              m-entry-time             mmc1_pinctl5_iodelay
k-mm-init-dur            m-heap-init-dur          mmc2_pinctl2_iodelay
k-rest-init-time         m-image-load-dur         mmc2_pinctl3_iodelay
k-start-time             m-ipu1start-time         mmc4_pinctl0_iodelay
k-user-space-entry-time  m-ipu2start-time         mmc4_pinctl1_iodelay
m-boardinit-time         m-kernelstart-time       name
m-display-time           m-mmc-init-dur

The prefix of the node names indicates the stage of execution at which the measurement was made.

Prefix	Interpretation	Example
`m-`	measurement in `MLO`	`m-entry-time`
`k-`	measurement in `kernel`	`k-start-time`

The suffix indicates whether the measurement is a time stamp or a duration measurement.

Suffix	Interpretation	Example	Description
`-time`	indicates time from PORZ	`m-entry-time`	indicates the time at which `MLO` execution started.
`-dur`	indicates duration for an operation	`m-spi-init-dur`	indicates the amount of taken taken to initialize the QSPI peripheral.

All the measurements are reported in ticks of the 32 KHz timer. One tick is equal to 30.5 us. The value assigned to the device tree node can be read as a 32 bit big endian integer.

To convert the measurements to milliseconds, please run the readproc utility included in the filesystem. This reads each measurement in the device tree nodes, converts it into milliseconds and stores the output in a text file of the same name under /tmp. The script list-boot-times.sh included in the target file system can be used to easily print these times. Please see the example below.

target # readproc;list-boot-times.sh
m-entry-time,339
m-boardinit-time,440
m-heap-init-dur,0
m-image-load-dur,272
m-mmc-init-dur,85
m-kernelstart-time,802

k-start-time,1009
k-cust-machine-dur,86
k-hwmod-dur,202
k-mm-init-dur,203
k-rest-init-time,1317
k-user-space-entry-time,5619

The above shows MLO entry at 339 ms, MLO calling the kernel entry point at 800 ms. Kernel execution starts at 1009 ms after it decompresses itself. Kernel mounts file system and jumps to user space at 5619 ms. MMC initialization in MLO takes 85 ms.

The script list-boot-times.sh only prints the measurements on the terminal. The measurements can be displayed in the performance monitor tool using the sample script send_boot_times_to_monitor.sh.

target # readproc;sh send_boot_times_to_monitor.sh

Configuration of the soc-ddr-bw-visualizer

Refer to #Using_the_GLSDK_statistics_collector_.28bandwidth_application.29

The total time that the tool runs is configured using config.ini.
To allow finer granularity of control to choose the initiators of interest, the user will have to modify the initiators.cfg.

The tool will have to relaunched for the new settings to take effect.

Additional Procedures

Build Environment Setup

NOTE: From this release, each component i.e kernel, u-boot or any userspace application should be cross-compiled

Cross Compiler setup

The cross compiler setup for the Rules.make is done as a part of the setup.sh script in the GLSDK folder. The script for cross compiler ensures that the linaro cross compiler toolchain is installed in the ${HOME} (or user specified) folder of the host machine.
Note:Please ensure that the PATH variable is set in your machine to point to the cross compiler setup.
To compile the code (if not using the top level Makefile to build kernel and u-boot), please ensure the environment variables ARCH and CROSS_COMPILE is set to arm and to the linaro cross compiler path respectively.

Rebuilding the GLSDK components

The GLSDK has provided a top level Makefile to allow the re-building of the various components within the GLSDK.

Rebuild the GLSDK components by first entering the GLSDK directory using:

host $ cd ${GLSDK}

The GLSDK makefile has a number of build targets which allows you to rebuild the GLSDK components. For a complete list execute:

host $ make help

After that, each of the build targets listed by 'make help' can then be executed using:

host $ make <target>_clean
host $ make <target>
host $ make <target>_install

For example, to compile the Linux Kernel, you can use the following commands

host $ make linux_clean
host $ make linux
host $ make linux_install

In order to install the resulting binaries on your target, execute one of the "install" targets. Where the binaries are copied is controlled by the EXEC_DIR variable in ${GLSDK}/Rules.make. By default, this variable is set up to point to your NFS mounted target file system when you execute the GLSDK setup (setup.sh) script, but can be manually changed to fit your needs.

You can remove all components generated files at any time using:

host $ make clean

And you can rebuild all components using:

host $ make all

You can then install all the resulting target files using:

host $ make install

Creating your own Linux kernel image

The pre-built Linux kernel image (uImage) provided with the GLSDK is compiled with a default configuration. You may want to change this configuration for your application, or even alter the kernel source itself. This section shows you how to recompile the Linux kernel provided with the GLSDK, and shows you how to boot it instead of the default Linux kernel image.

1. If you haven't already done so, follow the instructions in #Setting_up_the_GLSDK to setup your build environment.

2. Recompile the kernel provided with the GLSDK by executing the following:

host $ cd ${GLSDK}
host $ make linux_clean
host $ make linux
host $ make linux_install

3. You will need a way for the boot loader (u-boot) to be able to reach your new uImage. Copy the new uImage that is generated in arch/arm/boot/ directory to the boot filesystem

4. Copy the exported Linux kernel modules from the EXEC_DIR to the /lib/modules directory to the root file system

Using the GLSDK statistics collector (bandwidth application)

Starting from GLSDK 7_02_00_02 release, the default GLSDK filesystem includes a utility to determine the bandwidth statistics of each initiator in the J6 SoC.

This section will give an overview of how the user can use this effectively.

Target side

The tool is called glsdkstatcoll and is present under the /usr/bin folder. This tool requires a config file as an input which is also part of the GLSDK filesystem

Copy the sample config file into your working directory:

target # cp /etc/glsdkstatcoll/* .
target # glsdkstatcoll -h

There are two levels of configuration that the tool allows:

Configuration of the interval and the total time can be controlled via config.ini
The list of initiators can be configured using the initiators.cfg file.

Note that both these files have to be present under the current directory.

After configuration, the user can launch the tool as below:

target # glsdkstatcoll -f config.ini

The tool will run for the specified duration in seconds "TOTAL_TIME" in config.ini and will sample every "INTERVSAL_US" microseconds.

The results from this tool will be available in statcollector.csv

target # ls -al statcollector.csv

Host side

To visualize this data, first install matplotlib:

host # sudo apt-get install python-matplotlib
host # git clone git://git.ti.com/glsdk/example-applications.git
host # cd example-applications/bandwidth-tool/host

Since the analysis of the data will be done over many iterations, the user has been provided with a config file in which some basic configuration can be done.

host # vi configstat.ini # Set the IP Address of the target and also the directory where the statcollector.csv was generated

Once the above setup is completed, the data can be visualized as below:

host # python statcoll_plot.py

This will tool will do the following:

Fetch the file from the target
Figure out all the initiators that did not have any traffic and exclude them from the plot.
Plot the total traffic from EMIF1_SYS and EMIF2_SYS ports
Display the peak, average and average(active) traffic on the various ports.
Note that if the INTERVAL_US is other than 30000 microseconds, user will have to edit the statcoll_plot.py

If the target does not have the Ethernet capabilities, then the file can be fetched and the same tool can be run like below:

host # python statcoll_plot.py -f <name of the file>

There are some further enhancements planned, they will be posted in the git place holder.

Setting up Tera Term

Tera Term is a commonly used terminal program on Windows. If you prefer to use it instead of Minicom, you can follow these steps to set it up.

1. Download Tera Term from this location, and start the application.

2. In the menu select Setup->General... and set:

Default port: COM1

3. In the menu select Setup->Serial Port... and set the following:

Port:         COM1
Baud rate:    115200
Data:         8 bits
Parity:       none
Stop:         1 bit
Flow control: none

NOTE: Kernel Bootargs can be generated by running the setup script. See the section #Setting_up_the_GLSDK for details on running the setup script.

Download the Latest GLSDK

The latest GLSDK is available for download from http://downloads.ti.com/infotainment/esd/jacinto6/glsdk/latest/index_FDS.html

GLSDK releases can be downloaded from http://downloads.ti.com/infotainment/esd/jacinto6/glsdk/

The current version is 7_03_00_03.

For technical support please post your questions at http://e2e.ti.com. Please post only comments about the article DRA7xx GLSDK Software Developers Guide here.