Difference between revisions of "STM32MP1 Developer Package for Android"

[quality revision] [quality revision]
(Creating project from CubeMx)
m (Creating your project using STM32CubeMX)
 

This article describes how to obtain and use the Developer Package of the STM32MPU Embedded Software for Android™ for any STM32MP1 family development platform (STM32MP15 boards) in order to develop applications on it.

It details some prerequisite knowledge and the development environment, and gives step-by-step instructions to download and install the STM32MPU Embedded Software for Android components for the Package.

Finally, it gives guidelines on upgrading (to add, remove, configure, or improve) any piece of software.

1 Developer Package content[edit]

If you are not familiar with the STM32MPU Embedded Software for Android distribution and its Packages, please read the following articles:

In summary, this Developer Package provides:

  • for the STM32MPU distribution for Android™ (development on Arm® Cortex®-A processor):
    • the software development kit (SDK) update associated with Android Studio IDE, adding a service to connect your application to the coprocessor (customization)
  • for the STM32Cube MPU Package (development on Arm® Cortex®-M processor):
    • source code for all pieces of software (BSP, HAL, middleware and applications)
    • the integrated development environment (IDE) (STM32-CoPro-MPU Eclipse pluginSTM32CubeIDE)
    • a pre-configured project for CubeMx including default resources allocations for the Arm® Cortex®-M4
    • a multicore application example using the coprocessor service (Android application linked with a Arm® Cortex®-M4 firmware)

2 Prerequisite knowledge[edit]

The STM32MP1 Developer Package aims to enrich Linux-based software for the targeted product. A basic knowledge of Linux and Android is recommended in order to make the most of this Package. Reading the STM32MPU Embedded Software for Android architecture overview is also highly recommended.

3 Installing the required components to develop software running on Arm Cortex-A (STM32MPU distribution for Android)[edit]

3.1 Installing the Android Studio IDE[edit]

The IDE is available in the Android developer site[1].

3.2 Installing the SDK update[edit]

The official SDK for Android must be loaded through Android Studio using the SDK manager, selecting the correct version for the Starter package version used.

The SDK can then be updated by replacing the android.jar file (JAVA archive file for Android) of the loaded SDK with the one provided within the Developer package (adding the coprocessor service classes). Refer to Install SDK in Android Studio.

The software package is provided AS IS, and by downloading it, you agree to be bound to the terms of the software license agreement (SLA). The detailed content licenses can be found here.

Warning white.png Warning
To download a package, it is recommended to be logged in to your "myst" account [1]. If, trying to download, you encounter a “403 error”, you could try to empty your browser cache to workaround the problem. We are working on the resolution of this problem.
We apologize for this inconvenience
STM32MPU distribution for Android™
Tag API version Link Release note
st-android-1011.0.0-20202021-0201-21 API 29 en.st-android-10.0.0-2020-02-21-sdk-api29.zip st-android-10.0.0-2020-02-21 release note st-android-9.0.0-2019-09-27 API 28 API 30 en.st-android-911.0.0-20192021-0901-2729-sdk-api28api30.zip st-android-911.0.0-20192021-0901-27 29 release note

4 Installing the required components needed to develop software running on the Arm Cortex-M4 (STM32Cube MPU Package)[edit]

4.1 Installing the Eclipse IDESTM32CubeMX[edit]

The table below explains how to download and install the System Workbench for the STM32 IDE, which is the AC6 product addressing the STM32 MCU, and the STM32-CoPro-MPU plugin, which provides support for Cortex-M inside the STM32 MPU. STM32-CoPro-MPU plugin release note Please refer to the STM32CubeMX page.

4.2 Installing the STM32Cube MPU PackageSTM32CubeIDE[edit]

Prerequite: the Eclipse IDE is installed.

  • The STM32CubeMP1 Package is delivered through an archive file named en.STM32Cube_FW_MP1_V1.3.0.zip.
  • Download and install the STM32CubeMP1 Package

The software package is provided AS IS, and by downloading it, you agree to be bound to the terms of the software license agreement (SLA). The detailed content licenses can be found here.

Warning white.png Warning
To download a package, it is recommended to be logged in to your "myst" account [2]. If, trying to download, you encounter a “403 error”, you could try to empty your browser cache to workaround the problem. We are working on the resolution of this problem.
We apologize for this inconvenience
. STM32MP1 Developer Package STM32CubeMP1 Package - v2.1.0 release Download

You need to be logged on my.st.com before accessing the following link:
en.STM32Cube_FW_MP1_V1.3.0.zip

Installation
$ cd <working directory path>/Developer-Package

  • Download the archive file in this directory
  • Uncompress the archive file to get the STM32CubeMP1 Package:
$ unzip en.STM32Cube_FW_MP1_V1.3.0.zip

Release note

Details about the content of the STM32CubeMP1 Package are available in the STM32Cube_FW_MP1_V2.1.0/Release_Notes.html file.

Archive box.png If you are interested in older releases, please have a look into the section Archives.

  • The STM32CubeMP1 Package installation directory is in the <Developer Package installation directory> directory, and is named STM32Cube_FW_MP1_V1.2.0:
STM32Cube_FW_MP1_V1.3.0                             STM32CubeMP1 Package: details in STM32CubeMP1 Package content article
├── Drivers
│   ├── BSP                                         BSP drivers for the supported STM32MP1 boards
│   │   └── [...]
│   ├── CMSIS
│   │   └── [...]
│   └── STM32MP1xx_HAL_Driver                       HAL drivers for the supported STM32MP1 devices
│       └── [...]
├── _htmresc
│   └── [...]
├── License.md
├── Middlewares
│   └── [...]
├── package.xml
├── Projects
│   ├── STM32CubeProjectsList.html                  List of examples and applications for STM32CubeMP1 Package
│   ├── STM32MP157C-DK2                             Set of examples and applications → STM32MP15 Discovery kits
│   │   └── [...]
│   └── STM32MP157C-EV1                             Set of examples and applications → STM32MP15 Evaluation boards
│       └── [...]
├── Readme.md
├── Release_Notes.html                              Release note for STM32CubeMP1 Package
└── Utilities
    └── [...]

The STM32Cube MPU Package is now installed: let's develop software running on Arm Cortex-M.

Please refer to the STM32CubeIDE page.

5 Developing multi-core applications using the coprocessor service (CoproManager)[edit]

STM32MP1 Platforms for Android propose an environment for developing Android applications running on the Arm Cortex-A7, combined with a remote firmware offloaded in the Arm Cortex-M4. This is based in the coprocessor service. Please check How to use coprocessor service for Android page for details.

A STCoproM4Example project, containing both Android application and Cortext-M4 firmware, is given with the STM32MP1 Developer Package for Android, and is used to illustrate below chapters.

5.1 Software running on Arm Cortex-M4 with STM32CubeMP1 Developer Package[edit]

This It is possible to develop Arm Cortex-M4 software based on the default resources allocated in the Linux kernel device - tree (detailed in Default resources allocation for Arm Cortex-M4 in Developer Package for Android).

5.1.1 Prerequisites[edit]

Main components to be used:

5.1.2 Creating your project from CubeMxusing STM32CubeMX[edit]

STM32CubeMX install is done and environment is available.

As an initial CubeMx default configuration project which include supported resources allocations for Cortext-M4, please load the ioc file adapted to your used deliveryIt's required to configure your project using STM32CubeMX. It's possible to start from the provided STM32CubeMX project .ioc file which reserve (not activate and not configure) the available Cortex-M4 resources as listed in Default resources allocation for Arm Cortex-M4 in Developer Package for Android.

At this stage, the required STM32Cube package must be downloaded and installed.

The software package is provided AS IS, and by downloading it, you agree to be bound to the terms of the software license agreement (SLA). The detailed content licenses can be found here.

Warning white.png Warning
To download a package, it is recommended to be logged in to your "myst" account [32]. If, trying to download, you encounter a “403 error”, you could try to empty your browser cache to workaround the problem. We are working on the resolution of this problem.
We apologize for this inconvenience
STM32MPU distribution for Android™
Tag Board Link Release note
st-android-1011.0.0-20202021-0201-21 29 STM32MP157x-EV1 Evaluation boards en.st-android-1011.0.0-20202021-0201-2129-eval-cubemx.zip st-android-10.0.0-2020-10-21 release note st-android-9.0.0-2019-09-27 STM32MP157x-EV1 Evaluation boards en.st-android-9.0.0-2019-09-27-eval-cubemx.ioc.zip st-android-911.0.0-20192021-0901-27 29 release note
Warning white.png Warning

It allocates some resources to the Cortext-M4, but do not configure each resources, as it depends on the way it will be used for your project.

5.1.3 Using the Eclipse IDE for building the project[edit]

The STCoproM4Example project, which is using the coprocessor service (CoproManager), is taken as example in this paragraph.

5.1.3.1 Get the source code of the example[edit]

