Documentation on deps/src/newlib_nano.c

[javf88]

Dear Threadx team,

I hope you are doing well. I am new with threadx but I find it very interesting as a new RTOS.
Here is a feature/documentation request. Maybe there is no need of documentation and the answers to my questions would be enough :)

kind regards,
javf88

Is your feature request related to a problem? Please describe.
The deps/src/newlib_nano.c file is a bit puzzling. I have worked with newlib and newlib-nano. It seems to me that most of the content of this file are stubs. I found no traces of it in the devkit from Microsoft, but I did find some similar ideas in the mxchip/mxos repo.

What is the purpose of this file? It seems to me that the file has stubs of some POSIX/runtime functions.

Describe the solution you'd like
Could you add some documentation for this file? maybe in the comment at the top of the file could help.

Describe alternatives you've considered
If it is a file with only stubs to be able to link threadx with newlib, I would try to keep it simple and clean. I linked threadx against two different version of arm-none-eabi, the linker complains about different functions that are undefined. Curiously enough, the higher the version of arm-none-eabi, the more undefined functions.

Additional context
I am trying to add a new board to threadx

[fdesbiens]

Hi @javf88.

Thank you for working on support for new hardware! Out of curiosity, what is it?

As a quick repository-placement reminder: reusable processor/compiler core ports belong in the ThreadX repository, while board support packages, board initialisation, samples, and demos belong in SampleX.

newlib_nano.c is not part of ThreadX itself or the ThreadX POSIX compatibility layer. It provides the target-facing system-call hooks that Newlib/Newlib-nano expects when running on a bare-metal target. In this sample, _read() and _write() are implemented separately by the board console code, while functions such as _close(), _fstat(), and _sbrk() are provided by newlib_nano.c.

The exact set of required hooks depends on the Newlib version and configuration, linker specifications, and which C library routines the application uses. Therefore, seeing additional undefined symbols after changing Arm GNU Toolchain versions is expected. Those functions should be implemented in the BSP according to the board and application requirements; the sample stubs should not be treated as a portable or exhaustive implementation. In particular, a production _sbrk() implementation should enforce linker-defined heap bounds and account for concurrency.

The new POSIX regression tests use the same kind of C-library glue to run on bare-metal QEMU, which is likely the connection you noticed. However, those hooks remain separate from the ThreadX POSIX layer: the POSIX layer implements APIs such as pthreads, semaphores, and message queues using ThreadX primitives; it does not provide Newlib's target system calls.

We have now clarified this in SampleX PR #68 and added general bare-metal C-library integration guidance in documentation PR #75. Have a look and let me know what you think!