Enea® Linux User's Guide

4.0-docupdate1 Enea® Linux User's Guide

This User Documentation consists of confidential information and is protected by Trade Secret Law. This notice of copyright does not indicate any actual or intended publication of this information.

Except to the extent expressly stipulated in any software license agreement covering this User Documentation and/or corresponding software, no part of this User Documentation may be reproduced, transmitted, stored in a retrieval system, or translated, in any form or by any means, without the prior written permission of Enea Software AB. However, permission to print copies for personal use is hereby granted.

Disclaimer

The information in this User Documentation is subject to change without notice, and unless stipulated in any software license agreement covering this User Documentation and/or corresponding software, should not be construed as a commitment of Enea Software AB.

Trademarks

Enea®, Enea OSE®, and Polyhedra® are the registered trademarks of Enea AB and its subsidiaries. Enea OSE®ck, Enea OSE® Epsilon, Enea® Element, Enea® Optima, Enea® Linux, Enea® LINX, Enea® LWRT, Enea® Accelerator, Polyhedra® Flash DBMS, Polyhedra® Lite, Enea® dSPEED, Accelerating Network Convergence™, Device Software Optimized™, and Embedded for Leaders™ are unregistered trademarks of Enea AB or its subsidiaries. Any other company, product or service names mentioned in this document are the registered or unregistered trademarks of their respective owner.

Acknowledgements and Open Source License Conditions

Information is found in the Release Information manual.

Table of Contents 1 - Introduction ...... 6 1.1 - About this Manual ...... 6 1.2 - Enea Linux and Open Source ...... 6 2 - System Requirements ...... 8 3 - Getting Started ...... 9 3.1 - Download and Install Enea Linux ...... 9 3.2 - Install Packages ...... 10 3.2.1 - Ubuntu or Debian ...... 10 3.2.2 - Fedora ...... 10 3.2.3 - OpenSuse ...... 10 3.2.4 - Red Hat ...... 10 3.3 - Initialize Build Environment ...... 12 3.3.1 - Recommended: source enea-init-build-env ...... 12 3.3.2 - Alternative: source oe-init-build-env ...... 13 3.4 - Build Enea Linux Images ...... 14 3.4.1 - Build Performance Considerations ...... 14 3.5 - Run Enea Linux in QEMU ...... 15 3.6 - Use Precompiled Images ...... 15 4 - Target Guide ...... 16 4.1 - Finding Out the Linux Kernel Version ...... 16 4.2 - Enea Linux on QEMU ...... 17 4.2.1 - Setup and Build Enea Linux for QEMU ...... 17 4.2.2 - Run QEMU ...... 18 4.3 - Enea Linux on EVMK2H Keystone ...... 19 4.3.1 - Setup and Build Enea Linux ...... 19 4.3.2 - tftp kernel to RAM and mount rootfs over NFS ...... 20 4.4 - Enea Linux on B4860QDS ...... 21 4.4.1 - Setup and Build Enea Linux ...... 21 4.4.2 - tftp kernel and rootfs to RAM ...... 22 4.4.3 - tftp kernel to RAM but mount rootfs over NFS ...... 22 4.5 - Enea Linux on P2020RDB ...... 23 4.5.1 - Setup and Build Enea Linux ...... 23 4.5.2 - tftp kernel and rootfs to RAM ...... 24 4.5.3 - tftp kernel to RAM but mount rootfs over NFS ...... 24 4.5.4 - Preparing for Building P2020RDB with PREEMPT_RT ...... 24 4.5.5 - Optional: Flashing U-Boot ...... 25 4.6 - Enea Linux on P2041RDB ...... 26 4.6.1 - Setup and Build Enea Linux ...... 26 4.6.2 - tftp kernel and rootfs to RAM ...... 27 4.6.3 - tftp kernel to RAM but mount rootfs over NFS ...... 27 4.6.4 - Preparing for Building P2041RDB with PREEMPT_RT ...... 28 4.6.5 - Optional: Flashing U-Boot, Programming RCW, Programming FMAN ...... 28 4.7 - Enea Linux on P4080DS ...... 29 4.7.1 - Setup and Build Enea Linux ...... 29 4.7.2 - tftp kernel and rootfs to RAM ...... 30 4.7.3 - tftp kernel to RAM but mount rootfs over NFS ...... 30 4.7.4 - Optional: Flashing U-Boot, Programming RCW, Programming FMAN ...... 31 4.8 - Enea Linux on PandaBoard ...... 32 4.8.1 - Setup and Build Enea Linux ...... 32 4.8.2 - tftp kernel and rootfs to RAM ...... 33 4.8.3 - tftp kernel to RAM but mount rootfs over NFS ...... 33 4.9 - Enea Linux on Romley Ivy Bridge x86_64 ...... 34

