Enea® Linux User's Guide

Release Version 8.1

Profile rt-8.1 Enea® Linux User's Guide

Enea® Linux User's Guide: Release Version 8.1

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, Enea® NFV Access, 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

Detailed information is found in the Open Source Report(s) provided with this Release.

Table of Contents 1 - Preface ...... 4 1.1 - The Purpose of this Guide ...... 4 2 - Introduction ...... 6 3 - Prerequisites and Requirements ...... 7 3.1 - Git Configuration ...... 7 3.2 - Host Packages ...... 7 3.2.1 - Using Pre-Build Binaries ...... 7 3.2.2 - Required Packages for the Host Development System ...... 7 3.3 - Default Shell Configuration ...... 7 4 - Getting Enea Linux ...... 9 4.1 - Getting Pre-Built Binaries ...... 9 4.2 - Getting the Sources ...... 9 4.2.1 - Get access to git.enea.com ...... 9 4.2.2 - Get Sources ...... 10 5 - Using Enea Linux ...... 11 5.1 - Building Enea Linux ...... 11 5.1.1 - Building Real-Time images ...... 11 5.1.2 - Building the SDK ...... 12 5.2 - Booting Enea Linux ...... 13 5.2.1 - Booting via PXE ...... 13 5.2.2 - Boot from RAM ...... 14 5.2.3 - Boot from SD card ...... 14 5.3 - Customizing Enea Linux ...... 15 5.3.1 - Layers and Adaptations ...... 15 5.3.2 - Adding a Recipe ...... 17 5.3.3 - Configuring Packages via Recipes ...... 17 5.3.4 - Building with Commercial Licenses ...... 17 5.4 - Installing the Enea Linux SDK ...... 18 5.5 - Using Package Management ...... 19 5.5.1 - RPM Package Management (RPM Packages) ...... 19 6 - Application Development ...... 21 6.1 - Cross-Compiling Applications ...... 21 6.2 - Cross-Compiling Kernel modules ...... 21 6.3 - Add an Application using devtool ...... 22 7 - Using Eclipse ...... 25 7.1 - Installing Oxygen Eclipse IDE ...... 25 7.2 - Installing Yocto Plugins ...... 25 7.3 - Setting up a TCF Connection from Eclipse ...... 25 7.4 - Developing Applications in Eclipse ...... 26 7.4.1 - Cross-Compiling from Eclipse ...... 26 7.4.2 - Debugging Applications from Eclipse ...... 27 7.4.3 - Debugging Multi-Process Applications from Eclipse ...... 30 7.4.4 - Using the Postmortem Debugger ...... 31 7.5 - Debugging the Linux Kernel in Eclipse ...... 32 7.6 - Workarounds ...... 34 7.6.1 - Run/Debug Configuration Not Created ...... 34 8 - Real-Time in Enea Linux ...... 35 8.1 - Benchmark ...... 35 8.1.1 - Benchmark Details ...... 35 8.1.2 - Stress Testcases ...... 35

1. Preface 1.1 The Purpose of this Guide

This guide is intended for all Enea Linux developers who want to configure and build customized Linux kernel images for embedded system targets, but also for developers who want to build and run applications in Enea Linux.

Note Always read the README files and the Release Information before this User's Guide.

The recommended order of operations for developers are:

1. Receive information from Enea and read the initial documentation online.

2. Update the development host with the needed packages, then download and install Enea Linux.

3. Download and install the Cross-Compilation Toolchain.

4. Start developing your own Enea Linux applications or building your own Enea Linux images.

It is assumed that the reader of this User's Guide has a deep knowledge about Linux, how to configure the Linux kernel, and knows how to use the Yocto build system. The variety of information provided in this guide can serve as a quick start introduction to the standards and best practices we share with the Linux community. In this spirit, Enea provides training courses1.

With this Enea Linux release you have a verified and easy to install board support package for a number of supported hardware types. The board support package includes a set of prebuilt utilities, accessible and setup to rapidly reach your objectives as a developer. In this regard, the support package contains a Linux kernel and root file system, a Software Development Kit (SDK) which includes the cross-compilation toolchain, a variety of tools and scripts for development and customization, and if opted for, a user-friendly Eclipse version with an integrated development environment.

The documentation for Enea Linux consists of generic and distribution-specific documents. The generic documents are common for several Enea Linux distributions. The main documents are:

Table 1.1 Enea Linux Release Information A distribution specific document detailing what the current release contains, including supported features, references to other documentation, known problems and limitations, and Enea support contact information. README files for the distribution Distribution specific documents that serve as an introduction and how-to for this release, where you also find target specific commands and parameters, replacing the generic examples in the User's Guide. These files also point to Build, Boot, and Configu- ration information details for this distribution. Enea Linux User's Guide The generic manual for developers who build Linux kernels for embedded systems or use prebuilt Linux kernels.

1 http://www.enea.com/training

Enea Linux Open Source Report The distribution specific list of software packages with corresponding Open Source Licenses, that are included in the Enea Linux distribution. Enea Linux Security Report The release specific document listing the CVEs af- fecting this distribuition. Enea Linux Real Time documentation2 and Re- Enea Linux Real-Time Guide and Real-Time Linux al-Time Linux Wiki3 Wiki page.

See also the following generic documentation related to the Yocto project, which actually is based on OpenEmbedded.

• https://www.yoctoproject.org/documentation/archived - Yocto project documentation. Search for the Yocto version included in your Enea Linux distribution.

• http://docs.openembedded.org - OpenEmbedded documentation, useful since Yocto is based on Open- Embedded.

• https://wiki.yoctoproject.org/wiki 4- Yocto Wiki, useful information for Yocto users

• https://wiki.yoctoproject.org/wiki/Ptest - Ptest wiki. Ptest was initiated by Enea, for building, installing and running package test suites

• http://www.crashcourse.ca/wiki/index.php/Poky_Variable_Glossary - Explanation of some Yoc- to/Poky variables used in the build configuration files.

2 https://linux.enea.com/4.0/documentation/html/book-enea-linux-realtime-guide/ 3 https://rt.wiki.kernel.org/index.php/Main_Page 4 https://wiki.yoctoproject.org/wiki

2. Introduction

Welcome to Enea® Linux

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.

The Yocto-based development environment of Enea Linux allows you to build embedded Linux kernels and tool chains on a Linux host. It aids you in customizing embedded Linux kernels for a specific hardware architecture, and in building and troubleshooting embedded Linux applications on targets or emulated in QEMU.

Enea Linux also provides 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.

Providing true open source Linux with customer interests in mind, is the cornerstone for Enea when sup- plying Enea Linux. We provide:

• A Yocto compatible environment, familiar for those who have used Yocto from any other distribution.

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

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

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

Enea can also assist a customer by analyzing source code and producing valid open source reports, as required by the community when open source components are used.

3. Prerequisites and Requirements

Building Enea Linux or compiling applications requires that your git environment be setup properly and for certain packages to be installed on your Linux development host. The following chapter details the configurations needed on the build environment in order to properly use Enea Linux. 3.1 Git Configuration

If you intend to get Enea Linux sources and build Enea Linux yourself, you will need Git installed in your build environemtn. Please refer to Getting Started - First-Time Git Setup1, for more details on how to set up your git environment correctly, including how to set your identity using the following commands:

$ git config --global user.name "John Doe" $ git config --global user.email [email protected] 3.2 Host Packages

In order to work with Enea Linux, you need a set of tools installed on the build machine, depending on the scenario you use. The following chapters will describe what tools to install on the build machine.

3.2.1 Using Pre-Build Binaries

Using the pre-built binaries, you can get up and running more quickly. Since building is not required, there are not a lot of packaes and tools that need to be installed but a few are still required:

• wget - for downloading the Enea Linux binaries

• tar - for decompressing the Enea Linux release

• tftpboot server - for deploying Enea Linux on target

• NFS server - in case you want to mount the root file system over NFS

3.2.2 Required Packages for the Host Development System

Building Enea Linux requires a set of packages to be installed on your Linux development host. The list of required packages is described in the Yocto Project reference manual2. 3.3 Default Shell Configuration

Before installing Enea Linux, make sure that bash is the default shell.

To verify the default system shell

• If your system runs Ubuntu, use list to verify if /usr/bin is a symbolic link to bash:

# ls -l /bin/sh lrwxrwxrwx 1 root root 4 2012-03-02 11:53 /bin/sh -> bash

• Optionally, in case the link points to dash, change it through the following steps:

# ls -l /bin/sh lrwxrwxrwx 1 root root 4 2012-03-02 11:53 /bin/sh -> dash # sudo dpkg-reconfigure dash

1 https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup 2 https://www.yoctoproject.org/docs/2.7/ref-manual/ref-manual.html#required-packages-for-the-host-development-system

Use dash as the default system shell (/bin/sh)? No

4. Getting Enea Linux

