1. Overview¶

1.1. Processor SDK Android Software Developers Guide¶

Welcome to the Processor SDK Android Software Developer’s Guide

Thank you for choosing to evaluate one of our TI Processors ARM microprocessors. Please bookmark this page and refer back to it as needed. It is designed to quickly provide the information you need most while evaluating a TI microprocessor, specifically running one of the Software Architectures available, embedded Android. We are always striving to improve this product.  Please let us know if you have ideas or suggestions.

Version

This information covers Processor SDK Android 4.0.0 and above.

Feedback

If you have feedback, suggestions, or ideas on how to improve the SDK, it is very appreciated. Please post your ideas to the Sitara E2E Forum.

1.2. Processor SDK Android Getting Started Guide¶

Welcome to the Android Getting Started Guide

Thanks for your interest in learning more about the Android Software Development Kit (SDK). The SDK as we affectionately call it is our attempt to provide a great starting point to develop an embedded system on a TI Processor running Android. Given this goal, we wanted to provide something that is more than just a typical Board Support Package (BSP) containing a bootloader, Linux kernel, and Android filesystem. While these are certainly necessary elements, we feel they are just a starting point, especially for those that aren’t experts in developing with Android. So, the SDK also contains tools for developing on TI Processors (a validated cross-compiling toolchain, for example), pre-built libraries that you can use without having to rebuild them yourself, and some documentation to help explain how all of these pieces work together. We package all of this together with a working Android Embedded System that has been built with all of the things mentioned above.

What it really serves as is a “known good” starting point. One of the big challenges with starting development on a new platform (not to mention, a new Operating System (OS) for many), is getting an environment set up where you can build and debug code on hardware. The SDK attacks this problem with providing everything you need to do development, and it is validated on standard TI hardware platforms (EVMs). It wraps all of this up into one simple installer that helps get everything you need in the right place to do development. For example, you can start off with simply re-building the Android Embedded System that we provide to validate that everything is working on your system. This simple step gives you confidence that you can move forward from a good baseline.

As you go along your development journey and have questions, there is documentation and support available to you. Make sure to save a pointer to the Android SDK Software Developer’s Guide (SDG). If you don’t find what you need, take a look at the active Sitara Forum on the E2E Community and see if the topic has been covered before. If not, post a new thread and we’ll do our best to provide some guidance.

What would you like to do with the SDK?

As described above, the SDK has a lot to it. Let’s break it down to two pieces to simplify things a bit:

• The example embedded Android system. Essentially, a working bootloader (U-Boot), Linux kernel, and Android filesystem that can be put on an SD card and ran on a TI AM57xx EVM.
• Everything needed to create the above embedded system from “scratch”:
  • U-Boot sources and configuration files
  • Kernel sources and configuration files
  • An Android cross-compiling toolchain as well as other host binaries and components
  • The Android Open Source Project (AOSP) filesystem and sources for example applications (after syncing using the repo tool)
  • A variety of scripts and Makefiles to automate certain tasks
  • Other components needed to build an embedded Android system that don’t fit neatly into one of the above buckets

With these two pieces more clearly defined, we can now get back to that all important question, “What would you like to do with the SDK?”. If the answer is clearly “I want to build something and I’m ready to start developing now!”, then go ahead and skip down to the “I want to Develop!” (or, Developing with the SDK) section below for instructions on installing the SDK on a Linux Host System. This is a somewhat involved process focusing on the second of the two parts of the SDK listed above and may be more than some people want to start with. However, it provides access to the full spectrum of development from rebuilding the SDK from sources to fully adapting it with new device drivers and applications.

So, if you’re not quite there yet, let’s discuss some other options. Maybe you’d like to evaluate the SDK a bit to see if it is how you’d like to get started.

If this is not good enough and you really want to get your hands on something, check out the next section which shares how to play with the embedded Android system. All you’ll need is access to a Windows/Linux computer, an SD card, an SD card reader, some free, open-source software, and a supported Hardware platform.