4.9.1 - Setup and Build Enea Linux ...... 34 4.9.2 - Boot from USB flash memory hard disk ...... 35 4.9.3 - Boot via PXE using DHCP, TFTP, and NFS servers ...... 35 4.9.4 - Root file system customization hints ...... 36 4.10 - Enea Linux on Xilinx Zynq ZC702 ...... 37 4.10.1 - Setup and Build Enea Linux ...... 37 4.10.2 - tftp kernel and rootfs to RAM ...... 38 4.10.3 - tftp kernel to RAM and mount rootfs over NFS ...... 38 5 - Using Enea Linux ...... 40 5.1 - Applying Patches ...... 40 5.2 - Layers and Adaptations ...... 40 5.3 - Appending Recipes for a Custom Layer ...... 41 5.4 - Adding a Hello World Recipe ...... 41 5.5 - Rootfs Images and Toolchains ...... 41 5.6 - Configuring Packages ...... 43 5.6.1 - The Linux Kernel ...... 43 5.6.2 - Busybox ...... 43 5.7 - Installing a Cross-Compilation Toolchain ...... 44 5.8 - Cross-Compiling Applications from Command Line ...... 45 5.9 - Using the Package Management Systems (PMS) ...... 46 5.10 - Debugging the Linux Kernel (KGDB) from Command Line ...... 47 5.11 - Using wic to Create Rootfs Images ...... 49 5.11.1 - About wic ...... 49 5.11.2 - Configuration ...... 49 5.11.3 - Setting up SDK Environment (Prerequisite in Raw Mode) ...... 51 5.11.4 - Generate Rootfs Image from Bitbake Image (Cooked Mode) ...... 51 5.11.5 - Generate Rootfs Image from Core Base Rootfs (Raw Mode) ...... 51 5.11.6 - Generate Rootfs Image from Pre-Built Packages (Raw Mode) ...... 51 6 - Using Eclipse Tools ...... 53 6.1 - Why Eclipse? ...... 53 6.2 - Installing and Starting Eclipse and Plug-ins ...... 53 6.3 - Creating Customized Linux Images in Eclipse ...... 54 6.3.1 - BitBake Commander ...... 54 6.3.2 - HOB ...... 55 6.3.3 - Yocto BSP ...... 55 6.4 - Developing Applications in Eclipse ...... 57 6.4.1 - Cross-Compiling from Eclipse ...... 57 6.4.2 - Setting up a Remote Connection from Eclipse ...... 58 6.4.3 - Launching QEMU from Eclipse ...... 59 6.4.4 - Remote Debugging from Eclipse ...... 60 6.4.5 - Tracing and Profiling from Eclipse ...... 61 6.4.6 - Add Tools Support to Customized Image ...... 66 6.5 - Debugging the Linux Kernel (KGDB) from Eclipse ...... 68 7 - Real-Time in Enea Linux ...... 71 8 - Networking ...... 72 8.1 - Open vSwitch ...... 72 8.2 - DPDK ...... 73 8.3 - DPDK vSwitch ...... 73 8.3.1 - Configuring and Starting DPDK vSwitch ...... 73 8.4 - NUMA ...... 74 9 - Virtualization ...... 76 9.1 - Kernel-Based Virtual Machine (KVM) ...... 76 9.1.1 - Using KVM ...... 76 9.1.2 - Booting a KVM Guest ...... 77