Enea Linux is available as both pre-built binary images and source code. Both serve a specific purpose and each have their advantages. However, using the pre-built binary images allows for getting up and running faster. Please refer to the sections below for details on how to get Enea Linux as pre-built binary images or source code. 4.1 Getting Pre-Built Binaries

Enea Linux pre-built binaries are available for download on Enea Download Portal1. Log in using the credentials provided. Using the menu, browse to the Linux section. You will now have access to the Files section and the Online Documentation section.

The Files section lists each Enea Linux distribution, one for each version and profile, as a separate download package. Clicking on the name of the distribution will open a new page, which presents further details about the content of the release and a list of downloadable archives, one for each hardware target included in the release. Each archive provides the following content:

• images directory - this directory includes the binary image files needed to boot the target with Enea Linux. This includes the kernel, the root file system, device tree, etc.

• esdk directory - this directory includes the installer for the Extensible SDK.

• deb directory - this directory contains all the packages included in the distribution in deb format, which can be installed using the package manager.

For faster downloads, each archive is mirrored in several places, geographically. Choose the archive in the region closest to you.

The Documentation section lists all the documents delivered with the release. 4.2 Getting the Sources

Enea Linux sources are available for cloning from a set of Git repositories on git.enea.com2. Since Enea Linux requires multiple repositories, Google Repo tool is used in order to manage configurations and make the cloning step simpler. Google Repo tool uses files, known as manifests, which store a list of tuples (repository URL, version). The Repo tool is then used to traverse the list of tuples in the manifest file and clone the specified versions of each repository. See https://code.google.com/p/git-repo/ for more info.

4.2.1 Get access to git.enea.com

In order to get access to git.enea.com, a ssh key is required for Git authentication. If you don't already have such a key, follow the steps below to generate one:

1. Generate the ssh key pair:

$ ssh-keygen -t rsa

When asked for a password, just press Enter. This will create two files in the .ssh directory in your home directory.

id_rsa id_rsa.pub

1 https://portal.enea.com/login 2 https://git.enea.com

2. Copy the public key into an authorized_keys file:

$ cat id_rsa.pub >> authorized_keys

Once these steps are done and you have a valid ssh key pair, send the public key, id_rsa.pub, via email to in order to get access to git.enea.com3.

4.2.2 Get Sources

To use the Repo tool to download the sources for Enea Linux, do the following:

1. Make sure that the repo tool is installed. If not, do the following:

mkdir -p ~/bin curl https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo chmod a+x ~/bin/repo export PATH=~/bin:$PATH

2. Then use the repo command below:

mkdir enea-linux cd enea-linux repo init -u [email protected]:linux/manifests/el_manifests-rt.git \ -b refs/tags/Enea_Linux_RT_8.1 -m $MACHINE/default.xml repo sync

Once the source code is downloaded, the current directory will contain a README file with instructions on how to build the distro and boot the machine you choose. .

It's not necessary to explicitly clone the manifest repository since that is done automatically by the repo tool. To see the current manifest, use the following command:

$ repo manifest

3 https://git.enea.com

5. Using Enea Linux 5.1 Building Enea Linux

Enea Linux is made available as sources, allowing for the building of various Enea Linux artifacts, detailed in the following sections. 5.1.1 Building Real-Time images

Real-Time images use the Intel RT kernel, no additional configuration is needed.

How to Build an Enea Linux RT image

1. Set the $MACHINE/ variable to the target you need, e.g. intel-corei7-64.

2. Clone Enea Linux sources using the Repo tool. Please refer to Section 4.2, Getting the Sources [9] for more details.

$ mkdir enea-linux $ cd enea-linux $ repo init -u [email protected]:linux/manifests/el_manifests-rt.git \ -b refs/tags/Enea_Linux_RT_8.1 -m $MACHINE/default.xml $ repo sync

3. Source the build environment

$ cd poky $ TEMPLATECONF=meta-el-rt/conf/template. \ . ./oe-init-build-env

Sourcing the build environment is needed every time a new shell is used. However, sourcing using the TEMPLATECONF is only needed the first time around. After the first time, it is enough to source the build directory created before.

Note The build directory may reside on an NFS mount, but the TMPDIR (/ tmp) may not. Either build all on a local disk, or update TMPDIR in conf/local.conf to point to a local disk.

4. Build an Enea Linux RT image

# You have already initiated the build environment and are in the $ bitbake $ cd /tmp/deploy/images// # Here are the build binaries

Note Some builds have restrictions on the length of the path name. If you get a build error indicating that the length is too long, you need to move your build to obtain a shorter path.

Generated images are by default saved in /tmp/deploy/images/, where by default is the current working directory. Images are created for emulation on host or for booting a physical target, according to how the build environment was set up before running bitbake.

Depending on the number of processors and cores, the amount of RAM, the speed of your internet connection and other factors, the build process can take several hours the first time you run it. Sub- sequent builds run much faster since parts of the build are cached.

Note Make sure that the user running the build has access to the Git repositories on git.enea.com. The build process fetches information from git.enea.com so the user running the build needs to have the ssh key properly configured. Please refer to Section 4.2, Getting the Sources [9] for more details on how to get access to Enea Linux sources.

5.1.2 Building the SDK

If you want to rebuild a cross-compilation toolchain to be used by in application development, do the following:

1. Clone Enea Linux sources using the Repo tool. Please refer to Section 4.2, Getting the Sources [9] for more details on how to do this.

$ mkdir enea-linux $ cd enea-linux $ repo init -u [email protected]:linux/manifests/el_manifests-rt.git \ -b refs/tags/Enea_Linux_RT_8.1 -m $MACHINE/default.xml $ repo sync

2. Source the build environment

$ cd poky $ TEMPLATECONF=meta-el-rt/conf/template. \ . ./oe-init-build-env

Sourcing the build environment is needed everytime a new shell is used. However, sourcing using the TEMPLATECONF is only needed the first time around. Afterwards it is enough to source the build directory created before.

Note The build directory may reside on an NFS mount, but the TMPDIR (/ tmp) may not. Either build all on a local disk, or update TMPDIR in conf/local.conf to point to a local disk.

3. Build Enea Linux SDK

# You have already initiated the build environment and are in the $ bitbake -c populate_sdk_ext $ cd /tmp/deploy/sdk/ # Here is the SDK installer script

Note Some builds have restrictions on the length of the path name. If you get a build error indicating that the length is too long, you need to move your build to obtain a shorter path.

The generated SDK installer script is by default saved in /tmp/deploy/sdk, where by default is the current working directory.

For more details on how to install and use the SDK, please refer to Section 5.4, Installing the Enea Linux SDK [18].

5.2 Booting Enea Linux

Regardless whether you decide to use the pre-built images or if you choose to build your own, the end result should be similar. Once you have the artifacts availalbe, you may proceed to booting Enea Linux on target.

Enea Linux supports multiple booting methods which will be described in the following sections.

5.2.1 Booting via PXE

Below is an example of how to boot Enea Linux on a target supporting PXE. The PXE boot is handled by the target BIOS.

This requires the setup of DHCP, TFTP and NFS servers on the host. The DHCP server contains a configuration for the target, found via the target MAC address, and refers to the TFTP server for the boot image and to the NFS server for the root file system.

For the DHCP server, in addition to the general configuration, the DHCPD configuration should contain an entry for the target with the following information:

• Host name. • MAC hardware ethernet address (also available in the TFTP configuration). • IP address (assuming a fixed IP address is used). • The TFTP server shall be defined as next-server. • The relative path in the TFTP server to the PXE file pxelinux.0. • The NFS server IP address and the path to the rootfs on the NFS server, defined as option root- path.

Example of a DHCP server configuration:

host intel-corei7-64_host { hardware ethernet 01:00:25:90:c8:c5:98; fixed-address 192.168.1.38; next-server 192.168.2.10; filename "intel-corei7-64_tftp/pxelinux.0"; option root-path "192.168.2.20:/export/intel-corei7-64_rootfs"; }

For the TFTP server, the TFTP path to the target's pxelinux.0 file is given in the DHCP Configuration. Examples of files included in the TFTP subdirectory indicated by the DHCP configuration are:

pxelinux.0 vesamenu.c32 boot/device01/bzImage (bootable image file) pxelinux.cfg/01-00-25-90-c8-c5-98 (Configuration file)

One configuration file has the same name as the target's MAC address (but with hyphens instead of a colon). This configuration file contains a pointer to the bootable image and also a list of command line arguments to append when the image is started. The same NFS path to the root file system is both in the DHCP and the TFTP configuration.

Example of a configuration file:

default vesamenu.c32 prompt 0 timeout 100

label device01 menu label ^EneaLinuxNFS menu default kernel boot/device01/bzImage

append root=/dev/nfs nfsmount=192.168.2.20:/export/intel-corei7-64_rootfs ip=dhcp console=ttyS0,115200

