Aksal/nuttx
3
1
Fork 1
mirror of https://github.com/apache/nuttx.git synced 2026-08-27 20:30:38 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 2
nuttx/Documentation/components/filesystem/nxflat.rst
Marco Casaroli abbe0df26d !arch/arm: Use r9 as the PIC base register. 
ARM PIC has used r10 as the base register, but the tree has never been
consistent about it.  Toolchain.defs gives CONFIG_BUILD_PIC
-mpic-register=r9 and CONFIG_PIC -mpic-register=r10, twenty-five lines
apart, and arm_initialstate.c sets REG_R9 from inline assembly under one
and REG_PIC under the other, with a comment reading "Set the PIC base
register (probably R10)".  This settles it on r9 for all of PIC: NXFLAT,
ELF PIC and CONFIG_BUILD_PIC alike.

r9 is the right choice rather than an arbitrary one.  It is the AAPCS
platform register, the "static base", and it is what GCC itself picks
for -msingle-pic-base on an EABI target; r10 is the non-EABI default.

It also removes a combination that cannot build today.  Stack checking
adds -ffixed-r10 in armv7-m/Toolchain.defs and armv8-m/Toolchain.defs,
while CONFIG_PIC adds -mpic-register=r10, and GCC rejects the pair with
"unable to use 'r10' for PIC register".  The comment above REG_PIC has
always said the register "can be R9 if stack checking is enabled", but
the definition was unconditionally REG_R10, so it would have named the
wrong register even had the build succeeded.

The thunk generator moves with the firmware.  NXFLAT import stubs had
the register baked in as "add ip,ip,sl", so a module built for r9 would
load and then branch to a wild address on its first call out.  The stubs
now come from NXFLAT_PIC_REG in the in-tree tool, which is built only
when CONFIG_NXFLAT is set, following the
CONFIG_BOARD_ETC_ROMFS_PASSWD_ENABLE precedent in tools/Unix.mk.

That leaves modules built before this change, and they are the reason
for the ABI marker.  The NXFLAT header cannot carry a version: h_magic
is written by ldnxflat, which is GPL, derived from elf2flt, and stays
out of this repository, so it can never be changed in step with the
loader.  The import table can, because both of its ends are in-tree --
mknxflat emits it and nxflat_bindimports() reads it -- and ldnxflat
passes it through untouched.  So every module now imports
__nxflat_abi_v2, the base firmware defines it, and a module that does
not import it is refused.

Making the marker a real exported symbol rather than a name the loader
special-cases is what keeps it out of the build system's way: a board's
symbol table picks it up exactly as it picks up printf, so mksymtab.sh
and its equivalents need no change.  It also gives the reverse direction
a diagnosis for free -- a module built against a newer ABI than its
firmware fails with "Exported symbol __nxflat_abi_v2 not found".

Most of the remaining churn is boards restating a default.  ARCHPICFLAGS
is a "?=" default so that a board only speaks up when it differs, and
twenty-six were assigning the value the default already had.  MKNXFLAT
gets the same treatment: thirteen boards named the same tool, and the
only thing that varies is ARM versus Thumb-2, which falls out of
CONFIG_ARM_THUMB.  LDNXFLAT gains a default too -- it stays an
out-of-tree PATH lookup, but naming it centrally fixes boards that never
assigned it, where it expanded to nothing and handed make a recipe
beginning "-e", whose leading dash make ate as "ignore errors".

The non-ARM boards carrying -mpic-register=r10 lose it: it is an
ARM-only option, reachable only through CPICFLAGS, which is only used to
build NXFLAT modules, and no non-ARM board enables NXFLAT.

Boards keep nothing about PIC flags any more.  ARCHPICFLAGS was set by
sixty-three of them and only ever fed CPICFLAGS, which is only used to
build NXFLAT modules; no board outside arch/arm enables NXFLAT, so every
non-ARM copy was setting a variable nothing read.  Those are removed
rather than moved somewhere more central, which would only make dead
text look load-bearing.  LDNXFLAT goes the same way as MKNXFLAT, for the
same reason: thirteen boards named the same tool that Toolchain.defs now
names once.

