TranslateProject/sources/tech/20160412 How to use the ZYBO Yocto BSP.md

Introduction

This section provides a quick guide to

• Build Yocto image with meta-xilinx provided by Digilent

Prepare build sources and configuration

This section provides the basic steps to setup build system and configurations

Prerequisites

• Internet access
• required tools
  • git
  • repo
• Vivado tools for JTAG boot
• SD card for SD Boot + SD Card reader for programing the SD card.
• Linux workstation - currently tested with 64bit Ubuntu 14.04.4

Install git

Ubuntu:

$ sudo apt-get install git-core

Install repo

Repo is a tool that makes it easier to work with Git in the context of Android. We use it to simplify the process of preparing yocto layers.

$ mkdir ~/bin
$ PATH=~/bin:$PATH
$ curl https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo
$ chmod a+x ~/bin/repo

repo command reference

Notes

• Ensure Yocto build is not over NFS/CIFD
• Only support jethro release at this point

Preparation

Fetch/clone the required layer repos and assume the layer repos are store in "~/tmp/layers" folder.

$ export branch=jethro
$ export layer_root=${HOME}/tmp/layers
$ mkdir -p $layer_root
$ cd $layer_root

Fetch required layers and hardware project with 'repo'

$ repo init -u https://github.com/Digilent/meta-manifest.git -b ${branch}
$ repo sync

Initialize build directory

This section provides the general step to create and config the build directory

Follow the commands to create a build directory "${HOME}/tmp/zybo-linux-bd-zynq7"

$ cd ${HOME}/tmp
$ export target_machine="zybo-linux-bd-zynq7"
$ . ${layer_root}/poky/oe-init-build-env ${target_machine}
$ tree .
    .
    └── conf
        ├── bblayers.conf
        ├── local.conf
        └── templateconf.cfg

oe-init-build-env generates some generic configuration files in the build/conf directory.

• The "bblayer.conf" file defines layers that are include in the build
• The "local.conf" file defines the configuration of the build.

Add required layers

Add meta-oe and meta-xilinx layer to the BBLAYERS variable

$ cd ${HOME}/tmp/${target_machine}
$ sed -i "/meta-yocto-bsp/a \  ${layer_root}/meta-openembedded/meta-oe \\\ " conf/bblayers.conf
$ sed -i "/meta-yocto-bsp/a \  ${layer_root}/meta-xilinx \\\ " conf/bblayers.conf

you can also use vim/nano/other editor to add the layer to conf/bblayers.conf

If you check the conf/bblayers.conf, you should see similar output to the follows:

    LCONF_VERSION = "6"
    BBPATH = "${TOPDIR}"
    BBFILES ?= ""

    BBLAYERS ?= " \
      ${HOME}/tmp/layers/poky/meta \
      ${HOME}/tmp/layers/poky/meta-yocto \
      ${HOME}/tmp/layers/poky/meta-yocto-bsp \
      ${HOME}/tmp/layers/meta-xilinx \
      ${HOME}/tmp/layers/meta-openembedded/meta-oe \
      "
    BBLAYERS_NON_REMOVABLE ?= " \
      ${HOME}/tmp/layers/poky/meta \
      ${HOME}/tmp/layers/poky/meta-yocto \
      "

Where the ${HOME} is the path to your home directory.

Customize the build configuration

The variables you need to customize:

• MACHINE

[MACHINE]: Defines the target build machine. In our case, it is zynq-hdmi_out-zynq7. Modify the conf/local.conf to correct MACHINE with the following commands.

$ sed -i "s/MACHINE ??= \"qemux86\"/MACHINE ?= \"${target_machine}\"/" conf/local.conf

or you can use text editor replacing the following

    MACHINE ?= "qemux86"

with

    MACHINE ?= "zybo-linux-bd-zynq7"

Optional variables you may want to customize:

• DL_DIR
• SSTATE_DIR
• TMPDIR
• PACKAGE_CLASSES

[DL_DIR]: Defines where the upstream source code tarballs are stored. This allows multiple builds without re-download the source code again.

[SSTATE_DIR]: Defines where to store the shared state files. It also allows multiple build share the same state files and speed up the build processes.

[TMPDIR]: Define where to store the build outputs. Not recommended to share with other builds.

[PACKAGE_CLASSES] Defines which packing formats to enable and used in the system.

Useful link to speed up the build.

Set up preferred kernel and u-boot

Since there are multiple u-boot/kernel recipes can be use for zynq-linux-bd-zynq7 machine. We will need to define the preferred provider by adding the following lines to conf/local.conf file

PREFERRED_PROVIDER_virtual/bootloader = "u-boot-digilent"
PREFERRED_PROVIDER_u-boot = "u-boot-digilent"
PREFERRED_PROVIDER_virtual/kernel = "linux-digilent"
PREFERRED_PROVIDER_virtual/boot-bin = "u-boot-digilent"

