1. Overview¶

1.2.1. Linux SD Card Creation Guide¶

Availible Drives to write images to:

#  major   minor    size   name
1:   8       16    7761920 sdb

Enter Device Number:

Would you like to re-partition the drive anyways [y/n] :

Number of partitions needed [2/3] :

################################################################################

    Choose file path to install from

    1 ) Install pre-built images from SDK
    2 ) Enter in custom boot and rootfs file paths

################################################################################

Choose now [1/2] :

################################################################################

   Multiple rootfs Tarballs found

################################################################################

         1:tisdk-server-extra-rootfs-image-k2g-evm.tar.gz
         2:tisdk-server-rootfs-image-k2g-evm.tar.gz

Enter Number of rootfs Tarball:

no SDK PATH found
Enter path to SDK :

################################################################################

    Choose file path to install from

    1 ) Install pre-built images from SDK
    2 ) Enter in custom boot and rootfs file paths

################################################################################

Choose now [1/2] :

Enter path where SD card tarballs were downloaded :

$ cd <SDK INSTALL DIR>/board-support/prebuilt-images
$ sudo dd if=u-boot-omapl138-lcdk.ais of=/dev/sd<N> seek=117 bs=512 conv=fsync

1.2.2. Windows SD Card Creation Guide¶

Introduction

This page details how to use an image file to create a SD Card containing the embedded Linux system provided with the Linux SDK. This allows a user to evaluate the embedded system on a supported hardware platform.

What is Needed

• Access to a Windows PC
• A valid Linux SDK image for the appropriate processor (AM335x, for example)
• Software to decompress a zip file (ex. 7-zip)
• Software to write an image file to a SD card
• A SD card appropriate for the required hardware platform, must be 2GB or larger
• A SD card reader/writer

Steps to Follow

Here is the process to follow to create the SD card.

1. Download the Processor SDK for Linux image file that you want to use.

2. On a Windows PC, you’ll need software to decompress a zip file. Windows 7 can do this natively. If you don’t already have something that works, the open source software 7-zip is a great choice. Since this image is created with lots of empty space, this step saves about 700 MB of download time.

3. Use the decompression software to decompress the zipped file to an image file. Here’s how to do it with 7-zip:

   

   You should see a status bar as the image is decompressed:

   

   And this is what you should have when it is finished:

   

4. If you don’t have it already, download a program to write the image file to the SD card. The open source Win32 Disk Imager is a good option.

5. Use the software for writing an image to disk to write the decompressed .img file to the SD card.

   1. Plug the SD card into the SD card reader/writer.

   2. Insert the SD card reader/writer into the PC.

   3. Launch the disk writer software, if needed.

   4. Choose the image file for the SDK that you want to write.

      

      And select the appropriate SDK Image file:

      

   5. Choose the SD card as the destination.

      

   6. Write the image to the SD card.

      

      Note

      You’ll likely get the below confirmation box. This command will overwrite whatever disk you point it to, please make sure and choose the correct disk:

      

      You should see the following status bar as the image is being written to the disk:

      

      And when the write is complete, you should get a notification:

      

      You can now close the image writing program:

      

6. Safely eject the SD card from the computer. Here’s an example using Windows 7:

1. Plug it into a supported hardware platform and boot the platform from the SD card.
2. If the platform has a display (Starterkit, for example), you should see the Matrix application from the SDK. If the hardware does not have a display, you should be able to access Matrix remotely through a web browser if the PC and the board are on a common network. You can also connect to the board using a terminal emulator (ex. Tera Term) in order to view the serial console and interact with the embedded Linux system (ex. run ifconfig to get the IP address of the target board in order to connect to it to view remote matrix).

1.2.3. Download and Install the SDK¶

Overview

The Processor SDK Installer (ti-processor-sdk-linux-[platformName]-evm-xx.xx.xx.xx-Linux-x86-Install.bin) will install the necessary components to start your development on the TI microprocessor. The SDK consists of source for the Matrix App launcher starting point application, a development filesystem, a target filesystem, example applications, toolchain and board support package, ease of use scripts and documentation. The Processor SDK now includes the Linaro GCC toolchain.  The Processor SDK was built and tested against a specific Linux Distribution name and version, Ubuntu 14.04 and 16.04. Note this does not prevent the user from installing the SDK on other Linux distributions.

How to Get the SDK Installer

There are two ways you can get the installer:

1. From a file downloaded from the SDK download page. This will always host the latest version of SDK.

   Note

   The second way below is not applicable to K2H/K2K, K2E, and K2L platforms, which are using SD card.

2. From the SD Card included with a TI EVM. This may not be the latest version of the SDK. We recommend checking the above site and using the latest version if at all possible. Before running the SDK Installer from the SD card, the SD Card from the EVM box needs to be mounted to your Linux Host PC (using a USB SD Card reader).  The SDK Installer is found in the START_HERE partition of the SD card.

How to Run the SDK Installer

Make sure that the execute permissions are set. Bring up a terminal window and change directories to the where the installer is located (probably the Downloads directory if downloaded or the START_HERE partition mounted from the SD Card) and run the following commands:

chmod +x ./ti-processor-sdk-linux-[platformName]-evm-xx.xx.xx.xx-Linux-x86-Install.bin ./ti-processor-sdk-linux-[platformName]-evm-xx.xx.xx.xx-Linux-x86-Install.bin |

Alternatively, you can give execute permissions and run the SDK Installer by double clicking on it within your Linux host PC.

Additional Installer Options

Invoking the installer with argument –help will list available options for the installer (e.g. text installer, etc.):

./ti-processor-sdk-linux-[platformName]-evm-xx.xx.xx.xx-Linux-x86-Install.bin –help |

SDK Installer Execution Steps

1. Confirm User is to confirm if loading the Processor SDK is ok. This is important to note if the user is trying to over-install on an existing directory and has made changes to the directory.
2. Directory Install Location The user will be prompted for a location on where to put the Processor SDK. An example is given below.
3. Installation of software The software is installed.

Where to install the Processor SDK package

