1. Article purpose[edit source]
This article explains how to configure TAMP internal peripheral.
This article describes the TAMP configuration performed using the device tree mechanism, which provides an hardware description of the TAMP peripheral.
2. DT bindings documentation[edit source]
The following binding-related documentation explains how to write device tree files for TAMP:
- TF-A: docs/devicetree/bindings/soc/st,stm32-tamp.txt
- OP-TEE: documentation/devicetree/bindings/hwmon/st,stm32-tamp.yaml
- Linux Kernel: Backup register management: Documentation/devicetree/bindings/power/reset/syscon-reboot-mode.yaml
3. DT configuration[edit source]
This hardware description is a combination of the STM32 microprocessor device tree files (.dtsi extension) and board device tree files (.dts extension). See the Device tree for an explanation of the device-tree file split.
STM32CubeMX can be used to generate the board device tree. Refer to How to configure the DT using STM32CubeMX for more details.
3.1. DT configuration (SoC level)[edit source]
3.1.1. STM32 TAMP node in Linux[edit source]
- for STM32MP13x lines
in stm32mp131.dtsi
- for STM32MP15x lines in stm32mp151.dtsi
- for STM32MP25x lines in stm32mp251.dtsi
3.1.2. STM32 TAMP node in OP-TEE[edit source]
- for STM32MP13x lines in stm32mp131.dtsi
- for STM32MP15x lines in stm32mp151.dtsi
- for STM32MP25x lines in stm32mp251.dtsi
3.2. DT configuration (board level)[edit source]
3.2.1. STM32MP1 TAMP node append (OP-TEE specific)[edit source]
The board definition in the device tree may include some additional board-specific pin control management, some global configuration for the tampers and the backup registers configuration.
Example for STM32MP13x lines in core/arch/arm/dts/stm32mp135f-dk.dts :
&tamp {
st,backup-zones = <10 5 17>;
st,tamp-passive-nb-sample = <4>;
st,tamp-passive-sample-clk-div = <16384>;
wakeup-source;
wakeup-parent = <&exti>;
st,tamp-internal-tampers =
<INT_TAMPER_RTC_CALENDAR_OVERFLOW TAMPER_CONFIRMED_MODE>;
/* Tamper button */
tamp_button: tamp-passive@2 {
status = "okay";
reg = <EXT_TAMPER_2>;
pinctrl-0 = <&tamp0_in2_pin_a>;
st,tamp-mode = <TAMPER_CONFIRMED_MODE>;
};
/* Connect pin8 and pin22 from CN8 */
tamp-active@3 {
pinctrl-0 = <&tamp0_in3_pin_a &tamp0_out1_pin_a>;
reg = <EXT_TAMPER_3>;
st,tamp-mode = <TAMPER_POTENTIAL_MODE>;
status = "disabled";
};
};
Learn more about the topology of the backup registers in pages:
3.2.2. STM32MP2 TAMP node append (OP-TEE specific)[edit source]
The STM32MP25x lines embeds a RIF board device tree source file. The TAMP peripheral is RIF-Aware, meaning it is responsible to apply its own RIF configuration.
Contrary to the STM32MP1 series, the backup registers configuration is present in RIF configuration file . Learn more about the topology of the backup registers on STM32MP25x lines platforms here.
Example for the STM32MP25x lines :
&tamp {
wakeup-source;
wakeup-parent = <&exti2>;
st,tamp-passive-precharge = <2>;
st,tamp-passive-nb-sample = <4>;
st,tamp-passive-sample-clk-div = <16384>;
st,tamp-internal-tampers =
<INT_TAMPER_RTC_CALENDAR_OVERFLOW TAMPER_CONFIRMED_MODE>,
<INT_TAMPER_MONOTONIC_COUNTER_1 TAMPER_CONFIRMED_MODE>;
st,protreg = <
//Tamper configuration and interrupt can only be done by the CID1, secure and privileged context
RIFPROT(RIF_TAMP_RESOURCE(0), RIF_UNUSED, RIF_UNLOCK, RIF_SEC, RIF_PRIV, RIF_CID1, RIF_SEM_DIS, RIF_CFEN)
//Monotonic counter 1 can be read and written by the CID1, secure and privileged context
RIFPROT(RIF_TAMP_RESOURCE(1), RIF_UNUSED, RIF_UNLOCK, RIF_SEC, RIF_PRIV, RIF_CID1, RIF_SEM_DIS, RIF_CFEN)
//Monotonic counter 2 can be read and written by the CID2, secure and privileged context
RIFPROT(RIF_TAMP_RESOURCE(2), RIF_UNUSED, RIF_UNLOCK, RIF_SEC, RIF_PRIV, RIF_CID2, RIF_SEM_DIS, RIF_CFEN)
>;
//Declaration of the number of backup registers per zone (Zone1-RIF1, Zone1-RIF2, etc...)
st,backup-zones = <24 24 24 24 12 12 8>;
//RIF configuration and backup registers definition should be present in the *-rif.dtsi device tree file
/* Tamper button */
tamp_button: tamp-passive@3 {
status = "disabled";
reg = <EXT_TAMPER_3>;
pinctrl-0 = <&tamp_in3_pin_a>;
st,tamp-mode = <TAMPER_POTENTIAL_MODE>;
};
};
3.3. How to use TAMP Backup Registers[edit source]
In order to use free Backup registers, users should :
- locate one or more free Backup registers (cf STM32MP2 Backup register memoy mapping)
- Add the NVMEM cell description under the nvram node in the device tree
&nvram {
//TAMP_BKP127R : HEX(127*4) = 0x1FC
my_free_backup_register: tamp-bkp@1fc {
reg = <0x1FC 0x4>;
};
};
- Add a the nvmem-cells and nvmem-cell-names properties to the node of the device that would use the backup registers (following NVMEM consumer device tree bindings[1])
&my_device_node {
nvmem-cells = <&my_free_backup_register>;
nvmem-cell-names = "my_backup_register";
}
3.3.1. Common TAMP node append[edit source]
Some system configuration can be overriden in the board tamp node, as these depend of the board. These global configuration are defined for all external tampers.
- st,tamp-passive-precharge: Can be 0, 1, 2, 4, 8.
- 0 is no precharge, so the pull-up is disabled for all external passive tamper.
- 1, 2, 3, 4, 8 define the number of cycle the STM32 precharge the pin before checking the value (low/high) for all external tamper.
- st,tamp-passive-nb-sample: The number of sample to read in a row to raise a passive tamper. Can be 0 (activation on edge), 2, 4, 8.
- st,tamp-passive-sample-clk-div: Clock divider to define frequency to read a sample for a passive tamper.
- st,tamp-active-filter:
- 0: Active tamper filtering disable
- 1: Active tamper filtering enable: a tamper event is detected when 2 comparison mismatches occur out of 4 consecutive samples.
- st,tamp-active-clk-div: Clock divider to define the frequency of read/write cycle for all active tampers.
- wakeup-source: TAMP event will exit from low power mode.
- st,backup-zones: Define the number of backup register per zone. Please refer to the YAML documentation
- st,tamp-internal-tampers: List of the internal tampers to activate. Be aware that some internal tampers (e.g: power monitoring tampers) require some features to be enabled (properties in other device tree nodes). For STM32MP15x lines , the field describing the mode is not used be must be present.
- st,tamp-mask-pot-reset: Mask the reset control line of some resources when a potential tamper occurs. Please refer to the SoC reference manual to see what resource it concerns.
Each sub-node define an external tamper, and within this node:
- pinctrl-0 entry defines which pin for which tamper id (see stm32mp13-pinctrl.dtsi for possible values). If only one pin is defined, the external tamper is a passive one, otherwise the external tamper is an active one (first entry is the input pin, second the output pin)
- st,trig-on defines the active level to activate this passive tamper (not used if pintctrl-0 as 2 entries). It depends also of st,tamp-passive-precharge value.
- if st,tamp-passive-precharge=0 this passive tamper activate at edge.
- if st,tamp-passive-precharge != 0, with st,trig_on defined, this passive tamper will activate if st,tamp-passive-nb-sample in a row are high. If not defined the passive tamper event is raised if st,tamp-passive-nb-sample in a row are low.
- st,tamp-mode: Either TAMPER_CONFIRMED_MODE or TAMPER_POTENTIAL_MODE to configure the external tamper either in confirmed or potential mode.
4. How to configure the DT using STM32CubeMX[edit source]
The STM32CubeMX tool can be used to configure the STM32MPU device and get the corresponding platform configuration device tree files.
STM32CubeMX may not support all the properties described in the documents listed in DT bindings documentation above. If so, the tool inserts user sections in the generated device tree. These sections can then be edited to add some properties that are preserved from one generation to another. Refer to the STM32CubeMX user manual for further information.
5. References[edit source]
Please refer to the following links for additional information:
- ↑ Documentation/devicetree/bindings/nvmem/nvmem-consumer.yaml , NVMEM consumer device tree bindings