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 Manual:  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.

Supported Hardware

This BSP supports the phyCORE-STM32MP15x SOM with phyBOARD-Sargas SBC. The STM32MP15x BSP is a unified BSP, which means in the future it will support 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 phyCORE-STM32MP15x Product Page (Downloads under the heading "Software Linux BSP-Releases / Software Manuals", click on the corresponding BSP release).

Example: Release page for STM32MP15x PD25.1.0 Release: BSP-Yocto-OpenSTLinux-STM32MP15x-PD25.1.0

If you choose a specific Machine Name in the section Supported Machines, you can see which Article Numbers are available under this machine and also a short description of the hardware information. In case you only have the Article Number of your hardware, you can leave the Machine Name drop-down menu empty and only choose your Article Number. Now it should show you the necessary Machine Name for your specific hardware. 

phyBOARD-Sargas Connectors

phyBOARD-Sargas Buttons, LED, and Jumpers

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).

Prebuild Images

PHYTEC provides prebuild images and release notes for the phyBOARD-Sargas-STM32MP15x. They can be downloaded here: https://download.phytec.de/Software/Linux/BSP-Yocto-STM32MP1/

Building the BSP

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

Get and Initialize the BSP Environment

To know how to get and initialize the BSP environment, please follow our Yocto OpenSTLinux Manual. In this manual, you will also find out how to choose the right OpenSTLinux Distribution and the right BSP Image for your project.

Build Process

Now that the build environment is ready, you can start the first build process, using the following command:

host:~/PHYTEC_STM32MP1_BSP/build$ bitbake <BSP_IMAGE>

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

host:~/PHYTEC_STM32MP1_BSP/build$ bitbake st-image-weston

Generated BSP Image Binaries

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

Programming the Target

Connecting the Board via USB DFU Link to use STM32MPCubeProgrammer 

STM32MPCubeProgrammer tool is used for flashing the NOR, eMMC, NAND, or SD Card.

Installing and using the tool is described in our Yocto OpenSTLinux Manual(in Programming the Target section).

To download the BSP with STM32MPCubeProgrammer, change the BOOT mode to UART/USB boot mode.

For phyBOARD-Sargas:

• 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 BSP image => The RED LED should stop blinking.

The board is now ready for programming with STM32MPCubeProgrammer.

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

When booting from an 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 can be done from a .wic file or .raw file.

Please refer to Yocto OpenSTLinux Manual to learn how to create an SD card.

System Booting

The phyCORE-STM32MP15x 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 follows: 

There are two ways to create a bootable SD card (refer to Programming the target). You can either use:

• Use a single prebuilt SD card image
  
• Use STM32MPCubeprogrammer to flash the SD card from a target

Booting from eMMC Flash

• First, you have to follow the procedure to flash the eMMC: Programming the target
  
• After flashing, power off the board. Then set the S7 DIP switch to the correct positions:

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

Booting from NOR Flash

• First, you have to follow the procedure to flash the NOR/eMMC: Programming the target
• After flashing, power off the board. Then set the S7 DIP switch to the correct positions:

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

Booting from NAND Flash

• First, you have to follow the procedure to flash the NAND: Programming the target
• After flashing, power off the board. Then set the S7 DIP switch to the correct positions: 

• 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-STM32MP15x and carrier board are configured by default with 4 UARTs:

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. To get the currently configured baud rate, you can use the command stty on the target.

Command to get tty help:

target$ tty --help

Device Tree configuration for the UARTs on phyBOARD-Sargas:https://git.phytec.de/linux-stm32mp/tree/arch/arm/boot/dts/st/stm32mp15xx-phyboard-sargas.dtsi?h=v6.6-phy#n290

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 of how to send or receive data on a SocketCAN interface using the can-utils package with the cansend and candump commands:

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"

Device Tree configuration for the FDCAN2 on phyBOARD-Sargas:https://git.phytec.de/linux-stm32mp/tree/arch/arm/boot/dts/st/stm32mp15xx-phyboard-sargas.dtsi?h=v6.6-phy#n91

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 of how to assign a given IP address to an Ethernet ETH0 interface:

ifconfig eth0 10.48.1.324

Device Tree configuration for the ETH0 interface (Ethernet PHY populated on SoM):https://git.phytec.de/linux-stm32mp/tree/arch/arm/boot/dts/st/stm32mp15xx-phycore-som.dtsi?h=v6.6-phy#n275

SD/MMC card

The STM32MP15x 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.

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 commands work as expected.

