OP-TEE configuration switches

Applicable for

STM32MP13x lines, STM32MP15x lines, STM32MP25x lines

1. Purpose[edit source]

This article describes the configuration switches used in OP-TEE OS component.
It is recommended to first read OP-TEE overview article for a presentation of OP-TEE.

2. Overview[edit source]

OP-TEE is presented in OP-TEE overview and STM32MPU OP-TEE Profiles articles.

OP-TEE OS build sequence is based on GNU Makefile files. OP-TEE configuration is set straight from the OP-TEE build process and in based on shell environment variables, also used as Makefile variables as shown in the build command lines below:

 make PLATFORM=stm32mp1-135F_DK

 make PLATFORM=stm32mp1-135F_DK CFG_TEE_CORE_DEBUG=y

 CFG_TEE_CORE_DEBUG=y make PLATFORM=stm32mp1-135F_DK

 make PLATFORM=stm32mp1 CFG_EMBED_DTB_SOURCE_FILE=stm32mp135f-dk.dts CFG_STM32MP_PROFILE=secure_and_system_services

The above make command lines should be enough to build your target boot firmware images.

This article presents many of the OP-TEE configuration switches that can be tuned for a given target. This article does not present all OP-TEE configuration switches. Almost all OP-TEE configuration switches are prefixed CFG_.

Usually the first OP-TEE configuration switches one tunes are debug mode (CFG_TEE_CORE_DEBUG=y|n), log trace level (CFG_TEE_CORE_LOG_LEVEL=[0|1|2|3|]) and the selection of the STM32MPU OP-TEE profile CFG_STM32MP_PROFILE={system_services|secure_and_system_services}. Each platform has a preset of default configuration switches values.

It is also possible to pass a config makefile to the make sequence. The OP-TEE OS configuration file shall set PLATFORM and the other expected configuration variables.

 make CFG_OPTEE_CONFIG=/path/to/conf-OP-TEE-CUSTOM.mk

3. Main configuration switches[edit source]

The minimal configuration directives required to build OP-TEE OS are the identification of the target (product line + embedded Device Tree) and the cross compilation toolchain.

3.1. Target platform definition[edit source]

OP-TEE OS configuration must define the target product line and the Device Tree source file to be embedded on OP-TEE firmware:

PLATFORM=<platform>
- Ex: PLATFORM=stm32mp1 for STM32MP1 series
- Ex: PLATFORM=stm32mp2 for STM32MP2 series
One of the following exclusive configuration switch must be enabled:
- CFG_STM32MP13=y when targeting a STM32MP13x lines platform
- CFG_STM32MP15=y when targeting a STM32MP15x lines platform
- CFG_STM32MP25=y when targeting a STM32MP25x lines platform
CFG_EMBED_DTB_SOURCE_FILE=<device-tree-source-file>: in-tree (core/arch/arm/dts/ ) device tree filename with its .dts extension.
- Ex: CFG_EMBED_DTB_SOURCE_FILE=stm32mp157f-dk2.dts

OP-TEE OS may guess the target product line (CFG_STM32MPxx=y) based on CFG_EMBED_DTB_SOURCE_FILE value.

Some couples of platform/device-tree source file are predefined in OP-TEE OS source tree. They can be used as an alternative to CFG_EMBED_DTB_SOURCE_FILE, using configuration switch PLATFORM with a platform flavor suffix. For example:

PLATFORM=stm32mp1-157F_EV1
is an equivalent for PLATFORM=stm32mp1 CFG_STM32MP15=y CFG_EMBED_DTB_SOURCE_FILE=stm32mp157f-ev1.dts.
PLATFORM=stm32mp1-135F_DK
is an equivalent for PLATFORM=stm32mp1 CFG_STM32MP13=y CFG_EMBED_DTB_SOURCE_FILE=stm32mp135f-dk.dts.
PLATFORM=stm32mp2-257F_DK
is an equivalent for PLATFORM=stm32mp2 CFG_STM32MP25=y CFG_EMBED_DTB_SOURCE_FILE=stm32mp257f-dk.dts.

3.2. STM32MPU OP-TEE profile[edit source]

STM32MPU OP-TEE proposes configuration profiles to ease defining the services to embed in OP-TEE. The profiles are described in STM32MPU OP-TEE Profiles article. The configuration switch supported values are:

