Host setup and development flow (BELK/BXELK)

Introduction

The software development flows for BoraX requires the use of several tools on host side. This document describes how to install and set up these tools.

The following figure shows the developing environment for an Embedded Linux system based on BoraX: it is composed of a host machine and a target machine.

caption

In a typical environment, the host is used by the developer to (cross-)compile the code that is to run on the target. In our case the target is a SOM, while the host is assumed to be a PC running the Linux operating system, either in a physical installation or as a virtual machine. The bootloader running on the target can download the Linux kernel image through the network (TFTP), as well as the u-boot binary images (useful when an update of the bootloader is required). Moreover, the Linux kernel running on the target is able to mount the root file system from different physical media, for example from a directory exported via Network File System (NFS) by the host. This strategy (kernel image and RFS retrieved from the network) saves time during the development phase, since no flash reprogramming or removable storage (SD, usb pen drives, external disks) is required to test new versions or updates of the software components. In contrast with a typical embedded system, BoraX adds some complexity, due to the nature of the Zynq processor, which provides both a CPU core (PS, processing system) and an integrated FPGA (PL, programmable logic). This means that additional tools are required to manage this complexity. In particular, the Vivado® Design Suite and the Xilinx Software Development Kit are required for the hardware level configuration and for building the first stage boot loader (FSBL).

Software components

Xilinx Zynq-7000 development tools

Vivado® Design Suite

Xilinx provides the [https://www.xilinx.com/products/design-tools/vivado.html Vivado® Design Suite], a SoC-strength, IP-centric and system-centric, next generation comprehensive development environment for All Programmable SoCs. The Vivado® Design Suite is used to configure the PS for embedded processor hardware system development. Specification of the microprocessor, memory parameters, boot peripherals, MIO settings and the interconnection of these components, along with their respective detailed configuration, takes place in Vivado IP Integrator.

Xilinx Software Development Kit (SDK)

The Software Development Kit (SDK) is the Xilinx Integrated Design Environment for creating embedded applications on Zynq™-7000 All Programmable SoCs. SDK is the first application IDE to deliver true homogeneous and heterogeneous multi-processor design and debug, it is optionally included with the Vivado Design Suite or ISE Design Suite, or available as a separate free download for application developers. It is based on Eclipse and CDT and it directly interfaces to the Vivado embedded hardware design environment. The SDK offers support for complete software design and debug flows including multi-processor and hardware/software debug capabilities, integrating editor, compilers, build tools, flash memory management, JTAG/GDB debug, custom libraries and device drivers.

Zynq application development flow

The following diagram describes the development flow for Zynq-based Linux applications:

caption

Toolchain

With the term "toolchain" we refer to the set of programs that allow the building of a generic application. For applications built to run on the same platform as the tool chain, we use a native toolchain. On the contrary, for applications built to run on a target architecture different from the host architecture, we use a cross-toolchain. In this case all the tools involved in this process are lead by the “cross-” prefix. So we talk about cross-compiler, cross-toolchain and so on. The cross-toolchain used to build U-Boot, the Linux kernel and the applications is the GNU toolchain for the ARM architecture built for x86 hosts. In other words, the toolchain runs on x86 machines but generates binaries for ARM processors. As for all the software compliant to the GPL license, it is released in source code. Thus the first thing to do to set up the developing environment should be building the cross-toolchain. This is not a trivial task, it takes a lot of time and hard disk space. To avoid this tedious task, we suggest using a pre-built toolchain as explained in the following sections.

First stage bootloader (FSBL)

The first stage bootloader is loaded by the internal bootrom during the boot process. FSBL is run to set up the PS and load the second stage bootloader (U-Boot). The FSBL must be created using the Xilinx development tools and must be stored into the boot memory.

Second stage bootloader: U-Boot

U-Boot is a very powerful boot loader and it became the "de facto" standard on non-x86 embedded platforms. The main tasks performed by U-Boot are:

• Hardware initialization
• Starting a shell on the serial port allowing the user to interact with the system through the provided commands
• Automatic execution of the boot script (if any).

After system power-up, U-Boot prints some information about itself and about the system it is running on. Once the bootstrap sequence is completed, the prompt is printed and U-Boot is ready to accept user's commands. U-Boot manages an environment space where several variables can be stored. These variables are extremely useful to permanently save system settings (such as Ethernet MAC address) and to automate boot procedures. This environment is redundantly stored in two physical sectors of boot flash memory; the default variables set is hard-coded in the source code itself. User can modify these variables and add new ones in order to create his/her own custom set of configurations. The commands used to do that are setenv and saveenv. This process allows the user to easily set up the required configuration. Once U-Boot prompt is available, it is possible to print the whole environment by issuing the command printenv.

For further information on use of U-Boot, please refer to this page.

Kernel

Linux kernel for Zynq processors is maintained primarily by Xilinx, that constantly works in close cooperation with Linux community in order to push all the released drivers into mainstream kernel.

Kernels released within BXELK derive directly from Xilinx Zynq kernels, with patches added by DAVE Embedded Systems to support the BoraX hardware platform.

Target root file system

The Linux kernel running on the target needs to mount a root file system. Building a root file system from scratch is definitively a complex task because several well known directories must be created and populated with a lot of files that must follow some standard rules. Again we will use pre-packaged root file systems that make this task much easier. Please note that using a pre-packaged root file system can lead to conflicts with the application binaries obtained using the pre-built cross-toolchain: as a general rule, dynamically linking an application against libraries built with a different toolchain can cause malfunctioning.

Build system

Introduction A build system is a set of tools, source trees, Makefiles, patches, configuration files and scripts that makes 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 (libraries, programs), the 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).