Source code of the Arm Cortex-M4 software example is available on githubAt the end, the STM32CubeIDE project can be generated.

Info white.png Information
At any time, it's possible to change the configuration using STM32CubeMX and re-generate the sources, considering that the added code in the user sections is not impacted)

You can also refer to the configured STM32CubeMX project copro_m4example.ioc associated to the STCoproM4Example firmware project available on GitHub: STCoproM4Example.

5.1.3

.2 Install and build project

Building your project using STM32CubeIDE[edit]

  • Open the folder containing the example and double-click on file .project to open Eclipse IDE.
  • When project is loaded on the eclipse IDE, then click on build button to build the example

In case of issue, please find complete view with similar exmaple in How to rebuild example page

5.1.3.3 Connect the target board[edit]
  • The board is booted, ST-Link connected to your PC (for getting console through virtual communication port), and USB OTG also connected to your PC (for getting ADB link)
  • Open the serial console to check connection to the board is ok
Click Open console on serial device button

IDE ExampleSerialConsole.png

A dedicated Console panel is open with prompt. You can then check you are connected to the board
:/ $ ls / acct data init.recovery.stm.rc oem storage bin default.prop init.usb.configfs.rc postinstall sys bugreports dev init.usb.rc proc system cache etc init.zygote32.rc product ueventd.rc charger init lost+found res vendor config init.environ.rc mnt sbin d init.rc odm sdcard 5.1.3.4 Download and run the project image on the target

At this stage, it's possible to open the generated project using STM32CubeIDE. Pleaser refer to STM32CubeIDE user guide to understand it's usage.

The default IPC mechanism is based on a virtual UART which must be used to receive commands from the Cortex-A7 and transmit results. It's possible to refer to the example available in GitHub: STCoproM4Example firmware project.

Warning white.png Warning

The generated sources include CA7 device tree files are not needed in Android context. As mentioned, only the listed reserved Cortex-M4 resources can be used. Otherwise, it's required to use the STM32MP1 Distribution Package for Android.

At this stage your project has been built and a generated .elf file is available.

5.1.4 Loading your generated image in the device[edit]

The download of the project firmware .elf image (Arm Cortex-M4 firmware) on the target has to be done via command line in the STM32MP1 Developer Package for Androidis performed using ADB.

Info white.png Information

All Firmware firmware .elf images using the coprocessor service is downloaded with the SW4STM32 IDE must be downloaded in the Linux File System in /vendor/firmware/copro

Info white.png Information
Only ADB link allows to push files on the remote target board
  • Connect ADB to the remote target board via USB OTG through Android Studio
  • Check for the adb link:
adb devices List of devices attached <your_device_id> device Load the

/ directory.


To load the Arm Cortex-M4 firmware image on the target

in the dedicated path: /vendor/firmware/copro.
Example for STCoproM4Example firmware:
Note: root access right required for creating directory in /vendor to be able to create any new directory in /vendor

, execute the following commands using a terminal:

 adb root; adb remount
 adb push <path_to>/copro_m4example<project image>.elf /vendor/firmware/copro/
 adb reboot

5.1.

3.5 How to test the Cortex-M4 firmware in standalone (without Android application)[edit]

This is possible to test the Cortex-M4 firmware independently from the Android application, and via the console in the IDE:

  • Enable root access rights
- Using ADB shell is ADB link available:

5 Testing your project[edit]

There are several solutions to test your project on the device (using STM32CubeIDE in engineering mode, using test binary, using Android application).

It's also possible to load, start and send commands manually.

Open a console:

 adb root
 adb shell
 ...
- or Using uart console shell:
su ...

Configure the firmware to be loaded by Linux in the Cortex-M4:

:/ # echo copro/copro_m4example<project image>.elf > /sys/class/remoteproc/remoteproc0/firmware

Start the

example and check in log that the

firmware

is running

:

:/ # echo start > /sys/class/remoteproc/remoteproc0/state

Check that all required resources have been reserved without error