9.1.3 - Starting a Guest ...... 77 9.1.4 - Isolation ...... 78 9.1.5 - Share a Directory with the Host ...... 78 9.1.6 - Networking Using libvirt ...... 79 9.1.7 - Example Configuration Files ...... 79 9.2 - Linux Containers (LXC) ...... 80 9.2.1 - Using LXC ...... 80 9.2.2 - Container Root File System ...... 81 9.2.3 - Network Configuration ...... 81 9.2.4 - Starting a Container ...... 81 9.2.5 - Stopping a Container ...... 82 9.2.6 - Listing Containers ...... 82 9.2.7 - Sharing a Folder Between Containers and Host ...... 82 9.2.8 - Example Container Configuration ...... 82 9.3 - Terminology ...... 83 10 - Troubleshooting ...... 84 10.1 - Build Fails with GNU Make 3.82 ...... 84 10.2 - Workarounds to Tools Problems ...... 84 10.2.1 - BitBake Commander Does Not Start from Eclipse ...... 84 10.2.2 - HOB Does Not Launch from Eclipse ...... 84 10.2.3 - Failed to Launch Server from Eclipse ...... 85 10.2.4 - Run/Debug Configuration Not Created ...... 85 10.2.5 - Inaccessible Variables in SystemTap Script (crosstap) ...... 85 Index ...... 87

1. Introduction

Welcome to Enea® Linux!

With Enea Linux you get a Yocto based development environment allowing you to build embedded Linux kernels and toolchains on a Linux host, to customize embedded Linux kernels for a specific hardware architecture, and to build and troubleshoot embedded Linux applications on target or emulated in QEMU.

Enea Linux also provides you with verified and easily installed board support packages (BSP) for a number of hardware architectures. Each BSP includes a Linux kernel and a root filesystem (rootfs), plus a number of packages that can be extended on request. You also get the packages required for building images on any of the supported Linux distributions for your host. 1.1 About this Manual

This Enea Linux User's Guide provides the following information:

• Getting Started - how to prepare your Linux host for building Enea Linux and build your first image • Target Guide - supported targets, how to build for a target and load the target with kernel and rootfs • Using Enea Linux - how to customize layers, add recipes and configure packages • Using Eclipse Tools - how to use the ADT tools integrated in Eclipse to build customized images and develop applications • Troubleshooting - workarounds to known problems

Extend your reading with additional documentation:

• Enea® Linux Release Information • Enea® Linux Real-Time Guide • Enea® Linux Open Source Report • Enea® Linux Eclipse Open Source Report • Enea Linux solution overview1 on enea.com, with links to downloads and training. • Yocto Project documentation2. When releasing Enea Linux 4.0, the corresponding Yocto 1.6 documentation can be accessed from the Current3 documentation web page. It will later be available from the Archived4 documentation web page. • Ptest description at yoctoproject.org/wiki5 with instructions on how to build, install and run package test suites. 1.2 Enea Linux and Open Source

Enea® Linux is based on the open source configuration system Yocto which is becoming the de facto standard for building and configuring embedded Linux. Yocto development is coordinated by the Yocto Project which was initiated by the Linux Foundation.

Providing true open source with the best for the customer in mind is the key cornerstone for Enea when supplying Enea Linux:

• Enea Linux is Yocto compatible and you will encounter a familiar environment with Enea Linux if you have already used Yocto from any other distribution.

1 http://www.enea.com/software/products/Enea-Linux/ 2 https://www.yoctoproject.org/documentation 3 https://www.yoctoproject.org/documentation/current 4 https://www.yoctoproject.org/documentation/archived 5 https://wiki.yoctoproject.org/wiki/Ptest

• Enea Linux is fully independent from hardware vendor leverage and does not push for a particular hardware architecture.

• Enea has initiated and contributes the package test framework ptest to the Yocto Project. Enea also uses ptest to verify the packages on target.

Enea Linux is simply open embedded Linux, packaged for easy start and upgrade, and will continuously extend its hardware support based on customer demands.

By using and testing Yocto and sharing Linux patches with upstream projects, Enea assists the open source community in providing mature software in less time. As a user of Enea Linux you are also welcome to contribute to the world-wide Linux development by propagating your Linux patches through Enea.

2. System Requirements

Ensure that the following requirements are met for the Linux hosts where you will build your images, and for the targets where Enea Linux will run:

Linux distribution for The downloaded code shall be built on a Linux host to generate images for host your target or for emulation in QEMU. You should experience no problems building Enea Linux on any stable Linux distribution, such as the penulti- mate version of Ubuntu, Fedora, openSUSE, Red Hat, or Debian. Packages on host Depending on the Linux distribution and version on host, some packages are required by e.g. bitbake. You will install required packages when following the instructions further on in this chapter. Supported targets Images can be generated for any of the supported targets in the Target Guide. Required disk space Your system should have at least 50 GB of free disk space when building smaller images like enea-image-minimal. To allow for future package extensions and variations in the build process, as well as for building larger images like enea-image-demo, a minimum of 100 GB free disk space is recommended. Recommended RAM Your system must have at least 4 GB available RAM, and it is recommended to have 8 GB RAM available for parallel build jobs. Internet access Internet access must be available when building an image, since bitbake downloads source files from various servers during the build. Java Running Eclipse requires Java. The Eclipse version, 4.3 Kepler, provided with Enea Linux 4.0, recommends a Java 6 JRE/JDK. More information re- garding operating environments for Eclipse 4.3 is provided in the Eclipse Project Release Notes1.

1 http://www.eclipse.org/eclipse/development/readme_eclipse_4.3.html

3. Getting Started

This chapter describes the steps required until you have a Linux kernel up and running on an emulated or physical target. The examples herein illustrate how to prepare Enea Linux for emulation in QEMU. Corresponding examples for all supported physical targets are found in the Target Guide chapter.

Start with preparing the build environment on your Linux host:

1. System requirements must be met. 2. Download and install Enea Linux 3. Install packages on your Linux host. 4. Initialize build environment.

Once the build environment is ready to use, you can download or build your own kernel and root filesystem for a specific target, and boot Enea Linux on the target or emulated on host:

5. Build Enea Linux for target or Use precompiled images. 6. Run Enea Linux in QEMU or Install and boot Enea Linux on target.

You can now cross-compile your applications for the specified target and run them in Enea Linux.

For your convenience, you can use the optional Eclipse IDE with application development tools (ADT) to cross-compile, trace, and monitor the performance of your applications, see Using Eclipse Tools.

Similar information as in this chapter is provided in the Yocto Project Quick Start1. 3.1 Download and Install Enea Linux

Download the needed tarballs from http://linux.enea.com/4.0:

Enea-Linux-4.0.tar.gz The actual Enea Linux distribution, containing a toolchain in a self- extracting archive, and the following directory: • poky - bitbake, conf files, recipes (.bb, .bbappend, .inc files), packages, patches, scripts, and poky documentation

Enea-Linux-doc_4.0.tar.gz Note If available, take instead Enea-Linux-doc_4.0-docupdate- to get the latest documentation.

The Enea Linux documentation. Recommended tarball containing: • README.htm - index linking to the Enea Linux documentation • README.release - overview of release contents and quick installation guide • documentation - Enea Linux documentation in PDF and HTML format: Release Information, User's Guide, Real-Time Guide, Open Source Reports.

Enea-Linux-Eclipse_4.0.tar.gz The Enea Linux tools. Recommended tarball containing: • eclipse - the Eclipse IDE version 4.3 Kepler, with eclipse bi- nary and plug-ins (CDT, RSE, SDK, ...) • yocto-plugins - additional eclipse plug-ins with tools from the Yocto Project Application Development Toolkit (ADT)

1 http://www.yoctoproject.org/docs/1.6/yocto-project-qs/yocto-project-qs.html

The Eclipse related documentation - Eclipse Open Source Report, and the Eclipse chapter in the User's Guide - is available in the Enea Linux documentation tarball.

Unpack the Enea Linux distribution tarball:

$ tar xzf Enea-Linux-4.0.tar.gz

Unpack the Enea Linux documentation tarball:

$ tar xzf Enea-Linux-doc_4.0.tar.gz # or, if available: $ tar xzf Enea-Linux-doc_4.0-docupdate.tar.gz

If you want to use the Eclipse IDE and the application development tools, unpack the Eclipse tarball:

$ cd Enea-Linux-4.0 # available if the Enea Linux distribution has been unpacked $ tar xzf Enea-Linux-Eclipse_4.0.tar.gz

Finally apply additional patches if needed, see Applying Patches. 3.2 Install Packages

Building Enea Linux requires some packages to be installed on your Linux host. 3.2.1 Ubuntu or Debian

For a supported Ubuntu and Debian distributions you need the following packages:

$ sudo apt-get install gawk wget git-core diffstat unzip texinfo build-essential \ chrpath libsdl1.2-dev xterm

