OP-TEE remoteproc framework overview

Applicable for

1. Framework purpose[edit source]

The OP-TEE remote processor (RPROC) framework allows the different platforms/architectures to control (power on, load firmware, power off) remote processors in the Secure context. In addition it offers services to authenticate the firmware image and isolate the associated to ensure the integrity of the firmware running on the coprocessor.

2. System overview[edit source]

2.1. Component description[edit source]

remoteproc Trusted application(TA): this is the remote processor framework generic part. Its role is to provide interface to the Linux remoteproc framework to:
- Load and authenticate a firmware image in the remote processor memory.
- Provide resource table address.
- Control the remote processor execution (start, stop...).
remoteproc Pseudo Trusted application(PTA): this component is the STM32MPU platform implementation of the services associated to the management of the Cortex-M coprocessor. Its role is to provide atomic services to the remoteproc TA:
- Load and authenticate image segment in the remote processor memory.
- manage the memory regions isolations
stm32mp_remoteproc driver: configuration of the Cortex-M coprocessor and associated memory based on the OP-TEE device tree.Based on the device tree configurationits role is to:
- Determine if the Cortex-M firmware image is managed by:
  - The OP-TEE remoteproc framework ( signed firmware images): In this configuration the remoteproc driver list the memory regions declared in the device tree for the Cortex-M usage. and manage the Cortex-M configuration (reset, boot address, Trust Zone,...)
  - The Linux remoteproc framework (ELF firmware image): In this configuration the remoteproc driver disables the Trust Zone and provides access right to the Linux remoteproc framework, in the non secure context, to manage the Cortex-M (reset and non secure boot address).

Information

In the STM32MPU Embedded Software distribution, the OP-TEE remoteproc framework imposes that the remoteproc firmware is signed to use the Cortex-M Trust Zone

2.2. API description[edit source]

The emoteproc TA API is available in ta/remoteproc/include/ta_remoteproc.h .
The remoteproc PTA API is available in lib/libutee/include/remoteproc_pta.h .

3. Configuration[edit source]

3.1. build configuration[edit source]

CFG_DRIVERS_REMOTEPROC and CFG_STM32MP_REMOTEPROC enable the support the stm32_remoteproc drivers
CFG_REMOTEPROC_PTA enables the support of the remoteproc PTA but also the remoteproc TA
CFG_IN_TREE_EARLY_TAS += remoteproc/80a4c275-0a47-4905-8285-1486a9771a08 specifies that the remoteproc TA is embedded in the OP-TEE OS firmware and accessible during the boot stage (refer to How_to_start_the_coprocessor_from_the_bootloader for detail))
RPROC_SIGN_KEY specify the key used for the firmware image signature (default key is keys/default.pem )

3.2. Device tree configuration[edit source]

The XXX framework generic DT bindings and the detailed DT configuration for STM32 internal peripherals associated with the XXX framework must be described in dedicated (separated) articles (one per internal peripheral) that follow the Contributors:Peripheral or framework device tree configuration model. Indeed, these articles might be referenced not only in "internal peripheral" articles, but also in "internal peripheral Linux driver" articles and in "framework overview" articles.

However, if the XXX framework is associated with several STM32 internal peripherals, it might be pertinent to refer here to the common parts of the DT configuration.

See examples in GPIOLib overview#Device tree configuration or in IIO overview#Device tree configuration

Use the following generic bullet if there are common parts of the DT configuration to explain to the the readers

XXX generic DT bindings:

...

Detailed DT configuration for STM32 internal peripherals:

Links to internal peripheral device tree configuration articles

4. How to use the framework[edit source]

The objective of this chapter is to explain to the readers how to use the XXX framework and its underlying Linux drivers and internal peripherals.

To detail a little more, "how to use" aims, to demonstrate that these elements (framework, drivers and internal peripherals) are working correctly, to show how to use the APIs listed in #API description, and to help the readers to create their own applications on top of these elements.

"How to use" could take different forms from simple command lines to execute standard Linux tools, complex scripts (Python, Perl...), standard applications (e.g. GStreamer video player, Java applications...), to standard or ST specific C code.

The objectives and levels defined for the Linux examples fit with the needs of this chapter. So, generally speaking, it might be enough to link here to the "how to" articles written for the Linux examples. See example in IIO overview#How to use the framework. Note that these "how to" articles might be referenced not only in the "framework overview" articles, but also in the "internal peripheral Linux driver" articles.

Obviously, additional information that you consider out of the "how to" articles scope, might be added in this chapter. This information might be source code, that explains how to use the APIs, but that is not a complete buildable C application. See example in Pinctrl overview#How to use the framework.

5. How to trace and debug the framework[edit source]

The objective of this chapter is to give methods to monitor, trace and debug the XXX framework. This chapter must be present: it is mandatory to have at least one method presented.

5.1. How to monitor[edit source]

Give instructions to help developer/user to get information about this framework in the Linux file system. Monitoring is understood here as getting static status about the framework.

5.1.1. How to monitor with debugfs[edit source]

5.1.2. Other ways of monitoring[edit source]

Up to framework owner to add any relevant other ways to monitor the framework (e.g. device entry, sysfs, procfs...).

5.2. How to trace[edit source]

Give instructions to help developer/user for getting trace(s) via:

dynamic debug if exist,
specific log files if exist,
dmesg output information,
...

Tracing is understood here as getting dynamic logs about the framework.

Up to framework owner to add any relevant other ways to trace the framework.

5.3. How to debug[edit source]

Give recommendations and tips to developers/users for debugging this framework:

How to efficiently use the monitoring and trace instructions presented above to debug some "well-known" problems
How to proceed front of some critical situations (e.g. error messages). Note that there are several ways to describe the debugging procedure:
- It might be enough to link to a Web article
- If the explanation takes few lines, a subchapter (or a bullet) is enough
- If the explanation is long, a dedicated "how to" article is recommended
Other instructions than the ones presented in the monitoring and trace subchapters above might be proposed
It might also be interesting to highlight some Trace and debug tools that are very helpful to debug the XXX framework

6. Source code location[edit source]

The objective of this chapter is to indicate the location of the XXX framework source code.

See the example in GPIOLib overview#Source code location.

You can use the following way to present the source code location: "The XXX framework is composed of:"

Set links to the files (".c", ".h", ".txt"...) thanks to the Template:CodeSource. See examples in Template:CodeSource#Example.

7. To go further[edit source]

The objective of this chapter is to give extra information such as links to online trainings, recommended books, tips and tricks that it is not pertinent to put in the other chapters.