This is an automated email from the ASF dual-hosted git repository. xiaoxiang781216 pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/nuttx.git
commit a46119d43726b69bb91805af45ec94c5024c95d2 Author: Marco Casaroli <[email protected]> AuthorDate: Tue Oct 20 23:33:23 2026 +0200 Documentation: Say that the arch sets the ELF and module flags. The notes of the elf, posix_spawn, module and sotest examples told the board to set CELFFLAGS, LDELFFLAGS, CMODULEFLAGS and LDMODULEFLAGS with "=", with the entry point main and with linker scripts that do not exist. The arch Toolchain.defs sets these flags. Say that a board can add an option with "+=", and that it must not set them again. Assisted-by: Claude Code:claude-opus-5-5 Signed-off-by: Marco Casaroli <[email protected]> --- Documentation/applications/examples/elf/index.rst | 37 +++++++--------------- .../applications/examples/module/index.rst | 36 ++++++--------------- .../applications/examples/posix_spawn/index.rst | 37 +++++++--------------- .../applications/examples/sotest/index.rst | 36 ++++++--------------- 4 files changed, 42 insertions(+), 104 deletions(-) diff --git a/Documentation/applications/examples/elf/index.rst b/Documentation/applications/examples/elf/index.rst index 1988fd5a8b0..65707789bd4 100644 --- a/Documentation/applications/examples/elf/index.rst +++ b/Documentation/applications/examples/elf/index.rst @@ -27,41 +27,26 @@ Configuration options: **Notes**: -1. ``CFLAGS`` should be provided in ``CELFFLAGS``. RAM and FLASH memory regions may - require long allcs. For ARM, this might be:: - - CELFFLAGS = $(CFLAGS) -mlong-calls - - Similarly for C++ flags which must be provided in ``CXXELFFLAGS``. - -2. Your top-level ``nuttx/Make.defs`` file must also include an appropriate - definition, ``LDELFFLAGS``, to generate a relocatable ELF object. With GNU LD, - this should include ``-r`` and ``-e main`` (or ``_main`` on some platforms).:: - - LDELFFLAGS = -r -e main - - If you use GCC to link, you make also need to include ``-nostdlib``. - -3. ELF size: The ELF files in this example are, be default, quite large because +1. The arch ``Toolchain.defs`` sets ``CELFFLAGS``, ``CXXELFFLAGS`` and + ``LDELFFLAGS``. For example, on ARM they contain ``-mlong-calls``, the entry + point ``_start`` and the linker script ``libs/libc/elf/gnu-elf.ld``. A board + ``scripts/Make.defs`` can add an option with ``+=``, for example + ``LDELFFLAGS += -melf32lriscv``. Do not set these variables again with + ``=``: the board then loses the options that the arch adds for the + configuration, for example ``crt0.o`` and the PIC and FDPIC options. + +2. ELF size: The ELF files in this example are, be default, quite large because they include a lot of build garbage. You can greatly reduce the size of the ELF binaries are using the ``objcopy --strip-unneeded`` command to remove un-necessary information from the ELF files. -4. Simulator. You cannot use this example with the NuttX simulator on Cygwin. +3. Simulator. You cannot use this example with the NuttX simulator on Cygwin. That is because the Cygwin GCC does not generate ELF file but rather some Windows-native binary format. If you really want to do this, you can create a NuttX x86 buildroot toolchain and use that be build the ELF executables for the ROMFS file system. -5. Linker scripts. You might also want to use a linker scripts to combine - sections better. An example linker script is at - ``nuttx/binfmt/elf/gnu-elf.ld``. That example might have to be tuned for - your particular linker output to position additional sections correctly. The - GNU LD ``LDELFFLAGS`` then might be:: - - LDELFFLAGS = -r -e main -T$(TOPDIR)/binfmt/elf/gnu-elf.ld - -6. When generating the ``romfs.img`` for external filesystem the image (``romfs.img``) +4. When generating the ``romfs.img`` for external filesystem the image (``romfs.img``) needs to be manually copied to the start of the configured ``CONFIG_EXAMPLES_ELF_DEVPATH`` using ``openocd`` or your preferred programmer. diff --git a/Documentation/applications/examples/module/index.rst b/Documentation/applications/examples/module/index.rst index e75a3e86580..04115a12a88 100644 --- a/Documentation/applications/examples/module/index.rst +++ b/Documentation/applications/examples/module/index.rst @@ -20,43 +20,27 @@ configuration options: **Notes**: -1. ``CFLAGS`` should be provided in ``CMODULEFLAGS``. RAM and FLASH memory regions - may require long allcs. For ARM, this might be:: - - CMODULEFLAGS = $(CFLAGS) -mlong-calls - - Similarly for C++ flags which must be provided in ``CXXMODULEFLAGS``. - -2. Your top-level ``nuttx/Make.defs`` file must also include an appropriate - definition, LDMODULEFLAGS, to generate a relocatable ELF object. With GNU LD, - this should include ``-r`` and ``-e <entry point>``.:: - - LDMODULEFLAGS = -r -e module_initialize - - If you use GCC to link, you make also need to include ``-nostdlib``. - -3. This example also requires ``genromfs``. ``genromfs`` can be build as part of the +1. The arch ``Toolchain.defs`` sets ``CMODULEFLAGS`` and ``LDMODULEFLAGS``. For + example, on ARM they contain ``-mlong-calls``, ``-r`` and the linker script + ``libs/libc/elf/gnu-elf.ld``. A board ``scripts/Make.defs`` can add an option + with ``+=``, for example ``LDMODULEFLAGS += -melf32lriscv``. Do not set these + variables again with ``=``: the board then loses the options that the arch + adds for the configuration, for example the FDPIC options. + +2. This example also requires ``genromfs``. ``genromfs`` can be build as part of the nuttx toolchain. Or can built from the ``genromfs`` sources that can be found in the NuttX tools repository (``genromfs-0.5.2.tar.gz``). In any event, the PATH variable must include the path to the ``genromfs`` executable. -4. ELF size: The ELF files in this example are, be default, quite large because +3. ELF size: The ELF files in this example are, be default, quite large because they include a lot of build garbage. You can greatly reduce the size of the ELF binaries are using the ``objcopy --strip-unneeded`` command to remove un-necessary information from the ELF files. -5. Simulator. You cannot use this example with the NuttX simulator on Cygwin. +4. Simulator. You cannot use this example with the NuttX simulator on Cygwin. That is because the Cygwin GCC does not generate ELF file but rather some Windows-native binary format. If you really want to do this, you can create a NuttX x86 ``buildroot`` toolchain and use that be build the ELF executables for the ROMFS file system. - -6. Linker scripts. You might also want to use a linker scripts to combine - sections better. An example linker script is at - ``nuttx/libc/elf/gnu-elf.ld``. That example might have to be tuned for your - particular linker output to position additional sections correctly. The GNU - LD ``LDMODULEFLAGS`` then might be:: - - LDMODULEFLAGS = -r -e module_initialize -T$(TOPDIR)/libc/elf/gnu-elf.ld diff --git a/Documentation/applications/examples/posix_spawn/index.rst b/Documentation/applications/examples/posix_spawn/index.rst index f9872edcdbe..e4f83cb3c77 100644 --- a/Documentation/applications/examples/posix_spawn/index.rst +++ b/Documentation/applications/examples/posix_spawn/index.rst @@ -32,42 +32,27 @@ Test-specific configuration options: **Notes**: -1. ``CFLAGS`` should be provided in ``CELFFLAGS``. RAM and FLASH memory regions may - require long allcs. For ARM, this might be:: - - CELFFLAGS = $(CFLAGS) -mlong-calls - - Similarly for C++ flags which must be provided in ``CXXELFFLAGS``. - -2. Your top-level ``nuttx/Make.defs`` file must also include an appropriate - definition, ``LDELFFLAGS``, to generate a relocatable ELF object. With GNU LD, - this should include ``-r`` and ``-e main`` (or ``_main`` on some platforms).:: - - LDELFFLAGS = -r -e main - - If you use GCC to link, you make also need to include ``-nostdlib``. - -3. This example also requires ``genromfs``. ``genromfs`` can be build as part of the +1. The arch ``Toolchain.defs`` sets ``CELFFLAGS``, ``CXXELFFLAGS`` and + ``LDELFFLAGS``. For example, on ARM they contain ``-mlong-calls``, the entry + point ``_start`` and the linker script ``libs/libc/elf/gnu-elf.ld``. A board + ``scripts/Make.defs`` can add an option with ``+=``, for example + ``LDELFFLAGS += -melf32lriscv``. Do not set these variables again with + ``=``: the board then loses the options that the arch adds for the + configuration, for example ``crt0.o`` and the PIC and FDPIC options. + +2. This example also requires ``genromfs``. ``genromfs`` can be build as part of the nuttx toolchain. Or can built from the ``genromfs`` sources that can be found in the NuttX tools repository (``genromfs-0.5.2.tar.gz``). In any event, the ``PATH`` variable must include the path to the ``genromfs`` executable. -4. ELF size: The ELF files in this example are, be default, quite large because +3. ELF size: The ELF files in this example are, be default, quite large because they include a lot of build garbage. You can greatly reduce the size of the ELF binaries are using the ``objcopy --strip-unneeded`` command to remove un-necessary information from the ELF files. -5. Simulator. You cannot use this example with the NuttX simulator on Cygwin. +4. Simulator. You cannot use this example with the NuttX simulator on Cygwin. That is because the Cygwin GCC does not generate ELF file but rather some Windows-native binary format. If you really want to do this, you can create a NuttX x86 buildroot toolchain and use that be build the ELF executables for the ROMFS file system. - -6. Linker scripts. You might also want to use a linker scripts to combine - sections better. An example linker script is at - ``nuttx/binfmt/elf/gnu-elf.ld``. That example might have to be tuned for - your particular linker output to position additional sections correctly. The - GNU LD ``LDELFFLAGS`` then might be:: - - LDELFFLAGS = -r -e main -T$(TOPDIR)/binfmt/elf/gnu-elf.ld diff --git a/Documentation/applications/examples/sotest/index.rst b/Documentation/applications/examples/sotest/index.rst index 1049591d7ab..980f98541d0 100644 --- a/Documentation/applications/examples/sotest/index.rst +++ b/Documentation/applications/examples/sotest/index.rst @@ -19,42 +19,26 @@ system. At run time, the shared library is installed and exercised. Requires **Notes**: -1. ``CFLAGS`` should be provided in ``CMODULEFLAGS``. RAM and FLASH memory regions - may require long allcs. For ARM, this might be:: - - CMODULEFLAGS = $(CFLAGS) -mlong-calls - - Similarly for C++ flags which must be provided in ``CXXMODULEFLAGS``. - -2. Your top-level ``nuttx/Make.defs`` file must also include an appropriate - definition, ``LDMODULEFLAGS``, to generate a relocatable ELF object. With GNU - LD, this should include ``-r`` and ``-e <entry point>``.:: - - LDMODULEFLAGS = -r -e module_initialize - - If you use GCC to link, you make also need to include ``-nostdlib``. - -3. This example also requires ``genromfs``. ``genromfs`` can be built as part of the +1. The arch ``Toolchain.defs`` sets ``CMODULEFLAGS`` and ``LDMODULEFLAGS``. For + example, on ARM they contain ``-mlong-calls``, ``-r`` and the linker script + ``libs/libc/elf/gnu-elf.ld``. A board ``scripts/Make.defs`` can add an option + with ``+=``, for example ``LDMODULEFLAGS += -melf32lriscv``. Do not set these + variables again with ``=``: the board then loses the options that the arch + adds for the configuration, for example the FDPIC options. + +2. This example also requires ``genromfs``. ``genromfs`` can be built as part of the nuttx toolchain. Or can built from the ``genromfs`` sources that can be found in the NuttX tools repository (``genromfs-0.5.2.tar.gz``). In any event, the ``PATH`` variable must include the path to the ``genromfs`` executable. -4. ELF size: The ELF files in this example are, be default, quite large because +3. ELF size: The ELF files in this example are, be default, quite large because they include a lot of build garbage. You can greatly reduce the size of the ELF binaries are using the ``objcopy --strip-unneeded`` command to remove un-necessary information from the ELF files. -5. Simulator. You cannot use this example with the NuttX simulator on Cygwin. +4. Simulator. You cannot use this example with the NuttX simulator on Cygwin. That is because the Cygwin GCC does not generate ELF file but rather some Windows-native binary format. If you really want to do this, you can create a NuttX x86 buildroot toolchain and use that to build the ELF executables for the ROMFS file system. - -6. Linker scripts. You might also want to use a linker script to combine - sections better. An example linker script is at - ``nuttx/libc/elf/gnu-elf.ld``. That example might have to be tuned for your - particular linker output to position additional sections correctly. The GNU - LD ``LDMODULEFLAGS`` then might be:: - - LDMODULEFLAGS = -r -e module_initialize -T$(TOPDIR)/libc/elf/gnu-elf.ld
