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 fb1a739096abd636e331fc0943926078535c9bb1 Author: Marco Casaroli <[email protected]> AuthorDate: Sat Oct 17 20:04:46 2026 +0200 Documentation/nxflat: Describe the in-tree ldnxflat. ldnxflat is now in the tree, in tools/nxflat, and the make build makes it with mknxflat when CONFIG_NXFLAT is selected. Its options changed: -e and -o are required, and -d is gone. It also fixes the GOT entries of .bss objects, and Toolchain.defs adds -mno-pic-data-is-text-relative, so a module can have static data and string constants. The documentation still said that ldnxflat must come from the buildroot toolchain, showed the old usage, and said that a module must have no static data and no strings. Update the NXFLAT page, the nxflatxip example page and the xipfs-nxflat configuration of the pimoroni-pico-2-plus board. Assisted-by: Claude Code:claude-opus-5-5 Signed-off-by: Marco Casaroli <[email protected]> --- .../applications/examples/nxflatxip/index.rst | 18 +++-- Documentation/os/binfmt/nxflat.rst | 77 +++++++++++----------- .../rp23xx/boards/pimoroni-pico-2-plus/index.rst | 6 +- 3 files changed, 48 insertions(+), 53 deletions(-) diff --git a/Documentation/applications/examples/nxflatxip/index.rst b/Documentation/applications/examples/nxflatxip/index.rst index 74de1ee54e1..1b1e43e8a31 100644 --- a/Documentation/applications/examples/nxflatxip/index.rst +++ b/Documentation/applications/examples/nxflatxip/index.rst @@ -61,16 +61,14 @@ Building the module =================== The module is built from ``module/xipmod.c`` at build time, exactly the way -:doc:`../nxflat/index` builds its test programs, so it needs the same host -tools: ``mknxflat``, which NuttX builds itself, and ``ldnxflat``, which has -to come from the buildroot toolchain. See :doc:`/os/binfmt/nxflat`. - -The module has no static data and no string constants, and reports through a -callback into the firmware rather than formatting its own output. The comment -at the top of ``module/xipmod.c`` records why: the ``ldnxflat`` in -circulation miscomputes both of those cases. The callback also exercises the -other direction of the interface, firmware code entered with the module's -data base still live in its PIC register. +:doc:`../nxflat/index` builds its test programs, with the host tools +``mknxflat`` and ``ldnxflat`` that NuttX builds itself. See +:doc:`/os/binfmt/nxflat`. + +The module reports through a callback into the firmware rather than +formatting its own output. The callback exercises the other direction of +the interface: firmware code entered with the module's data base still live +in its PIC register. Configuration ============= diff --git a/Documentation/os/binfmt/nxflat.rst b/Documentation/os/binfmt/nxflat.rst index 4e38f751992..73616c042ea 100644 --- a/Documentation/os/binfmt/nxflat.rst +++ b/Documentation/os/binfmt/nxflat.rst @@ -143,30 +143,23 @@ Building an NXFLAT module takes two tools beyond an ordinary GCC toolchain: ``mknxflat``, which generates the module's *thunk* file, and ``ldnxflat``, which links the module into the NXFLAT binary format. -``mknxflat`` is part of NuttX, in ``tools/nxflat``. The build produces it as -``tools/mknxflat`` whenever ``CONFIG_NXFLAT`` is selected, so there is -nothing to install. - -``ldnxflat`` is not part of NuttX and cannot be: it is GPL and derives from -elf2flt. It lives in the NuttX buildroot toolchain, at -`patacongo/buildroot <https://github.com/patacongo/buildroot>`__, under -``toolchain/nxflat``. - -Only that one tool is needed. The rest of the buildroot toolchain is not: -an ordinary ``arm-none-eabi`` GCC compiles and links NXFLAT modules, so a -board does not have to select ``CONFIG_ARM_TOOLCHAIN_BUILDROOT`` to use -them. - -``ldnxflat`` reads its input through libbfd, so it is built against a -binutils source tree and a binutils build of the same version. -``toolchain/nxflat/Makefile`` takes those as ``BINUTILS_DIR`` and -``BINUTILS_DIR1``, and expects an ``arch`` symbolic link naming the target, -``thumb2`` or ``arm``. Where the binutils build leaves ``libbfd.a`` varies, -so the library path may need adjusting. Put the result on your ``PATH``. +Both tools are part of NuttX, in ``tools/nxflat``, and both are under the +Apache 2.0 license. When ``CONFIG_NXFLAT`` is selected, the make build +makes them as ``tools/mknxflat`` and ``tools/ldnxflat``, so there is +nothing to install. An ordinary ``arm-none-eabi`` GCC compiles and links +the module objects, so a board does not have to select +``CONFIG_ARM_TOOLCHAIN_BUILDROOT``. + +``tools/nxflat/testsuite.sh`` builds and converts every module of +``apps/examples/nxflat/tests`` and reports the relocations of each one. It +needs no board. On ARM, ``arch/arm/src/common/Toolchain.defs`` provides both ``MKNXFLAT`` (with the ``-a`` option following ``CONFIG_ARM_THUMB``) and ``LDNXFLAT``, so -a board only has to assign them if it needs something different. +a board only has to assign them if it needs something different. With +``CONFIG_NXFLAT``, the same file adds ``-mno-pic-data-is-text-relative`` to +``ARCHPICFLAGS`` (GCC only; Clang has no such option), so a module reaches +its read-only data through the GOT and can hold string constants. mknxflat -------- @@ -199,25 +192,29 @@ was compiled for. ldnxflat -------- -``ldnxflat`` is use to link your object files along with the *thunk* -file generated by ``mknxflat`` to produce the NXFLAT +``ldnxflat`` converts the relocatable object that contains your object +files and the *thunk* file generated by ``mknxflat`` into the NXFLAT binary module. See below for usage:: - Usage: ldnxflat [options] <bfd-filename> + Usage: ldnxflat -e <entry> -o <output> [-s <stack>] [-v] <elf-file> - Where options are one or more of the following. Note - that a space is always required between the option and - any following arguments. + Convert one ELF object into an NXFLAT module. The + object is what these produce, in this order: - -d Use dynamic symbol table [Default: symtab] - -e <entry-point> - Entry point to module [Default: _start] - -o <out-filename> - Output to <out-filename> [Default: <bfd-filename>.nxf] - -s <stack-size> - Set stack size to <stack-size> [Default: 4096] - -v Verbose output. If -v is applied twice, additional - debug output is enabled [Default: no verbose output]. + ld -r -d -warn-common + mknxflat, assembled and linked in + ld -r -d -warn-common -T gnu-nxflat-gotoff.ld -no-check-sections + + -e <entry> The symbol the loader enters. Needed: + a module has no crt0, so no name for it + is conventional. + -o <output> Where to write it. Needed. + -s <stack> Stack the module is given, in bytes [4096]. + -v Say what was placed; twice, every relocation. + +``-e`` and ``-o`` are required. The in-tree ``ldnxflat`` has no ``-d`` +option, which the older, out-of-tree tool had. It converts ARM objects +only, and refuses an object for another machine. mksymtab -------- @@ -343,10 +340,10 @@ Module ABI marker ----------------- The NXFLAT header carries no version field -- ``h_magic`` is written by -``ldnxflat``, which lives outside this repository and cannot be changed in -step with the loader -- so the module ABI is declared through the import -table instead. Every module built by ``mknxflat`` imports the symbol -``__nxflat_abi_v2``, libc defines it, and the loader refuses a module whose +``ldnxflat``, and modules built by an older ``ldnxflat`` are still in use +-- so the module ABI is declared through the import table instead. Every +module built by ``mknxflat`` imports the symbol ``__nxflat_abi_v2``, libc +defines it, and the loader refuses a module whose import table does not name it. Being in libc, the marker is in every image that can pass ``exec()`` a symbol table: the user image of a protected or kernel build as well as the base firmware. The generation is bumped diff --git a/Documentation/platforms/arm/rp23xx/boards/pimoroni-pico-2-plus/index.rst b/Documentation/platforms/arm/rp23xx/boards/pimoroni-pico-2-plus/index.rst index 5c13ebb50ad..ecc987b7c77 100644 --- a/Documentation/platforms/arm/rp23xx/boards/pimoroni-pico-2-plus/index.rst +++ b/Documentation/platforms/arm/rp23xx/boards/pimoroni-pico-2-plus/index.rst @@ -202,6 +202,6 @@ diagnostic. xipfs-nxflat ------------ -Same as ``xipfs``, plus the NXFLAT execute-in-place demo. Building this -configuration requires ``ldnxflat``, which is not part of a standard -toolchain installation; see :doc:`/os/binfmt/nxflat`. +Same as ``xipfs``, plus the NXFLAT execute-in-place demo. The build makes +the NXFLAT host tools ``mknxflat`` and ``ldnxflat`` itself; see +:doc:`/os/binfmt/nxflat`.