Evaluating the SDK Embedded Android System

If you’re a hands on person, reading documentation and looking at presentations gets old fast. So, if you want to see an example of what you can build with the SDK and actually hold it in your hands and play with it (or show it to someone else that needs help understanding what you want to do with it), with minimal effort, you can simply run the SDK Embedded Android System on a supported Hardware platform. This will allow you to poke and prod and interact. It’s a powerful way to get the imagination active and engaged.

If you’ve recently purchased a TI AM572x GP EVM or an AM57xx IDK, move on to the next step to install the SDK and boot your board using the provided prebuilt images.

Start your Android Development

OK, you’re all in. Either you’ve known this is what you wanted to do, or you’ve gone through the above steps and you want to do more. It’s time to develop! Here’s a high level overview:

• Get a Linux host up and running if you don’t already have one
• Install the SDK and run some scripts to get everything set up
• Put the SDK Embedded Android System on an Evaluation Module to play with
• Build something to validate set up – the SDK for example
• Add something to the SDK, like a simple Hello World app

After completing these steps, you’ll have a known good baseline from which you can start development.

1. Configure a Linux Host - If you already have a Linux host machine, go to Step 2. To do Android development with the SDK, you’ll need a host PC running Linux. The Linux host is generally much faster and has a lot more memory (both RAM and hard disk space) than the typical embedded system. While it is certainly possible to do all development natively, we feel the advantages of using a host provide a better way to go and what is supported out of the box with the SDK. There are many, many ways to get access to a Linux host. We simply can’t validate all possibilities and iterations, therefore we focus on validating using Ubuntu as the host Linux distribution, running natively. We validate the Long-term Support (LTS) versions of Ubuntu at the time of a SDK release (Ubuntu 14.04 is the currently supported LTS version). Can you use other versions of Ubuntu or even other distributions? Theoretically, yes, as long as you can get it to work and there may be more “assembly” required. If you can use the Ubuntu version validated against the SDK, it will be the smoothest path and we will be able to help you more if you do run into trouble. Likewise, we would strongly recommend getting a native 64-bit Ubuntu LTS machine set up for development. For the cost of a little bit of hard drive space, Ubuntu can have direct access to the host’s hardware. Virtual Machines (VMs) have come a long way over the years, and many people use them daily without problems. However, when you are working with a target embedded system (that may be a prototype board), whether it be a TI board or eventually your own, removing the complexity of a VM from the get go can avoid a lot of frustration (i.e. wasted time). When using a VM while connecting and disconnecting hardware components, you have to be very diligent about making sure what is connected to what. You might prefer using an hour to get more work done than debugging a perceived problem caused by the fact the virtual host grabbed a USB port when you weren’t watching. When you’re ready to proceed, Ubuntu provides a great overview for how to install natively. If you eventually want to rebuild the Android filesystem from source, you’ll also need to follow the instructions from the official Android page here for setting up the packages required for building Android.

2. Install the SDK - Within your Linux host machine, Install the Android SDK Processor SDK Installer is 64-bit, and installs only on 64-bit host machine. Support for 32-bit host is dropped as of the Gingerbread Android release At least 70 GB of free space is required on the host machine in order to pull and then rebuild the full AOSP filesystem

3. Create an SD Card using the SDK Create SD Card Script You will need a >4GB SD Card and the capability to connect that card to your Linux Host machine (using a USB SD Card reader, for example). If using a virtual machine as your Linux host, you may need to import the SD Card reader into your virtual machine (disconnect it from the host and connect it to the VM so that the Linux VM can see it).

4. Configure your development environment There are many ways to connect the host development platform and the target board. These connections will vary depending on how you like to develop and what you are trying to do. Here is an example of a common set up with a serial connection for console, an Ethernet for networking, and a USB connection for flashing and ADB:

   

