Skip to end of metadata
Go to start of metadata



This Quickstart provides you with the tools and know-how to install and work with the Android Board Support Package (BSP) for the phyCORE-AM57x Rapid Development Kit. This Quickstart shows you how to do everything from installing the appropriate tools and source, to building custom kernels, to deploying the OS, to exercising the software and hardware. Please refer to the phyCORE-AM57x Hardware Manual for specific information on board-level features such as jumper configuration, memory mapping and pin layout for the phyCORE-AM57x System on Module (SOM) and baseboard. Additionally, gain access to the SOM and baseboard schematics for the phyCORE-AM57x Rapid Development Kit by submitting a Request for Schematic Files from the PHYTEC Service Desk. Sign up or login here: https://support.phytec.com

Requirements


The following system requirements are necessary to successfully complete this Quickstart. Deviations from these requirements may suffice, or may have other workarounds.

Hardware

  • phyCORE-AM57x System on Module (PCM-057)
  • phyCORE-AM57x Baseboard (PCM-948)
  • Serial cable (RS-232)
  • Ethernet cable
  • USB A to mini-B cable
  • AC adapter supplying 12VDC / min. 2A

  • SD card reader operational under Linux

  • 8GB or 16GB SD Card

Software

  • A modern GNU/Linux Operating host system either natively or via a virtual machine:
    • Ubuntu 14.04 LTS recommended, 64-bit required. Other distributions will likely work, please note that some setup information as well as OS-specific commands and paths may differ
    • If using a virtual machine, VMWare Workstation, VMWare Player, and VirtualBox are all viable solutions
  • Root access to your Linux Host PC. Some commands in the Quickstart will not work if you don’t have sudo access (ex. package installation, formatting SD card)
  • At least 120GB free on target build partition.
  • Active Internet connection

Development Host Setup


Host Debian Packages

Android development requires certain packages to be installed. The commands below are separated into two categories: for flashing, and for building.

Packages for Flashing

These packages are the bare minimum required to flash pre-built images to the target. Specifically phablet-tools contains fastboot and adb, and android-tools-fsutils contains make_ext4fs.

Host
sudo apt-get install phablet-tools android-tools-fsutils git

If your goal is to flash images and not build your own, you can continue to the Getting Started with Pre-built Images section

Packages for Building

These packages are required for building from our sources.

Host
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 lzop device-tree-compiler


Additionally, Android Nougat requires Java 1.8.x to be installed and configured.

We have provided Google's instructions for Ubuntu 14.04 below, based on their complete instructions for Ubuntu 14.04 and other Ubuntu versions that are available here: https://source.android.com/source/initializing#installing-the-jdk.


This can be done with the following steps:

  1. Download the .deb packages for 64-bit architecture from archive.ubuntu.com:
    1. openjdk-8-jre-headless_8u45-b14-1_amd64.deb with
      SHA256 0f5aba8db39088283b51e00054813063173a4d8809f70033976f83e214ab56c0
    2. openjdk-8-jre_8u45-b14-1_amd64.deb with
      SHA256 9ef76c4562d39432b69baf6c18f199707c5c56a5b4566847df908b7d74e15849
    3. openjdk-8-jdk_8u45-b14-1_amd64.deb with
      SHA256 6e47215cf6205aa829e6a0a64985075bd29d1f428a4006a80c9db371c2fc3c4c
  2. Optionally, confirm the checksums of the downloaded files against the SHA256 strings using the sha256sum tool:

    Host
    sha256sum {downloaded .deb file}
  3. Install the packages:

    Host
    sudo apt-get update

    Run dpkg for the downloaded .deb files. It may produce errors due to missing dependencies:

    Host
    sudo dpkg -i openjdk-8-*

    To fix missing dependencies:

    Host
    sudo apt-get -f install
  4. (Optional) If there was another java version previously installed, update the default versions:

    Host
    sudo update-alternatives --config java
    sudo update-alternatives --config javac

Directory Setup

Create a directory that will be used as the root for all of the sources and additional components needed for building:

Host
sudo mkdir -p /opt/PHYTEC_BSPs
sudo chown -R <user>: /opt/PHYTEC_BSPs    # <user> should be replaced by your host's username

mkdir -p /opt/PHYTEC_BSPs/am57xx
cd /opt/PHYTEC_BSPs/am57xx
export AM57XX_DIR=`pwd`
mkdir -p afs
cd afs
export ANDROID_ROOT=`pwd`

$AM57XX_DIR and $ANDROID_ROOT are referenced throughout this document. If you use a different directory instead of what is here, be sure to configure those variables accordingly.

Toolchain for Building the Kernel and Bootloaders

The Android Filesystem (AFS) contains a pre-built toolchain, but it is not 100% compatible with our external sources (the Linux kernel and U-boot) so we recommend downloading and utilizing a separate Linaro toolchain for this purpose:

Host
wget https://releases.linaro.org/components/toolchain/binaries/5.3-2016.02/arm-linux-gnueabihf/gcc-linaro-5.3-2016.02-x86_64_arm-linux-gnueabihf.tar.xz
tar -Jxvf gcc-linaro-5.3-2016.02-x86_64_arm-linux-gnueabihf.tar.xz -C /opt/PHYTEC_BSPs
rm gcc-linaro-5.3-2016.02-x86_64_arm-linux-gnueabihf.tar.xz


After extracting the toolchain, it needs to be added to the host's PATH to properly use it for building:

Host
export PATH=/opt/PHYTEC_BSPS/gcc-linaro-5.3-2016.02-x86_64_arm-linux-gnueabihf/bin:$PATH

To make this change last beyond your current terminal session, use a text editor to modify your ~/.bashrc file and add it to the end.

Git Setup

If you have not yet configured your Git environment on your host machine, please execute the following commands to set your user name and email address. See here for more information on getting started with Git.

Host
git config --global user.email "your@email.com" 
git config --global user.name "Your Name"
git config --global http.sslcainfo /etc/ssl/certs/ca-certificates.crt

Server Setup (Optional)

 Click here to see server setup for TFTP, NFS, and Samba (optional)

The following steps describe the setup for TFTP, NFS, and Samba servers. Server setup is not required for working with the board, however they will significantly reduce time and are highly recommended during the building and development phase.

TFTP

TFTP is a "trivial" file transfer protocol used to transfer individual files across a network. Setting up a TFTP server on your Linux Host PC will allow you to exchange files with the target board. Some examples where this will be advantageous include:

  • Modifying and doing development on the Linux kernel. Barebox can be configured to remotely boot the kernel so you have access to the latest build without needing to continually reflash the target board.
  • Updating images from the bootloader. Transferring files over a network in Barebox is an alternative to using an SD card which eliminates some time consuming steps such as formatting an SD card.
  • Individual file transfer to the root fileystem. When Linux has been fully booted you may want to copy a specific file from your Host PC to the target board (images, application executables).

Install the TFTP server on your Host PC:

sudo apt-get install tftpd-hpa

Specify a folder where the files will reside on your Host PC by replacing the folder path for ''TFTP_DIRECTORY'' with whatever folder you wish to use as your TFTP file storage location, or leave the folder as the default.

sudo gedit /etc/default/tftpd-hpa
# /etc/default/tftpd-hpa
TFTP_USERNAME="tftp"
TFTP_DIRECTORY="/var/lib/tftpboot"
TFTP_ADDRESS="0.0.0.0:69"
TFTP_OPTIONS="--secure"

If you made any changes to the settings of the TFTP server, you need to restart it for them to take effect.

sudo restart tftpd-hpa

If you would like to grant every user on the system permission to place files in the TFTP directory, use the following command, replacing ''<TFTP_DIRECTORY>'' with your chosen location.

sudo chmod ugo+rwx <TFTP_DIRECTORY>

Files in the ''<TFTP_DIRECTORY>'' on your Host PC can now be accessed from another machine on the same network such as the target board by simply using the IP address of the Host PC. Take note of this IP address, in a typical wired connection this will be ''inet addr'' listed under ''eth0''.

