Non-Kit SOM

If working with a non-kit SOM, there are additional steps required to build this release for your configuration. Please view the notes in the Building the BSP from Source and Built Images sections for the applicable differences. For each SOM configuration there may be a required change to the Linux dts, the yocto MACHINE value, and the output images.



This BSP Development Guide provides you with the tools and know-how to install and work with the Linux Board Support Package (BSP) for the phyCORE-AM57x Development Kit. The guide will walk-through how to install the appropriate tools and source, build custom kernels, deploy the OS, and how to exercise the software and hardware. Please refer to the phyCORE-AM57xx Hardware Manual for specific information on board-level features such as jumper configuration, memory mapping and pin layout for the phyCORE-AM57xx System on Module (SOM) and Carrier Board. Additionally, gain access to the SOM and baseboard schematics for the phyCORE-AM57xx kit by registering at the following: http://phytec.com/support/registration/.


Requirements


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

Software

  • A modern GNU/Linux Operating host system either natively or via a virtual machine:

    • Ubuntu 18.04 LTS, 64-bit, required. Other distributions may work but are unsupported.

    • 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 500GB free on target build partition and at least 8GB of RAM available to the build host.

  • SD card reader operational under Linux.

    • If you do not have SD card access under Linux then formatting, copying the bootloader, and mounting the root file system on an SD card will not be possible.

  • Active Internet connection

Hardware

  • phyCORE-AM57x System on Module (PCM-057)
  • phyCORE-AM57x Baseboard (PCM-948)
  • Serial cable (RS-232)
  • Ethernet cable
  • SD Card (16GB or more recommended for flashing and development)
  • AC adapter supplying 12VDC / min. 2A

See the Release Notes for supported SOM and carrier board versions.

Getting Started With Binary Images


In order to get your phyCORE-AM57x development kit booted for the first time, please checkout the QuickStart

For additional resources pertaining to working with PHYTEC's Pre-Built Images, checkout the following guides:

  • Create a Bootable SD Card - Your kit should have came with a pre-flashed SD Card from the factory but if it didn't or yours is no longer viable this is the guide for you.
  • Flashing Images to eMMC - This will allow you to free up the SD Card slot for other purposes.
  • Boot Configuration - Learn how to configure the phyCORE-AM57x development kit to utilize different boot media.

Building Images from Source


This section will show you how to configure your development host to build your own BSP images from source and how to start BSP image builds. Building BSP images from source is useful for those who require modifying the default Linux image and if you would like to deploy those changes in an easy and reproducible way.

Development Host Setup

Host Packages

Yocto development requires certain packages to be installed. Run the following commands to install them:

sudo apt-get update
sudo apt-get install git build-essential python python3 diffstat texinfo gawk chrpath dos2unix wget unzip socat doxygen libc6:i386 libncurses5:i386 libstdc++6:i386 libz1:i386 bison flex lzop libssl-dev u-boot-tools
CODE

The above is the recommended package installation for development on a Ubuntu 18.04 LTS Linux distribution. For a breakdown of the packages, as well as a list of packages required for other Linux distributions, see the "Required Packages for the Build Host" section in the Yocto Project Reference Manual: https://www.yoctoproject.org/docs/2.6/ref-manual/ref-manual.html#required-packages-for-the-build-host

Verify that the preferred shell for your Host PC is ''bash'' and not ''dash'':

sudo dpkg-reconfigure dash
# Respond "No" to the prompt asking "Install dash as (/bin/sh)?"
bash
CODE

Repo Tool

Download and install the repo tool. This tool is used to obtain Yocto source from Git.

cd /opt
sudo mkdir bin
# /opt/ directory has root permission, change the permissions so your user account can access this folder. In the following replace <user> with your specific username
sudo chown -R <user>: bin

cd bin
curl http://commondatastorage.googleapis.com/git-repo-downloads/repo > ./repo
# add directory that contains repo to your path
chmod a+x repo
CODE

Add the repo directory in your PATH, using export from the command line or permanently by including it in .bashrc:

export PATH=/opt/bin/:$PATH
CODE

Git Setup

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

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
CODE

Setup the BSP Directory

Create a directory which will house your BSP development. In this example the BSP directory is /opt/PHYTEC_BSPs/. This is not a requirement and if another location is preferred (ex. ~/PHYTEC_BSPs) feel free to modify. We recommend using /opt over your HOME directory to avoid errors attributed to ~ syntax as well as the sudo requirement for the root filesystem and automation package building. We also recommend creating a package download directory (yocto_dl) separate from the yocto tree (yocto_ti), as it makes resetting the build environment easier and subsequent build times much faster.

sudo mkdir /opt/PHYTEC_BSPs
cd /opt/


# /opt/ directory has root permission, change the permissions so your user account can access this folder. In the following replace <user> with your specific username
sudo chown -R <user>: PHYTEC_BSPs


cd PHYTEC_BSPs
mkdir yocto_ti
mkdir yocto_dl
cd yocto_ti
export YOCTO_DIR=`pwd`
CODE

At this point you will now be able to navigate to the Yocto directory using the $YOCTO_DIR environment variable.

Install the Toolchain

Run the following commands to install the Toolchain:

wget https://developer.arm.com/-/media/Files/downloads/gnu-a/8.3-2019.03/binrel/gcc-arm-8.3-2019.03-x86_64-arm-linux-gnueabihf.tar.xz
tar -Jxvf gcc-arm-8.3-2019.03-x86_64-arm-linux-gnueabihf.tar.xz -C /opt/bin
rm gcc-arm-8.3-2019.03-x86_64-arm-linux-gnueabihf.tar.xz
CODE

Download the BSP Meta Layers

Download the manifest file for the phyCORE-AM57x BSP:

cd $YOCTO_DIR
repo init -u https://stash.phytec.com/scm/pub/manifests-phytec.git -b am57xx -m PD20.1.2.xml
CODE

Download the Yocto meta layers specified in the manifest file:

repo sync
CODE

Start the Build

You can replace MACHINE=am57xx-phycore-kit in all of the build instructions with the appropriate MACHINE for your SOM configuration. The SOM-specific MACHINE targets can be found in the Yocto Machine Configuration Table section of the latest phyCORE-AM57x Linux BSP release notes. However, the am57xx-phycore-kit MACHINE target will produce images that work for all phyCORE-AM57x SOMs.

Run the Yocto build directory setup script. The TEMPLATECONF variable is used to set the source of the local configuration files (conf/bblayers.conf and conf/local.conf), which are located in the meta-phytec layer:

cd $YOCTO_DIR
TEMPLATECONF=$YOCTO_DIR/sources/meta-phytec/meta-phytec-ti/conf MACHINE=am57xx-phycore-kit source sources/oe-core/oe-init-build-env build
CODE

Open the build/conf/local.conf file using your favorite editor and make the following modifications:

DL_DIR ?= "/opt/PHYTEC_BSPs/yocto_dl"
CODE

Select a specific machine to target the build with.

MACHINE ?= "am57xx-phycore-kit"
CODE

Maximize build efficiency by modifying the BB_NUMBER_THREADS variable to suit your host development system. This sets the maximum number of tasks that BitBake should run in parallel. Also set the variable PARALLEL_MAKE to specify the number of threads that make can run. By default, these are set to 4 in build/conf/local.conf:

# Parallelism options - based on cpu count
BB_NUMBER_THREADS ?= "4"
PARALLEL_MAKE ?= "-j 4"
CODE

Add the following to a new line at the end of the file to set the TOOLCHAIN_BASE variable to point to where you extracted the Toolchain:

build/conf/local.conf

TOOLCHAIN_BASE = "/opt/bin"
CODE

Be sure to save your changes to the local.conf file before closing.

Increase the limit on open file descriptors in your bash shell from the default of 1024 to 8192:

ulimit -n 8192
BASH


The setup is complete and you now have everything ready to start a build. This BSP has been tested with the arago-core-tisdk-bundle and it is suggested that you start with this image before building other images. Alternate images are located in various meta layers at yocto_ti/sources/meta*/recipes*/images/*.bb. They can be found using the command bitbake-layers show-recipes "*-image*" in $YOCTO_DIR/build/.

The default build target is arago-core-tisdk-bundle, which includes all TISDK demos and support.

In the interest of creating a smaller image, we recommend using arago-base-tisdk-image. PHYTEC offers arago-base-tisdk-image binaries on Artifactory.

If building for am5726 or am5716 MACHINE targets, the video and graphics support will be removed from the output regardless of the image target as am57x6 hardware does not support these features.


The following will start a build from scratch. This by default generates a bootloader, Linux kernel, root filesystem images, and installs the toolchain by default.

cd $YOCTO_DIR/build
MACHINE=am57xx-phycore-kit bitbake arago-core-tisdk-bundle
CODE

Built Images

If working with a non-kit SOM, select it in the Yocto Machine Configuration Table and use the device tree files mentioned in the Device Tree File column.

The device tree filename referenced in this section is am5728-phycore-kit-41300111i as the phyCORE-AM57x development kit comes standard with a PCM-057-41300111I SOM.

All images generated by bitbake are deployed to $YOCTO_DIR/build/arago-tmp-external-arm-toolchain/deploy/images/<machine>:

  • Bootloader: MLO, u-boot.img
  • Kernel: zImage
  • Kernel device tree file: am5728-phycore-kit-41300111i.dtb
  • Root Filesystem: tisdk-rootfs-image-am57xx-phycore-kit.tar.xz

Source Locations:

  • Kernel: $YOCTO_DIR/build/arago-tmp-external-arm-toolchain/work/<MACHINE>-linux-gnueabi/linux-phytec-ti/4.19.79+git_v4.19.79-phy3-r7a/git/
    • The device tree file to modify within the linux kernel source is: am5728-phycore-kit-41300111i.dts and its included dtsi files.

  • u-boot: $YOCTO_DIR/build/arago-tmp-external-arm-toolchain/work/<MACHINE>-linux-gnueabi/u-boot-phytec/2019.01+git_v2019.01-phy5-r0/git/

Build Time Optimizations

The build time will vary depending on the package selection and Host performance. Beyond the initial build, after making modifications to the BSP, a full build is not required. Use the following as a reference to take advantage of optimized build options and reduce the build time.

To rebuild U-Boot:

bitbake u-boot-phytec -f -c compile && bitbake u-boot-phytec
CODE

To rebuild the Linux kernel:

bitbake linux-phytec-ti -f -c compile && bitbake linux-phytec-ti
CODE

The Yocto project's Bitbake User Manual provides useful information regarding build options: http://www.yoctoproject.org/docs/2.6/bitbake-user-manual/bitbake-user-manual.html