or

$ echo 'PREFERRED_PROVIDER_virtual/bootloader = "u-boot-digilent"' >> conf/local.conf
$ echo 'PREFERRED_PROVIDER_u-boot = "u-boot-digilent"' >> conf/local.conf
$ echo 'PREFERRED_PROVIDER_virtual/kernel = "linux-digilent"' >> conf/local.conf
$ echo 'PREFERRED_PROVIDER_virtual/boot-bin = "u-boot-digilent"' >> conf/local.conf

Note: currently supported kernel and u-boot recipe are as follows table:

recipe name	Description
linux-digilent	Stable kernel that has been tested - fixed commit id
linux-digilent-dev	base on latest commit of linux-digilent master branch
u-boot-digilent	Stable U-Boot that has been tested - fixed commit id
u-boot-digilent-dev	base on latest commit of u-boot-digilent master branch

Including additional pacakges

An example of adding mtd-utils to the image. Add the following line to conf/local.conf file

IMAGE_INSTALL_append = " mtd-utils"

Another example of adding kernel modules to the rootfs. Add the following line to conf/local.conf file

IMAGE_INSTALL_append = " kernel-modules"

Kernel configuration

Enter kernel menuconfig for the preferred kernel.

$ bitbake virtual/kernel -c menuconfig

or specific kernel receipt

$ bitbake linux-digilent-dev -c menuconfig

Build

This section provides the basic yocto build

Yocto default images types

Yocto poky distribution provides a set of reference image recipe to create your own distribution. You can find them under poky directory. In here, we only try to build core-imiage-minimal and core-imiage-sato

minimal image

A image provides a console based Linux OS. Build core-image-minimal run:

$ bitbake core-image-minimal

Intall alsa-utils to test the audio on the zybo-linux-bd-zynq7 machine (still issues, please refer to the known issue section for detail) by adding "alsa-utils" to IMAGE_INSTALL_append variable in the conf/local.conf file

IMAGE_INSTALL_append = " mtd-utils alsa-utils"

sato image

Image with Sato, a mobile environment and visual style for mobile devices. The image supports X11 with a Sato theme, Pimlico applications, and contains terminal, editor, and file manager. To build it run:

$ bitbake core-image-sato

You can also append xterm to the image by adding the "xterm" to IMAGE_INSTALL_append variable in conf/local.conf file. e.g.

IMAGE_INSTALL_append = " mtd-utils xterm"

build products

if you did not specify your own TMPDIR in local.conf, the default TMPDIR is under the build directory, in this case, it should ${HOME}/tmp/${target_machine}/tmp. Image stores at {HOME}/tmp/${target_machine}/tmp/deploy/images/zybo-linux-bd-zynq7. You can find a list of build images in the directory.

${IMG_TYPE} refers to the build image, for example, core-image-minimal.
${target_machine} refers to zybo-linux-bd-zynq7 in this example.

File	Description
boot.bin	Zynq Boot Image that only contents the U-Boot SPL
download.bit	FPGA bitstream if applicable
fit.itb	fitImage with kernel + dtb + rootfs
sdroot-fitImage	fitImage with modified dtb which use use SD root (second partition of SD)
uImage	U-Boot image format of kernel image
linux.bin	Linux kernel in binary format
modules-${target_machine}.tgz	Kernel modules
sdimg	SD card image that can be used to program SD with dd (Linux/MAC) or Win32DiskImage(Windows)
system.dtb	Device Tree Binary (DTB)
uImage-its-${target_machine}.its	its that used to create the fitImage
u-boot.bin	U-Boot binary file
u-boot-dtb.bin	U-Boot binary file with DTB
u-boot-dtb.img	U-Boot image format of u-boot-dtb.bin
u-boot-spl.bin	SPL Preloader Binary
${IMG_TYPE}-${target_machine}.cpio	Root filesystem in cpio archive format
${IMG_TYPE}-${target_machine}.cpio.gz.uboot	Root filesystem in U-Boot image format with compression
${IMG_TYPE}-${target_machine}.ext4	Root filesystem as ext4 image

Useful commands

Show list of package available in the yocto recipes

$ bitbake -s

or

$ bitbake-layers show-recipes

Removes all output files and shared state cache for a target. Becareful of using this command. This will force everything to be rebuild from scratch.

$ bitbake cleansstate

Removes all output files and shared state cache for a recipe

$ bitbake -c cleansstate <recipe name>

Build specific pkg, linux-digilent-dev as an example:

$ bitbake linux-digilent-dev

List out the task available for a recipe, linux-digilent-dev as an example:

$ bitbake -c listtasks linux-digilent-dev

Run specific task for a recipe, linux-digilent-dev as an example:

$ bitbake -c deploy linux-digilent-dev