5. Run the Setup Script - Once the SDK has been installed and the SD card has been created and placed into the device, **run the setup.sh Script** on your host to guide you through the process of flashing the bootloader, kernel, and Android filesystem to the onboard eMMC.

1. Rebuild sources using the top-level makefile in the SDK root directory. For example:

• make all rebuilds all components in the SDK
• make linux configures and builds the kernel
• make u-boot-spl builds u-boot and u-boot-spl

The Android filesystem can be rebuilt, and then flashed to the onboard eMMC, by following these instructions.

What Would You Like to do Next?

Now that you have a solid baseline set up, you can choose what you’d like to do next based on what you need to do. Here are some of the many possibilities:

1.2.1. Install the Android SDK¶

Overview

The Processor SDK Installer (ti-processor-sdk-android-am57xx-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 universal bootloader (u-boot), the Linux kernel, toolchain and board support package, ease of use scripts and documentation. The Android file system sources can also be cloned to the SDK using the provided repo tool and manifest file. The Processor SDK was built and tested against a specific Linux Distribution name and version, Ubuntu 14.04. Note this does not prevent the user from installing the SDK on other Linux distributions.

How to Get the SDK Installer

Download from the Android SDK download page. This will always host the latest version of SDK.

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) and run the following commands:

chmod +x
./ti-processor-sdk-android-am57xx-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.

Note

If nothing seems to happen, you are probably running a 32-bit version of Linux. The installer is 64-bit, and will not execute properly.

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. Environment Support Message User is to acknowledge the host operating system recommendations.
2. GPLv3 Components Notice User is to acknowledge the use of GPLv3 components in the SDK.
3. Directory Install Location The user will be prompted for a location on where to put the Processor SDK. An example is given below.
4. Review and 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.
5. 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’.

sudo <ANDROID SDK INSTALL DIR>/bin/create-sdcard.sh

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] :

now installing:  ti-processor-sdk-android-am57xx-evm-04.00.00.01

0. BOOTFILEPATH = ....00.00.01//board-support/prebuilt-images
1. MLO          = GP_MLO
2. BOOTIMG      = u-boot-am57xx-evm.img
3. BOOTUENV     = uEnv.txt
4. KERNELIMAGE  = zImage-am57xx-evm.bin
5. DTBDIR       = ....00.00.01//board-support/prebuilt-images
    * am571x-idk-lcd-osd.dtb
    * am571x-idk-lcd-osd101t2587.dtb
    * am571x-idk.dtb
    * am572x-idk-lcd-osd.dtb
    * am572x-idk-lcd-osd101t2587.dtb
    * am572x-idk.dtb
    * am57xx-beagle-x15-revb1.dtb
    * am57xx-beagle-x15.dtb
    * am57xx-evm-reva3.dtb
    * am57xx-evm.dtb
6. RAMDISKIMG   = ...oard-support/prebuilt-images/ramdisk.img
7. SYSTEMIMG    = ...board-support/prebuilt-images/system.img
8. USERDATAIMG  = ...ard-support/prebuilt-images/userdata.img


Would you like to continue? [y/n] :

./setup.sh

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

Would you like to create a minicom script to configure the board (y/n)?
[ y ]

Would you like to run the setup script now (y/n)?
[ y ]

1.3. Processor SDK Android Directory Structure¶

The Processor SDK for Android contains the following top-level directories and files

These directories contain the code and tools used to develop for Processor SDK Android devices.

• android-devkit - Contains the cross-compile toolchain and libraries to speed development for the target device.
• bin - Contains the helper scripts for flashing the eMMC on the development device as well as the Android Debug Bridge (adb) tool.
• board-support - Contains the SDK components that need to be modified when porting to a custom platform. This includes the kernel, boot loader, Android Open Source Project filesystem, as well as any out of tree drivers.
• docs - Contains various SDK documentation such as the software manifest and additional user’s guide. This is also the location where you can find the training directory with the device training materials.
• filesystem -
• Makefile - Provides build targets for many of the SDK components from the top-level of the SDK.
• Rules.make - Sets default values used by the top-level Makefile as well as sub-component Makefiles.
• setup.sh - Runs the fastboot.sh script (found in bin/) to flash the eMMC of the connected device using the files in the board-support/prebuilt-images/ directory.

