Build system (BELK/BXELK)

Info Box Applies to Bora Applies to BORA Xpress

As the structure of the BELK/BXELK is based on several tools, it is strongly recommended the reading of this document and this document first.

History

Version	Date	BELK version	Notes
1.0.0	November 2015	3.0.0	First release
1.0.1	December 2016	3.0.0	Updated information about git repositories access
2.0.0	July 2017	3.0.0, 4.0.0	Updates for BELK 4.0.0/BXELK 2.0.0

Introduction

A build system is a set of tools, source trees, Makefiles, patches, configuration files and scripts that make it easy to generate all the components of a complete embedded Linux system. A build system, once properly set up, automates the configuration and cross-compilation processes, generating all the required targets (userspace packages such as libraries and programs, the o.s. kernel, the bootloader and root filesystem images) depending on the configuration. In particular, using an integrated build system prevents from problems caused by misaligned toolchains, since a unique toolchain is used to build all the software components, including the customer application. Some well known structured build systems are the following:

• OpenEmbedded (http://wiki.openembedded.net/index.php/Main_Page)
• Yocto (https://www.yoctoproject.org/)
• Buildroot (http://buildroot.uclibc.org).

In the following section, we will refer to the system running the Xilinx tools (that can be either a Microsoft Windows machine or a GNU/Linux machine) as the "Zynq development server", and to the machine running the GNU/Linux tools as the "Linux development server".

As described here, the structure of the BELK/BXELK has changed over the years. That's why the istructions here indicated may differ accoording to the kit version.

Setting up the Zynq development server environment

The following software packages must be installed on the Zynq development server:

• Vivado® Design Suite version 2017.1 (for BELK 4.0.0 or newer, BXELK 2.0.0 or newer)
• Vivado® Design Suite version 2014.4 (for BELK version up to 3.0.2, BXELK version up to 1.0.1)
• Xilinx Software Development kit (same version as the Vivado® Design Suite)
• Python 2.7.x (C:\Python27 must be the installation directory on Windows)
• A Git tool (e.g. for Windows: MsysGit http://msysgit.github.io/).

The Zynq 7000 development tools can be downloaded from the Xilinx website: http://www.xilinx.com/support/download/index.htm in the WebPACK™ Edition, which is a free version that provides instant access to the fundamental Vivado features and functionality at no cost. For the hardware requirements of the PC, please refer to http://www.xilinx.com/design-tools/vivado/memory.htm#zynq-7000. The Git tool is used to download the BORA/BORAX project files for Vivado from DAVE Embedded Systems' public git repositories, as described in the next section.

N.B. Sometimes the download of the Vivado 2014.4 full package fails because of some download system malfunctioning, but the problem is barely noticeable, except by performing the MD5 check of the downloaded file. In case of problems, we suggest using the Multi-File Download (available on the same web page), that splits the full package in a collection of smaller files. If you use the Multi-File Download to get the "Vivado (No SDK)" package, you must also download the "Software Development Kit - 2014.4" package.

How BORA/BORAX project files are managed

Since a Vivado project for the Zynq device is composed of a lot of files (including temporary and GUI-managed files), providing the BORA project files with the BELK is not considered as an efficient and user-friendly solution, for two main reasons:

• we should provide a compressed archive for each version (updates, new features, bug fixes) of the project, wasting storage space and download bandwidth, introducing redundancy and complicating file management
• there is no version control, which means that it's not possible to track changes to the project files, making development and release management complicated and error-prone

The best solution to these problems is that we create and maintain a Git repository to store and track only the main files of the Vivado project. Therefore, the developer can clone the repository and keep it in sync with our modifications. The following diagram shows how the solution works:

git-based Vivado project management

BELK also provides the tools for keeping the files modified within the Vivado tools in sync with the local Git repository: with this solution, all the modifications are tracked and developers can take advantage of all the benefits of using git as a version control system.

The public git repository for BORA/Zynq project files is git@git.dave.eu:dave/bora/bora.git. Please note that BELK distribution provides the git archive of the .git directory of the repository, so the user can immediately get access to the development tree (please refer to section Using the pre-packaged git archive).

Setting up the Linux development server environment

During development, the software developer needs to interact with the target system. This section describes the tools that must be installed and configured on the Linux host system for this purpose.

BELK 4.0.0 or newer, BXELK 2.0.0 or newer

Thanks to the use of the Managed Virtual Machine (MVM) (the Basic version), the process of setting up the Linux development server is dramatically simplified with respect to the previous versions of the kit. To put it simply, MVM is a virtual machine containing all the tools required for the development of the software running on the target. To install it, please refer to this page.

If you purchased a previous version of the kit and want to upgrade it, it is necessary to download the MVM image first. For more details, please contact our Sales Department.

As described here, MVM includes the resources—in terms of network services, cross-toolchain, etc.—to implement the development host shown here.

Part of these resources was generated by the Yocto build system, as depicted in the following picture.

Simplified flow of Yocto-based building process

The Yocto-related resources included in the MVM provided with the kit allows the developer to:

• Build U-Boot SPL/U-Boot separately
• Build the Linux kernel separately
• Build user application upon the Yocto SDK
• Use a pre-built root file system image
• Install on the target pre-built additional packages.

The build processes mentioned above make use of a pre-built cross-toolchain. To use it, the shell environment has to be set up properly first. To do this, just issue the following command:

source /home/dvdk/env.sh

For detailed instructions on how to build U-Boot and the Linux kernel, please refer to this page and this page.

By default, the sources are installed in the following directories:

• U-Boot: /home/dvdk/<target_name>/u-boot
• Linux kernel: /home/dvdk/<target_name>/linux
• MVM: /home/dvdk/<target_name>/mvm/.

U-Boot and Linux sources were retrieved from public git repositories:

Component	Remote git repository
U-Boot	git@git.dave.eu:dave/bora/u-boot-xlnx.git
Linux kernel	git@git.dave.eu:dave/bora/linux-xlnx.git
Yocto BSP	git@git.dave.eu:dave/bora/bora-bsp.git

Access to DAVE Embedded Systems' git repositories is granted to development kit's owners only. Please refer to this page for detailed instructions on how to get access.

The components listed in the table above can be kept in sync and up to date with DAVE Embedded Systems' repositories. Once the git account has been enabled, the developer can:

• clone the repository with the git clone <git_remote_repository> command
• synchronize a source tree entering the repository directory and launching the git fetch origin command.

Please note that git fetch doesn't merge the commits on the current branch. To do that, the developer should run the git merge command or replace the fetch-merge process with a single git pull command. Please note that the recommended method is the fetch-merge process. For further information on Git, please refer to the official Git Documentation (http://git-scm.com/documentation).

Technically speaking, the developer can run a Yocto-based full build process to (re)generate all the pre-built objects includes in the MVM. However, this process requires a lot of hardware resources in terms of disk storage, RAM, and processing power. For this reason, it is discouraged to use the MVM to perform such build. Using a physical machine is recommended instead. For more details on this, please refer to this page.

As known, Linux needs a root file system to operate: a root file system must contain everything needed to support the Linux system (applications, settings, data, ..). The root file system is the file system that is contained on the same partition on which the root directory is located. The Linux kernel, at the end of its startup stage, mounts the root file system on the configured root device and finally launches the /sbin/init, the first user space process and "father" of all the other processes. For more information on the Linux filesystem, please refer to http://www.thegeekstuff.com/2010/09/linux-file-system-structure/.

BELK/BXELK provides one (or more) pre-built root file system, that can be used during the evaluation/development phase since it provides a relatively rich set of packages for working with the BORA platform. This root file system is located here: /home/dvdk/<target_name>/rfs/<kit_name>.

BELK/BXELK also provides a rich repository containing pre-built applications and libraries. These packages can be easily installed on the target by using the smart tool. Please refer to this section for more details.

The following table lists the pre-built root file systems included in the MVM.

Kit version BELK BXELK	Image name	Build commands	Path
4.0.0 2.0.0	bora-image-devel	dvdk@dvdk-vm:~/belk$ curl http://commondatastorage.googleapis.com/git-repo-downloads/repo > repo dvdk@dvdk-vm:~/belk$ chmod a+x repo dvdk@dvdk-vm:~/belk$ ./repo init -u git@git.dave.eu:bora/bora-bsp.git -b bora-morty dvdk@dvdk-vm:~/belk$ ./repo sync dvdk@dvdk-vm:~/belk$ source bora-bsp-init-env.sh dvdk@dvdk-vm:~/belk/build$ bitbake bora-image-devel	/home/dvdk/bora/rfs/belk-4.0.0

The following table lists the pre-built Yocto SDKs included in the MVM. These SDKs are associated with the root file system images mentioned above.

Kit version BELK BXELK	SDK name	Build commands	Path
4.0.0 2.0.0	bora-image-devel	bitbake bora-image-devel -c populate-sdk	/home/dvdk/bora/sdk/belk-4.0.0/sysroots/cortexa9hf-neon-xilinx-linux-gnueabi

About C/C++ application development and debugging, please refer to this page.

BELK version up to 3.0.2, BXELK version up to 1.0.1

Since various heterogeneous tools are required to build the software components for the BORA/BORAX SOM, BELK/BXELK does not provide a fully structured build system. In particular, the Xilinx Zynq 7000 development tools are required to configure the system and build the FSBL, while the standard GNU tools are required to build U-Boot, kernel and user-space applications.

During development, user needs to interact with the target system. This section describes the tools that must be installed and configured on the Linux host system for this purpose.

TFTP Server

One of the most useful features of a bootloader during development is the capability to download the Linux kernel from the network. This saves a lot of time because developer doesn't have to program the image in flash every time he/she modifies it. U-Boot implements the TFTP protocol (see the tftp command), so the host system must be configured to enable the TFTP service. Installation and configuration of a TFTP server depends on the host Linux distribution.

NFS Server

One of the most important components of a Linux system is the root file system. A good development root file system provides the developer with all the useful tools that can help him/her on his/her work. Such a root file system can become very big in size, so it's hard to store it in flash memory. User could split the file system in different parts, mounting them from different media (flash, network, USB...). But the most convenient thing is to mount the whole root file system from the network, allowing the host system and the target to share the same files. In this way, the developer can quickly modify the root file system, even “on the fly” (meaning that the file system can be modified while the system is running).

The most common way to setup a system like the one described is by the use of network file system (NFS). Installation and configuration of NFS service on host machine depends on the Linux distribution. Here is described the procedure for some common distributions.

Pre-built toolchain

To start developing software for the BORA/BORAX platform, users need a proper toolchain, which can be pre-built or built-from-scratch. Building a toolchain from scratch is not a trivial task (though using a recent build system is easier than in the past), so the recommended approach consists in using a pre-built toolchain.

The toolchain used as a reference for BELK is the toolchain provided with the Xilinx SDK (usually installed into /opt/Xilinx/SDK/<Vivado_version>/gnu/arm/lin/bin). Once the toolchain is installed, create a a bash script (env.sh) containing the following lines:

export PATH=<path_to_toolchain>:$PATH
export ARCH=arm
export CROSS_COMPILE=<toolchain_prefix>

For example, for the Vivado 2014.4 release, the variables are the following:

export PATH=/opt/Xilinx/SDK/2014.4/gnu/arm/lin/bin:$PATH
export ARCH=arm
export CROSS_COMPILE=arm-xilinx-linux-gnueabi-

Use the following command to set up the environment shell variables required during the building procedure:

source env.sh

Pre-built root file system

Linux needs a root file system: a root file system must contain everything needed to support the Linux system (applications, settings, data, ..). The root file system is the file system that is contained on the same partition on which the root directory is located. The Linux kernel, at the end of its startup stage, mounts the root file system on the configured root device and finally launches the /sbin/init, the first user space process and "father" of all the other processes. For more information on the Linux filesystem, please refer to http://www.thegeekstuff.com/2010/09/linux-file-system-structure/.

BELK provides a pre-built root file system, that can be used during the evaluation/development phase, since it provides a rich set of packages for working with the BORA platform. Since this pre-built root file system is not generated using the same cross-toolchain used for building the BELK software components, we recommend to choose one of the following options:

• if a native compiler is available on the root file system, go for native compilation instead of cross-compilation
• when you cross-compile, rely on static linking and avoid dynamic linking against the root file system libraries
• build your application using the same cross-toolchain (when available) used for building the root file system

Please refer to this page and this FAQ for further details.

U-Boot, Linux kernel and Yocto BSP git repositories

BELK/BXELK source trees for U-Boot, Linux kernel and Yocto BSP are provided as git repositories, as detailed in the following table.

Component	Remote git repository
U-Boot	git@git.dave.eu:dave/bora/u-boot-xlnx.git
Linux kernel	git@git.dave.eu:dave/bora/linux-xlnx.git
Yocto BSP	git@git.dave.eu:dave/bora/bora-bsp.git

Access to DAVE Embedded Systems' git repositories is granted to development kit's owners only. Please refer to this page for detailed instructions on how to get access.

The components listed in the table above can be kept in sync and up to date with DAVE Embedded Systems' repositories. Once the git account has been enabled, the developer can:

• clone the repository with the git clone <git_remote_repository> command
• synchronize a source tree entering the repository directory and launching the git fetch origin command.

Please note that git fetch doesn't merge the commits on the current branch. To do that, the developer should run the git merge command or replace the fetch-merge process with a single git pull command. Please note that the recommended method is the fetch-merge process. For further information on Git, please refer to the official Git Documentation (http://git-scm.com/documentation).

Using the pre-packaged git archive (BELK <= 3.0.0 only)

BELK distribution provides (on request) the tar-gzipped archive of the .git directory of the repositories, so the user can immediately get access to the development trees (for example this is used when corporate security policies don't allow to use the git protocol).

Uncompressing the archive enables access to the hidden .git directories of the repositories; to get the source files, the developer must enter the project directory (eg: bora/linux-xlnx.git) and launch the git checkout <bora current branch> command, like in the following examples:

• For u-boot: git checkout bora
• For linux: git checkout bora

Once these steps are completed, don't forget to update the repositories, as described in this section.