tools/fdpic: Add the module build helpers the demo apps use.

apps/examples/fdpicxip is in apps master and its modules/Makefile reads

  FDPICDIR  = $(NUTTX_DIR)/tools/fdpic
  MODULE_MK = $(FDPICDIR)/nuttx-fdpic.mk
  EMBED     = $(FDPICDIR)/fdpic-embed.py

which is not in this tree, so the committed module blobs cannot be
regenerated.  This adds what that Makefile names.

nuttx-fdpic.mk builds a module: compile with the stock arm-none-eabi GCC,
which emits correct FDPIC objects for C and C++, then assemble and link
with an arm-uclinuxfdpiceabi binutils, which is the only piece a
distribution does not carry.  build-binutils.sh builds that, and takes
about a minute.

nuttx-exports.sh turns a built firmware's exec_symtab.c into a symbol
list, fdpic-verify.sh checks a module's imports against it, and
fdpic-embed.py turns a module into a C header for an image that carries
one inside it.

crt0.c is the module's own start-up file, the counterpart of
arch/<arch>/src/common/crt0.c for a module the in-tree build produces.  It
walks .init_array and then calls main, so a C++ global object is constructed
on the task that runs the module, in that task's group and with that task's
data base, rather than on whichever task called the loader.  That is why
ENTRY is _start rather than main.  It does not register the destructors:
-fno-use-cxa-atexit puts them in .fini_array, which the loader walks on
unload, and registering them here would run each one twice.  A shared
library is never entered, so ENTRY = 0 leaves crt0 out of the link and its
constructors come from dlopen().

init-array.ld goes with crt0.  The linker names the bounds of .init_array
when it links an executable and not when it links a shared object, because a
shared object is expected to be constructed by whoever loaded it.  Reading
DT_INIT_ARRAY out of _DYNAMIC instead is not an answer: the addresses there
are link-time ones, and an FDPIC object cannot translate them, since its two
segments move independently and only the loader knows by how much.  The
fragment uses INSERT, so the built-in script still applies.

build-binutils.sh passes MAKEINFO=true.  binutils builds its info pages by
default, and a host without makeinfo, which macOS is, fails on doc/bfd.info
after everything that matters has been built.

The tools are host side and nothing in the NuttX build calls them.  The
loader that runs what they build is proposed separately, so a module built
here has nothing to load it yet, and the page says so.

Documentation/components/tools/fdpic.rst describes them, under Host Tools,
where the tools index picks it up by glob.

Assisted-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Signed-off-by: Marco Casaroli <marco.casaroli@gmail.com>

Author: casaroli

Documentation/components/tools/fdpic.rst