CFG_STM32MP_PROFILE=system_services
CFG_STM32MP_PROFILE=secure_and_system_services

On STM32MPU platforms, the default select profile depends on the target, refer to Platform default configuration article.

3.3. Cross-compilation directives[edit source]

We mention here also the cross compilation prefix, as alternative to generic CROSS_COMPILE:

CROSS_COMPILE32:
CROSS_COMPILE64:
OP-TEE cross-compilation toolchain is set from CROSS_COMPILE however, for 64bit targets, OP-TEE can host both 32bit and 64bit Trusted Applications. To build the former, CROSS_COMPILE32 shall be set. CROSS_COMPILE64 is used for 64bit build or build makefiles fallback to CROSS_COMPILE.

4. OP-TEE core generic switches[edit source]

Below are some OP-TEE generic optional directives commonly used, described in OP-TEE OS mk/config.mk file:

CFG_CORE_HEAP_SIZE=<VALUE>: define the byte size of OP-TEE core memory allocation pool.
CFG_NUM_THREADS=<VALUE>: define the number of TEE threads provisioned in OP-TEE.

CFG_WITH_PAGER={n|y}: disable/enable OP-TEE core "pager" mode, allowing OP-TEE is execute in a size constrained internal RAM for few hundreds of kBytes. The feature is used only on STM32MP15x lines when secure services are enabled.

On Armv8-A paltforms, OP-TEE can be built in 64bit (CFG_ARM64_core=y) or in 32bit mode (CFG_ARM32_core=y).

5. Resource management service configuration switches[edit source]

In both Resource Management profile and Secure Service profile, OP-TEE embeds resource management services that are default enabled in STM32MP software delivery. Each can be individually disabled using their related configuration switch:

CFG_DEVICE_ENUM_PTA={y|n}. Enumeration of registered embedded services to non-secure world. Default enabled. This is used by U-Boot and the Linux kernel to bind driver instances (SCMI, HWRNG, ...).

CFG_HWRNG_PTA={y|n}. Default enabled in both profiles. The ease support for various configuration, it can be convenient to embed true random number generator service interface, known that the service is enumerated (see CFG_DEVICE_ENUM_PTA) only if a secure RNG driver registers to OP-TEE core.

CFG_RTC_PTA={y|n}: Default disabled. It is expected a future service.

CFG_SCMI_PTA={y|n}: Default enabled on STM32MPU OpenSTLinux platforms to manage clock, reset, power and voltage domains, and more.

6. Secure services related configuration switches[edit source]

The configuration switch listed in this section all require STM32MPU OP-TEE secure service to be enabled with CFG_STM32MP_PROFILE=secure_and_system_services.

6.1. Generic switches for secure services[edit source]

CFG_REE_FS={n|y}: disable/enable OP-TEE secure storage area based on a non-secure filesystem
CFG_RPMB_FS={n|y}: disable/enable OP-TEE secure storage area based on eMMC/RPMB resource
CFG_RPMB_FS_DEV_ID=<VALUE>: define the mmcblk block device used by REE for eMMC/RPMB accesses
(e.g. "'1'" on stm32mp157x-ev1 boards)

6.2. Trusted applications[edit source]

CFG_WITH_USER_TA={n|y}: disable/enable support for Trusted Applications in OP-TEE secure memory
CFG_PAGED_USER_TA={n|y}: disable/enable support for paged Trusted Applications when CFG_WITH_PAGER is enabled.
CFG_USER_TA_TARGETS=ta_arm64\ ta_arm32
CFG_USER_TA_TARGETS=ta_arm64
CFG_USER_TA_TARGETS=ta_arm32
Defines whether a 64bit core support 32bit and/or 64 Trusted Applications.

6.3. BSEC secure fuse[edit source]

CFG_STM32_BSEC=y|n: STM32 BSEC2 OTP access interface driver.
CFG_STM32_BSEC3=y|n: STM32 BSEC3 OTP access interface driver.
The below config switches require that one of CFG_STM32_BSEC and CFG_STM32_BSEC3 is enabled and its driver probed.
- CFG_STM32_BSEC_WRITE=y|n: Allow burning OTP fuses.
- CFG_STM32MP_PROVISIONING=y|n: Load BSEC shadow memory from values read from OP-TEE core secure Device Tree.
- CFG_BSEC_PTA=y|n: STM32 BSEC secure words access services. Access rights are assigned from OP-TEE core Device Tree.