NFS server: The NFS server shall contain an unpacked root file system in the path indicated both in the DHCP and in the TFTP configuration.

After configuring the servers, copy files from the build directory into the correctly configured paths:

1. Ensure the target is not already running an OS, otherwise the target might attempt to change files on the root file system while it is populated with new files. 2. Copy pxelinux.0 and vesamenu.c32 from the build directory, e.g. from tmp/ work/corei7-64-enea-linux/syslinux/6.04-pre2-r0/image/usr/share/syslinux/. 3. Copy bzImage from /tmp/deploy/images//. 4. Populate the root file system in the NFS directory by unpacking enea-image-rt-intel-cor- ei7-64.tar.gz found at /tmp/deploy/images//.

Boot the target by:

1. Use the BIOS or boot setup to select PXE boot, if not already selected.

2. Reboot the target.

The boot setup menu is usually launched by pressing F12 or ESC during BIOS power up tests. Look up the manufacturer's documentation for your board model to find the appropriate key.

5.2.2 Boot from RAM

This example requires that a TFTP server is set up at IP address , and that the server stores the Enea Linux image files, kernel image, device tree blob and root filesystem, in /tftpboot/. Please refer to Section 3.2.1, Using Pre-Build Binaries [7] for more details on how to install and configure the TFTP server.

Once you have that in place, run the following commands on the target:

## set tftp server IP U-Boot> setenv serverip

## tftp the image files on the target machine U-Boot> tftpboot 0x01000000 Image U-Boot> tftpboot 0x02000000 Image-bcm2837-rpi-3-b.dtb U-Boot> tftpboot 0x03000000 enea-image-standard-raspberrypi3-64.ext2.gz.u-boot

## add any other bootargs values if necessary U-Boot> setenv bootargs "8250.nr_uarts=1 root=/dev/ram rw ramdisk_size=500000 ip=dhcp \ console=ttyS0,115200"

## Start boot sequence U-Boot> booti 0x01000000 0x03000000 0x02000000

5.2.3 Boot from SD card

Copy the enea-image-rt-raspberrypi3-64.rpi-sdimg image to the SD card using the Linux dd tool or Win32DiskImager in Windows, and insert it into the RPi. The Raspberry Pi will not start without a properly formatted SD Card, containing the bootloader, kernel image and rootfs.

Below you can find two methods of how to format an SD Card:

• Format and copy images to the SD card using the Linux dd command line

The dd command copies a file, converting the format of the data in the process, according to the operands specified:

sudo dd bs=4M if=enea-image-standard-sdk-raspberrypi3-64.rpi-sdimg of=/dev/sdg

Note Use dd cautiously - improper usage or entering the wrong values could inadvertently wipe, destroy, or overwrite the data on your hard drive.

• Format the SD card using the Win32DiskImager program

1. Download and unzip Win32DiskImager1.

2. Run Win32DiskImager.exe.

3. Select the drive of your SD card.

4. Select the image enea-image-standard-raspberrypi3-64.rpi-sdimg.

5. Click "Write" and wait for the write to complete.

6. Exit the imager and eject the SD Card.

7. Plug the card into your Raspberry Pi.

Note Be careful to select the correct drive. If you choose the wrong one you may destroy your HDD data. If you are using an SD Card slot and can't see the drive in the Win32DiskImager window, try using an affordable external adapter in a USB slot.

5.3 Customizing Enea Linux

5.3.1 Layers and Adaptations

Bitbake allows a modular approach of Metadata, by building images for the layers listed in the conf/ bblayers.conf file from your build directory.

To avoid polluting the build with unnecessary packages, before adding a new layer, it is recommended to check if the Metadata you need is already available in the enabled layers, in which case, for the intended configuration, it may require less modification.

To ease further use of the layer, try to follow as many best practices as possible when creating it:

• Use names starting with the meta prefix (although this is not a requirement)

• Place your layer under poky

• Isolate different customizations by layer

• Assign the layer to a repository (to easily have access to maintenance)

To enable a layer, its top path must be specified in the BBLAYERS variable, as follows:

1 https://sourceforge.net/projects/win32diskimager/

# POKY_BBLAYERS_CONF_VERSION is increased each time build/conf/bblayers.conf # changes incompatibly POKY_BBLAYERS_CONF_VERSION = "2"

BBPATH = "${TOPDIR}" BBFILES ?= ""

BBLAYERS ?= " \ /path/to/poky/meta \ /path/to/poky/meta-el-common \ /path/to/poky/meta-el-rt \ /path/to/poky/meta-enea-bsp-common \ /path/to/poky/meta-enea-bsp-x86 \ /path/to/poky/meta-openembedded/meta-oe \ /path/to/poky/meta-openembedded/meta-networking \ /path/to/poky/meta-openembedded/meta-filesystems \ /path/to/poky/meta-openembedded/meta-python \ /path/to/poky/meta-poky \ /path/to/poky/meta- \ "

Before adding an extra layer, please keep in mind that the order of layers is important (due to BitBake parsing conf/layer.conf as specified in BBLAYERS). To add an extra layer, you can modify the build/ conf/bblayers.conf file in the source code editor you prefer, as described above, or use one of the specially designed Yocto tools.

To do such, you can simply modify the build/conf/bblayers.conf file in the source code editor you prefer, as described above, or use one of the specially designed Yocto tools.

For instance, in addition to the above, the Yocto Bitbake layers utility ensures a very useful checking of some basic layer requirements. Bitbake layers are available, as most of the BitBake tools, when sourcing oe-init-build-env. Therefore, to enable a custom meta layer, you should simply run the following from the build directory:

bitbake-layers add-layer

If the specified layer doesn't contain a conf/layer.conf file, you should add one with the needed configuration. Also, to make sure the layer insertion is done in the right metadata, the utility looks for the bblayers.conf configuration file in the corresponding path, which should be satisfied if running the command from the generated build directory.

For further information on this or on other utilities belonging to the same suite, run:

bitbake-layers -h

As a result, BBLAYERS shall be extended with the bsp-layer/s layer for your target and any other additional layer/s. For details on how to do this, see the Yocto 2.7 Dev Manual, section "Understanding and Creating Layers".2 If needed replace the Yocto version.

Layers can be added when you initialize the build environment. The layers required for each target are specified in the build commands in the Enea Linux distribution's Release Information.

Each Enea Linux customer is advised to add a custom layer for customer-specific additions and customizations, instead of modifying existing layers.

The recommended way to modify a package is to edit directly in the recipe file. Utilizing the devshell, bitbake -c devshell , when constructing or modifying recipes is really handy when experimenting, but do not forget to make the final updates directly in the recipe file. It is difficult to keep track of exactly what in the user environment is "dirty" and not in sync with current recipes. Therefore,

2 http://www.yoctoproject.org/docs/2.7/dev-manual/dev-manual.html#understanding-and-creating-layers

always make sure to bitbake -c clean after finishing up a devshell session, and adapt recipes accordingly to ensure a shareable and repeatable build environment.

5.3.2 Adding a Recipe

Study the Hello World recipe3 in the Yocto Project Development Manual. If needed replace the example version (2.7) with the Yocto version in your Enea Linux distribution.

5.3.3 Configuring Packages via Recipes

The default configuration produces a standard Linux installation, but it is often desirable to configure specific packages in more detail. Different packages implement their configuration in different ways, and there is no single method that is valid for all packages. As always, in a collaborative development environment, the developer should make sure that the recipes in the custom layer are upgraded accordingly when a reconfiguration of a specific package is done.

In subsequent sections you find examples on how to configure some common packages.

5.3.3.1 The Linux Kernel

The Linux kernel provides a vast array of configuration options, managed using its own configuration system. The kernel package can be supplied from different providers, and this example uses the virtual/kernel package name to refer to the kernel used in the build:

$ bitbake -c menuconfig virtual/kernel

Note menuconfig requires Ncurses. If the terminal that pops up immediately closes instead of show- ing the menuconfig interface, check that the Ncurses development library is installed.

First build the kernel:

$ bitbake -f -c compile -c install -c deploy virtual/kernel

Then build the whole distribution:

$ bitbake enea-image-

5.3.3.2 Busybox

Busybox uses the same configuration system as the Linux kernel and is therefore invoked similarly. In contrast to the kernel, there is generally only one variant of busybox in a distribution and we can therefore refer to it by the package name alone:

$ bitbake -c menuconfig busybox

5.3.4 Building with Commercial Licenses

Note Adding commercial-licensed packages might pose distribution problems due to license agree- ments or patents.

Commercial-licensed packages are not provided with Enea Linux. Depending on your use case, you might need to extend the initial image with more packages by adding recipes and updating the image definition,

3 https://www.yoctoproject.org/docs/2.7/dev-manual/dev-manual.html#new-recipe-single-c-file-package-hello-world

always in accordance with the license conditions. To succeed with building the customized image, you might need to solve dependencies by adding even more packages.

