Newlib + threadx

[Mula-Gabriel]

I use ThreadX with Newlib (or Newlib-nano) on several NXP microcontrollers.
I'm using the version of Newlib provided by NXP with MCUXpresso (Newlib version 4.3.0, Mcuxpresso 24.12 ).
Newlib is built with multithreading support enabled (SINGLE_THREAD is not defined) and with _RETARGETABLE_LOCKING enabled.

I’ve implemented all the _retarget_lock***** functions using ThreadX mutexes, and I’ve made sure in the linker script that the Newlib-managed heap doesn’t overlap with any byte pool or extended objects managed by ThreadX.
I chose this approach because it felt more "complete" than implementing only the specific lock hooks like __malloc_lock or __env_lock.
With this setup, I can use malloc or printf from multiple threads, and everything seems stable.

However, after reading this section on reentrancy, I’m concerned that I may not be managing __reent properly.

Option 1: Manually managing the struct _reent per thread seems error-prone to me.
Ideally, I’d like this structure to be handled automatically.

On FreeRTOS, there’s a compilation flag configUSE_NEWLIB_REENTRANT that updates _impure_ptr during vTaskSwitchContext.

Question: On ThreadX, what are the recommended practices to properly manage the _reent struct?

[fdesbiens]

@eclipse-threadx/iot-threadx-committers and @eclipse-threadx/iot-threadx-contributors: Please provide feedback to the issue's author.

[Mula-Gabriel]

After further investigation, I identified a potentially suitable solution by leveraging the USER_EXTENSION mechanism.

1. To detect thread context switches, I compiled ThreadX with the TX_ENABLE_EXECUTION_CHANGE_NOTIFY option enabled.
   (On my target, this flag should be add as assembler additional option, because those fonction are called in tx_thread_schedule.S)

I define the following fonction somewhere in my code :

void _tx_execution_thread_enter(void)
{
    extern TX_THREAD *     _tx_thread_current_ptr;
    _impure_ptr = &_tx_thread_current_ptr->newlib;
}

void _tx_execution_thread_exit(void)
{
	//Nothing special to do
}

2. To add a reent struct per thread i set (in tx_user.h)

#define TX_THREAD_USER_EXTENSION struct _reent newlib;

and define init macro like that :
#define TX_THREAD_CREATE_EXTENSION(thread_ptr) _REENT_INIT_PTR(&thread_ptr->newlib);

Note that tx_port.h need a little change to not redefine TX_THREAD_CREATE_EXTENSION to empty :

from

#define TX_THREAD_CREATE_EXTENSION(thread_ptr)
#define TX_THREAD_DELETE_EXTENSION(thread_ptr)

to

//may be defined in tx_user.h
#if !defined(TX_THREAD_CREATE_EXTENSION)
#define TX_THREAD_CREATE_EXTENSION(thread_ptr)
#endif

#if !defined(TX_THREAD_DELETE_EXTENSION)
#define TX_THREAD_DELETE_EXTENSION(thread_ptr)
#endif

What are your thoughts on this approach ?

[fdesbiens]

I think @sanderson-AstroFirmwareSolutions mentioned that he had experience with Newlib. Can you confirm, Seth?

[sanderson-AstroFirmwareSolutions]

@Mula-Gabriel, I believe you are taking a good approach, but there are a few more things that I would add. I can confirm that the following approach is threadsafe (for threads and one level of ISR), so long as you ensure that TX_ENABLE_EXECUTION_CHANGE_NOTIFY is defined for assembly and C files, and that Newlib's locking functions have a suitable locking mechanism.

In tx_user.h:

#include <reent.h>

#define TX_THREAD_USER_EXTENSION               struct _reent reent;

#define TX_THREAD_CREATE_INTERNAL_EXTENSION(threadPtr)                \
	{                                                                 \
		memset(&(threadPtr)->reent, 0, sizeof((threadPtr)->reent)); \
		_REENT_INIT_PTR_ZEROED(&(threadPtr)->reent);                  \
	}

#define TX_THREAD_DELETE_PORT_COMPLETION(threadPtr) \
	{                                               \
		if (_impure_ptr == &(threadPtr)->reent) {   \
			_impure_ptr = &_impure_data;            \
		}                                           \
		_reclaim_reent(&(threadPtr)->reent);        \
	}

#define TX_THREAD_RESET_PORT_COMPLETION(threadPtr) \
	TX_THREAD_DELETE_PORT_COMPLETION(threadPtr)    \
	TX_THREAD_CREATE_INTERNAL_EXTENSION(threadPtr)

Of course, do check that these macros are not overridden for your ThreadX port.

In C file:

#include <reent.h>
#include "tx_api.h"
#include "tx_port.h"
#include "tx_thread.h"
#include "tx_timer.h"

ULONG tx_execution_isr_nest_counter;

VOID _tx_execution_thread_enter(void) {
	_impure_ptr = &_tx_thread_current_ptr->reent;
}

VOID _tx_execution_thread_exit(void) {
	_impure_ptr = &_impure_data;
}

VOID _tx_execution_isr_enter(void) {
	tx_execution_isr_nest_counter++;

	if ((TX_THREAD_GET_SYSTEM_STATE()) && (tx_execution_isr_nest_counter == 1)) {
		_impure_ptr = &_impure_data;
	}
}

VOID _tx_execution_isr_exit(void) {
	if ((TX_THREAD_GET_SYSTEM_STATE()) && (tx_execution_isr_nest_counter == 1)) {
		TX_THREAD* thread_ptr = _tx_thread_current_ptr;

		if (thread_ptr) {
			_impure_ptr = &thread_ptr->reent;
		}
	}

	tx_execution_isr_nest_counter--;
}

With these additions, you could use the following check to ensure that newlib is threadsafe at compile time, in an assembly and C/H file:

#if !defined(TX_ENABLE_EXECUTION_CHANGE_NOTIFY) && !defined(TX_EXECUTION_PROFILE_ENABLE)
	#error "TX_ENABLE_EXECUTION_CHANGE_NOTIFY or TX_EXECUTION_PROFILE_ENABLE must be defined. Newlib is not threadsafe."
#endif

Implementing Newlib's locking functions without switching the reent struct on a per-thread basis would cause functions such as strtok to be NOT threadsafe. When each thread has its own reent struct, strtok is threadsafe.

Newlib's locking functions do need to be implemented in some way for Newlib to be threadsafe. Some of Newlib's locking functions are for creating and deleting locks. I would need to test some things using ThreadX mutexes to give you more concrete advice for using ThreadX mutexes for Newlib's locks. If you can permit it, simply disabling interrupts can be acceptable. Be sure that the locks that you use are recursive (for example, by keeping track of the PRIMASK and how many times each lock has been locked).

The best way I have found to test if the reent struct is safe on a system is to continuously snprintf a floating-point number in a task. Then, very frequently, interrupt that task for a different task that also snprintf's a floating point number. In both places, check that the number returned from snprintf is equal to the strlen of the string produced by snprintf. Those numbers should be the same.

Do you have any more questions?

[Mula-Gabriel]

I have no further questions, thank you. However, since newlib is widely used, I suggest adding this response to the documentation. Thank you again for your support.

[fdesbiens]

Thank you for confirming, @Mula-Gabriel.

@sanderson-AstroFirmwareSolutions: Can I ask you to propose a way to add this information to our official documentation, please? You will find the source here: https://github.com/eclipse-threadx/rtos-docs-asciidoc