Device Tree configuration for the SDMMC1 (SD card slot on phyBOARD-Sargas):https://git.phytec.de/linux-stm32mp/tree/arch/arm/boot/dts/st/stm32mp15xx-phyboard-sargas.dtsi?h=v6.6-phy#n263

eMMC Devices

PHYTEC modules like phyCORE-STM32MP15x are populated with an e.MMC memory chip as the main storage. e.MMC devices contain raw Multi-Level Cells (MLC) or Triple-Level Cells (TLC) combined with a memory controller that handles ECC and wear leveling. They are connected via an SD/MMC interface to the STM32MP15x and are represented as block devices in the Linux kernel like SD cards, flash drives, or hard disks.

The electric and protocol specifications are provided by JEDEC (https://www.jedec.org/standards-documents/technology-focus-areas/flash-memory-ssds-ufs-emmc/e-mmc). The e.MMC manufacturer’s datasheet is relatively short and meant to be read together with the supported version of the JEDEC e.MMC standard.

PHYTEC currently utilizes the e.MMC chips with JEDEC Version 5.0 and 5.1

Device Tree configuration for the SDMMC2 (eMMC populated on SoM): https://git.phytec.de/linux-stm32mp/tree/arch/arm/boot/dts/st/stm32mp15xx-phycore-som.dtsi?h=v6.6-phy#n375

GPIOs

The phyBOARD-Sargas carrier board has a set of pins specifically dedicated to user I/Os. Those pins are connected directly to STM32MP15x balls and are used as GPIOs (default state of the STM32MP15x I/O pins if not muxed as alternate function). 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 

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

Device Tree configuration for the gpio-key on phyBOARD-Sargas:https://git.phytec.de/linux-stm32mp/tree/arch/arm/boot/dts/st/stm32mp15xx-phyboard-sargas.dtsi?h=v6.6-phy#n44

LEDs

If any LEDs are connected to GPIOs, you can access them by a special LED driver (gpio-leds) 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 dimmer present on the phyBOARD-Sargas. 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

Device Tree configuration for the leds dimmer (PCA9533 through i2c1 on phyBOARD-Sargas):https://git.phytec.de/linux-stm32mp/tree/arch/arm/boot/dts/st/stm32mp15xx-phyboard-sargas.dtsi?h=v6.6-phy#n170

I²C Bus

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

• I²C4 is reserved for the I²C devices on the module (PMIC, RTC, EEPROM).
• I²C1 is reserved for the carrier board, which provides plenty of different I²C devices connected to the I²C1 bus of the STM32MP15x (such as Audio Codec or touch screen).

This section will describe basic device usage and its Device Tree configuration of some I²C devices integrated into our phyBOARD-Sargas.

The device tree node for i2c contains settings such as clock-frequency to set the bus frequency and the pin control settings.

• General I²C4 bus Device Tree configuration on SoM: https://git.phytec.de/linux-stm32mp/tree/arch/arm/boot/dts/st/stm32mp15xx-phycore-som.dtsi?h=v6.6-phy#n102

• General I²C1 bus Device Tree configuration on phyBOARD-Sargas: https://git.phytec.de/linux-stm32mp/tree/arch/arm/boot/dts/st/stm32mp15xx-phyboard-sargas.dtsi?h=v6.6-phy#n98

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.

Device Tree configurationfor the EEPROM populated on SoM:https://git.phytec.de/linux-stm32mp/tree/arch/arm/boot/dts/st/stm32mp15xx-phycore-som.dtsi?h=v6.6-phy#n261

RTC

RTCs can be accessed via /dev/rtc*. 

• Check the available RTC:

target$ ls /sys/class/rtc
target$ rtc0  rtc1

• To find the name of the RTC devices, you can read their sysfs entry with:

target$ cat /sys/class/rtc/rtc*/name
rtc-rv3028 1-0052
stm32_rtc 5c004000.rtc

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 0711101425
Fri Jul 11 10:14:00 UTC 2025
target$ hwclock -w

Device Tree configuration of the external I²C RTC populated on SoM: https://git.phytec.de/linux-stm32mp/tree/arch/arm/boot/dts/st/stm32mp15xx-phycore-som.dtsi?h=v6.6-phy#n267

Note that the "enable-level-switching-mode" property still present in the device tree does't have any effect anymore since BSP PD23.1. hwclock commandmust now be used instead (refer to next section).

RTC Parameters

RTCs have a few abilities that can be read/set with the help of hwclock tool.

• We can check RTC-supported features with:

target$ hwclock --param-get features
The RTC parameter 0x0 is set to 0x70.

What this value means is encoded in the kernel; each set bit translates to:

#define RTC_FEATURE_ALARM               0
#define RTC_FEATURE_ALARM_RES_MINUTE    1
#define RTC_FEATURE_NEED_WEEK_DAY       2
#define RTC_FEATURE_ALARM_RES_2S        3
#define RTC_FEATURE_UPDATE_INTERRUPT    4
#define RTC_FEATURE_CORRECTION          5
#define RTC_FEATURE_BACKUP_SWITCH_MODE  6
#define RTC_FEATURE_ALARM_WAKEUP_ONLY   7
#define RTC_FEATURE_CNT                 8

• We can check RTC BSM (Backup Switchover Mode) with:

target$ hwclock --param-get bsm
The RTC parameter 0x2 is set to 0x1.

What BSM values mean translates to these values:

#define RTC_BSM_DISABLED   0
#define RTC_BSM_DIRECT     1
#define RTC_BSM_LEVEL      2
#define RTC_BSM_STANDBY    3

So, here, the BSM value is "RTC_BSM_DIRECT", meaning that the RTC is currently in "Direct Switching Mode".

• We can set RTC BSM to "RTC_BSM_LEVEL" ("Level Switching Mode") with:

target$ hwclock --param-set bsm=0x2
The RTC parameter 0x2 will be set to 0x2.

SPI Bus

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

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

Device Tree configuration for SPI1 bus with spidev driver: https://git.phytec.de/linux-stm32mp/tree/arch/arm/boot/dts/st/stm32mp15xx-phyboard-sargas.dtsi?h=v6.6-phy#n276

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

Device Tree configuration for USB Host and OTG on phyBOARD-Sargas:https://git.phytec.de/linux-stm32mp/tree/arch/arm/boot/dts/st/stm32mp15xx-phyboard-sargas.dtsi?h=v6.6-phy#n319

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 follows: 

• Plug a USB-A male into 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: a 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: a new interface called "enp0s20f0u2u3"). Then, configure the IP that matches 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 assigned 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 phyBOARD-Sargas, we use the TI TLV320AIC3007 audio codec. Audio support is done via the SAI2 interface and controlled via I²C.

