BSP Development Guide



The BSP Development guide provides you with the tools and know-how to build the Linux Board Support Package (BSP) for the phyCORE-i.MX7 Development Kit. The operating system is built using The Yocto Project. This guide will walk you through the steps of setting up your Host PC, building a Linux image for the phyCORE-i.MX7, and deploying it to the target hardware. You will want to follow this guide if you need to customize the bootloader, kernel, or add packages to the root filesystem for your project based on the phyCORE-i.MX7 SOM.

This guide was written for the standard phyCORE-i.MX7 Development Kit. If you are working with a non-standard kit SOM, there are additional steps required to build this release for your configuration which can be found throughout this guide.


Requirements


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

  • A modern GNU/Linux Operating host system either natively or via a virtual machine:
    • Ubuntu 16.04 LTS 64-bit recommended. 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 70GB 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

Building Images from Source


This section explains how to build your BSP from source.

Development Host Setup

Host Debian Packages

Yocto development requires certain packages to be installed. Run the following commands to ensure you have the packages installed:

sudo apt-get install gawk wget git-core diffstat unzip texinfo gcc-multilib build-essential chrpath socat libsdl1.2-dev curl vim

The above is the recommended package installation for development on a Ubuntu 16.04 LTS Linux distribution. It also includes a couple recommended packages from PHYTEC. For a breakdown of the packages as well as a list of packages required for other Linux distributions, see the "Required Packages for the Host Development System" section in the Yocto Project Reference Manual


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?"

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
chmod a+x repo

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

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. 

git config --global user.email "your@email.com" 
git config --global user.name "Your Name"

Are you new to git?

See here for more information about getting started with Git: https://git-scm.com/

Yocto Build Steps

BSP Directory Setup

Create a directory which will house your BSP development. In this example the root BSP directory is /opt/PHYTEC_BSPs/. The table below gives an overview of the recommended setup and structure used in this BSP Development Guide. 

DirectoryDescription
/opt/PHYTEC_BSPs

Root directory to house your BSP development. 

Note: 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.

/opt/PHYTEC_BSPs/yocto_imx7phyCORE-i.MX7 Yocto tree. Source files for Yocto build. In this guide this directory is referred to as $YOCTO_DIR
/opt/PHYTEC_BSPs/yocto_dlPackage download directory for source tarballs downloaded from the web to be used in the Yocto build. Having this directory separate from your Yocto tree will make resetting the build environment easier and subsequent build times much faster.


The following code block can be used to setup the directory structure described.

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_imx7
mkdir yocto_dl
cd yocto_imx7
export YOCTO_DIR=`pwd`

At this point you will now be able to navigate to the Yocto directory using the $YOCTO_DIR environment variable. You can test it out by running the following:

echo $YOCTO_DIR

You should see the full path to your Yocto directory. Here is an example of the expected output:

Expected Output
support@phytec-support:/opt/PHYTEC_BSPs/yocto-imx7$ export YOCTO_DIR=`pwd`
support@phytec-support:/opt/PHYTEC_BSPs/yocto-imx7$ echo $YOCTO_DIR
/opt/PHYTEC_BSPs/yocto_imx7

Download the BSP Meta Layers

Download the manifest file for BSP-Yocto-FSL-iMX7-PD19.1.0:

cd $YOCTO_DIR 
repo init -u https://stash.phytec.com/scm/pub/manifests-phytec.git -b imx7 -m BSP-Yocto-FSL-iMX7-PD19.1.0.xml

Download the Yocto meta layers specified in the manifest file:

repo sync

Start the Build

Run the Yocto build directory setup. 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-fsl/conf source sources/poky/oe-init-build-env build

Modify the default build configuration to match your Host PC setup. To do so you will want to edit variables in your local configuration file ($YOCTO_DIR/build/conf/local.conf). Open the file to begin editing:

vim conf/local.conf


The text editor used in this guide is vim. Feel free to use other Linux text editors such as nano, sublime, gedit, or whatever you are comfortable with instead.

If you are new to Linux, try out this interactive tutorial for vim to get an introduction: https://www.openvim.com/.

