Getting Started with MistySOM

MistySOM

Table Of Contents

• Getting Started with MistySOM
  • Introduction
    • Dependencies
    • Why build using Docker
    • Setting Up Host Computer
      • Ubuntu
      • Debian
      • Fedora
      • Arch
  • Container usage
    • Building and starting the container
    • Building the SDK
    • Installation of the SDK
    • Description of advanced container options
      • Building the BSP
      • Building the SDK
      • Output
      • Load Files to uSD card
      • Note to WSL users
      • Run time information
  • Develop example application
    • Hello World
    • Source Files
      • Build using the installed SDK
      • Build using Yocto
  • MistySOM Development Shell
  • Configure U-Boot
  • Connecting the hardware

Getting Started with MistySOM

Introduction

This guide gets you started and set up to develop software and/or firmware for MistySOM.

MistyWest provides an environment in a docker container to build the BSP¹ and an SDK² for both versions of MistySOM. The host computer requires docker to be configured, set up and running. The requirements for setting up the host computer are described in the section Setting Up Host Computer.

Dependencies

The following instructions have some dependencies, they include:

• A running Linux host
• Installed docker, running dockerd(docker daemon) and added the current user to the docker group to allow execution of docker commands

Why Build Using Docker

Each version of Yocto may have unique Host requirements (e.g., Ubuntu 16.04, Ubuntu 18.04). This can be cumbersome during development if you are working on multiple projects at the same time. Dedicated build machines seem unfeasible for multiple reasons, one of which is the cost of hardware. Virtual machines have definite shortcomings as they reserve and virtualize the host hardware and only provide a limited set of resources to the build process.

Docker is a great solution to this problem and provides:

• Lightweight and simple to share configuration and setup files (allows the creation of identical environments)
• A git revision controlled build environment
• Flexible allocation of RAM and hard drive memory
• Little CPU/IO overhead (build time is not impacted)
• Containers that start and stop within 2 seconds
• The ability to run multiple containers simultaneously
• A build environment that is kept isolated from the host machine

Docker's efficiency allows multiple containers to be run simultaneously without burdening the host OS.

Setting Up Host Computer

A Linux host with a running docker daemon is required for building the MistySOM BSP and SDK. Docker can be installed through a distribution’s packaging manager. Look up how to install docker and start dockerd for your respective distributions. Some links to find documentation about some common distributions are listed below:

Ubuntu

https://docs.docker.com/engine/install/ubuntu/

Debian

https://docs.docker.com/engine/install/debian/

Fedora

https://docs.docker.com/engine/install/fedora/

Arch

https://docs.docker.com/desktop/install/archlinux/

After docker has been installed and started, you can confirm the functionality of the installation with the command:

$ docker run hello-world

If you see:

Hello from Docker!

it means your installation is working correctly.

Container Usage

Building and Starting the Container

The first step is to clone the MistySOM/rzv2l or MistySOM/rzg2l repository from GitHub³ using the commands:

$ git clone git@github.com:MistySOM/rzg2l.git

or

$ git clone git@github.com:MistySOM/rzv2l.git

make sure you have the latest submodules:

$ git submodule update --init --recursive

then enter the Build/ directory.

$ cd Build/

and execute

$ ./build.sh

This will download the required files and build the container. To enable caching, create a directory to cache the source packages and object build files. This directory can be reused for every subsequent container run, so that the files do not need to be downloaded and built multiple times. In the example below, that directory is called /path/to/dir/

Important: the directory needs to have read and write access for uid 1000 and gid 1000
(hint: you can execute chmod -R 777 /path/to/dir to grant read, write & execute access for the directory to everybody on your system )

The owner's uid and gid settings can be confirmed with

$ ls -na /path/to/dir

Which should provide a line similar to the one below if the first user on a Linux system was used to create the directory:

drwxr-xr-x 1 1000 1000    0 Month  # HH:MM ./

If uid and gid do not indicate 1000 1000, please read about file permissions and attributes, see here.

Invoke the container and pass the cache directory with the command:

$ ./run.sh -c /path/to/dir

Upon completion of the build, the created image files are copied to the directory output/. This directory got created in the same path as where ./run.sh was invoked from. The rootfs, kernel, and device tree blob can now be copied to the destination uSD card. See section Output below.

Building the SDK

For development purposes, the SDK can be built with the above container. To do this, append the -s flag to the ./run.sh call:

$ ./run.sh -c /path/to/dir -s

This will automatically build the BSP and the SDK and copy the resulting files into the output/deploy/sdk/ directory.

Installation of the SDK

To install the SDK, execute it as user root on the host, e.g. with sudo as shown in the command below

(Note that /path/to/ is the location of your extracted MistySOMContainer archive)

$ sudo /path/to/out/deploy/sdk/poky-glibc-x86_64-core-image-<image_type>- aarch64-<board_name>-toolchain-3.1.5.sh

Upon which, paths can be set up by executing:

$ source /opt/poky/3.1.5/environment-setup-aatch64-poky-linux

This command has to be invoked every time before the SDK is used.

Description of Advanced Container Options

Building the BSP

