Preskočiť na hlavný obsah

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:

BlockFunctionsMeaning
TZSC - peripherals and mastersGtzc_Set_PeriphAttribute, Gtzc_Get_PeriphAttribute, Gtzc_Set_MasterAttributeThe 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 - SRAMsGtzc_Set_SramBlockAttribute, Gtzc_Set_SramRangeAttributeThe 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 regionsGtzc_Set_WatermarkRegionThe secure / privileged regions of the external memories (the OCTOSPI, the FMC) and of the backup SRAM: start, length, attribute.
TZIC - illegal accessGtzc_Set_IllegalAccessActive, Gtzc_Get_IllegalAccessStatus, Gtzc_Set_IllegalAccessCallbackWhich peripherals report an illegal access by the interrupt, the status flags, the callback with the peripheral that was accessed.

Rules:

  1. 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.
  2. 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_ConfigLock locks it on purpose at the end of the boot.
  3. 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 by Gtzc_Init.
  4. 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).
  5. 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.
  6. 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.

FamilyBranchControllerStatus
STM32H5Dev/STM32H5GTZC1: 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)
STM32U5Dev/STM32U5GTZC1, GTZC2 (the domains), TZSC, MPCBB, watermark controllers, TZICplanned
STM32U3Dev/STM32U3GTZCplanned
STM32G4, STM32L4, STM32H7, STM32F4, STM32F7Dev/STM32G4 ...no TrustZone on the device - the module is a stub that returns GTZC_REQUEST_ERRORplanned

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)​

GroupFunctions
Module managementGtzc_Get_ModuleVersion, Gtzc_Init, Gtzc_Deinit, Gtzc_Task, Gtzc_Get_DefaultConfig
Peripherals and mastersGtzc_Set_PeriphAttribute, Gtzc_Get_PeriphAttribute, Gtzc_Set_PeriphAttributeList, Gtzc_Set_MasterAttribute
SRAM blocksGtzc_Set_SramBlockAttribute, Gtzc_Set_SramRangeAttribute, Gtzc_Get_SramBlockAttribute
Watermark regionsGtzc_Set_WatermarkRegion, Gtzc_Get_WatermarkRegion
Illegal accessGtzc_Set_IllegalAccessActive, Gtzc_Set_IllegalAccessInactive, Gtzc_Get_IllegalAccessStatus, Gtzc_Set_IllegalAccessClear
LockGtzc_Set_ConfigLock, Gtzc_Get_LockState
InterruptsGtzc_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.

TypeMeaning
gtzc_Config_tThe 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_tGTZC_PERIPH_USART1 ... - only the securable peripherals of the device
gtzc_Sram_tGTZC_SRAM_1, GTZC_SRAM_2, GTZC_SRAM_3 ...
gtzc_Security_t, gtzc_Privilege_tGTZC_SECURE / GTZC_NON_SECURE, GTZC_PRIVILEGED / GTZC_UNPRIVILEGED
gtzc_Region_t, gtzc_RegionConfig_tThe watermark region (OCTOSPI 1, FMC bank 1 ..., backup SRAM) and its start, length and attribute
gtzc_IllegalAccessCallback_tvoid ( 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( &gtzcConfig );
gtzcConfig.PeriphList = periphTable;
gtzcConfig.PeriphListCnt = sizeof( periphTable ) / sizeof( periphTable[ 0u ] );

(void)Gtzc_Init( &gtzcConfig );
(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_ConfigLock the 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 enum list with exactly the items that are valid for the device line; a pin is an item GTZC_<SIGNAL>_PIN_<INSTANCE>_P<port><pin> and there is an *_UNUSED item. 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_Init checks 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:

PathContent
README.mdREADME of the family: the instances of the device, specifics, errata, status
Gtzc_Port.h, Gtzc_Types.hPublic interface (identical in all families)
Gtzc*.c, Gtzc.hImplementation of the family
CMakeLists.txtLibrary Gtzc_Lib of the EmBi platform
Tests/UnitTestsUnit tests (Unity + CMock + RegMem)
Tests/IntegrationTestsIntegration 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 )
  1. Link Gtzc_Lib to your CMake library.
  2. Include Gtzc_Port.h in your project.
  3. 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​

Contributions are welcome! Please open a pull request.