.. _yocto-thud-setup: Setup ========== References ---------- A cheat sheet for bitbake: http://elinux.org/Bitbake_Cheat_Sheet STM32 MPU Wiki: https://wiki.st.com/stm32mpu/index.php Requirements -------------------- For Yocto a Linux Host Machine is needed. .. hint:: The supported distributions for `Thud` are listed at the `official Yocto documentation `_. If you're running such a machine, you should be fine, else we recommend to use *VirtualBox* to run a virtual machine. **Use an Ubuntu 16.04 or 18.04 instance**. Get a virtual machine image from `osboxes.org `_. See their `guide `_ to run the virtual machine image. An important consideration is the hard disk space required for the virtual appliance. **At least** 120 GiB is provided, 500 GiB would be better. Host Packages ------------- The Yocto framework requires dependencies that need to be available on the host system to run builds. To meet minimal version requirements you should have the following installed: * Git 1.8.3.1 or greater * tar 1.27 or greater * Python 3.4.0 or greater If your system does not meet these requirements see `this `_. To get the right packages for your build host, have a look at the official `Yocto project documentation `_. Essential Yocto Project host packages are: .. code-block:: text sudo apt-get install gawk wget git-core diffstat unzip texinfo gcc-multilib build-essential chrpath socat cpio python python3 python3-pip python3-pexpect xz-utils debianutils iputils-ping Setting up Git -------------- If not already done, setup git with the commands below: .. code-block:: text git config --global user.name "Your Name" git config --global user.email "Your Email" git config --list Setting up the Repo Utility --------------------------------- Repo is a tool built on top of Git that makes it easier to manage projects that contain multiple repositories, which do not need to be on the same server. Repo complements very well the layered nature of the Yocto Project, making it easier for users to add their own layers to the BSP. To install the "repo" utility, perform these steps: 1. Create a bin folder in the home directory: .. code-block:: text mkdir ~/bin (this step may not be needed if the bin folder already exists) curl https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo chmod a+x ~/bin/repo 2. Add the following line to the ``~/.bashrc`` file to ensure that the ``~/bin`` folder is in your PATH variable: .. code-block:: text export PATH=~/bin:$PATH BSP Checkout ------------------- The Repo tool checks out different layers for you, which are defined in our XML-manifest. Their source code can be found in ``layers`` directory, which contains the recipes and machine configurations used to build the image. +----------------+----------------+-------------------------------------+ | Branch | Kernel Version | Supported Machines | +================+================+=====================================+ | thud | 4.19.49 | QSMP DevelopmentKit, TXMP Series | +----------------+----------------+-------------------------------------+ The directory ``karo-stm-bsp`` is just an example and can be chosen free. .. code-block:: text mkdir karo-stm-bsp cd karo-stm-bsp repo init -u https://github.com/karo-electronics/karo-stm-bsp -b repo sync You can update the codebase to any time if you want to, which can be performed via the following command: .. code-block:: text repo sync .. note:: Syncing the repo might take some time. Build Configuration --------------------- The sources are now set up. We edited ST's script, ``envsetup.sh``, to fit the setup for our machines. To use the script, the machine name needs to be specified as well as the desired distro. The script sets up a directory and the configuration files for the specified machine and distro. It also adds our layer to the ``bblayers.conf`` file. To get a better understanding of the layers we applied our changes to, you could have a look at STM's documentation: https://wiki.st.com/stm32mpu/index.php/OpenSTLinux_distribution There are different configurations you can choose from. * DISTRO configurations: +---------------------+-------------------------------------------------------------------------------------------------------+ | ``DISTRO=`` | Description | +=====================+=======================================================================================================+ | openstlinux-eglfs | OpenSTLinux featuring eglfs - no X11, no Wayland | +---------------------+-------------------------------------------------------------------------------------------------------+ | openstlinux-weston | OpenSTLinux featuring Weston/Wayland | +---------------------+-------------------------------------------------------------------------------------------------------+ | openstlinux-x11 | OpenSTLinux featuring X11 | +---------------------+-------------------------------------------------------------------------------------------------------+ | nodistro | --- DEFAULT OPENEMBEDDED SETTING: DISTRO is not defined --- | +---------------------+-------------------------------------------------------------------------------------------------------+ * A list of supported MACHINE configurations: +---------------------+-------------------------------------------------------------------------------------------------------+ | ``MACHINE=`` | Description | +=====================+=======================================================================================================+ | qsmp-1570-qsbase1 | Machine configuration for the QSMP-1570-QSBASE1 Evaluation Kit | +---------------------+-------------------------------------------------------------------------------------------------------+ | txmp-1570 | Machine configuration for TXMP-1570 module on MB7 | +---------------------+-------------------------------------------------------------------------------------------------------+ | txmp-1530 | Machine configuration for TXMP-1530 module on MB7 | +---------------------+-------------------------------------------------------------------------------------------------------+ Use the command below to setup your build directory (specify the distro you want to use, the machine, and the build directory): .. code-block:: text DISTRO= MACHINE= source layers/meta-karo-stm/envsetup.sh After accepting the EULA, your current directory should have changed to the ```` you chose before. **Example:** .. code-block:: text DISTRO=openstlinux-weston MACHINE=qsmp-1570-qsbase1 source layers/meta-karo-stm/envsetup.sh build-qsmp-1570-qsbase1 U-Boot Version --------------- When building your image, four U-Boot versions will be built. +--------------------+------------------------------------------------------------------------------------+ | U-Boot Version | Description | +====================+====================================================================================+ | default | U-Boot with default environment to write inside the eMMC and boot your module. | +--------------------+------------------------------------------------------------------------------------+ | noenv | U-Boot with an empty environment. | +--------------------+------------------------------------------------------------------------------------+ | mfg | U-Boot with enabled fastboot protocol. (e.g. used when flashing your device) | +--------------------+------------------------------------------------------------------------------------+ | trusted | U-Boot with secure-boot enabled. | +--------------------+------------------------------------------------------------------------------------+ ARM® Trusted Firmware ----------------------------- Every image also builds the Trusted Firmware you will need to program and boot your board. Details on how the ARM® Trusted Firmware works you will find on: https://wiki.st.com/stm32mpu/index.php/TF-A_overview You can build the Trusted Firmware **with** or **without (default)** debug output. To set this, go to your ``conf/local.conf`` inside your build-directory and set the variable: .. code-block:: text TF_DEBUG = "1" Building an Image ==================== .. note:: Before starting a build, you should consider enabling the **SSTATE CACHE** to speedup the build process. See :ref:`Enabling Sstate Cache `. Here are the different images you can build [1]_: +-----------------------+----------------------------------------------------------------------------+ | Image | Description | +=======================+============================================================================+ | **Official Images** | +-----------------------+----------------------------------------------------------------------------+ | st-image-weston | OpenSTLinux weston image with basic Wayland support (if enabled in distro) | +-----------------------+----------------------------------------------------------------------------+ | **Supported images** | +-----------------------+----------------------------------------------------------------------------+ | st-image-core | OpenSTLinux core image | +-----------------------+----------------------------------------------------------------------------+ | **Example Images** | +-----------------------+----------------------------------------------------------------------------+ | st-example-image-qt | ST example of image based on QT framework | +-----------------------+----------------------------------------------------------------------------+ | st-example-image-x11 | ST example of image based on X11 | +-----------------------+----------------------------------------------------------------------------+ | st-example-image-xfce | ST example of image based on XFCE framework | +-----------------------+----------------------------------------------------------------------------+ | st-example-image-gtk | ST example of image based on GTK framework | +-----------------------+----------------------------------------------------------------------------+ Build the image with the following command inside your ````: .. prompt:: :prompts: $ bitbake .. hint:: For your headless boards you are fine with the ``st-image-core``. When you are using a **display** you can build the ``st-image-weston``. There you can also test the working GPU on the **XXmp-1570** variants. Image Deployment ================== After a build is complete, the created images and files are in the ``tmp-glibc/deploy/images/`` directory. Inside this directory is a folder named ``/flashlayouts``, containing *.tsv* files with partition layouts to flash your board. To flash your board with these files, proceed with :ref:`stm32-programmer-setup`. .. [1] From https://wiki.st.com/stm32mpu/index.php/OpenSTLinux_distribution.