3. User Guide¶

The following instructions have been validated with Ubuntu 22.04, but for sure it will work with lower release.

3.1. Pre-requisite¶

We need to run some i386 executables, and we need to install some i386 libraries too.

sudo dpkg --add-architecture i386
sudo apt-get update
sudo apt-get install libc6:i386 libncurses5:i386 libstdc++6:i386
sudo apt-get install lib32z1-dev
sudo apt-get install zlib1g:i386

Various other packages are required:

sudo apt-get install pkg-config libgtk2.0-dev bridge-utils
sudo apt-get install unzip bc
sudo apt-get install elfutils u-boot-tools
sudo apt-get install device-tree-compiler
sudo apt-get install fdisk
sudo apt-get install libncurses-dev

The following packets are not mandatory, but they can be installed to prevent annoying warnings:

sudo apt-get install bison flex

3.2. Files and directroy organisation¶

SO3 root directory (main subdirs):

so3
├── usr
├── src
├── filesystem
├── target
├── u-boot
└── qemu

The SO3 tree is organized in two main parts: kernel and user space files. All kernel space related files are located in so3/ while the user space files resides in usr/.
The filesystem directory contains the virtual SD-card image which will be attached to the QEMU environment.
The target directory contains the set of .its files which are used by the U-boot bootloader.
The u-boot and qemu directories contain the bootloader and the emulator respectively.

3.3. Build of the environment¶

3.3.1. About the toolchain¶

We use the arm-none-eabi toolchain which has no dependencies on a libc.

The following package can be installed:

apt install gcc-arm-none-eabi

3.3.2. Quick setup & early test¶

The following commands is helpful to have quick up-and-running environment with SO3, i.e. a shell running on top of the kernel in the emulated virt32 environment.

3.3.3. Setting up QEMU¶

The QEMU emulator can be installed via apt for 32-bit and 64-bit versions, as follows:

apt-get install qemu-system-arm
apt-get install qemu-system-aarch64

3.3.4. Compiling U-boot¶

U-boot is used as initial bootloader. The kernel image, the device tree and its root filesystem will be embedded in a single ITB image file.

In u-boot/ directory:

cd u-boot
make virt32_defconfig
make -j8

3.3.5. Creating the virtual disk image¶

In filesystem/ directory, create a virtual disk image with the following script:

cd filesystem
./create_img.sh vexpress

This script will create two FAT32 partitions, but only the first one will be used currently (there is no support to mount the filesystem on the second partition).

3.3.6. Compiling the user space¶

The user space build system is based on cmake (CMakeList.txt files).

To build the user space applications, go to usr/ directory and simply do make:

cd usr
./build.sh

In order to support the configuration with an embedded ramfs, you also need to create a FAT-32 image which will contain the user apps. This is achieved with the following script:

cd rootfs
./create_ramfs.sh

The deployment of user applications into this ramfs will be done below during the deployment into the SD-card (option -u of the deploy.sh script at the root directory).

3.3.7. Compiling the kernel space¶

The kernel has to be compiled in *so3*/ after choosing a configuration:

cd so3
make virt32_ramfs_defconfig
make

In this example, we are working with an embedded ramfs which will be packed in the ITB image file.

3.3.8. Deployment into the SD-card¶

At this point, all necessary components have been built. Now comes the phase of deployment in the virtual disk. This is done by means of the deploy.sh script located at the root tree. Currently, you should only use option -b and -u to deploy the kernel, the device tree and the ramfs into the ITB file. This image file is then copied in the first partition of the SD-card.

./deploy.sh -bu

3.4. Starting SO3¶

Simply invoking the script st as following:

./st

and you should run into the shell…

Note

To quit QEMU, type Ctrl+x followed by a (not Ctrl+a).

3.5. SO3 Configuration and ITS files¶

This section describes the default configurations of the SO3 kernel which are present in *so3/configs/* and in target/

SO3 works with the following plaforms: virt32, virt64, rpi4, rpi4_64

ITS	DTS	Config	virt64	rpi4_64	avz	pv	vt	soo (linux)	rootfs	Validation
		virt32_defconfig
		virt64_defconfig	X						X
rpi4_64_avz_so3_pv.its	rpi4_64_avz_pv.dts	rpi4_64_pv_defconfig		X	X	X			X	27.09.23
rpi4_64_so3_standalone.its	rpi4_64.dts	rpi4_64_defconfig		X					X	26.09.23
virt64_avz_so3_pv.its	virt64.dts	virt64_pv_defconfig	X		X	X			X	26.09.23
rpi4_64_avz_so3_vt.its		rpi4_64_defconfig		X	X		X		X	27.09.23
(soo) virt64.its	virt64_avz_pv	virt64_pv_defconfig	X			X		X		07.10.23
(soo) rpi4_64.its	rpi4_64_avz_pv	virt64_pv_defconfig		X	X	X		X		08.10.23

To be completed

3.6. Deployment of a Hello World application¶

3.6.1. Using a ramfs configuration¶

All user applications reside in usr/src directory. Adding a C file requires to update the CMakeLists.txt file.

All binaries are produced in the usr/build directory by cmake. And all files which will be deployed by the deployment script are stored in usr/build/deploy.

Note

Currently, the cd command is not implemented in the shell of SO3. For this reason, all executables (and other files) are stored in the root directory, except the entries of dev/ used to access the drivers.

The deployment into the virtual SD-card is simply done with the deploy.sh script at the root dir as follows:

./deploy.sh -u

Note

This manner of deploying user applications requires to have a ramfs configuration. All user apps are actually transfered into the itb file which is deployed in the unique partition of the SD-card.

The next section shows how you should deploy with the MMC configuration.

3.6.2. Using a mmc configuration¶

If you intend to use the vexpress_mmc_defconfig configuration for example, you will need to deploy the user apps manually (the deploy.sh script will be extended very soon). The deployment can be achieved as follows (from the root dir):

cd filesystem
./mount.sh 1 vexpress
sudo cp -r ../usr/build/deploy/* .
./umount.sh

The 1 refers to the partition #1.

Warning

Do not forget that deploy.sh -b will erase the whole partition of the SD-card. You then need to re-deploy the user apps.

3.7. Installation and run with SO3 docker¶

It is also possible to start SO3 within a docker container. The Dockerfile is located at the root directory and two scripts drun and drunit (for interactive mode) are available to start the execution.

For example, building of a container named so3/vexpress can achieved like this:

The, starting the execution of the container: