(nuttx) 05/05: Documentation: Describe TLS, constructors and section placement in NXFLAT.

[ac...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

acassis pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/nuttx.git

commit a44a93f9b6bdd952dbcc942e982cf6028de8d4bc
Author: Marco Casaroli <ma...@gmail.com>
AuthorDate: Mon Oct 19 10:02:20 2026 +0200

    Documentation: Describe TLS, constructors and section placement in NXFLAT.
    
    Add two limitations to the NXFLAT page: a module can use __thread and
    thread_local variables only with emulated TLS, and nothing runs the
    static constructors and destructors of a module.  ldnxflat refuses a
    module with native TLS sections or with an .init_array or .fini_array.
    
    Also say that ldnxflat places the sections itself, so a section that the
    linker script does not name does not overlap another one.
    
    Assisted-by: Claude Code:claude-opus-5-5
    Signed-off-by: Marco Casaroli <ma...@gmail.com>
---
 Documentation/os/binfmt/nxflat.rst | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/Documentation/os/binfmt/nxflat.rst b/Documentation/os/binfmt/nxflat.rst
index 73616c042ea..79bd0e142a5 100644
--- a/Documentation/os/binfmt/nxflat.rst
+++ b/Documentation/os/binfmt/nxflat.rst
@@ -117,6 +117,20 @@ Limitations
     and watchdog timer callbacks. But other callbacks (like those
     used with qsort() must be avoided in an NXFLAT module.
 
+  - **Emulated Thread-Local Storage Only**:
+    A module can use ``__thread`` and C++ ``thread_local`` variables only
+    when the toolchain emulates TLS (GCC configured with ``--disable-tls``).
+    The compiler then calls ``__emutls_get_address()``, which the module
+    imports from the base code like any other function. ``ldnxflat``
+    refuses a module that holds native TLS sections (``.tdata``,
+    ``.tbss``).
+
+  - **No Static Constructors**:
+    Nothing runs the static constructors and destructors of a module
+    (``.init_array``, ``.fini_array``), so ``ldnxflat`` refuses a module
+    that has them. A C++ ``thread_local`` object needs no static
+    constructor: each thread constructs it at its first use.
+
 Supported Processors
 --------------------
 
@@ -216,6 +230,11 @@ binary module. See below for usage::
 option, which the older, out-of-tree tool had.  It converts ARM objects
 only, and refuses an object for another machine.
 
+``ldnxflat`` places the sections of each segment itself, in the order of
+the section headers, and does not use the addresses that the linker script
+gives.  So a section that the script does not name, such as a member of a
+C++ COMDAT group that ``ld -r`` keeps apart, does not overlap another one.
+
 mksymtab
 --------