The default selection of where to install is the user’s home directory. In this particular example the name of the user is ‘sitara’.

1.2.4. Program EVM User Guide¶

cd bin/program_evm/binaries/evmk2h/
ln -sv ../../../../board-support/prebuilt-images/u-boot-spi-k2hk-evm.gph nor.bin
ln -sv ../../../../filesystem/tisdk-server-rootfs-image-k2hk-evm.ubi nand.bin

cd bin/program_evm/binaries/evmk2e/
ln -sv ../../../../board-support/prebuilt-images/u-boot-spi-k2e-evm.gph nor.bin
ln -sv ../../../../filesystem/tisdk-server-rootfs-image-k2e-evm.ubi nand.bin

cd bin/program_evm/binaries/evmk2l/
ln -sv ../../../../board-support/prebuilt-images/u-boot-spi-k2l-evm.gph nor.bin
ln -sv ../../../../filesystem/tisdk-server-rootfs-image-k2l-evm.ubi nand.bin

file_name  = nor.bin

file_name  = nand.bin

├───program_evm
│   │   program_evm.js
│   │
│   ├───binaries
│   │   └───evmxxx
│   │           eepromwriter_evmxxx.out
│   │           eepromwriter_input.txt
│   │           eepromwriter_input50.txt
│   │           eepromwriter_input51.txt
│   │           nand.bin (symbolic link created as above)
│   │           nandwriter_evmxxx.out
│   │           nand_writer_input.txt
│   │           nor.bin (symbolic link created as above)
│   │           norwriter_evmxxx.out
│   │           nor_writer_input.txt
│   ├───configs
│   │   └───evmxxx
│   │           evmxxx.ccxml
│   │           evmxxx-linuxhost.ccxml
│   ├───gel
│   │           xtcievmk2x.gel
│   │           evmk2e.gel
│   │           tcievmk2l.gel
│   │           README.txt
│   └───logs (empty directory)

1.2.4.6. Verify CCS Connection¶

First, start CCS on linux host machine and configure the target configuration for the EVM (e.g., bin/program_evm/configs/evmk2h/evmk2h-linuxhost.ccxml). Then, launch the target configuration, and verify the connection to the ARM and DSP through JTAG.

After the CCS connection is verified, disconnect the target connection, exit CCS and continue to Set the Environment Variables.

Update firmware on xd200 pod for USB3 Ports

Note

Please note that this section is needed only the CCS connection cannot be established successfully.

When USB3 ports are used for the JTAG, the following error can be reported when testing the connection to the target.

...
This utility has selected a 560/2xx-class product.
This utility will load the program 'xds2xxu.out'.
E_RPCENV_IO_ERROR(-6) No connection
Failed to open i/o connection (xds2xxu:0)
...

When this happens, it is required to update the firmware on the xd200 pod. This can be done on a PC which is able to communicate to the xd200 pod, and has CCS and the latest TI emulators package installed. Example:

cd ccsv6/ccs_base/common/uscif/xds2xx
xds2xx_conf.exe update xds2xxu 0 xds200_firmware_v1006.bin
xds2xx_conf.exe boot xds2xxu 0

Set the EVM for no-boot mode

For EVMK2H

Due to hardware NAND issue, EVM of certain revisions need to use alternative programming method:

EVM Revision	NAND Known Issue	Programming Method
Rev 3.0	Yes	Alternative U-Boot command
Rev 2.0	Yes	Alternative U-Boot command
Rev 1.x	No	Program_evm

For Rev 2.0 and 3.0 EVM using alternative U-Boot command to program NAND, please follow the steps below: Set the boot mode to SPI boot mode: Set_SPI_boot

1. Set up TFTP server
2. copy filesystem/tisdk-server-rootfs-image-k2h-evm.ubi to tftp directory
3. Have Ethernet cable connected to the EVM and verify the connection to the TFTP server
4. Boot up the EVM to the U-boot prompt and type the following commands:

u-boot# setenv serverip <TFTP server IP address>
u-boot# setenv tftp_root <tftp directory>
u-boot# setenv addr_fs 0x82000000
u-boot# nand erase.part ubifs
u-boot# dhcp ${addr_fs} ${tftp_root}/tisdk-server-rootfs-image-k2h-evm.ubi
u-boot# nand write ${addr_fs} ubifs ${filesize}
u-boot# env default -f -a
u-boot# setenv boot ubi
u-boot# saveenv

Once it is completed, the EVM is ready to use.

For Rev 1.0 EVM, make sure the EVM dip switches are set for no-boot mode and continue.

SWITCH	Pin1	Pin2	Pin3	Pin4
SW1	Off	Off	Off	On

See instruction here for K2H no boot mode for reference K2H_Noboot

For EVMK2E

Make sure the EVM dip switches are kept as below to put the board in no-boot mode, and continue.

SWITCH	Pin1	Pin2	Pin3	Pin4
SW1	On	On	On	On

See instruction here for K2E no boot mode for reference: K2E_NoBoot

For EVMK2L

Make sure the EVM dip switches are kept as below, and continue.

SWITCH	Pin1	Pin2	Pin3	Pin4
SW1	On	On	On	On

See instructions here for K2L no boot mode for reference: K2L_NoBoot

Set the Environment Variables

Please make sure the below environment variables needs to be set. Otherwise there could be some unexpected behavior experienced.

1. Set the DSS_SCRIPT_DIR environment variable (Mandatory) to your Code Composer Studio scripting bin directory. Example:

export DSS_SCRIPT_DIR=~/ti/ccsv6/ccs_base/scripting/bin

2. Set the PROGRAM_EVM_TARGET_CONFIG_FILE environment variable. Please provide the path for the ccxml file that is created for the EVM for the CCS. Example:

export PROGRAM_EVM_TARGET_CONFIG_FILE=configs/evmk2h/evmk2h-linuxhost.ccxml

DSS Script Arguments

General Script Usage

Script Usage:

cd bin/program_evm
$DSS_SCRIPT_DIR/dss.sh program_evm.js evm(k2h|k2e|k2l)[-le] (nor|nand)

