L-876e.A1 phyCORE-STM32MP1 BSP Manual

Table of Contents

L-876e.A1 phyCORE-STM32MP1 BSP Manual
Document TitleL-876e.A1 phyCORE-STM32MP1 BSP Manual
Document TypeBSP Manual
Article NumberL876e.A1
Release Date02.03.2021
Is Branch ofL-876e.Ax phyCORE-STM32MP1 BSP Manual Head

Compatible BSP'SBSP Release TypeBSP Release DateBSP Status
PD20.1.0Major Release18.09.2020Released
PD21.1.0Major Release02.03.2021Released

Yocto Introduction

Our STM32MP1 BSP is based on OpenSTLinux Distribution: https://wiki.st.com/stm32mpu/wiki/OpenSTLinux_distribution

  • To adapt the OpenSTLinux Distribution layer ("meta-st-openstlinux") to our board, we use our own yocto layer, "meta-st-openstlinux-phytec".  This layer extends the functionality of the meta-st-openstlinux distribution layer to enable features provided by our boards. With this layer we also provide custom distros and images based on the one from OpenSTlinux.
  • To adapt the STMicroelectronics BSP layer ("meta-st-stm32mp") to our board, we use our own yocto layer, "meta-phytec/dynamic-layer/stm-st-stm32mp". This layer adapts the bootloaders (Trusted firmware + u-boot) and the Linux kernel to our Board.

You can find those layers in our git server below:

https://git.phytec.de/meta-st-openstlinux-phytec/
https://git.phytec.de/meta-phytec/tree/dynamic-layers/stm-st-stm32mp

Note

The meta-yogurt layer (PHYTEC custom distro layer) is not used with the OpenSTLinux BSP.

PHYTEC Documentation

PHYTEC will provide a variety of hardware and software documentation for all of our products. This includes any or all of the following:

  • Quickstart Guide: A short guide on how to set up and boot a phyCORE board along with brief information on building a BSP, the device tree, and accessing peripherals.
  • Hardware Manual:  A detailed description of the System on Module and accompanying carrier board. 
  • Yocto Guide:  A comprehensive guide for the Yocto version the phyCORE uses. This guide contains an overview of Yocto; introducing, installing, and customizing the PHYTEC BSP; how to work with programs like Poky and Bitbake; and much more.
  • BSP Manual:  A manual specific to the BSP version of the phyCORE. Information such as how to build the BSP, booting, updating software, device tree, and accessing peripherals can be found here.
  • Development Environment Guide:  This guide shows how to work with the Virtual Machine (VM) Host PHYTEC has developed and prepared to run various Development Environments. There are detailed step-by-step instructions for Eclipse and Qt Creator, which are included in the VM. There are instructions for running demo projects for these programs on a phyCORE product as well. Information on how to build a Linux host PC yourself is also a part of this guide.
  • Pin Muxing Table:  phyCORE SOMs have an accompanying pin table (in Excel format). This table will show the complete default signal path, from processor to carrier board. The default device tree muxing option will also be included. This gives a developer all the information needed in one location to make muxing changes and design options when developing a specialized carrier board or adapting a PHYTEC phyCORE SOM to an application. 

On top of these standard manuals and guides, PHYTEC will also provide Product Change Notifications, Application Notes, and Technical Notes. These will be done on a case-by-case basis. Most of the documentation can be found on the applicable download page of our products.

Warning

Be aware that not all of the above documentation will be available for the phyBOARD-Sargas. To find all PHYTEC documentation, go to https://www.phytec.de/produkt/system-on-modules/phycore-stm32mp1-download/ or https://www.phytec.eu/product-eu/system-on-modules/phycore-stm32mp1-download/

BSP Introduction

Supported Hardware

This BSP supports the phyCORE-STM32MP1 SOM with phyBOARD-Sargas SBC. Visit our web page at:
https://www.phytec.de/produkt/system-on-modules/phycore-stm32mp1-download/
or
https://www.phytec.eu/product-eu/system-on-modules/phycore-stm32mp1-download/

Click the corresponding BSP release and look for the article number of your module in the column "Article Number". Finally, look for the correct machine name in the corresponding cell under "Machine Name".

Software and Software Requirements

  • A modern Linux operating host system either natively or via a Virtual Machine.
  • Ubuntu 20.04 LTS or 18.04 LTS (64-bit).
  • VMWare Player and VirtualBox are possible solutions if you want to use a Virtual Machine.
  • Virtual Machine (VM) configured for this BSP build environment can be downloaded at https://www.phytec.de/produkt/system-on-modules/phycore-stm32mp15x-download/#vm
  • Root access to your Linux host PC. Some commands in this guide will not work if you do not have sudo access (e.g. package installation, formatting an SD card).
  • At least 8GB of RAM (16GB or more is recommended).
  • At least 100 GB of free space on the build partition of the host PC.
  • An SD card reader operational under Linux.
  • An active internet connection.

For more details concerning Linux PC configuration, please refer to https://wiki.st.com/stm32mpu/wiki/PC_prerequisites

Getting Started with the Included SD Card

This section is designed to get the board up and running with the SD Card included in the kit, which has been prepared with pre-built images.

Booting from the SD Card

This section describes how to boot the phyBOARD-Sargas with the pre-built images on the included SD card.

  • Insert the micro SD card into the SD card slot of the board.
  • Check that the S7 DIP switch is in the default position (boot from SD):

  • Plug the USB cable into the USB debug on the board (X13) and your host PC. You should see two new devices appear: /dev/ttyUSB0 and /devttyUSB1. A Linux terminal will be accessible on /dev/ttyUSB0
  • Start your favorite terminal software (e.g. Minicom or Tera Term) on your host PC and configure it for 115200 baud, 8 data bits, no parity, and 1 stop bit (8n1) with no handshake.
  • Example to launch minicom on /dev/ttyUSB0:
host:~$sudo minicom -D /dev/ttyUSB0 
  • Connect the power supply to the power connector.

The RGB LED (D11) will begin blinking BLUE as the board begins booting into Linux. The console output can be viewed in your terminal window. If everything was done correctly, the login prompt will be shown at the end of the booting process:

ST OpenSTLinux - Weston - (A Yocto Project Based Distro) 3.1-snapshot phycore-stm32mp1-3 ttySTM0
phycore-stm32mp1-3 login: root (automatic login)
root@phycore-stm32mp1-3:~#

Log in is done automatically as root (no password is required).

Building the BSP

This section will guide you through the general build process of the STM32MP1 BSP using our phyLinux script (based on repo tool) and the Yocto environment.

Basic Set-Up

There are a few important steps that have to be done before the main build process.

Finding the Right Software Platform

The STM32MP1 BSP is a unified BSP, which means in the future it supports a set of different PHYTEC carrier boards (CB) with different Systems on Module (SOMs). These hardware sets are called MACHINE.

If you need to figure out the corresponding machine name of your board, go to https://www.phytec.de/produkt/system-on-modules/phycore-stm32mp15x-download/#software and click on the corresponding BSP release. You can also refer 

Choose a BSP OpenSTLinux Distribution

The phyCORE-STM32MP1 BSP is based on OpenSTLinux which offers different distributions (DISTRO). When building the BSP, you have to choose one of them. The choice will depend on the features you want to get on your final application.

The available DISTROs are:

DISTRODescription
openstlinux-eglfs

OpenSTLinux featuring EGLFS (no X11, no Wayland).

EGLFS is a platform plugin for running Qt5 applications on top of EGL and OpenGL ES 2.0, without an actual windowing system like X11 or Wayland.

openstlinux-westonOpenSTLinux featuring Weston/Wayland display server protocol.
openstlinux-tiny

Distribution customized by PHYTEC for SOM equipped with small Flash memory size (128MB). It is based on OpenSTLinux distro with the following differences :

  • no X11, no Wayland, no eglfs
  • no uninative support
  • SysVinit instead of systemd
  • following features removed: alsa, wifi, nfs, bluetooth, bluez5

NOTE: currently, only BSP images proposed as an example only can be built with this DISTRO (no ST/PHYTEC support on this)

For more details on the OpenSTLinux distributions, please refer to https://wiki.st.com/stm32mpu/wiki/OpenSTLinux_distribution#Distros

For our examples in this document, we will use: <DISTRO>= openstlinux-weston

Choose a BSP Image to be Build and Deployed

Once you have chosen a DISTRO, you have to choose a BSP Image to build and deploy on target. The available images depend on the DISTRO that has been chosen before.

BSP ImageDescriptionRequired DISTRO MACHINE minimal FLASH memory size

st-image-weston

OpenSTLinux Weston image with basic Wayland support - OpenSTLinux official image

It comes with a graphical application demo that will show up on a Screen  (if one display is connected to the carrier board). This is the image that is delivered by default with our standard evaluation kit.

The Graphical demo is called "GTK demo launcher" and allow you to add additional custom applications that can be launched from this interface. More information on the available demo and how to add your own application can be found at this link:

https://wiki.st.com/stm32mpu/wiki/GTK_demo_launcher

openstlinux-weston

>= 1GB

st-image-core

OpenSTLinux core image (without Weston or any GUI framework) - OpenSTLinux supported image

any openstlinux DISTRO

(except openstlinux-tiny)

>= 512MB

st-example-image-qt (sample image)

OpenSTLinux example of image based on QT framework over EGLFS - proposed as an example only

openstlinux-eglfs

>= 1GB

st-example-image-qt-wayland (sample image)OpenSTLinux example of image based on QT framework over  Weston/Wayland - proposed as an example onlyopenstlinux-weston>= 1GB
st-image-core-minimal

PHYTEC OpenSTLinux core minimal image (PHYTEC custom image)  - proposed as an example only

It is based on st-image-core, but without :

  • framework for display and multimedia
  • framework tools base components (core, kernel, network, audio, ui, python2, python3)
  • package management system
openstlinux-tiny>= 128MB
st-example-image-qt-minimal (sample image)

PHYTEC OpenSTLinux example of image based on Qt minimal framework (PHYTEC custom image)  - proposed as an example only
It is based on st-example-image-qt with fewer features and QT packages to decrease the image size.

openstlinux-eglfs>= 512MB

For more information regarding OpenSTLinux images and how to create your own image, please refer to: https://wiki.st.com/stm32mpu/wiki/How_to_create_your_own_image

For our examples in this document we will use: <BSP_IMAGE>=st-image-weston

Get and Initialize the BSP Environment

  • Create a fresh project directory:
host:~$ mkdir ~/PHYTEC_STM32MP1_BSP
  • Get and Initialize the BSP yocto environment with our phyLinux script:
host:~$ cd ~/PHYTEC_STM32MP1_BSP
host:~/PHYTEC_STM32MP1_BSP$ wget https://download.phytec.de/Software/Linux/Yocto/Tools/phyLinux
host:~/PHYTEC_STM32MP1_BSP$ chmod +x phyLinux
host:~/PHYTEC_STM32MP1_BSP$ ./phyLinux init
  • On the first initialization, the phyLinux script will ask you to install the Repo tool in your /usr/local/bin directory.
  • During the execution of the init command, you first need to choose the  processor platform (SoC):
***************************************************
* Please choose one of the available SoC Platforms:
*
*   1: am335x
*   2: imx6
*   3: imx6ul
*   4: imx8
*   5: imx8m
*   6: imx8mm
*   7: nightly
*   8: rk3288
*   9: stm32mp1
*   10: topic
*
$ 
  • Enter the choice number corresponding to stm32mp1 (9).
  • Then choose the PHYTEC's BSP release number:
***************************************************
* Please choose one of the available Releases:
*
*   1: PD-BSP-Yocto-OpenSTLinux-STM32MP1-ALPHA1
*   2: PD-BSP-Yocto-OpenSTLinux-STM32MP1-ALPHA2
*   3: PD-BSP-Yocto-OpenSTLinux-STM32MP1-PD20.1.0
*   4: PD-BSP-Yocto-OpenSTLinux-STM32MP1-PD21.1.0
*
$ 
  • The repo initialization will start

Tip

"ERROR 404" may appear during "repo init" command without any impact on the process.

  • Once the repo initialization is finished, a popup will appear to will ask you to choose the DISTRO:

Press 'space' to select and press 'enter' to validate.

  • Once the DISTRO is chosen, another popup will appear and will ask you to choose the MACHINE among all available Phytec platforms:

You must select one of the supported "phycore-stm32mp1-x" machines (PHYTEC phyCORE-STM32MP1).

  • The STM32MP1 BSP depends on packages and firmware which are covered by a software license agreement (SLA). You will be asked to read and to accept this EULA:

Note

It is mandatory to accept this EULA to be able to use the internal STM32MP1 GPU.

  • After accepting the EULA, the OpenEmbedded Environment will be the setup and you should now be in a sub-folder named '~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-<MACHINE>':
[HOST DISTRIB check]
Linux Distrib: Ubuntu
Linux Release: 18.04

Required packages for Linux Distrib:
build-essential chrpath cpio debianutils diffstat gawk gcc-multilib git iputils-ping libegl1-mesa libsdl1.2-dev libssl-dev pylint3 python3 python3-git python3-jinja2 python3-pexpect python3-pip socat texinfo unzip wget xterm xz-utils

Check OK: all required packages are installed on host.

[DISTRO configuration]
Selected DISTRO: openstlinux-weston

[MACHINE configuration]
Selected MACHINE: phycore-stm32mp1-3

[source layers/openembedded-core/oe-init-build-env][from nothing]

[EULA configuration]

[Configure *.conf files]
[INFO] No 'site.conf.sample' file available at ~/PHYTEC_STM32MP1_BSP/layers/meta-st/scripts. Create default one...

