Reproduce

This document provides the instructions for setting up the build environment, checking out code, building, running and validating the key use cases.

Environment Setup

The following instructions have been tested on hosts running Ubuntu 20.04. Install the required packages for the build host: https://docs.yoctoproject.org/4.1.1/singleindex.html#required-packages-for-the-build-host

Kas is a setup tool for bitbake based projects. The minimal supported version is 3.0.2 (version 3.1 was used during the development), install it like so:

pip3 install --user --upgrade kas==3.1

For more details on kas, see https://kas.readthedocs.io/.

To build the recipe for the FVP_Base_AEMv8R model itself, you also need to accept the EULA 1 by setting the following environment variable:

export FVP_BASE_R_ARM_EULA_ACCEPT="True"

To fetch and build the ongoing development of this Software Stack, follow the instructions in the below sections of this document.

Note

The host machine should have at least 85 GBytes of free disk space for the next steps to work correctly.

Download

Fetch the v8r64 repository into a build directory:

mkdir -p ~/fvp-baser-aemv8r64-build
cd ~/fvp-baser-aemv8r64-build
git clone https://gitlab.arm.com/automotive-and-industrial/v8r64 -b v5.0

Build and Run

The Software Stack supports building and running three sub-stacks: Baremetal Zephyr, Baremetal Linux and Virtualization, which are associated with the use cases described in Use Cases Overview. Instructions to build and run these three sub-stacks are as below:

Baremetal Zephyr

Build and run with the below commands:

cd ~/fvp-baser-aemv8r64-build

# Build
kas build v8r64/meta-armv8r64-extras/kas/baremetal-zephyr.yml \
    --target zephyr-synchronization

# Output images will be located at
# build/tmp_baremetal-zephyr/deploy/images/fvp-baser-aemv8r64/

# Run
kas shell -k v8r64/meta-armv8r64-extras/kas/baremetal-zephyr.yml \
    -c "../layers/meta-arm/scripts/runfvp --verbose --console"

To finish the FVP emulation, you need to close the telnet session:

  1. Escape to telnet console with ctrl+].

  2. Run quit to close the session.

A different sample application can be selected by changing the Kas --target flag value, e.g.:

kas build v8r64/meta-armv8r64-extras/kas/baremetal-zephyr.yml \
    --target zephyr-helloworld

There are 3 supported targets zephyr-helloworld, zephyr-synchronization and zephyr-philosophers. See the Zephyr section for more information.

Baremetal Linux

Build and run with the below commands:

cd ~/fvp-baser-aemv8r64-build

# Build
kas build v8r64/meta-armv8r64-extras/kas/baremetal-linux.yml

# Output images will be located at
# build/tmp_baremetal-linux/deploy/images/fvp-baser-aemv8r64/

# Run
kas shell -k v8r64/meta-armv8r64-extras/kas/baremetal-linux.yml \
    -c "../layers/meta-arm/scripts/runfvp --verbose --console"

Virtualization

Build and run with the below commands:

cd ~/fvp-baser-aemv8r64-build

# Build
kas build v8r64/meta-armv8r64-extras/kas/virtualization.yml

# Output images are located at
# build/tmp_virtualization/deploy/images/fvp-baser-aemv8r64/

# Run
kas shell -k v8r64/meta-armv8r64-extras/kas/virtualization.yml \
    -c "../layers/meta-arm/scripts/runfvp --verbose"

# Check Xen output.
telnet localhost 5000

# Check guest OS in another terminals after Xen started
# Zephyr
# The zephyr-rpmsg-demo application starts automatically.
telnet localhost 5001

# Linux
# The rpmsg-demo application starts automatically.
telnet localhost 5002

Note

When --console is specified, port 5002 (which exposes the Linux terminal) is automatically connected through telnet. In this case, please do not connect to port 5002 again, as another connection to port 5002 terminates the FVP. If no Linux log is printed, connect to port 5000 (which exposes the Xen terminal) in another terminal. More details of runfvp can be found at runfvp.md.

Note

When running the runfvp command with the --verbose option enabled, you will see the following output:

terminal_0: Listening for serial connection on port 5000
terminal_1: Listening for serial connection on port 5001
terminal_2: Listening for serial connection on port 5002
terminal_3: Listening for serial connection on port 5003

Among them, port 5000 is assigned to the Xen hypervisor, 5001 to the Zephyr domain, 5002 to the Linux domain, and 5003 unused. If these ports are already occupied (for example, there is already a runfvp instance running), then the port number will automatically increase by 4, that is, ports 5004 ~ 5007 will be assigned. In this case, checking the output from the Zephyr and Linux domains requires using ports 5005 and 5006:

telnet localhost 5005
telnet localhost 5006

If any port(s) in 5000 ~ 5003 is (are) used by other programs, the FVP will try to find 4 available ports starting from 5000. Be sure to check the log of runfvp (with --verbose) to determine the correct port numbers, then apply the determined port number to the telnet command.

By default, the rpmsg-demo application and the Nginx web server start automatically. rpmsg-demo sends status data from the Zephyr domain to the Linux domain, and saves the data to zephyr-status.html. The files can be visited through Nginx web server using the following commands in the Linux domain.

# The Nginx docker container starts automatically in Linux.
# Check that Nginx is working in Linux.
wget http://localhost/index.html

# Check the rpmsg-demo output in Linux. rpmsg-demo updates this file
# periodically.
wget http://localhost/zephyr-status.html

These pages can also be visited from a web browser in the host that is running FVP. By default port 80 in FVP is mapped to port 8080 on host in the Virtualization stack. To browse these pages in the host web browser, use http://localhost:8080/index.html and http://localhost:8080/zephyr-status.html respectively.

More details of Demo Applications can be found in Applications section.

Validate

The Software Stack contains test suite which are enabled using the environment variable TESTIMAGE_AUTO=1. They can be included into the target build to automatically validate the functionality of each stack. The test cases use the Yocto image testing feature 2 to boot the FVP and validate the output.

Baremetal Zephyr

For the Zephyr RTOS, tests are provided to validate the three sample applications supported in this Software Stack. Use the following command to build and run the tests:

TESTIMAGE_AUTO=1 kas build v8r64/meta-armv8r64-extras/kas/baremetal-zephyr.yml

An example of the test suite output is as follows:

Creating terminal default on terminal_0
Skipping - not zephyr-helloworld
Skipping - not zephyr-philosophers
RESULTS:
RESULTS - zephyr_v8r64.ZephyrTests.test_synchronization: PASSED (3.79s)
RESULTS - zephyr_v8r64.ZephyrTests.test_helloworld: SKIPPED (0.00s)
RESULTS - zephyr_v8r64.ZephyrTests.test_philosophers: SKIPPED (0.00s)
SUMMARY:
zephyr-synchronization () - Ran 3 tests in 3.793s
zephyr-synchronization - OK - All required tests passed (successes=1, skipped=2, failures=0, errors=0)
Creating terminal default on terminal_0
Skipping - not zephyr-helloworld
Skipping - not zephyr-synchronization
RESULTS:
RESULTS - zephyr_v8r64.ZephyrTests.test_philosophers: PASSED (0.64s)
RESULTS - zephyr_v8r64.ZephyrTests.test_helloworld: SKIPPED (0.00s)
RESULTS - zephyr_v8r64.ZephyrTests.test_synchronization: SKIPPED (0.00s)
SUMMARY:
zephyr-philosophers () - Ran 3 tests in 0.638s
zephyr-philosophers - OK - All required tests passed (successes=1, skipped=2, failures=0, errors=0)
Creating terminal default on terminal_0
Skipping - not zephyr-philosophers
Skipping - not zephyr-synchronization
RESULTS:
RESULTS - zephyr_v8r64.ZephyrTests.test_helloworld: PASSED (0.73s)
RESULTS - zephyr_v8r64.ZephyrTests.test_philosophers: SKIPPED (0.00s)
RESULTS - zephyr_v8r64.ZephyrTests.test_synchronization: SKIPPED (0.00s)
SUMMARY:
zephyr-helloworld () - Ran 3 tests in 0.731s
zephyr-helloworld - OK - All required tests passed (successes=1, skipped=2, failures=0, errors=0)

The logs can be viewed at (using zephyr-synchronization as an example):

  • Testimage output: build/tmp_baremetal-zephyr/work/armv8r-poky-linux/zephyr-synchronization/3.2.0+gitAUTOINC+4256cd41df-r0/temp/log.do_testimage

  • Console output: build/tmp_baremetal-zephyr/work/armv8r-poky-linux/zephyr-synchronization/3.2.0+gitAUTOINC+4256cd41df-r0/testimage/default_log

Baremetal Linux

For the Linux OS, to build the image with the test suite and run it, use the following command:

TESTIMAGE_AUTO=1 kas build v8r64/meta-armv8r64-extras/kas/baremetal-linux.yml