BXELK does not provide a fully structured build system, since various heterogeneous tools are required to build the software components for the BORAX SOM. 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. 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”.

Setting up the Zynq development server environment

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

• Vivado® Design Suite version 2014.4
• Xilinx Software Development kit
• 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 our 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 by a lot of files (including temporary and GUI-managed files), providing the BORA/BORAX 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:

caption

BXELK 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 BXELK 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 3.3.3.7 TBD).

Setting up the Linux development server environment

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 through NFS (installation and configuration depends on the host Linux distribution).

Pre-built toolchain

To start developing software for the BORA 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/.

BXELK 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 Sections 3.2.6 TBD and 4.6 TBD for further details.

U-Boot and Linux git repositories

BELK source trees for U-Boot and Linux kernel are provided as git repositories.

TBD Component Git Remote U-Boot git@git.dave.eu:dave/bora/u-boot-xlnx.git Linux git@git.dave.eu:dave/bora/linux-xlnx.git

This means that these components can be kept in sync and up to date with DAVE Embedded Systems' repositories.

When the git account is enabled (please refer to section 3.3.3.6), 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).

Please refer to this page for detailed instructions on how to get access to DAVE Embedded Systems' git repositories.

Working with BXELK

The following sections describe how to perform the most common tasks for building the software components for a BORA-based embedded system.

Creating and building a Zynq project for BoraX

BXELK provides an example Vivado project for BoraX boards. This project allows to:

• generate the FSBL binary image
• generate the bitstream of a simple PL design used to route PS' CAN0 and UART0 signals through EMIO (see also the following pictures).

This article describes how two build this project. Two procedures are described, the former is command line based while the latter is GUI based.

The project is stored is a git repository, as described in section 3.3.2.1. It is assumed that the Zynq development environment has been set up properly (see section 3.3.2 for more details).

caption

Command line based procedure

The procedure is the following:

Host setup

As stated previously, XUELK host tools are based on a Managed Virtual Machine. As indicated here, microSD card delivered along with XUELK includes basic version of MVM that is the default option.

In case you choose to use the Advanced version of the MVM instead, the project-name to be used is lynx.

Either version you choose, please follow the procedure described here to install the MVM.

It is also worth remembering that access to git repositories is required to download target source code. To enable it, please refer to this page.

Either version of MVM is installed, it provides the tools required to build U-boot and Linux kernel. It does not include the tools required to run Yocto build system instead.