TrustZone#

APIs to use RAIL with TrustZone enabled and peripherals configured as secure.

RAIL internally accesses CMU, EMU, GPIO, LDMA, HFXO, PRS and SYSRTC. If some of them are configured as secure peripherals, some RAIL code must be executed as secure code. To do so, callbacks gathered in RAIL_TZ_Config_t must be implemented and passed to RAIL through RAIL_TZ_InitNonSecure(). Each callback must do the non-secure/secure transition, call RAIL_TZ_CheckPeripheralsSecureStates() and then call the corresponding RAIL API from secure world:

Secure peripheral

Callbacks to implement

CMU

RAIL_TZ_Config_t::changedDcdcCallback, RAIL_TZ_Config_t::configAntennaGpioCallback, RAIL_TZ_Config_t::radioClockEnableCallback, RAIL_TZ_Config_t::getRadioClockFreqHzCallback, RAIL_TZ_Config_t::rfecaClockEnableCallback, RAIL_TZ_Config_t::rfecaIsClockEnabledCallback

EMU

RAIL_TZ_Config_t::readInternalTemperatureCallback, RAIL_TZ_Config_t::enableSecureRadioIrqsCallback, RAIL_TZ_Config_t::disableSecureRadioIrqsCallback

GPIO

RAIL_TZ_Config_t::configAntennaGpioCallback

LDMA

RAIL_TZ_Config_t::radioPerformM2mLdmaCallback

HFXO

RAIL_TZ_Config_t::configureHfxoCallback

RAIL internally calls platform functions that access CMU, EMU, GPIO, LDMA HFXO and PRS. If some of them are configured as secure peripherals, some functions must be executed as secure code. To do so, those functions are prepended with weak symbols and must be overwritten to do the non-secure/secure transition and call the corresponding platform function from secure world:

Secure peripheral

Platform functions to overwrite

CMU

CMU_ClockEnable, EMU_DCDCSetPFMXTimeoutMaxCtrl (DCDC access: SL_TRUSTZONE_PERIPHERAL_DCDC_S)

HFXO

CMU_HFXOCTuneSet, CMU_HFXOCTuneGet, CMU_HFXOCoreBiasCurrentCalibrate

PRS

PRS_SourceAsyncSignalSet, PRS_GetFreeChannel, PRS_ConnectConsumer, PRS_PinOutput, PRS_Combine

When there is a combination of secure and non-secure peripherals, defines must be added in secure application slcp file so non-secure peripherals can properly accessed by secure code. Example with only CMU non-secure:

define:
  - name: SL_TRUSTZONE_PERIPHERAL_CMU_S
    value: 0
    condition: [trustzone_secure]
  - name: SL_TRUSTZONE_PERIPHERAL_EMU_S
    value: 1
    condition: [trustzone_secure]
  - name: SL_TRUSTZONE_PERIPHERAL_GPIO_S
    value: 1
    condition: [trustzone_secure]
  - name: SL_TRUSTZONE_PERIPHERAL_LDMA_S
    value: 1
    condition: [trustzone_secure]
  - name: SL_TRUSTZONE_PERIPHERAL_HFXO0_S
    value: 1
    condition: [trustzone_secure]
  - name: SL_TRUSTZONE_PERIPHERAL_PRS_S
    value: 1
    condition: [trustzone_secure]
  - name: SL_TRUSTZONE_PERIPHERAL_SYSRTC_S
    value: 1
    condition: [trustzone_secure]

Some RAIL API are not suppoted with EMU, GPIO, LDMA, HFXO, PRS or SYSRTC configured secure:

Secure peripheral

Unsupported RAIL API/features

EMU

RAIL_StartThermistorMeasurement(), RAIL_InitPowerManager()

GPIO

RAIL_EnableDirectMode(), RAIL_EnableDirectModeAlt(), RAIL_EnablePti(), RAIL_ConfigPti(), RAIL_ConfigHFXOThermistor(), RAIL_StartThermistorMeasurement(), RAIL_ConfigVdet()

LDMA

RAIL_IEEE802154_SUPPORTS_RX_CHANNEL_SWITCHING (RAIL_IEEE802154_ConfigRxChannelSwitching() and RAIL_RX_OPTION_CHANNEL_SWITCHING)

HFXO

RAIL_StartThermistorMeasurement(), RAIL_EnableVdet(), RAIL_GetVdet()

PRS

RAIL_EnablePrsLnaBypass()

SYSRTC

RAIL_ConfigSleep() with RAIL_SleepConfig_t::RAIL_SLEEP_CONFIG_TIMERSYNC_ENABLED, RAIL_ConfigSleepAlt() with RAIL_SleepConfig_t::RAIL_SLEEP_CONFIG_TIMERSYNC_ENABLED