host# make

host# make clean

host# make install

host# make linux

host# make linux_install

1.4. Processor SDK Android Building The SDK¶

Using the Prebuilt Release Images

SD Card

The prebuilt release image can be found in the ‘board-support/prebuilt-images/’ directory of the Processor SDK Android installation. The create-sdcard.sh script (found in the ‘bin/’ directory of the SDK) will create a bootable SD card using the prebuilt images that you can use to boot your AM572x GP EVM, AM571x IDK, or AM572x IDK.

Flashing to onboard eMMC

You can also use the top-level setup.sh script to flash the prebuilt release images to the eMMC of your EVM or IDK.

Rebuilding Android from Sources

Build PC setup

You need a 64 bit Ubuntu 14.04 machine for building the Android file system.

Install Pre-requisite packages for building the Android File System Follow instructions from official Android page here for setting up the packages required for building Android.

Use the following command to install the same packages that were used during the SDK development process:

sudo apt-get install git-core gnupg flex bison gperf build-essential zip curl zlib1g-dev gcc-multilib g++-multilib libc6-dev-i386 lib32ncurses5-dev x11proto-core-dev libx11-dev lib32z-dev ccache libgl1-mesa-dev libxml2-utils xsltproc unzip openjdk-7-jdk lzop bc u-boot-tools

Proxy/Firewall If you are behind proxy/firewall, workaround it using the instructions in [1]. For installing repo make sure you also export https_proxy environment variable.

repo tool Google’s repo tool is used to clone all of the git repositories that you need to rebuild the full Android filesystem from source. A copy of the repo tool is provided in the Processor SDK Android in the board-support/aosp-6AM.1.3/.repo/repo/ directory. Instructions to use the repo tool are provided below in this guide.

Tool Chain for building Kernel and Drivers The Kernel and Driver sources are built using the Android linux-x86 toolchain for ARM GNU/Linux version . This tool chain is provided in the android-devkit directory of the SDK.

A note on Host binaries of Marshmallow Host binaries like simg2img, make_exr4fs etc.. that are built in Android M needs shared libraries now. You might see errors like below when trying to use those binaries

simg2img: error while loading shared libraries: libc++.so: cannot open shared object file: No such file or directory

To resolve it, export your LD_LIBRARY_PATH to include the libraries. Point it to either the daily build or the folder from your build system

export LD_LIBRARY_PATH=~/ti-processor-sdk-android-am57xx-evm-04.00.00.xx/board-support/aosp-6AM1.3/out/host/linux-x86/lib64/

U-Boot, Linux Kernel, and Android Filesystem Sources

Android Filesystem Sources

You can get the Android filesystem sources for this release by using the repo tool along with the provided manifest file.

cd ~/ti-processor-sdk-android-am57xx-evm-04.00.00.xx/board-support/aosp-6AM.1.3/
./repo sync

This command may take several hours as it is cloning hundreds of repositories and checking them out to a specific commit. This will also take up considerable space on your development machine’s hard drive (~70GB).

Note: The repo tool has already been initialized with the manifest file found in board-support/aosp-6AM.1.3/.repo/manifests/aosp-6AM.1.3_manifest.xml. That is why only the ‘repo sync’ command is required above.

TI Hardware Accelerated Graphics and MultiMedia Binaries

Multimedia (DCE) and accelerated graphics binaries are part of Android file system build

U-Boot Sources

The U-Boot sources are included in the Processor Android SDK in the board-support/u-boot-20xx-yy.zz/ directory.

Kernel & Driver Sources

The Linux kernel sources are included in the Processor Android SDK in the board-support/linux-x.y.zz/ directory.