@@ -0,0 +1,111 @@
+=====================================
+fdpic: FDPIC module build tooling
+=====================================
+
+``tools/fdpic`` is everything needed to build an FDPIC module out of tree.  A
+module is an ELF shared object whose read-only segment the target maps straight
+out of flash and executes in place, while its writable segment is copied to RAM
+once per running instance.  It links against nothing: libc and everything else
+are imported from the firmware's exported symbol table at load time.
+
+These are host tools only.  ``apps/examples/fdpicxip`` uses them to rebuild its
+committed module blobs, which is what they are in the tree for.  The loader that
+runs such a module is proposed separately; until it is in, a module built here
+has nothing in NuttX to load it.
+
+Contents
+========
+
+============================ ==================================================
+File                         Purpose
+============================ ==================================================
+``nuttx-fdpic.mk``           The module build itself; include it from a
+                             two-line makefile
+``fdpic-verify.sh``          Checks a built module's imports resolve against
+                             the firmware
+``nuttx-exports.sh``         Turns ``libs/libc/exec_symtab.c`` into a symbol
+                             list
+``fdpic-embed.py``           Turns a built module into a C header, for carrying
+                             one inside an image
+``build-binutils.sh``        Builds the ``arm-uclinuxfdpiceabi`` binutils, the
+                             one from-source dependency
+``crt0.c``                   The module start-up file, linked into every
+                             module that is entered
+``init-array.ld``            Names the bounds of ``.init_array`` for it
+============================ ==================================================
+
+Building a module
+=================
+
+A whole module is three lines of makefile beside the source.  Taking
+``apps/examples/fdpicxip/modules/qsorter.c``, which is a module in its own
+right, as the source:
+
+.. code:: makefile
+
+   MODULE = qsorter
+   SRCS   = qsorter.c
+
+   include /path/to/nuttx/tools/fdpic/nuttx-fdpic.mk
+
+Then:
+
+.. code:: console
+
+   $ make NUTTX_DIR=/path/to/nuttx
+     CC   crt0.c
+     CC   qsorter.c
+     LD   qsorter.fdpic
+   OK    qsorter.fdpic: FDPIC, entry 0x2a1, 4 imports resolved
+
+``NUTTX_DIR`` has to be a configured, built tree: the compile needs its headers
+and the verify step needs the export table generated into
+``libs/libc/exec_symtab.c``.
+
+Toolchain
+=========
+
+Two toolchains are involved.  The stock ``arm-none-eabi`` compiler does the
+compiling -- it emits perfectly good FDPIC objects for both C and C++ -- and
+``arm-uclinuxfdpiceabi`` **binutils** does the linking, because
+``arm-none-eabi-ld`` cannot produce an FDPIC object at all.  So the
+from-source dependency is binutils alone, which ``build-binutils.sh`` builds in
+about a minute.
+
+Verification runs as part of the default target on purpose: a module that
+imports a symbol the firmware does not export links perfectly happily and fails
+only once it is on the target, as a bare ``-ENOENT`` that names nothing.
+
+Start-up file
+=============
+
+``crt0.c`` is the entry point of a module, the counterpart of
+``arch/<arch>/src/common/crt0.c`` for a module the in-tree build produces.  It
+walks ``.init_array`` and then calls ``main``, so a C++ global object is
+constructed on the task that runs the module, in that task's group and with
+that task's data base, rather than on whichever task called the loader.  It is
+why ``ENTRY`` defaults to ``_start`` rather than ``main``.
+
+It does not register the destructors.  ``-fno-use-cxa-atexit`` puts them in
+``.fini_array``, which the loader walks when the module is unloaded, so
+registering them here would run each one twice.
+
+A shared library is never entered, so ``ENTRY = 0`` leaves ``crt0.c`` out of
+the link.  Its constructors run from ``dlopen()`` instead.
+
+``init-array.ld`` goes with it.  The linker names the bounds of
+``.init_array`` when it links an executable and not when it links a shared
+object, because a shared object is expected to be constructed by whoever
+loaded it.  Reading ``DT_INIT_ARRAY`` out of ``_DYNAMIC`` instead is not an
+answer: the addresses there are link-time ones, and an FDPIC object cannot
+translate them, since its two segments move independently and only the
+loader knows by how much.  The fragment uses ``INSERT``, so the linker's
+built-in script still applies.
+
+Modules carried inside an image
+===============================
+
+``fdpic-embed.py`` exists for applications that have to load a module before
+there is any way to put files on the target, so they embed one and write it out
+at run time.  ``apps/examples/fdpicxip/modules/`` uses it that way, and is the
+worked example of driving this tooling for several modules at once.

tools/fdpic/build-binutils.sh

@@ -0,0 +1,84 @@
+#!/bin/bash
+############################################################################
+# tools/fdpic/build-binutils.sh
+#
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.  The
+# ASF licenses this file to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance with the
+# License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
+# License for the specific language governing permissions and limitations
+# under the License.
+#
+############################################################################
+
+# Build arm-uclinuxfdpiceabi binutils -- the only part of the module
+# toolchain that has to be built from source.
+#
+# The compiling is done by the stock Arm bare-metal toolchain, which emits
+# correct FDPIC objects for both C and C++.  What it cannot do is *link*
+# them: arm-none-eabi-ld is configured with the `armelf` emulation alone, so
+# it produces an object marked "UNIX - System V" that the loader refuses.
+# The FDPIC linker carries armelf_linux_fdpiceabi, and that is the whole of
+# the gap.
+#
+# So this builds binutils and nothing else: about a minute, roughly 23 MB.
+# An FDPIC GCC is not needed for any of this.
+#
+# Usage: build-binutils.sh <workdir> [install-prefix]
+#
+# Then add <install-prefix>/bin to PATH.
+
+set -e
+
+WORK="${1:?usage: build-binutils.sh <workdir> [prefix]}"
+PREFIX="${2:-$WORK/toolchain}"
+TARGET=arm-uclinuxfdpiceabi
+BINUTILS=binutils-2.43
+J="$(getconf _NPROCESSORS_ONLN 2>/dev/null || echo 4)"
+
+mkdir -p "$WORK/src" "$WORK/build"
+
+cd "$WORK/src"
+[ -d "$BINUTILS" ] || {
+    curl -fL -O "https://ftp.gnu.org/gnu/binutils/$BINUTILS.tar.xz"
+    tar xf "$BINUTILS.tar.xz"
+}
+
+rm -rf "$WORK/build/binutils"
+mkdir -p "$WORK/build/binutils"
+cd "$WORK/build/binutils"
+
+# --with-system-zlib because the bundled copy does not compile against the
+# macOS SDK headers.  Harmless elsewhere.
+
+"$WORK/src/$BINUTILS/configure" \
+    --target="$TARGET" \
+    --prefix="$PREFIX" \
+    --disable-nls \
+    --disable-werror \
+    --with-system-zlib
+
+# MAKEINFO=true because binutils builds its info pages by default and a
+# host without makeinfo, which macOS is, fails the build on doc/bfd.info
+# after everything that matters has already been built.
+
+make -j"$J" MAKEINFO=true
+make install MAKEINFO=true
+
+echo
+echo "Installed to $PREFIX/bin"
+echo
+"$PREFIX/bin/$TARGET-ld" -V | head -8
+echo
+echo "armelf_linux_fdpiceabi in the list above is the one that matters."
+echo "Add to PATH:  export PATH=$PREFIX/bin:\$PATH"

