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.

2. Overview[edit source]

OP-TEE is presented in OP-TEE overview and How to configure OP-TEE 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 envrionment 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

The above make command lines should be enought 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 siwtches 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 enable of disable of either CFG_STM32_RESOURCE_MANAGEMENT_PROFILE or CFG_STM32_SECURE_SERVICE_PROFILE. Each platform has a preset of default values for some configuraion swithes.

2.1. Main configuration switches[edit source]

Some configuration switches are required to build OP-TEE OS, they define the target platform and the target board (that is the device tree source file to use for that platform):

PLATFORM=<platform>
- Ex: PLATFORM=stm32mp1 for STM32MP1 series
- Ex: PLATFORM=stm32mp2 for STM32MP2 series
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

Note that 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_EMBED_DTB_SOURCE_FILE=stm32mp157f-ev1.dts.
PLATFORM=stm32mp1-135F_DK
is an equivalent for PLATFORM=stm32mp1 CFG_EMBED_DTB_SOURCE_FILE=stm32mp135f-dk.dts.
PLATFORM=stm32mp2-257F_DK
is an equivalent for PLATFORM=stm32mp2 CFG_EMBED_DTB_SOURCE_FILE=stm32mp257f-dk.dts.

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 Trsuted Applications. To build the former, CROSS_COMPILE32 shall be set. CROSS_COMPILE64 is used for 64bit build or build makefiles fallback to CROSS_COMPILE.

STM32MP OP-TEE configuration provides 2 main configuration switch used to select either the resource managemet profile or the secure service profile. These profiles are described in OP-TEE core configuration (FIXME: reference to check) article.

CFG_STM32_RESOURCE_MANAGEMENT_PROFILE=y
CFG_STM32_SECURE_SERVICE_PROFILE=y

On STM32MPU platforms, either 2 of these 2 profiles is enabled.

MP13-PRODUCT-LINE: since OSTLv5.1: CFG_STM32_RESOURCE_MANAGEMENT_PROFILE=n CFG_STM32_SECURE_SERVICE_PROFILE=y. MP15-PRODUCT-LINE: since OSTLv5.1: CFG_STM32_RESOURCE_MANAGEMENT_PROFILE=y CFG_STM32_SECURE_SERVICE_PROFILE=n. MP25-PRODUCT-LINE: since OSTLv5.1: CFG_STM32_RESOURCE_MANAGEMENT_PROFILE=n CFG_STM32_SECURE_SERVICE_PROFILE=y.

2.2. 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_REE_FS={n|y}: disable/enable OP-TEE REE filsystem based secure storage area
CFG_RPMB_FS={n|y}: disable/enable OP-TEE eMMC/RPMB based secure storage area
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)
CFG_WITH_USER_TA={n|y}: disable/enable support for Trusted Applications in OP-TEE secure memory (default is y)
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.
CFG_PAGED_USER_TA={n|y}: disable/enable support for paged Trusted Applications when CFG_WITH_PAGER is enabled.

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

When CFG_STM32_SECURE_SERVICE_PROFILE is enabled, the above switches related to secure services are defautl enabled. Alternatively, when CFG_STM32_RESOURCE_MANAGER_PROFILE is enabled, the above switches related to secure services are disabled.

2.3. 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 secure service to Linux kernel. Default enabled.
CFG_HWRNG_PTA={y|n}. Default enabled in Secure Service profile.
CFG_RTC_PTA={y|n}
CFG_SCMI_PTA={y|n}: Default enabled on STM32MPU OpenSTLinux platforms to manage clock, reset, power and voltage domains, and more.

2.4. Secure services related configuration switches[edit source]

2.5. = Generic switches for secure services[edit source]

CFG_REE_FS={n|y}: disable/enable OP-TEE REE filsystem based secure storage area
CFG_RPMB_FS={n|y}: disable/enable OP-TEE eMMC/RPMB based secure storage area
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)
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.

2.5.1. Trusted applications[edit source]

CFG_WITH_USER_TA={n|y}: disable/enable support for Trusted Applications in OP-TEE secure memory (default is y)
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.

2.5.2. 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: Secure Service for burning secure OTP fuses.
- CFG_BSEC_PTA=y|n: STM32 BSEC secure words access services

2.5.3. Other 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=3072: RSA key size used for the attestation.
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.

2.6. STM32 driver 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 conrtoller, voltage regulatos, pinmuxing and GPIOs based on STM32 intefraces:
- CFG_STM32MP{15|13|25}_CLK=y|n, CFG_STM32MP_CLK_CORE=y|n: Clock framework for STM32MPU varriants.
- 'CFG_STM32MP{15|13|25}_RSTCTRL=y|n
CFG_STM32_IWDG=y
- 'CFG_STM32_GPIO=y; CFG_STM32_UART=y,
  CFG_STM32_LPTIMER=y, CFG_STM32_I2C=y, CFG_STM32_HASH=y, ...

STM32MP resource access firewals support:
- CFG_STM32_FIREWALL=y
- CFG_STM32_ETZPC=y: Firewall enforced enabled in MP13 and MP15 Secure Service profile.
- CFG_STM32_IAC=y, CFG_STM32_{RIF|RIFSC|RISAB|RISAF}=y :
  Firewall enforced enabled in MP25 Secure Service profile.

STM32MP cyrptographic hadrware assitance:
- CFG_STM32_CRYPTO_DRIVER=y: Disable in Resource Management profile, enabled in Secure Service profile.
- CFG_STM32_{CRYP|PKA|SAES|RNG}{{=}]y Support to related STM32 IP interface. Selectively enabled in Secure service profile for applicable platforms.

Media that requires a secure or low power assitance.
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.
Low power modes resources
CFG_STM32_VREFBUF=y, CFG_STPMIC2=y, CFG_STM32_EXTI=y,* CFG_STM32_CPU_OPP=y
Debug related:
CFG_STM32_EARLY_CONSOLE_UART={0|1|..}

2.7. Cryptographic operation configuration[edit source]

Main siwtches:

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 crypto library embedded in OP-TEE core. Default is libtomcrypt and its internal path.

Digest and hashing functions:

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:

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_CRYPTO_[DH|DSA|RSA|RSASSA_NA1]={y|n}
CFG_CRYPTO_[ECC|ED25519|X25519]={y|n}
CFG_CRYPTO_SM2_[DSA|KEP|PKE]={y|n}

Generic crypto framework configuration switches:

CFG_WITH_SOFTWARE_PRNG={y|n}
CFG_CRYPTO_SIZE_OPTIMIZATION={y|n}
CFG_CRYPTO_DRIVER={y|n}
CFG_CRYPTO_DRIVER_DEBUG={0|...}
CFG_CRYPTO_DRV_ACIPHER=y|n
CFG_CRYPTO_DRV_CIPHER=y|n
CFG_CRYPTO_DRV_ECC=y|n
CFG_CRYPTO_DRV_HASH=y|n
CFG_CRYPTO_DRV_MAC=y|n

2.8. Debug related configuraiton 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 assert() with 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 retrieve from the Stats PTA service.
CFG_WERROR=n|y: disable/enable build error trigger on OP-TEE build warning occurences.
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.