Build Instructions

Setting up build environment

export CROSS_COMPILE=${HOME}/ti-processor-sdk-android-am57xx-evm-04.00.00.xx/android-devkit/arm-linux-androideabi-4.9.x-google/bin/arm-linux-androideabi-

Building U-boot sources

The top-level Makefile can be used to build MLO and U-Boot

cd ~/ti-processor-sdk-android-am57xx-evm-04.00.00.xx/
make u-boot

Building Kernel

The top-level Makefile can also be used to build the Linux kernel

cd ~/ti-processor-sdk-android-am57xx-evm-04.00.00.xx/
make linux
make linux-dtbs

Building Android Filesystem (AFS)

Instructions for building Android file system (Processor SDK 4.0, 4.1).

cd ~/ti-processor-sdk-android-am57xx-evm-04.00.00.xx/board-support/aosp-.../
. build/envsetup.sh
lunch full_am57xevm-userdebug
make -j8 clean
make -j8

See Android Build Tricks for tricks on building Android. Adjust -jX to match your build machine, where X is the number of jobs.

Instructions for building Android file system (Processor SDK 4.2 +)

cd ~/ti-processor-sdk-android-am57xx-evm-04.00.00.xx/board-support/aosp-.../
export KERNELDIR=~/ti-processor-sdk-android-am57xx-evm-04.00.00.xx/board-support/linux-.../
. build/envsetup.sh
lunch full_am57xevm-userdebug
make -j8 clean
make -j8

Building SGX Kernel Module

Instructions for rebuilding the SGX kernel module.

cd ~/ti-processor-sdk-android-am57xx-evm-04.00.00.xx/board-support/aosp-6AM.1.3/device/ti/proprietary-open/jacinto6/sgx_src/eurasia_km/eurasiacon/build/linux2/omap_android
export KERNELDIR=${HOME}/ti-processor-sdk-android-am57xx-evm-04.00.00.xx/board-support/linux-4.4.x...
export CROSS_COMPILE=${HOME}/ti-processor-sdk-android-am57xx-evm-04.00.00.xx/android-devkit/arm-linux-androideabi-4.9.x-google/bin/arm-linux-androideabi-
export KERNEL_CROSS_COMPILE=${HOME}/ti-processor-sdk-android-am57xx-evm-04.00.00.xx/android-devkit/arm-linux-androideabi-4.9.x-google/bin/arm-linux-androideabi-
export ARCH=arm
make TARGET_PRODUCT="am57xevm" BUILD=release

SGX module will be generated at:

~/ti-processor-sdk-android-am57xx-evm-04.00.00.xx/board-support/aosp-6AM.1.3/device/ti/proprietary-open/jacinto6/sgx_src/eurasia_km/eurasiacon/binary2_omap_android_release/target/pvrsrvkm.ko

Use ADB to push pvrsrvkm.ko file to the /system/lib/modules/ location on the AM57xx target and reboot the board.

Preparing Android Image

Rebuild Android Filesystem (AFS) to include kernel

Copy Kernel Image (This step is for making your kernel to be part of boot.img)

cd ~/ti-processor-sdk-android-am57xx-evm-04.00.00.xx/board-support/aosp-6AM.1.3
cp -v ../linux-4.4.x.../arch/arm/boot/zImage device/ti/am57xevm/kernel

Rebuild AFS to generate update images

