Targets
QEMU setup
This document describes how to run TRS for the QEMU target. It is assumed that
you have completed the procedures outlined on the Initial setup page and
at least built the firmware for the tsqemuarm64-secureboot
target and the
trs
image. If not, begin there before proceeding.
Run
After the build is complete, you will be able to run it on your host system using QEMU.
$ make run
U-Boot is already set to boot the current kernel, initramfs, and rootfs upon initial startup.
Hint
To quit QEMU, press Ctrl-A x
(alternatively kill the qemu-system-aarch64 process)
If everything goes as planned, you will be greeted with a login message and a
login prompt. The login name is ewaol
as depicted below.
ledge-secure-qemuarm64 login: ewaol
ewaol@ledge-secure-qemuarm64:~$
Test
Once the build has been completed, you can run automatic tests with QEMU. These
boot QEMU using the compiled images and run test commands via SSH on the running
system. While the QEMU image is running, SSH access to it works via localhost IP
address 127.0.0.1
and TCP port 2222
. TEST_SUITE
variable in
trs-image.bb
recipe define which tests are executed.
$ cd <workspace root>
$ make test
See Yocto runtime testing documentation for details about the test environment and instructions for writing new tests.
Baremetal
This section will explain how to run TRS on hardware. There are primarily two steps that must be taken. We should a) flash the device firmware to a suitable medium and b) prepare a USB disk with the operating system.
Flashing the firmware
The firmware of a device is unique to that device. As a result, each supported device has its own set of tools and requirements to follow when writing the firmware. Device specific flashing instructions for TRS supported devices can be found at the Installing firmware page.
Warning
If the firmware is to be flashed on an SD card, the SD card should be found
under /dev/sdX
, where X is a letter associated to the card as recognized
by the host system (ex. /dev/sda
or /dev/sdb
).
Flashing the OS and rootfs
TRS builds an OS and a root filesystem that are compatible with all devices, as opposed to the device firmware that is device-specific. Therefore, it is sufficient to write a “wic-file” to a device (eMMC or SD card) in order to get the OS image and root filesystem onto TRS supported devices. In TRS, it’s the image named as “trs-image-trs-qemuarm64.wic”, that should be used. Although the wic-file name contains QEMU, it is the correct one and should be used for all devices.
$ sudo dd if=build/tmp_trs-qemuarm64/deploy/images/trs-qemuarm64/trs-image-trs-qemuarm64.wic \
of=/dev/sdX bs=1M status=progress
$ sync
Boot TRS
Plug-in the USB stick, SD-cards and reset the device. If the USB stick or SD-cards is detected, TRS will boot automatically.
Hint
Prefer USB 3.0+ ports always. If you are experiencing difficulties booting TRS, interrupt the U-Boot boot sequence and verify that your disk is identified.
=> usb start
=> usb storage
Device 0: Vendor: SanDisk Rev: 1.00 Prod: Cruzer Blade
Type: Removable Hard Disk
Capacity: 29340.0 MB = 28.6 GB (60088320 x 512)
Docker
This installation method has been created to aid developers in quickly setting up an initial TRS development environment. By leveraging the scripts and Dockerfile available in the trs repository, with just a few steps you can have a TRS-development environment running in a docker container. The benefits of using a container for your development environment include quickly reproducing your environment, speed of setup, all devs in a similar environment, can be customized/extended to meet your needs, usable across different host platforms, and more.
Container Configuration
This section provides an overview of how this container is set up.
Referring to the diagram above:
The username is
dev
.When logging into the container, it defaults into the pre-determined
$HOME/trs-workspace
directory.Under
$HOME/trs-workspace
is the./build
directory that has a softlink to the$HOME/yocto_cache/
directories.This docker configuration provides three shared directories.
The first,
$HOME/trs_reference_repo
on the Host is shared with$HOME/trs-reference-repo
in the container. This allows a user to keep it updated from the host side and potentially be shared by multiple containers.The second and third directories are tied to the creation of a Yocto build cache, also to reduce build times. These default to
$HOME/yocto_cache
on the host and container. Two subdirectories are created under$HOME/yocto_cache
. These are$HOME/yocto_cache/sstate-cache
and$HOME/yocto_cache/downloads
The default directories/shares described above may of course all be customized by modifying the Dockerfile and scripts, but note that the naming must be assured to be consistent in all the files.
Tested Environments
The instructions/scripts in this section have been verified against Ubuntu 22.04 desktop machine and a share server environment also based on Ubuntu 20.04.
Host Prerequisites
Assure that Docker has been installed on your Host development machine
$: docker --version;
Docker version 20.10.19, build d85ef84;
Note
These instructions assume the user name is dev
.
Installation instructions
Since there are instructions for both the Host running Docker and the Container that will have the Ubuntu 20.04 TRS development environment set up, the following sections will delineate the difference by using “Host” or “Container” in the header. That way a user will know where the commands are intended to run.
1. Clone the TRS repository (Host)
Cloning the repo to be able to easily grab the scripts.
$ cd ~
$ mkdir trs-repo
$ cd trs-repo
$ git clone https://gitlab.com/Linaro/trusted-reference-stack/trs.git
Optionally check that the Dockerfile and scripts are present:
$ ls ~/trs-repo/trs/scripts/docker-scripts
Dockerfile run-trs.sh trs-install.sh
2. Build Docker Image (Host)
Create a docker image, named trs
.
$ cd ~/trs-repo/trs/scripts/docker-scripts
$ docker build -t trs .
Note
The above defaults to a UID/GID
of 1000/1000
; typical of an Ubuntu
Desktop. If the host has a different UID/GID
and it’s desired for the
container to have the same, use the following command instead of the one
above:
$ cd ~/trs-repo/trs/scripts/docker-scripts
$ docker build --build-arg USER_UID=$(id -u) --build-arg USER_GID=$(id -g) -t trs .
Hint
During a docker build, it’s not uncommon to see warnings such as the following that can be ignored, for example:
WARNING: apt does not have a stable CLI interface. Use with caution in
scripts.
Optionally, after completion of the docker build, you can confirm that the images are there and look OK. Assuming you had no other docker images, you should see something similar to the following:
$ docker images
REPOSITORY TAG IMAGE ID CREATED SIZE
trs latest 2a10a95eacd2 10 seconds ago 336MB
ubuntu 22.04 a8780b506fa4 4 weeks ago 77.8MB
3. Download and sync the TRS source using Repo tool (Host)
As described above, the Host and Container share the TRS repo in a shared directory. This section sets up this share TRS repo with the following commands.
$ cd ~
$ mkdir trs_reference_repo
$ cd trs_reference_repo
$ repo init -u https://gitlab.com/Linaro/trusted-reference-stack/trs-manifest.git -m default.xml
$ repo sync
With all the above steps completed, we’re now ready to launch the TRS container!
Warning
The location above is important as this is a shared folder between the Host and the Container. If the user chooses to change this location, the scripts/Dockerfile must be updated to align.
4. Create and enter the Container (Host)
The following commands will launch the container using the Dockerfile built in the earlier steps
$ cd ~/trs-repo/trs/scripts/docker-scripts
$ docker build -t trs .
$ ./run-trs.sh
dev@2d0b8419dac3:~/trs-workspace$
A new prompt will be shown in your terminal similar to the above and you’re now working in the docker container!
Optionally, from the Container, some quick checks can be executed to assure
that the container is set up right. This includes assuring all the shares have
permissions set correctly, and that the build directory is linked to the
yocto_cache
directory using a soft link.
dev@92fae72fafee:~/trs-workspace$ ls -l
total 8
drwxr-xr-x 1 dev dev 4096 Jan 27 21:22 build
-rwxrwxr-x 1 dev dev 1936 Jan 27 20:41 trs-install.sh
dev@92fae72fafee:
dev@2d0b8419dac3:~/trs-workspace$ ls -l build
total 0
lrwxrwxrwx 1 dev dev 31 Jan 27 21:22 downloads -> /home/dev/yocto_cache/downloads
lrwxrwxrwx 1 dev dev 34 Jan 27 21:22 sstate-cache -> /home/dev/yocto_cache/sstate-caches
dev@92fae72fafee:
dev@2d0b8419dac3:~/trs-workspace$ ls -l ~
total 16
drwxrwxr-x 17 dev dev 4096 Jan 19 23:26 trs-reference-repo
drwxr-xr-x 1 dev dev 4096 Jan 27 21:27 trs-workspace
drwxr-xr-x 1 root root 4096 Jan 27 21:21 yocto_cache
dev@92fae72fafee:~/trs-workspace$ ls ~/yocto_cache -l
total 80
drwxrwxr-x 4 dev dev 73728 Jan 27 22:05 downloads
drwxrwxr-x 259 dev dev 4096 Jan 27 21:28 sstate-cache
dev@2d0b8419dac3:~/trs-workspace$
dev@92fae72fafee:~/trs-workspace$ ping google.com
PING google.com (142.250.188.238) 56(84) bytes of data.
64 bytes from lax31s15-in-f14.1e100.net (142.250.188.238): icmp_seq=1 ttl=116 time=31.7 ms
64 bytes from lax31s15-in-f14.1e100.net (142.250.188.238): icmp_seq=2 ttl=116 time=29.2 ms
64 bytes from lax31s15-in-f14.1e100.net (142.250.188.238): icmp_seq=3 ttl=116 time=26.4 ms
^C
--- google.com ping statistics ---
3 packets transmitted, 3 received, 0% packet loss, time 2001ms
rtt min/avg/max/mdev = 26.419/29.119/31.708/2.160 ms
dev@92fae72fafee:~/trs-workspace$ ^C
dev@92fae72fafee:~/trs-workspace$
If the user, group and shares all look good and a ping verified we have connectivity to the internet, then we’re ready to move on to the final step, which is performing a TRS build!
5. Build TRS (Container)
To verify everything is correct, perform a build by executing the
./trs-install.sh -h -r
command. Be sure to include the -h -r
options
when kicking off the build script for the build to work correctly.
dev@92fae72fafee:~/trs-workspace$ ./trs-install.sh -h -r
Using Yocto cache from host
Using reference from host
Downloading Repo source from https://gerrit.googlesource.com/git-repo
repo: Updating release signing keys to keyset ver 2.3
warning: gpg (GnuPG) is not available.
warning: Installing it is strongly encouraged.
repo has been initialized in /home/dev/trs-workspace
Fetching: 71% (10/14) Linaro/trusted-reference-stack/trs.git
...
Note
This build currently requires several hours to complete. There will be a number of warnings during the build, but this is OK. If completes successfully, then you’ll see a message prior to returning to the prompt similar to the following:
Summary: There were 4 WARNING messages.
Build succeeded, see output in build/tmp_trs-qemuarm64/deploy directories.
dev@92fae72fafee:~/trs-workspace$
Once the build succeeds, the user can perform a final verification step, which is to execute the steps in the QEMU setup section of this document.