In a bare-metal environment, this is achieved by executing all OpenThread procedures from the main function context. Do not call any OpenThread functions in ISRs or callbacks from ISR context. You can use the app_scheduler module to execute callbacks from the app_timer and the SoftDevice in the main context. Refer to the examples included in this SDK to see how the app_scheduler module should be used with OpenThread.
In an operating system environment, all calls to the OpenThread API must be performed from a single thread. Other threads may call OpenThread functions, but the function call must be guarded by mutex to make sure one call is not preempted by another one. For a reference, see BLE HRS and Thread CoAP Server with FreeRTOS Example.

Mbed TLS configuration header file

The Mbed TLS cryptographic library uses a custom configuration file that enables various functionalities and cryptographic operations.

Use the correct configuration file depending on the variant of the Mbed TLS library:

variant with the CryptoCell 310 module:
- File name: nrf-config.h
- Path: <InstallFolder>/external/nrf_security/config
Software-only variant:
- File name: mbedtls-config.h
- Path: <InstallFolder>/external/openthread/mbedtls/mbedtls/platform

Configuring Thread-safe Mbed TLS

You need to configure thread-safe Mbed TLS to be able to use mutexes, either those included in this SDK or your own.

In general, to keep the Mbed TLS library thread-safe, make sure that a single thread uses only one context of any function. For more details and the list of modules with automatic locking protection, see MbedTLS Thread Safety and Multi Threading.

However, if you want to use multiple threads when working with the Mbed TLS library, you need to complete additional configuration steps. The steps depend on the Mbed TLS library variant that is used. Make sure to include the required libraries in your project.

Software-only variant

An external implementation for mutexes is used when working in the RTOS environment.

By default, the Mbed TLS software-only library uses the mutex definition from <InstallFolder>/external/nrf_security/include/software-only-threading. However, you can modify it by providing a path to a header file with your definition. To do this, build your application with the following define:

MBEDTLS_THREADING_MUTEX_DEF="path_to_a_header_file_with_mutex_definition.h"

This SDK provides sample implementation of mutex for FreeRTOS. To enable multi-threading in your FreeRTOS application that uses the software-only Mbed TLS:

Include in your project the freertos_mbedtls_mutex component available at <InstallFolder>/components/thread/freertos_mbedtls_mutex.
Call the function freertos_mbedtls_mutex_init() in the initialization of the application before initializing OpenThread and using any mbedTLS API.

Use the following setup in the RTOS environment (with error checking omitted):

freertos_mbedtls_mutex_init()

Note: When using the freertos_mbedtls_mutex component, use the external implementation of some heap operations, that is, use the heap_4.c file available at <InstallFolder>/external/freertos/source/portable/MemMang.

ARM CryptoCell 310 module variant

CryptoCell hardware is present only in nRF52840.

The CryptoCell library is used by OpenThread to accelerate cryptographic operations (AES-EBC, ECJ-PAKE, and SHA256) in the Mbed TLS library. For more information about CryptoCell, see CryptoCell library.

This SDK provides a precompiled version of the hardware-accelerated Mbed TLS library that uses the ARM CryptoCell technology, which can be used with OpenThread. When building an application that uses the precompiled CryptoCell 310 example implementations from the SDK, the following explicit setup is needed (with error checking omitted):

mbedtls_platform_set_calloc_free(calloc, free);

mbedtls_platform_setup(NULL);

This setup can be modified depending on the additional support you want to configure, either for multiple threads or abort mechanism, or both. If sample implementations from the SDK for both options are used, the setup looks as follows:

mbedtls_platform_set_calloc_free(calloc, free);
nrf_cc310_platform_abort_init();
nrf_cc310_platform_mutex_init();
mbedtls_platform_setup(NULL);

Support for multiple threads

The hardware-accelerated Mbed TLS library supports access from multiple threads. The mutex mechanism is set by the nrf_cc310_platform_set_mutexes() function:

void nrf_cc310_platform_set_mutexes(nrf_cc310_platform_mutex_apis_t const * const apis,

nrf_cc310_platform_mutexes_t const * const mutexes)

This function must be called before mbedtls_platform_setup().

The SDK provides sample implementation of mutexes, depending on the operating system:

Path: <InstallFolder>/external/nrf_security/nrf_cc310_plat
FreeRTOS files:
- include/nrf_cc310_platform_mutex_freertos.h
- src/nrf_cc310_platform_mutex_freertos.c
Zephyr files:
- include/nrf_cc310_platform_mutex_zephyr.h
- src/nrf_cc310_platform_mutex_zephyr.c

Both files for each of the operating systems implement the following function:

int nrf_cc310_platform_mutex_init(void)

This function calls the nrf_cc310_platform_set_mutexes() function with custom mutex definitions.

The nrf_cc310_platform_mutex_init() function must be called before mbedtls_platform_setup():

mbedtls_platform_set_calloc_free(calloc, free);
nrf_cc310_platform_mutex_init();
mbedtls_platform_setup(NULL);

Support for abort mechanism

The CryptoCell 310 platform implements an abort mechanism. By default, any fault in the CryptoCell 310 library results in the system reset. The default behavior can be changed by a call to the nrf_cc310_platform_set_abort() function:

void nrf_cc310_platform_set_abort(nrf_cc310_platform_abort_apis_t const * const apis)

This function must be called before mbedtls_platform_setup().

The SDK provides sample implementation of the abort functionality, depending on the operating system:

Path: <InstallFolder>/external/nrf_security/nrf_cc310_plat
FreeRTOS files:
- include/nrf_cc310_platform_abort_freertos.h
- src/nrf_cc310_platform_abort_freertos.c
Zephyr files:
- include/nrf_cc310_platform_abort_zephyr.h
- src/nrf_cc310_platform_abort_zephyr.c

Both files for each of the operating systems implement the following function:

int nrf_cc310_platform_abort_init(void)

This function calls the nrf_cc310_platform_set_abort() function with custom abort definitions.

The nrf_cc310_platform_abort_init() function must be called before mbedtls_platform_setup():

mbedtls_platform_set_calloc_free(calloc, free);
nrf_cc310_platform_abort_init();
mbedtls_platform_setup(NULL);

USB pseudo reset

The USB variant of the nRF52840 platform library uses a feature called pseudo reset.

Pseudo reset causes the reinitialization of the OpenThread stack and certain peripherals. It is invoked instead of triggering a hardware reset when a reset from OpenThread stack is requested. The reason for such behavior is that when native USB CDC connectivity is used, performing a hardware reset would cause the device to reenumerate in the host system. As a result, this would impair the ongoing communication through CLI or Spinel. Any application that uses USB CDC for serial communication must use the pseudo reset feature instead of the hardware reset. Refer to Thread CLI Example or Thread NCP/RCP Example for an example implementation of this feature.

Table of Contents