Introduction

Docker is a tool which uses OS-level virtualization to provide complete compute environments called containers. Please refer to https://www.docker.com/ for more details on Docker.

This page presents how to use Docker to build Yocto recipes using a freely available container available at https://hub.docker.com/r/yoedistro/yoe-build.

By using the container to build the Yocto recipes, you do not have to deal with the various system requirements that the Yocto recipes may have, like the supported Linux distributions and the required packages and package versions.

This page shows how to install and use Docker on Ubuntu 20.04, but the usage will be similar on all Linux platforms.

Setting up Docker

To install docker on Ubuntu, run the following instructions:

sudo apt  install docker.io 
sudo usermod -aG docker $USER
sudo reboot

Refer to https://docs.docker.com/get-docker/ for more detais on installing Docker.

Configure Docker Proxy

If you are in a network that is connected to Internet through a proxy, you need to follow the instructions from https://docs.docker.com/config/daemon/systemd/#httphttps-proxy

1. Create the service folder:

sudo mkdir -p /etc/systemd/system/docker.service.d

2. Create /etc/systemd/system/docker.service.d/http-proxy.conf with the following contents:

[Service]
Environment="HTTP_PROXY=http://proxy.address.com:8080"
Environment="HTTPS_PROXY=http://proxy.address.com:8080"
Environment="NO_PROXY=localhost,127.0.0.1,docker-registry.example.com"

Replace http://proxy.address.com:8080 with the appropriate proxy information for your network.

3. Reload the daemon and restart docker:

sudo systemctl daemon-reload
sudo systemctl restart docker

4. Show the properties to make sure they are correct:

sudo systemctl show --property=Environment docker

Set up and build the Docker Image

Run the following command to download the Dockerfile:

wget https://rocketboards.org/foswiki/pub/Documentation/DockerYoctoBuild/Dockerfile

1. Specify proxies (if needed) into a file named "proxies" and add them to the Dockerfile:

cat << EOT > proxies
env ALL_PROXY=socks://proxy.address.com:8080
env FTP_PROXY=http://proxy.address.com:8080
env HTTPS_PROXY=http://proxy.address.com:8080
env HTTP_PROXY=http://proxy.address.com:8080
env NO_PROXY=localhost,127.0.0.0/8,::1
env all_proxy=socks://proxy.address.com:8080
env ftp_proxy=http://proxy.address.com:8080
env https_proxy=http://proxy.address.com:8080
env http_proxy=http://proxy.address.com:8080
env no_proxy=localhost,127.0.0.0/8,::1
RUN git config --global  http.proxy http://proxy.address.com:8080
RUN git config --global  https.proxy http://proxy.address.com:8080
EOT
sed '/Proxies/ r proxies' Dockerfile > dock; mv dock Dockerfile

Replace http://proxy.address.com:8080 with the appropriate proxy information for your network.

2. Build the image with a mirror of the current user (this will make things like debugging easier).

docker build  -t gsrd_image  --build-arg username=$(whoami)  .  

Note: This step only needs to be done once.

Set up the container

1. Choose the target board:

stratix10:

export BOARD=stratix10

axilex7:

 export BOARD=agilex7_dk_si_agf014ea

2. Under our current directory previously created by for example "Setting_up_Environment", export our current TOP_FOLDER and clone the latest yocto's git repository:

export TOP_FOLDER=$(pwd) 
git clone -b nanbield https://github.com/altera-opensource/gsrd_socfpga

3. Yocto may use some other directories as cache and other purposes, let's create them.

 mkdir -p $HOME/tasks/yocto/downloads
 mkdir -p $HOME/tasks/yocto/sstate

4. Create/run a container based on the "gsrd_image" docker image:

docker run -v $HOME/tasks/yocto/sstate:$HOME/tasks/yocto/sstate  \
-v $HOME/tasks/yocto/downloads:$HOME/tasks/yocto/downloads   \
-v $PWD:$TOP_FOLDER   \
-it --user=$UID --name ${BOARD}_container -e BOARD -e TOP_FOLDER -d -t gsrd_image

Note: You can create as many containers as you wish, each with a different name.

5. Add a custom .bashrc into our container to set up yocto's environment automatically:

docker exec -it --user root ${BOARD}_container bash -c 'cat << EOT > ~/.bashrc
cd $TOP_FOLDER/gsrd_socfpga/;  
. ./${BOARD}-gsrd-build.sh;
. ./poky/oe-init-build-env ${BOARD}-gsrd-rootfs/ 2>/dev/null ;
cd $TOP_FOLDER/gsrd_socfpga/;
EOT'

Build Yocto

1. Invoke the container and build the images by executing the following command:

Set up Yocto layers:

docker exec -it ${BOARD}_container bash -c ' . ~/.bashrc; build_setup;'

Build and package:

docker exec -it ${BOARD}_container bash -c ' . ~/.bashrc; bitbake_image;package'

Note: if the container isn't running for any reason execute:

docker start  ${BOARD}_container

The two most relevant files created in the gsrd_socfpga/${BOARD}-gsrd-images folder are:

File	Description
sdimage.tar.gz	SD Card Image
u-boot-${BOARD}-socdk-gsrd-atf/u-boot-spl-dtb.hex	U-Boot SPL Hex file

This is the list of all files created in the gsrd_socfpga/${BOARD}-gsrd-images folder:

• console-image-minimal-${BOARD}.jffs - for QSPI boot, not used in default Golden System Reference Design (GSRD) User Manuals
• console-image-minimal-${BOARD}.tar.gz
• console-image-minimal-${BOARD}.ubifs - for NAND boot, not enabled in default GHRD
• console-image-minimal-${BOARD}.wic.xz
• gsrd-console-image-${BOARD}.jffs2 - for QSPI boot, not used in default Golden System Reference Design (GSRD) User Manuals
• gsrd-console-image-${BOARD}.tar.gz
• gsrd-console-image-${BOARD}.ubifs - for NAND boot, not enabled in default GHRD
• gsrd-console-image-${BOARD}.wic
• Image
• kernel.itb
• sdimage.tar.gz
• sdimage.tar.gz.md5sum
• socfpga_${BOARD}_socdk.dtb
• socfpga_${BOARD}_socdk_nand.dtb
• socfpga_${BOARD}_socdk_nand-${BOARD}.dtb
• socfpga_${BOARD}_socdk-${BOARD}.dtb
• ${BOARD}_gsrd_ghrd
  • ghrd.core.rbf
  • nand.core.rbf - NAND not enabled in default GHRD, precompiled file from rocketboards
  • persona0.rbf
  • persona1.rbf
• u-boot-${BOARD}-socdk-gsrd-atf/
  • boot.scr.uimg
  • u-boot
  • u-boot.dtb
  • u-boot-dtb.bin
  • u-boot-dtb.img
  • u-boot.img
  • u-boot.itb
  • u-boot.map
  • u-boot-spl
  • u-boot-spl.bin
  • u-boot-spl.dtb
  • u-boot-spl-dtb.bin
  • u-boot-spl-dtb.hex
  • u-boot-spl.map
  • u-boot.txt

These files are also present in the host. To get more details on how to use them or more deeper documentation about yocto customization and other topics like GHRD please refer to:

Agilex7: https://www.rocketboards.org/foswiki/Documentation/AgilexSoCGSRD

Stratix10: https://rocketboards.org/foswiki/Documentation/Stratix10SoCGSRD

Using Docker

This section presents how to start a container, execute commands and stop the container.

Executing Yocto commands

It is possible to execute bitbake commands(like bitbake virtual/kernel -c menuconfig) in two different ways:

NonInteractive shell:

docker exec -it ${BOARD}_container bash -c ' . ~/.bashrc; bitbake virtual/kernel -c menuconfig'

Interactive shell:

Open the Docker shell:

docker exec -it ${BOARD}_container bash

Execute the bitbake commands within the container:

bitbake virtual/kernel -c menuconfig

Installing software inside the Yocto Container

If some extra software is required like for example vim then you have to execute the following command:

docker exec -u 0 -it ${BOARD}_container apt-get install vim

Any software you install will only apply for that specific container

Start Yocto Container

Container might be stopped for any reason and we won't be able to either copy or execute anything. if this is the case we have to start it again.

1.- Determine the container name/id if you don't don't know it:

 docker container ls -a 

2.- Start the container:

docker start <name/id> 

Stop Yocto Container

1. Determine the id of the running container:

docker ps

2. Stop the container:

docker stop <id>

3. Remove the container(only if you don't need it anymore):

docker rm <id>