Sample Projects

This chapter provides a short description on how to create and debug applications on the M4 coprocessor of the STM32MP1 with the help of two example applications.
For a more general and detailed description of the M4 functionality please refer to the STM32 MPU wiki by ST .

Prerequisites

For M4 debugging you need an appropriate JTAG debugger. What we recommend is

See the board documentation for the location of the debug plug. For Kontron Demo-Kits the outline of the debug plug can be found here.

Before continuing make sure that:

Debug modes of the M4 coprocessor

The M4 firmware can be run and debugged in two different modes:

  • Production mode: M4 firmware is loaded from network and started with the remoteproc service running on the A7.

  • Engineering mode: M4 firmware is loaded and started from the debugger similar to normal STM32 procedure. In this mode the A7 is not running.

Info

Due to a missing boot switch the engineering mode is currently not available on our Kontron Demo-Kits. Thus, following description is for the production mode.

More detailed information on the boot modes can be found in the ST wiki.

Debugging the M4 coprocessor

Step by step guide on how to debug the example application on the M4 in production mode and the Kontron Demo-Kit.

  • Connect the debug console to the host (via USB interface)
  • Connect the Demo-Kit to the network and figure out the ip address with ifconfig
  • Connect the ST-Link with Olimex connector to the board and the pc
  • Open the System WorkBench
  • Open the example project "m4_ktn-simple-monitor" which can be downloaded from the following repository git@git.kontron-electronics.de:stm32mp/m4_ktn-simple-monitor.git
  • Rebuild the project
  • Right click on the project and go to Debug as..
    double click ST's STM32 MPU Debugging
    go to the Startup tab and input the ip address of the board
  • Set a breakpoint at the start of main()
  • Press Debug and input root as username and no password
  • After confirming the log in data a few times, you should end up in the Debug view similar to normal STM32 debugging.

The next section describes the capabilities of this application and how to use it.

Description of the "m4_ktn-simple-monitor" example application

This example is based on the OpenAMP_TTY_echo example application from ST which can be found here.
Similar to the example application provided by ST it will create two virtual uart channels between the A7 and the M4 cores based on the Linux frameworks RPMsg , VirtIO] and IPCC and the OpenAmp framework on the M4 site.

As the name implies the application offers a simple monitor, which allows to control the LED1 on the evaluation board from the linux console. This simple monitor operates on virtual uart channel 0 while virtual uart channel 1 echos all incoming messages back.

If the application is up and running (default state with the evaluation board image) you can simply write a command on the virtual uart channel 0 (/dev/ttyRPMSG0) by using rpmsg0. For example rpmsg0 "help" which will show all available commands to control the LED on the evaluation board. Use rpmsg1for messages on the second channel, which will only echoed back.

Creating a new project

New projects might be created with the System Workbench or by taking the ST template from https://github.com/STMicroelectronics/STM32CubeMP1.

This repository also includes all HAL_Drivers and lots of examples which can be used for building your application.

However, these example applications are designed for the evaluation boards of ST and have complex include paths structures which are not very friendly for extracting project parts like the OpenAMP framework.

Thus, it is less stressful to use the sample project "m4_ktn-eval-usart6" as starting point as it includes the rsc_table, basic Drivers and system libraries as well as all necessary header and source files. Or the "m4_ktn-simple-monitor" project if you want to use the OpenAMP framework.

Assigning peripheral devices to the M4 coprocessor

To use a peripheral device with the M4 coprocessor it has to be assigned to it in the device tree prior to the linux boot. This can be accomplished by creating your own board device tree. For the Kontron Demo-Kits this is done in the file stm32mp-board-s.dtsi in the directory layers/meta-ktn-stm32mp/recipes-kernel/linux/linux-stm32mp.

In the following the usart6 peripheral is taken as an example. On the Kontron Demo-Kit the usart6 is converted into a RS232 signal on connector x16 (pin 1 Tx and pin 3 Rx). For other boards see the documentation.

First of all, the respective node has to be disabled for A7 cores with linux. This can be accomplished by adding:

&usart6{
    status = "disabled";
};

Next we enable the peripheral for the M4:

&m4_usart6{
    status = "okay";
};

To rebuild the device tree, either build the respective image or only the linux kernel image with bitbake linux-stm32mp.

Afterwards replace the old device tree in the borootfs and boot the board. To check if the resource is really disabled for the A7 read the node status with cat /proc/device-tree/soc/serial\@44003000/status. Additionally, check if the M4 resource was enabled successfully with cat /proc/device-tree/m4\@0/m4_system_resources/serial\@44003000/status.

A simple example for M4, which initializes the usart6 and continuously sends out a string, can be downloaded from git@git.kontron-electronics.de:stm32mp/m4_ktn-simple-monitor.git.

This example can be debugged similar to the m4_ktn-simple-monitor example described above.

Additionaly, for an easy and graphical configuration of a new peripheral the CubeMX tool can be used to generate the respective System WorkBench project. As a starting point the CubeMX project with the initial evaluation board configuration can be used, which can be found in the meta-ktn-stm32mp layer at conf/machine/cubemx. Here, it is again simplier to take the initialization of the respective peripheral from the project created by CubeMX and use it in an already working project.

More detailed informations on assigning peripheral devices can be found in the ST wiki.

In this application also the resource manager is implemented to check for conflicts in peripheral assignment.

Starting Software with system service

A system service called m4_fw-autoload.sh is already included in the linux image for the Kontron Demo-Kits. It autoloads the above mentioned example m4_ktn-simple-monitor on system boot. The service can be controlled with the commands start and stop. For example this stops the M4 processor:

/etc/init.d/m4_fw-autoload.sh stop

By changing the APPLICATION_NAME in /etc/default/m4_fw-autoload.conf to m4_ktn-eval-usart6 this example will be used by the service.

If you want to include your own binary file into the service you need to copy it to the directory recipes-extended/m4-fw-autoload/files/binary in your own layer and create a m4-fw-autoload.bbappend file and a adapted m4_fw-autload.conf file. This should lead to the binary being copied into the image on build and started from the system service.

Starting software manually

In case the system service is not used, the M4 firmware can be started manually with the following principle

  • Load the binary file into /lib/firmware
  • echo -n "firmware_name" > /sys/class/remoteproc/remoteproc0/firmware where firmware_name is the name of your firmware binary file
  • echo -n start > /sys/class/remoteproc/remoteproc0/state
  • read state of M4 via cat /sys/class/remoteproc/remoteproc0/state
  • stop the M4 via echo -n stop > /sys/class/remoteproc/remoteproc0/state

Alternatively you can also use the fw_cortex_m4.sh script present in the Remoteproc folder of the application.

Getting logs from M4

For all of the demo projects a trace buffer is added to the resource table. This enables reading out the log buffer of M4 in the linux context:

root@stm32mp-t1000-s-multi:~# cat /sys/kernel/debug/remoteproc/remoteproc0/trace0
[00000.000][INFO ]Cortex-M4 boot successful with STM32Cube FW version: v1.0.0
[00000.008][INFO ]Virtual UART0 OpenAMP-rpmsg channel creation
[00000.009][INFO ]Virtual UART1 OpenAMP-rpmsg channel creation