cd ~/ti-processor-sdk-android-am57xx-evm-04.00.00.xx/board-support/aosp-6AM.1.3/
. build/envsetup.sh
lunch full_am57xevm-userdebug
rm out/target/product/am57xevm/*.img
rm out/target/product/am57xevm/obj/PACKAGING/systemimage_intermediates/system.img
make -j2

Preparing eMMC binaries/images

cd ~/ti-processor-sdk-android-am57xx-evm-04.00.00.xx/board-support/
mkdir emmc_files
cp -v ./aosp-6AM.1.3/out/target/product/am57xevm/*img emmc_files
cp -v ./aosp-6AM.1.3/device/ti/am57xevm/fastboot.sh emmc_files
cp -v ./aosp-6AM.1.3/out/host/linux-x86/bin/{simg2img,make_ext4fs,mkbootimg,fastboot,adb} emmc_files
cp -v ./aosp-6AM.1.3/out/host/linux-x86/lib64/{libc++.so,libcutils.so,liblog.so,libselinux.so} emmc_files
cp -v ./linux-4.4.x.../arch/arm/boot/zImage emmc_files/kernel
cp -v ./linux-4.4.x.../arch/arm/boot/dts/am57*.dtb emmc_files
cp -v ./u-boot.20xx.yy.../MLO emmc_files/GP_MLO
cp -v ./u-boot.20xx.yy.../MLO emmc_files/
cp -v ./u-boot.20xx.yy.../u-boot.img emmc_files

Flashing eMMC images

The default setup is to flash MLO and u-boot.img ,kernel, dtb file and AFS to emmc.

• Instructions are same for AM57x GP EVM and the AM57x IDK boards

Flashing procedure

• Create an SD card containing MLO and u-boot.img using the create-sdcard.sh script provided in the SDK and then boot the target board from this external SD card.
• Connect a USB cable from the Linux PC to the micro USB port on the EVM
  • There is only one micro USB port on the AM57x GP EVM
  • On the AM57xx IDK boards you need to connect the micro USB cable to the micro USB port on the opposite side of the (4) RJ-45 connectors (The other micro USB port on the IDK boards is used for serial communication and JTAG).
• Power on the board and stop the board at u-boot prompt by interrupting with key press

Hit any key to stop autoboot:  3

• Set the right environment variables for Android SDK and save (This step is needed only for fresh flash, for incremental flashing this is optional)

=> env default -f -a
=> setenv partitions $partitions_android
=> env save

• Reboot the board and stop it at the u-boot prompt again and put the board into fastboot mode

=> fastboot 1

on the host machine

=> cd ~/ti-processor-sdk-android-am57xx-evm-04.00.00.xx/board-support/emmc_files
=> sudo ./fastboot oem format
=> sudo ./fastboot reboot (reboot and stop the device again in u-boot)

• Put the board in fastboot mode by typing in below command

=> fastboot 1

• On the Linux PC which has the emmc images run the fastboot.sh script to flash the binaries

cd ~/ti-processor-sdk-android-am57xx-evm-04.00.00.xx/board-support/emmc_files
sudo ./fastboot.sh

• NOTE: After the flashing is done, remove the external SD card and reboot the board.

1.5. Software Stack¶

1.6. Processor SDK Technical Support¶

Technical support is a broad term. Our desire is to provide a solid product, good documentation, and useful training that defines a clear path for developing a product based on the Linux/RTOS/Android SDKs. However, we know we’ll never cover everything that can be done, and occasionally we even make mistakes <gasp>. So, when you can’t seem to find what you need, there’s a good place to search through previously answered questions and ask a new one - The E2E Support Forums.

There is an active community of TIers and other customers like you already using a TI Processor, on these forums. You may find your question has already been answered with a quick Search of the Forums. If not, a quick post will likely provide you the answers you need.

• E2E Support Forums for AM335x, AM437x, and AM57xx
• E2E Support Forums for K2H, K2K, K2E, K2L, K2G, C665x, and C667x
• E2E Support Forums for OMAP-L13x and C674x

1.7. Processor SDK Android GPLv3 Disclaimer¶

There are GPLv3 licensed software components contained within the Processor SDK for Android on both the target and the host. The software manifest (Processor-SDK_Android_AM57X_Manifest.html) for the Android SDK is located in the docs/ directory of the installed SDK. The NOTICE.html file for the Android Open Source Project is also located in the docs/ directory. All GPLv3 components for both target and host are contained in the SDK directory.