Functions
bool	tz_api_init (struct tz_api *apip)
	Initialize the TrustZone API.

bool	tz_api_poll (void)
	Poll the secure world and process all events in the queue.

void	tz_api_println (const char *text, size_t len)
	Print the specified message via the secure world.

bool	tz_api_request_ns_poll (void)
	Mark the normal world as needing another poll cycle.

Detailed Description

This subsystem implements TrustZone support for Arm Cortex-M processors. The archtiecture is based on dual Contiki-NG firmwares: the secure world contains an instance of Contiki-NG with reduced functionality, and the normal world contains an instance with regular functionality. When programming an IoT device, the hex files with the two firmwares are merged into a single hex file, which is flashed to the device.

Both worlds can access core system functionality such as processes, timers, and library functions. The normal world is expected to contain applications and networking functionality. By contrast, the secure world will contain secret information and functionality for monitoring the normal world. Hardware peripherals can be configured to be accessible in either of the worlds.

Currently, the only supported Contiki-NG platform is the nRF5340 development kit, which is equipped with two different Arm Cortex-M33 processors.

Function Documentation

◆ tz_api_init()

bool tz_api_init ( struct tz_api * apip )

Initialize the TrustZone API.

Parameters

apip	A pointer to a tz_api structure.

Return values

false	Error (apip pointed to invalid memory, or the API has been initialized already.)
true	Success.

Note: Must be called from the normal world before any normal-world scheduling begins, since the secure side posts trustzone_init_event to autostart processes from inside this call.

Definition at line 59 of file tz-api.c.

References process_alloc_event(), and process_post().

◆ tz_api_poll()

bool tz_api_poll ( void )

Poll the secure world and process all events in the queue.

Return values

true	If the secure world has more work to do — either residual events in the queue, or a deferred poll request raised by the secure side during the call. The NS caller should reschedule itself.
false	If the secure world has nothing more to do, or the call was rejected (see note).

Note: Must be called only from NS thread mode. The function runs process_run() and is not reentrant; calls from a handler context (NS interrupt or, defensively, a secure ISR) are rejected and return false without running events.

Definition at line 88 of file tz-api.c.

References clock_time(), process_nevents(), process_run(), and watchdog_periodic().

◆ tz_api_println()

void tz_api_println	(	const char *	text,
		size_t	len )

Print the specified message via the secure world.

Parameters

text	A pointer to the message text in non-secure memory.
len	The length of the message in bytes.

Definition at line 136 of file tz-api.c.

◆ tz_api_request_ns_poll()

bool tz_api_request_ns_poll ( void )

Mark the normal world as needing another poll cycle.

          Called from the secure world (e.g. via the Contiki-NG
          process module's PROCESS_CONF_POLL_REQUESTED hook)
          when secure-side state changes that the normal world
          needs to react to. The flag is observed by the next
          tz_api_poll(), which then returns true so the NS
          caller reschedules itself.

          This is a secure-internal helper, not a secure
          gateway entry, and must not be called from the
          normal world.