• 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...). For example, to check the right and left channels (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 card capabilities, call:

target$ alsamixer -c STM32MP1PHYCORE

You should see a lot of options as the audio-ICs have 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

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 the 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 of the 3007. The software is used for both chips.

Device Tree configuration for SAI2 interface:https://git.phytec.de/linux-stm32mp/tree/arch/arm/boot/dts/st/stm32mp15xx-phyboard-sargas.dtsi?h=v6.6-phy#n197

Device Tree configuration for Audio Codec through i2c1 bus: https://git.phytec.de/linux-stm32mp/tree/arch/arm/boot/dts/st/stm32mp15xx-phyboard-sargas.dtsi?h=v6.6-phy#n108

Note that because the codec interface is shared between two SAIs (SAI2A and SAI2B), the TLV320AIC3x driver needs some code modification (add "of_xlate_dai_id" callback): https://git.phytec.de/linux-stm32mp/commit/?h=v6.6-phy&id=a9f6e7dbd11e613c76914d06b9353d9f704852b1

Refer to https://wiki.st.com/stm32mpu/wiki/SAI_device_tree_configuration for more details.

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). Switching between those 4 different configurations is explained in the next section.

Changing the BSP Display Configuration

Changing the BSP display configuration can be done by enabling/disabling one of the following Linux Kernel device tree overlays:

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

By default, phyboard-stm32mp1-peb-av02-lcd device tree overlay is enabled.

Note that only one display expansion can be enabled at a time.

• To enable/disable one of those device tree expansions, refer to How to apply the device tree overlay.
• Once you have activated the corresponding device tree overlay, 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 a 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, graphics, 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"

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 the 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

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 mode 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 follows.

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 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 supported by the STM32MP15x.

Once you have saved the u-boot environments with "saveenv", you can continue the normal boot with the u-boot command "boot".

WLAN / Bluetooth Module Expansion

Two different WLAN / Bluetooth modules are supported :

• Laird Stering-LWB 2.4GHz or 5Ghz 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. Activating Wifi/Bluetooth modules is explained in the next section.

Enabling WLAN / Bluetooth Module

Activating WLAN / Bluetooth module can be done by enabling one of the following Linux Kernel device tree overlays:

• To enable/disable one of those device tree expansions, refer to How to apply the device tree overlay.

Watchdog