===========================================================================
Configuration files have been created for the following configuration:

DISTRO : openstlinux-weston
DISTRO_CODENAME : dunfell
MACHINE : phycore-stm32mp1-3
BB_NUMBER_THREADS : <no-custom-config-set>
PARALLEL_MAKE : <no-custom-config-set>

BUILDDIR : build-openstlinuxweston-phycore-stm32mp1-3
DOWNLOAD_DIR : <disable>
SSTATE_DIR : <disable>

SOURCE_MIRROR_URL : <no-custom-config-set>
SSTATE_MIRRORS : <disable>

WITH_EULA_ACCEPTED: YES

===========================================================================

Available images for OpenSTLinux layers are:

- Official OpenSTLinux images:
st-image-weston - OpenSTLinux weston image with basic Wayland support (if enable in distro)

- Other OpenSTLinux images:
- Supported images:
st-image-core - OpenSTLinux core image


You can now run 'bitbake <image>'

host:~/PHYTEC_STM32MP1_BSP/build-openstlinuxweston-phycore-stm32mp1-3$

OpenEmbedded Environment Setup

Note

The OpenSTLinuxOpenEmbedded environment setup script is sourced automatically when using the phyLinux tool (at the end of the phyLinux init command execution). But the environment is valid only for the current terminal session.

This section describes the Environment Setup procedure when using a new terminal session.

 The environment setup must be executed once per new terminal session, with the following command:

host:~/PHYTEC_STM32MP1_BSP$ source layers/meta-st-openstlinux-phytec/scripts/openstlinux-init-phytec.sh

A popup will appear to ask you to select one of the available Build directories:

You can choose to use one of the existing build environment (previously created) or you can choose to create a new build environment selecting "NEW" (in case you want to use a new MACHINE and/or DISTRO)

Note

It is also possible to specify "DISTRO=x" and "MACHINE=x" in the command. In this case, the popup for MACHINE and DISTRO selection will not appear.

Example:

host:~/PHYTEC_STM32MP1_BSP$ DISTRO=openstlinux-weston MACHINE=phycore-stm32mp1-3 source layers/meta-st-openstlinux-phytec/scripts/openstlinux-init-phytec.sh

Build Process

Now you should be in a sub-folder named '~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-<MACHINE>' and you can start the first build process, using the following command:

host:~/PHYTEC_STM32MP1_BSP/build-openstlinuxweston-phycore-stm32mp1-3$ bitbake <BSP_IMAGE>

Example to build the "st-image-weston":

host:~/PHYTEC_STM32MP1_BSP/build-openstlinuxweston-phycore-stm32mp1-3$ bitbake st-image-weston

Generated BSP Image Binaries

All images generated by Bitbake are deployed to ~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-<MACHINE>/tmp-glibc/deploy/images/<MACHINE>. The following list shows the generated files used for flashing the phycore-stm32mp1:

Binary subfolder locationBinary file nameDescription
arm-trusted-firmwaretf-a-<MACHINE>-serialboot.stm32

TF-A binary for serial boot mode (STM32CubeProgrammer)

arm-trusted-firmwaretf-a-<MACHINE>-trusted.stm32TF-A binary for FSBL partition (trusted boot chain)
bootloader

u-boot-<MACHINE>-trusted.stm32

U-Boot binary for SSBL partition (trusted boot chain)
-

st-image-bootfs-<DISTRO>-<MACHINE>.ext4

Binary for bootfs partition on eMMC and microSD card devices
-

st-image-vendorfs-<DISTRO>-<MACHINE>.ext4

Binary for vendorfs partition on eMMC and microSD card devices
-

<BSP_IMAGE>-<DISTRO>-<MACHINE>.ext4

Binary for rootfs partition on eMMC and microSD card devices
-

st-image-userfs-<DISTRO>-<MACHINE>.ext4

Binary for userfs partition on eMMC and microSD card devices
-<BSP_IMAGE>-<DISTRO>-<MACHINE>_nand_x_x_multivolume.ubiBinary for bootfs, vendorfs, rootfs, and userfs partitions on NAND device

Programming the Target

In this section, we explain how to use the STM32MPCubeProgrammer tool to flash the NOR, eMMC, NAND, or SD Card.

Install STM32CubeProgrammer Tool

When using the PHYTEC Virtual Machine preconfigured for the phyCORE-STM32MP1 BSP, this tool is already installed. Otherwise, refer to https://wiki.st.com/stm32mpu/wiki/STM32CubeProgrammer for information on installing the STM32CubeProgrammer.

To download the BSP via DFU link, change the BOOT mode to UART/USB boot mode

  • Switch OFF the board
  • Change the S7 DIP switch to UART/USB boot mode:

  • Switch ON the board => The RED LED on the SOM must start blinking RED.
  • Connect a USB micro-AB (OTG) to X12 and to the host PC that contains the downloaded image => The RED led should stop blinking.

Using STM32CubeProgrammer

  • Go to the directory that contains the binaries and the flash layout files: 
host:~$ cd ~/PHYTEC_STM32MP1_BSP/build-openstlinuxweston-stm32mp1/tmp-glibc/deploy/images/phycore-stm32mp1-3
  • Get the device port location for the USB link:
$ STM32_Programmer_CLI -l usb
      -------------------------------------------------------------------
                        STM32CubeProgrammer <tool version>                  
      -------------------------------------------------------------------

=====  DFU Interface   =====

Total number of available STM32 device in DFU mode: 1

  Device Index           : USB1
  USB Bus Number         : 001
  USB Address Number     : 001
  Product ID             : DFU in HS Mode @Device ID /0x500, @Revision ID /0x0000
  Serial number          : 003C00283338510C34383330
  Firmware version       : 0x0110
  Device ID              : 0x0500
  • Use the flashing command:
$ STM32_Programmer_CLI -c port=<DEVICE_PORT_LOCATION> -w [<file.tsv>]
where 
 w:
     Write
 <file.tsv>:PathToFlashlayout/flashlayout.tsv file
         if Flashlayout and binaries are not in the same directory, then the path to the Flashlayout files must be precised.
 <DEVICE_PORT_LOCATION>:
         e.g. usb1 (case sensitive)

Flashing the SD Card (Boot from SD-card)

To flash the SD Card with STM32CubeProgrammer:

  • If not already done, insert an SD Card in the SD Card connector (X14).
  • Use the flashing command with the following Flashlayout file: /flashlayout_st-image-weston/trusted/FlashLayout_sdcard_phycore-stm32mp1-3-trusted.tsv
$ STM32_Programmer_CLI -c port=usb1 -w flashlayout_st-image-weston/trusted/FlashLayout_sdcard_phycore-stm32mp1-3-trusted.tsv

This operation takes several minutes (mainly depending on the rootfs size). A successful flashing outputs the following message:

Flashing service completed successfully

Flashing the Target

Flashing the NOR and eMMC (Boot from NOR)

  • Use the flashing command with the following Flashlayout file: /flashlayout_<BSP_IMAGE>/trusted/FlashLayout_nor-emmc_<MACHINE>-trusted.tsv

Tip

With this FlashLayout file, the ST Trusted Firmware and U-boot are downloaded into the NOR Flash. The kernel and rootfs files are downloaded into eMMC. This enables booting from NOR Flash and running Linux on the eMMC.


$ STM32_Programmer_CLI -c port=usb1 -w flashlayout_st-image-weston/FlashLayout_nor-emmc_phycore-stm32mp1-3-trusted.tsv

This operation takes several minutes (mainly depending on the rootfs size). A successful flashing outputs the following message:

Flashing service completed successfully

Flashing eMMC (Boot from eMMC)

  • Use the flashing command with the following Flashlayout file: /flashlayout_<BSP_IMAGE>/trusted/FlashLayout_emmc_<MACHINE>-trusted.tsv
$ STM32_Programmer_CLI -c port=usb1 -w flashlayout_st-image-weston/FlashLayout_emmc_phycore-stm32mp1-3-trusted.tsv

This operation takes several minutes (mainly depending on the rootfs size). A successful flashing outputs the following message:

Flashing service completed successfully

Flashing NAND (Boot from NAND)

  • Use the flashing command with the following Flashlayout file: /flashlayout_<BSP_IMAGE>/trusted/FlashLayout_nand_<MACHINE>-trusted.tsv
$ STM32_Programmer_CLI -c port=usb1 -w flashlayout_st-image-weston/FlashLayout_nand-2-256_phycore-stm32mp1-3-trusted.tsv

This operation takes several minutes (mainly depending on the rootfs size). A successful flashing outputs the following message:

Flashing service completed successfully

Create an SD Card Image (with PC Host SD Card Reader)

When booting from SD card, another possibility (apart from using STM32Cubeprogrammer) is to create an SD Card image that contains all BSP binary files in correctly preformatted partitions. This image can be copied to the SD card easily using the single Linux command dd. Use the script create_sdcard_from_flashlayout.sh with the <FlashLayout file> = FlashLayout_sdcard_phycore-stm32mp1-3-trusted.tsv:

host:~$ cd build-<DISTRO>-<MACHINE>/tmp-glibc/deploy/images/<MACHINE>/scripts
host:~$ ./create_sdcard_from_flashlayout.sh ../flashlayout_<built-image>/trusted/<FlashLayout file>

Example:

host:~$ cd build-openstlinuxweston-phycore-stm32mp1-3/tmp-glibc/deploy/images/phycore-stm32mp1-3/scripts
host:~$ ./create_sdcard_from_flashlayout.sh ../flashlayout_st-image-weston/trusted/FlashLayout_sdcard_phycore-stm32mp1-3-trusted.tsv 

The script will generate the following SD Card image (raw file): in the binaries directory: .../flashlayout_<BSP_IMAGE>_FlashLayout_sdcard_<MACHINE>-trusted.raw

Example : flashlayout_st-image-weston_FlashLayout_sdcard_phycore-stm32mp1-3-trusted.raw (in build-openstlinuxweston-phycore-stm32mp1-3/tmp-glibc/deploy/images/phycore-stm32mp1-3)

Use this raw file to populate the SD Card with dd command:

  • Insert the uSD Card in the PC Host
  • Umount all the partitions associated with uSD Card
  • Populate microSD card with dd command:
host:~$ cd build-openstlinuxweston-phycore-stm32mp1-3/tmp-glibc/deploy/images/phycore-stm32mp1-3
host:~$ sudo dd if=flashlayout_st-image-weston_FlashLayout_sdcard_phycore-stm32mp1-3-trusted.raw of=/dev/mmcblk0 bs=8MB conv=fdatasync

More details can be found here: https://wiki.st.com/stm32mpu/wiki/How_to_populate_the_SD_card_with_dd_command

Warning

To create your bootable SD Card with the dd command, you must have root privileges. Because of this, you must be very careful when selecting the destination device for the dd command! All files on the selected destination device will be erased immediately without any further query! Consequently, having selected the wrong device can also erase your hard drive!

System Booting

The phyCORE-STM32MP1 can boot from the following devices:

  • eMMC
  • NOR
  • NAND (when populated instead of eMMC)
  • UART 
  • USB
  • SD-Card

The boot source is chosen by setting the S7 DIP switch.

Booting from SD Card

Booting from the SD Card is useful in several situations (for example when the bootloader in Flash memory has crashed).

To boot from the SD card, set the S7 DIP switch as follow: 

There are two ways to create a bootable SD card. You can either use:

Booting from eMMC Flash

  • When powering the board again, the system will boot from eMMC.

Booting from NOR Flash

  • When powering the board again, the system will boot from NOR.

Booting from NAND Flash

  • When powering the board again, the system will boot from NAND.

Accessing Peripherals (in Linux userspace)

The following sections provide an overview of the supported hardware components and their operating system drivers on the STM32 platform.

UARTs (tty)

The STM32MP15x SoC provides up to 4 x UART and 4 x USART. phyCORE-STM32MP1 and carrier board is configured by default with 4 UARTs:

UART interfaceLinux DeviceFunction on Carrier BoardRTS/CTS
UART4/dev/ttySTM0

USB debug (X13) - 1st FTDI serial port (Linux Terminal)
optionally available on Expansion connector (X33)

no
USART3/dev/ttySTM1

USB debug (X13) - 2nd FTDI serial port
optionally available on:

  • Arduino Shields connector (X3)
  • Expansion connector (X33)
no
USART1/dev/ttySTM2

UART available on:

  • RS232/RS485 (X35)
  • Arduino Shields connector (X3)
  • Raspberry Pi HAT connector (X7)
yes

Below are some Linux userspace commands to test the UART on target:

  • Sending a message on USART3:
target$ echo "test" > /dev/ttySTM1
  • Receiving a message on USART3:
target$ cat /dev/ttySTM1
  • Be sure that the baud rate is set correctly on the host and target. In order to get the currently configured baud rate, you can use the command stty on the target.

Command to get tty help:

target$ tty --help

FD CAN Bus

For an overview of the Linux Controller Area Network (CAN) framework, please refer to https://wiki.st.com/stm32mpu/wiki/CAN_overview

Below are some examples on how to send or receive data on a SocketCAN interface using the can-utils package with the cansend and candump command:

Prerequisite: At least two nodes are required to communicate on a CAN network.

  • Initialize CAN0 Link with 1Mbit/s:
target$ ip link set can0 up type can bitrate 1000000
  • The command below allows you to get details on the created link:
target$ ip -details link show can0
2: can0: <NOARP,UP,LOWER_UP,ECHO> mtu 16 qdisc fq_codel state UNKNOWN mode DEFAULT group default qlen 10
    link/can  promiscuity 0 
    can state ERROR-ACTIVE (berr-counter tx 0 rx 0) restart-ms 0 
          bitrate 992063 sample-point 0.761
          tq 48 prop-seg 7 phase-seg1 8 phase-seg2 5 sjw 1
          m_can: tseg1 2..256 tseg2 1..128 sjw 1..128 brp 1..512 brp-inc 1
          m_can: dtseg1 1..32 dtseg2 1..16 dsjw 1..16 dbrp 1..32 dbrp-inc 1
          clock 62500000numtxqueues 1 numrxqueues 1 gso_max_size 65536 gso_max_segs 65535
  • To send a single frame, use the cansend utility (cansend <device> <can_frame>):
target$ cansend can0 123#1122334455667788                                                                                                                                                   
  • To receive CAN message, use the candump utility:
target$ candump can0                                                                                                                                                     
  can0  123   [8]  00 11 22 33 44 55 66 77
  can0  123   [8]  00 11 22 33 44 55 66 77
  • To print help on candump utility, use: "candump -h"

Network

A gigabit Ethernet is provided by our module and board. The interfaces offer a standard Linux network port that can be programmed using theBSD socket interface. The BSP contains different Network tools that allow for the configuration and testing of the Ethernet connection.

For information about these different tools and how to use them, please refer tohttps://wiki.st.com/stm32mpu/wiki/Network_tools

Example on how to assign a given IP address to an Ethernet ETH0 interface:

ifconfig eth0 10.48.1.324

SD Card

The phyBOARD-Sargas supports a slot for Secure Digital Cards to be used as general-purpose block devices. These devices can be used in the same way as any other block device.

Warning

These kinds of devices are hot-pluggable. Nevertheless, you must ensure not to unplug the device while it is still mounted. This may result in data loss!

After inserting an SD/MMC card, the kernel will generate new device nodes in /dev. The full device can be reached via its /dev/mmcblk0 device node. SD/MMC card partitions will show up in the following way:

/dev/mmcblk0p<Y>

<Y> counts as the partition number starting from 1 to the max count of partitions on this device. The partitions can be formatted with any kind of file system and also handled in a standard manner, e.g. the mount and umount command work as expected.

GPIOs

The phyBOARD-Sargas carrier board has a set of pins specifically dedicated as user I/Os. Those pins are connected directly to STM32MP15x balls and are muxed as GPIOs. Accessing GPIOs from userspace can be done using the libgpiod.

To see how to access the GPIOs, please refer to https://wiki.st.com/stm32mpu/wiki/How_to_control_a_GPIO_in_userspace 

Warning

Most of the CPU IOs are used for special functions. Before using a user IO, refer to the schematic or the hardware manual of your board to ensure that it is not already in use.

Keys

With gpio-keys driver, the Linux kernel can interpret GPIO signals as virtual keyboard events. The carrier board has 2 buttons (S4 and S5), which can be used with the gpio-keys driver. 

To display the key events in ASCII format, use evtest.

  • To show the available input devices, run:
target$ evtest
  • You will get, for example:
No device specified, trying to scan all of /dev/input/event*
Available devices:
/dev/input/event0:      pmic_onkey
/dev/input/event1:      gpio-keys
Select the device event number [0-1]:
  • Select input device event number 1 for gpio-keys:
Select the device event number [0-1]: 1
Input driver version is 1.0.1
Input device ID: bus 0x19 vendor 0x1 product 0x1 version 0x100
Input device name: "gpio-keys"
Supported events:
  Event type 0 (EV_SYN)
  Event type 1 (EV_KEY)
    Event code 28 (KEY_ENTER)
    Event code 102 (KEY_HOME)
Properties:
Testing ... (interrupt to exit)
  • Now you will see every hit on push buttons S4 (KEY_HOME) or S5 (KEY_ENTER):
Event: time 1570639195.409061, type 1 (EV_KEY), code 102 (KEY_HOME), value 1
Event: time 1570639195.409061, -------------- SYN_REPORT ------------
Event: time 1570639195.569047, type 1 (EV_KEY), code 102 (KEY_HOME), value 0
Event: time 1570639195.569047, -------------- SYN_REPORT ------------
Event: time 1570639196.809052, type 1 (EV_KEY), code 28 (KEY_ENTER), value 1
Event: time 1570639196.809052, -------------- SYN_REPORT ------------
Event: time 1570639197.009031, type 1 (EV_KEY), code 28 (KEY_ENTER), value 0
Event: time 1570639197.009031, -------------- SYN_REPORT ------------
  • You can exit evtest with Ctrl+C
  • Listening to the device with cat will print the raw output:
target$ cat /dev/input/event1
root@phycore-stm32mp1-3:/sys/class# cat /dev/input/event1 
F
�]��fF
�]��F
�]BfF
�]B

LEDs

If any LEDs are connected to GPIOs, you have the possibility to access them by a special LED driver interface instead of the general GPIO interface (section GPIOs). You will then access them using /sys/class/leds/ instead of /sys/class/gpio/. The maximum brightness of the LEDs can be read from the max_brightness file. The brightness file will set the brightness of the LED (taking a value from 0 up to max_brightness). Most LEDs do not have hardware brightness support and therefore, will just be turned on by all non-zero brightness settings.

Here is a simple example:

  • To get all LEDs available, type:
target$ ls /sys/class/leds
blue-power  pca:green:power  pca:red:power

Here the LEDs are the three possible colors from RGB lED driven by a LED dimmer present on the carrier board. By default, the RGB LED blinks blue (it is the "Linux Heartbeat" that shows the Linux Kernel is running). But this RGB LED can also be used as a "user LED".

  • Example to toggle the RGB LED Blue color OFF:
target$ cd /sys/class/leds
target$ echo 0 >  blue-power/brightness
  • Example to toggle RGB LED Blue color ON with a brightness=10:
target$ echo 10 >  blue-power/brightness
  • Example to toggle RGB LED Green color ON with a brightness=20:
target$ echo 20 >  pca\:green\:power/brightness

I2C Bus

The STM32MP15x SoC provides up to 6 I²C FM (Fast-Mode). The phyCORE-STM32MP1 is configured with two Fast-Mode I²C modules called I2C4 and I2C1.

  • I2C4 is reserved for the I²C devices on the module (PMIC, RTC, EEPROM).
  • I2C1 is reserved for the carrier board which provides plenty of different I²C devices connected I²C1 bus of the STM32MP15x.

This section will describe the basic device usage.

EEPROM

It is possible to read and write directly to the device:

/sys/class/i2c-dev/i2c-1/device/1-0050/eeprom
  • To read and print the first 1024 bytes of the EEPROM as a hex number, execute:
target$ dd if=/sys/class/i2c-dev/i2c-1/device/1-0050/eeprom bs=1 count=1024  | od -x
  • To fill the whole EEPROM with zeros, use:
target$ dd if=/dev/zero of=/sys/class/i2c-dev/i2c-1/device/1-0050/eeprom bs=4096 count=1

This operation takes some time as the EEPROM is relatively slow.

RTC

RTCs can be accessed via /dev/rtc*

  • Check the available RTC:
target$ ls /sys/class/rtc
target$ rtc0  rtc1

Tip

This will list all RTCs including the non-I²C RTCs.

  • To find the name of the RTC devices, you can read its sysfs entry with:
target$ cat /sys/class/rtc/rtc*/name
rtc-rv3028 1-0052
stm32_rtc 5c004000.rtc
RTC devicesNameDescription
/dev/RTC0rtc-rv3028 1-0052External RTC RV-3028 (on the SOM). It is the Default RTC used by Linux Timing System.

/dev/RTC1

stm32_rtc 5c004000.rtc

Internal RTC of the CPU

As time is set according to the value of rtc0 during system boot, rtc0 should always be the RTC that is being backed up. 

  • Date and time can be manipulated with the date command and the hwclock tool. Example to set the date on /dev/RTC0:
target$ date 1010123119
Thu Oct 10 12:31:00 UTC 2019
target$ hwclock -w


Tip

As the VBACKUP pin of the external RTC component RV-3028 (on the SOM) is connected to a Gold Cap (on the carrier board), the date and time stored in the RTC are kept even if the board is switched off.

SPI Bus

The STM32MP1 SoC provides up to 6 SPI interfaces. The phyCORE-STM32MP1 is configured with 1 SPI called SPI16 (configured as SPI1 or SPI6).

By default, the Linux SPI driver used in the BSP is spidev.

SPI interfaceLinux Device

SPI1 (or SPI6)

/dev/spidev0.0

USB Host and OTG

Both USB Host and OTG use the same framework.

To learn about the Linux USB framework and how to use it, please refer to the USB framework: https://wiki.st.com/stm32mpu/wiki/USB_overview

For more software details about the OTG internal peripheral, please refer to https://wiki.st.com/stm32mpu/wiki/OTG_internal_peripheral

For more software details about the USBH internal peripheral, please refer to https://wiki.st.com/stm32mpu/wiki/USBH_internal_peripheral

Create an SSH Connection with USB OTG or Ethernet

When the target is running on Linux, you can create an SSH connection with Ethernet or USB OTG (Ethernet point to point).

To create an SSH connection over USB OTG, proceed as follow: 

  • Plug a USB-A male to USB Micro B between the carrier board (X12) and the PC Host.
  • On your host PC, with your network manager or using "ifconfig" on a terminal, check that there is a new network interface (ex: new interface called "enp0s20f0u2u3").
  • Check the IP address of the USB OTG device of the target (usb0). By default it is configured to 192.168.7.1.
target$ ifconfig 
eth0      Link encap:Ethernet  HWaddr 8E:C5:2C:68:CF:75  
          inet6 addr: fe80::8cc5:2cff:fe68:cf75/64 Scope:Link
          UP BROADCAST RUNNING MULTICAST  MTU:1500  Metric:1
          RX packets:0 errors:0 dropped:0 overruns:0 frame:0
          TX packets:35 errors:0 dropped:0 overruns:0 carrier:0
          collisions:0 txqueuelen:1000 
          RX bytes:0 (0.0 B)  TX bytes:7597 (7.4 KiB)
          Interrupt:61 Base address:0x2000 

lo        Link encap:Local Loopback  
          inet addr:127.0.0.1  Mask:255.0.0.0
          inet6 addr: ::1/128 Scope:Host
          UP LOOPBACK RUNNING  MTU:65536  Metric:1
          RX packets:264 errors:0 dropped:0 overruns:0 frame:0
          TX packets:264 errors:0 dropped:0 overruns:0 carrier:0
          collisions:0 txqueuelen:1000 
          RX bytes:16800 (16.4 KiB)  TX bytes:16800 (16.4 KiB)

usb0      Link encap:Ethernet  HWaddr BA:15:19:D5:BC:01  
          inet addr:192.168.7.1  Bcast:192.168.7.255  Mask:255.255.255.0
          UP BROADCAST MULTICAST  MTU:1500  Metric:1
          RX packets:0 errors:0 dropped:0 overruns:0 frame:0
          TX packets:0 errors:0 dropped:0 overruns:0 carrier:0
          collisions:0 txqueuelen:1000 
          RX bytes:0 (0.0 B)  TX bytes:0 (0.0 B)
  • On your host PC, with your network manager or with ifconfig command, check that there is a new network interface (ex: new interface called "enp0s20f0u2u3"). Then, configure the IP that matches with the usb0 target interface (192.168.7.1). Example with ifconfig:
host:~$ sudo ifconfig enp0s20f0u2u3 192.168.7.2
  • Connect to the target (to create a new remote terminal through SSH):
host:~$ ssh root@192.168.7.1
  • You can also copy any file from the host to the target with the following command:
host:~$ scp ~/myFile root@192.168.7.1:/home/root

The same procedure can be applied with an Ethernet connection, except that no Ethernet IP is attributed by default on the target (when no DHCP server is used). So you first have to set an Ethernet IP address to the target.

Audio

On the phyCORE-STM32MP1, we use the TI TLV320AIC3007 audio codec. Audio support is done via the SAI2 interface and controlled via I2C.

  • To check if your sound card driver is loaded correctly and to check which audio output device is available:
target$ aplay -L
  • You will get output similar toː
null
      Discard all samples (playback) or generate zero samples (capture)
pulse
      PulseAudio Sound Server
default
      Default ALSA Output (currently PulseAudio Sound Server)
sysdefault:CARD=STM32MP1PHYCORE
      STM32MP1-PHYCORE, 
       Default Audio Device
  • To test Audio Playback:
target$ aplay -D plughw:CARD=STM32MP1PHYCORE /usr/share/sounds/alsa/Front_Center.wav
  • To list audio capture devices:
target$ arecord -l
**** List of CAPTURE Hardware Devices ****card 0: STM32MP1PHYCORE [STM32MP1-PHYCORE], device 1: 4400b004.audio-controller-tlv320aic3x-hifi tlv320aic3x-hifi-1 [] 
Subdevices: 1/1 Subdevice #0: subdevice #0
  • Run speaker-test to identify channel numbers (Left, Right...). Example to check right and left channel (2 channels):
target$ speaker-test -c 2 -t wav
  • You may have to select the audio device:
target$ speaker-test -c 2 -t wav -D plughw:CARD=STM32MP1PHYCORE
  • To inspect your sound cards capabilities, call:
target$ alsamixer -c STM32MP1PHYCORE

You should see a lot of options as the audio-ICs has many features you can play with. It might be better to open alsamixer via ssh (see Create an SSH Connection with USB OTG or Ethernet) instead of the serial console, as the console graphical effects are better.

