Resource manager for coprocessing

1. Principles[edit source]

The multiprocessors enables the possibility to run independent firmwares on several cores. Under that context, a core could use some peripherals without knowledge of the usage of these same peripherals on the other core(s). This fact introduces potential contentions that must be secured by a policy management. Refer to STM32MP15 peripherals overview for more information on peripherals.

The role of the resource management is to control the assignment of a peripheral to a dedicated core and to provide a method to configure the system resources used to operate that peripheral.

1.1. Terminology[edit source]

To understand the STM32 resource management mechanism, there are some terms the user might be familiar with:

Assignment: a peripheral assignment to a core means that a peripheral (or hardware block) is used by that processor.
System resource: a shared resource required to operate the peripheral and controlled by the master core.

1.2. The system resources[edit source]

A peripheral needs some external resources to properly run. These resources are clocks, interrupt lines, signal lines, pins, regulators, etc.

Whereas some of these resources (for instance interrupts, clock gatings, resets) are instantiated for each core, some other ones (defined as system resources) are shared by both cores. To avoid contention on these system resources, developer has to pay attention on how to control these specific resources.

The system resources are divided in two categories:

The system resources shared by Arm Cortex-A an Cortex-M contexts and protected by an hardware semaphore:

Pin: the pin configuration
External interrupt (EXTI): the bind between the GPIO and the associated EXTI interrupt.

For details on system resources managed by hardware semaphore please refer to System resource protection by hardware semaphore article.

The system resources controlled only by Linux through the resource manager framework:

Clock tree: the clock configuration is managed by the Linux clock framework. The coprocessor is in charge of the clock gating for the peripheral assigned to Cortex-M4 context.
Regulator: the power supply is managed by the Linux regulator framework.

This page focuses only on the system resources managed by Linux thanks to the resource manager.

1.3. Resource management in term of services[edit source]

To ensure coexistence of the two firmware, the resource management provides several services which are detailed in the next sections:

Peripheral assignment request service: mechanism used to ensure that a peripheral is reserved for an exclusive processor context usage.
System resource configuration set: services available in the main processor (Arm^® Cortex-A running Linux^®) to configure the system resources needed to operate the peripheral on the coprocessor.
Dynamic system resource update service: services based on remote processing messaging that allows the coprocessor to ask the main processor to update the system resources configuration.

2. Peripheral assignment to a runtime context[edit source]

2.1. Principle[edit source]

The term peripheral assignment is used to identify the action to assign a set of peripherals to a runtime context. This service relies on:

ETZPC internal peripheral which controls the bus firewall to secure and/or MCU-isolate some peripherals (such as I2Cn or USARTn):

The access to a secured peripheral from a non-secure world (Linux, M4 firmware) is not possible (Bus error)
The access to a Cortex-M MCU-isolated peripheral from the Cortex-A MPU is not possible (Bus error)
ETZPC internal peripheral is configured during the boot stage by TF-A

The peripheral assignment request service: a mechanism used to ensure that a peripheral can be accessed by a context.

Information

The peripheral assignment service does not configure the system resources associated to the peripheral. The way to configure the system resources is described in system resource manager

2.2. Overview[edit source]

Cortex-A components:

stm32 driver XXX: Linux driver in charge of the peripheral XXX, it must be disabled as peripheral is used by Cortex-M
stm32 driver YYY: Linux driver in charge of the peripheral YYY, it must be enabled as peripheral is used by Cortex-A
Device tree: refer to the Linux kernel device tree

Cortex-M components:

HAL_XXX: HAL driver in charge of the peripheral XXX
ResourceManager: STM32Cube utility implementing the peripheral assignment request service. In charge of requesting peripheral accessibility and reconfiguring system resources.

HW components:

ETZPC: protection controller of bus firewall (refer to ETZPC internal peripheral).

2.3. Assignment[edit source]

The assignment is set by the boot stage. See How to assign an internal peripheral to a runtime context for details.