The STM32MP includes a Watchdog circuit called "IWDG" (Independent WatchDog) that can 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 stm32mp15xx-phycore-som.dtsi kernel device tree with a custom timeout value in seconds (timeout-sec):

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

By default, the Watchdog Timer Linux framework support and the IWDG support are 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
<*> ARM Secure Monitor Call based watchdog support
<*> 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 can 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 /lib/systemd/system.conf.d/00-systemd-conf.conf :

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 overlays with the following dts files:

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

By default, no device tree overlays for those specific connectors are enabled.

• To enable/disable one of those device tree expansions, refer to How to apply the device tree overlay. 
• To modify and rebuild the device tree overlays (for example, to adapt the pinout configuration of one specific connector), please refer to Rebuilding the Kernel, Bootloader, or Trusted Firmware.
  

Raspberry 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 overlay file: phyboard-stm32mp1-pi-hat-extension.dts

Please refer to the L-875e.A2 phyCORE-STM32MP15x / phyBOARD-Sargas (1534.1/1517.2) Hardware Manual, in Raspberry Pi HAT Connector (X7) chapter for the pinout of this connector.

Arduino Shields Connector (X3)

This connector is compatible with the standard Arduino pinout connector (https://docs.arduino.cc/hardware/uno-rev3). The pinout can be configured by pin muxing in the following device tree overlay file: phyboard-stm32mp1-uno-r3-extension.dts

Please refer to the L-875e.A2 phyCORE-STM32MP15x / phyBOARD-Sargas (1534.1/1517.2) Hardware Manual, in Arduino Shields Connector (X3) chapter, 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 overlay files: phyboard-stm32mp1-motor-control.dts or phyboard-stm32mp1-motor-control-m4.dts.

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

Please refer to the L-875e.A2 phyCORE-STM32MP15x / phyBOARD-Sargas (1534.1/1517.2) Hardware Manual, in Motor Control Connector (X38) for the pinout of this connector.

Device Tree (DT)

STM32MP15x BSP Device Tree Concept

All device tree documentation can be found under:

host:~/PHYTEC_STM32MP1_BSP/build/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 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 STM32MP15x Device Tree can be found at:

• https://wiki.st.com/stm32mpu/wiki/Device_tree
• https://wiki.st.com/stm32mpu/wiki/STM32_MPU_device_tree
• https://wiki.st.com/stm32mpu/wiki/Category:Device_tree_configuration

As shown in the STM32MP15x device tree documentation, the device tree organization depends on whether you are using the standard STM device tree structure (the recommended method by PHYTEC), or the device tree generated by the STM32CubeMX tool. We recommend using the standard STM device tree structure to be conformed with the upstream kernel. In this BSP customization chapter, we are presenting the standard STM device tree organization.

For the STM32CubeMX, STM32MP15x device tree organization refers to "The STM32CubeMX tool" chapter of the Yocto Reference Manual.

Note that in this STM documentation,  the concept is the same for the phyCORE-STM32MP15x boards, but with those two main differences:

• Device tree files of our boards contain "phycore-som" or "phyboard-sargas".
• The main Device tree file (.dts) of our boards doesn't have the same name between the bootloaders (TF-A and U-boot) and the kernel.
  

Refer to the following section for the phyCORE and phyBOARD device tree file organization: phyCORE-STM32MP15x and phyBOARD-Sargas Device Tree.

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 version (MACHINE), it is assigned a .dts file (one for TF-A, one for u-boot, and one for Linux).

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

For example, our stm32mp15xx-phyboard-sargas-rdk.dts 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 an STM32MP157CAC SoC):

stm32mp157c-phyboard-sargas-rdk.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. 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:

• https://wiki.st.com/stm32mpu/wiki/Pinctrl_overview
• https://wiki.st.com/stm32mpu/wiki/Pinctrl_device_tree_configuration

phyCORE-STM32MP15x and phyBOARD-Sargas Device Tree

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

• SOM:  stm32mp15xx-phycore-som.dtsi => contains the Hardware specificities common to all the phyCORE-STM32MP15xx SOM declinations (or Yocto machines)
  
• Baseboard:stm32mp15xx-phyboard-sargas.dtsi  => contains the Hardware configuration of the phyBOARD-Sargas

SOM and Baseboard .dtsi include others .dtsi files (for pin control for example).

Below is the complete list of our PHYTEC custom DTS files (.dts & .dtsi) for the phyCORE-STM32MP15xx 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.

phyBOARD-Sargas Device Tree Overlay

phyBOARD-Sargas add-ons (expansions, phyCAM, etc..), or specific connector configurations (like pin muxing examples for Raspberry PI HAT or Arduino Uno connectors) are managed by Device Tree Overlay(DTO).

