GTZC MCAL Module
Supported STM32 families: H5
Not supported: F4, F7, G4, H7, L4, U3, U5
This module provides an abstraction layer for the global TrustZone controller (GTZC) of STM32 MCUs: the assignment of the
security and privilege attributes to the peripherals and to the bus masters (TZSC), the block-based protection of the
internal SRAMs (MPCBB), the watermark protection of the external memories and the backup SRAM (MPCWM) and the
illegal access reporting (TZIC). It is a low-level MCAL module: it owns the GTZC hardware, the application and the other
modules never touch the registers.
The public interface (Gtzc_Port.h, Gtzc_Types.h) is identical for all supported families. The implementation
for a family lives in its own branch (Dev/<Family> for development, Releases/<Family> for the released versions), so
a module or an application written against the interface does not change when the MCU family changes.
This README is the landing page and the specification of the interface (master). The family branches contain their own README with everything that is specific to the family: the instances of the device, their settings and the status of the implementation.
Status: design. No implementation exists yet, the interface below is a proposal. Stories and branches follow.
Intent and purpose
- On a device with the Armv8-M TrustZone the system is split into a secure world (the keys, the boot, the update, the crypto) and a non-secure world (the application, the RTOS, the stacks). The split is enforced by the hardware, but someone has to configure it: which peripherals the non-secure code may touch, which SRAM blocks are secure, which part of the external flash is secure, which masters (DMA, the Ethernet DMA) may access what. The GTZC is the register block for all of it; the module is the only code that writes it and gives the configuration a readable shape.
- Without the TrustZone (a device line or a product that does not enable it) the same hardware provides the privilege protection: a peripheral accessible to the privileged code only. The module offers it under the same interface.
- A violation of the configuration is an illegal access: the TZIC collects it per peripheral, the module reports it (the flag, the callback), so a test or a production firmware can find the code that touches what it should not.
- The module hides the differences between the families: the number of the securable peripherals and masters, the SRAM block granularity, the number of the watermark regions, the line without the TrustZone (privilege only) differ, the interface stays the same.
What the module is not: it does not enable the TrustZone (the TZEN option byte belongs to the Flash module and the product life
cycle), it does not configure the Cortex-M security attribution unit (SAU / IDAU) or the MPU, and it does not partition the
flash (the secure watermark of the flash is a part of the Flash module).
Concept
The module keeps the four functional blocks of the controller apart:
| Block | Functions | Meaning |
|---|---|---|
| TZSC - peripherals and masters | Gtzc_Set_PeriphAttribute, Gtzc_Get_PeriphAttribute, Gtzc_Set_MasterAttribute | The attribute of a peripheral (gtzc_Periph_t): GTZC_SECURE / GTZC_NON_SECURE and GTZC_PRIVILEGED / GTZC_UNPRIVILEGED. The same for the bus masters that the device allows to configure. |
| MPCBB - SRAMs | Gtzc_Set_SramBlockAttribute, Gtzc_Set_SramRangeAttribute | The attribute of the SRAM in blocks of the granularity of the family (for example 256 bytes): a block is secure or non-secure, privileged or unprivileged; a range function sets a number of the blocks at once. |
| MPCWM - watermark regions | Gtzc_Set_WatermarkRegion | The secure / privileged regions of the external memories (the OCTOSPI, the FMC) and of the backup SRAM: start, length, attribute. |
| TZIC - illegal access | Gtzc_Set_IllegalAccessActive, Gtzc_Get_IllegalAccessStatus, Gtzc_Set_IllegalAccessCallback | Which peripherals report an illegal access by the interrupt, the status flags, the callback with the peripheral that was accessed. |
Rules:
- The configuration is done from the secure code. A call from the non-secure world (or on a device where the TrustZone is disabled
and the function needs it) returns
GTZC_REQUEST_ERROR; the module reads the security state at the initialization. - Every setter reads the register back; a locked configuration (the lock bit of the TZSC / MPCBB, set until the reset)
makes the write fail and the module reports the error.
Gtzc_Set_ConfigLocklocks it on purpose at the end of the boot. - The attribute of a peripheral is set before the non-secure code starts to use it; the module offers
Gtzc_Set_PeriphAttributeList(a table of the peripherals with their attributes) so that the whole product configuration is a single constant table applied byGtzc_Init. - A change of a security attribute of a memory block is not a copy: the content stays in the block, the world that owns the block changes. The module does not erase it; the application erases the secret data before it hands the block over (the RamCfg module can erase an SRAM).
- A watermark region is described by the start, the end and the attribute inside the window of the memory; regions must not overlap and must respect the granularity of the family; otherwise the call is rejected before a register is written.
- The illegal access callback is called from the interrupt of the controller; the flags are cleared by the module.
Supported families
Every family gets its own story, its own tasks and its own branches Dev/<Family> and Releases/<Family> cut from this
master.
| Family | Branch | Controller | Status |
|---|---|---|---|
| STM32H5 | Dev/STM32H5 | GTZC1: TZSC, MPCBB1 / MPCBB2 (SRAM blocks), watermark controllers of the OCTOSPI, the FMC and the backup SRAM, TZIC; STM32H503 has the privilege protection only (the global privilege controller) | planned (first) |
| STM32U5 | Dev/STM32U5 | GTZC1, GTZC2 (the domains), TZSC, MPCBB, watermark controllers, TZIC | planned |
| STM32U3 | Dev/STM32U3 | GTZC | planned |
| STM32G4, STM32L4, STM32H7, STM32F4, STM32F7 | Dev/STM32G4 ... | no TrustZone on the device - the module is a stub that returns GTZC_REQUEST_ERROR | planned |
A function without a meaning in a family stays in the interface, returns GTZC_REQUEST_ERROR and suppresses the unused
parameters (for example the security attribute on a privilege-only controller, a master that cannot be configured, a
watermark region the device does not have).
Public interface in short (proposal)
| Group | Functions |
|---|---|
| Module management | Gtzc_Get_ModuleVersion, Gtzc_Init, Gtzc_Deinit, Gtzc_Task, Gtzc_Get_DefaultConfig |
| Peripherals and masters | Gtzc_Set_PeriphAttribute, Gtzc_Get_PeriphAttribute, Gtzc_Set_PeriphAttributeList, Gtzc_Set_MasterAttribute |
| SRAM blocks | Gtzc_Set_SramBlockAttribute, Gtzc_Set_SramRangeAttribute, Gtzc_Get_SramBlockAttribute |
| Watermark regions | Gtzc_Set_WatermarkRegion, Gtzc_Get_WatermarkRegion |
| Illegal access | Gtzc_Set_IllegalAccessActive, Gtzc_Set_IllegalAccessInactive, Gtzc_Get_IllegalAccessStatus, Gtzc_Set_IllegalAccessClear |
| Lock | Gtzc_Set_ConfigLock, Gtzc_Get_LockState |
| Interrupts | Gtzc_Set_IrqPriority / Get, the callback is a part of the configuration |
gtzc_ModuleVersion_t Gtzc_Get_ModuleVersion ( void );
gtzc_RequestState_t Gtzc_Init ( const gtzc_Config_t * const gtzcConfig );
gtzc_RequestState_t Gtzc_Deinit ( void );
void Gtzc_Task ( void );
gtzc_RequestState_t Gtzc_Get_DefaultConfig ( gtzc_Config_t * const gtzcConfig );
gtzc_RequestState_t Gtzc_Set_PeriphAttribute ( gtzc_Periph_t periph, gtzc_Security_t security, gtzc_Privilege_t privilege );
gtzc_RequestState_t Gtzc_Get_PeriphAttribute ( gtzc_Periph_t periph, gtzc_Attribute_t * const attribute );
gtzc_RequestState_t Gtzc_Set_PeriphAttributeList ( const gtzc_PeriphAttribute_t * const list, gtzc_ListCnt_t listCnt );
gtzc_RequestState_t Gtzc_Set_SramRangeAttribute ( gtzc_Sram_t sram, gtzc_Address_t startAddress, gtzc_Size_t size, gtzc_Security_t security, gtzc_Privilege_t privilege );
gtzc_RequestState_t Gtzc_Set_WatermarkRegion ( gtzc_Region_t region, const gtzc_RegionConfig_t * const regionConfig );
gtzc_RequestState_t Gtzc_Set_IllegalAccessActive ( gtzc_Periph_t periph );
gtzc_RequestState_t Gtzc_Get_IllegalAccessStatus ( gtzc_Periph_t periph, gtzc_FlagState_t * const flagState );
gtzc_RequestState_t Gtzc_Set_ConfigLock ( void );
Every function returns GTZC_REQUEST_OK / GTZC_REQUEST_ERROR and checks its parameters and the state of the module
before it touches a register.
| Type | Meaning |
|---|---|
gtzc_Config_t | The table of the peripheral attributes, the SRAM ranges, the watermark regions, the illegal access list, the lock request, the callback, the interrupt priority |
gtzc_Periph_t | GTZC_PERIPH_USART1 ... - only the securable peripherals of the device |
gtzc_Sram_t | GTZC_SRAM_1, GTZC_SRAM_2, GTZC_SRAM_3 ... |
gtzc_Security_t, gtzc_Privilege_t | GTZC_SECURE / GTZC_NON_SECURE, GTZC_PRIVILEGED / GTZC_UNPRIVILEGED |
gtzc_Region_t, gtzc_RegionConfig_t | The watermark region (OCTOSPI 1, FMC bank 1 ..., backup SRAM) and its start, length and attribute |
gtzc_IllegalAccessCallback_t | void ( gtzc_Periph_t periph ) |
Usage
Product configuration applied once at the boot
#include "Gtzc_Port.h"
static const gtzc_PeriphAttribute_t periphTable[] =
{
{ GTZC_PERIPH_USART1, GTZC_NON_SECURE, GTZC_UNPRIVILEGED },
{ GTZC_PERIPH_RNG, GTZC_SECURE, GTZC_PRIVILEGED }, /* the random numbers only for the secure world */
{ GTZC_PERIPH_SAES, GTZC_SECURE, GTZC_PRIVILEGED },
};
gtzc_Config_t gtzcConfig;
(void)Gtzc_Get_DefaultConfig( >zcConfig );
gtzcConfig.PeriphList = periphTable;
gtzcConfig.PeriphListCnt = sizeof( periphTable ) / sizeof( periphTable[ 0u ] );
(void)Gtzc_Init( >zcConfig );
(void)Gtzc_Set_SramRangeAttribute( GTZC_SRAM_2, sram2Start, sram2Size, GTZC_SECURE, GTZC_PRIVILEGED );
(void)Gtzc_Set_ConfigLock(); /* frozen until the next reset */
Finding the code that touches what it must not
static void App_IllegalAccess( gtzc_Periph_t periph )
{
/* log the peripheral, the fault happened in the non-secure code */
}
(void)Gtzc_Set_IllegalAccessActive( GTZC_PERIPH_RNG );
Behaviour and limits
- Secure code only. The controller registers are accessible to the secure privileged code; the module cannot be used from the non-secure world and reports it as an error.
- Order at the boot. The attributes are set before the non-secure application starts; a peripheral used by both worlds is split in the application design (the module does not arbitrate).
- Lock. After
Gtzc_Set_ConfigLockthe configuration is frozen until the reset - every later change is reported as an error. - Granularity. The SRAM blocks and the watermark regions have a granularity; a range is rounded inwards (never wider than requested) and the module returns an error when the range becomes empty.
- External memories. A watermark region protects the window of the memory-mapped external memory; the encrypted execution of it (the OtfDec module) is a separate protection.
- Not part of the first version: the dynamic reassignment of the peripherals between the worlds during the run, the attribution of the Cortex-M33 SAU, the partitioning of the flash.
Dependencies
- Rcc - the clock of the controller
- Nvic - the illegal access interrupt
- Flash - the TrustZone enable and the flash watermark are configured there (the module only reads the security state)
- RAL (Register Abstraction Layer) - used internally to access the registers
All mandatory RCC and NVIC configurations are handled internally.
Testing
- Unit tests (host, Unity + CMock + RegMem): the peripheral list applied in full, the rejected calls from the non-secure state, the range rounding and the empty range, the overlap check of the regions, the lock behaviour, the illegal access flags and the callback.
- Integration tests (target, probe-rs): a non-secure access to a secure peripheral and to a secure SRAM block produces the illegal access report, the secure access passes, the lock is effective until the reset.
Interface conventions
The module follows the common rules of the MCAL layer, so that it behaves like the other modules:
- Lists instead of free members. Everything that the hardware restricts (the pins, the kernel clock sources, the DMA
channels, the triggers and the other selectable sources) is a
typedef enumlist with exactly the items that are valid for the device line; a pin is an itemGTZC_<SIGNAL>_PIN_<INSTANCE>_P<port><pin>and there is an*_UNUSEDitem. A choice that is not in the list cannot be written. - Own peripheral only. The module calls only the registers / LL functions of its own peripheral. The clocks, the interrupts, the pins, the DMA and the EXTI lines go through the API of the Rcc, Nvic, Gpio, Gpdma and Exti modules; a missing function is added to that module, it is not bypassed.
- Init verifies itself.
Gtzc_Initchecks the result at the end; when it is not as required, the module is deinitialized and an error is returned. The waiting for the hardware is a loop on the register state with a timeout, never a blind delay. - Transfer modes. Where the module moves data, the POLL (served by
Gtzc_Task), ISR and DMA modes have the same configuration structure, the same request and the same callbacks (error, half transfer, transfer complete). - Flags and states are enums of the module (
gtzc_FunctionState_t,gtzc_FlagState_t), the limits and the constants are named, there are no magic numbers in the interface. - Unsupported functions stay. A function without a meaning in a family keeps its signature, suppresses the unused
parameters and returns
GTZC_REQUEST_ERROR. - Documentation. Every function and type has a Doxygen description, the main header has the
\defgroup.
Repository layout and branches
The master holds this README and the license. The family branches (Dev/<Family>, Releases/<Family>) hold:
| Path | Content |
|---|---|
README.md | README of the family: the instances of the device, specifics, errata, status |
Gtzc_Port.h, Gtzc_Types.h | Public interface (identical in all families) |
Gtzc*.c, Gtzc.h | Implementation of the family |
CMakeLists.txt | Library Gtzc_Lib of the EmBi platform |
Tests/UnitTests | Unit tests (Unity + CMock + RegMem) |
Tests/IntegrationTests | Integration tests on the target (probe-rs) |
A change of the public interface is made in all families.
CMake integration
target_link_libraries( User_Lib PRIVATE Gtzc_Lib )
- Link
Gtzc_Libto your CMake library. - Include
Gtzc_Port.hin your project. - Configure the module as needed for your hardware.
License
This project is licensed under the Creative Commons Attribution-NonCommercial 4.0 International (CC BY-NC 4.0).
You are free to use, modify, and share this work for non-commercial purposes, provided appropriate credit is given.
See LICENSE.md for full terms or visit creativecommons.org/licenses/by-nc/4.0.
Authors
- Mr.Nobody - embedbits.com
Contributions are welcome! Please open a pull request.