tools/fdpic/crt0.c

@@ -0,0 +1,126 @@
+/****************************************************************************
+ * tools/fdpic/crt0.c
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.  The
+ * ASF licenses this file to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance with the
+ * License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
+ * License for the specific language governing permissions and limitations
+ * under the License.
+ *
+ ****************************************************************************/
+
+/* The start-up file of an FDPIC module, the counterpart of
+ * arch/<arch>/src/common/crt0.c for a module that the in-tree build
+ * produces.  A module that exec() runs is entered here rather than at main,
+ * so that its constructors run on the task that runs the module, in that
+ * task's group and with that task's data base, rather than on whichever
+ * task happened to call the loader.
+ *
+ * Destructors are not registered here.  -fno-use-cxa-atexit puts them in
+ * .fini_array, which the loader walks in libelf_uninit() when the module is
+ * unloaded, and registering them again would run each one twice.
+ *
+ * A shared library is not entered at all, so it does not link this file.
+ * Its constructors run from libelf_insert() when dlopen() maps it.
+ */
+
+/****************************************************************************
+ * Included Files
+ ****************************************************************************/
+
+#include <stdint.h>
+
+/****************************************************************************
+ * Public Function Prototypes
+ ****************************************************************************/
+
+int main(int argc, char *argv[]);
+void exit(int status);
+
+/****************************************************************************
+ * Private Data
+ ****************************************************************************/
+
+/* init-array.ld defines these around .init_array.  The linker's built-in
+ * script does not, when it links a shared object.
+ *
+ * They are declared hidden so that the compiler reaches them through the
+ * GOT of this object rather than through a dynamic symbol, which is what
+ * lets the loader resolve them with an ordinary R_ARM_RELATIVE.
+ *
+ * Each entry is a code address rather than a function descriptor: the
+ * linker resolves .init_array with R_ARM_RELATIVE too, not with
+ * R_ARM_FUNCDESC_VALUE.
+ */
+
+extern uintptr_t __init_array_start[] __attribute__((visibility("hidden")));
+extern uintptr_t __init_array_end[] __attribute__((visibility("hidden")));
+
+/****************************************************************************
+ * Private Functions
+ ****************************************************************************/
+
+/****************************************************************************
+ * Name: call_initializer
+ *
+ * Description:
+ *   Enter one .init_array entry.  A plain call through a function pointer
+ *   cannot be used: under -mfdpic the compiler would take the entry for a
+ *   function descriptor and load a data base out of the code address.  The
+ *   data base is right already, because this runs inside the module.
+ *
+ ****************************************************************************/
+
+static void call_initializer(uintptr_t entry)
+{
+  __asm__ __volatile__
+  (
+    "blx %[entry]\n"
+    :
+    : [entry] "r" (entry)
+    : "r0", "r1", "r2", "r3", "r12", "lr", "cc", "memory"
+  );
+}
+
+/****************************************************************************
+ * Public Functions
+ ****************************************************************************/
+
+/****************************************************************************
+ * Name: _start
+ *
+ * Description:
+ *   The entry point of a module.  Runs the constructors, calls main and
+ *   passes its return value to exit().
+ *
+ * Input Parameters:
+ *   argc - The number of parameters being passed.
+ *   argv - The parameters being passed.
+ *
+ * Returned Value:
+ *   Does not return.
+ *
+ ****************************************************************************/
+
+void _start(int argc, char *argv[])
+{
+  uintptr_t *entry;
+
+  for (entry = __init_array_start; entry != __init_array_end; entry++)
+    {
+      call_initializer(*entry);
+    }
+
+  exit(main(argc, argv));
+}