Modules#

RAIL_TZ_Config_t

Typedefs#

typedef RAIL_Status_t(*
RAIL_TZ_ChangedDcdcCallbackPtr_t)(void)

A pointer to the callback used to switch to secure world and run RAIL_ChangedDcdc().

typedef RAIL_Status_t(*
RAIL_TZ_ConfigAntennaGpioCallbackPtr_t)(const RAIL_AntennaConfig_t *config)

A pointer to the callback used to switch to secure world and run RAIL_TZ_ConfigAntennaGpio().

typedef void(*
RAIL_TZ_RadioClockEnableCallbackPtr_t)(void)

A pointer to the callback used to switch to secure world and run RAIL_TZ_RadioClockEnable().

typedef uint32_t(*
RAIL_TZ_GetRadioClockFreqHzCallbackPtr_t)(void)

A pointer to the callback used to switch to secure world and run RAIL_GetRadioClockFreqHz().

typedef void(*
RAIL_TZ_RfecaClockEnableCallbackPtr_t)(void)

A pointer to the callback used to switch to secure world and run RAIL_TZ_RfecaClockEnable().

typedef bool(*
RAIL_TZ_RfecaIsClockEnabledCallbackPtr_t)(void)

A pointer to the callback used to switch to secure world and run RAIL_TZ_RfecaIsClockEnabled().

typedef RAIL_Status_t(*
RAIL_TZ_ReadInternalTemperatureCallbackPtr_t)(uint16_t *internalTemperatureKelvin, bool enableTemperatureInterrupts)

A pointer to the callback used to switch to secure world and run RAIL_TZ_ReadInternalTemperature().

typedef void(*
RAIL_TZ_EnableSecureRadioIrqsCallbackPtr_t)(void)

A pointer to the callback used to switch to secure world and run RAIL_TZ_EnableSecureRadioIrqs().

typedef void(*
RAIL_TZ_DisableSecureRadioIrqsCallbackPtr_t)(void)

A pointer to the callback used to switch to secure world and run RAIL_TZ_DisableSecureRadioIrqs().

typedef RAIL_Status_t(*
RAIL_TZ_RadioPerformM2mLdmaCallbackPtr_t)(uint32_t *pDest, const uint32_t *pSrc, uint32_t numWords)

A pointer to the callback used to switch to secure world and run RAIL_TZ_RadioPerformM2mLdma().

typedef RAIL_Status_t(*
RAIL_TZ_ConfigureHfxoCallbackPtr_t)(void)

A pointer to the callback used to switch to secure world and run RAIL_TZ_ConfigureHfxo().

Functions#

RAIL_Status_t
RAIL_TZ_InitNonSecure(const RAIL_TZ_Config_t *pTzConfig)

Init RAIL TrustZone feature for non-secure world.

RAIL_Status_t
RAIL_TZ_InitSecure(void)

Init RAIL TrustZone feature for secure world.

RAIL_Status_t
RAIL_TZ_CheckPeripheralsSecureStates(void)

Check the secure state of peripherals used by RAIL.

RAIL_Status_t
RAIL_TZ_RadioClockEnable(void)

Enable radio clocks.

RAIL_Status_t
RAIL_TZ_RfecaClockEnable(void)

Enable RFECA clocks.

bool
RAIL_TZ_RfecaIsClockEnabled(void)

Indicate whether RFECA clocks are enabled.

RAIL_Status_t
RAIL_TZ_ReadInternalTemperature(uint16_t *internalTemperatureKelvin, bool enableTemperatureInterrupts)

Read the internal temperature.

RAIL_Status_t
RAIL_TZ_EnableSecureRadioIrqs(void)

Enable secure peripheral interrupts needed by the radio.

RAIL_Status_t
RAIL_TZ_DisableSecureRadioIrqs(void)

Disable secure peripheral interrupts needed by the radio.

RAIL_Status_t
RAIL_TZ_RadioPerformM2mLdma(uint32_t *pDest, const uint32_t *pSrc, uint32_t numWords)

Perform ldma transfer for the radio.

RAIL_Status_t
RAIL_TZ_ConfigAntennaGpio(const RAIL_AntennaConfig_t *config)

Set GPIO for antenna config.

Typedef Documentation#

RAIL_TZ_ChangedDcdcCallbackPtr_t#

RAIL_TZ_ChangedDcdcCallbackPtr_t )(void)

A pointer to the callback used to switch to secure world and run RAIL_ChangedDcdc().

Returns

  • Status code indicating success of the function call.


Definition at line 5942 of file common/rail_types.h

RAIL_TZ_ConfigAntennaGpioCallbackPtr_t#