An example of the test suite output is as follows:

Creating terminal default on terminal_0
default: Waiting for login prompt
RESULTS:
RESULTS - linuxboot.LinuxBootTest.test_linux_boot: PASSED (89.56s)
RESULTS - basictests.BasicTests.test_basic_tests: PASSED (155.99s)
RESULTS - sysinfo.SysInfo.test_hostname: PASSED (3.41s)
RESULTS - sysinfo.SysInfo.test_kernel_version: PASSED (3.34s)
SUMMARY:
core-image-minimal () - Ran 4 tests in 252.298s
core-image-minimal - OK - All required tests passed (successes=4, skipped=0, failures=0, errors=0)

The logs can be viewed at:

  • Testimage output: build/tmp_baremetal-linux/work/fvp_baser_aemv8r64-poky-linux/core-image-minimal/1.0-r0/temp/log.do_testimage

  • Console output: build/tmp_baremetal-linux/work/fvp_baser_aemv8r64-poky-linux/core-image-minimal/1.0-r0/testimage/default_log

Virtualization

For the Virtualization stack, to build the image with the test suite and run it, use the following command:

XEN_DOM0LESS_DOM_LINUX_DEMO_AUTORUN=0 \
TESTIMAGE_AUTO=1 \
    kas build v8r64/meta-armv8r64-extras/kas/virtualization.yml

This runs the same test cases as for the baremetal Linux and Zephyr stacks, as well as an additional test case against the Xen console output.

Note

When setting TESTIMAGE_AUTO=1 for automatic testing, XEN_DOM0LESS_DOM_LINUX_DEMO_AUTORUN must be set to 0, and vice versa. That is, TESTIMAGE_AUTO and XEN_DOM0LESS_DOM_LINUX_DEMO_AUTORUN cannot be set to 1 at the same time, because demo application autorun and testimage both start the rpmsg-remote application, which will cause testimage to fail.

An example of the test suite output is as follows:

Creating terminal default on terminal_2
Creating terminal xen on terminal_0
Creating terminal zephyr_v8r64 on terminal_1
default: Waiting for login prompt
ptest-runner started
Skipping - not zephyr-helloworld
Skipping - not zephyr-philosophers
Skipping - not zephyr-synchronization
RESULTS:
RESULTS - linuxboot.LinuxBootTest.test_linux_boot: PASSED (145.80s)
RESULTS - basictests.BasicTests.test_basic_tests: PASSED (181.35s)
RESULTS - linuxlogin.LinuxLoginTest.test_linux_login: PASSED (4.58s)
RESULTS - ptest_docker.PtestDockerTests.test_ptestdocker: PASSED (439.05s)
RESULTS - rpmsg.RpmsgTests.test_rpmsg_demo: PASSED (62.72s)
RESULTS - rpmsg.RpmsgTests.test_zephyr_boot: PASSED (0.00s)
RESULTS - sysinfo.SysInfo.test_hostname: PASSED (5.30s)
RESULTS - sysinfo.SysInfo.test_kernel_version: PASSED (3.28s)
RESULTS - xen.XenBoot.test_boot: PASSED (0.00s)
RESULTS - zephyr_v8r64.ZephyrTests.test_helloworld: SKIPPED (0.00s)
RESULTS - zephyr_v8r64.ZephyrTests.test_philosophers: SKIPPED (0.00s)
RESULTS - zephyr_v8r64.ZephyrTests.test_synchronization: SKIPPED (0.00s)
SUMMARY:
core-image-minimal () - Ran 12 tests in 842.089s
core-image-minimal - OK - All required tests passed (successes=9, skipped=3, failures=0, errors=0)

The logs can be viewed at:

  • Testimage output: build/tmp_virtualization/work/fvp_baser_aemv8r64-poky-linux/core-image-minimal/1.0-r0/temp/log.do_testimage

  • Xen console output: build/tmp_virtualization/work/fvp_baser_aemv8r64-poky-linux/core-image-minimal/1.0-r0/testimage/xen_log

  • Zephyr console output: build/tmp_virtualization/work/fvp_baser_aemv8r64-poky-linux/core-image-minimal/1.0-r0/testimage/zephyr_v8r64_log

  • Linux console output: build/tmp_virtualization/work/fvp_baser_aemv8r64-poky-linux/core-image-minimal/1.0-r0/testimage/default_log

Reference

1

https://developer.arm.com/downloads/-/arm-ecosystem-fvps/eula

2

https://docs.yoctoproject.org/test-manual/intro.html