ifconfig

NFS

A network filesystem (NFS) server gives other systems the ability to mount a filesystem stored on the Host PC and exported over the network. Setting up an NFS server on your Linux Host PC gives you access to the target boards root filesystem which will allow you to quickly test applications and evaluate different filesystem setups for the target board. That is, the root filesystem for the board will actually be located on the remote host Linux machine. This enables easy access and modifications to the root filesystem during development.

Install the NFS server on your Host PC:

sudo apt-get install nfs-kernel-server

Exported filesystems are designated in the "/etc/exports" file and allow you to choose both the directory to be exported and many settings for accessing the exports. Below is an example for exporting a folder called "nfs_export-ex" located in a user's home directory.

sudo gedit /etc/exports
# /etc/exports
/home/<user>/nfs_export-ex *(rw,sync,no_root_squash,no_subtree_check)

The options (rw, sync, no_root_squash, no_subtree_check) for this folder are essential in setting up the NFS export correctly. For more information on additional options, refer to the man page for 'exports'.

  • rw enables: read and write access when the directory is mounted
  • sync: tells the file-system to handle local access calls before remote access
  • no_root_squash: allows root access when mounting the file-system
  • no_subtree_check: reduces the number of checks the server must make to ensure that an exported sub-directory is within an exported tree and also enables access to root files in conjunction with no_root_squash

After modifying this file, in order to mount the directories as an NFS, you must force the NFS server to export all of the directories listed in "/etc/exports".

sudo /usr/sbin/exportfs -va

Samba

Samba servers are an excellent way to access a Linux file-system on a Windows machine via a network connection. Using a Samba server, it is quick and easy to transfer files between systems.

To install a Samba server, use the following command:

sudo apt-get install samba

Before the Samba share can be mounted on another machine it's necessary to modify the configuration file to allow write access and access to home directories. Start by editing the "/etc/samba/smb.conf" file.

sudo gedit /etc/samba/smb.conf

Inside this file there are four specific things that need to be uncommented (remove the ';' at the beginning of the line) to enable the sharing of home folders and write access. Below is the section that must be modified:

#======================= Share Definitions =======================
# Un-comment the following (and tweak the other settings below to suit)
# to enable the default home directory shares. This will share each
# user's home directory as \\server\username
;[homes]
; comment = Home Directories
; browseable = yes
# By default, the home directories are exported read-only. Change the
# next parameter to 'no' if you want to be able to write to them.
; read only = no

The outcomes after the changes are made follow:

#======================= Share Definitions =======================
# Un-comment the following (and tweak the other settings below to suit)
# to enable the default home directory shares. This will share each
# user's home directory as \\server\username
[homes]
comment = Home Directories
browseable = yes
# By default, the home directories are exported read-only. Change the
# next parameter to 'no' if you want to be able to write to them.
read only = no

It might also be necessary to change the ''workgroup'' line to match the workgroup for your machine.

To apply the changes, the next step is to restart all Samba-related processes.

sudo restart smbd
sudo restart nmbd

Lastly, each user needs to have a password enabled to be able to use the Samba server. There are no rules for this password. The simplest method for choosing this password is to make it the same as the UNIX user's password, but it is not a requirement. After typing in the command below, you will be prompted to enter the password for the specified user.

sudo smbpasswd -a <user>

As mentioned in the configuration file, the samba share can be connected by accessing "\\<host machine ip>\\<user>" by either mounting a network share or using Windows explorer to navigate to it.


Getting Started with Pre-Built Images


This section is intended to walk you through the steps required to retrieve, flash, and boot the released pre-built images.

If you made it this far without first visiting the Requirements, Development Host Setup, and Directory Setup sections please follow those links and return when your configuration meets the requirements and your environment is ready.

Retrieve the Pre-Built Images

Download the release images and script used for flashing