• The script run.sh can be supplied with an external path to a directory with -c /path/to/dir or --cpath /path/to/dir where the Yocto downloads and the built object files can be cached (it requires about 10GB of empty space as of 10/20/2022) so that they do not need to be re-downloaded and re-built for every container run (just resubmit the same directory path). To allow the container to cache the data, the target directory needs to be writable by uid and gid 1000 (which is the default user id & group id of the first user on a Linux system, confirm with id -u, id -g & ln -n).
• When no download path is submitted, the container will build the binaries in offline mode, utilizing the data & files that have been downloaded during the container build.

Building the SDK

The run.sh script, in addition, can be started with the argument -s to trigger the compilation of the SDK after the initial BSP build has finished. The SDK must not be built by itself, hence the -s switch will automatically build the BSP, followed by the SDK.

Output

After the compilation finishes, the shell in the container will remain active. The output is available in

• images/BSP: /home/yocto/rzv_vlp_v3.0.0/out/deploy/images/[board]/
• SDK: /home/yocto/rzv_vlp_v3.0.0/out/deploy/sdk/

The files in the above images/ directory include:

and the resources can simply be copied to the host with docker cp NAME:SRC DST where NAME is the name of the running container that can be retrieved by running docker ps on the host.

In order to test the newly built BSP, files need to be loaded to a uSD card that MistySOM will boot from. Please follow the instructions on the Preparing uSD card page accordingly.

Run time information

• ./build.sh Builds the container image from the Dockerfile and downloads the required files from the web.
• ./run.sh Will start the container image, upon start, the exec.sh script is executed from within the container
• exec.sh invokes start.sh which sets up the Yocto build environment inside the container
• after the environment has been set up, exec.sh will invoke the bitbake⁴ commands required to build the binary files

Develop Example Application

Hello World

Source Files

Create a file called helloworld.c with the following contents:

#include <stdio.h>

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

Create a file called hello.bb⁵ that contains:

DESCRIPTION = "Simple helloworld application"
LICENSE = "MIT"
LIC_FILES_CHKSUM = "file://${COMMON_LICENSE_DIR}/MIT;md5=0835ade698e0bcf8506ecda2f7b4f302"

SRC_URI = "file://myhello.c"

S = "${WORKDIR}"

do_compile() {
	${CC} myhello.c ${LDFLAGS} -o myhello
}

do_install() {
	install -d ${D}${bindir}
	install -m 0755 myhello ${D}${bindir}
}

Build Using the Installed SDK

This step requires completion of the previous steps: Building the SDK and Installation of the SDK.

After the SDK has been installed, set the paths in your environment by executing:

$ sudo /path/to/out/deploy/sdk/poky-glibc-x86_64-core-image-<image_type>- aarch64-<board_name>-toolchain-3.1.5.sh

On your host computer.

$ $CC $CFLAGS $LDFLAGS helloworld.c -o helloworld

The resulting binary file helloworld can be copied and run on the MistySOM platform.

Build using Yocto

For testing this, the container should be started into a dev shell with:

./run.sh -n

or

./run.sh -c /path/to/dir -n

to launch it with the cache directory mounted.

Source the Build Environment

$ source poky/oe-init-build-env

and change to the directory where the layer is going to be located at

$ cd ..

Create Custom Layer

$ bitbake-layers create-layer --priority 3 meta-helloworld

Use the hello.c and hello.bb files from above to create the following directory structure within the meta-helloworld/ directory:

$ tree meta-helloworld
meta-helloworld
├── conf
│   └── layer.conf
├── COPYING.MIT
├── README
└── recipes-example
    ├── example
    │   └── example_0.1.bb
    └── myhello
        ├── files
        │   └── myhello.c
        └── myhello.bb

Add New Layer to Configuration

Execute the following command to add the line ${TOPDIR}/../meta-helloworld \ to the file conf/bblayers.conf (after the meta-renesas layer).

$ sed -i 's/renesas \\/&\n  ${TOPDIR}\/..\/meta-helloworld \\/' conf/bblayers.conf

Build MyHello

By invocation of

$ bitbake myhello

The myhello test application will be built utilizing the bitbake server.

With

$ find . -name myhello*

The output package can be investigated.

To add the output of this recipe to the output images, add the following to your conf/local.conf file in your Yocto build directory:

IMAGE_INSTALL_append = " myhello"

This will put the myhello app to the rootfs.

MistySOM Development Shell

When the container gets started with the -n argument like:

./run.sh -n

The container image gets started with the Yocto build environment setup. For administrative tasks, the primary user in the container image is called yocto with the password set to yocto.

Configure U-Boot

In order for MistySOM to boot with the files copied onto the uSD card above, the bootloader needs to be configured accordingly. For instructions on how to configure U-Boot, please follow the information on Configure U-Boot

Connecting the Hardware

To test the build generated by following the instructions above, the MistySOM hardware has to be connected and powered up. For development purposes, use the FTDI serial console cable⁶ and the UISB-C power cable⁷ Connect the FTDI able to connector J40 on MistyCarrier and connect the USB-C power cable to J1. The locations of the two connectors are highlighted in the following image:

Open a serial terminal: (instructions with tera Term for Windows or instructions with screen for Linux) and set the baudrate to 115200bps. If you connect the board successfully within the first few seconds of it booting, you should see boot messages followed by a login prompt:

smarc-rzg2l login:

If you don't see anything, press the Enter key and the above login prompt should appear. You can now log in with username root which will bring you to the shell from where you can invoke and execute commands.

Notes