DTOs are device tree blob fragments that allow specific parts of a Kernel device tree to be overridden on-the-fly, before booting the Kernel. This allows you to make small changes without defining a new complete device tree or modifying the original one.

The phyBOARD-Sargas DTO defined the necessary Kernel device tree adaptation for the specific add-ons/connectors config. One or more DTO can be applied by u-boot over the machine device tree (DTB) before booting the kernel (through boot.scr.cmd script).

phyBOARD-Sargas DTO source files (.dts) are stored separately from the other kernel device tree source files, in a subdirectory called "overlays": arch/arm/boot/dts/st/overlays/

Like classic device tree, the Device Tree Overlay sources are processed by DTC (Device Tree Compiler), but into a binary with .dtbo extension. Those binaries are then stored on target under/boot/overlays/

List of phyBOARD-Sargas Device Tree Overlays

How to Apply the Device Tree Overlay

The board must be booted and accessible through a remote console. Device tree overlays can be applied either from u-boot or from userspace:

Applying DTO from userspace

• Edit the /boot/overlays/overlays.txt file

target$ vi /boot/overlays/overlays.txt 

This file specifies the DT overlays to apply with the following syntax:

overlay=aa bb cc dd

- aa, bb, cc, dd correspond to a device tree name file (without extension) located in/overlays/ directory:

/overlays/aa.dtbo
/overlays/bb.dtbo
/overlays/cc.dtbo
/overlays/dd.dtbo

Edit the file to enable/disable any DTO located in the /overlays/ directory.

• force filesystem sync:

target$ sync

• Reboot the board:

target$ reboot

Applying DTO from u-boot

Device tree overlays to apply can also be set on u-boot with the following commands:

STM32MP> setenv overlay 'aa bb cc'
STM32MP> saveenv

With aa, bb, cc, dd corresponding to a device tree name file (without extension) located on /overlays/ directory:

/overlays/aa.dtbo
/overlays/bb.dtbo
/overlays/cc.dtbo
/overlays/dd.dtbo

If you want to modify an existing overlay variable, you can use the following command:

STM32MP> editenv overlay

Once you have saved the u-boot environments with "saveenv", you can continue the normal boot with the u-boot command "boot".

Modifying device tree

Modifying the device tree is a mandatory step when customizing the BSP for a custom carrier board. It is possible to do that using the OpenSTLinux Yocto build environment.

Please refer to our Yocto OpenSTLinux Manual.

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 redistributes this SDK to developers.

The Procedure to build, install, and use the SDK is described in our Yocto OpenSTLinux Manual.

How to Use the Cortex-M4 MCU

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

STM32Cube™ provides comprehensive embedded software libraries and tools, significantly reducing development effort, time, and cost. It is fully integrated into 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

• The official git repository of STM32CubeMP1 is:
  https://github.com/STMicroelectronics/STM32CubeMP1
  
  
• The git repository with additional components from PHYTEC is:
  https://git.phytec.de/STM32CubeMP1

In our PHYTEC git repository, the "master" branch is a clone from the last official version of STM32CubeMP1ST (from STM Github). In the "x.y.z-phy" branches, we have added additional components for the phyBOARD-Sargas development board specifics, to provide some STM32CubeMP1 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
    • ADC/ADC_SingleConversion_Polling
    • ADC/ADC_SingleConversion_TriggerTimer_DMA
  • 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 projects from "Applications and Examples" directories are, by default, built and deployed on target within our BSP image. They can be run from Linux userspace (refer to next section: How to run Cortex-M4 examples on target).

Coprocessor Management with STM32Cube‎MP1 and Linux

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

Other 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-x-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:

2. Select Examples or Applications to Run:

root@phycore-stm32mp1-4:~# cd /usr/local/Cube-M4-examples/STM32MP15-phyBOARD-Sargas

• For 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, the 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 with GPIO_EXTI :

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 with GPIO_EXTI:

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) assigns and configures 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.

In the particular case of the GPIO_EXTI M4 example firmware, pushing the User S5 button of the phyBOARD-Sargas will result in switching ON or switching OFF the LED2 (Red LED) on phyCORE-STM32MP15x (refer to the README file for details).

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.

Start the Coprocessor from the Bootloader

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

Protect the Processor Firmware

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

Assign an Internal Peripheral to a Runtime Context

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

Configure System Resources

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

Exchange Large Data Buffers with the Coprocessor - Principle

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

Retrieve Cortex-M4 Logs after Crash

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

Revision History