Packages needed for application development:

$ sudo apt-get install autoconf automake libtool libglib2.0-dev 3.2.2 Fedora

For a supported Fedora distribution you need the following packages:

$ sudo yum install gawk make wget tar bzip2 gzip python unzip perl patch \ diffutils diffstat git cpp gcc gcc-c++ glibc-devel texinfo chrpath \ ccache perl-Data-Dumper perl-Text-ParseWords SDL-devel xterm perl-Thread-Queue

Packages needed for application development:

$ sudo yum install autoconf automake libtool glib2-devel 3.2.3 OpenSuse

For a supported OpenSUSE distribution you need the following packages:

$ sudo zypper install python gcc gcc-c++ git chrpath make wget python-xml \ diffstat texinfo python-curses patch libSDL-devel xterm

Packages needed for application development:

$ sudo zypper install autoconf automake libtool glib2-devel 3.2.4 Red Hat

For a supported Red Hat distribution you need the following packages:

$ sudo yum install gawk make wget tar bzip2 gzip python unzip perl patch \ diffutils diffstat git cpp gcc gcc-c++ glibc-devel texinfo chrpath SDL-devel

Packages needed for application development:

$ sudo yum install autoconf automake libtool glib2-devel xterm xorg-x11-xauth

Note Depending on your Red Hat version, other requirements and dependencies might exist.

3.2.4.1 Required Git, tar, and Python Versions for Red Hat

Bitbake requires the following versions of Git, tar and Python on your build host:

• Git 1.7.5 or later • tar 1.24 or later • Python 2.7.3 or later version not including Python 3.x, which is not supported • wget 1.13 or later

The required versions of these tools are part of the buildtools toolchain, which in its turn is included in the self-extracting archive enea-eglibc-x86_64-buildtools-tarball-core2-64-buildtools-nativesdk-standalone-4.0.sh, referred to as the "installer" in this instruction.

You have two options to install the required package versions:

A. Use the precompiled buildtools toolchain supplied with Enea Linux: 1. Extract the installer from the Enea-Linux-4.0 tarball, see Download Enea Linux. 2. Install the buildtools toolchain by running the installer:

$ ./enea-eglibc-x86_64-buildtools-tarball-core2-64-buildtools\ -nativesdk-standalone-4.0.sh

You will be prompted where to install the toolchain. Enter e.g. /opt/enea/4.0. 3. Source the environment setup file to take the new packages into use, e.g.:

$ source /opt/enea/4.0/environment-setup-x86_64-eneasdk-linux

B. ... or, you can use your own buildtools toolchain, but you have to build it on another Linux distribution since you do not yet have the tool versions required by bitbake to build it on this system (Catch-22). 1. Build the buildtools toolchain on a Linux distribution where bitbake can run, and save the results to a dedicated build directory:

$ cd Enea-Linux-4.0/poky $ source enea-init-build-env -m genericx86-64 -b build-buildtools $ bitbake buildtools-tarball

The buildtools toolchain is created and wrapped in the installer in ./tmp/deploy/sdk/. The SDKMACHINE variable in local.conf determines whether you build tools for a 32-bit or 64-bit system. You can use "i686" or "x86_64" as possible values for this variable. 2. Copy the .sh file to this Red Hat system. 3. Install the buildtools toolchain by running the installer:

$ ./enea-eglibc-x86_64-buildtools-tarball-core2-64-buildtools-\ nativesdk-standalone-4.0.sh

You will be prompted where to install the toolchain. Enter e.g. /opt/enea/4.0. 4. Source the environment setup file to take the new packages into use, e.g.:

$ source /opt/enea/4.0/environment-setup-x86_64-eneasdk-linux

3.3 Initialize Build Environment

Before building any image, you need a build directory with configuration for bitbake. This initialization is accomplished by sourcing an init script from within Enea-Linux-/poky.

Choose one of the following init scripts:

• enea-init-build-env - quickest, the Enea way • oe-init-build-env - the good old OpenEmbedded way

The script creates - if not already existing - a build directory with configuration files, and changes working directory into the build directory. bitbake shall be run from within the build directory, and images will be saved here.

The script updates files under the build folder only, no other files, and tells what is modified.

See the Yocto Mega Manual for more details about The Build Directory2.

$ cd Enea-Linux-4.0/poky $ source