k2h:TCI6638 device

k2e:C66AK2E device

k2l:TCI6630 device

-le (optional): Little Endian (default)

-be (optional): Big Endian

(nor|nand): choose from nor or nand

Formatting the NAND Flash

Note

Sometimes, NAND flash could be corrupted (e.g. EVM boots from UBI and does not gracefully shut down), NAND flash needs to be formatted before loading the program using program_evm utility.

The program_evm supports formatting the NAND device as below. Linux:

cd bin/program_evm
$DSS_SCRIPT_DIR/dss.sh program_evm.js evm(k2h|k2e|k2l)-le format-nand

Warning

Please note that this would erase all the nand blocks.

Executing the DSS script to restore factory default images

1. cd “bin/program_evm” directory
2. Set the necessary environment variables as described under Set the Environment Variable.
3. Run the “program_evm.js” script command from program_evm directory.

Example:

cd bin/program_evm
$DSS_SCRIPT_DIR/dss.sh program_evm.js evmk2h-le nor

This will write all the little endian images to K2H EVM.

Sample DSS Script Output

The sample output after running the DSS Script is as below.

Note

The loading of nand.bin can take up to a few minutes depending on the image size.

bin/program_evm$ $DSS_SCRIPT_DIR/dss.sh program_evm.js evmk2h nor
board: evmk2h
endian: Little
emulation: XDS2xx emulator
binaries: /home/user/ti-processor-sdk-linux-k2hk-evm-02.00.01.07/bin/program_evm/binaries/evmk2h/
ccxml: configs/evmk2h/evmk2h-linuxhost.ccxml
C66xx_0: GEL Output:
Connecting Target...

C66xx_0: GEL Output: TCI6638K2K GEL file Ver is 1.3

C66xx_0: GEL Output: Detected PLL bypass disabled: SECCTL[BYPASS] = 0x00000000

C66xx_0: GEL Output: (3a) PLLCTL = 0x00000040

C66xx_0: GEL Output: (3b) PLLCTL = 0x00000040

C66xx_0: GEL Output: (3c) Delay...

C66xx_0: GEL Output: (4)PLLM[PLLM] = 0x0000000F

C66xx_0: GEL Output: MAINPLLCTL0 = 0x07000000

C66xx_0: GEL Output: (5) MAINPLLCTL0 = 0x07000000

C66xx_0: GEL Output: (5) MAINPLLCTL1 = 0x00000040

C66xx_0: GEL Output: (6) MAINPLLCTL0 = 0x07000000

C66xx_0: GEL Output: (7) SECCTL = 0x00090000

C66xx_0: GEL Output: (8a) Delay...

C66xx_0: GEL Output: PLL1_DIV3 = 0x00008002

C66xx_0: GEL Output: PLL1_DIV4 = 0x00008004

C66xx_0: GEL Output: PLL1_DIV7 = 0x00000000

C66xx_0: GEL Output: (8d/e) Delay...

C66xx_0: GEL Output: (10) Delay...

C66xx_0: GEL Output: (12) Delay...

C66xx_0: GEL Output: (13) SECCTL = 0x00090000