Host
wget http://artifactory.phytec.com/artifactory/am57xx-images-released-public/BSP-Android-TI-AM57x-PD17.1.0.tar.bz2
mkdir -p $AM57XX_DIR/emmc_files
tar -jxf BSP-Android-TI-AM57x-PD17.1.0.tar.bz2 -C $AM57XX_DIR/emmc_files
cp /usr/bin/fastboot /usr/bin/make_ext4fs $AM57XX_DIR/emmc_files/.

Optional command to free up disk space:

Host
rm -f BSP-Android-TI-AM57x-PD17.1.0.tar.bz2

Create a Bootable SD Card

Flashing the BSP-Android-TI-AM57x-PD17.1.0 images requires initially booting the system using bootloaders loaded on an SD card.

Specifically, you will need an SD card with the first partition configured for roughly 64MiB. We recommend that you use the attached script here for simplicity: create-sdcard.sh

When using this script, it will ask if you want to create 2 or 3 partitions. Press 2.

Further, when it asks if you would like to continue press N.

After the card has been partitioned, remove and reinsert it in your card reader to automount the partitions in Ubuntu. Once the partitions appear in /media/<user>/, copy the MLO and u-boot.img bootloaders to the boot partition.

Host
cp $AM57XX_DIR/emmc_files/MLO $AM57XX_DIR/emmc_files/u-boot.img /media/<user>/boot/.    # as before, replace <user> with your host's username
sync; umount /media/<user>/*

Prepare the Target For Flashing

Now that an SD card is loaded with bootloaders, the target is almost ready for booting.

The following image will help for the next steps below:

  1. Insert the SD card into X2.
  2. Verify all of the S5 switches are set to OFF as shown above.
  3. Connect a USB A to Mini-B cable to both the host and X9
  4. Connect the kit-supplied serial cable between a host RS-232 serial port and X18
  5. (Recommended) connect a display output to the carrier board (Parallel Display @ X25 or HDMI @ X24)
    1. X25: connect a LCD-018-070-KAP display for both video output and capacitive touch
    2. X24: connect a HDMI to Micro-HDMI cable between a consumer monitor and the target for video output

      Although some HDMI monitors have touch capabilities, this is currently untested and therefore unsupported

  6. Start terminal software (i.e. Minicom, TeraTerm, or PuTTY) on your host and configure it for 115200 baud, 8 data bits, no parity, and 1 stop bit (8n1) with no handshaking or flow control.
  7. Insert the kit-supplied 12V power adapter into X4. There will be two green LEDs visible on the carrier board.
  8. Press S2 to power on the board, resulting in additional green LEDs lighting up and console output on the terminal.
  9. Press any key in the serial console to stop u-boot from proceeding further.
  10. Type the following commands into the serial console to set up the u-boot environment:

    Target
    env default -f -a
    set partitions $partitions_android
    saveenv
    env save
    reset
  11. Press any key in the serial console to stop in u-boot again and type this command to prepare the target for flashing:

    Target
    fastboot 1

Flash the Target with Pre-Built Images

Now that the target is ready to receive images, we need to tell the host what to send over USB. To this end, we use the commands fastboot and the fastboot.sh script that has been created to facilitate the process.

If you are using a VM for your host PC, after performing the previous 'fastboot 1' command on the target, you will need to attach the 'Texas Instruments USB download gadget' device to it before the following commands will work.

Perform these commands from the host:

Host
cd $AM57XX_DIR/emmc_files
sudo ./fastboot.sh

This will start a flurry of output on both the host PC's terminal and the serial console. Once the transfer and flashing is complete, this is an example of what you will see on the host:

Following that, we use fastboot to reboot the board completely into Android with the following command:

Host
sudo ./fastboot reboot

Booting into Android will begin with an animated "android" logo visible on an attached display. Additionally, there will be console access to the filesystem shortly after the animated logo appears.

Booting is complete when a minimal Android home screen is visible.

To properly power the target down after you are finished with it, use the following command on the console:

Target
reboot -p

Building the BSP from Source


This section will explain how to build the individual pieces of the BSP from source to create your own customized images.

If you made it this far without first visiting and following the information provided in the Requirements and Development Host Setup sections, please follow those links and return when your configuration meets the requirements and your environment is ready.

Building the Bootloaders (U-Boot)

The first step to building the bootloaders is to fetch the source from the PHYTEC git repository:

Host
cd $AM57XX_DIR
git clone https://stash.phytec.com/scm/asdk/uboot-phytec.git -b BSP-Android-TI-AM57x-PD17.1.1
cd uboot-phytec

After downloading the source you will have the BSP-Android-TI-AM57x-PD17.1.1 tag checked out and it is recommended that you create a branch from this location to manage any changes that you make to the source. The following command can be used to create a branch and switch to it:

Host
git checkout -b "WIP/mychanges"    # this is a basic example of a branch name

Following that, the images can be built using the following make command:

Host
make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- O=am57xx_phycore_rdk am57xx_phycore_rdk_defconfig all

The Toolchain needs to be configured and added to your PATH for this command to work properly. Please revisit that section if you have a build error.


The above make command creates the build in an output directory am57xx_phycore_rdk instead of in the local directory, keeping the local directory clean and all build settings contained. After it finishes, the MLO and u-boot.img binary images are located in the am57xx_phycore_rdk directory.

To flash these images using the fastboot.sh script utilized to Flash the Target with Pre-Built Images, copy them to the aforementioned emmc_files directory:

Host
cp am57xx_phycore_rdk/MLO am57xx_phycore_rdk/u-boot.img $AM57XX_DIR/emmc_files/.

Building the Kernel

Like the instructions for the bootloaders, you first need to fetch the kernel source from the PHYTEC git repository:

If you have already downloaded the AFS and completed the setup steps, you can skip the fetching steps mentioned below and use the kernel source located at $ANDROID_ROOT/device/phytec/am57xx_rdk-kernel. Keep in mind that any changes to the source here may be disregarded with future repo sync operations.

Host
cd $AM57XX_DIR
git clone https://stash.phytec.com/scm/asdk/linux-phytec-ti.git -b BSP-Android-TI-AM57x-PD17.1.1
cd linux-phytec-ti

After downloading the source you will have the BSP-Android-TI-AM57x-PD17.1.1 tag checked out and it is recommended that you create a branch from this location to manage any changes that you make to the source. The following command can be used to create a branch and switch to it:

Host
git checkout -b "WIP/mychanges"    # this is a basic example of a branch name

Following that, the images can be built using the following make commands:

Host
export KERNELDIR=`pwd`

make ARCH=arm am57xx_phycore_rdk_defconfig
make -j<N> ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf-    # replace <N> with the number of CPU threads you want to use. Suggested value for <N> is (number of CPU threads) - 1

The Toolchain needs to be configured and added to your PATH for this command to work properly. Please revisit that section if you have a build error.

When the build is complete, you will find the kernel at arch/arm/boot/zImage and the devicetree binary at arch/arm/boot/dts/am57xx-phycore-rdk.dtb.

In Android, the kernel becomes part of the boot.img file/partition and cannot be flashed by itself, but to flash the devicetree binary using the fastboot.sh script utilized to Flash the Target with Pre-Built Images, copy it to the aforementioned emmc_files directory:

Host
cp arch/arm/boot/dts/am57xx-phycore-rdk.dtb $AM57XX_DIR/emmc_files/.

After completing the AFS steps involving repo init and repo sync, the kernel binary can be copied to $ANDROID_ROOT/device/phytec/am57xx_rdk/kernel to be included as part of boot.img in the next AFS build.

Host
cp arch/arm/boot/zImage $ANDROID_ROOT/device/phytec/am57xx_rdk/kernel

If boot.img already exists in $ANDROID_ROOT/out/target/product/am57xx_rdk/ then you will also need to remove it before initiating another AFS build or it will not be regenerated.

Host
rm -f $ANDROID_ROOT/out/target/product/am57xx_rdk/boot.img

Building the Android Filesystem (AFS)

The Android filesystem contains many different git repositories and packages so we use the repo tool to fetch and prepare everything we need for building based on our customized manifest file.

Host
cd $ANDROID_ROOT
repo init -u https://stash.phytec.com/scm/asdk/platform-manifests.git -b nougat-mr1-release -m default.xml
repo sync -j<N>    # replace <N> with the number of threads you wish to use. For repo, this also means more parallel downloads and increased bandwidth usage in addition to CPU thread usage.

If you notice general sluggishness of your network or repo appears to hang at any point, Ctrl + C to quit out of the repo command and reduce the number of threads in your repo sync command before continuing.

After successfully fetching all of the sources, we need to apply a couple patches to modify TI's sources to build properly with our board.

Host
cp device/phytec/am57xx_rdk/ti-proprietary-open-patches/patch-ti-proprietary-open.sh $ANDROID_ROOT/.
./patch-ti-proprietary-open.sh device/phytec/am57xx_rdk/ti-proprietary-open-patches

If you built your own kernel, now is the best time to place it in $ANDROID_ROOT/device/phytec/am57xx_rdk to create a boot.img that matches your changes.

Set up the AFS build environment and set it to build for the phyCORE-AM57xx RDK

Host
source build/envsetup.sh
lunch full_am57xx_rdk-userdebug

Lastly, initiate the build.

Host
make -j<N>    # replace <N> with the number of CPU threads you want to use. Suggested value for <N> is (number of CPU threads) - 1.

Build time will vary based on host specifications and dedicated threads, but expect a clean build to take a minimum of one hour.

After the build is complete, the output images are in out/target/product/am57xx_rdk.

To flash these images using the fastboot.sh script utilized to Flash the Target with Pre-Built Images, copy them to the aforementioned emmc_files directory:

Host
cp $ANDROID_ROOT/out/target/product/am57xx/*.img $AM57XX_DIR/emmc_files/.

Rebuilding the PowerVR SGX Kernel Module

If the kernel .config has been modified, potentially resulting in different headers, the SGX kernel module pvrsrvkm.ko will need to be rebuilt and a new system.img generated that contains it. The following commands will need to be executed:

Host
# configure additional environment variables
export CROSS_COMPILE=$ANDROID_ROOT/prebuilts/gcc/linux-x86/arm/arm-eabi-4.8/bin/arm-eabi-
export KERNEL_CROSS_COMPILE=arm-linux-gnueabihf-
export OUT_DIR=$ANDROID_ROOT/out


cd device/ti/proprietary-open/jacinto6/sgx_src/eurasia_km/eurasiacon/build/linux2/omap_android
make ARCH=arm TARGET_PRODUCT="am57xx_rdk" BUILD=release

$ANDROID_ROOT and $KERNELDIR are set at different stages in this document and need to be configured for the above make command to work successfully. Please refer to Directory Setup and Building the Kernel sections to set these appropriately.

After the make command succeeds, you can find the new SGX module here: $ANDROID_ROOT/device/ti/proprietary-open/jacinto6/sgx_src/eurasia_km/eurasiacon/binary2_omap_android_release/target/pvrsrvkm.ko. To make it part of your next AFS build, it needs to be copied to the system directory and some files deleted to force system.img to be rebuilt:

Host
cp $ANDROID_ROOT/device/ti/proprietary-open/jacinto6/sgx_src/eurasia_km/eurasiacon/binary2_omap_android_release/target/pvrsrvkm.ko $ANDROID_ROOT/out/target/product/am57xx_rdk/system/lib/modules/pvrsrvkm.ko


rm -f $ANDROID_ROOT/out/target/product/am57xx_rdk/system.img
rm -f $ANDROID_ROOT/out/target/product/am57xx_rdk/obj/PACKAGING/systemimage_intermediates/system.img

Now the next make command run from $ANDROID_ROOT should generate a new system.img with the updated SGX module.

Host
cd $ANDROID_ROOT
make -j<N>    # replace <N> with the number of CPU threads you want to use. Suggested value for <N> is (number of CPU threads) - 1.