The Yocto firmware generation has been tested on Ubuntu 24.04. You can either use your host machine’s tools, or use cqfd to build. More details are given in the next sections of this document.
We are using repo to synchronize the source code using a manifest (an XML
file) which describes all git repositories required to build a firmware. The
manifest file is hosted in a git repository named repo-manifest.
First initialize repo:
$ cd my_project_dir/ $ repo init -u <manifest_repo_url> $ repo sync
For instance, for Seapath yocto-bsp project:
$ cd my_project_dir/ $ repo init -u https://github.com/seapath/repo-manifest.git $ repo sync
|
Note
|
The initial build process takes approximately 4 to 5 hours on a current developer machine and will produce approximately 50GB of data. |
Before building you must put a ssh public in keys/ansible_public_ssh_key.pub. It will be used by Ansible to communicate with the machines. See for keys/README for more informations.
cqfd is a quick and convenient way to run commands in the current directory,
but within a pre-defined Docker container. Using cqfd allows you to avoid
installing anything else than Docker and repo on your development machine.
|
Note
|
We recommend using this method as it greatly simplifies the build configuration management process. |
Yocto provides a way to share build artifacts between multiple workspaces and developers through the DL_DIR and SSTATE_DIR environment variables. To use them with cqfd, add to your .bashrc:
export CQFD_EXTRA_RUN_ARGS="-v <your_dldir_path>:/mnt/dl -e DL_DIR=/mnt/dl -v <your_sstate_path>:/mnt/sstate -e SSTATE_DIR=/mnt/sstate"
You could also do this configuration in .cqfdrc with docker_run_args under build section:
docker_run_args='-v <your_dldir_path>:/mnt/dl -e DL_DIR=/mnt/dl -v <your_sstate_path>:/mnt/sstate -e SSTATE_DIR=/mnt/sstate'
See docker manual: Install docker
On Ubuntu 20.04 and greater:
$ sudo curl -o /usr/local/bin/repo https://storage.googleapis.com/git-repo-downloads/repo $ sudo chmod +x /usr/local/bin/repo $ sed 's|/usr/bin/env python|/usr/bin/env python3|' -i /usr/local/bin/repo
-
Install cqfd:
if necessary install make and pkg-config packages.
For instance, with Ubuntu/Debian distribution:
$ sudo apt-get install build-essential pkg-config
then
$ git clone https://github.com/savoirfairelinux/cqfd.git
$ cd cqfd
$ sudo make installThe project page on Github contains detailed information on usage and installation.
-
Make sure that docker does not require sudo
Please use the following commands to add your user account to the docker
group:
$ sudo groupadd docker
$ sudo usermod -aG docker $USERLog out and log back in, so that your group membership can be re-evaluated.
The first step with cqfd is to create the build container. For this, use the
cqfd init command:
$ cqfd init
|
Note
|
The step above is only required once, as once the container image has been
created on your machine, it will become persistent. Further calls to cqfd init
will do nothing, unless the container definition (.cqfd/docker/Dockerfile) has
changed in the source tree.
|
cqfd provides different flavors that allow to call build.sh with certain image, distro and machine parameters. To list the available flavors, run:
$ cqfd flavors
Here is a description of flavors:
-
all: all flavors
-
flasher: image to flash a SEAPATH disk
-
guest_efi: efi guest image (VM)
-
guest_efi_test: similar to guest_efi with additionnal test packages
-
guest_efi_dbg: similar to guest_efi with debug tools
-
host_efi: efi host image (including security, clustering and readonly features)
-
host_efi_dbg: similar to host_efi with debug tools
-
host_efi_test: similar to host_efi with additionnal test packages
-
host_efi_swu: efi host update image (SwUpdate)
-
observer_efi: efi observer image (used to observer the cluster)
-
observer_efi_swu: efi observer update image (SwUpdate)
To build on of this flavor, run:
$ cqfd -b <flavor>
Note:
* bash completion works with -b parameter
* detail command used per flavor is described in .cqfdrc file
This method relies on the manual installation of all the tools and dependencies required on the host machine.
The following packages need to be installed:
$ sudo apt-get update && sudo apt-get install -y ca-certificates gawk wget \ git-core diffstat unzip texinfo gcc-multilib build-essential chrpath \ socat cpio python3 python3-pip python3-pexpect xz-utils debianutils \ iputils-ping libsdl1.2-dev xterm repo lz4 libgmp-dev libmpc-dev
The build is started by running the following command:
$ ./build.sh -i seapath-host-efi-image -m boardname --distro distroname
You can also pass custom BitBake commands using the -- separator:
$ ./build.sh -i seapath-host-efi-image -m boardname --distro distroname -- bitbake -c clean package_name
Images can be produced for UEFI firmware only.
You can find below the Yocto images list:
-
Host images
-
seapath-host-efi-image: production image
-
seapath-host-efi-dbg-image: debug image
-
seapath-host-efi-test-image: production image with test tools
-
-
Guest images
-
seapath-guest-efi-image: QEMU-compatible virtual machine production image (UEFI only)
-
seapath-guest-efi-dbg-image: QEMU-compatible virtual machine debug image (UEFI only)
-
seapath-guest-efi-test-image: guest production image with test tools (UEFI only)
-
-
Hybrid images guest with test tool
-
Flasher images
-
seapath-flasher: USB drive or PXE flash image used to flash SEAPATH images on disk. during a PXE boot.
-
-
Observer images
-
seapath-observer-efi: production image for an observer (needed for clustering quorum establishment)
-
SEAPATH offer different distros for hosts depending on the use case. Here is a table describing the different distros available:
| DISTRO | container | virtualization | security | read-only | secure-boot | clustering |
|---|---|---|---|---|---|---|
seapath-host-sb |
Yes |
Yes |
Yes |
Yes |
Yes |
Yes |
seapath-host |
Yes |
Yes |
Yes |
Yes |
No |
Yes |
seapath-container-host |
Yes |
No |
Yes |
Yes |
No |
Yes |
seapath-standalone-host |
Yes |
Yes |
Yes |
Yes |
No |
No |
seapath-standalone-containers-host |
Yes |
No |
Yes |
Yes |
No |
No |
seapath-host-cluster-minimal |
Yes |
Yes |
No |
No |
No |
Yes |
seapath-host-minimal |
Yes |
Yes |
No |
No |
No |
No |
In addition to host distro we have specific distros:
-
seapath-flash: distro used for the flasher image
-
seapath-guest: distro used for guest images
-
seapath-observer: distro used for observer image
You can create an SDK matching your system’s configuration using with the following command:
$ ./build.sh -i seapath -m boardname --sdk
|
Note
|
prefix this command with cqfd run if using cqfd.
|
When the bitbake command completes, the toolchain installer will be in
tmp/deploy/sdk/ under your build directory.
-
The
seapath-flasherimage and the SEAPATH image to flash.
bmap-tool can be installed through your package manager, commonly under the
name bmap-tools or python3-bmaptools.
On Ubuntu/Debian/Mint:
$ sudo apt install bmap-tools
On Fedora:
$ sudo dnf install bmap-tools
On CentOS/Red Hat:
$ sudo yuml install bmap-tools
To be able to install Seapath firmware on machines you need to use a USB drive
running a specific application.
This application is available in seapath-installer directory.
To create the flash USB drive, on a Linux system, you can use the bmaptool
command.
For instance, if USB drive device is /dev/sdx:
$ sudo umount /dev/sdx* $ sudo bmaptool copy build/tmp/deploy/images/seapath-installer/seapath-flasher-seapath-installer.rootfs.wic.gz /dev/sdx
|
Tip
|
You can also use the lsblk command to list all block devices and their
mount points to identify the USB drive.
|
Copy the generated image in format wic or wic.gz on the USB drive flasher_data parition.
Boot the usb drive (usually requires to go through the BIOS’s boot menu). You
can login with a screen and a keyboard to the root user.
Use the flash script to write the firmware image on the
disk. flash takes two arguments:
-
--images: the path to the image to be flashed. The image partition are mounted on /media.
-
--disk: the disk to flash. Usualy /dev/sda.
For instance:
$ flash --image /media/seapath-host-efi-image.wic.gz --disk /dev/sda
|
Tip
|
You can also use the lsblk command to list all block devices and their
mount points to identify the disk.
|
To be able to install Seapath observer on Raspberry Pi, you need to use a SD card.
To create a bootable SD card for Raspberry Pi on a Linux system, you can use the bmaptool command.
For instance, if the SD card is /dev/sdx:
$ sudo umount /dev/sdx* $ sudo bmaptool copy --bmap build/tmp/deploy/images/seapath-observer-rpi/seapath-observer-rpi-image-seapath-observer-rpi.wic.bmap build/tmp/deploy/images/seapath-observer-rpi/seapath-observer-rpi-image-seapath-observer-rpi.wic.bz2 /dev/sdx
Note: The A/B updates does not work on Raspberry Pi for now. The cluster functionalities are not tested yet.
You can login on the hypervisor using a screen and keyboard. The default
credentials are emergadmin:emergadmin. Alternatively, if DHCP is available,
you can connect to the admin user using the SSH key configured through [the
keys folder](keys/README.adoc).
The next step to use Seapath is to setup the cluster with Ansible. Follow the instructions of the [Ansible playbook](https://github.com/seapath/ansible).
For general SEAPATH usage, follow the documentation on [SEAPATH Wiki](https://lf-energy.atlassian.net/wiki/spaces/SEAP/overview)
Hypervisors updates are enabled only for production efi images. They are performed with SwUpdate.
To build the SwUpdate image (.swu) run:
$ cqfd -b host_efi_swu
Refer to [SEAPATH wiki](https://lf-energy.atlassian.net/wiki/spaces/SEAP/pages/31820194/Update+and+Rollback) for information on how to use this update image.
A basic virtual machine qcow2 file can be created using the cqfd guest_efi flavor :
$ cqfd -b guest_efi
Refer to [SEAPATH wiki](https://lf-energy.atlassian.net/wiki/spaces/SEAP/pages/31818833/How+to+manage+VM+in+SEAPATH) for information on how to deploy the VM.
This documentation uses the AsciiDoc documentation generator. It is a convenient format that allows using plain-text formatted writing that can later be converted to various output formats such as HTML and PDF.
In order to generate an HTML version of this documentation, use the following command (the asciidoc package will need to be installed in your Linux distribution):
$ asciidoc README.adoc
This will result in a README.html file being generated in the current directory.
If you prefer a PDF version of the documentation instead, use the following command (the dblatex package will need to be installed on your Linux distribution):
$ asciidoctor-pdf README.adoc