RAIL_TZ_ConfigAntennaGpioCallbackPtr_t )(const RAIL_AntennaConfig_t *config)

A pointer to the callback used to switch to secure world and run RAIL_TZ_ConfigAntennaGpio().

Parameters
[in]config

A pointer to a configuration structure applied to the relevant Antenna Configuration registers. A NULL configuration will produce undefined behavior.

Returns

  • Status code indicating success of the function call.


Definition at line 5954 of file common/rail_types.h

RAIL_TZ_RadioClockEnableCallbackPtr_t#

RAIL_TZ_RadioClockEnableCallbackPtr_t )(void)

A pointer to the callback used to switch to secure world and run RAIL_TZ_RadioClockEnable().


Definition at line 5962 of file common/rail_types.h

RAIL_TZ_GetRadioClockFreqHzCallbackPtr_t#

RAIL_TZ_GetRadioClockFreqHzCallbackPtr_t )(void)

A pointer to the callback used to switch to secure world and run RAIL_GetRadioClockFreqHz().

Returns

  • Radio subsystem clock frequency in Hz.


Definition at line 5972 of file common/rail_types.h

RAIL_TZ_RfecaClockEnableCallbackPtr_t#

RAIL_TZ_RfecaClockEnableCallbackPtr_t )(void)

A pointer to the callback used to switch to secure world and run RAIL_TZ_RfecaClockEnable().


Definition at line 5980 of file common/rail_types.h

RAIL_TZ_RfecaIsClockEnabledCallbackPtr_t#

RAIL_TZ_RfecaIsClockEnabledCallbackPtr_t )(void)

A pointer to the callback used to switch to secure world and run RAIL_TZ_RfecaIsClockEnabled().

Returns

  • true if RFECA clocks are enabled; false otherwise


Definition at line 5990 of file common/rail_types.h

RAIL_TZ_ReadInternalTemperatureCallbackPtr_t#

RAIL_TZ_ReadInternalTemperatureCallbackPtr_t )(uint16_t *internalTemperatureKelvin, bool enableTemperatureInterrupts)

A pointer to the callback used to switch to secure world and run RAIL_TZ_ReadInternalTemperature().

Parameters
[out]internalTemperatureKelvin

A pointer to the internal temperature in Kelvin.

[in]enableTemperatureInterrupts

Indicate whether temperature interrupts are enabled.

Returns

  • Status code indicating success of the function call.


Definition at line 6004 of file common/rail_types.h

RAIL_TZ_EnableSecureRadioIrqsCallbackPtr_t#

RAIL_TZ_EnableSecureRadioIrqsCallbackPtr_t )(void)

A pointer to the callback used to switch to secure world and run RAIL_TZ_EnableSecureRadioIrqs().


Definition at line 6013 of file common/rail_types.h

RAIL_TZ_DisableSecureRadioIrqsCallbackPtr_t#

RAIL_TZ_DisableSecureRadioIrqsCallbackPtr_t )(void)

A pointer to the callback used to switch to secure world and run RAIL_TZ_DisableSecureRadioIrqs().


Definition at line 6021 of file common/rail_types.h

RAIL_TZ_RadioPerformM2mLdmaCallbackPtr_t#

RAIL_TZ_RadioPerformM2mLdmaCallbackPtr_t )(uint32_t *pDest, const uint32_t *pSrc, uint32_t numWords)

A pointer to the callback used to switch to secure world and run RAIL_TZ_RadioPerformM2mLdma().

Parameters
[in]pDest

A pointer to the destination data.

[in]pSrc

A pointer to the source data.

[in]numWords

Number of words to transfer.

Returns

  • Status code indicating success of the function call.


Definition at line 6034 of file common/rail_types.h

RAIL_TZ_ConfigureHfxoCallbackPtr_t#

RAIL_TZ_ConfigureHfxoCallbackPtr_t )(void)

A pointer to the callback used to switch to secure world and run RAIL_TZ_ConfigureHfxo().


Definition at line 6044 of file common/rail_types.h

Function Documentation#

RAIL_TZ_InitNonSecure#

RAIL_Status_t RAIL_TZ_InitNonSecure (const RAIL_TZ_Config_t * pTzConfig)

Init RAIL TrustZone feature for non-secure world.

Parameters
[in]pTzConfig

A non-NULL pointer to a RAIL_TZ_Config_t structure.

Returns

  • Status code indicating success of the function call.

Note


Definition at line 6823 of file common/rail.h

RAIL_TZ_InitSecure#

RAIL_Status_t RAIL_TZ_InitSecure (void )

Init RAIL TrustZone feature for secure world.

Parameters
N/A

Returns

  • Status code indicating success of the function call.

