查看“How to assign an internal peripheral to a runtime context”的源代码

== Article purpose ==
This article explains how to configure the software that assigns a peripheral to a [[Getting_started_with_STM32_MPU_devices#Multiple-core_architecture_concepts|runtime context]].

== Introduction ==
A peripheral can be '''assigned''' to a [[Getting_started_with_STM32_MPU_devices#Multiple-core_architecture_concepts|runtime context]] via the configuration defined in the [[Device tree|device tree]]. The [[Device tree|device tree]] can be either generated by the [[STM32CubeMX]] tool or edited manually.
<br /><br />
On STM32MP15 line devices, the assignement can be strengthened by a hardware mechanism: the [[ETZPC internal peripheral]], which is configured by the [[TF-A overview |TF-A]] boot loader. The [[ETZPC internal peripheral]] isolates the peripherals for the <span style="color:#FFFFFF; background:{{STPink}};">&nbsp;Cortex-A7 secure&nbsp;</span> or the <span style="color:#FFFFFF; background:{{STLightBlue}};">&nbsp;Cortex-M4&nbsp;</span> context. The peripherals assigned to the <span style="color:#FFFFFF; background:{{STDarkBlue}};">&nbsp;Cortex-A7 non-secure&nbsp;</span> context are visible from any context, without any isolation.
<br /><br />
The components running on the platform after TF-A execution (such as [[U-Boot overview|U-Boot]], [[STM32MP15 Linux kernel overview|Linux]], [[STM32CubeMP1 architecture|STM32Cube]] and [[OP-TEE overview|OP-TEE]]) must have a '''configuration''' that is consistent with the assignment and the isolation configurations.
<br /><br />
The following sections describe how to configure TF-A, U-Boot, Linux and STM32Cube accordingly.

== STM32CubeMX generated assignment ==
The screenshot below shows the [[STM32CubeMX]] user interface:
* '''I2C2''' peripheral is selected, on the left
* '''I2C2 Mode and Configuration''' panel, on the right, shows that this I2C instance can be assigned to the <span style="color:#FFFFFF; background:{{STDarkBlue}};">&nbsp;Cortex-A7 non-secure&nbsp;</span> or the <span style="color:#FFFFFF; background:{{STLightBlue}};">&nbsp;Cortex-M4&nbsp;</span> (that is selected) runtime context
* '''I2C''' mode is enabled in the drop down menu
<br />
[[File:cubeMX-assign-peripheral.png| center|800px|link=]]  

{{Info| The context assignment table is displayed inside each peripheral '''Mode and Configuration''' panel but it is possible to display it for all the peripherals in the '''Options''' menu via the '''Show contexts''' option}}

The '''GENERATE CODE''' button, on the top right, produces the following:
* The '''TF-A device tree''' with the [[ETZPC internal peripheral|ETZPC]] configuration that isolates the I2C2 instance (in the example) for the <span style="color:#FFFFFF; background:{{STLightBlue}};">&nbsp;Cortex-M4&nbsp;</span> context. This same device tree can be used by '''OP-TEE''', when enabled
* The '''U-Boot device tree''' widely inherited from the Linux one, just below
* The '''Linux kernel device tree''' with the I2C node disabled for Linux and enabled for the coprocessor
* The '''STM32Cube project''' with I2C2 HAL initialization code

The [[#Manual_assignment|Manual assignment]] section, just below, illustrates what STM32CubeMX is generating as it follows the same example.

{{ReviewsComments|-- [[User:Gerald Baeza|Gerald Baeza]] ([[User talk:Gerald Baeza|talk]]) 09:44, 30 January 2020 (CET)<br />Put here the info box that is shown in the next paragraph, explaining that the user may have to complete user section with system resources (ex: VREFBUF for ADC or DAC)}}

== Manual assignment ==
{{ReviewsComments|-- [[User:Gerald Baeza|Gerald Baeza]] ([[User talk:Gerald Baeza|talk]]) 09:45, 30 January 2020 (CET)<br />Insert clock management information in the paragraph below}}
This section gives step by step instructions, per software components, to manually perform the peripherals assignments.<br />
It takes the same I2C2 example as the previous section, that showed how to use STM32CubeMX, in order to make the move from one approach to the other easier.
{{Info | The assignments combinations described in the [[STM32MP15 peripherals overview]] article are naturally supported by [[STM32MPU Embedded Software distribution]]. Note that the [[STM32MP15 resources#Reference manuals|STM32MP15 reference manual]] may describe more options that would require embedded software adaptations}}

=== TF-A ===
The assignment follows the [[ETZPC device tree configuration]], with below possible values:
* '''DECPROT_S_RW''' for the <span style="color:#FFFFFF; background:{{STPink}};">&nbsp;Cortex-A7 secure&nbsp;</span> (Secure OS like OP-TEE)
* '''DECPROT_NS_RW''' for the <span style="color:#FFFFFF; background:{{STDarkBlue}};">&nbsp;Cortex-A7 non-secure&nbsp;</span> (Linux)
** As stated earlier in this article, there is no hardware isolation for the Cortex-A7 non-secure so this value allows accesses from any context
* '''DECPROT_MCU_ISOLATION''' for the <span style="color:#FFFFFF; background:{{STLightBlue}};">&nbsp;Cortex-M4&nbsp;</span> (STM32Cube)
<br />
Example:
 @etzpc: etzpc@5C007000 {
        st,decprot = <
            DECPROT(STM32MP1_ETZPC_{{Highlight|I2C2}}_ID, DECPROT_{{Highlight|MCU_ISOLATION}}, DECPROT_UNLOCK)
        >;
 };
{{Info | The value '''DECPROT_NS_RW''' can be used with '''DECPROT_LOCK''' as last parameter. In Cortex-M4 context, this specific configuration allows the generation of an error in the [[Resource_manager_for_coprocessing#Overview | resource manager utility]] while trying to use on Cortex-M4 side a peripheral that is assigned to the Cortex-A7 non-secure context. If '''DECPROT_UNLOCK''' is used, then the utility allows the Cortex-M4 to use a peripheral that is assigned to the Cortex-A7 non-secure context.}}

=== U-boot ===
No specific configuration is needed in [[U-Boot_overview|U-Boot]] to configure the access to the peripheral.<br>
{{Info | U-Boot does not perform any check with regards to ETZPC configuration before accessing to a peripheral. In case of inconsistency an illegal access is generated.}} 
{{Info | U-Boot checks the consistency between ETZPC isolation configuration and Linux kernel device tree configuration to guarantee that Linux kernel do not access an unauthorized device. In order to avoid the access to an unauthorized device, the U-boot fixes up the Linux kernel [[STM32MP15 device tree|device tree]] to disable the peripheral nodes which are not assigned to the Cortex-A7 non-secure context.}}

=== Linux kernel ===
Each assignable peripheral is declared twice in the Linux kernel device tree:
* Once in the '''soc''' node from {{CodeSource | Linux kernel | arch/arm/boot/dts/stm32mp157c.dtsi}}, corresponding to Linux assigned peripherals
** Example: i2c2
* Once in the '''m4_rproc''' node from {{CodeSource | Linux kernel | arch/arm/boot/dts/stm32mp157c-m4-srm.dtsi}}, corresponding to the Cortex-M4 context. Those nodes are disabled, by default.
** Example: m4_i2c2
<br />
In the board device tree file (*.dts), each assignable peripheral has to be enabled only for the context to which it is assigned, in line with TF-A configuration.<br />
As a consequence, a peripheral assigned to the Cortex-A7 secure has both nodes disabled in the Linux device tree.
<br />
<br />
Example:
 &i2c2 {
 	{{Highlight|status {{=}} "disabled";}}
 };
 ...
 &m4_i2c2 {
 	{{Highlight|status {{=}} "okay";}}
 };
{{Info | Beyond the peripherals assignment, explained in this article, it is also important to understand [[How to configure system resources]], shared between the Cortex-A7 and Cortex-M4 contexts}}

=== STM32Cube  ===
There is no configuration to do on STM32Cube side regarding the assignment and isolation. Nevertheless, the [[Resource_manager_for_coprocessing#Overview |resource manager utility]], relying on ETZPC configuration, can be used to check that the corresponding peripheral is well assigned to the Cortex-M4 before using it.<br />

Example:<BR>
*For {{EcosystemRelease | revision=1.1.0 | range=and after}}
 int main(void)
 {
 ...
  /* Initialize I2C2------------------------------------------------------ */
  /* Ask the resource manager for the I2C2 resource */
  {{Highlight|ResMgr_Init}}(NULL, NULL);
  if ({{Highlight|ResMgr_Request}}({{Highlight|RESMGR_ID_I2C2}}, RESMGR_FLAGS_ACCESS_NORMAL | \
                                     RESMGR_FLAGS_CPU1, 0, NULL) != RESMGR_OK)
  {
    Error_Handler();
  }
 ...
  if ({{Highlight|HAL_I2C_Init}}(&I2C2) != HAL_OK)
  {
    Error_Handler();
  }
 }

<div class="mw-collapsible mw-collapsed">
*For {{EcosystemRelease | revision=1.0.0}}
<div class="mw-collapsible-content">
 int main(void)
 {
 ...
  /* Initialize I2C2------------------------------------------------------ */
  /* Ask the resource manager for the I2C2 resource */
  {{Highlight|ResMgr_Init}}(NULL, NULL);
  if ({{Highlight|ResMgr_Request}}({{Highlight|RESMGR_ID_I2C2}}, RESMGR_FLAGS_ACCESS_NORMAL | \
                                     RESMGR_FLAGS_CPU_SLAVE, 0, NULL) != RESMGR_OK)
  {
    Error_Handler();
  }
 ...
  if ({{Highlight|HAL_I2C_Init}}(&I2C2) != HAL_OK)
  {
    Error_Handler();
  }
 }
</div></div>

{{Info | Beyond the peripherals assignment, explained in this article, it is also important to understand [[How to configure system resources]], shared between the Cortex-A7 and Cortex-M4 contexts}}

=== OP-TEE  ===
No specific configuration is needed in [[OP-TEE overview|OP-TEE]] to configure the access to the peripheral.<br>

<noinclude>
{{PublicationRequestId | 10647| 2019-02-06}}
[[Category:How to customize software]]
[[Category:Coprocessor management Linux]]
[[Category:Coprocessor management STM32Cube]]
</noinclude>