Make the following changes to variables in local.conf:

  • Set DL_DIR to the path to yocto_dl directory you created previously

    Text Editor (local.conf)
    DL_DIR ?= "/opt/PHYTEC_BSPs/yocto_dl"
  • Set BB_NUMBER_THREADS and PARALLEL_MAKE to the number of parallel tasks and threads that should be used for the build. By default these are set to 4 and should not exceed the number of CPU cores dedicated to your machine. These settings will determine how many of your processor's cores will be allocated to the build process. Generally speaking, the more cores you allocate, the faster the build will complete.

    Text Editor (local.conf)
    # Parallelism options - based on cpu count 
    BB_NUMBER_THREADS ?= "4" 
    PARALLEL_MAKE ?= "-j 4"
  • Add variable ACCEPT_FSL_EULA. In order to build certain packages included in the FSL meta layers, you need to accept the NXP EULA located at '$YOCTO_DIR/sources/meta-fsl-bsp-release/imx/EULA.txt'. Please read the file and set the variable to 1 if you accept it.

    Text Editor (local.conf)
    ACCEPT_FSL_EULA = "1"
  • Exit and save changes to local.conf.

If working with a non-kit SOM, please expand the content below for additional instructions.

 Click here to expand...

Non-Standard Kit SOM machine configurations are included in the Yocto layer meta-phytec-extra. To include this meta layer in the build, add it to the build/conf/bblayers.conf file:

        ${BSPDIR}/sources/meta-phytec/meta-phytec-fsl \
+       ${BSPDIR}/sources/meta-phytec-extra \
  "

Not sure whether your SOM is part of a standard kit? See Release Notes Yocto Machine Config table for kit part numbers.


The setup is complete and you now have everything to complete a build. The following bitbake command will start a build from scratch including installation of the toolchain as well as the bootloader, Linux kernel, and root filesystem images. These commands will build the default image, fsl-image-validation-imx for the phyBOARD-Zeta development kit (Yocto Machine configuration: imx7d-phyboard-zeta-004):

cd $YOCTO_DIR/build
MACHINE=imx7d-phyboard-zeta-004 bitbake fsl-image-validation-imx

It is suggested that you start with the fsl-image-validation-imx image to verify functionality before building other images. Alternate images are located in various meta layers at meta*/recipes*/images/*.bb. They can be found using the command bitbake-layers show-recipes "*-image*" in $YOCTO_DIR/build/.

If working with a non-kit SOM, please expand the content below for additional instructions.

See Release Notes for supported Yocto machine configurations, and replace imx7d-phyboard-zeta-004 in the above command with the corresponding Yocto Machine Config string from the Yocto Machine Configuration Table.

Built Images

All images generated by bitbake are deployed to $YOCTO_DIR/build/tmp/deploy/images/imx7d-phyboard-zeta-004:

  • SD Image: fsl-image-validation-imx-imx7d-phyboard-zeta-004.sdcard.bz2
  • Bootloader: u-boot.imx
  • Kernel: zImage
  • Kernel device tree file: zImage-imx7d-phyboard-zeta-004.dtb
    • device tree used when FreeRTOS is running on M4: zImage-imx7d-phyboard-zeta-004-m4.dtb
  • Root Filesystem: fsl-image-validation-imx-imx7d-phyboard-zeta-004.ext4

Source Locations:

Note that v4.14.78-phy<X> and v2018.03-phy<X> within the paths pertain to the release tag for the linux and u-boot sources. This matches the value of RELEASE_VER for the corresponding recipes in meta-phytec-fsl. For example, for release PD19.1.0 the kernel tag is v4.14.78-phy2.

Kernel: $YOCTO_DIR/build/tmp/work/imx7d_phyboard_zeta_004-poky-linux-gnueabi/linux-phytec-fsl/4.14.78+git_v4.14.78-phy2-r0/git/

    • The device tree file to modify within the linux kernel source is: arch/arm/boot/dts/imx7d-phyboard-zeta-004.dts and its dependencies

U-Boot: $YOCTO_DIR/build/tmp/work/imx7d_phyboard_zeta_004-poky-linux-gnueabi/u-boot-phytec/2018.03+git_v2018.03-phy1-r0/git/

    • Board file is located at: board/phytec/mx7d_phyboard_zeta/mx7d_phyboard_zeta.c

    • Device tree file is located at: arch/arm/dts/imx7d-phyboard-zeta-001.dts

Toolchain: $YOCTO_DIR/build/tmp/sysroots/x86_64-linux/usr/bin/arm-poky-linux-gnueabi/arm-poky-linux-gnueabi-

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:

MACHINE=imx7d-phyboard-zeta-004 bitbake u-boot-phytec -f -c compile && bitbake u-boot-phytec

To rebuild the Linux kernel:

MACHINE=imx7d-phyboard-zeta-004 bitbake linux-phytec-fsl -f -c compile && bitbake linux-phytec-fsl

The Yocto project's Bitbake User Manual provides useful information regarding build options.

BSP Documentation