6.4. Other secure services[edit source]

CFG_STM32MP_REMOTEPROC=y: Secure service for attesting secure loading and boot of the Cortex-M remote processor, if available.
When enabled, it enforces CFG_REMOTEPROC_PTA=y.
CFG_ATTESTATION_PTA={y|n} Default disabled. Can be used to ask OP-TEE to certify the Trusted Application state.
- CFG_ATTESTATION_PTA_KEY_SIZE=<VALUE>: RSA key size used for the attestation, default value is 3072.
CFG_SECSTOR_TA_MGMT_PTA={y|n}: Default enabled to allow Installation of TA images in the OP-TEE secure persistent storage.
CFG_SYSTEM_PTA={y|n}. Default enabled for TAs to interact with OP-TEE core.
CFG_PKCS11_TA=y|n This switch does not change OP-TEE OS but is exported to OP-TEE Test for regression test support.

7. STM32 drivers configuration switches[edit source]

STM32MPU variants: inherited from the Device Tree File name, or set by build environment.
The following switches are exclusive: only one can be enabled:

CFG_STM32MP13=y|n
CFG_STM32MP15=y|n
CFG_STM32MP25=y|n

Clocks, reset controllers, voltage regulators, pin muxing and GPIOs based on STM32 interfaces:

CFG_STM32MP{15|13|25}_CLK=y|n: Clock drivers. Required enabled for related STM32MPU variant.
RCC device shall have a node in OP-TEE device tree, see clock device tree configuration article.
CFG_STM32MP{15|13|25}_RSTCTRL=y|n: Reset controller drivers. Required enabled for related STM32MPU variant.
RCC device shall have a node in OP-TEE device tree, see reset device tree configuration article.

CFG_STM32_IWDG=y|n: STM32 IWDG Watchdog service
STM32 IWDG device requires a node in OP-TEE device tree, see IWDG device tree configuration article.
'CFG_STM32_GPIO=y: Required enabled, for GPIO and pin muxing (pin control).
STM32 GPIO banks shall have nodes in OP-TEE device tree, see GPIO device tree configuration article.

CFG_STM32_UART=y: Enabled for OP-TEE output console trace messages.
See alsoUSART and serial TTY device device tree configuration articles. STM32MP OP-TEE proposes an early trace message configuration switch, defining which UART instance of the STM32MPU device is to be used, see CFG_STM32_EARLY_CONSOLE_UART.
CFG_STM32_LPTIMER=y|n: Required by STM32MP1 series for clock calibration service (CFG_STM32_CLKCALIB). See also LPTIM and LPTIM device tree configuration articles.
CFG_STM32_I2C=y|n: STM32 I2C bus interface driver. Required when using an STPMIC control chip.
STM32 I2C driver is initialized upon a compatible node in OP-TEE device tree. Refer also to I2C device tree configuration article.

CFG_STM32_RNG=y|n: High quality hardware Random Number Generator STM32 RNG.
When enabled and CFG_WITH_SOFTWARE_PRNG=n (aka CFG_WITH_TRNG=y), STM32 RNG is used a RNG source by OP-TEE core.
When enabled and CFG_WITH_SOFTWARE_PRNG=y, OP-TEE PRNG is seeded by STM32 RNG before non-secure world boots. This can be used for platforms willing to drive STM32 RNG from the non-secure world (U-Boot, Linux). STM32 RNG driver is initialized upon a compatible node in OP-TEE device tree. Refer also to RNG device tree configuration article.

STM32MP resource access firewalls support:

CFG_STM32_FIREWALL=y : STM32MP firewall drivers framework
CFG_STM32_ETZPC=y: Firewall enforced enabled in MP13 and MP15 for the Secure Services profile. See also ETZPC interface and ETZPC device tree configuration articles.
CFG_STM32_{RIF|RIFSC|RISAB|RISAF}=y: Firewall drivers enforced enabled in MP25 for the Secure Services profile. See also relevant articles on RIFSC, RIFSAF, RISAB and their device tree artciles ( RIFSC configuration, RISAF configuration and RISAB configuration).
CFG_STM32_IAC=y, CFG_STM32_SERC=y|n: Invalid resource access monitoring on STM32MP25x lines .
- CFG_STM32_PANIC_ON_IAC_EVENT=y|n: Panic possibly with a debug trace message on IAC violation.
  Default y when CFG_TEE_CORE_DEBUG=y.