Audio Sources and Sinks

The phyBOARD-Sargas carrier board has three jacks: headphone (X28), line-in (X27), line out (X26); and one Mono speaker output connector (X5). Enabling and disabling input and output channels can be done with the alsamixer program.

With the Tabulator key, you can switch between the following screens:  Screen Playback; Screen Capture. To enable or disable switchable controls, press m (mute). With the cursor keys left and right, you can step through the different channels.  You can leave alsamixer by pressing the ESC key. The settings are saved automatically on shutdown and restored on boot by the systemd service alsa-restore. If you want to save the mixer settings manually, you can execute alsactl store. The settings are saved in /var/lib/alsa/asound.state.

Playback

To playback simple audio streams, you can use aplay. For example:

target$ aplay /usr/share/sounds/alsa/Front_Center.wav
#OR you may have to select the audio device:
target$ aplay -D plughw:CARD=STM32MP1PHYCORE /usr/share/sounds/alsa/Front_Center.wav

Capture

arecord is a command-line tool for capturing audio streams that use Line In as the default input source. The following example captures the current stereo input source with a sample rate of 48000 Hz and creates an audio file in WAV format (signed 16 bit per channel, 32 bit per sample):

target$ arecord -t wav -c 2 -r 48000 -f S16_LE test.wav
#OR :
target$ arecord -t wav -c 2 -f dat test.wav
#OR you may have to select the audio device:
target$ arecord -t wav -c 2 -f dat test.wav -D hw:0,1

Capturing can be stopped using CTRL-C. You can also specify the capture duration with the -d option.

  • To play the recorded file: 
target$ aplay test.wav

Texas Instruments TLV320AIC3007

The TI chip has a lot of mixing features as you will notice when opening alsamixer. To get an idea of the possibilities, refer to the datasheet from TI. One important feature is the analog mixing capability. You can route input channels to output channels, either active or passive, without transferring data back and forth to the SoC. This is usually known as zero-latency monitoring in terms of PC Audio cards. To control this feature, open alsamixer and go to Playback section (F3). There will be one group of selectors for each output channel, e.g. Right Line Mixer. For most of the input paths, you can select between "passive through" or you can activate a programmable gain signal path. To route the line input to the line output, activate both "Right Line Mixer PGAR Bypass" and "Left Line Mixer PGAL Bypass". You should now hear the input signal at the line-out.

As an example application, we can route the audio stream through the whole system. First, we deactivate the direct loop from line-in to line-out in alsamixer and activate the ADC for the analog input mixer and the DAC for the analog output mixer. We can now close the signal path in the user space by using a pipe and the ALSA tools:

target$ arecord -c 2 -r 48000 -f S16_LE | aplay
#OR
target$ arecord -c 2 -r 48000 -f S16_LE -D hw:0,1 | aplay -D plughw:CARD=STM32MP1PHYCORE

We created the following audio routing path:

analog in -> ADC -> STM32MP1 -> kernel -> (userspace -> kernel -> )* DAC -> analog out

* actually twice for the pipe

You should now hear the input signal at the line output again. But this time, the routing through the entire system added a latency of 750 ms to the signal. The line mixer on the other side will only add about 4 μs delay.

This pipe routing is a crude example of how to use audio. If you need good audio performance, you should use an audio server. There are two prominent choices available, pulseaudio and jack.

As a third option, you can route the audio from line-in to the internal ADC. But instead of taking the signal path through the complete system, you can use the internal digital mixer of the TLV to directly route the signal back to the DAC and then to the output analog mixer and line-out. This signal path is record-only. You do not have the option of full-duplex playback in this mode. You can, however, use all the available DSP features of the TLV, the automatic gain, the high-pass filter, EQ, and de-emphasis filters for the record path. To activate this mode, you have to use the TI Windows tool to look up the specific I²C commands. The software can be found on the TI webpage and is called TLV320AIC3107EVM-K - GUI software. The 3107 is register compatible with all available features to the 3007. The software is used for both chips.

Displays

Three different kinds of displays are currently supported:

  • HDMI monitor => with PEB-AV-01 PHYTEC addon connected on Audio/Video connectors X24/X25
  • AC158 7" EDT capacitive LCD screen - 800x480 pixels => with PEB-AV-02 PHYTEC addon connected on Audio/Video connectors X24/X25
  • MB1407 MIPI DSI screen  - 4" TFT 480x800 pixels (from STMicroelectronics : https://wiki.st.com/stm32mpu/wiki/MB1407) => connected on MIPI DSI connector X41
  • Official Raspberry Pi Touch 7" Display => connected on MIPI DSI connector X41

By default, the PHYTEC BSP is configured for the AC158 LCD parallel display (with PEB-AV-02 expansion).

To switch between the 3 different configurations, the device tree has to be rebuilt.

Changing the BSP Display Configuration

Prerequisite: Building the BSP must have been done.

Build a new image enabling/disabling one of the following Linux Kernel device tree files:

  • phyboard-stm32mp1-peb-av01-hdmi.dtsi
  • phyboard-stm32mp1-peb-av02-lcd.dtsi
  • phyboard-stm32mp1-dsi-lcd-mb1407.dtsi
  • phyboard-stm32mp1-dsi-rpi-official-display.dtsi

By default, phyboard-stm32mp1-peb-av02-lcd.dtsi is enabled.

  • To enable/disable one of these device tree expansions, comment (line begin with //) or uncomment the corresponding line in the phyboard-stm32mp1.dtsi kernel device tree file (at the end of file).  Only one display expansion can be enabled at a time.
  • To modify and re-build the Linux Kernel device tree, please refer to section BSP Customization.
  • Once you have built and deployed your new BSP image on target, you can check that the display configuration is correct with the following command:
target$ modetest -M stm -c
Connectors:
id      encoder status          name            size (mm)       modes   encoders
29      28      connected       HDMI-A-1        520x290         2       28
  modes:
        name refresh (Hz) hdisp hss hse htot vdisp vss vse vtot)
  1024x768 70 1024 1048 1184 1328 768 771 777 806 75000 flags: nhsync, nvsync; type: driver
  800x600 72 800 856 976 1040 600 637 643 666 50000 flags: phsync, pvsync; type: driver
  props:
        1 EDID:
                flags: immutable blob
                blobs:

                value:
                        00ffffffffffff005a6330b701010101
                        201a010380341d782e0bd5a25750a128
                        0f5054bfef80b300a940a9c095009040
                        8180814081c0023a801871382d40582c
                        450009252100001e000000ff0055454a
                        3136333232313038340a000000fd0032
                        4b185213000a202020202020000000fc
                        00564132343635205345524945530081
        2 DPMS:
                flags: enum
                enums: On=0 Standby=1 Suspend=2 Off=3
                value: 0
        5 link-status:
                flags: enum
                enums: Good=0 Bad=1
                value: 0
        6 non-desktop:
                flags: immutable range
                values: 0 1
                value: 0
        19 CRTC_ID:
                flags: object
                value: 32

This command allows the user to check the display connectors and their status. modetest is DRM/KMS test tool.

The '-c' modetest option displays only the Connectors. To check all the Linux DRM display parameters (Encoders, CRTCs, Planes, Framerbuffers) use the command: 

target$ modetest -M stm

To get more information about the modetest command and the Linux DRM/KMS display, graphic and composition framework, please refer to: https://wiki.st.com/stm32mpu/wiki/DRM_KMS_overview#Show_display_overall_status

Expected results to check that the display configuration on target is correct:

  • HDMI configuration enabled: connector name = "HDMI-A-1", status ="connected"
  • parallel LCD configuration enabled: connector name = "DPI-1", status ="connected"
  • MIPI DSI display configuration enabled: connector name = "DSI-1", status ="connected"


Warning

  • If you want to test displays or set specific video modes with the modetest tool, the Wayland/Weston framework has to be stopped with the following command:

systemctl stop weston@root.service

  • If you want to restart Wayland, use the following command:

systemctl start weston@root.service

  • If Wayland/Weston framework is not running but the splash screen is displayed, this one must be removed with the following command:

psplash-drm-quit

Selecting the HDMI Monitor Video Modes

To get the supported video modes (resolutions and refresh frequencies) of an HDMI monitor connected to the phyCORE-STM32MP platform, please refer to https://wiki.st.com/stm32mpu/wiki/How_to_display_on_HDMI#Video_modes and https://wiki.st.com/stm32mpu/wiki/How_to_display_on_HDMI#FAQ.

Example to set a particular HDMI video mode:

Taking the result of the "modetest -M stm -c" command from previous section, we can see that:

  • HDMI-A-1 is on connector id 29, is connected, and supports a resolution of 1280x720-50.
  • associated CRTC is on id 32

The command to set the supported "800x600-72" video mode is:

target$ modetest -M stm -s 29@32:800x600-72 -d

Note: To be able to use this command, stop any running graphical environment on top of DRM/KMS Linux framework (like Wayland Weston or splash screen).

Generally, the HDMI monitor (or TV) provides (through I2C) several video modes (resolutions and refresh frequencies), that might not be all supported by the platform. In case all video modes supported by the monitor are rejected by the phyCORE-STM32MP platform, you will not be able to use the monitor.

One solution, in this case, is to use Linux kernel DRM KMS Helper with EDID Firmware files to be able to get more video modes possibilities and choose the HDMI resolution to apply. This EDID firmware is installed by default in the BSP.  The resolution must be set in u-boot, setting the variable environment "hdmi_resolution" as follow.

example to fix the HDMI resolution to 1280x720 in u-boot:

STM32MP> setenv hdmi_resolution HDMI-A-1:edid/1280x720.bin
STM32MP> saveenv

By default, this environment variable does not exist in u-boot so that this EDID Firmware is not used for HDMI resolution configuration (resolution provided by the monitor and supported by the STM32MP are used).

The list of available EDID resolution binaries can be found on target in linux under: /lib/firmware/edid/. Note that not all of them are not supported by the STM32MP1.

WLAN / Bluetooth Module Expansion

Two different WLAN / Bluetooth modules are supported :

  • Laird Stering-LWB 2.4GHz from Laird™ => with PEB-WLBT-05 PHYTEC addon connected on Expansion connector X33
  • AMPAK AP6212A => with the Raspberry PI HAT "RedBear IoT pHAT v1.0" connected on Raspberry Pi connector X7

By default, the PHYTEC BSP is configured without any Wifi/Bluetooth module activated in the device tree.

To enable one of these two modules, the Linux Kernel device tree has to be rebuilt.

Enabling WLAN / Bluetooth Module on a Device Tree

Prerequisite: Building the BSP must have been done.

With this PEB-WLBT-05 expansion, WLAN and Bluetooth device tree can be activated separately, so it is possible to use WLAN only, Bluetooth only, or both enabled.

  • Build a new image enabling the following Linux Kernel device tree files:
Expansion

FunctionKernel device tree expansion

PEB-WLBT-05[1]

Bluetooth[2]

on USART1

phyboard-stm32mp1-peb-wlbt-05-bluetooth-usart1.dtsi

on USART3phyboard-stm32mp1-peb-wlbt-05-bluetooth-usart3.dtsi
WLAN

phyboard-stm32mp1-peb-wlbt-05-wlan.dtsi

RedBear IoT pHAT v1.0WLAN and Bluetoothphyboard-stm32mp1-pi-hat-redbear.dtsi

1.

With PEB-WLBT-05, WLAN and Bluetooth expansion device tree files can be both enabled or only one can be enabled, so it is possible to use WLAN only, Bluetooth only, or both.

2.