2.4. Example of a peripheral assignment[edit source]

Refer to How to assign an internal peripheral to a runtime context for examples.

3. System resource configuration set service[edit source]

3.1. Principle[edit source]

This service is dedicated to peripheral assigned to the Cortex-M context. It is mainly managed on the Cortex-A by Linux. A remote processor system resource manager (rproc_srm) permits the assignment and configuration of the system resources of a peripheral assigned to the Cortex-M coprocessor.

3.2. Overview[edit source]

Cortex-A components:

rproc_srm_core: system resource manager core part which is in charge of parsing its device tree node for peripherals assigned to the Cortex-M.
rproc_srm_dev: device driver that reserves and configures the system resources needed by the peripheral assigned to the coprocessor. One instance of the driver is created per peripheral declared in the device tree resource manager node.
remoteproc: in charge of probing the resource manager before loading the Cortex-M firmware. Refer to Linux remoteproc framework overview.

Cortex-M components:

HAL_RCC: HAL driver in charge of the reset and clock control (RCC) peripheral.
HAL_X: HAL driver in charge of the peripheral X.
HAL_..._MSP: peripheral system level initialization user callback.

3.2.1. System resource manager on the Cortex-A[edit source]

The configuration of the system resources for the Cortex-M is done in the m4_system_resources node of the Linux kernel device tree.

The rproc_srm driver parses this node to configure these resources.

Inside that node, the resources of each device controlled by the coprocessor must be described in a sub-node with the following template:

 m4_system_resources {
 	compatible = "rproc-srm-core";
 	status = "okay";
 
	/* System resources for peripheral A */
	<m4_aliasA>: <deviceA>@<addressA> {
		compatible = "rproc-srm-dev";
		reg = <...>;
		clocks = <...>;
		clock-names = "...";
		x-supply = <...>;
		status = "okay";
	};

	/* System resources for peripheral B */
	<m4_aliasB>: <deviceB>@<addressB> {
		compatible = "rproc-srm-dev";
		reg = <...>;
		clocks = <...>;
		clock-names = "...";
		x-supply = <...>;
		status = "okay";
	};

 };

In addition it is also possible (so optional) to add in the peripheral nodes the declaration of the EXTI interrupts, and GPIOs.

For these system resources protected by hardware semaphore, the resource manager reserves the resource in Linux. This action allows, for debug purpose, to verify that the resource is not also reserved to Linux.

	
&m4_usart2 {
	interrupt-parent = <&exti>;
	interrupts = <27 1>;
	pinctrl-names = "rproc_default";
	pinctrl-0 = <&usart2_pins_a>;
};

Note that:

The most part of the m4_system_resources node and sub-nodes is already defined (with a 'disabled' status) in the ST delivered device tree.
The system resource configuration and peripheral assignment concepts are complementary:

Enabling the m4_system_resources node allows to configure some system resources for the Cortex-M.
Enabling the m4_system_resources node is not sufficient to guaranty assignment of this peripheral to the Cortex-M. See peripheral assignment for more details

3.2.2. Resource management on the Cortex-M firmware[edit source]

The system resource configuration (assigned to the Cortex-M) is deported on the Cortex-A and managed by the Linux framework.

As a consequence system resource configuration has to be performed depending on the system context.
For details please refer to System resource management on the Cortex M4 firmware article.

3.3. Is System resource configuration set service mandatory in my project?[edit source]

STMicroelectronics strongly recommends the use of the system resource configuration set service to:

Ensure coherency in the system.
Avoid concurrency access to system resource register.
Allow Linux framework to efficiently manage the resources, thanks to the knowledge of the resource used by Cortex-M context.

For example, this can prevent a peripheral assigned to the Cortex-M from being unclocked, when the Cortex-A enters in a low-power mode or no longer uses the peripheral's parent clock.

3.4. Example of a system resources configuration[edit source]

Refer to How to assign an internal peripheral to a runtime context for examples.