- CFG_STM32_PANIC_ON_SERC_EVENT=y|n: Panic spossibly with a debug trace message on SERC events.
  Default y when CFG_TEE_CORE_DEBUG=y.

OTP fuses service:

CFG_STM32_{BSEC|BSEC3}=y|n: Refer to BSEC configuration section.

STM32MP cryptographic hardware assistance:

CFG_STM32_CRYPTO_DRIVER=y: Enabled in the Secure Services profile.
CFG_STM32_{HASH|CRYP|PKA|SAES}=y Support to related STM32 peripheral interface. Selectively enabled in Secure service profile for applicable platforms.
See also the related device tree configuration articles for HASH configuration, CRYP configuration, PKA configuration, SAES configuration.
Note that SAES and PKA depend on RNG support.

Power and low power modes resources:

Voltage regulators: CFG_STM32_VREFBUF=y, CFG_STM32_PWR=y, CFG_STPMIC1=y|n, CFG_STPMIC2=y|n
Low power resources: CFG_STM32_EXTI=y, CFG_STM32_CPU_OPP=y, CFG_SYSCFG=y|n, CFG_STM32_PWR_IRQ=y|n.

Other STM32MPU drivers:

Media that requires a secure or low power assistance.
CFG_STM32_OMM=y, CFG_STM32_FMC=y, CFG_STM32_HPDMA=y
Remote processor management:
CFG_STM32_HSEM=y, CFG_STM32_IPCC=y.
Tampering and monitor
CFG_STM32_TAMP=y, CFG_STM32_TAMP_NVRAM=y, CFG_STM32_HSE_MONITORING=y.

Debugging the traces:

CFG_STM32_EARLY_CONSOLE_UART={0|1|..} : OP-TEE core early trace UART instance. When 0, early traces (e.g. before MMU is enabled) are disabled. When 1, or more, this is the UART/USART instance used, likely already setup by some previous boot stage.
CFG_STM32_CLK_DEBUG=y|n: Print clocks state at run time from STM32 clock drivers.

8. Cryptographic operation configuration[edit source]

Main switches:

CFG_CRYPTO=y|n
CFG_CRYPTOLIB_NAME=tomcrypt, alternatively CFG_CRYPTOLIB_NAME=mbedtls
CFG_CRYPTOLIB_DIR=core/lib/libtomcrypt (resp. CFG_CRYPTOLIB_DIR=lib/mbedtls)
Target software cryptographic library embedded in OP-TEE core. Default is libtomcrypt and its internal path.

For all the cryptographic algorithms listed below, all those that are enabled by do not have hardware assistance are processed by the software cryptography library of OP-TEE, either the TomCrypt library [1] or the MbedTLS library [2].

Digest and hashing functions:
Note: CFG_STM32_HASH enforce MD5, SHA*, SHA3_*, and SHAKE*.

CFG_CRYPTO_[MD5|SHA1|SHA224|SHA256|SHA384]=y|n
CFG_CRYPTO_SHA3_[224|384|512]=y|n
CFG_CRYPTO_SHA512|SHA512_256]=y|n
CFG_CRYPTO_SHAKE[128|256]=y|n
CFG_CRYPTO_SM3]=y|n

Symmetric cryptographic algorithms:
Note: CFG_STM32_CRYP enforces support for AES ECB/CBC/CTR/GCM/CCM and DES/TDES EBC/CBC.
CFG_STM32_SAES enforces support for AES ECB/CBC/CTR/GCM/CCM.

CFG_CRYPTO_AES=y|n:
CFG_CRYPTO_AES_GCM_FROM_CRYPTOLIB=y|n
CFG_CRYPTO_DES=y|n
CFG_CRYPTO_SM4=y|n
CFG_CRYPTO_HMAC=y|n

and their related modes (when applicable):