One of them was not merely redundant.  am67/t3-gem-o1 asked for
"-mpic-register=r10 -ffixed-r10", which GCC refuses outright with
"unable to use 'r10' for PIC register" -- the very combination the
filter-out machinery in Toolchain.defs exists to prevent.  It has
survived because that board does not build NXFLAT modules, so the flags
are never handed to a compiler.  Renaming the register would have
carried the fault forward unchanged, so the line goes.

Tested on lm3s6965-ek:qemu-nxflat under QEMU, configured and built with
no overrides.  The nxflat example runs the errno, hello and struct
modules with output identical to the same config built from master.
Built with the old out-of-tree thunk generator instead, the same
firmware refuses all three with ENOEXEC rather than locking up in a
HardFault, which is what this change is for.  mps3-an547:picostest,
which is CONFIG_PIC without CONFIG_NXFLAT, builds clean and does not
build the thunk generator.

The .def files pick up two cosmetic changes here alongside the register:
a "Dyanamic" typo that codespell rejects, and a reworded comment in each
thunk_*.c.  Neither appears in the emitted thunk -- both are in C
comments -- so the generated text is still what the upstream tool
produces, modulo the register itself.

BREAKING CHANGE: ARM PIC moves from r10 to r9.  An NXFLAT module built
before this change has r10 baked into its import stubs and will not run
against a firmware carrying it; the two cannot be mixed.  The module is
refused with ENOEXEC rather than branching to a wild address, by way of the
__nxflat_abi_v2 marker described below.

Quick fix: rebuild the module against this tree.  Its source needs no
change.  A board that reserved r10 by hand, or that assigned ARCHPICFLAGS
or MKNXFLAT to restate a default, should drop those assignments; nothing
else is affected, and CONFIG_PIC without CONFIG_NXFLAT needs no action.

Assisted-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Signed-off-by: Marco Casaroli <marco.casaroli@gmail.com>
2026-08-06 01:38:23 +08:00

180 lines
No EOL
6.4 KiB
ReStructuredText
Raw Blame History