Below is an example with steps on how to add a package with a commercial license. The configuration is updated in two places and the recipes are selected for the packages and any dependencies.

Note This is only an illustrating example, the exact configuration may differ between different packages. Some packages could require other defines added to local.conf and some packages might need an added DEPENDS in the *.inc file, or other particular changes.

• Append the package name to the IMAGE_INSTALL definition, used in the recipe corresponding to the image you will build, as in one of the examples below:

1. If you need the package in a set of images, to avoid defining it in each recipe, add the following line to IMAGE_INSTALL in meta-el-common/images/enea-image-common.inc

package_name \

2. If you have specific images in which you need the package, add the following line in the corresponding recipes in meta-el-/images/enea-image-.bb

IMAGE_INSTALL += " \ package_name \ "

• Add the required license to the LICENSE_FLAGS_WHITELIST definition. This can be done by adding script lines in the corresponding scripts/conf_setup.sh file, which appends LI- CENSE_FLAGS_WHITELIST += " to conf/local.conf.

• To mitigate the build errors caused by packages with commercial licenses, you might also need to append the generic license LICENSE_FLAGS_WHITELIST += "commercial" in the same way as above.

• Select the needed recipes for the packages and add these to the build configuration.

• Select the needed recipes to resolve dependencies for the new packages and add these to the build configuration.

More information about recipes can be found here:

• http://git.openembedded.org/

• https://wiki.yoctoproject.org/wiki/Building_your_own_recipes_from_first_principles

• http://www.yoctoproject.org/docs/current/dev-manual/dev-manual.html#new-recipe-writing-a-new- recipe 5.4 Installing the Enea Linux SDK

Before cross-compiling applications for your target, you need to install the Software Development Kit (SDK) - which contains the cross-compilation toolchain - and set up the cross-compilation environment on your host. The toolchain for each supported target contains a 64-bit library for gcc. The toolchain and the environment-setup script are wrapped together inside a toolchain installer in the form of a shell script.

The cross-compilation toolchain is packaged as follows:

• The toolchain contains the lib64 (64-bit) library.

• The installer has an environment-setup script which will select the lib64 to be used by gcc. This way, a 64-bit application can be cross-compiled.

Do as in the example below to install the SDK and set up the cross-compilation environment:

1. The fastest alternative is to use a precompiled cross-compilation toolchain installer for your host and target.

Please refer to the Release Information document, in section 1.1 Provided Contents, for more details on where to find the pre-compiled SDK installer.

2. Run the installer to unpack the cross-compilation toolchain and the environment-setup script:

$ chmod 770 enea-*-toolchain-.sh $ ./enea-*-toolchain-.sh

When prompted, select to install the SDK in the desired directory, referred to as . The default path where the SDK will be installed, will be shown in the prompt. The installer unpacks the environment setup script in and the toolchain under /sysroots.

Note Choose a unique directory for each toolchain. Installing a second toolchain of any type (buildtools toolchain or cross-compilation toolchain) in the same directory as a previously installed one will break the $PATH variable of the first one.

3. Setup the toolchain environment for your target by sourcing the environment-setup script:

$ . /environment-setup--enea-linux

Example:

$ . /opt/enea/environment-setup-corei7-64-enea-linux

Once the cross-compilation toolchain is in place and the environment set up, you can proceed with Cross- Compiling Applications from Command Line (4.1) or, if Eclipse is installed, Cross-Compiling from Eclipse (5.4.1). 5.5 Using Package Management

A Package Management System (PMS) can be used to customize your image in a consistent way, e.g. to install, upgrade, or delete packages considering the dependencies. The package management systems supported by Enea Linux are described in this section. More information about PMS can be found in the Yocto 2.7 document Yocto Project Mega Manual4. If needed replace the Yocto version in the link. 5.5.1 RPM Package Management (RPM Packages)

The application for performing runtime package management of RPM packages on the target is called rpm.

Use the rpm command to install, upgrade, or remove packages. Before using any rpm options that require network access, please check that the network is configured and working properly.

The rpm command is by default included in Enea Linux images.

5.5.1.1 Preparation

RPM packages need to first be downloaded on target.

4 http://www.yoctoproject.org/docs/2.7/mega-manual/mega-manual.html

# wget https://rpmfind.net/linux/fedora/linux/development/rawhide/Everything/ aarch64/os/Packages/v/vim-common-8.1.2120-1.fc32.aarch64.rpm

They can be copied either from public maintained repositories or from locally maintained collections of useful RPMs.

# wget http://linux.enea.com/RPM/aarch64/vim-common-7.4.481-r0.0.aarch64.rpm

RPM is also identifying and checking for package dependencies. It warns if the package can not be installed correctly and lists what needs to be done.

5.5.1.2 Installing

RPM packages typically have file names like foo-1.0.1-r0.0_arm64.rpm The file name includes the package name (foo), version (1.0.1), revison (r0.0), and architecture (arm64). To install a package, log in as root and type the following command at a shell prompt:

# rpm -i vim-common-8.1.1017-r0.0.aarch64.rpm user.notice [RPM][351]: Transaction ID 5d836e00 started user.notice [RPM][351]: install vim-common-8.1.1017-r0.0.aarch64: success user.notice [RPM][351]: install vim-common-8.1.1017-r0.0.aarch64: success user.notice [RPM][351]: Transaction ID 5d836e00 finished: 0

5.5.1.3 Upgrading

The rpm -U command will upgrade one or more packages which are currently installed in the system.

# rpm -U vim-common-8.1.1518-r0.0.aarch64.rpm user.notice [RPM][346]: Transaction ID 5d836d54 started user.notice [RPM][346]: erase vim-common-8.1.1017-r0.0.aarch64: success user.notice [RPM][346]: install vim-common-8.1.1518-r0.0.aarch64: success user.notice [RPM][346]: erase vim-common-8.1.1017-r0.0.aarch64: success user.notice [RPM][346]: install vim-common-8.1.1518-r0.0.aarch64: success user.notice [RPM][346]: Transaction ID 5d836d54 finished: 0

5.5.1.4 Removing

The rpm -e command will remove the package which is currently installed in the system. Example:

# rpm -e vim-common user.notice [RPM][350]: Transaction ID 5d836dc9 started user.notice [RPM][350]: erase vim-common-8.1.1518-r0.0.aarch64: success user.notice [RPM][350]: erase vim-common-8.1.1518-r0.0.aarch64: success user.notice [RPM][350]: Transaction ID 5d836dc9 finished: 0

5.5.1.5 Searching

The rpm -q allows searching for the given expressions in the name, summary and description of known packages. Example:

# rpm -q vim-common vim-common-8.1.1017-r0.0.aarch64

6. Application Development 6.1 Cross-Compiling Applications

Running make cross-compiles your applications according to the environment settings. By installing a Cross-Compilation Toolchain for your target, the environment variables are set up for cross-compilation. For more details, see Section 5.4, Installing the Enea Linux SDK [18].

Once the cross-compilation environment is set up, you can make your applications as usual and get them compiled for your target. Below you see how to cross-compile from the command line. If Eclipse is installed, you can also cross-compile your code from the Eclipse IDE. For more details, see Sec- tion 7.4.1, Cross-Compiling from Eclipse [26].

1. Create a Makefile for your application. Example of a simple Makefile and application:

helloworld:helloworld.o $(CC) -o helloworld helloworld.o

clean: rm -f *.o helloworld

#include

int main(void) { printf("Hello World\n"); return 0; }

2. Run make to cross-compile your application according to the environment set up:

$ make

Tip If the build fails, check if the GNU Make workaround solves your problem.

3. Copy the helloworld program to your target and run it:

# ./helloworld Hello World 6.2 Cross-Compiling Kernel modules

Running make cross-compiles your kernel modules according to the environment settings. By installing a Cross-Compilation Toolchain for your target, the environment variables are set up for cross-compilation. For more details, see Section 5.4, Installing the Enea Linux SDK [18].

Before cross-compiling kernel modules, you need to make sure the installed toolchain includes the kernel source tree, which should be available at: /sysroots/-enea-linux/usr/src/kernel. If the kernel source tree is not included in the toolchain, you need to add the kernel-dev package into the image recipe enea-image- and build the toolchain again.

Once the cross-compilation environment is set up, you can make your kernel modules as usual and get them compiled for your target. Below you see how to cross-compile a kernel module.

1. Create a Makefile for the kernel module. Example of a simple Makefile and kernel module:

obj-m := hello.o PWD := $(shell pwd)

KERNEL_SRC :=

all: scripts $(MAKE) -C $(KERNEL_SRC) M=$(PWD) LDFLAGS="" modules scripts: $(MAKE) -C $(KERNEL_SRC) scripts clean: $(MAKE) -C $(KERNEL_SRC) M=$(PWD) LDFLAGS="" clean

#include /* Needed by all modules */ #include /* Needed for KERN_INFO */ #include /* Needed for the macros */