Note

  • This function must only be called from secure world (only if TrustZone is activated) on platforms having RAIL_SUPPORTS_TRUSTZONE_SECURE_PERIPHERALS. It must be called before starting the non-secure application.


Definition at line 6835 of file common/rail.h

RAIL_TZ_CheckPeripheralsSecureStates#

RAIL_Status_t RAIL_TZ_CheckPeripheralsSecureStates (void )

Check the secure state of peripherals used by RAIL.

Parameters
N/A

Returns

  • Status code indicating success of the function call.

Note

  • This function must only be called from secure world and it must be called at the beginning of each RAIL TrustZone callbacks (RAIL_TZ_Config_t) secure code to avoid secure fault.


Definition at line 6846 of file common/rail.h

RAIL_TZ_RadioClockEnable#

RAIL_Status_t RAIL_TZ_RadioClockEnable (void )

Enable radio clocks.

Parameters
N/A

Returns

  • Status code indicating success of the function call.

Note

  • This function must only be called from secure world when CMU is configured as secure TrustZone peripheral.


Definition at line 6857 of file common/rail.h

RAIL_TZ_RfecaClockEnable#

RAIL_Status_t RAIL_TZ_RfecaClockEnable (void )

Enable RFECA clocks.

Parameters
N/A

Returns

  • Status code indicating success of the function call.

Note

  • This function must only be called from secure world when CMU is configured as secure TrustZone peripheral.


Definition at line 6868 of file common/rail.h

RAIL_TZ_RfecaIsClockEnabled#

bool RAIL_TZ_RfecaIsClockEnabled (void )

Indicate whether RFECA clocks are enabled.

Parameters
N/A

Returns

  • true if RFECA clocks are enabled; false otherwise

Note

  • This function must only be called from secure world when CMU is configured as secure TrustZone peripheral.


Definition at line 6879 of file common/rail.h

RAIL_TZ_ReadInternalTemperature#

RAIL_Status_t RAIL_TZ_ReadInternalTemperature (uint16_t * internalTemperatureKelvin, bool enableTemperatureInterrupts)

Read the internal temperature.

Parameters
[out]internalTemperatureKelvin

A pointer to the internal temperature in Kelvin.

[in]enableTemperatureInterrupts

Indicate whether temperature interrupts are enabled.

Returns

  • Status code indicating success of the function call.

Note

  • This function must only be called from secure world when EMU is configured as secure TrustZone peripheral.


Definition at line 6894 of file common/rail.h

RAIL_TZ_EnableSecureRadioIrqs#

RAIL_Status_t RAIL_TZ_EnableSecureRadioIrqs (void )

Enable secure peripheral interrupts needed by the radio.

Parameters
N/A

Returns

  • Status code indicating success of the function call.

Note

  • This function must only be called from secure world when EMU is configured as secure TrustZone peripheral.


Definition at line 6906 of file common/rail.h

RAIL_TZ_DisableSecureRadioIrqs#

RAIL_Status_t RAIL_TZ_DisableSecureRadioIrqs (void )

Disable secure peripheral interrupts needed by the radio.

Parameters
N/A

Returns

  • Status code indicating success of the function call.

Note

  • This function must only be called from secure world when EMU is configured as secure TrustZone peripheral.


Definition at line 6917 of file common/rail.h

RAIL_TZ_RadioPerformM2mLdma#

RAIL_Status_t RAIL_TZ_RadioPerformM2mLdma (uint32_t * pDest, const uint32_t * pSrc, uint32_t numWords)

Perform ldma transfer for the radio.

Parameters
[in]pDest

A pointer to the destination data.

[in]pSrc

A pointer to the source data.

[in]numWords

Number of words to transfer.

Returns

  • Status code indicating success of the function call.

Note

  • This function must only be called from secure world when LDMA is configured as secure TrustZone peripheral.


Definition at line 6931 of file common/rail.h

RAIL_TZ_ConfigureHfxo#

RAIL_Status_t RAIL_TZ_ConfigureHfxo (void )

Configure HFXO.

Parameters
N/A

Returns

  • Status code indicating success of the function call.

Note

  • This function must only be called from secure world when HFXO is configured as secure TrustZone peripheral.


Definition at line 6944 of file common/rail.h

RAIL_TZ_ConfigAntennaGpio#

RAIL_Status_t RAIL_TZ_ConfigAntennaGpio (const RAIL_AntennaConfig_t * config)

Set GPIO for antenna config.

Parameters
[in]config

A pointer to a configuration structure applied to the relevant Antenna Configuration registers. A NULL configuration will produce undefined behavior.

Returns

  • Status code indicating success of the function call.

Note

  • This function must only be called from secure world when CMU or GPIO are configured as secure TrustZone peripheral.


Definition at line 6957 of file common/rail.h