With PEB-WLBT-05, for Bluetooth, enabled the device tree corresponding to the UART interface that should be used by the module (refer to the Application Note of this module to configure the phyBOARD-Sargas correctly).

  • To enable/disable those Kernel device tree expansions, comment (line begin with //) or uncomment the corresponding line in the phyboard-stm32mp1.dtsi kernel device tree file (at the end of file). 
  • To modify and re-build the device tree, please refer to section BSP Customization.

Tip

Watchdog

The STM32MP includes a Watchdog circuit called "IWDG" (Independent WatchDoG) that is able to reset the board when the system hangs (due to software or hardware failures). The IWDG is clocked by an independent clock and stays active even if the main clock fails. In addition, the watchdog function is performed in the VDD voltage domain, allowing the IWDG to remain functional even in low-power modes.

Two independent watchdogs (IWDG1 and IWDG2) are dedicated to MPU:

  • IWGG1 can only be allocated to the Cortex-A7 secure (to be used in the secure context by the customer application: this instance is not supported in OpenSTLinux distribution).
  • IWDG2 can be allocated to the Cortex-A7 non-secure to be used with Linux Watchdog Timer (WDT) framework.

How to enable the IWDG2 and configure its timeout value

The IWDG2 watchdog is enabled by default in the phycore-stm32mp157cac-som.dtsi kernel device tree with a custom timeout value in seconds (timeout-sec):

&iwdg2 {
timeout-sec = <32>;
status = "okay";
};

By default, the Watchdog Timer Linux framework support and the IWDG support is activated in the Linux kernel. This configuration can be changed through the Menuconfig tool (Configure the kernel through Menuconfig ):

Device Drivers --->
[*] Watchdog Timer Support --->
[*] Disable watchdog shutdown on close
[*] Update boot-enabled watchdog until userspace takes over
<*> STM32 Independent WatchDoG (IWDG) support

With the option  "Update boot-enabled watchdog until userspace takes over" (enabled by default),  the kernel will ping the watchdog as long as an application opens the /dev/watchdog file (used by systemd).

How to use the watchdog in Linux using systemd

systemd is able to use the Hardware watchdog to check for system hangs (when the system is running or during reboot). This feature is enabled by default, with the RuntimeWatchdogSec= option in the file system.conf in /etc/systemd/  :

RuntimeWatchdogSec=30s
ShutdownWatchdogSec=10min

When RuntimeWatchdogSec is not set or equal to 0, the Watchdog is not used. Setting this option to a different value allows you to use it.

RuntimeWatchdogSec defines the timeout value of the watchdog, while ShutdownWatchdogSec defines the timeout when the system is rebooted. For more detailed information about hardware watchdogs under systemd refer to http://0pointer.de/blog/projects/watchdog.html.

To get more information on the IWDG internal peripheral please refer to:

https://wiki.st.com/stm32mpu/wiki/IWDG_internal_peripheral

https://wiki.st.com/stm32mpu/wiki/IWDG_device_tree_configuration

To get more information on the IWDG Linux Kernel support and how to use and trace/debug the WDT framework, please refer to:

https://wiki.st.com/stm32mpu/wiki/Watchdog_overview

Special Connectors Pinout Configuration

The following special connectors are available on the phyCORE-Sargas:

  • Raspberry PI HAT
  • Arduino Shields
  • Motor Control

Those special connectors pinout can be configured in the Linux Kernel device tree with the following dts files:

  • phyboard-stm32mp1-pi-hat-extension.dtsi
  • phyboard-stm32mp1-uno-r3-extension.dtsi
  • phyboard-stm32mp1-motor-control.dtsi

By default, only phyboard-stm32mp1-pi-hat-extension.dtsi is enabled.

  • To enable/disable those Kernel device tree files, comment (line begins with //) or uncomment the corresponding line in the phyboard-stm32mp1-1.dtsi device tree file (at the end of file).
  • To modify and rebuild the device tree, please refer to section BSP Customization.

Prerequisite: Building the BSP must have been done.

Rapsberry PI HAT Connector (X7)

This connector is compatible with the pinout of the standard Raspberry Pi HAT connector (https://pinout.xyz/). The pinout can be configured by pin muxing in the following device tree file: phyboard-stm32mp1-pi-hat-extension.dtsi

Please refer to the phyCORE-STM32MP1 Hardware Manual section Raspberry Pi HAT Connector (X7) for the pinout of this connector.

Arduino Shields Connector (X3)

This connector is compatible with the standard Arduino pinout connector (https://www.arduino.cc/en/reference/board). The pinout can be configured by pin muxing in the following device tree file: phyboard-stm32mp1-uno-r3-extension.dtsi

Please refer to the phyCORE-STM32MP1 Hardware Manual section Arduino Shields Connector (X3) for the pinout of this connector.

Motor Control Connector (X38)

This connector is compatible with the pinout of STM32 standard motor control power boards. It is also possible to connect X-NUCLEO-IHMx STM32 motor control expansions using X-NUCLEO-IHM09M1 adaptor: https://www.st.com/en/ecosystems/x-nucleo-ihm09m1.html. The pinout can be configured by pin muxing in the following device tree file: phyboard-stm32mp1-motor-control.dtsi or phyboard-stm32mp1-motor-control-m4.dtsi.

phyboard-stm32mp1-motor-control-m4.dtsi is an example of device tree configuration when signals are used by the Cortex-M4 MCU.

Please refer to the phyCORE-STM32MP1 Hardware Manual section Motor Control Connector (X38) for the pinout of this connector.

Warning

By default phyboard-stm32mp1-motor-control.dtsi and phyboard-stm32mp1-motor-control-m4.dtsi are not included in the SRC_URI of the linux-stm32mp yocto recipe. So, to be able to compile them, you first have to modify this recipe to add the corresponding SRC_URI. Please refer to Modify the Kernel Device Tree to know how to do this.

BSP Customization

STM32MP1 BSP Device Tree Concept

All device tree documentation can be found under:

host:~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-<MACHINE>/tmp-glibc/work/<MACHINE>-<DISTRO>-linux-gnueabi/linux-stm32mp/<x.y>-r0/<x.y>/<x.y.z>/Documentation/devicetree/bindings

<x.y> and <x.y.z> in the above path have to be replaced by the Linux Kernel version number (ex: 5.4-r0/5.4/5.4.56/).

An introduction of the device tree usage can be found in the Linux kernel: linux/Documentation/devicetree/usage-model.txt. The device tree files are used during boot time by the Trusted Firmware (TF-A), the Bootloader (U-Boot), by the Linux kernel.

STM32MP documentation about the STM32MP1 Device Tree can be found at:

As shown in the STM32MP1 device tree documentation, the device tree organization depends if you are using the "upstream device tree" or the device tree generated by the STM32CubeMX tool.

In this BSP customization chapter, we are presenting the "upstream device tree" organization. For the STM32CubeMX STM32MP1 device tree organization refers to The STM32CubeMX tool.

Note that in this STM documentation, the device tree file's name concerning the boards do not correspond to our PHYTEC boards but the concept is exactly the same. The device tree files for our boards start with "phycore" or "phyboard". Refer to the following section for the phyCORE and phyBOARD device tree file organization: phyCORE-STM32MP1 and phyBOARD-STM32MP1 device tree (upstream).

Device tree source files:

.dts: The device tree source (DTS) that can be processed by DTC (Device Tree Compiler) into a binary device tree called "device tree blob" (.dtb). This device tree blob can be parsed by the embedded software components: LinuxKernel, U-Boot, and TF-A.

For each SOM versions (MACHINE), it is assigned a .dts file (ex: phycore-stm32mp1-4.dts for MACHINE=phycore-stm32mp1-4).

.dtsi: Source files that can be included from a DTS file.

For example, our phycore-stm32mp1-x DTS (phycore-stm32mp1-x.dts files) include one of the following STM32MP15dtsi files (SoC specific) which are upstreamed to the communities:

Example for our MACHINE "phycore-stm32mp1-3" (equipped with a STM32MP157CAC SoC):

phycore-stm32mp1-3.dts includes the following STM32MP15 SoC dtsi:  stm32mp157.dtsi + stm32mp15xc.dtsi + stm32mp15-pinctrl.dtsi + stm32mp15xxac-pinctrl.dtsi

STM32MP1 Pin Muxing

The STM32MP1 SoC contains many peripheral interfaces. In order to reduce package size and lower overall system cost while maintaining maximum functionality, many of the STM32MP1 terminals can multiplex up to 16 signal functions. The STM32MP1 BSP is based on the pin controller Linux kernel framework (pinctrl) with a specific pinctrl-stm32 driver. The configuration is performed in the device tree source (DTS).

Please refer to ST documentation to learn about pinctrl and how to configure it in the device tree:

 phyCORE-STM32MP1 and phyBOARD-Sargas Device Tree (Upstream)

As seen in previous section, the DTS of the phycore-stm32mp1-x machines (phycore-stm32mp1-x.dts) contain the specific SoC dtsi files. In addition to those dtsi, other dtsi are included to specify the Board Hardware specificities, which is split into two boards; the SOM and the Baseboard (one dtsi per board): 

  • SOM:phycore-stm32mp15-som.dtsi => contains the Hardware specificities common to all the phyCORE-STM32MP1 SOM declinations (machines)
  • Baseboard:phyboard-stm32mp1.dtsi => contains the Hardware configuration of the phyBOARD-Sargas

Note

The hardware differences between the different phyCORE-STM32MP1 machines are set in the phycore-stm32mp1-x.dts files. This is done including different ddr configuration dtsi files (in U-boot and TF-A only), and enabling/disabling SoC features (like GPU or CAN) or SOM devices (like eMMC/NAND).

SOM and Baseboard dtsi includes others .dtsi files (for pin control or for baseboard expansion boards).

Below is the complete list of our PHYTEC custom DTS files (.dts & .dtsi) for the phyCORE-STM32MP1 and phyBOARD-Sargas used by each software component (Linux Kernel, U-Boot, and TF-A).

To know how to modify those sources and rebuild the BSP image, refer to the next sections.

SourcesDTS files pathMachine (.dts)phyCORE-STM32MP1 .dtsi filesphyBOARD-Sargas .dtsi files

peripheral configuration

pin controlperipheral configurationpin control

Linux

Kernel

arch/arm/boot/dts/

Default:

phycore-stm32mp1-x.dts

Cortex-M4 example (1):

phycore-stm32mp1-x-m4-examples.dts

Cortex-A7 example (2):

phycore-stm32mp1-x-a7-examples.dts

phycore-stm32mp15-som.dtsi


phycore-stm32mp15-pinctrl.dtsi

phyboard-stm32mp1.dtsi
phyboard-stm32mp1-peb-av01-hdmi.dtsi
phyboard-stm32mp1-peb-av02-lcd.dtsi
phyboard-stm32mp1-peb-av02-lcd-res.dtsi

phyboard-stm32mp1-dsi-lcd-mb1407.dtsi

phyboard-stm32mp1-dsi-rpi-official-display.dtsi

phyboard-stm32mp1-pi-hat-extension.dtsi

phyboard-stm32mp1-peb-wlbt-05-bluetooth-usart1.dtsi
phyboard-stm32mp1-peb-wlbt-05-bluetooth-usart3.dtsi
phyboard-stm32mp1-peb-wlbt-05-wlan.dtsi
phyboard-stm32mp1-pi-hat-redbear.dtsi

Default:

phyboard-stm32mp1-pinctrl.dtsi

Pinctrl examples for Timers and ADC:

phyboard-stm32mp1-motor-control.dtsi

phyboard-stm32mp1-motor-control-m4.dtsi

(example of device tree configuration for peripheral used by Cortex-M4)

phyboard-stm32mp1-uno-r3-extension.dtsi

U-Bootarch/arm/dtsphycore-stm32mp1-x.dts

Copied from kernel:

phycore-stm32mp1-x.dts

phycore-stm32mp15-som.dtsi

Specific to u-boot:

phycore-stm32mp1-x-u-boot.dtsi

phycore-stm32mp1-common-u-boot.dtsi

Specific to u-boot:

phycore-stm32mp15-ddr3-x-y-z.dtsi (same as TF-A)

phycore-stm32mp15-pinctrl.dtsi

(copied from kernel)

same dtsi files as kernel (copied from kernel)

same dtsi files as kernel (copied from kernel)

TF-Afdtsphycore-stm32mp1-x.dts

Copied from kernel:

phycore-stm32mp1-x.dts

Partially copied from kernel:

phycore-stm32mp15-som.dtsi

Specific to TF-A:

phycore-stm32mp15-ddr3-x-y-z.dtsi (same as u-boot)

phycore-stm32mp15-pinctrl.dtsi

-

-

(1) : dedicated device tree configuration for Cortex-M4 examples, which allows the allocation of peripherals and pins assignments related to M4 examples. By default, this device tree is not used by the kernel, but it can be loaded instead of the default one, selecting the boot mode phycore-stm32mp1-x-m4-examples during the U-Boot stage.

(2) : dedicated device tree configuration for Cortex-A7 examples, which allows the allocation of peripherals and pins assignments related to A7 examples. By default, this device tree is not used by the kernel, but it can be loaded instead of the default one, selecting the boot mode phycore-stm32mp1-x-a7-examples during the U-Boot stage.

Tip

Creating Custom Yocto Layer

Creating your layer should be one of the first tasks when customizing the BSP. In the following chapter, we have an embedded project called "racer" which we will implement using the OpenSTLinux distribution. First, we need to create a new layer. Yocto provides a script for that. If you set up the BSP and the shell is ready, type:

host:~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-<MACHINE>$ bitbake-layers create-layer meta-racer

The default options are fine for now. Move the layer to the source directory:

host:~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-<MACHINE>$ mv meta-racer ../layers/

Create a Git repository in this layer to track your changes:

host:~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-<MACHINE>$ cd ../layers/meta-racer
host:~/PHYTEC_STM32MP1_BSP/layers/meta-racer$ git init && git add . && git commit -s -m "create meta-racer"

Now you can add the layer directly to your build-<DISTRO>-<MACHINE>/conf/bblayers.conf:

BBLAYERS += "${OEROOT}/layers/meta-racer"

or with a script provided by Yocto:

host:~/PHYTEC_STM32MP1_BSP/layers/meta-racer$ cd ../../build-<DISTRO>-<MACHINE>
host:~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-<MACHINE>$ bitbake-layers add-layer ../layers/meta-racer

Configure the Kernel through Menuconfig

The process of building a kernel has two parts: configuring the kernel options and building the source with those options. For your BSP customization, you may have to change the kernel options. This section describes how to do it.

  • Start the Linux kernel configuration menu:
host:~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-<MACHINE>$ bitbake linux-stm32mp -c menuconfig
  • Navigate forward or backward directly between feature
    • un/select, modify feature(s) you want
    • When the configuration is OK: exit and save the new configuration

Tip

useful Menuconfig keys to know:
enter: enter in config subdirectory
space: hit several times to either select [*], select in module [m], or unselect [ ] 
/: to search for a keyword, this is useful to navigate in the tree
?: to have more information on the selected line

  • After saving et exiting the menuconfig, the kernel the modifications made are only temporary. Only the kernel configuration file (.config) in the kernel build directory is updated. It is located under:
host:~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-<MACHINE>/tmp-glibc/work/<MACHINE>-ostl-linux-gnueabi/linux-stm32mp/<x.y>-r0/build/
  • Your modifications will be taken into account if the kernel is rebuilt from this point (without clean), but it will not be permanent (not in the Linux Kernel source directory). To save it, create a new configuration fragment that will contain only your configuration changes:
host:~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-<MACHINE>$ bitbake linux-stm32mp -c diffconfig
  • The fragment is generated under:
host:~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-<MACHINE>/tmp-glibc/work/phycore_stm32mp1_x-ostl-linux-gnueabi/linux-stm32mp/<x.y>-r0/fragment.cfg
  • You can temporarily save and rename this fragment to your home folder (for example):
host:~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-<MACHINE>$ cp tmp-glibc/work/phycore_stm32mp1_x-ostl-linux-gnueabi/linux-stm32mp/<x.y>-r0/fragment.cfg ~/<custom-fragment>.cfg
host:~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-<MACHINE>$ bitbake linux-stm32mp -c cleansstate

With this clean, when using bitbake diffconfig command again, it will generate a new fragment comparing the new changes made from the default Linux Kernel configuration. 

Patch Kernel, Bootloader, or Trusted Firmware

Modify the Sources with devtool

Instead of using the standard PHYTEC versions of kernel, bootloader, or trusted firmware which are provided in the Yocto recipes, you can modify the source code to build your customized BSP.

Modifying the kernel device tree is necessary when enabling/disabling dts expansions for the phyBOARD-Sargas (for example when enabling one display interface or expansion boards).  It is also necessary when customizing your own application/baseboard (ex: pin muxing modification). 

Devtool is a set of helper scripts to enhance the user workflow of Yocto. It is available as soon as you set up your shell environment. Devtool can be used to:

  • modify existing sources
  • integrate software projects into your build setup
  • build software and deploy software modifications to your target

Devtool command to modify an existing recipe:

devtool modify -x <recipename> [<directory>]
  • <recipename>: corresponding recipe names for kernel, bootloader, or trusted firmware are: 
Trusted Firmwaretf-a-stm32mp
Bootloaderu-boot-stm32mp
Kernellinux-stm32mp
  • <directory>: optional parameter to specify the path where the source files will be located. If not specified, the following subdirectory will be created and used: ~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-<MACHINE>/workspace/sources

Example for modifying the kernel:

host:~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-<MACHINE>$ devtool modify -x linux-stm32mp sources/linux-stm32mp

Devtool will create a new Yocto layer in /build-openstlinuxweston-<MACHINE>/workspace where you can see all modifications done by devtool. It will extract the sources corresponding to the recipe to the specified directory. In this example kernel sources will be extracted on the following local git directory: /build-openstlinuxweston-<MACHINE>/sources/linux-stm32mp

bbappend file will be created in the workspace directing the SRC_URI to this directory. Building an image with Bitbake will now use the sources in this directory. Now you can do your kernel, u-boot, or trusted-firmware modifications.

Example of modifying a kernel device tree file:

host:~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-<MACHINE>$ vim sources/linux-stm32mp/arch/arm/boot/dts/phycore-stm32mp1-3.dtsi

Make a change in the dts file with your favorite code editor. When it is done, refer to the next sections for re-building the BSP:

If you want to store your code changes permanently, it is advisable to create a patch from the changes, then store and backup only the patch. You can go into the linux-stm32mp directory and create a patch with the method described in the section Creating Patches.

Updating the kernel/device Tree on a Running Target (Temporary Method)

After modifying the device tree kernel and/or kernel configuration, you can test your modifications on your running target with the following quick but temporary method (to use for prototyping only).

  • Rebuild kernel/device tree:
host:~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-<MACHINE>$ bitbake linux-stm32mp

This command will generate a new Kernel Image (uImage) and new device tree blob (<MACHINE>.dtb) under the binaries folder (tmp-glibc/deploy/images/<MACHINE>)

host:~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-<MACHINE>$ scp tmp-glibc/deploy/images/<MACHINE>/<MACHINE>.dtb root@<Target_IP>:/boot

Example:

host:~/PHYTEC_STM32MP1_BSP/build-openstlinuxweston-phycore-stm32mp$ scp tmp-glibc/deploy/images/phycore-stm32mp-3/phycore-stm32mp-3.dtb root@192.168.7.1:/boot
  • For kernel update: copy the new kernel image (uImage) to the /boot directory of the target:
host:~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-<MACHINE>$ scp tmp-glibc/deploy/images/<MACHINE>/uImage root@<Target_IP>:/boot

Example:

host:~/PHYTEC_STM32MP1_BSP/build-openstlinuxweston-phycore-stm32mp$ scp tmp-glibc/deploy/images/phycore-stm32mp-3/uImage root@192.168.7.1:/boot
  • Reboot the board with the following commands on target:
root@phycore-stm32mp1-3:~# cd /boot; sync; systemctl reboot

Rebuilding the Kernel, Bootloader, or Trusted Firmware

Launch the following command to re-start the BSP image build process (only the modules that have been modified will be re-generated; the kernel for example).

host:~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-<MACHINE>$ bitbake <BSP_IMAGE>

For quick build tests, you may also want to build only the module you have modified (kernel, bootloader, or trusted firmware), as described in the following sections.

Tip

We recommend rebuilding the entire BSP image as described above, so that all necessary BSP binaries are generated, before flashing the target.

Rebuild the Kernel

To rebuild the kernel only, launch the following command:

host:~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-<MACHINE>$ bitbake linux-stm32mp

Rebuild the Bootloader

To rebuild the bootloader only, launch the following command:

host:~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-<MACHINE>$ bitbake u-boot-stm3mp

Rebuild the Trusted Firmware

To rebuild the trusted firmware only, launch the following command:

host:~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-<MACHINE>$ bitbake tf-a-stm32mp

Creating Patches

You have to create the patch from the local git directory containing the modified source code (directory created by devtool).

Example to Create a Kernel Patch

  • Enter to the <local git directory>:
host:~/PHYTEC_STM32MP1_BSP/build-openstlinuxweston-phycore-stm32mp1-3$ cd sources/linux-stm32mp 
host:<local git directory>$ cd sources/linux-stm32mp
host:<local git directory>$ git status                        # Show changes files
host:<local git directory>$ git diff                          # Show all the changes made compared to the previous commit
host:<local git directory>$ git add .                         # Add all modified file to the staging area
host:<local git directory>$ git commit -m "DTS modification"  # Creates a commit with a not so useful commit message
host:<local git directory>$ git format-patch -1 -o ~/         # Creates a patch of the last commit and saves it in you home directory
/home/<user>/0001-DTS-modification.patch

The created patch is the home directory: host:~/0001-DTS-modification.patch.

Applying Patches

The created patches can be used once you have validated your device tree modifications (using devtool for example) and you want to customize the BSP by adding a custom Yocto layer (how to create a Yocto layer is described in Creating Custom Yocto Layer). 

Tip

It is possible to add your patches directly in the meta-phytec layer, but it is not recommended to do this, as it is easier to maintain your custom BSP if you have your own Yocto layer (particularly when we deliver BSP updates).


Warning

Before being able to apply any patch to a recipe, the recipe must be removed from the devtool workspace. To do that, use the following command (example for linux-stm32mp recipe):

devtool reset linux-stm32mp

This will remove the linux-stm32mp.bbappend file created by devtool in ../build-<DISTRO>-<MACHINE>/workspace/appends

Then clean the recipe build

bitbake linux-stm32mp -c cleansstate

After you have created the kernel patch, you must create a .bbappend file in your custom layer. The locations for the append recipes are:

recipe (.bb) to append.bbappend file path in custom layer to create
linux-stm32mp.bblayers/<custom_layer>/recipes-kernel/linux/linux-stm32mp_%.bbappend
u-boot-stm32mp.bblayers/<custom_layer>/recipes-bsp/u-boot-stm32mp/u-boot-stm32mp_%.bbappend
tf-a-stm32mp.bblayers/<custom_layer>/recipes-bsp/trusted-firmware-a/tf-a-stm32mp_%.bbappend

The following example is for the linux-stm32mp recipe. You have to adjust the paths:

  • Create the folders and move the patch into it. Then create the bbappend file:
host:~/PHYTEC_STM32MP1_BSP/$ mkdir -p layers/meta-custom/recipes-kernel/linux/features                          # create the directories
host:~/PHYTEC_STM32MP1_BSP/$ cp ~/0001-DTS-modification.patch layers/meta-custom/recipes-kernel/linux/features  # copy patch in the features directory
host:~/PHYTEC_STM32MP1_BSP/$ touch layers/meta-custom/recipes-kernel/linux/linux-stm32mp_%.bbappend             # create a bbappend file

Warning

Pay attention to your current work directory. You have to execute the above commands in the BSP top-level directory. Not in the build directory!

  • Use your favorite editor to add the following lines into the bbappend file (layers/meta-custom/recipes-kernel/linux/linux-stm32mp_%.bbappend):
FILESEXTRAPATHS_prepend := "${THISDIR}/features:"
SRC_URI_append = " \
file://0001-DTS-modification.patch \
"
  • Save the file, go back to the build directory and rebuild the kernel recipe with:
host:~/PHYTEC_STM32MP1_BSP/$ cd build-<DISTRO>-<MACHINE>
host:~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-<MACHINE>$ bitbake linux-stm32mp -c cleansstate
host:~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-<MACHINE>$ bitbake linux-stm32mp
  • If the build is successful, you can then rebuild the entire image (st-image-weston for example).

Adding Kernel Configuration Fragment

After creating one or more kernel configuration file (.cfg) with menuconfig and diffconfig bitbake commands (Configure the kernel through Menuconfig), you have to add them in the linux-stm32mp_%.bbappend recipe of your customer Yocto layer, so that it will be included in the final generated Kernel configuration file (.config file in the Kernel build directory).

Tip

It is possible to add your kernel config fragment files directly in the meta-phytec layer, but it is no recommended to do this, as it is easier to maintain your custom BSP if you have your own Yocto layer (particularly when we deliver BSP updates).

  • If not already done, you must create a linux-stm32mp_%.bbappend file in your custom layer:

Replace <x.y> below with the kernel version x.y (ex: 5.4).

host:~/PHYTEC_STM32MP1_BSP/$ mkdir -p layers/meta-custom/recipes-kernel/linux/features/<x.y>                     # create the directories
host:~/PHYTEC_STM32MP1_BSP/$ touch layers/meta-custom/recipes-kernel/linux/linux-stm32mp_%.bbappend             # create a bbappend file

  • Copy your config fragment file (<custom-fragment>.cfg) into the features/<x.y> directory (ex: features/4.19):
host:~/PHYTEC_STM32MP1_BSP/$ cp ~/<custom-fragment>.cfg layers/meta-custom/recipes-kernel/linux/features/<x.y>  # copy fragment in the features directory

Warning

Pay attention to your current work directory. You have to execute the above commands in the BSP top-level directory. Not in the build directory!

  • Use your favorite editor to add the following lines into the bbappend file (layers/meta-custom/recipes-kernel/linux/linux-stm32mp_%.bbappend):
FILESEXTRAPATHS_prepend := "${THISDIR}/features:"

SRC_URI += "file://${LINUX_VERSION}/custom-fragment.cfg;subdir=fragments"
KERNEL_CONFIG_FRAGMENTS += "${WORKDIR}/fragments/${LINUX_VERSION}/custom-fragment.cfg"
  • Save the file, go back to the build directory and rebuild the kernel recipe with:
host:~/PHYTEC_STM32MP1_BSP/$ cd build-<DISTRO>-<MACHINE>
host:~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-<MACHINE>$ bitbake linux-stm32mp -c cleansstate
host:~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-<MACHINE>$ bitbake linux-stm32mp
  • If the build is successful, you can then rebuild the st-image-bootfs partition (containing the kernel and device tree) or the entire image (st-image-weston for example).

OpenSTLinux Yocto SDK

When a Yocto distribution has been modified and validated on target, it is pertinent to build a new Software Development Kit that integrates the modifications and to redistribute this SDK to developers.

This chapter describes the procedure to build, install and use the SDK.

For  more details on the OpenSTLinux SDK, please refer to https://wiki.st.com/stm32mpu/wiki/SDK_for_OpenSTLinux_distribution

How to Build the SDK

To build the SDK, first, if not already done, initialize the OpenEmbedded Environment for the phyCORE-STM32MP1 BSP (refer to: OpenEmbedded Environment Setup). Then launch the following bitbake command:

bitbake -c populate_sdk <image>

With  <image> =  Image name (example: st-image-weston)

Example:

host:~/PHYTEC_STM32MP1_BSP/build-openstlinuxweston-phycore-stm32mp1-3$ bitbake -c populate_sdk st-image-weston

The SDK installation files  are deployed into the following output directory: build-<DISTRO>-<MACHINE>/tmp-glibc/deploy/sdk/ :

host:~/PHYTEC_STM32MP1_BSP/build-openstlinuxweston-phycore-stm32mp1-3$ cd tmp-glibc/deploy/sdk
host:~/PHYTEC_STM32MP1_BSP/build-openstlinuxweston-phycore-stm32mp1-3/tmp-glibc/deploy/sdk$ ls -l
total 955772
-rw-r--r-- 1 cparant cparant 11572 Feb 3 11:38 st-image-weston-openstlinux-weston-phycore-stm32mp1-3-x86_64-toolchain-3.1-snapshot.host.manifest
-rw-r--r-- 1 cparant cparant 21707 Feb 3 11:38 st-image-weston-openstlinux-weston-phycore-stm32mp1-3-x86_64-toolchain-3.1-snapshot.license
-rw-r--r-- 1 cparant cparant 575516 Feb 3 11:58 st-image-weston-openstlinux-weston-phycore-stm32mp1-3-x86_64-toolchain-3.1-snapshot-license_content.html
-rwxr-xr-x 1 cparant cparant 977377750 Feb 3 11:57 st-image-weston-openstlinux-weston-phycore-stm32mp1-3-x86_64-toolchain-3.1-snapshot.sh
-rw-r--r-- 1 cparant cparant 157514 Feb 3 11:37 st-image-weston-openstlinux-weston-phycore-stm32mp1-3-x86_64-toolchain-3.1-snapshot.target.manifest
-rw-r--r-- 1 cparant cparant 549110 Feb 3 11:37 st-image-weston-openstlinux-weston-phycore-stm32mp1-3-x86_64-toolchain-3.1-snapshot.testdata.json

The main final output is the cross-development toolchain installation shell script : <image>-<distro>-<machine>-<host machine>-toolchain-<Yocto release>-snapshot.sh

with:

<host machine>: Host machine on which the SDK is generated: x86_64 (the only supported value)

<Yocto release>: Release number of the Yocto Project; here it is Yocto 3.1 (dunfell)

For more details, refer to: https://wiki.st.com/stm32mpu/wiki/How_to_create_an_SDK_for_OpenSTLinux_distribution

How to Install the SDK

Execute the cross-development toolchain installation shell script, as follow:

host:~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-<MACHINE>$ ./st-image-weston-openstlinux-weston-phycore-stm32mp1-3-x86_64-toolchain-3.1-snapshot.sh -d ../../../SDK
This will install the SDK into ~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-<MACHINE>/SDK, but it can be installed into any other location.

When installation is finished and successfull, the following log should appears:
ST OpenSTLinux - Weston - (A Yocto Project Based Distro) SDK installer version 3.1-snapshot
===========================================================================================
You are about to install the SDK to "<user_path>/PHYTEC_STM32MP1_BSP/build-openstlinuxweston-phycore-stm32mp1-3/SDK". Proceed [Y/n]? y
Extracting SDK..................................................................................................................................................................................................................done
Setting it up...done
SDK has been successfully set up and is ready to be used.
Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g.
 $ . <user_path>/PHYTEC_STM32MP1_BSP/build-openstlinuxweston-phycore-stm32mp1-3/SDK/environment-setup-cortexa7t2hf-neon-vfpv4-ostl-linux-gnueabi

How to use the SDK in a Linux Terminal

If you want to cross-compile your application project into a Linux terminal, you have to start the SDK, using the following command:

host:$ source <SDK installation directory>/environment-setup-cortexa7t2hf-neon-vfpv4-ostl-linux-gnueabi

Note that the SDK environment setup script must be run once in each new working terminal in which you cross-compile.

The following checking list allows you to ensure that the environment is correctly setup:

  • Check the target architecture:
host:$ echo $ARCH
arm
  • Check the toolchain binary prefix for the target tools:
host:$ echo $CROSS_COMPILE
arm-ostl-linux-gnueabi-
  • Check the C compiler version:
host:$ $CC --version
arm-ostl-linux-gnueabi-gcc (GCC) <GCC version>
[...]
  • Check that the SDK version is the expected one:
host:$ echo $OECORE_SDK_VERSION
<expected SDK version>

If any of these commands fails or does not return the expected result, please try to reinstall the SDK.

Tip

Once the SDK is installed, it is easy to develop a userspace application outside of the OpenEmbedded build system. There are different three ways to use the SDK toolchain within a terminal:

  • command line
  • makefile-based project
  • autotools-based project

Whatever the method, it relies on:

  • the sysroot that is associated with the cross-toolchain, and that contains the header files and libraries needed for generating binaries (see target sysroot)
  • the environment variables created by the SDK environment setup script (see SDK startup)

You can refer to the following simple example: Addition of a "hello world" userspace application: https://wiki.st.com/stm32mpu/wiki/How_to_cross-compile_with_the_Developer_Package#Adding_a_.22hello_world.22_user_space_example

How to Use the SDK with STM32CubeIDE

STM32CubeIDE can be used for Cortex-A7 or Cortex-M4 application development purposes.

For more details on the STM32CubeIDE tool, please refer to STM32CubeIDE Development Tool

To know how to use the SDK to debug Linux userspace application, please refer to How to debug a Linux user space application (Cortex-A7)

The STM32CubeMX Tool

STM32CubeMX is an official STMicroelectronics graphical software configuration tool that allows, among others features, to:

  • configure pin assignments, the clock tree, or internal peripherals
  • generate the device tree for a Linux kernel, TF-A, and U-Boot firmware for Cortex-A7
  • generate HAL initialization code for Cortex-M4

For more details on these and other features, go to https://wiki.st.com/stm32mpu/wiki/STM32CubeMX

To install the tool and get the user manual: https://www.st.com/en/development-tools/stm32cubemx.html

Using STM32CubeMX to Generate Device Tree

STM32CubeMX can be used to generate the device tree files for a given project:

  • It generates one unique <soc>-<project>-mx.dts file (containing all the custom board DTS configuration) per sotware components (Kenel, U-boot and TF-A). This .dts includes the upstream specific SoC dtsi files (Soc, SoC extension and SoC package Pincontrol).
  • For U-boot, it also generates u-boot board specificdtsi file: <soc>-<project>-mx-u-boot.dtsi
  • For U-boot and TF-A , it also generates DDR configurationdtsi file: stm32mp15-mx.dtsi (included in <soc>-<project>-mx.dts for TF-A and in <soc>-<project>-mx-u-boot.dtsi for U-boot)

For more details of the generated dtsi files for each component, refer to https://wiki.st.com/stm32mpu/wiki/STM32MP15_device_tree (STM32CubeMX generated device tree section).

Tip

PHYTEC provides STM32CubeMX project of the phyCORE-STM32MP1 SOM (NAND version or eMMC version) as well as the project of the phyBOARD-Sargas (including phyCORE-STM32MP1). Those projects can be download at https://www.phytec.de/produkt/system-on-modules/phycore-stm32mp15x-download/#CubeMX. For device tree generation, you can follow the next section.

Add phyCORE-STM32MP1 and phyBOARD Device Tree User Code Templates

As the generated device tree files do not contain all the necessary device tree properties (dependent on BSP drivers), some manual code ("User code") needs to be added in specific sections of the generated files.

To be able to build the BSP with the device tree generated from the phyCORE-STM32MP1/phyBOARD-Sargas STM32CubeMX project, we also provide .dts templates. Those are the generated device tree from the STM32CubeMX project in which we have added the necessary user code, (adding some device tree properties) so to build the BSP image with it.

The templates that we provide are inside the downloaded CubeMX project archive, under DTS_templates directory. This directory containing .dts files that are the device tree templates.

The dts templates contain some user code section like these:

In the device tree root:

/* USER CODE BEGIN root */

/* USER CODE END root */

In each device tree specific <node>:

/* USER CODE BEGIN <node> */

/* USER CODE END <node> */

Those different sections can be parsed by the STM32Cube generator and then be automatically added into the generated DTS files.

To know how to force STM32CubeMX to use those templates during the code generation, refer to the Phytec-CubeMX_info.txt file located in the downloaded CubeMX project archive.

How to Use the Cortex-M4 MCU

The Arm® Cortex®-M4 coprocessor and its peripherals are directly inherited from the STM32 MCU family. STM32Cube™ environment that is usually used for STM32 MCU is also used for the STM32MP1.

STM32Cube™ provides comprehensive embedded software libraries and tools, significantly reducing development effort, time, and cost. It is fully integrated in the STM32MPU Embedded Software distribution (https://wiki.st.com/stm32mpu/wiki/STM32MPU_Embedded_Software_distribution) thanks to the STM32CubeMP1 Firmware Package and tools such as  STM32CubeMX, STM32CubeIDE, or STM32CubeProgrammer.

STM32CubeMP1‎ Overview

STM32CubeMP1‎ is the embedded software part of STM32Cube™, running on the Arm® Cortex®-M4 processor. It is based on the STM32Cube MCU package but has been adapted to a Linux Framework (OpenSTLinux).

  • To get an overview of this package, use the following links:

https://wiki.st.com/stm32mpu/wiki/STM32CubeMP1_Package

https://wiki.st.com/stm32mpu/wiki/STM32CubeMP1_architecture

In our PHYTEC git repository, the "master" branch is a clone from the last official version of STM32CubeMP1ST (from STM Github). In the "1.3.0-phy" branch we have added additional components for the phyBOARD-Sargas development board specifics, so to provide some STM32CubeM1 examples running on our development board.

Those additional components are the following:

  • Drivers/BSP/STM32MP15xx_phyBOARD-Sargas
  • Projects/STM32MP15-phyBOARD-Sargas
    • Applications
      • OpenAMP/OpenAMP_TTY_echo

      • OpenAMP/OpenAMP_raw
    • Demonstrations
      • AI_Character_Recognition (=> this application can be run using the GTK demo launcher of the Weston image)
    • Examples
      • GPIO/GPIO_EXTI
      • UART/UART_Receive_Transmit_Console
    • Templates

The above projects are provided as examples. They are copied from "Projects/STM32MP157C-DK2" but with little adaptations for the phyBOARD-Sargas and can be used with the STM32MP1CubeIDE development tool.

The above project from Applications and Examples directories are by default build and deployed on target within our BSP image, so they can be run from Linux userspace (refer to next section: How to run Cortex-M4 examples on target).

Tip

Other M4 applications (like CoproSync or FreeRTOS) or M4 examples (like I2C, ADC, Crypto, Timers...) can be found on Projects/STM32MP157C-DK2 (or Projects/STM32MP157C-EV1) and can be easily adapted to the phyBOARD-Sargas or a custom board if needed.

Coprocessor Management with STM32Cube‎MP1 and Linux

In order to manage the coprocessor system, services are proposed relying on the open-source Linux RemoteProc framework and the RPMsg frameworks.

Overview

For an overview, go to https://wiki.st.com/stm32mpu/wiki/Coprocessor_management_overview.

Linux Coprocessor Management

Information on the Linux coprocessor management software frameworks such as mailbox and RPMsg:

https://wiki.st.com/stm32mpu/wiki/Linux_Mailbox_framework_overview

https://wiki.st.com/stm32mpu/wiki/Linux_remoteproc_framework_overview

https://wiki.st.com/stm32mpu/wiki/Linux_RPMsg_framework_overview

Others Coprocessor Management Information

https://wiki.st.com/stm32mpu/wiki/Coprocessor_management_troubleshooting_grid

https://wiki.st.com/stm32mpu/wiki/Coprocessor_power_management

https://wiki.st.com/stm32mpu/wiki/Coprocessor_resource_table

https://wiki.st.com/stm32mpu/wiki/Exchanging_buffers_with_the_coprocessor

https://wiki.st.com/stm32mpu/wiki/Resource_manager_for_coprocessing

STM32CubeMP1‎ Development Guidelines

https://wiki.st.com/stm32mpu/wiki/STM32CubeMP1_development_guidelines

How to‎...

How to Run Cortex-M4 Examples on Target

1. Select boot mode for m4 examples:

When booting the Linux image, select the dedicated device tree configuration for m4 examples. This device tree allows the allocation of specific IP, clock, and pin control assignments related to M4 examples.

To do that, select the boot mode phycore-stm32mp1-4-m4-examples during the U-Boot stage (boot mode number 3), as described in the following log:

U-Boot 2020.01-stm32mp-r2.1 (Jan 06 2020 - 20:56:31 +0000)

CPU: STM32MP157FAC Rev.Z
Model: Phytec GmbH phycore-stm32mp1-4 Dev Board
Board: stm32mp1 in trusted mode (phycore-stm32mp1-4)
...
...
Found /mmc1_extlinux/phycore-stm32mp1-4_extlinux.conf
Retrieving file: /mmc1_extlinux/phycore-stm32mp1-4_extlinux.conf
851 bytes read in 20 ms (41 KiB/s)
Retrieving file: /splash.bmp
18244 bytes read in 21 ms (847.7 KiB/s)
Select the boot mode
1: OpenSTLinux
2: phycore-stm32mp1-4-a7-examples
3: phycore-stm32mp1-4-m4-examples
Enter choice:
Select the boot mode
1:      OpenSTLinux
2:      phycore-stm32mp1-4-a7-examples
3:      phycore-stm32mp1-4-m4-examples
Enter choice:


Note

phycore-stm32mp1-4-m4-examples.dts kernel device tree allows you to define peripherals and pins that are assigned to the Cortex-M4. In this device tree example, a bunch of peripherals and pins are assigned to the cortex-M4 to be able to run the STM32CubeMP1 examples (avoiding conflicts with Linux).

2. Select examples or applications to run:

root@phycore-stm32mp1-4:~# cd /usr/local/Cube-M4-examples/STM32MP15-phyBOARD-Sargas
  • For an Example use the following command:

cd /usr/local/Cube-M4-examples/STM32MP15-phyBOARD-Sargas/Examples/<example_type>/<example_to_run>

  • For an Application use the following command:

cd /usr/local/Cube-M4-examples/STM32MP15-phyBOARD-Sargas/Applications/<application_type>/<application_to_run>

In each of those directories, following files are present:

  • fw_cortex_m4.sh: script to start / stop firmware
  • README: all information about the application/example
  • lib/firmware/<example_or_application_to_run>.elf: Cortex-M4 firmware of the application/example to run

Example :

root@phycore-stm32mp1-4:/usr/local/Cube-M4-examples/STM32MP15-phyBOARD-Sargas/Examples/GPIO/GPIO_EXTI# ls -l
total 8
-rwxr-xr-x 1 root root 4263 Sep 23  2020 README
-rwxr-xr-x 1 root root 1084 Sep 23  2020 fw_cortex_m4.sh
drwxr-xr-x 3 root root 1024 Sep 23  2020 lib
root@phycore-stm32mp1-4:/usr/local/Cube-M4-examples/STM32MP15-phyBOARD-Sargas/Examples/GPIO/GPIO_EXTI# ls -l lib/firmware/
total 4
-rwxr-xr-x 1 root root 68004 Sep 23 2020 GPIO_EXTI.elf

3. Start the firmware:

Use the following command to start the selected example:

./fw_cortex_m4.sh start

Example:

root@phycore-stm32mp1-4:/usr/local/Cube-M4-examples/STM32MP15-phyBOARD-Sargas/Examples/GPIO/GPIO_EXTI# ./fw_cortex_m4.sh start
fw_cortex_m4.sh: fmw_name=GPIO_EXTI.elf
[ 72.909122] remoteproc remoteproc0: powering up m4
[ 72.913032] remoteproc remoteproc0: Booting fw image GPIO_EXTI.elf, size 68004
[ 72.919852] remoteproc remoteproc0: header-less resource table
[ 72.925647] remoteproc remoteproc0: no resource table found for this firmware
[ 72.932696] remoteproc remoteproc0: header-less resource table
[ 73.012111] rproc-srm-core mlahb:m4@10000000:m4_system_resources: bound mlahb:m4@10000000:m4_system_resources:serial@4000f000 (ops 0xc0cfd7e4)
[ 73.038917] rproc-srm-core mlahb:m4@10000000:m4_system_resources: bound mlahb:m4@10000000:m4_system_resources:i2c@40012000 (ops 0xc0cfd7e4)
[ 73.068431] rproc-srm-core mlahb:m4@10000000:m4_system_resources: bound mlahb:m4@10000000:m4_system_resources:dac@40017000 (ops 0xc0cfd7e4)
[ 73.079861] rproc-srm-core mlahb:m4@10000000:m4_system_resources: bound mlahb:m4@10000000:m4_system_resources:timer@44000000 (ops 0xc0cfd7e4)
[ 73.092382] rproc-srm-core mlahb:m4@10000000:m4_system_resources: bound mlahb:m4@10000000:m4_system_resources:spi@44004000 (ops 0xc0cfd7e4)
[ 73.104798] rproc-srm-core mlahb:m4@10000000:m4_system_resources: bound mlahb:m4@10000000:m4_system_resources:dma@48001000 (ops 0xc0cfd7e4)
[ 73.117427] rproc-srm-core mlahb:m4@10000000:m4_system_resources: bound mlahb:m4@10000000:m4_system_resources:adc@48003000 (ops 0xc0cfd7e4)
[ 73.129877] rproc-srm-core mlahb:m4@10000000:m4_system_resources: bound mlahb:m4@10000000:m4_system_resources:hash@4c002000 (ops 0xc0cfd7e4)
[ 73.142468] rproc-srm-core mlahb:m4@10000000:m4_system_resources: bound mlahb:m4@10000000:m4_system_resources:rng@4c003000 (ops 0xc0cfd7e4)
[ 73.154978] rproc-srm-core mlahb:m4@10000000:m4_system_resources: bound mlahb:m4@10000000:m4_system_resources:crc@4c004000 (ops 0xc0cfd7e4)
[ 73.167518] rproc-srm-core mlahb:m4@10000000:m4_system_resources: bound mlahb:m4@10000000:m4_system_resources:cryp@4c005000 (ops 0xc0cfd7e4)
[ 73.180131] rproc-srm-core mlahb:m4@10000000:m4_system_resources: bound mlahb:m4@10000000:m4_system_resources:button (ops 0xc0cfd7e4)
[ 73.192099] rproc-srm-core mlahb:m4@10000000:m4_system_resources: bound mlahb:m4@10000000:m4_system_resources:m4_led (ops 0xc0cfd7e4)
[ 73.204291] remoteproc remoteproc0: remote processor m4 is now up

The effects of these commands are:

  • The remote processor system resource manager (rproc_srm) assign and configure the system resources of peripherals/pins assigned to the Cortex-M4 coprocessor (peripherals/pins that must be assigned to the Cortex-M4 are set in the Linux device tree)
  • The Linux Remote Processor (remoteproc) loads and starts the M4 firmware.

4. Stop the firmware:

Use the following command to stop the example that is running:

./fw_cortex_m4.sh stop

Example:

root@phycore-stm32mp1-4:/usr/local/Cube-M4-examples/STM32MP15-phyBOARD-Sargas/Examples/GPIO/GPIO_EXTI# ./fw_cortex_m4.sh stop
fw_cortex_m4.sh: fmw_name=GPIO_EXTI.elf
[ 4296.915003] remoteproc remoteproc0: warning: remote FW shutdown without ack
[ 4296.920578] remoteproc remoteproc0: stopped remote processor m4

This stops the firmware using the Linux Remote Processor component (remoteproc). It releases the relevant resource settings used by the example.

How to start the coprocessor from the bootloader

https://wiki.st.com/stm32mpu/wiki/How_to_start_the_coprocessor_from_the_bootloader

How to protect the processor firmware

https://wiki.st.com/stm32mpu/wiki/How_to_protect_the_coprocessor_firmware

How to assign an internal peripheral to a runtime context

https://wiki.st.com/stm32mpu/wiki/How_to_assign_an_internal_peripheral_to_a_runtime_context

How to configure system resources

https://wiki.st.com/stm32mpu/wiki/How_to_configure_system_resources

How to exchange large data buffers with the coprocessor - principle

https://wiki.st.com/stm32mpu/wiki/How_to_exchange_large_data_buffers_with_the_coprocessor_-_principle

How to retrieve Cortex-M4 logs after crash

https://wiki.st.com/stm32mpu/wiki/How_to_retrieve_Cortex-M4_logs_after_crash

STM32CubeIDE Development Tool

STM32CubeIDE is an advanced C/C++ development platform with peripheral configuration, code generation, code compilation, and debug features for STM32 microcontrollers and microprocessors. To know how to install and use this tool please refer to: https://wiki.st.com/stm32mpu/wiki/STM32CubeIDE

How to Debug a Linux userspace Application (Cortex-A7)

Prerequisite:  SDK must have been installed as described in the section OpenSTLinux Yocto SDK

Please refer to the following link to know how to create a "userspace" project and debug it with STM32CubeIDE:

https://wiki.st.com/stm32mpu/wiki/How_to_debug_a_user_space_application_with_STM32CubeIDE

How to Create a Cortex-M4 Project

They are several ways to create a STM32CubeIDE project for Cortex-M4 application development, among the following methods:

Generate a new project from a STM32CubeMX project (.ioc)

This is ideal when you have configured your platform with this tool (for the pin muxing and clock configuration). In this case, there are two methods to generate the STM32CubeIDE project:

    • 1st method, use STM32CubeIDE : File → New → STM32 from an Existing STM32CubeMX Configuration File
    • 2nd method, use STM32CubeMX code generator tool to create the STM32CubeIDE project:
      • Open your STM32CubeMX project with the STM32CubeMX tool
      • Project Manager → Project → Toolchain / IDE: must be is set to STM32CubeIDE
      • Generate Code => thiswill create a STM32CubeIDE project with some codes (HAL/Middleware code for M4  / device tree for A7) corresponding to your CubeMX project configuration
      • The newly generated project can be opened in STM32CubeIDE: File →  New → Open Projects from File System..

Using the Template project provided in the STM32CubeMP1 package

A template of STM32CubeIDE projectfor Cortex-M4 is provided in the STM32CubeMP1 packageunder Projects/STM32MP15-phyBOARD-Sargas/Templates (refer to STM32CubeMP1 Overview). You can direcly create your own project using this template:

    • File →  New → Open Projects from File System..

From an existing SW4STM32 IDE project

Please refer to the following page:https://wiki.st.com/stm32mpu/wiki/How_to_move_from_SW4STM32_to_STM32CubeIDE

From scratch

Specific Tool Configuration for the phyBOARD-Sargas

Use external JTAG

As the phyBOARD-Sargas is not equipped with STLINK serial link / debug feature, a STLINK external JTAG (STLINK/V2 or STLINK-V3SET) or SEGGER J-LINK connected to the JTAG connector (X8) must be used to debug Cortex-M4 application (not needed for Linux application).

Configure the MPU Serial Device

As the phyBOARD-Sargas is equipped with an FDTI usb/serial device, the "MPU serial device" parameter of the tool must be modified as follow (on Linux computer):

  • Connect your phyBOARD serial console to your computer (X13 connector)
  • Open the Preferences menu: Window => Preferences
  • In the "Preferences" menu, open the submenu STM32Cube/MPU Serial
  • And configure the MPU serial as below ("/dev/ttyUSB0" should be in the Prefered device list):

image2020-8-7_11-24-24.png

Cortex-M4 Debug Modes

Two modes can be used to debug Arm® Cortex®-M firmware on STM32 MPU device: "Engineering mode" or "Production mode".

Production mode

Production debug mode is close to a final product. To used the Production mode, the board must be booted with the "classic" procedure (boot mode is SD CARD / eMMC / NOR / NAND for Linux booting).

In this mode, Linux must be already booted and running on the Cortex-A7. Cortex-M4 firmware is loaded from an ssh connection (through Ethernet or USB OTG) and started with the remoteproc service running on the Cortex-A7.

Engineering mode

To use the Engineering mode, the board must be booted in a specific way called "Engineering boot Mode". In this mode, only Cortex-M is started and Firmware is loaded via JTAG/SWD into its dedicated RAM.

Warning

Initialization normally done in Cortex-A7 (clock tree set-up, ...) have to be handled by Arm Cortex-M4.

Tip

Debugging in Engineering Mode with STM32 MPU device is very similar to a standard STM32 MCU debug, except that here, the Arm Cortex-M4 has only a dedicated memory, no flash memory type.

On phyBOARD-Sargas, set the S7 DIP switch as follow before powering or resetting the board to enter the Engineering mode:

How to debug a Cortex-M4 application

Engineering mode

  • To use this mode, first check that:
    • your board is correctly connected to the host PC with the JTAG
    • the  boot mode is set correctly on your board to Engineering mode (with S7 DIP switch on phyBOARD-Sargas)
    • the application to debug contains some code that configures the system clock in case the Engineering mode is detected (the examples/applications given in the STM32CubeMP1 contains this code, so you can use it as a reference).
  • To start debugging:
    • on the left Project Explorer section, click on your Project and launch the Debug Configurationmenu with RunDebug asSTM32 Cortex-M C/C++ Application
    • in the Debug Configuration menu, go to Debugger tab, select the option thru JTGA/SWD link (Engineering mode)
    • if you are using an ST-LINK, you do not have to change more options
    • click on Debug

Debug configuration setting for Engineering mode:

Production mode

  • To use this mode, first check that:
    • your board is correctly connected to the host PC with:
      • a JTAG (ST-LINK or SEGGER J-LINK)
      • a Network connection: USB OTG (Ethernet point to point) or Ethernet (IP address attributed by DHCP server or to be manually configured)
      • a Serial Link (to access the Linux remote console).
    • your board is powered on and Linux is booted and running
    • the application to debug contains some code that configures the system clock in case the Engineering mode is detected (the examples/applications given in the STM32CubeMP1 contains this code, so you can use it as a reference).

Tip

With the phyBOARD-Sargas, to create the network connection, the easiest way is it to use the USB OTG (connector X12) as it is already configured with a fix IP adress 192.168.7.1 (see Create an SSH Connection with USB OTG or Ethernet)

  • To start debugging:
    • on the left Project Explorer section, click on your Project and launch the Debug Configurationmenu with RunDebug asSTM32 Cortex-M C/C++ Application
    • in the Debug Configuration menu, go to Debugger tab, keep the default option which is: thru Linux Core (Production mode)
    • In the Connection section select the Serial Port (ex: MPU Serial (/dev/ttyUSB0)) and the Ethernet address of your target (ex: 192.168.7.1)
    • click on Debug

Debug configuration setting for production mode:

At debug launch, the following pop-up will appear:

  • a message requesting the SSH Password => User ID = "root" / no password (you can check the box "save the password", so it will not be asked again)
  • a Warning message: The RSA key has to be approved => click on "Yes"
  • a Progress bar information that informs about the firmware loading progress into the target
  • a message "Confirm Perspective switch" => click on "Switch" (you can check "remember my decision, so it will not be asked again)

When debug mode is ready, the following logs will appear in red in the console, with some information from the debugger:

Below are the 3 steps which are done to enter the Debug session in Production mode:

1. The firmware-built binary is transferred to the target through the network link (ssh protocol). It is copied in the Cortex-A Linux file system.

2. The firmware is loaded to Cortex-M core thanks to the “remoteproc” framework.

3. The Debug session is started via JTAG/SWD connection.

Basic commands to debug an application:

  • Set breakpoints to desired lines → Make sure that "Skip all breakpoints" button is not active
  • Start program and debugging with "Resume" button
  • Stop debug session with "Terminate" button


STM32MP15x Low Power Modes

Low Power Overview

https://wiki.st.com/stm32mpu/wiki/Power_overview

How to Define Your Low Power Strategy

https://wiki.st.com/stm32mpu/wiki/How_to_define_your_low-power_strategy

Revision History

VersionChangesDateAuthor
L-876e.A0Preliminary Edition11.09.2020C. Parant
L-876e.A1Update for PD21.1.002.03.2021C. Parant