static int __init hello_start(void) { printk(KERN_INFO "Loading hello module...\n"); printk(KERN_INFO "Hello, world\n"); return 0; }

static void __exit hello_end(void) { printk(KERN_INFO "Goodbye, world\n"); }

module_init(hello_start); module_exit(hello_end);

MODULE_LICENSE("GPL");

2. Run make to cross-compile your kernel module according to the environment set up:

$ make

3. Copy the kernel module hello.ko to your target and install/remove it:

# insmod hello.ko # rmmod hello.ko # dmesg [...] Loading hello module... [...] Hello, world [...] Goodbye, world 6.3 Add an Application using devtool

As a prerequisite, you need to install the SDK and set up the environment. For this, see Section 5.4, In- stalling the Enea Linux SDK [18].

The following section, Use devtool add to Add an Application1, in Yocto Project Software Development Kit (SDK) Developer's Guide, explains how to use devtool to generate recipes from existing application code, edit and build recipes, and deploy the output on target. If needed, replace the Yocto version in the link.

This example will show how to generate a recipe from the existing application code and Makefile, edit the recipe in order to provide an installation path for the application, build the recipe, and deploy the output on a target, or create a DEB package from the recipe and install the package.

1. Create a simple application and Makefile in /my_app:

/my_app/my_hello_app.c

#include

1 http://www.yoctoproject.org/docs/2.5/sdk-manual/sdk-manual.html#sdk-use-devtool-to-add-an-application

int main(void) { printf("Hello world!\n"); return 0; }

/my_app/Makefile

my_hello_app:

2. Generate a recipe (my-hello-recipe) using the source tree of the application (/my_app):

$ devtool add my-hello-recipe /my_app NOTE: Using source tree as build directory since that would be the default for this recipe NOTE: Recipe /workspace/recipes/my-hello-recipe/my-hello-recipe.bb has been automatically created; further editing may be required to make it fully functional

$ cat /workspace/recipes/my-hello-recipe/my-hello-recipe.bb # Recipe created by recipetool # This is the basis of a recipe and may need further editing in order to be fully # functional. # (Feel free to remove these comments when editing.) # # Unable to find any files that looked like license statements. Check the # accompanying documentation and source headers and set LICENSE and # LIC_FILES_CHKSUM accordingly. # # NOTE: LICENSE is being set to "CLOSED" to allow you to at least start building - if # this is not accurate with respect to the licensing of the software being built (it # will not be in most cases) you must specify the correct value before using this # recipe for anything other than initial testing/development! LICENSE = "CLOSED" LIC_FILES_CHKSUM = ""

# No information for SRC_URI yet (only an external source tree was specified) SRC_URI = ""

# NOTE: this is a Makefile-only piece of software, so we cannot generate much of the # recipe automatically - you will need to examine the Makefile yourself and ensure # that the appropriate arguments are passed in.