=================================
NuttX FLAT Binary Format (NXFLAT)
=================================
.. warning::
Migrated from:
https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=139630111
Overview
========
NuttX supports a configurable :doc:`binary loader <../binfmt>` .
This binary loader supports loading and executing binary objects from
the file system.
The NuttX binary loader is capable of supporting multiple binary formats.
One of of those binary formats is NXFLAT, the top of this Wiki page.
NXFLAT is a customized and simplified version of binary format
implemented a few years ago called XFLAT.
With the NXFLAT binary format you will be able to do the following:
* Place separately linked programs in a file system, and
* Execute those programs by dynamically linking them to the
base NuttX code.
This allows you to extend the NuttX base code after it has been
written into FLASH.
One motivation for implementing NXFLAT is support clean CGI under
an HTTPD server.
This feature is especially attractive when combined with the
NuttX ROMFS support:
ROMFS allows you to execute programs in place (XIP) in flash
without copying anything other than the .data section to RAM.
In fact, the initial NXFLAT release only worked on ROMFS.
Later extensions also support execution NXFLAT binaries from
an SRAM copy as well.
This NuttX feature includes:
* A dynamic loader that is built into the NuttX core (See SVN).
* Minor changes to RTOS to support position independent code, and
* A linker to bind ELF binaries to produce the
NXFLAT binary format (See SVN).
Toolchain Compatibility Problem
===============================
Description
-----------
NXFLAT flat requires a specific kind of position independence.
The ARM family of GCC toolchains has historically supported
this method of position independence: All code addresses are
accessed relative to the Program Counter (PC) and a special,
`PIC register` (usually ``r10``) is used to access all data. To
load or store a data value, the contents of ``r10``, the PIC
base, is added to a constant, position-independent offset
to produce the absolute address of the data.
.. image:: nxflat/nxflat-addressing.png
The `Global Offset Table` (GOT) is a special data structure that
resides in D-Space. So PIC-base relative addressing may also
be specified as GOT-Relative addressing (or ``GOTOFF``). The older
GCC 4.3.3 GCC compiler, for example, generates ``GOTOFF``
relocations to the constant strings, like:
.. code-block:: asm
.L3:
.word .LC0(GOTOFF)
.word .LC1(GOTOFF)
.word .LC2(GOTOFF)
.word .LC3(GOTOFF)
.word .LC4(GOTOFF)
Where ``.LC0``, ``.LC1``, ``.LC2``, ``.LC3``, and ``.LC4`` are the labels
corresponding to strings in the ``.rodata.str1.1`` section. One
consequence of this is that ``.rodata`` must reside in D-Space
since it will addressed relative to the GOT (see the section
entitled "Read-Only Data in RAM" here).
The newer 4.6.3 GCC compiler, however, generated PC relative
relocations to these same strings:
.. code-block::
.L2:
.word .LC0-(.LPIC0+4)
.word .LC1-(.LPIC1+4)
.word .LC2-(.LPIC2+4)
.word .LC3-(.LPIC4+4)
.word .LC4-(.LPIC5+4)
These are `PC-Relative` relocations. This means that the string
data is address not by an offset relative to the PIC register
(``r10``) but to the program count (PC). This is good and bad. This
is good because it means that ``.rodata.str1.1`` must now can now
reside in FLASH with ``.text`` and can be accessed using PC-relative
addressing. That can be accomplished by simply moving the ``.rodata``
from the ``.data`` section to the ``.text`` section in the linker script.
The NXFLAT linker script is located at
``nuttx/binfmt/libnxflat/gnu-nxflat-?.ld``. **NOTE**: There are two
linker scripts located at ``nuttx/binfmt/libnxflat/``:
1. ``binfmt/libnxflat/gnu-nxflat-gotoff.ld.`` Older versions
of GCC (at least up to GCC 4.3.3), use GOT-relative
addressing to access RO data. In that case, read-only
data (``.rodata``) must reside in D-Space and this linker
script should be used.
2. ``binfmt/libnxflat/gnu-nxflat-pcrel.ld.`` Newer versions
of GCC (at least as of GCC 4.6.3), use PC-relative
addressing to access RO data. In that case, read-only
data (``.rodata``) must reside in I-Space and this linker
script should be used.
But this is very bad because a lot of NXFLAT is now broken.
For it appears that not just constant strings, but that all
data may now be referenced using PC-relative addressing to
.bss and .data values. I do not yet know the extent of this
problem or the direction that GCC is going but certainly
version 4.6.3 cannot be used with NXFLAT.
The workaround for now is to use the older, 4.3.3 OABI
compiler. In the long run, this might spell the end
to NXFLAT.
Update: Restored GCC Support
----------------------------
This post was pointed out by Michael Jung:
.. code-block:: bash
MCU: STM32F4 (ARM Cortex M4)
Build environment: arm-none-eabi-gcc 4.8.4 20140725
My goal is to build an image that can be run from any properly-aligned
offset in internal flash (i.e., position-independent). I found the
following set of gcc flags that achieves this goal:
# Generate position independent code.
-fPIC
# Access bss via the GOT.
-mno-pic-data-is-text-relative
# GOT is not PC-relative; store GOT location in a register.
-msingle-pic-base
# Store GOT location in r9.
-mpic-register=r9
Reference: https://gcc.gnu.org/ml/gcc-help/2015-07/msg00027.html
Michael has verified that ``-mno-pic-data-is-text-relative`` is,
indeed, a solution to the above NXFLAT problem in newer
compilers. You simply need to modify the board Make.defs
file like:
1. ARCHPICFLAGS = -fpic -msingle-pic-base -mpic-register=r9
.. code-block:: bash
+ARCHPICFLAGS = -fpic -msingle-pic-base -mpic-register=r9 -mno-pic-data-is-text-relative
NuttX uses ``r9`` as the PIC base register in all configurations,
which matches the register named in the post above.
See this `thread <https://groups.google.com/forum/>`_ for additional information.
References
----------
* :doc:`NXFLAT <../nxflat>`
* `XFLATFLAT <http://xflat.sourceforge.net/>`_
* `FLAT <http://retired.beyondlogic.org/uClinux/bflt.htm>`_
* `ROMFS <http://romfs.sourceforge.net/>`_
Reference in a new issue View git blame Copy permalink