:/ # dmesg
...
[13366.032915

Example of dmesg trace with copro/copro_m4example.elf:

[ 5183.938679] remoteproc remoteproc0: powering up m4
[13366 5183.038707947729] remoteproc remoteproc0: Booting fw image copro/copro_m4example.elf, size 24104603107616
[13366.052612] rproc-srm-dev m4@0:m4_system_resources:dac@40017000: Linked as a consumer to regulator.9
[13366.060918 5183.989105] rproc-srm-devcore m4@0:m4_system_resources:adc@48003000: Linked as a consumer to regulator.9
[13366.081654] rproc-srm-core m4@0:mlahb:m4@10000000:m4_system_resources: bound m4@0mlahb:m4@10000000:m4_system_resources:timer@40000000 (ops rproc_srm_dev_ops)
[13366 5184.081683001239] rproc-srm-core m4@0mlahb:m4@10000000:m4_system_resources: bound m4@0mlahb:m4@10000000:m4_system_resources:timer@40005000 (ops rproc_srm_dev_ops)
[13366 5184.081706014541] rproc-srm-core m4@0mlahb:m4@10000000:m4_system_resources: bound m4@0mlahb:m4@10000000:m4_system_resources:serial@4000f000 (ops rproc_srm_dev_ops)
[13366 5184.081727027795] rproc-srm-core m4@0mlahb:m4@10000000:m4_system_resources: bound m4@0mlahb:m4@10000000:m4_system_resources:i2c@40015000 (ops rproc_srm_dev_ops)
[13366 5184.084560043446] rproc-srm-core m4@0mlahb:m4@10000000:m4_system_resources: bound m4@0mlahb:m4@10000000:m4_system_resources:dac@40017000 (ops rproc_srm_dev_ops)
[13366 5184.084591055294] rproc-srm-core m4@0mlahb:m4@10000000:m4_system_resources: bound m4@0mlahb:m4@10000000:m4_system_resources:spi@44004000 (ops rproc_srm_dev_ops)
[13366 5184.084614068340] rproc-srm-core m4@0mlahb:m4@10000000:m4_system_resources: bound m4@0mlahb:m4@10000000:m4_system_resources:dma@48001000 (ops rproc_srm_dev_ops)
[13366 5184.084641081449] rproc-srm-core m4@0mlahb:m4@10000000:m4_system_resources: bound m4@0mlahb:m4@10000000:m4_system_resources:adc@48003000 (ops rproc_srm_dev_ops)
[13366 5184.084662094565] rproc-srm-core m4@0mlahb:m4@10000000:m4_system_resources: bound m4@0mlahb:m4@10000000:m4_system_resources:hash@4c002000 (ops rproc_srm_dev_ops)
[13366 5184.084682107796] rproc-srm-core m4@0mlahb:m4@10000000:m4_system_resources: bound m4@0mlahb:m4@10000000:m4_system_resources:rng@4c003000 (ops rproc_srm_dev_ops)
[13366 5184.084703120918] rproc-srm-core m4@0mlahb:m4@10000000:m4_system_resources: bound m4@0mlahb:m4@10000000:m4_system_resources:crc@4c004000 (ops rproc_srm_dev_ops)
[13366 5184.084723134054] rproc-srm-core m4@0mlahb:m4@10000000:m4_system_resources: bound m4@0mlahb:m4@10000000:m4_system_resources:cryp@4c005000 (ops rproc_srm_dev_ops)
[13366 5184.084744147277] rproc-srm-core m4@0mlahb:m4@10000000:m4_system_resources: bound m4@0mlahb:m4@10000000:m4_system_resources:qspi@58003000 (ops rproc_srm_dev_ops)
[13366 5184.084762160489] rproc-srm-core m4@0mlahb:m4@10000000:m4_system_resources: bound m4@0:m4_system_resources:button (ops rproc_srm_dev_ops)
[13366.084780] rproc-srm-core m4@0:mlahb:m4@10000000:m4_system_resources: bound m4@0:m4_system_resources:m4_led (ops rproc_srm_dev_ops)
[13366 5184.085683173700] m4@0#vdev0bufferremoteproc0#vdev0buffer: assigned reserved memory node vdev0buffer@10044000vdev0buffer@10042000
[13366 5184.086750182181] virtio_rpmsg_bus virtio0: rpmsg host is online
[13366 5184.087508182335] m4@0#vdev0buffer: virtio_rpmsg_bus virtio0: creating channel rpmsg-tty-channel addr 0x0
[ 5184.187346] remoteproc0#vdev0buffer: registered virtio0 (type 7)
[13366 5184.087525200672] remoteproc remoteproc0: remote processor m4 is now up
[13366.088987] virtio_rpmsg_bus virtio0: creating channel rpmsg-tty-channel addr 0x0
[13366.090313 5184.204352] rpmsg_tty virtio0.rpmsg-tty-channel.-1.0: new channel: 0x400 -> 0x0 : ttyRPMSG0
Stop the example and check in log that the firmware is stopped

Send command:

:/ # echo stop<command> > /sys/class/remoteproc/remoteproc0/state
 dmesg
...
[13431.354096] rpmsg_tty virtio0.rpmsg-tty-channel.-1.0: rpmsg tty device 0 is removed
[13431.862382] remoteproc remoteproc0: warning: remote FW shutdown without ack
[13431.869044] rproc-srm-dev m4@0:m4_system_resources:dac@40017000: Dropping the link to regulator.9
[13431.873046] rproc-srm-dev m4@0:m4_system_resources:adc@48003000: Dropping the link to regulator.9
[13431.883389] remoteproc remoteproc0: stopped remote processor m4

5.1.3.6 How to debug an example with IDE[edit]
  • Configure Main tab of the Debug Configurations panel to add the firmware binary
Menu > Run > Debug configuration... / [ Main ] tab

IDE ExampleDebugMenu.png

IDE ExampleDebugPanelMain.png

  • Configure Startup tab of the Debug Configurations panel
Menu > Run > Debug configuration... / [ Starter ] tab
Unselect Load image
Info white.png Information

To work in Engineering mode, you need to:

  • Ensure the example firmware is running on the target.
  • Run the debug mode on IDE side.

The IDE will attach the current running firmware on the Arm Cortex-M4. It is then possible to break software execution and make step by step debug.

5.
dev/ttyRPMSG0

Receive returned data (to be executed in another console before sending the command):

:/ # od -c < /dev/ttyRPMSG0

Stop the firmware:

:/ # echo stop > /sys/class/remoteproc/remoteproc0/state

5.2 Android application running on Arm Cortex-A7[edit]

Please refer to the Android developer guide[2] for generic informations information about standard Android application development.

Then based on the SDK delivered within the Developer Package for Android (see Installing the SDK update), this is possible to develop an application which can use the coprocessor service (CoproManager), in order to interact with remote Arm Cortex-M4 core software.

Coprocessor service detailed information and API are described in dedicated page. Please see How to use coprocessor service for Android.


You As example, you can refer to the STCoproM4Example application for Android, and corresponding source code to get example for implementation. Source code of the Arm Cortex-A7 software example is available on github: STCoproM4Exampleavailable on GitHub.

6 How to go further[edit]

Now that your developments are ready, you may switch to the STM32MP1 Distribution Package for Android in order to create your own distribution and to generate your own SDK and image.

7 References[edit]


This article describes how to obtain and use the '''Developer Package''' of the '''STM32MPU Embedded Software for Android&trade;''' for any '''STM32MP1 family''' development platform ([[STM32MP15 boards]]) in order to develop applications on it.

It details some '''prerequisite''' knowledge and the development environment, and gives  '''step-by-step''' instructions to download and install the STM32MPU Embedded Software for Android components for the Package.

Finally, it gives guidelines on upgrading (to add, remove, configure, or improve) any piece of software.

==Developer Package content==
If you are not familiar with the '''STM32MPU Embedded Software for Android''' distribution and its '''Packages''', please read the following articles:
* [[Which STM32MPU Embedded Software Package for Android better suits your needs]] (and especially the [[Which STM32MPU Embedded Software Package for Android better suits your needs#Developer Package|Developer Package]] chapter)
* [[:Category:STM32MPU Embedded Software distribution for Android|STM32MPU Embedded Software distribution for Android]]

In summary, this '''Developer Package''' provides:
* for the '''STM32MPU distribution for Android&trade;''' (development on Arm<sup>&reg;</sup> Cortex<sup>&reg;</sup>-A processor):
** the '''software development kit''' (SDK) update associated with Android Studio IDE, adding a service to connect your application to the coprocessor (customization)
* for the '''STM32Cube MPU Package''' (development on Arm<sup>&reg;</sup> Cortex<sup>&reg;</sup>-M processor):
** '''source code''' for all pieces of software (BSP, HAL, middleware and applications)
** the '''integrated development environment (IDE)''' (STM32-CoPro-MPU Eclipse pluginSTM32CubeIDE)
** a '''pre-configured project for CubeMx''' including default resources allocations for the Arm<sup>&reg;</sup> Cortex<sup>&reg;</sup>-M4
** a '''multicore application example using the coprocessor service''' (Android application linked with a Arm<sup>&reg;</sup> Cortex<sup>&reg;</sup>-M4 firmware)

==Prerequisite knowledge==
The STM32MP1 Developer Package aims to enrich Linux-based software for the targeted product. A basic knowledge of Linux and Android is recommended in order to make the most of this Package.
Reading the [[STM32MPU Embedded Software for Android architecture overview]] is also highly recommended.

==Installing the required components to develop software running on Arm Cortex-A (STM32MPU distribution for Android)==

===Installing the Android Studio IDE===
The IDE is available in the Android developer site<ref>https://developer.android.com/studio</ref>.

===Installing the SDK update===
The official SDK for Android must be loaded through Android Studio using the SDK manager, selecting the correct version for the Starter package version used. 

The SDK can then be updated by replacing the ''android.jar'' file (JAVA archive file for Android) of the loaded SDK with the one provided within the Developer package (adding the coprocessor service classes). Refer to [[How to build and install an SDK for Android#Install SDK in Android Studio | Install SDK in Android Studio]].

{{SoftwareLicenseAgreement | distribution=Android}}

{|class="st-table"
|-
| colspan="4" | '''STM32MPU distribution for Android&trade;'''
|-
| style="width:20%; text-align:center" | Tag
| style="width:10%; text-align:center" | API version
| style="width:30%; text-align:center" | Link
| style="width:30%; text-align:center" | Release note

|-
| st-android-1011.0.0-2020-02-212021-01-29

| API 2930

| [https://st.com/content/ccc/resource/technical/sw-updater/firmware2/group0/70/1f/57/30/9f/48/4c/71/STM32MP1_Developer_Package_for_Android_SDK/files/st-android-10.0.0-2020-02-21-sdk-api29.zip/jcr:content/translations/en.st-android-10.0.0-2020-02-21-sdk-api29.zip en.st-android-10.0.0-2020-02-21-sdk-api29.zip]
| [[STM32MP15 distribution for Android release note - v1.1.0 | st-android-10.0.0-2020-02-21 release note]]
|-
| st-android-9.0.0-2019-09-27
| API 28
| [https://www.st.com/content/ccc/resource/technical/sw-updater/firmware2/group0/6c/13/b9/39/b3/11/41/94software/application_sw/group0/69/08/f1/d8/38/f2/41/de/STM32MP1_Developer_Package_for_Android_SDK/files/st-android-911.0.0-2019-09-272021-01-29-sdk-api28api30.zip/jcr:content/translations/en.st-android-911.0.0-2019-09-272021-01-29-sdk-api28api30.zip en.st-android-911.0.0-2019-09-272021-01-29-sdk-api28api30.zip]
| [[STM32MP15 distribution for Android release note - v1v2.0.0 | st-android-911.0.0-2019-09-272021-01-29 release note]]
|}

==Installing the required components needed to develop software running on the Arm Cortex-M4 (STM32Cube MPU Package)==

===Installing the Eclipse IDE===
The table below explains how to download and install the System Workbench for the STM32 IDE, which is the AC6 product addressing the STM32 MCU, and the STM32-CoPro-MPU plugin, which provides support for Cortex-M inside the STM32 MPU.
{{:STM32-CoPro-MPU plugin release note}}

===Installing the STM32Cube MPU Package===
Prerequite: the [[#Installing the Eclipse IDE|Eclipse IDE is installed]].
{{:STM32MP1 Developer Package - STM32CubeMP1 Package}}
'''The STM32Cube MPU Package is now installed''': let's develop software running on Arm Cortex-M==

===Installing STM32CubeMX===
Please refer to the [[STM32CubeMX]] page.

===Installing STM32CubeIDE===
Please refer to the [[STM32CubeIDE]] page.

== Developing multi-core applications using the coprocessor service (CoproManager) ==
STM32MP1 Platforms for Android propose an environment for developing Android applications running on the Arm Cortex-A7, combined with a remote firmware offloaded in the Arm Cortex-M4.</br>

This is based in the coprocessor service. Please check [[How to use coprocessor service for Android]] page for details.

A STCoproM4Example project, containing both Android application and Cortext-M4 firmware, is given with the STM32MP1 Developer Package for Android, and is used to illustrate below chapters.

===Software running on Arm Cortex-M4 with STM32CubeMP1 Developer Package===
This===
It is possible to develop Arm Cortex-M4 software based on the default resources allocated in the Linux kernel device- tree (detailed in [[STM32MP15_Evaluation_boards_-_Starter_Package_for_Android#Default_resource_allocation_for_Arm-C2-AE_Cortex-C2-AE-M4|Default resources allocation for Arm Cortex-M4 in Developer Package for Android]]).

====Prerequisites====
Main components to be used:
* [[STM32CubeMX]]
* Eclipse IDE (See [[#Installing the Eclipse IDE|Installing the Eclipse IDE]])
* [[#Installing the STM32Cube MPU Package|Developer Package for STM32CubeMP1]] (''eclipse plugin for IDE software, i.e. System workbench for STM32'')

====Creating project from CubeMx====
[[STM32CubeMX]] install is done and environment is available.

As an initial CubeMx default configuration project which include supported resources allocations for Cortext-M4, please load the ioc file adapted to your used deliverySTM32CubeMX (See [[#Installing STM32CubeMX|Installing STM32CubeMX]])
* STM32CubeIDE (See [[#Installing STM32CubeIDE|Installing STM32CubeIDE]])

====Creating your project using STM32CubeMX====
It's required to configure your project using STM32CubeMX. It's possible to start from the provided STM32CubeMX project <code>.ioc</code> file which reserve (not activate and not configure) the available Cortex-M4 resources as listed in [[STM32MP15_Evaluation_boards_-_Starter_Package_for_Android#Default_resource_allocation_for_Arm-C2-AE_Cortex-C2-AE-M4|Default resources allocation for Arm Cortex-M4 in Developer Package for Android]].

At this stage, the required STM32Cube package must be downloaded and installed.

{{SoftwareLicenseAgreement | distribution=Android}}

{|class="st-table"
|-
| colspan="4" | '''STM32MPU distribution for Android&trade;'''
|-
| style="width:20%; text-align:center" | Tag
| style="width:15%; text-align:center" | Board
| style="width:35%; text-align:center" | Link
| style="width:25%; text-align:center" | Release note
|-
| st-android-1011.0.0-2020-02-212021-01-29

| STM32MP157x-EV1 Evaluation boards
| [https://www.st.com/content/ccc/resource/technical/software/application_sw-updater/firmware2//group0/42/78/e2/cb/e1/16/4d/62bf/41/04/fa/ae/c8/4c/05/STM32MP157c_Evaluation_board_Developer_Package_for_Android_CubeMx/files/st-android-1011.0.0-2020-02-212021-01-29-eval-cubemx.ioc.zip/jcr:content/translations/en.st-android-1011.0.0-2020-02-212021-01-29-eval-cubemx.ioc.zip en.st-android-1011.0.0-2020-02-212021-01-29-eval-cubemx.ioc.zip]
| [[STM32MP15 distribution for Android release note - v1.1v2.0.0 | st-android-1011.0.0-2020-10-212021-01-29 release note]]
|-
| st-android-9.0.0-2019-09-27
| STM32MP157x-EV1 Evaluation boards
| [https://www.st.com/content/ccc/resource/technical/sw-updater/firmware2/group0/d1/01/81/4b/6a/99/40/2f/STM32MP157c_Evaluation_board_Developer_Package_for_Android_CubeMx/files/st-android-9.0.0-2019-09-27-eval-cubemx.zip/jcr:content/translations/en.st-android-9.0.0-2019-09-27-eval-cubemx.zip en.st-android-9.0.0-2019-09-27-eval-cubemx.zip]
| [[STM32MP15 distribution for Android release note - v1.0.0 | st-android-9.0.0-2019-09-27 release note]]
|}

{{Warning|
It allocates some resources to the Cortext-M4, but do not configure each resources, as it depends on the way it will be used for your project.}}

====Using the Eclipse IDE for building the project====
The STCoproM4Example project, which is using the coprocessor service (CoproManager), is taken as example in this paragraph.

=====Get the source code of the example=====
Source code of the Arm Cortex-M4 software example is available on github}

At the end, the STM32CubeIDE project can be generated.
{{Info|At any time, it's possible to change the configuration using STM32CubeMX and re-generate the sources, considering that the added code in the user sections is not impacted)}}

You can also refer to the configured STM32CubeMX project <code>copro_m4example.ioc</code> associated to the STCoproM4Example firmware project available on GitHub: [https://github.com/STMicroelectronics/copro-m4example STCoproM4Example].

=====Install and build project=====
* Open the folder containing the example and double-click on file '''.project''' to open Eclipse IDE.
* When project is loaded on the eclipse IDE, then click on {{Highlight|''build''}} button to build the example
In case of issue, please find complete view with similar exmaple in [[STM32CubeMP1_Package#How to rebuild an example|How to rebuild example]] page

=====Connect the target board=====
* The board is booted, '''ST-Link''' connected to your PC (for getting console through virtual communication port), and '''USB OTG''' also connected to your PC (for getting ADB link)

* Open the '''serial console''' to check connection to the board is ok
:Click {{Highlight|''Open console on serial device''}} button
[[File:IDE_ExampleSerialConsole.png|1024px|link=]]

:A dedicated '''Console''' panel is open with prompt. You can then check you are connected to the board
 {{Board$}}:/ $ ls /
  acct       data            init.recovery.stm.rc oem         storage    
  bin        default.prop    init.usb.configfs.rc postinstall sys        
  bugreports dev             init.usb.rc          proc        system     
  cache      etc             init.zygote32.rc     product     ueventd.rc 
  charger    init            lost+found           res         vendor     
  config     init.environ.rc mnt                  sbin        
  d          init.rc         odm                  sdcard      

=====Download and run the project image on the target=====Building your project using STM32CubeIDE====
At this stage, it's possible to open the generated project using STM32CubeIDE. Pleaser refer to [[STM32CubeIDE]] user guide to understand it's usage.

The default IPC mechanism is based on a virtual UART which must be used to receive commands from the Cortex-A7 and transmit results. It's possible to refer to the example available in GitHub: [https://github.com/STMicroelectronics/copro-m4example STCoproM4Example] firmware project.

{{Warning|
The generated sources include CA7 device tree files are not needed in Android context. As mentioned, only the listed reserved Cortex-M4 resources can be used. Otherwise, it's required to use the [[STM32MP1 Distribution Package for Android]].
}}

At this stage your project has been built and a generated <code>.elf</code> file is available.

====Loading your generated image in the device====

The download of the project firmware <code>.elf</code> image (Arm Cortex-M4 firmware) on the target has to be done via command line in the STM32MP1 Developer Package for Android.

{{info|
All Firmware is performed using [[ADB]].

{{info|
All firmware <code>.elf</code> images using the coprocessor service is must be downloaded with the SW4STM32 IDE in the Linux File System in '''/vendor/firmware/copro'''}}

{{Info|Only ADB link allows to push files on the remote target board}}
* Connect [[ADB]] to the remote target board via USB OTG through Android Studio
* Check for the adb link:
 {{PC$}} adb devices
 List of devices attached
 {{HighlightParam|''<your_device_id>''}}	device

* Load the in the <code>/vendor/firmware/copro/</code> directory.
}}

To load the Arm Cortex-M4 firmware image on the target in, execute the dedicated path: {{Highlight|/vendor/firmware/copro}}.
:Example for STCoproM4Example firmware:
::''Note: root access right required for creating directory in /vendor to be able to create any new directory in /vendor''following commands using a terminal:{{PC$}} adb root; adb remount
 {{PC$}} adb push {{HighlightParam|''<path_to>''}}/copro_m4example{{HighlightParam|''<project image>''}}.elf /vendor/firmware/copro/=====How to test the Cortex-M4 firmware in standalone (without Android application)=====
This is possible to test the Cortex-M4 firmware independently from the Android application, and via the console in the IDE:

* Enable root access rights
:- Using ADB shell is ADB link available{{PC$}} adb reboot

====Testing your project====
There are several solutions to test your project on the device (using STM32CubeIDE in engineering mode, using test binary, using Android application).

It's also possible to load, start and send commands manually.

Open a console:
 {{PC$}} adb root
 {{PC$}} adb shell
 {{Board$}} ...:- or Using uart console shell:
 {{Board$}} su
 {{Board$}} ...

*
Configure the firmware to be loaded by Linux in the Cortex-M4:

 {{Board$}}:/ # echo copro/copro_m4example{{HighlightParam|<project image>}}.elf > /sys/class/remoteproc/remoteproc0/firmware
*Start the example and check in log that the firmware is running:
 {{Board$}} '''firmware:
 {{Board$}}:/ # echo start > /sys/class/remoteproc/remoteproc0/state'''
 {{Board$}} dmesg
 ...
 [13366.032915


Check that all required resources have been reserved without error
 {{Board$}}:/ # dmesg

Example of <code>dmesg</code> trace with <code>copro/copro_m4example.elf</code>:
 [ 5183.938679] remoteproc remoteproc0: powering up m4
 [13366.038707 5183.947729] remoteproc remoteproc0: Booting fw image copro/copro_m4example.elf, size 2410460
 [13366.052612] rproc-srm-dev m4@0:m4_system_resources:dac@40017000: Linked as a consumer to regulator.9
 [13366.060918] rproc-srm-dev m4@0:m4_system_resources:adc@48003000: Linked as a consumer to regulator.9
 [13366.081654] rproc-srm-core m4@0:3107616
 [ 5183.989105] rproc-srm-core mlahb:m4@10000000:m4_system_resources: bound m4@0:mlahb:m4@10000000:m4_system_resources:timer@40000000 (ops rproc_srm_dev_ops)
 [13366.081683 5184.001239] rproc-srm-core m4@0:mlahb:m4@10000000:m4_system_resources: bound m4@0:mlahb:m4@10000000:m4_system_resources:timer@40005000 (ops rproc_srm_dev_ops)
 [13366.081706 5184.014541] rproc-srm-core m4@0:mlahb:m4@10000000:m4_system_resources: bound m4@0:mlahb:m4@10000000:m4_system_resources:serial@4000f000 (ops rproc_srm_dev_ops)
 [13366.081727 5184.027795] rproc-srm-core m4@0:mlahb:m4@10000000:m4_system_resources: bound m4@0:mlahb:m4@10000000:m4_system_resources:i2c@40015000 (ops rproc_srm_dev_ops)
 [13366.084560 5184.043446] rproc-srm-core m4@0:mlahb:m4@10000000:m4_system_resources: bound m4@0:mlahb:m4@10000000:m4_system_resources:dac@40017000 (ops rproc_srm_dev_ops)
 [13366.084591 5184.055294] rproc-srm-core m4@0:mlahb:m4@10000000:m4_system_resources: bound m4@0:mlahb:m4@10000000:m4_system_resources:spi@44004000 (ops rproc_srm_dev_ops)
 [13366.084614 5184.068340] rproc-srm-core m4@0:mlahb:m4@10000000:m4_system_resources: bound m4@0:mlahb:m4@10000000:m4_system_resources:dma@48001000 (ops rproc_srm_dev_ops)
 [13366.084641 5184.081449] rproc-srm-core m4@0:mlahb:m4@10000000:m4_system_resources: bound m4@0:mlahb:m4@10000000:m4_system_resources:adc@48003000 (ops rproc_srm_dev_ops)
 [13366.084662 5184.094565] rproc-srm-core m4@0:mlahb:m4@10000000:m4_system_resources: bound m4@0:mlahb:m4@10000000:m4_system_resources:hash@4c002000 (ops rproc_srm_dev_ops)
 [13366.084682 5184.107796] rproc-srm-core m4@0:mlahb:m4@10000000:m4_system_resources: bound m4@0:mlahb:m4@10000000:m4_system_resources:rng@4c003000 (ops rproc_srm_dev_ops)
 [13366.084703 5184.120918] rproc-srm-core m4@0:mlahb:m4@10000000:m4_system_resources: bound m4@0:mlahb:m4@10000000:m4_system_resources:crc@4c004000 (ops rproc_srm_dev_ops)
 [13366.084723 5184.134054] rproc-srm-core m4@0:mlahb:m4@10000000:m4_system_resources: bound m4@0:mlahb:m4@10000000:m4_system_resources:cryp@4c005000 (ops rproc_srm_dev_ops)
 [13366.084744 5184.147277] rproc-srm-core m4@0:mlahb:m4@10000000:m4_system_resources: bound m4@0:mlahb:m4@10000000:m4_system_resources:qspi@58003000 (ops rproc_srm_dev_ops)
 [13366.084762 5184.160489] rproc-srm-core m4@0:mlahb:m4@10000000:m4_system_resources: bound m4@0:m4_system_resources:button (ops rproc_srm_dev_ops)
 [13366.084780] rproc-srm-core m4@0:m4_system_resources: bound m4@0:m4_system_resources:m4_mlahb:m4@10000000:m4_system_resources:m4_led (ops rproc_srm_dev_ops)
 [13366.085683] m4@0#vdev0buffer 5184.173700] remoteproc0#vdev0buffer: assigned reserved memory node vdev0buffer@10044000
 [13366.086750vdev0buffer@10042000
 [ 5184.182181] virtio_rpmsg_bus virtio0: rpmsg host is online
 [13366.087508] m4@0#vdev0buffer: registered virtio0 (type 7)
 [13366.087525] remoteproc remoteproc0: remote processor m4 is now up
 [13366.088987]  5184.182335] virtio_rpmsg_bus virtio0: creating channel rpmsg-tty-channel addr 0x0
 [13366.090313] rpmsg_tty virtio0.rpmsg-tty-channel.-1.0: new channel: 0x400 -> 0x0 : ttyRPMSG0

*Stop the example and check in log that the firmware is stopped:
 {{Board$}} '''echo stop > /sys/class/remoteproc/remoteproc0/state'''
 {{Board$}} dmesg
 ...
 [13431.354096 5184.187346] remoteproc0#vdev0buffer: registered virtio0 (type 7)
 [ 5184.200672] remoteproc remoteproc0: remote processor m4 is now up
 [ 5184.204352] rpmsg_tty virtio0.rpmsg-tty-channel.-1.0: rpmsg tty device 0 is removed
 [13431.862382] remoteproc remoteproc0: warning: remote FW shutdown without ack
 [13431.869044] rproc-srm-dev m4@0:m4_system_resources:dac@40017000: Dropping the link to regulator.9
 [13431.873046] rproc-srm-dev m4@0:m4_system_resources:adc@48003000: Dropping the link to regulator.9
 [13431.883389] remoteproc remoteproc0: stopped remote processor m4

=====How to debug an example with IDE=====
* Configure '''Main tab''' of the Debug Configurations panel to add the firmware binary
:'''''Menu'''''  >  ''Run''  >  {{Highlight|''Debug configuration...  /  [ Main ] tab''}}
[[File:IDE_ExampleDebugMenu.png|820px|link=]]

[[File:IDE_ExampleDebugPanelMain.png|1024px|link=]]

* Configure '''Startup tab''' of the Debug Configurations panel
:'''''Menu'''''  >  ''Run''  >  {{Highlight|''Debug configuration...  /  [ Starter ] tab''}}
:Unselect '''Load image'''
{{info|
To work in Engineering mode, you need to:
:* Select the [[STM32MP15_ROM_code_overview#Engineering_boot|Engineering boot pin]] on your board
:* Select the Engineering mode in the panel below}}

* Ensure the example firmware is running on the target.

* Run the debug mode on IDE side.

The IDE will attach the current running firmware on the Arm Cortex-M4. It is then possible to break software execution and make step by step debug.
new channel: 0x400 -> 0x0 : ttyRPMSG0

Send command:
 {{Board$}}:/ # echo {{HighlightParam|<command>}} > /dev/ttyRPMSG0

Receive returned data (to be executed in another console before sending the command):
 {{Board$}}:/ # od -c < /dev/ttyRPMSG0

Stop the firmware:
 {{Board$}}:/ # echo stop > /sys/class/remoteproc/remoteproc0/state
===Android application running on Arm Cortex-A7===
Please refer to the Android developer guide<ref>https://developer.android.com/guide</ref> for generic informationsinformation about standard Android application development.

Then based on the SDK delivered within the Developer Package for Android (see [[#Installing the SDK update|Installing the SDK update]]), this is possible to develop an application which can use the coprocessor service (CoproManager), in order to interact with remote Arm Cortex-M4 core software.

Coprocessor service detailed information and API are described in dedicated page. Please see [[How to use coprocessor service for Android]].
You 

As example, you can refer to the STCoproM4Example application for Android, and corresponding source code to get example for implementation.

Source code of the Arm Cortex-A7 software example is available on github: available on [https://github.com/STMicroelectronics/app-stcoprom4example STCoproM4ExampleGitHub].

==How to go further==
Now that your developments are ready, you may switch to the [[STM32MP1 Distribution Package for Android]] in order to create your own distribution and to generate your own SDK and image.

== References ==
<references/>

<noinclude>

[[Category:Getting started with STM32MP1 boards]]
[[Category:Developer Package]]
[[Category:Android]]
{{PublicationRequestId | 12869 | 2019-07-30}}</noinclude>
(32 intermediate revisions by 3 users not shown)
Line 15: Line 15:
 
* for the '''STM32Cube MPU Package''' (development on Arm<sup>&reg;</sup> Cortex<sup>&reg;</sup>-M processor):
 
* for the '''STM32Cube MPU Package''' (development on Arm<sup>&reg;</sup> Cortex<sup>&reg;</sup>-M processor):
 
** '''source code''' for all pieces of software (BSP, HAL, middleware and applications)
 
** '''source code''' for all pieces of software (BSP, HAL, middleware and applications)
** the '''integrated development environment (IDE)''' (STM32-CoPro-MPU Eclipse plugin)
+
** the '''integrated development environment (IDE)''' (STM32CubeIDE)
 
** a '''pre-configured project for CubeMx''' including default resources allocations for the Arm<sup>&reg;</sup> Cortex<sup>&reg;</sup>-M4
 
** a '''pre-configured project for CubeMx''' including default resources allocations for the Arm<sup>&reg;</sup> Cortex<sup>&reg;</sup>-M4
 
** a '''multicore application example using the coprocessor service''' (Android application linked with a Arm<sup>&reg;</sup> Cortex<sup>&reg;</sup>-M4 firmware)
 
** a '''multicore application example using the coprocessor service''' (Android application linked with a Arm<sup>&reg;</sup> Cortex<sup>&reg;</sup>-M4 firmware)
Line 23: Line 23:
 
Reading the [[STM32MPU Embedded Software for Android architecture overview]] is also highly recommended.
 
Reading the [[STM32MPU Embedded Software for Android architecture overview]] is also highly recommended.
   
==Installing the components to develop software running on Arm Cortex-A (STM32MPU distribution for Android)==
+
==Installing the required components to develop software running on Arm Cortex-A==
   
 
===Installing the Android Studio IDE===
 
===Installing the Android Studio IDE===
Line 45: Line 45:
   
 
|-
 
|-
| st-android-10.0.0-2020-02-21
+
| st-android-11.0.0-2021-01-29
| API 29
+
| API 30
| [https://st.com/content/ccc/resource/technical/sw-updater/firmware2/group0/70/1f/57/30/9f/48/4c/71/STM32MP1_Developer_Package_for_Android_SDK/files/st-android-10.0.0-2020-02-21-sdk-api29.zip/jcr:content/translations/en.st-android-10.0.0-2020-02-21-sdk-api29.zip en.st-android-10.0.0-2020-02-21-sdk-api29.zip]
+
| [https://st.com/content/ccc/resource/technical/software/application_sw/group0/69/08/f1/d8/38/f2/41/de/STM32MP1_Developer_Package_for_Android_SDK/files/st-android-11.0.0-2021-01-29-sdk-api30.zip/jcr:content/translations/en.st-android-11.0.0-2021-01-29-sdk-api30.zip en.st-android-11.0.0-2021-01-29-sdk-api30.zip]
| [[STM32MP15 distribution for Android release note - v1.1.0 | st-android-10.0.0-2020-02-21 release note]]
+
| [[STM32MP15 distribution for Android release note - v2.0.0 | st-android-11.0.0-2021-01-29 release note]]
|-
 
| st-android-9.0.0-2019-09-27
 
| API 28
 
| [https://www.st.com/content/ccc/resource/technical/sw-updater/firmware2/group0/6c/13/b9/39/b3/11/41/94/STM32MP1_Developer_Package_for_Android_SDK/files/st-android-9.0.0-2019-09-27-sdk-api28.zip/jcr:content/translations/en.st-android-9.0.0-2019-09-27-sdk-api28.zip en.st-android-9.0.0-2019-09-27-sdk-api28.zip]
 
| [[STM32MP15 distribution for Android release note - v1.0.0 | st-android-9.0.0-2019-09-27 release note]]
 
 
|}
 
|}
   
==Installing the components needed to develop software running on the Arm Cortex-M4 (STM32Cube MPU Package)==
+
==Installing the required components needed to develop software running on the Arm Cortex-M4==
   
===Installing the Eclipse IDE===
+
===Installing STM32CubeMX===
The table below explains how to download and install the System Workbench for the STM32 IDE, which is the AC6 product addressing the STM32 MCU, and the STM32-CoPro-MPU plugin, which provides support for Cortex-M inside the STM32 MPU.
+
Please refer to the [[STM32CubeMX]] page.
{{:STM32-CoPro-MPU plugin release note}}
 
   
===Installing the STM32Cube MPU Package===
+
===Installing STM32CubeIDE===
Prerequite: the [[#Installing the Eclipse IDE|Eclipse IDE is installed]].
+
Please refer to the [[STM32CubeIDE]] page.
{{:STM32MP1 Developer Package - STM32CubeMP1 Package}}
 
'''The STM32Cube MPU Package is now installed''': let's develop software running on Arm Cortex-M.
 
   
 
== Developing multi-core applications using the coprocessor service (CoproManager) ==
 
== Developing multi-core applications using the coprocessor service (CoproManager) ==
Line 73: Line 65:
 
A STCoproM4Example project, containing both Android application and Cortext-M4 firmware, is given with the STM32MP1 Developer Package for Android, and is used to illustrate below chapters.
 
A STCoproM4Example project, containing both Android application and Cortext-M4 firmware, is given with the STM32MP1 Developer Package for Android, and is used to illustrate below chapters.
   
===Software running on Arm Cortex-M4 with STM32CubeMP1 Developer Package===
+
===Software running on Arm Cortex-M4===
This is possible to develop Arm Cortex-M4 software based on the default resources allocated in the Linux kernel device-tree (detailed in [[STM32MP15_Evaluation_boards_-_Starter_Package_for_Android#Default_resource_allocation_for_Arm-C2-AE_Cortex-C2-AE-M4|Default resources allocation for Arm Cortex-M4 in Developer Package for Android]]).
+
It is possible to develop Arm Cortex-M4 software based on the default resources allocated in the Linux kernel device tree (detailed in [[STM32MP15_Evaluation_boards_-_Starter_Package_for_Android#Default_resource_allocation_for_Arm-C2-AE_Cortex-C2-AE-M4|Default resources allocation for Arm Cortex-M4 in Developer Package for Android]]).
   
 
====Prerequisites====
 
====Prerequisites====
 
Main components to be used:
 
Main components to be used:
* [[STM32CubeMX]]
+
* STM32CubeMX (See [[#Installing STM32CubeMX|Installing STM32CubeMX]])
* Eclipse IDE (See [[#Installing the Eclipse IDE|Installing the Eclipse IDE]])
+
* STM32CubeIDE (See [[#Installing STM32CubeIDE|Installing STM32CubeIDE]])
* [[#Installing the STM32Cube MPU Package|Developer Package for STM32CubeMP1]] (''eclipse plugin for IDE software, i.e. System workbench for STM32'')
 
   
====Creating project from CubeMx====
+
====Creating your project using STM32CubeMX====
[[STM32CubeMX]] install is done and environment is available.
+
It's required to configure your project using STM32CubeMX. It's possible to start from the provided STM32CubeMX project <code>.ioc</code> file which reserve (not activate and not configure) the available Cortex-M4 resources as listed in [[STM32MP15_Evaluation_boards_-_Starter_Package_for_Android#Default_resource_allocation_for_Arm-C2-AE_Cortex-C2-AE-M4|Default resources allocation for Arm Cortex-M4 in Developer Package for Android]].
   
As an initial CubeMx default configuration project which include supported resources allocations for Cortext-M4, please load the ioc file adapted to your used delivery.
+
At this stage, the required STM32Cube package must be downloaded and installed.
   
 
{{SoftwareLicenseAgreement | distribution=Android}}
 
{{SoftwareLicenseAgreement | distribution=Android}}
Line 98: Line 89:
 
| style="width:25%; text-align:center" | Release note
 
| style="width:25%; text-align:center" | Release note
 
|-
 
|-
| st-android-10.0.0-2020-02-21
+
| st-android-11.0.0-2021-01-29
| STM32MP157x-EV1 Evaluation boards
 
| [https://www.st.com/content/ccc/resource/technical/sw-updater/firmware2/group0/42/78/e2/cb/e1/16/4d/62/STM32MP157c_Evaluation_board_Developer_Package_for_Android_CubeMx/files/st-android-10.0.0-2020-02-21-eval-cubemx.zip/jcr:content/translations/en.st-android-10.0.0-2020-02-21-eval-cubemx.zip en.st-android-10.0.0-2020-02-21-eval-cubemx.zip]
 
| [[STM32MP15 distribution for Android release note - v1.1.0 | st-android-10.0.0-2020-10-21 release note]]
 
|-
 
| st-android-9.0.0-2019-09-27
 
 
| STM32MP157x-EV1 Evaluation boards
 
| STM32MP157x-EV1 Evaluation boards
| [https://www.st.com/content/ccc/resource/technical/sw-updater/firmware2/group0/d1/01/81/4b/6a/99/40/2f/STM32MP157c_Evaluation_board_Developer_Package_for_Android_CubeMx/files/st-android-9.0.0-2019-09-27-eval-cubemx.zip/jcr:content/translations/en.st-android-9.0.0-2019-09-27-eval-cubemx.zip en.st-android-9.0.0-2019-09-27-eval-cubemx.zip]
+
| [https://st.com/content/ccc/resource/technical/software/application_sw/group0/bf/41/04/fa/ae/c8/4c/05/STM32MP157c_Evaluation_board_Developer_Package_for_Android_CubeMx/files/st-android-11.0.0-2021-01-29-eval-cubemx.ioc.zip/jcr:content/translations/en.st-android-11.0.0-2021-01-29-eval-cubemx.ioc.zip en.st-android-11.0.0-2021-01-29-eval-cubemx.ioc.zip]
| [[STM32MP15 distribution for Android release note - v1.0.0 | st-android-9.0.0-2019-09-27 release note]]
+
| [[STM32MP15 distribution for Android release note - v2.0.0 | st-android-11.0.0-2021-01-29 release note]]
 
|}
 
|}
   
  +
At the end, the STM32CubeIDE project can be generated.
  +
{{Info|At any time, it's possible to change the configuration using STM32CubeMX and re-generate the sources, considering that the added code in the user sections is not impacted)}}
   
{{Warning|
+
You can also refer to the configured STM32CubeMX project <code>copro_m4example.ioc</code> associated to the STCoproM4Example firmware project available on GitHub: [https://github.com/STMicroelectronics/copro-m4example STCoproM4Example].
It allocates some resources to the Cortext-M4, but do not configure each resources, as it depends on the way it will be used for your project.}}
 
   
====Using the Eclipse IDE for building the project====
+
====Building your project using STM32CubeIDE====
The STCoproM4Example project, which is using the coprocessor service (CoproManager), is taken as example in this paragraph.
+
At this stage, it's possible to open the generated project using STM32CubeIDE. Pleaser refer to [[STM32CubeIDE]] user guide to understand it's usage.
   
=====Get the source code of the example=====
+
The default IPC mechanism is based on a virtual UART which must be used to receive commands from the Cortex-A7 and transmit results. It's possible to refer to the example available in GitHub: [https://github.com/STMicroelectronics/copro-m4example STCoproM4Example] firmware project.
Source code of the Arm Cortex-M4 software example is available on github: [https://github.com/STMicroelectronics/copro-m4example STCoproM4Example].
 
   
=====Install and build project=====
+
{{Warning|
* Open the folder containing the example and double-click on file '''.project''' to open Eclipse IDE.
+
The generated sources include CA7 device tree files are not needed in Android context. As mentioned, only the listed reserved Cortex-M4 resources can be used. Otherwise, it's required to use the [[STM32MP1 Distribution Package for Android]].
* When project is loaded on the eclipse IDE, then click on {{Highlight|''build''}} button to build the example
+
}}
In case of issue, please find complete view with similar exmaple in [[STM32CubeMP1_Package#How to rebuild an example|How to rebuild example]] page
 
   
=====Connect the target board=====
+
At this stage your project has been built and a generated <code>.elf</code> file is available.
* The board is booted, '''ST-Link''' connected to your PC (for getting console through virtual communication port), and '''USB OTG''' also connected to your PC (for getting ADB link)
 
   
* Open the '''serial console''' to check connection to the board is ok
+
====Loading your generated image in the device====
:Click {{Highlight|''Open console on serial device''}} button
+
The download of the firmware <code>.elf</code> image (Arm Cortex-M4 firmware) on the target is performed using [[ADB]].
[[File:IDE_ExampleSerialConsole.png|1024px|link=]]
 
 
 
:A dedicated '''Console''' panel is open with prompt. You can then check you are connected to the board
 
{{Board$}}:/ $ ls /
 
  acct      data            init.recovery.stm.rc oem        storage   
 
  bin        default.prop    init.usb.configfs.rc postinstall sys       
 
  bugreports dev            init.usb.rc          proc        system   
 
  cache      etc            init.zygote32.rc    product    ueventd.rc
 
  charger    init            lost+found          res        vendor   
 
  config    init.environ.rc mnt                  sbin       
 
  d          init.rc        odm                  sdcard     
 
 
 
 
 
=====Download and run the project image on the target=====
 
The download of the project image (Arm Cortex-M4 firmware) on the target has to be done via command line in the STM32MP1 Developer Package for Android.
 
   
 
{{info|
 
{{info|
All Firmware using the coprocessor service is downloaded with the SW4STM32 IDE in the Linux File System in '''/vendor/firmware/copro'''}}
+
All firmware <code>.elf</code> images using the coprocessor service must be downloaded in the <code>/vendor/firmware/copro/</code> directory.
  +
}}
   
{{Info|Only ADB link allows to push files on the remote target board}}
 
* Connect [[ADB]] to the remote target board via USB OTG through Android Studio
 
* Check for the adb link:
 
{{PC$}} adb devices
 
List of devices attached
 
{{HighlightParam|''<your_device_id>''}} device
 
   
* Load the Arm Cortex-M4 firmware on the target in the dedicated path: {{Highlight|/vendor/firmware/copro}}.
+
To load the Arm Cortex-M4 firmware image on the target, execute the following commands using a terminal:
:Example for STCoproM4Example firmware:
 
::''Note: root access right required for creating directory in /vendor to be able to create any new directory in /vendor''
 
 
  {{PC$}} adb root; adb remount
 
  {{PC$}} adb root; adb remount
  {{PC$}} adb push {{HighlightParam|''<path_to>''}}/copro_m4example.elf /vendor/firmware/copro/
+
  {{PC$}} adb push {{HighlightParam|''<path_to>''}}/{{HighlightParam|''<project image>''}}.elf /vendor/firmware/copro/
  +
{{PC$}} adb reboot
   
=====How to test the Cortex-M4 firmware in standalone (without Android application)=====
+
====Testing your project====
This is possible to test the Cortex-M4 firmware independently from the Android application, and via the console in the IDE:
+
There are several solutions to test your project on the device (using STM32CubeIDE in engineering mode, using test binary, using Android application).
   
* Enable root access rights
+
It's also possible to load, start and send commands manually.
:- Using ADB shell is ADB link available:
+
 
  +
Open a console:
 
  {{PC$}} adb root
 
  {{PC$}} adb root
 
  {{PC$}} adb shell
 
  {{PC$}} adb shell
 
  {{Board$}} ...
 
  {{Board$}} ...
:- or Using uart console shell:
 
{{Board$}} su
 
{{Board$}} ...
 
 
*Configure the firmware to be loaded by Linux in the Cortex-M4
 
{{Board$}}:/ # echo copro/copro_m4example.elf > /sys/class/remoteproc/remoteproc0/firmware
 
   
*Start the example and check in log that the firmware is running:
+
Configure the firmware to be loaded by Linux in the Cortex-M4:
  {{Board$}} '''echo start > /sys/class/remoteproc/remoteproc0/state'''
+
  {{Board$}}:/ # echo copro/{{HighlightParam|<project image>}}.elf > /sys/class/remoteproc/remoteproc0/firmware
{{Board$}} dmesg
 
...
 
[13366.032915] remoteproc remoteproc0: powering up m4
 
[13366.038707] remoteproc remoteproc0: Booting fw image copro/copro_m4example.elf, size 2410460
 
[13366.052612] rproc-srm-dev m4@0:m4_system_resources:dac@40017000: Linked as a consumer to regulator.9
 
[13366.060918] rproc-srm-dev m4@0:m4_system_resources:adc@48003000: Linked as a consumer to regulator.9
 
[13366.081654] rproc-srm-core m4@0:m4_system_resources: bound m4@0:m4_system_resources:timer@40000000 (ops rproc_srm_dev_ops)
 
[13366.081683] rproc-srm-core m4@0:m4_system_resources: bound m4@0:m4_system_resources:timer@40005000 (ops rproc_srm_dev_ops)
 
[13366.081706] rproc-srm-core m4@0:m4_system_resources: bound m4@0:m4_system_resources:serial@4000f000 (ops rproc_srm_dev_ops)
 
[13366.081727] rproc-srm-core m4@0:m4_system_resources: bound m4@0:m4_system_resources:i2c@40015000 (ops rproc_srm_dev_ops)
 
[13366.084560] rproc-srm-core m4@0:m4_system_resources: bound m4@0:m4_system_resources:dac@40017000 (ops rproc_srm_dev_ops)
 
[13366.084591] rproc-srm-core m4@0:m4_system_resources: bound m4@0:m4_system_resources:spi@44004000 (ops rproc_srm_dev_ops)
 
[13366.084614] rproc-srm-core m4@0:m4_system_resources: bound m4@0:m4_system_resources:dma@48001000 (ops rproc_srm_dev_ops)
 
[13366.084641] rproc-srm-core m4@0:m4_system_resources: bound m4@0:m4_system_resources:adc@48003000 (ops rproc_srm_dev_ops)
 
[13366.084662] rproc-srm-core m4@0:m4_system_resources: bound m4@0:m4_system_resources:hash@4c002000 (ops rproc_srm_dev_ops)
 
[13366.084682] rproc-srm-core m4@0:m4_system_resources: bound m4@0:m4_system_resources:rng@4c003000 (ops rproc_srm_dev_ops)
 
[13366.084703] rproc-srm-core m4@0:m4_system_resources: bound m4@0:m4_system_resources:crc@4c004000 (ops rproc_srm_dev_ops)
 
[13366.084723] rproc-srm-core m4@0:m4_system_resources: bound m4@0:m4_system_resources:cryp@4c005000 (ops rproc_srm_dev_ops)
 
[13366.084744] rproc-srm-core m4@0:m4_system_resources: bound m4@0:m4_system_resources:qspi@58003000 (ops rproc_srm_dev_ops)
 
[13366.084762] rproc-srm-core m4@0:m4_system_resources: bound m4@0:m4_system_resources:button (ops rproc_srm_dev_ops)
 
[13366.084780] rproc-srm-core m4@0:m4_system_resources: bound m4@0:m4_system_resources:m4_led (ops rproc_srm_dev_ops)
 
[13366.085683] m4@0#vdev0buffer: assigned reserved memory node vdev0buffer@10044000
 
[13366.086750] virtio_rpmsg_bus virtio0: rpmsg host is online
 
[13366.087508] m4@0#vdev0buffer: registered virtio0 (type 7)
 
[13366.087525] remoteproc remoteproc0: remote processor m4 is now up
 
[13366.088987] virtio_rpmsg_bus virtio0: creating channel rpmsg-tty-channel addr 0x0
 
[13366.090313] rpmsg_tty virtio0.rpmsg-tty-channel.-1.0: new channel: 0x400 -> 0x0 : ttyRPMSG0
 
   
*Stop the example and check in log that the firmware is stopped:
+
Start the firmware:
  {{Board$}} '''echo stop > /sys/class/remoteproc/remoteproc0/state'''
+
  {{Board$}}:/ # echo start > /sys/class/remoteproc/remoteproc0/state
{{Board$}} dmesg
 
...
 
[13431.354096] rpmsg_tty virtio0.rpmsg-tty-channel.-1.0: rpmsg tty device 0 is removed
 
[13431.862382] remoteproc remoteproc0: warning: remote FW shutdown without ack
 
[13431.869044] rproc-srm-dev m4@0:m4_system_resources:dac@40017000: Dropping the link to regulator.9
 
[13431.873046] rproc-srm-dev m4@0:m4_system_resources:adc@48003000: Dropping the link to regulator.9
 
[13431.883389] remoteproc remoteproc0: stopped remote processor m4
 
   
=====How to debug an example with IDE=====
+
Check that all required resources have been reserved without error
* Configure '''Main tab''' of the Debug Configurations panel to add the firmware binary
+
  {{Board$}}:/ # dmesg
:'''''Menu'''''  >  ''Run''  > {{Highlight|''Debug configuration...  /  [ Main ] tab''}}
 
[[File:IDE_ExampleDebugMenu.png|820px|link=]]
 
   
[[File:IDE_ExampleDebugPanelMain.png|1024px|link=]]
+
Example of <code>dmesg</code> trace with <code>copro/copro_m4example.elf</code>:
 
+
[ 5183.938679] remoteproc remoteproc0: powering up m4
* Configure '''Startup tab''' of the Debug Configurations panel
+
[ 5183.947729] remoteproc remoteproc0: Booting fw image copro/copro_m4example.elf, size 3107616
:'''''Menu''''' > ''Run'' > {{Highlight|''Debug configuration...  / [ Starter ] tab''}}
+
[ 5183.989105] rproc-srm-core mlahb:m4@10000000:m4_system_resources: bound mlahb:m4@10000000:m4_system_resources:timer@40000000 (ops rproc_srm_dev_ops)
:Unselect '''Load image'''
+
[ 5184.001239] rproc-srm-core mlahb:m4@10000000:m4_system_resources: bound mlahb:m4@10000000:m4_system_resources:timer@40005000 (ops rproc_srm_dev_ops)
{{info|
+
[ 5184.014541] rproc-srm-core mlahb:m4@10000000:m4_system_resources: bound mlahb:m4@10000000:m4_system_resources:serial@4000f000 (ops rproc_srm_dev_ops)
To work in Engineering mode, you need to:
+
[ 5184.027795] rproc-srm-core mlahb:m4@10000000:m4_system_resources: bound mlahb:m4@10000000:m4_system_resources:i2c@40015000 (ops rproc_srm_dev_ops)
:* Select the [[STM32MP15_ROM_code_overview#Engineering_boot|Engineering boot pin]] on your board
+
[ 5184.043446] rproc-srm-core mlahb:m4@10000000:m4_system_resources: bound mlahb:m4@10000000:m4_system_resources:dac@40017000 (ops rproc_srm_dev_ops)
:* Select the Engineering mode in the panel below}}
+
  [ 5184.055294] rproc-srm-core mlahb:m4@10000000:m4_system_resources: bound mlahb:m4@10000000:m4_system_resources:spi@44004000 (ops rproc_srm_dev_ops)
  +
  [ 5184.068340] rproc-srm-core mlahb:m4@10000000:m4_system_resources: bound mlahb:m4@10000000:m4_system_resources:dma@48001000 (ops rproc_srm_dev_ops)
  +
  [ 5184.081449] rproc-srm-core mlahb:m4@10000000:m4_system_resources: bound mlahb:m4@10000000:m4_system_resources:adc@48003000 (ops rproc_srm_dev_ops)
  +
  [ 5184.094565] rproc-srm-core mlahb:m4@10000000:m4_system_resources: bound mlahb:m4@10000000:m4_system_resources:hash@4c002000 (ops rproc_srm_dev_ops)
  +
[ 5184.107796] rproc-srm-core mlahb:m4@10000000:m4_system_resources: bound mlahb:m4@10000000:m4_system_resources:rng@4c003000 (ops rproc_srm_dev_ops)
  +
[ 5184.120918] rproc-srm-core mlahb:m4@10000000:m4_system_resources: bound mlahb:m4@10000000:m4_system_resources:crc@4c004000 (ops rproc_srm_dev_ops)
  +
  [ 5184.134054] rproc-srm-core mlahb:m4@10000000:m4_system_resources: bound mlahb:m4@10000000:m4_system_resources:cryp@4c005000 (ops rproc_srm_dev_ops)
  +
  [ 5184.147277] rproc-srm-core mlahb:m4@10000000:m4_system_resources: bound mlahb:m4@10000000:m4_system_resources:qspi@58003000 (ops rproc_srm_dev_ops)
  +
[ 5184.160489] rproc-srm-core mlahb:m4@10000000:m4_system_resources: bound mlahb:m4@10000000:m4_system_resources:m4_led (ops rproc_srm_dev_ops)
  +
[ 5184.173700] remoteproc0#vdev0buffer: assigned reserved memory node vdev0buffer@10042000
  +
[ 5184.182181] virtio_rpmsg_bus virtio0: rpmsg host is online
  +
[ 5184.182335] virtio_rpmsg_bus virtio0: creating channel rpmsg-tty-channel addr 0x0
  +
[ 5184.187346] remoteproc0#vdev0buffer: registered virtio0 (type 7)
  +
[ 5184.200672] remoteproc remoteproc0: remote processor m4 is now up
  +
[ 5184.204352] rpmsg_tty virtio0.rpmsg-tty-channel.-1.0: new channel: 0x400 -> 0x0 : ttyRPMSG0
   
* Ensure the example firmware is running on the target.
+
Send command:
  +
{{Board$}}:/ # echo {{HighlightParam|<command>}} > /dev/ttyRPMSG0
   
* Run the debug mode on IDE side.
+
Receive returned data (to be executed in another console before sending the command):
  +
{{Board$}}:/ # od -c < /dev/ttyRPMSG0
   
The IDE will attach the current running firmware on the Arm Cortex-M4. It is then possible to break software execution and make step by step debug.
+
Stop the firmware:
  +
{{Board$}}:/ # echo stop > /sys/class/remoteproc/remoteproc0/state
   
 
===Android application running on Arm Cortex-A7===
 
===Android application running on Arm Cortex-A7===
Please refer to the Android developer guide<ref>https://developer.android.com/guide</ref> for generic informations about standard Android application development.
+
Please refer to the Android developer guide<ref>https://developer.android.com/guide</ref> for generic information about standard Android application development.
   
 
Then based on the SDK delivered within the Developer Package for Android (see [[#Installing the SDK update|Installing the SDK update]]), this is possible to develop an application which can use the coprocessor service (CoproManager), in order to interact with remote Arm Cortex-M4 core software.
 
Then based on the SDK delivered within the Developer Package for Android (see [[#Installing the SDK update|Installing the SDK update]]), this is possible to develop an application which can use the coprocessor service (CoproManager), in order to interact with remote Arm Cortex-M4 core software.
Line 244: Line 183:
 
Coprocessor service detailed information and API are described in dedicated page. Please see [[How to use coprocessor service for Android]].
 
Coprocessor service detailed information and API are described in dedicated page. Please see [[How to use coprocessor service for Android]].
   
You can refer to the STCoproM4Example application for Android, and corresponding source code to get example for implementation.
 
   
Source code of the Arm Cortex-A7 software example is available on github: [https://github.com/STMicroelectronics/app-stcoprom4example STCoproM4Example].
+
As example, you can refer to the STCoproM4Example application available on [https://github.com/STMicroelectronics/app-stcoprom4example GitHub].
   
 
==How to go further==
 
==How to go further==