do_configure () { # Specify any needed configure commands here : }

do_compile () { # You will almost certainly need to add additional arguments here oe_runmake }

do_install () { # NOTE: unable to determine what to put here - there is a Makefile but no # target named "install", so you will need to define this yourself : }

3. Edit the recipe to provide an installation path for the application:

$ devtool edit-recipe my-hello-recipe

$ cat /workspace/recipes/my-hello-recipe/my-hello-recipe.bb ...

do_install () { # NOTE: unable to determine what to put here - there is a Makefile but no # target named "install", so you will need to define this yourself install -d ${D}${bindir} install -m 0777 ${S}/my_hello_app ${D}${bindir} } ...

4. Build the recipe:

$ devtool build my-hello-recipe

The recipe build results can be seen here: /tmp/work/-enea-linux/my- hello-recipe/1.0-r0/

5. Deploy the output (in this case, the application) on target:

$ devtool deploy-target my-hello-recipe root@ Parsing recipes..done. NOTE: Successfully deployed /tmp/work/-enea-linux/my-hello-recipe/1.0-r0/image

As an alternative you can create a DEB package:

$ devtool package my-hello-recipe ... NOTE: Your packages are in /tmp/deploy/deb

Then copy the DEB package on the target and install it using dpkg:

# dpkg -i my-hello-recipe-1.0-r0.1..deb

7. Using Eclipse 7.1 Installing Oxygen Eclipse IDE

Note Yocto Eclipse Plugins are discontinued, with the last Yocto version that provides them being Yocto 2.5.

Configuration of the Eclipse Oxygen IDE should be done following the Yocto Project Application Devel- opment and the Extensible Software Development Kit (eSDK)1 documentation.

The installation instructions provided in Chapter 5.2.1.1 are no longer valid, please follow the steps below in order to install Eclipse Oxygen:

1. Download the Eclipse Oxygen archive2. Make sure to select the correct architecture in the link provided, e.g. eclipse-cpp-oxygen-2-linux-gtk-x86_64.tar.gz.

2. Unzip the Eclipse archive in your home directory and start the IDE:

$ tar xf ~/Downloads/eclipse-cpp-oxygen-2-linux-gtk-x86_64.tar.gz -C ~/ $ ~/eclipse/eclipse

3. Proceed to Chapter 5.2.1.2 in the Yocto documentation and configure Eclipse with Oxygen.

Note For compatibility reasons, only use JDK version 1.8 on your host.

7.2 Installing Yocto Plugins

To install the Yocto Plugins in Eclipse, follow the instructions in the Yocto Project Application Devel- opment and the Extensible Software Development Kit (eSDK)3 documentation, Chapter 5.2.1.3.

You have the option of installing pre-built plugins from the Yocto Project Eclipse update site (Chapter 5.2.1.3.1) or to install the plugins using the latest source code (Chapter 5.2.1.3.2). We recommend for the first installation the use of pre-built plugins. 7.3 Setting up a TCF Connection from Eclipse

Eclipse supports several types of remote connections to reference boards. Among these is the Target Com- munication Framework (TCF) type of connection. This information will be referenced throughout this guide, as it is used by several features.

How to set up a TCF connection to the target to be used later on

1. Make sure the tcf-agent is running on the target:

ps aux | grep tcf-agent root 329 0.0 0.2 1864824 2600 ? Ssl 12:47 0:08 /usr/sbin/tcf-agent -d -L- -l0

1 http://www.yoctoproject.org/docs/2.5/sdk-manual/sdk-manual.html#adt-eclipse 2 https://www.eclipse.org/downloads/packages/release/oxygen/2/eclipse-ide-cc-developers 3 http://www.yoctoproject.org/docs/2.5/sdk-manual/sdk-manual.html#oxygen-setting-up-the-eclipse-ide

2. Open the Target Explorer perspective from Window > Perspective > Open Perspective > Other... > Target Explorer.

This will open a new perspective, containing the System Management view.

3. The System Management window displays all existing TCF connections and allows you to manage them. To create a new connection, go to Connections > Create New Connection...

4. Type in an appropriate name in the Connection Name field.

5. Select TCP in the Transport Type section.

6. Fill in the target's IP address and leave the Port as it is (1534).

7. Check the Connect on finish checkbox and click Finish.

The connections created will be persistent and accessible from the Debug Configurations plugins. 7.4 Developing Applications in Eclipse 7.4.1 Cross-Compiling from Eclipse

Tip Watch Enea's video about Cross-compiling and Remote Debugging of Applications4.

In order to use Eclipse to compile an application for a certain target architecture, you need to first install a cross-compilation toolchain (SDK), configure the cross-compiler in Eclipse, and then create a Yocto ADT Autotools project , which uses the Yocto SDK.

Installing the cross-compilation toolchain is pretty straightforward. All you have to do is to run the shell script provided with the release and follow the instructions, see Installing a Cross-Compilation Toolchain (SDK).

Before creating the project, you must first configure the cross-compiler in Eclipse:

1. Select Window > Preferences > Yocto Project ADT to open a dialog.

2. Choose a Stand-alone pre-built toolchain.

3. For the Toolchain Root Location option, specify the path to the cross-compilation toolchain, e.g. / opt/enea/.

4. For the Sysroot Location option, specify the path to the target sysroot directory inside the toolchain root location e.g. /tmp/sysroots/corei7-64-enea-linux/

5. If multiple architectures are supported by the SDK, select the desired target architecture from the drop- down list.

Tip You can save different profiles with different configurations. This makes it easy to compile the same code for different architectures by simply choosing the desired development profile.

6. In Target Options, select the External HW option.

4 https://www.youtube.com/watch?v=i6KaMrhVOw8&list=PLF6PIT9GsZ19sUvQOCQnfgoWkQTc5CvGS

Tip Details on how to configure the cross-compiler can be found in the Yocto Project Application Development and Extensible Software Development Kit (eSDK) Manual5.

There is also a good cheat sheet available in Eclipse, under Help > Cheat Sheets > Yocto Project > Creating a Hello World ANSI C or C++ Autotools Project. This cheat sheet covers all the steps up to building the project.

Once you have configured the default options for the cross-compiler you can create a project:

1. Follow the steps in the wizard to create the project: a. Select File > New > Project > C Project and click Next. b. Select Yocto Project ADT Autotools Project > Hello World ANSI C Autotools Project, and give the project a Project name before clicking Next.

Note Having a hyphen character '-' in the name can cause configuration errors. c. Enter the Author and click Finish.

This will automatically generate all the files needed, creating all necessary configurations for cross- compiling. For more on how to create a project, watch Enea's video about setting up an ADT project6.

2. Optionally, if you want to have specific options for cross-compiling this project, select Project > Change Yocto Project Settings and modify the options for this project only.

3. Right-click on the project from the Project Explorer and choose Reconfigure Project. This will generate the necessary makefiles to build the project.

4. Finally, build the project from Project > Build Project, or by right-clicking on the project in the Project Explorer and selecting Build Project. A binary file for the target architecture is created in the project directory.

Tip If you need to add more files or compiler flags or parameters to the Makefile, edit Make- file.am accordingly and then reconfigure the project.

Note Eclipse displays the results from building a project in one Eclipse console, and reconfiguring a project in another one. Switching between the two consoles is necessary to view both outputs.

7.4.2 Debugging Applications from Eclipse

Tip Watch Enea's video about Cross-compiling and Remote Debugging of Applications7.

Using Eclipse you can build an application, deploy it on the target, and debug the source code remotely, all with a single mouse click. However, in order to achieve this you need to make certain configurations.

5 http://www.yoctoproject.org/docs/2.5/sdk-manual/sdk-manual.html 6 https://www.youtube.com/watch?v=2qxWae7srzE&list=PLF6PIT9GsZ19sUvQOCQnfgoWkQTc5CvGS 7 https://www.youtube.com/watch?v=i6KaMrhVOw8&list=PLF6PIT9GsZ19sUvQOCQnfgoWkQTc5CvGS

When setting the cross-compiler options for a target, a run/debug configuration is created as a C/C++ Remote Application instance. The configuration is named according to this syntax _gdb_- , for example: hello_gdb_aarch64-enea-linux.

Note If a run/debug configuration is not created when setting the cross-compiler options, perform the steps in Run/Debug Configuration Not Created.

The instructions below describes how to use Eclipse to debug single-process applications on a target. For information on how to debug multi-process applications, see Debugging Multi-Process Applications from Eclipse.

Use the run/debug configuration to connect the Eclipse GDB interface to the remote target, by doing the following:

1. Select Run > Debug Configurations > C/C++ Remote application from the menu and choose the run/debug configuration from the instances under C/C++ Remote Application in the left pane. You can rename, duplicate or remove the configuration as needed.

2. In the Main tab, do the following: a. Select an existing Connection from the drop-down list, or create a new one following the steps below:

i. To create a new connection, click the New... button and select a connection type. For debugging applications an SSH connection is recommended.

ii. Choose a connection name and fill in the Host information section with the target's IP and the username.

Note For Enea Linux, the default username is root and there is no password set.

iii.Depending on your network setup, select either Public key or Password-based authentication. If using Password-based authentication, leave the field empty when using the default root username.

iv. Click Finish. The new connection should now be available in the dropdown menu. This connection will be persist through all Run/Debug configurations.

You can manage your saved connections in the Connections view from Window -> Show View -> Other... -> Connections. b. Select the binary C/C++ Application you want to deploy.

If you click the Search Project button, Eclipse will parse the project and provide a list of all compiled binaries to choose from. Alternatively, you can Browse the file system for a binary, or use Variables to manually define the path. c. The Remote Absolute File Path is the path to which the binary on the target shall be deployed. Type it directly or click the Browse button and select a location on the remote target. Note that you need to specify the path including the filename. d. Optionally, you may choose not to download the application to the target, but instead debug an already downloaded application. e. You can also configure Eclipse to execute commands prior to launching the application, by speci- fying the commands in the corresponding field. © Enea Software AB 2019 Profile rt-8.1 28 Enea® Linux User's Guide 7. Using Eclipse

3. In the Arguments tab you can specify various arguments to be passed to your application at launch- time.

4. The Debugger tab deals with GDB specific configurations. This is automatically populated when configuring the cross-compiler. You may optionally choose additionally useful options as with any Eclipse GDB interface, e.g. whether to break at entering the main function or uploading shared libraries.

5. To enable debugging with shared libraries, do the following:

• Retrieve the debug sources from the target, and store them in a dedicated folder on the local host. They are found in /usr/src/debug in the target rootfs.

• Set a path mapping your debug configuration. In the Source tab, click Add, select Path Mapping, and assign paths to the mapping:

Compilation path: /usr/src/debug Local file system path (path to the debug sources retrieved from the target): /usr/src/debug

• In the Debugger/Shared Libraries tab, select option Load shared library symbols automatically and set the path to the shared library. The path depends on the processor architecture of your target.

For 32-bit targets: /sysroots/-enea-linux/lib/.debug

For 64-bit targets: /sysroots/-enea-linux/lib64/.debug

Note that inside Eclipse you must load the shared libraries with debug information (not stripped). Shared libraries that get built into the rootfs of the target image have debug information stripped off, for size and speed optimizations.

• To debug applications that depend on shared libraries built outside the rootfs of the target image, the same procedure applies, with the exception that you must upload the required shared libraries to the target prior to starting the debugging session.

If you upload them to /lib or /lib64 (depending on the target architecture) they get loaded by default. Otherwise, you must correctly update the LD_LIBRARY_PATH environment variable to match their look-up path. In Eclipse, you can automatically update this variable by setting the Com- mands to execute before application field to: export LD_LIBRARY_PATH=

6. Once you have set up all the debug configurations, click Apply and Debug. This will launch the GDB on the target and open the Debug perspective. This is the standard Eclipse GDB interface when debugging a remote target. You can use all GDB features, such as setting breakpoints, stepping through code, reading variable values, reading registers, viewing memory, etc.

When the debugger starts, Eclipse opens three consoles:

A. The Remote Shell - used to launch the application and display its output. B. The GDB console - named as the path to its GDB binary. You can use this console to control the GDB from the command line. C. The third console is named as the path of the binary on the local machine, and is in fact an artifact that must be ignored.

After having set up the debug configuration once, you can modify and rebuild your application and then relaunch it by simply clicking the Debug icon (the bug symbol) on the toolbar. You can also select the drop-down list for more configurations, and even add your configuration to the Favorites to easily retrieve it next time.

If you only want to deploy and run the application, without debugging, you can use the same configuration as the one set up for debugging, but simply click the Run icon (the Play button symbol) from the toolbar menu, or select Run > Run Configurations and Run the chosen configuration. 7.4.3 Debugging Multi-Process Applications from Eclipse

In Eclipse, remote debugging of an application that uses multiple processes is slightly different compared to debugging a single process application as described in Debugging Applications from Eclipse.

The following limitations exist for multi-process debugging:

• All debugged processes must share the same binary. • Debugging only works in non-stop mode, i.e. stopping at a breakpoint only stops the current thread while other threads continue to execute.

Note When using the GDB to debug multiple instances of the same process or thread, using the same symbols file, breakpoints will be common to all instances. That is, when setting a breakpoint in the code, all instances will stop there, and there is no way to filter them. The current thread filter in Eclipse is ineffective.

Use the run/debug configuration to connect the Eclipse GDB client to the remote target:

1. Go to Window > Preferences > Run/Debug > Launching > Default Launchers. Under C/C++ At- tach to Applicaton > Debug select the checkbox GDB (DSF) Attach to Process via TCF/TE Launch- er.

2. Select Run > Debug Configurations... from the menu and choose the run/debug configuration from the instances under C/C++ Attach to Application in the left pane. You can create, rename, duplicate, or remove the configurations as needed.

3. If you followed step 1, in the lower part of the dialog you will see that Using GDB (DSF) Attach to Process via TCF/TE Launcher is selected. If not, redo step 1 or click the Select Other... link, and use configuration specific settings by selecting the checkbox GDB (DSF) Attach to Process via TCF/ TE Launcher.

4. In the Main tab, do the following: a. Select the binary C/C++ Application you want to deploy. If you click the Search Project button, Eclipse will parse the project and provide a list of all compiled binaries to choose from. Alternatively, you can Browse the file system for a binary, or use Variables to manually define the path. b. Select an existing Connection from the drop-down list. If a connection is not available, create a new one following the steps in Setting up a TCF Connection from Eclipse. c. The Remote Absolute File Path is the path to the binary of the process you are planning to debug. Type it directly or click the Browse button and select a location on the remote target. You need an active TCF connection to the target for the Browse button to work (see chapter Setting up a TCF Connection from Eclipse). Note that you need to specify the path including the filename. d. Specify the PID of the remote process you are planning to attach.

5. The Debugger tab deals with GDB specific configurations. Select the gdbserver in the Debugger drop- down. You may also choose other useful options as with any Eclipse GDB interface, e.g. whether to break at entering the main function or uploading shared libraries. The following actions are important: a. In the Main tab, enter the path to the GDB binary in the SDK. For example: /tmp/sysroots/x86_64-linux/usr/bin/-enea-linux/- enea-linux-gdb. b. Select option Non-stop mode.

6. Once you have set up all the debug configurations, click Apply and Debug. This will launch the GDB and optionally open the Debug perspective for the process you selected. This is the standard Eclipse GDB interface when debugging a remote target. You can use all GDB features, such as setting breakpoints, stepping through code, reading variable values, reading registers, viewing memory, etc.

Repeat these steps for each process you want to debug. You can have multiple debug sessions running simultaneously for multiple processes sharing the same source code.

7.4.4 Using the Postmortem Debugger

When a program crashes, it may leave a core dump which can be used to figure out exactly why the program crashed. Core dumps are disabled by default and have to be activated before debugging. After retrieving and transferring a core dump file to a host machine, Eclipse and the SDK tool generated for the target, can be used to analyze the application state at the time of the crash.

If deep debugging within Linux libraries is needed, the debug SDK is required. See Installing Enea Linux SDK.

To enable writing core dump files, two steps need to be performed on the target: allowing resources for core dumps and defining a core file name pattern. These settings are valid until the next reboot, unless made permanent by configuration changes in the root file system.

Use the ulimit command to allow the system to use resources for core dumps. The ulimit command controls the resources available to a process started by the shell, on systems that allow such control. Type the following to use this command:

ulimit -c unlimited

To verify the result, type ulimit -a and see if the core file size is set to unlimited. User limits can also be changed from the application code using the function setrlimit(...) declared in the sys/ resource.h header (see the manual available through man setrlimit). To make this permanent across a reboot, adjust the configuration in /etc/security/limits.conf.

The next step is to specify the core pattern which defines the core dump file pattern name. The core pattern is defined in the /proc/sys/kernel/core_pattern.

The format of a core pattern follows certain rules:

• The maximum length is 128 characters

• Default core dump name is core

• The string stored in core_pattern is used as a pattern template for the output filename. Certain string patterns (beginning with %) are substituted with their actual values. The patterns are:

% '%' is dropped %% output one '%' %p pid %P global pid (init PID namespace) %i tid %I global tid (init PID namespace) %u uid (in initial user namespace) %g gid (in initial user namespace) %d dump mode, matches PR_SET_DUMPABLE and /proc/sys/fs/suid_dumpable %s signal number %t UNIX time of dump %h hostname %e executable filename (may be shortened) %E executable path

% both are dropped

• If the first character of the pattern is a '|', the kernel will treat the rest of the pattern as a command to run. The core dump will be written to the standard input of that program instead of to a file.

• By setting the value core_uses_pid to 1, the core dump filename gets the extension .PID, if the core_pattern does not contain "%p".

For example, the default file name core becomes core.PID if the core_uses_pid is set, and no core_pattern is defined.

Specify a core pattern by writing it to /proc/sys/kernel/core_pattern. For example:

echo "/core.%e.%p.%h.%t" > /proc/sys/kernel/core_pattern

To make the core dump file name permanent across a reboot, configure /etc/sysctl.conf. to re- flect this choice, by adding a line like in the following example: kernel.core_pattern=/core.%e.%p.%h.%t.

How to use the Eclipse post mortem debug configuration in order to view the call trace, for the core dump in the Eclipse GDB interface:

1. Ensure a core dump can be created on the target, see the information above. To see the full call stack, the application object files, compiled with debug information, are needed (the -g option in gcc). 2. After a core dump has been created, retrieve the core dump file from the target and store it on the host. 3. In Eclipse on the host, you need the core dump file, the SDK for the target, the application executable, and access to the source code. Once you have those, do the following: a. Switch to the Debug perspective in Eclipse. b. Select Run -> Debug Configurations ... (scroll down if you don't see the option at first glance) - > C/C++ Postmortem Debugger. c. Make sure the C/C++ Application field refers to your project executable, and fill in the Core file field with the path to the downloaded core file. d. Under the Debugger tab, fill in the GDB Debugger field with the path to the GDB binary from the SDK. Example path: /tmp/sysroots/x86_64/usr/bin/-enea- linux/-enea-linux-gdb e. Click the Debug button. Eclipse should switch into the Debug perspective (if it hasn't already) and the debugging instance should break somewhere inside the application. The call stack should be observable in the console and should show a termination message. 7.5 Debugging the Linux Kernel in Eclipse

In this section you learn to set up Eclipse for KGDB kernel debugging over the serial port, with examples for the intel-corei7-64 target. This is only given as an example, your Enea Linux distribution may contain other targets. The corresponding instruction for debugging outside Eclipse is available in Debug- ging the Linux Kernel (KGDB) from Command Line.

How to set up Eclipse for KGDB kernel debugging over a serial port:

1. Make sure that the cross-compilation toolchain (SDK) is installed on the host, see Installing Enea Linux SDK.

2. Ensure that the kernel debug image (vmlinux)is accessible on the host where you run Eclipse, and that you have permissions to execute it. You will later point to it in Eclipse.

If you are using the default kernel delivered with Enea Linux, you can find it in the rootfs under the / boot folder. If you build your own kernel using bitbake, it should be available in your build folder. Lo- cated in, for example: tmp/work/corei7-64-intel-common-enea-linux/linux-in-

tel/4.14.66+gitAUTOINC+d64aec9793_dd6a8b48d4-r0/ linux-corei7-64-intel-common-standard-build/vmlinux

3. In Eclipse:

a. Optional: The Linux kernel has a considerable amount of sources, and indexing the whole of it might take a lot of time. Save time by disabling C/C++ project indexing: i. Select Window > Preferences > C/C++ > Indexer. ii. Unselect the Enable indexer checkbox.

b. Create a project from the kernel tree: i. Select File > New > Project > C/C++ > C project. ii. In the left panel, select Makefile project > Empty project, and give the project a name. iii.Unselect the Use default location option. iv. Click Browse and navigate to the location of the kernel sources (git folder). v. Click Finish.

c. Create a C/C++ GDB Hardware Debugging configuration: i. Go to Run -> Debug Configurations. ii. Double-click GDB Hardware Debugging.

This will create a default configuration named project_name Default.

d. In the Main tab: i. Browse to the location of the vmlinux image. As an alternative, you may select a different project to debug, but if you followed the steps above you should not need to modify this. ii. Select the Disable auto build radio button. iii.At the bottom of the window, make sure GDB (DSF) Hardware Debugging Launcher is selected.

e. In the Debugger tab for C/C++ Application: i. Browse to the location of the GDB binary installed by the cross-compilation toolchain installer, by default: /tmp/sysroots/x86_64-linux/usr/bin/ -enea-linux/-enea-linux-gdb. ii. Select option Use remote target. iii.In the JTAG Device, select Generic Serial from the dropdown list. iv. In the GDB Connection String field, type the host's tty device used for the serial connection to the target, e.g. /dev/ttyUSB0.

f. In the Startup tab: i. Deselect the Load image option. ii. Select the Load symbols option. iii.Ensure that the Use project binary option defaults to your vmlinux image. iv. Click Apply to store the configurations above.

4. Prepare the target for KGDB debugging:

a. Configure a serial communication on the target, using the appropriate device for the target (e.g. ttyS0 for p2020rdb, ttyS2 for pandaboard, ttyPS0 for zynq):

echo ttyS0,115200 > /sys/module/kgdboc/parameters/kgdboc

b. Start KGDB on the target SysRq:

echo g > /proc/sysrq-trigger

c. Keep the serial connection open, but close the terminal to the target.

5. Launch the debug session in Eclipse: a. Select Run > Debug Configurations. b. Select the configuration created above. c. Click the Debug button.

The target halts in function kgdb_breakpoint(). The GDB view opens in Eclipse, and from here you can debug the kernel by giving ordinary GDB commands (resume, step, set breakpoint, etc.). 7.6 Workarounds

7.6.1 Run/Debug Configuration Not Created

• Description: When setting up Remote Debugging from Eclipse, a run/debug configuration is not created when setting the cross-compiler options, thus there is nothing to select under C/C++ Remote Ap- plication in the first step.

• Solution: Manually create a run/debug configuration.

Perform the following steps:

1. Double-click the C/C++ Remote Application. This will create a new debug configuration named after your project.

2. In the Debugger tab, select a GDB debugger by browsing for and selecting the debugger of your cross-compilation toolchain, from your Sysroot Location. Example:

$ /tmp/sysroots/x86_64-linux/usr/bin/\ -enea-linux/-enea-linux-gdb

where is e.g. /opt/enea/.

3. Outside Eclipse, create a new file named .gdbinit within your Eclipse workspace, under your project directory, e.g. //.gdbinit, with the following command, using your Sysroot Location:

$ set sysroot /sysroots

4. Back in Eclipse in the Debugger tab, browse for the newly created .gdbinit file and select it under GDB command file.

5. Click Apply, then go back to the Main tab and continue with the remaining steps in the Remote Debugging section.

8. Real-Time in Enea Linux

The Enea Linux Standard and Real-Time Profiles are based on the same Yocto (poky) version but differ in kernel needs. The RT Profile uses the Intel 4.19/preempt-rt kernel1.

Table 8.1 Addtional packages provided in the RT profile Package Version Description bitcalc 1.0-r0.0 Tool for understanding bit calculations and visualizing to binary, hex and decimal. count-ticks 1.1-r1.0 Counts the number of kernel ticks during command execution. partrt 1.1-r0.0 Tool for dividing a SMP Linux system into a real time domain and a non- real time domain. rt-tests 1.1 Programs that test various rt-linux features.

For the detailed list of packages provided in both Standard and RT profiles along with package versions, please refer to the Open Source Reports. 8.1 Benchmark

The worst case latency benchmark uses a combination of tools: cyclictest2, and stress3. The values of buffer sizes configured for use in the latter tool are chosen both to generate a stressful load on a network via NFS traffic in the hdd test, and in an attempt to resemble a real life embedded application. 8.1.1 Benchmark Details

The combination of cyclictest and stress has been used for the benchmarking presented in this document. Details are given in the tables presented below.

Table 8.2 Stress scenarios Id Command Description cpu ./stress -c worker threads spinning on sqrt() hdd ./stress -d --hdd-bytes 20M worker threads spinning on write()/unlink(). Each worker writes 20MB. io ./stress -i worker threads spinning on sync() vm ./stress -m --vm-bytes 10M worker threads spinning on malloc()/free(). Buffer size: 15MB full ./stress -c -i -m -- worker threads each doing the vm-bytes 15M cpu, io & vm stress. Buffer sizes are malloc: 256MB, write: 15MB.

8.1.2 Stress Testcases

Below you will find several testcases for intel-corei7-64 and raspberrypi3-64 RT images.

1 https://github.com/intel/linux-intel-lts/wiki 2 https://wiki.linuxfoundation.org/realtime/documentation/howto/tools/cyclictest/start 3 http://people.seas.harvard.edu/~apw/stress

8.1.2.1 Details on testcases for intel-corei7-64

Example 8.1 Test 1 (RT image)

# Test case (1/6): rt_bmark.intlat.no_stress # ...... # No stress requested # Starting cyclictest # Command: cyclictest -S -p 99 -q -i 100 -d 20 -l 30000 ...... # Min: 2 us # Avg: 2.0 us # Max: 24 us # Max list: [4, 6, 12, 14, 14, 24] # PASS

Example 8.2 Test 2 (RT image)

# Test case (2/6): rt_bmark.intlat.cpu # ...... # Starting stress(cpu) # Command: 'stress -c 8' # Starting cyclictest # Command: cyclictest -S -p 99 -q -i 100 -d 20 -l 30000 ...... # Min: 2 us # Avg: 2.0 us # Max: 10 us # Max list: [4, 5, 6, 7, 10, 10] # PASS

Example 8.3 Test 3 (RT image)

# Test case (3/6): rt_bmark.intlat.hdd # ...... # Starting stress(hdd) # Command: 'stress -d 8 --hdd-bytes 20M' # Starting cyclictest # Command: cyclictest -S -p 99 -q -i 100 -d 20 -l 30000 ...... # Min: 2 us # Avg: 2.0 us # Max: 24 us # Max list: [7, 13, 14, 20, 24, 24] # PASS

Example 8.4 Test 4 (RT image)

# Test case (4/6): rt_bmark.intlat.io # ...... # Starting stress(io) # Command: 'stress -i 8' # Starting cyclictest # Command : cyclictest -S -p 99 -q -i 100 -d 20 -l 30000 ...... # Min: 2 us # Avg: 2.0 us # Max: 13 us # Max list: [5, 7, 7, 9, 11, 13] # PASS

Example 8.5 Test 5 (RT image)

# Test case (5/6): rt_bmark.intlat.vm # ...... # Starting stress(vm) # Command: 'stress -m 8 --vm-bytes 10M' # Starting cyclictest # Command: cyclictest -S -p 99 -q -i 100 -d 20 -l 30000 ...... # Min: 2 us # Avg: 5 us # Max: 28 us # Max list: [12, 13, 14, 15, 19, 28] # PASS

Example 8.6 Test 6 (RT image)

# Test case (6/6): rt_bmark.intlat.full # ...... # Starting stress(io+cpu+hdd+vm) # Command: 'stress -i 8 -c 8 -d 8 --hdd-bytes 20M -m 8 --vm-bytes 10M' # Starting cyclictest # Command : cyclictest -S -p 99 -q -i 100 -d 20 -l 30000 ...... # Min: 2 us # Avg: 3.6 us # Max: 18 us # Max list: [12, 13, 14, 16, 16, 18] # PASS

Repeat these tests for the Standard image and compare the results (see the following tables).

Table 8.3 Benchmark Numbers for the Standard Image Stress Type Latency [us] no stress cpu Io vm hdd full Min 2 2 2 2 2 2 average 2.0 2.0 2.0 4.5 2.0 3.7 max 36 49 60 270 102 254

Table 8.4 Benchmark Numbers for the RT Image Stress Type Latency [us] no stress cpu Io vm hdd full Min 2 2 2 2 2 2 average 2.0 2.0 2.0 5.0 2.0 3.6 max 24 10 13 28 24 18

8.1.2.2 Details on testcases for raspberrypi3-64

Example 8.7 Test 1 (RT image)

# Test case (1/6): rt_bmark.intlat.no_stress # ...... # No stress requested # Starting cyclictest # Command: cyclictest -S -p 99 -q -i 100 -d 20 -l 30000 ....

.... # Min: 11 us # Avg: 28.4 us # Max: 135 us # Max list: [96, 99, 104, 110, 118, 135] # PASS

Example 8.8 Test 2 (RT image)

# Test case (2/6): rt_bmark.intlat.cpu # ...... # Starting stress(cpu) # Command: 'stress -c 8' # Starting cyclictest # Command: cyclictest -S -p 99 -q -i 100 -d 20 -l 30000 ...... # Min: 11 us # Avg: 29.5 us # Max: 130 us # Max list: [96, 103, 106, 109, 112, 130] # PASS

Example 8.9 Test 3 (RT image)

# Test case (3/6): rt_bmark.intlat.hdd # ...... # Starting stress(hdd) # Command: 'stress -d 8 --hdd-bytes 20M' # Starting cyclictest # Command: cyclictest -S -p 99 -q -i 100 -d 20 -l 30000 ...... # Min: 11 us # Avg: 29.7 us # Max: 173 us # Max list: [117, 126, 132, 137, 147, 173] # PASS

Example 8.10 Test 4 (RT image)

# Test case (4/6): rt_bmark.intlat.io # ...... # Starting stress(io) # Command: 'stress -i 8' # Starting cyclictest # Command : cyclictest -S -p 99 -q -i 100 -d 20 -l 30000 ...... # Min: 11 us # Avg: 27.6 us # Max: 137 us # Max list: [102, 108, 114, 123, 133, 137] # PASS

Example 8.11 Test 5 (RT image)

# Test case (5/6): rt_bmark.intlat.vm # ...... # Starting stress(vm) # Command: 'stress -m 8 --vm-bytes 10M' # Starting cyclictest # Command: cyclictest -S -p 99 -q -i 100 -d 20 -l 30000 ......

# Min: 11 us # Avg: 33.8 us # Max: 150 us # Max list: [107, 116, 119, 124, 125, 150] # PASS

Example 8.12 Test 6 (RT image)

# Test case (6/6): rt_bmark.intlat.full # ...... # Starting stress(io+cpu+hdd+vm) # Command: 'stress -i 8 -c 8 -d 8 --hdd-bytes 20M -m 8 --vm-bytes 10M' # Starting cyclictest # Command : cyclictest -S -p 99 -q -i 100 -d 20 -l 30000 ...... # Min: 11 us # Avg: 31.2 us # Max: 149 us # Max list: [124, 128, 134, 142, 144, 149] # PASS

Repeat these tests for the Standard image and compare the results (see the following tables).

Table 8.5 Benchmark Numbers for the Standard Image Stress Type Latency [us] no stress cpu Io vm hdd full Min 11 12 11 11 9 10 average 26.9 26.9 27.6 31.1 43.8 45.8 max 450 226 547 481 922 941

Table 8.6 Benchmark Numbers for the RT Image Stress Type Latency [us] no stress cpu Io vm hdd full Min 11 11 11 11 11 11 average 28.4 29.5 27.6 33.8 29.7 31.2 max 135 130 137 150 173 149