CFG_CRYPTO_ECB=y|n
CFG_CRYPTO_CBC=y|n
CFG_CRYPTO_CBC_MAC=y|n
- CFG_CRYPTO_CBC_MAC_BUNDLE_BLOCKS=64
CFG_CRYPTO_[CCM|CMAC|CTR|CTS|GCM|XTS]=y|n

Key derivation support:

CFG_CRYPTO_HKDF=y|n
CFG_CRYPTO_PBKDF2=y|n
CFG_CRYPTO_CONCAT_KDF=y|n
CFG_CRYPTO_HW_PBKDF2=y|n

Asymmetric cryptographic algorithms:
CFG_STM32_PKA=y enables ECC operations.

CFG_CRYPTO_[DH|DSA|RSA|RSASSA_NA1]={y|n}
CFG_CRYPTO_[ECC|ED25519|X25519]={y|n}
CFG_CRYPTO_SM2_[DSA|KEP|PKE]={y|n}

Generic cryptographic processing framework configuration switches:

CFG_WITH_SOFTWARE_PRNG={y|n}
CFG_WITH_TRNG={n|y}
Exclusive enabled switches
When CFG_WITH_SOFTWARE_PRNG=y: Random bytes are generated by a software implementation (Fortuna algorithm [3]).
When CFG_WITH_SOFTWARE_PRNG=n: Random bytes can be generated with a hardware source with CFG_WITH_TRNG=y. TRNG device are registered at boot time in OP-TEE core.

CFG_CRYPTO_SIZE_OPTIMIZATION={y|n}: Defines memory size footprint optimization of the cryptographic software libraries.

9. Debug related configuration switches[edit source]

OP-TEE generic optional debugging and test directives commonly used, described in OP-TEE OS mk/config.mk file:

CFG_TEE_CORE_DEBUG=n|y: disable/enable debug support (including support for assert() through NDEBUG)
CFG_TEE_CORE_LOG_LEVEL={0|1|2|3|4}: define OP-TEE core trace level (0: no trace, 4: overflow of traces) (default is 2: info)
CFG_TEE_CORE_TA_LEVEL={0|1|2|3|4}: define OP-TEE Trusted Applications (TAs) trace level (default is 1: error)
CFG_TEE_CORE_TA_TRACE=n|y: disable/enable TAs trace message at define OP-TEE core level (default is y)
CFG_STM32_EARLY_CONSOLE_UART={0|1|2|...}: define the USART instance used for early console trace messages (default is 4)
CFG_CC_OPT_LEVEL=[s|0|1|2] sets GCC/Clang optimization level. Default is s for speed.
CFG_UNWIND=n|y: disable/enable stack unwind debug trace messages
CFG_ENABLE_EMBEDDED_TESTS=n|y; disable/enable embedded test, used by xtest tool (default is y)
CFG_WITH_STATS=n|y: disable/enable OP-TEE statistics retrieval through OP-TEE Statistics PTA service interface.
CFG_WERROR=n|y: disable/enable build error trigger on OP-TEE build warning occurrences.
CFG_TA_GPROF_SUPPORT=n|y: disable/enable profiling of Trusted Application implementation based on gprof standard tool
CFG_FTRACE_SUPPORT=n|y: disable/enable function trace support in Trusted Applications based on ftrace standard tool
CFG_SYSCALL_FTRACE=n|y: disable/enable support for ftrace syscall graph generation

Information on configuration switches CFG_TEE_CORE_DEBUG, CFG_TEE_CORE_LOG_LEVEL and CFG_UNWIND can be found in the How_to_debug_OP-TEE article.

10. Constraints with OP-TEE Pager[edit source]

This section details the constraint related to when enabling OP-TEE pager, as specifically needed with STM32MP15x lines when enabling the secure services. These constraints are all related to the size of the internal secure memory assigned to OP-TEE OS. Details on the secure internal memory that can be assigned to OP-TEE can be found in [[STM32MPU_OP-TEE_profiles#Platform_default_configuration_and_constraints|STM32MP15x lines platform constraints]] article.

TO BE FILLED with information on OP-TEE performance impact related to the internal secure memory size and its use.

TO BE FILLED with specific info on CFG_TEE_CORE_LOG_LEVEL, CFG_TEE_CORE_DEBUG CFG_CORE_HEAP_SIZE and CFG_NUM_THREADS impact on pager resident memory