4. Dynamic system resource update service[edit source]

4.1. Principle[edit source]

Thanks to the system resource configuration set service described above, the Cortex-A context configures the system resources needed to operate peripherals in the Cortex-M context.

With the dynamic system resource update service, the Cortex-M context can ask the Cortex-A context to update the configuration of these resources during runtime.

This service relies on the rpmsg framework which is implemented by Linux rpmsg on Cortex-A and OpenAMP on Cortex-M. The Cortex-M ResourceManager uses a dedicated rpmsg channel to communicate with the Cortex-A.

This service offers the ability to get and set the following configurations:

Clock rate
Regulator enable / disable, voltage (min/max)

4.2. Overview[edit source]

Cortex-A components:

rproc_srm_core: system resource manager core part which is in charge of parsing the device tree for peripherals assigned to the Cortex-M and in charge of exchanging messages with the remote processor ResourceManager.
rproc_srm_dev: device driver that reserves and configures the system resources needed by the peripheral assigned to the coprocessor. One instance of the driver is created per peripheral declared in the device tree.
remoteproc: refer to Linux remoteproc framework overview.
rpmsg: refer to Linux RPMsg framework overview.
STM32 IPCC: Linux IPCC device driver.

Cortex-M components:

HAL_XXX: HAL driver in charge of the peripheral XXX.
HAL_IPCC: HAL driver in charge of the IPCC internal peripheral.
OpenAMP: library implementing the RPMsg service. Refer to OpenAMP.
ResourceManager: utility in charge of requesting peripheral accessibility and configuring system resources.

4.2.1. Cortex-A[edit source]

The Linux rproc_srm component implements the dynamic system resource update service relying on the rproc_srm rpmsg service.

The system resources that are declared in the m4_system_resources node (refer to system resource declaration) are the ones that can be configured by the Cortex-M.

rproc_srm_core receives the configuration update (or read) requests from the Cortex-M through an rpmsg channel, and in turn, rproc_srm_dev updates (or reads) the configuration of these resources.

4.2.2. Cortex-M[edit source]

4.2.2.1. Enable the service[edit source]

In order to use the dynamic system resource update service, the RESMGR_WITH_RPMSG option must be set in the Resource Manager configuration file (res_mgr_conf.h)

...
/** @defgroup RES_MGR_RPMSG extension
  * @{
  */
#define RESMGR_WITH_RPMSG

/**
  * @}
  */
...

4.2.2.2. Initialize the service[edit source]

The ResourceManger, its underlying OpenAMP framework and the IPCC HAL driver must be initialized before using the service. The initialization sequence must follow the he IPCC / OpenAMP / ResourceManager order.

4.2.2.3. Use the service[edit source]

In order to update the configuration of a system resource, the application has to call the ResourceManager SetConfig API. The GetConfig API can be used to read the configuration of a resource.

4.3. Example of system resource dynamic reconfiguration[edit source]

Refer to reconfigure the system resources during runtime for examples.

5. Linux kernel configuration[edit source]

The System resource configuration set and the Dynamic system resource update services require the resource manager support to be enabled in the Linux kernel.

The resource manager is activated by default in ST deliveries. Nevertheless, if a specific configuration is needed, this section indicates how it can be activated/deactivated in the kernel.
To activate the resource manager, the user can use the Linux Menuconfig tool: Menuconfig or how to configure kernel and select:

Device Drivers  --->
      Remoteproc drivers  --->
          <*> Support for Remote Processor subsystem
               -*-   Remoteproc System Resource Manager core
               -*-     Remoteproc System Resource Manager device
               <*>   STM32 remoteproc support

6. Debug logs[edit source]

In the Linux kernel console, the user can get some logs listing the resources configured by the resource manager before the firmware starts.

To get this log the user must enable the Linux kernel dynamic debug logs of the resource manager:

echo -n 'file rproc_srm*.c +p' > /sys/kernel/debug/dynamic_debug/control