C66xx_0: GEL Output: (Delay...

C66xx_0: GEL Output: (Delay...

C66xx_0: GEL Output: (14) PLLCTL = 0x00000041

C66xx_0: GEL Output: PLL has been configured (CLKIN * PLLM / PLLD / PLLOD = PLLOUT):

C66xx_0: GEL Output: PLL has been configured (122.88 MHz * 16 / 1 / 2 = 983.04 MHz)

C66xx_0: GEL Output: Power on all PSC modules and DSP domains...

C66xx_0: GEL Output: Power on all PSC modules and DSP domains... Done.

C66xx_0: GEL Output: WARNING: SYSCLK is the input to the PA PLL.

C66xx_0: GEL Output: Completed PA PLL Setup

C66xx_0: GEL Output: PAPLLCTL0 - before: 0x0x07080400    after: 0x0x07080400

C66xx_0: GEL Output: PAPLLCTL1 - before: 0x0x00002040    after: 0x0x00002040

C66xx_0: GEL Output: DDR begin

C66xx_0: GEL Output: XMC setup complete.

C66xx_0: GEL Output: DDR3 PLL (PLL2) Setup ...

C66xx_0: GEL Output: DDR3 PLL Setup complete, DDR3A clock now running at 666 MHz.

C66xx_0: GEL Output: DDR3A initialization complete

C66xx_0: GEL Output: DDR3 PLL Setup ...

C66xx_0: GEL Output: DDR3 PLL Setup complete, DDR3B clock now running at 800MHz.

C66xx_0: GEL Output: DDR3B initialization complete

C66xx_0: GEL Output: DDR done

Writer:/home/user/ti-processor-sdk-linux-k2hk-evm-02.00.01.07/bin/program_evm/binaries/evmk2h/norwriter_evmk2h.out

NOR:/home/user/ti-processor-sdk-linux-k2hk-evm-02.00.01.07/bin/program_evm/binaries/evmk2h/nor.bin

Start loading nor.bin
Start programming NOR
2016_01_7_174332
NOR Writer Utility Version 01.00.00.04

Flashing sector 0 (0 bytes of 458752)
Flashing sector 1 (65536 bytes of 458752)
Flashing sector 2 (131072 bytes of 458752)
Flashing sector 3 (196608 bytes of 458752)
Flashing sector 4 (262144 bytes of 458752)
Flashing sector 5 (327680 bytes of 458752)
Flashing sector 6 (393216 bytes of 458752)
Reading and verifying sector 0 (0 bytes of 458752)
Reading and verifying sector 1 (65536 bytes of 458752)
Reading and verifying sector 2 (131072 bytes of 458752)
Reading and verifying sector 3 (196608 bytes of 458752)
Reading and verifying sector 4 (262144 bytes of 458752)
Reading and verifying sector 5 (327680 bytes of 458752)
Reading and verifying sector 6 (393216 bytes of 458752)
NOR programming completed successfully
End programming NOR

Note

For EVMs without Security Accelerator components, PSC errors will show up due to a known issue in GEL file. The PSC errors can be ignored and are not fatal. The program EVM will proceed and complete successfully.

Programming the bin files for devices without DSP core

This section describes how to program the bin files to either NOR or NAND on the devices without DSP core (AM5K2E02 and AM5K2E04). The installation of Processor SDK and Code Composer Studio is required.

Set up TFTP server on the Linux host machine

Eable the TFTP server service on the Linux host machine, and copy u-boot-{platform].gph and isdk-server-rootfs-image-{platform].ubi from ProSDK installed directory to the tftp server directory. The files are located in board-support/prebuilt-images and filesystem directory respectively.

Have the Ethernet connection between the EVM and TFTP Server.

Set the EVM for no-boot mode

Follow the instruction in previous section to set the dip switch of the EVM in no-boot mode

Load and Run U-Boot on keystone EVMs using CCS

Follow the instructions in {Proc_SDK_Install_Dir}/board-support/u-boot-{Version}/board/ti/ks2_evm/README to run u-boot using CCS

Configuration for TFTP download

Interrupt the boot process when running u-boot using CCS. In the u-boot prompt console, configure the u-boot environment variables for TFTP download

# setenv serverip <TFTP_SERVER_IP>
# setenv tftp_root <TFTP_SERVER_DOWNLOAD_DIR>

Restore Factory default images

To restore the u-boot image in NOR:

# run get_uboot_net
# run burn_uboot_spi

To restore the combined kernel and fileystem UBI image in NAND:

# run get_ubi_net
# run burn_ubi

Note

When programming UBI image to NAND, be sure the UBI image size is enough to fit in NAND memory.

Reset U-Boot Environment Variables

Reset U-Boot environment variables if U-Boot version has been changed

# env default -f -a
# saveenv

Verification

Serial Port Setup

Connect the RS232 Serial cable provided in the box to the serial port of the Host PC. If Host is running Windows OS, start tera term and configure the serial port settings as follows.

1.2.4.7. Verifying NOR¶

EVMK2H, EVMK2E, EVMK2L

1. Set the dip switches as below to set SPI boot mode

SWITCH	Pin1	Pin2	Pin3	Pin4
SW1	Off	Off	On	Off

2. Power Cycle the board.
3. Make sure the evm is connected to the DHCP server.
4. U-Boot will show up on the UART. A sample screen is shown below.

Verifying NAND

EVMK2H, EVMK2E, EVMK2L

NOR(U-Boot) must be flashed prior to performing any of the steps below.

For EVMK2H, EVMK2E & EVMK2L it is necessary to reformat the NAND Flash prior to burning the image. Example command to do this:

%DSS_SCRIPT_DIR%\dss.sh program_evm.js evmk2h format-nand

After entering the command, burn the NAND and perform the steps below to verify.

1. Set the dip switches as below to set SPI boot mode

SWITCH	Pin1	Pin2	Pin3	Pin4
SW1	Off	Off	On	Off

2. Power Cycle the board. U-Boot will show up on the UART.
3. Type the following commands into U-Boot:

env default –f –a
setenv boot ubi
boot

4. A sample screen is shown below.

1.2.5. Run Setup Scripts¶

Overview

• Verification that the Linux host is the recommended Ubuntu LTS version
• Installation of required host packages
• Target FileSystem installation
• NFS setup
• TFTP setup
• Minicom setup
• uboot setup
• Load uboot script

BeagleBone Black Users

To run the SDK’s setup scripts the following cables are required to be connected to the BeagleBone Black and your Linux PC. Please ensure both are connected before following any of the steps in this guide.

• USB Mini cable (included with BBBlack)
• FTDI Serial cable

Clearing the eMMC

The BeagleBone Black includes an eMMC device on it which comes pre-flashed with an Angstrom distribution. Because eMMC is the default boot mode for this board we need to prevent it from being able to boot by either removing or renaming the MLO.

To do this you will need to wipe out the MLO file stored in the eMMC.

To eliminate the MLO first boot up the board with the USB mini cable connected to the board and your PC. Once the Angstrom kernel loads your host will mount the eMMC boot partition on your Linux host under /media/BEAGLEBONE. You can then erase or rename the MLO file here. You can also login to the BeagleBone Black and rename or remove /boot/MLO (e.g., mv /boot/MLO /boot/OLDMLO).

Once the above steps are completed you can follow the remaining steps on this guide to execute the setup script.

Restoring the eMMC

Instructions on restoring the eMMC can be found here.

K2H/K2K, K2L, and K2E Users

For K2H/K2K, K2L, and K2E platforms, if u-boot has not been loaded before or the previous u-boot is somehow corrupted, please first program the EVMs following the instructions at Program EVM User Guide. After that, continue to follow the sections below to use the setup scripts.

How to run the setup script

The Setup Script is located in the Processor SDK installation directory.  By default, this directory has a name that has the form ti-processor-sdk-linux-<Hardware-Platform>-<Version>.  Change to that ti-processor-sdk-linux install directory.  Then run the script:

./setup.sh

Detailed step by step description through the setup script

The following sections describe in more detail how to run the script and what is doing.

Installation of Required Host Packages

This section will check to make sure you have the proper host support packages to allow you do the following tasks:

• telnet
• bring up menuconfig, the kernel configuration tool
• mounting filesystem via nfs
• tftp
• bring up minicom
• rebuild u-boot

If your host lacks any of the needed packages, they will automatically be installed in this step.

The command below is an example of what this script is doing. The actual packages may vary for different releases:

sudo apt-get install xinetd tftpd nfs-kernel-server minicom build-essential libncurses5-dev autoconf automake dos2unix screen lrzsz lzop u-boot-tools

Add to Dialout Group

A unique step is required for users using Ubuntu 12.04+. By default the user does not have the proper permissions to access a serial device ( ex ttyS0, ttyUSB0, etc...). A user must be apart of a “dialout” group to access these serial device without root privileges.

During this step the script will check if the current Linux user is apart of the dialout group. If not the current Linux user will automatically be added to the dialout group. The Linux user will still be required to use sudo when accessing the serial device until the user logs out and then logs back in.

Target FileSystem Installation

This step will extract the target filesystem.

The default locations is: /home/user/ti-processor-sdk-linux-[platformName]-evm-x.x.x.x/targetNFS

In which directory do you want to install the target filesystem?(if this directory does not exist it will be created)
[ /home/user/ti-processor-sdk-linux-[platformName]-evm-x.x.x.x/targetNFS ]

You can override the default location by typing in another location or by hitting <Enter> you can accept the default location. This can take a little time to untar and unzip the filesytem.

If you have run this script more than once and the filesystem already exists, you will be asked to either:

• rename the filesystem
• overwrite the filesystem
• skip filesystem extraction

NFS Setup

This step will allow you to export your filesystem which was extracted in the previous step.

• This step adds the path to root filesystem from the previous step to the file /etc/exports on your host.
• The NFS kernel daemon is then stopped and then restarted to make sure the exported file system is recognized.

TFTP Setup

This section will setup tftp access on your host.

Which directory do you want to be your tftp root directory?(if this directory does not exist it will be created for you)
[ /tftpboot ]

The default location is /tftpboot which is off of the root directory on your linux host and requires administrator privileges. You can hit <Enter> to select the default location or type in another path to override the default. Then the following task occur:

• A tftp config file is created for you on your host at /etc/xinetd.d/tftp
• The tftp server is stopped and then restarted to insure the changes are picked up.

If you have run this script more than once or the filename already exists, you will be asked to select one of the following options.

• rename the filesystem
• overwrite the filesystem
• skip filesystem extraction

Repeat this for any additional prompts about /tftpboot files.

Minicom Setup

This step will set up minicom (serial communication application) for SDK development.

Which serial port do you want to use with minicom?
[ /dev/ttyUSB0 ]

For most boards, the default /dev/ttyUSB0 should be selected. For Beaglebone which has a USB-to-Serial converter, just hit enter and the proper serial port will be setup in a later step.

• A minicom configuration will be saved for you at /home/user/.minirc.dfl
• The old configuration if there was one will be saved at /home/user/.minirc.dfl.old

The configuration saved to /home/user/.minirc.dfl can be changed, see the Software Development Guide for more information.

uboot Setup

This section will create the necessary u-boot commands to boot up your board.

The script will detect your ip address and display it. You can override the detected value by entering an alternate value.

This step will set up the u-boot variables for booting the EVM.
Autodetected the following ip address of your host, correct it if necessary
[ xxx.xxx.xxx.xxx ]

Next, you will be prompted where you prefer your kernel and file system to be located.

• Kernel location
  • TFTP - located on your Host in your designated /tftpboot directory
  • SD card - located in the 1st partition named “boot” of your SD card
• Filesystem location
  • NFS - located on your Host. The location is where the file system was extracted in an earlier step.
  • SD card - located on the 2nd partition named “rootfs” of your SD card.

Next if you have selected TFTP, you will be prompted which uImage you want to boot using TFTP. You will be given a list of existing uImage’s and you can type one in from the list or hit <Enter> to select the default option. The default option will be the uImage corresponding to the SDK installation. This will be used in the next step to create the necessary u-boot options to boot up your device.

Load uboot Script

This section creates a minicom script or a uEnv.txt file which will be used by u-boot to provide the necessary commands to boot up in the preferred configuration.

• For boards with straight serial connectors and K2H/K2K, K2E, and K2L platforms, a minicom script is created.
• For boards like beaglebone with a USB-to-Serial configuration, then a uEnv.txt script is created and placed in the /boot partition of the SD card.

1.2.6. Top-Level Makefile¶

Overview

Inside of the Processor Linux SDK there is a top-level Makefile that can be used to build some of the sub-components found within the SDK. This Makefile uses the Rules.make file and gives an example of how the various components can be built and the parameters to use.

NOTE: You should not call this makefile with the **environment-setup script** sourced. The sub-component Makefiles will handle sourcing this script where appropriate, but some make targets such as the Linux kernel make target do not work properly when this script is already sourced.

Rules.make

The following sections cover the Rules.make file found in the top-level of the Processor Linux SDK.

Purpose

The Rules.make file in the top-level of the Processor Linux SDK is used not only by the top-level Makefile, but also by many of the sub-component Makefiles to gain access to common shared variables and settings. The next section covers the main variables defined in the Rules.make file.

Variables Defined

• PLATFORM - This represents the machine name of the device supported by the SDK. This machine name has a direct correlation to the machine definition in the Arago project build system. The PLATFORM variable can be used by component Makefiles to make decisions on a per-machine basis.
• ARCH - This represents the architecture family of the machine. This can be used by component Makefiles to change settings such as mtune values in CFLAGS based on the architecture of the PLATFORM.
• UBOOT_MACHINE - This us used when building u-boot to configure the u-boot sources for the correct device.
• TI_SDK_PATH - This points to the top-level of the SDK. This is the same directory where the Rules.make file itself is located.
• DESTDIR - This points to the base installation directory that applications/drivers should be installed to. This is usually the root of a target file system but can be changed to point anywhere. By default the initial value is a unique key value of __DESTDIR__ which is replaced with the location of the target NFS file system when the **setup.sh** script is run.
• LINUX_DEVKIT_PATH - This points to the linux-devkit directory. This directory is the base directory containing the cross-compiler and cross-libraries as well as the **environment-setup** script used by many component Makefiles to source additional variable settings.
• CROSS_COMPILE - This setting represents the CROSS_COMPILE prefix to be used when invoking the cross-compiler. Many components such as the Linux kernel use the variable CROSS_COMPILE to prepend the proper prefix to commands such as gcc to invoke the ARM cross-compiler.
• ENV_SETUP - This points to the **environment-setup** script in the linux-devkit directory used by many components to configure for a cross-compilation build.
• LINUXKERNEL_INSTALL_DIR - This points to the location of the Linux kernel sources, which is used by components such as out-of-tree kernel drivers to find the Linux kernel Makefiles and headers.

Makefile

The following sections cover the Makefile found in the top-level of the Processor Linux SDK

Target Types

For each of the targets discussed below the following target type are defined

• <target> - This is the build target which will compile the release version of the component
• <target>_install - This target will install the component to the location pointed to by DESTDIR
• <target>_clean - This target will clean the component

Top-Level Targets

The Processor Linux SDK provides the following targets by default which will invoke the corresponding component targets:

• all - This will call the build target for each component defined in the Makefile
• install - This will call the install target for each component defined in the Makefile
• clean - This will call the clean target for each component defined in the Makefile

Common Targets

The following targets are common to all platforms in Processor Linux SDK:

• linux - Compiles the Linux kernel using the default tisdk_<PLATFORM>_defconfig configuration
• matrix-gui - Builds the matrix-gui sources
• am-benchmarks - Builds the ARM Benchmarks for the ARCH defined in Rules.make
• am-sysinfo - Build the helper applications used by the system settings demos in Matrix
• matrix-gui-browser - Builds the matrix GUI browser Qt project
• refresh-screen - Builds the refresh screen Qt project

Additional Targets

Depending on the capabilities and software available for a given device additional targets may also be defined. You can find the list of all the targets by looking at the all target as described in the **Top-Level Targets** section above. Add devices will have one or the other of the following targets depending on the u-boot version used:

• u-boot-spl - This target will build both u-boot and the u-boot SPL (MLO) binaries used in newer versions of u-boot. This actually provides a u-boot and u-boot-spl target in the Makefile.
• u-boot-legacy - This target will build the u-boot binary for older versions of u-boot which do not support the SPL build.
• wireless - A wireless top-level build target that can be used to rebuild the wireless drivers against the kernel sources in the board-support directory.

Usage Examples

The following examples demonstrate how to use the top-level Makefile for some common tasks. All of the examples below assume that you are calling the Makefile from the top-level of the SDK.

• Build Everything

host# make

• Clean Everything

host# make clean

• Install Everything

host# make install

• Build the Linux kernel

host# make linux

• Install the Linux kernel modules

host# make linux_install

• Build the ARM Benchmarks

host# make am-benchmarks

• Clean the ARM Benchmarks

host# make am-benchmarks_clean

• Install the ARM Benchmarks

host# make am-benchmarks_install

A Note about Out-of-tree Kernel Modules

Some drivers like the SGX drivers are delivered as modules outside of the kernel tree. If you rebuild the kernel and install it using the “make linux_install” target you will also need to rebuild the out of tree modules and install them as well. The modules_install command used by the linux_install target will remove any existing drivers before installing the new ones. This means those drivers are no longer available until they have been rebuilt against the kernel and re-installed.

A Note about the Linux Kernel Version

To simplify and accelerate rebuilding and installing the linux kernel, the file .scmversion is included in the kernel source tree to pin down the version of the kernel provided in the SDK. If upgrading the kernel sources or adding new commits, this file should be removed so that the appropriate version is built into the kernel image.

1.2.7. GCC ToolChain¶

Overview

The Processor SDK for Linux contains a Linaro based toolchain for Cortex A devices. The Linaro toolchain also enables hardware floating point (hardfp) support. Older toolchains including arm-arago-linux-gnueabi- uses software floating point (softfp). This results in software built using a hardfp toolchain being incompatible with software built with a softfp toolchain.

Linaro Toolchain

The Processor SDK for Linux uses a Linaro based tool chain. Other than using a newer version of GCC the Linaro tool chain also supports hard floating point also known as Hard-FP. Hard-FP uses the FPU on the ARM instead of simulating it. Older tool chains including the Arago tool chain uses soft floating point (Soft-FP). Binaries built using a soft-fp tool chain are not compatible with binaries built using a hard-fp. Therefore, you must rebuild all binaries to use either hard-fp and soft-fp since you can’t mix and match. By default all binaries included in the Processor SDK for Linux will be built for hard-fp.

The name of the toolchain binaries have also been updated from older versions of the SDK. Previous versions may have used a prefix of “arm-arago-linux-gnueabi-”. Current SDK toolchains uses a prefix of “arm-linux-gnueabihf-” For example, the new toolchain’s gcc compiler is named arm-linux-gnueabihf-gcc.

Linux-Devkit Structure

Here is the structure of the Linux-devkit directory within the SDK.

Location in SDK

The toolchain is located in the Linux SDK in the <SDK INSTALL DIR>/linux-devkit directory. The following sections will cover the key components of the toolchain.

Cross-Compilers/Tools

The cross-compilers and tools such as qmake2 can be found the the <SDK INSTALL DIR>/linux-devkit/bin directory. Adding this directory to your PATH will allow using these tools. For example:

host# export PATH=”<SDK INSTALL DIR>/linux-devkit/sysroots/x86_64-arago-linux/usr/bin:$PATH”

The cross-compile tools are prefixed with the arm-linux-gnueabihf- prefix. i.e. the GCC cross compiler is called arm-linux-gnueabihf-gcc. Additional tools are also located here such as the qmake2, rcc, uic tools used by Qt. In addition there is a qt.conf file that can be used by tools such as Qt creator to use the pre-built libraries found in the Linux SDK.

Cross-Compiled Libraries

The toolchain within the Linux SDK contains more than just the cross-compiler, it also contains pre-built libraries that can be used in your applications without requiring you to cross-compile them yourself. These libraries include packages from alsa to zlib. The libraries are located in the <SDK INSTALL DIR>/linux-devkit/sysroots/<device specific string>-vfp-neon-linux-gnueabi/ directory. For a list of the libraries you can refer to the software manifest found in the <SDK INSTALL DIR>/docs directory or look at the list of libraries available in the <SDK INSTALL DIR>/linux-devkit/sysroots/<device specific string>-vfp-neon-linux-gnueabi/usr/lib directory. You will also find the header files corresponding to these libraries in the <SDK INSTALL DIR>/linux-devkit/sysroots/<device specific string>-vfp-neon-linux-gnueabi/usr/include directory. Usage of these libraries will be covered in more detail in the next sections, but as an example if your application wants access to the alsa asound library then you can now do the following command (assuming you have added the cross compiler to your PATH):

host# arm-linux-gnueabihf-gcc -lasound app.c -o app.out |

environment-setup script

When cross-compiling packages that use configuration tools and autotools there are many settings that are required to make sure that the proper cross-compile libraries are used. The environment-setup script located in the <SDK INSTALL DIR>/linux-devkit directory handles this for you. This script exports variables to perform actions such as:

• Adding the toolchain to the PATH
• Setting up CPATH
• Setting up PKG_CONFIG_* paths
• Setting standard variable such as CC, CPP, AR to the cross-compile values

To use the environment-setup script you only need to source it. This is as simple as:

host# source linux-devkit/environment-setup |

To know if the environment setup script has been sourced in your current shell the shell prompt will be changed to contain the [linux-devkit]: prefix in the command prompt.

The Usage section below will cover some cases where using the environment-setup script is useful.

When Compiling the Linux Kernel

Because environment-setup changes standard variables such as CC you should not use this script when compiler projects that build host-side as well as target-side tools. A prime example of this is the Linux kernel, which builds some host side tools to help during the kernel build. If the environment-setup script has been sourced then the CC value will specify the cross-compiler for the host-side tool build. This means that the tools compiled and used during the kernel build will be compiled for the ARM platform while the kernel build tries to run these tools on an Intel platform. This will cause the tools to fail to run and the kernel to fail to compile.

Usage

The following sections give some examples of how to use the included toolchain to compile simple applications such as HelloWorld to more complex examples such as configuring and compiler GStreamer plugins.

Simple Cross-Compile

In the simplest case the cross-compiler can be used to compile simple applications that just need access to standard libraries. The two examples below cover an application that uses only the standard libgcc libraries and another example that uses the pthreads threading library.

HelloWorld

Simple applications like HelloWorld can be compiled using just a call to the cross-compiler since the cross-compiler can find the libraries it was built with without any issues. The following steps will show how to make a simple helloworld application and cross-compile that application.

Create a helloworld.c file |

#include <stdio.h>

 int main() {
     printf ("Hello World from TI!!!\n");
     return 0;
 }

Cross-compile the helloworld.c file using the cross-compile toolchain. In this example we will invoke the toolchain without it having been added to our PATH.

host# <SDK INSTALL DIR>/linux-devkit/sysroots/x86_64-arago-linux/usr/bin/arm-linux-gnueabihf-gcc helloworld.c -o helloworld

After the above steps are run you should now have a helloworld executable in your directory that has been compiled for the ARM. A simple way to check this is to run the following command:

host# file helloworld

This should yield output like:

“helloworld: ELF 32-bit LSB executable, ARM, version 1 (SYSV), dynamically linked (uses shared libs), for GNU/Linux 2.6.31, not stripped”

Using PThreads

In many cases your simple application probably wants to use additional libraries than the standard libgcc and glibc libraries. In this case you will need to include the header files for those libraries as well as add the library to the compile line. In this example we will look at how to build a simple threading application and use the pthread library. This example was derived from the example code at **https://www.amparo.net/ce155/thread-ex.html**

Create a file thread-ex.c with the following contents

#include <unistd.h>;
#include <sys/types.h>;
#include <errno.h>;
#include <stdio.h>;
#include <stdlib.h>;
#include <pthread.h>;
#include <string.h>;

int print_message_function(void *ptr);

/* struct to hold data to be passed to a thread
this shows how multiple data items can be passed to a thread */
typedef struct str_thdata
{
    int thread_no;
    char message[100];
} thdata;

int main(int argc, void **argv)
{
    pthread_t thread1, thread2;
    thdata data1, data2;

    data1.thread_no = 1;
    strcpy(data1.message, "Hello!");

    data2.thread_no = 2;
    strcpy(data2.message, "Hi!");

    pthread_create (&thread1, NULL, (void *) &print_message_function, (void *) &data1);
    pthread_create (&thread2, NULL, (void *) &print_message_function, (void *) &data2);

    pthread_join(thread1, NULL);
    pthread_join(thread2, NULL);

    exit(0);
}

int print_message_function ( void *ptr )
{
    thdata *data;
    data = (thdata *) ptr;  /* type cast to a pointer to thdata */

    /* do the work */
    printf("Thread %d says%s \n", data->thread_no, data->message);

    return 0;
}

Cross-compile the thread-ex.c file using the cross-compile toolchain. In this example we will first add the toolchain to our PATH. This only needs to be done once. We will also add the pthread library to the compile line so that we will link with the library file that provides the pthread_* functions. |

export PATH=”<SDK INSTALL DIR>/linux-devkit/sysroots/x86_64-arago-linux/usr/bin/:$PATH”

arm-linux-gnueabihf-gcc ‘-lpthread’ thread-ex.c -o thread-ex

Configure/Autotools

The last case to cover is one where the environment-setup script is useful. In this case we will download the gst-plugins-bad package and configure and build it using the environment-setup script to configure the system for the autotools to properly detect the libraries available as pre-built libraries.

1. First download the gst-plugins-bad-0.10.11.tar.gz package wget https://gstreamer.freedesktop.org/src/gst-plugins-bad/gst-plugins-bad-0.10.11.tar.gz

   IMPORTANT In order to build the gst-plugins-bad package you will need libglib2.0-dev installed on your system. You can install this using sudo apt-get install libglib2.0-dev

2. Extract the plugins tarball tar zxf gst-plugins-bad-0.10.11.tar.gz

3. Change directory into the extracted sources cd gst-plugins-bad-0.10.11

4. Source the <SDK INSTALL DIR>/linux-devkit/environment-setup script to prepare to configure and build the plugins. source <SDK INSTALL DIR>/linux-devkit/environment-setup

5. Now configure the package. We need to define the host setting to tell the configuration utility what our host system is, and we will also disable some plugins that are known to be bad. ./configure –host=i686 –disable-deinterlace2 –disable-x264

6. When the configuration is done the last sections will show which plugins will be build based on the libraries available. This is the key point behind what the environment-setup script provides. By setting up the PKG_CONFIG_* paths and other variables the configure script was able to check for required libraries being available to know which plugins to enable. Now that the sources have been configured you can compile them with a simple make command. make

1.3.1. Introduction¶

This page provides the steps to build the Processor SDK and individual components from source. The Processor SDK build is based on the Arago Project which provides a set of layers for OpenEmbedded and the Yocto Project targeting TI platforms.

This page will provide the basic steps require to recreate the Processor SDK along with a reference of Processor SDK specific configurations, build targets, and target devices. Also, tips and suggestions are provided along with links for more in-depth information.

1.3.2. Quick Start¶

$ sudo apt-get install git build-essential python diffstat texinfo gawk chrpath dos2unix wget unzip socat doxygen libc6:i386 libncurses5:i386 libstdc++6:i386 libz1:i386

sudo dpkg-reconfigure dash

$ sudo dpkg-reconfigure dash
(Select "no" when prompted)

$ yum install gawk make wget tar bzip2 gzip python unzip perl patch diffutils diffstat git cpp gcc gcc-c++ glibc-devel texinfo chrpath socat SDL-devel xterm doxygen glibc-devel.i686 glibc-devel libstdc++-devel.i686 libgcc.i686 libstdc++-devel dos2unix

$ wget https://releases.linaro.org/components/toolchain/binaries/7.2-2017.11/arm-linux-gnueabihf/gcc-linaro-7.2.1-2017.11-x86_64_arm-linux-gnueabihf.tar.xz
$ tar -Jxvf gcc-linaro-7.2.1-2017.11-x86_64_arm-linux-gnueabihf.tar.xz -C $HOME

$ git clone git://arago-project.org/git/projects/oe-layersetup.git tisdk
$ cd tisdk
$ ./oe-layertool-setup.sh -f configs/processor-sdk/processor-sdk-<version>-config.txt
$ cd build
$ . conf/setenv
$ export TOOLCHAIN_PATH_ARMV7=$HOME/gcc-linaro-7.2.1-2017.11-x86_64_arm-linux-gnueabihf
$ MACHINE=am57xx-evm bitbake arago-base-tisdk-image

1.3.3. Processor SDK Build Reference¶

The following sections provide information for configuration, build options, and supported platforms of the Processor SDK.

$ git clone git://arago-project.org/git/projects/oe-layersetup.git tisdk
$ cd tisdk
$ ./oe-layertool-setup.sh -f configs/processor-sdk/processor-sdk-<version>-config.txt
$ mkdir downloads
$ cd downloads
$ # Assuming src file downloaded to $HOME/Downloads
$ tar xvf $HOME/Downloads/<target-board>-linux-sdk-arago-src-##.##.##.##.tar.xz
$ <target-board>-linux-sdk-arago-src-##.##.##.##/get_build_sources.sh <target-board>-linux-sdk-arago-src-##.##.##.##/source_pkg_list.txt
$ cd ..</span>
$ cd build
$ . conf/setenv
$ export TOOLCHAIN_PATH_ARMV7=$HOME/gcc-linaro-7.2.1-2017.11-x86_64_arm-linux-gnueabihf
$ MACHINE=<target-board> bitbake arago-core-tisdk-image

1.3.4. Common Variations (no SGX, X11, etc.)¶

Rebuilding without SGX

In Processor SDK delivered today the graphics hardware acceleration is enabled by default for device families with SGX (e.g. AM335x, AM437x, AM57xx). As a result, some of the applications with graphics dependencies will not run properly on device variants in those families that do not contain the SGX accelerator (e.g. AM3352, AM4372, etc.). The Processor SDK has been enhanced to provide the same OOB experience with software rendering provided by QT5/Weston. The non-SGX software rendering build will be enabled by adding the following to the bottom of conf/local.conf immediately before invoking bitbake.

MACHINE_FEATURES_remove="sgx"

PACKAGECONFIG_remove="wayland-egl"

Rebuilding without Wayland

If a full Window system is not needed, i.e. if you simply want apps to run full screen using EGLFS then you can remove Wayland by adding the following to the bottom of conf/local.conf immediately before invoking bitbake:

DISTRO_FEATURES_remove = "wayland"

X11 Build instructions

X11 has been validated as a build option, on top of Processor SDK 4.1 release. In order to build with X11 instead of Wayland, please use the configuration processor-sdk-04.01.00.06-x11-config.txt for oe-layer-setup. One of the key differences between this configuration file and the processor-sdk-04.01.00.06 config file is the branch from meta-processor-sdk. For X11 build, morty-x11-experimental branch is used, where the DISTRO_CONFIG is set to X11 instead of wayland.

X11 Filesystem

All the X11 related components are provided by the IMG DDK X11 package and located under /usr/local/XSGX directory instead of /usr/include and /usr/lib directories. The following applications and demos are built and verified with X11:

• SGX unitest programs: xgles1tests, xgles2test1, and etc.
• PVR SDK 3D demo programs: ChameleonMan, ExampleUI, and etc.
• QT5 Examples and demo programs over eglfs.x11 including matrix-gui-browser

In the X11 build, the xorg (Xserver) is running and owns the DSS resources by default. To support switching between X11 applications and non-X11 applications such as DRM modetest and gstreamer pipelines, the following shell file is provided to stop and start the Xserver.

/etc/init.d/xorg <start|stop>

1.3.5. See also¶

General information for building TI SDKs using the Arago Project can be found at Arago Project: Setting Up The Build Environment. This page contains information on the build host prerequisites, such as installing the toolchain, and required host packages and configuration, and the basic steps required to create an SDK completely from source. Once the Arago Project information is familiar, read the next section for a reference of layer configurations, build targets, and platforms supported by the Processor SDK.

• Yocto Project
• OpenEmbedded
• Arago Project