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_ConfigureHfxo(void)

Configure HFXO.

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.

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

Type	Direction	Argument Name	Description
	[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.

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().

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.

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().

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

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

Type	Direction	Argument Name	Description
	[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.

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().

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().

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

Direction	Argument Name	Description
[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.

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().

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

Type	Direction	Argument Name	Description
const RAIL_TZ_Config_t *	[in]	pTzConfig	A non-NULL pointer to a RAIL_TZ_Config_t structure.

Returns

Status code indicating success of the function call.

Note

This function must only be called from non-secure world (only if TrustZone is activated) on platforms having RAIL_SUPPORTS_TRUSTZONE_SECURE_PERIPHERALS. It must be called before RAIL_Init() and it must be called again with updated RAIL_TZ_Config_t if peripherals secure configuration has changed.

RAIL_TZ_InitSecure#

RAIL_Status_t RAIL_TZ_InitSecure (void )

Init RAIL TrustZone feature for secure world.

Parameters

Type	Direction	Argument Name	Description
void	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.

RAIL_TZ_CheckPeripheralsSecureStates#

RAIL_Status_t RAIL_TZ_CheckPeripheralsSecureStates (void )

Check the secure state of peripherals used by RAIL.

Parameters

Type	Direction	Argument Name	Description
void	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.

RAIL_TZ_RadioClockEnable#

RAIL_Status_t RAIL_TZ_RadioClockEnable (void )

Enable radio clocks.

Parameters

Type	Direction	Argument Name	Description
void	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.

RAIL_TZ_RfecaClockEnable#

RAIL_Status_t RAIL_TZ_RfecaClockEnable (void )

Enable RFECA clocks.

Parameters

Type	Direction	Argument Name	Description
void	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.

RAIL_TZ_RfecaIsClockEnabled#

bool RAIL_TZ_RfecaIsClockEnabled (void )

Indicate whether RFECA clocks are enabled.

Parameters

Type	Direction	Argument Name	Description
void	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.

RAIL_TZ_ReadInternalTemperature#

RAIL_Status_t RAIL_TZ_ReadInternalTemperature (uint16_t * internalTemperatureKelvin, bool enableTemperatureInterrupts)

Read the internal temperature.

Parameters

Type	Direction	Argument Name	Description
uint16_t *	[out]	internalTemperatureKelvin	A pointer to the internal temperature in Kelvin.
bool	[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.

RAIL_TZ_EnableSecureRadioIrqs#

RAIL_Status_t RAIL_TZ_EnableSecureRadioIrqs (void )

Enable secure peripheral interrupts needed by the radio.

Parameters

Type	Direction	Argument Name	Description
void	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.

RAIL_TZ_DisableSecureRadioIrqs#

RAIL_Status_t RAIL_TZ_DisableSecureRadioIrqs (void )

Disable secure peripheral interrupts needed by the radio.

Parameters

Type	Direction	Argument Name	Description
void	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.

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

Type	Direction	Argument Name	Description
uint32_t *	[in]	pDest	A pointer to the destination data.
const uint32_t *	[in]	pSrc	A pointer to the source data.
uint32_t	[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.

RAIL_TZ_ConfigureHfxo#

RAIL_Status_t RAIL_TZ_ConfigureHfxo (void )

Configure HFXO.

Parameters

Type	Direction	Argument Name	Description
void	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.

RAIL_TZ_ConfigAntennaGpio#

RAIL_Status_t RAIL_TZ_ConfigAntennaGpio (const RAIL_AntennaConfig_t * config)

Set GPIO for antenna config.

Parameters

Type	Direction	Argument Name	Description
const RAIL_AntennaConfig_t *	[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.