Mirrors_Framework/nuttx
1
0
Fork 0
mirror of https://github.com/apache/nuttx.git synced 2026-02-05 19:56:43 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity

docs: Update the ELF guides

Browse Source 
Rewrite parts of the two ELF guides to use scripts included in the
export archive and modernize some deprecated tools and Bash idioms.

Also add the new sphinx_collapse extension to the docs build config.

Signed-off-by: Niccolò Maggioni <nicco.maggioni+nuttx@gmail.com>
This commit is contained in:
Niccolò Maggioni
2025-06-11 02:12:08 +02:00
committed by Xiang Xiao
parent d651726b57
commit 2399702a28
5 changed files with 886 additions and 907 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
Documentation/Pipfile
View File

@@ -17,3 +17,4 @@ pytz = "*"
importlib-metadata = "*"
sphinx-tags = "*"
sphinx-design = "*"
sphinx-collapse = "*"

637
Documentation/Pipfile.lock generated
View File

File diff suppressed because it is too large Load Diff

1
Documentation/conf.py
View File

@@ -61,6 +61,7 @@ extensions = [
"warnings_filter",
"sphinx_tags",
"sphinx_design",
"sphinx_collapse",
]
source_suffix = [".rst", ".md"]

415
Documentation/guides/fully_linked_elf.rst
View File

File diff suppressed because it is too large Load Diff

275
Documentation/guides/partially_linked_elf.rst
View File

@@ -2,13 +2,6 @@
ELF Programs – With Symbol Tables
=================================
.. warning::
Migrated from:
https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=139629543
Updating a Release System with ELF Programs – With Symbol Tables
================================================================
You can easily extend the firmware in your released, embedded system using
ELF programs provided via a file system. For example, an SD card or, perhaps,
downloaded into on-board SPI FLASH.
@@ -17,9 +10,6 @@ In order to support such post-release updates, your released firmware must
support execution of ELF programs loaded into RAM and symbol tables also
provided via the file system (see `apps/examples/elf`).
The files shown in this Wiki page can be downloaded
`here <https://cwiki.apache.org/confluence/download/attachments/139629402/elfprog-wsymtab.tar.gz?version=1&modificationDate=1576735523000&api=v2>`_
Creating a Symbol Table
=======================
@@ -42,7 +32,11 @@ compatible with the example provided here:
To enable this method, you must:
- Set ``CONFIG_EXECFUNCS_HAVE_SYMTAB=y`` in your configuration.
- Provide a symbol table with the global name ``CONFIG_EXECFUNCS_SYMTAB_ARRAY`` with the variable name ``CONFIG_EXECFUNCS_NSYMBOLS_VAR`` that holds the number of symbol entries. The default symbol table name is ``g_symtab``.
- Provide a symbol table with the global name
``CONFIG_EXECFUNCS_SYMTAB_ARRAY`` with the variable name
``CONFIG_EXECFUNCS_NSYMBOLS_VAR`` that holds the number of symbol entries.
The default symbol table name is ``g_symtab``
and its length is ``g_nsymbols``.
In this example, let's illustrate this using an STM32F4-Discovery
configuration. We will assume that you have modified the
@@ -51,22 +45,24 @@ compatible with the example provided here:
.. code-block:: c
#include <stdio.h>
#include <nuttx/binfmt/symtab.h>
#include <nuttx/compiler.h>
#include <nuttx/symtab.h>
const struct symtab_s g_symtab[] = {
{"printf", (FAR void *)printf}
{ "printf", (FAR const void *)printf }
};
int g_nsymbols = 1;
This is a simple symbol table containing only the symbol string "printf,"
This is a simple symbol table containing only the symbol string "printf",
whose value is the address of the function ``printf()``.
There is, of course, a lot more that could be said about generating symbol
tables. NuttX provides specialized tools in the ``tools/`` directory and
instructions elsewhere for generating more extensive symbol tables. However,
this example keeps things simple to focus on the core functionality.
This example keeps things simple in order to focus on the core functionality,
but there is, of course, a lot more that could be said about generating symbol
tables. NuttX provides specialized tools in the ``tools/`` directory for
generating more extensive symbol tables: you can start by taking a look at
``tools/mksymtab.c``. An example invocation of that tool could be:
``./tools/mksymtab -d ./libs/libc/libc.csv <path_to_generated_symtab.c>``.
2. **Application Logic**
Alternatively, the symbol table can be provided dynamically by the
@@ -76,20 +72,23 @@ compatible with the example provided here:
allows for application-level control.
To use this approach, you need to:
- Enable the configurations ``CONFIG_LIB_BOARDCTL=y`` and ``CONFIG_BOARDCTL_APP_SYMTAB=y``.
- Include application logic to provide the symbol table. If ``CONFIG_EXAMPLES_NSH_SYMTAB=y`` is set, NSH can handle this automatically.
- Enable the configurations ``CONFIG_BOARDCTL=y``
and ``CONFIG_BOARDCTL_APP_SYMTAB=y``.
- Include application logic to provide the symbol table.
If ``CONFIG_EXAMPLES_NSH_SYMTAB=y`` is set, NSH can handle this
automatically.
Export Package
==============
Creating the Export Package
===========================
At the time of firmware release, you should create and save an export package.
This export package contains all the necessary files required to create
post-release add-on modules for your embedded system.
For demonstration purposes, we use the STM32F4-Discovery with the network NSH
configuration. This setup assumes that you have the STM32F4DIS-BB baseboard.
The demonstration also requires support for externally modifiable media, such
as:
For demonstration purposes, we'll use the STM32F4-Discovery with the network
NSH configuration. This setup assumes that you have the STM32F4DIS-BB
baseboard. The demonstration also requires support for externally modifiable
media, such as:
- Removable media, like an SD card or USB flash drive.
- An internal file system remotely accessible via USB MSC, FTP, or other
@@ -100,62 +99,70 @@ In this demonstration, the networking NSH configuration uses the SD card on
the STM32 baseboard. Other NSH configurations can also be used, provided they
supply the necessary file system support.
(No baseboard? You can add file system support to the basic ``STM32F4-Discovery``
board by following these instructions:
`USB FLASH drive <https://www.youtube.com/watch?v=5hB5ZXpRoS4>`_
or `SD card <https://www.youtube.com/watch?v=H28t4RbOXqI>`_.)
.. tip::
No baseboard? You can add file system support to the basic STM32F4-Discovery
board by following these instructions: `USB FLASH drive <https://www.youtube.com/watch?v=5hB5ZXpRoS4>`__
or `SD card <https://www.youtube.com/watch?v=H28t4RbOXqI>`__.
Example for STM32F4-Discovery:
Initialize the environment:
.. code-block:: shell
.. code-block:: console
$ make distclean
$ tools/configure.sh -c stm32f4discovery:netnsh
$ make menuconfig
Required configurations:
Edit the configuration:
- Disable networking: ``# CONFIG_NET is not set``
- Enable ELF binary support: ``CONFIG_ELF=y``, ``CONFIG_LIBC_EXECFUNCS=y``,
``CONFIG_EXECFUNCS_HAVE_SYMTAB=y``, ``CONFIG_EXECFUNCS_SYMTAB_ARRAY="g_symtab"`` and
``CONFIG_EXECFUNCS_NSYMBOLS_VAR="g_nsymbols"``
- Enable PATH variable support: ``CONFIG_BINFMT_EXEPATH=y``,
``CONFIG_PATH_INITIAL="/bin"``
- Enable execution from NSH: ``CONFIG_NSH_FILE_APPS=y``
- Disable networking (it is not needed in this example):
``# CONFIG_NET is not set``.
- Enable ELF binary support with external symbol tables:
``CONFIG_ELF=y``,
``CONFIG_LIBC_EXECFUNCS=y``,
``CONFIG_EXECFUNCS_HAVE_SYMTAB=y``,
``CONFIG_EXECFUNCS_SYMTAB_ARRAY="g_symtab"``,
``CONFIG_EXECFUNCS_NSYMBOLS_VAR="g_nsymbols"``.
- Enable PATH variable support:
``CONFIG_LIBC_ENVPATH=y``,
``CONFIG_PATH_INITIAL="/addons"``,
``# CONFIG_DISABLE_ENVIRON not set``.
- Enable execution of ELF files from NSH: ``CONFIG_NSH_FILE_APPS=y``.
Then, build the NuttX firmware image and the export package:
.. code-block:: shell
.. code-block:: console
$ make
$ make export
When ``make export`` completes, you will find a ZIP package in the top-level
NuttX directory called ``nuttx-export-x.y.zip`` (where x.y corresponds to the
version, determined by the .version file in the same directory). The contents
of this ZIP file are organized as follows:
NuttX directory called ``nuttx-export-x.y.zip`` (where ``x.y`` corresponds to
the version determined by the ``.version`` file in the same directory).
The contents of this ZIP file are organized as follows:
.. code-block:: text
nuttx-export-x.x
|- arch/
|- build/
|- include/
|- libs/
|- registry/
|- scripts/
|- startup/
|- tools/
|- System.map
`- .config
Add-On Build Directory
======================
Preparing the Add-On Build Directory
====================================
In order to create the add-on ELF program, you will need:
1. The export package.
2. A program build Makefile.
3. A linker script used by the Makefile.
2. A Makefile to build the program.
3. A linker script to use in the Makefile.
The example Makefile discussed below assumes the use of a GNU toolchain. Note
The example Makefile shown below assumes the use of a GNU toolchain. Note
that non-GNU toolchains would likely require a significantly different
Makefile and linker script.
@@ -172,17 +179,16 @@ source file ``hello.c``:
int main(int argc, char **argv)
{
printf("Hello from Add-On Program!\n");
printf("Hello from a partially linked Add-On Program!\n");
return 0;
}
Let's say that we have a directory called ``addon`` that contains the following:
Let's say that we have a directory called ``addon`` that contains
the following:
1. The ``hello.c`` source file.
2. A Makefile to build the ELF program.
3. A linker script called ``gnu-elf.ld`` needed by the Makefile.
4. The export package ``nuttx-export-7.25.zip``.
3. The export package ``nuttx-export-x.y.zip``.
Building the ELF Program
========================
@@ -190,72 +196,69 @@ Building the ELF Program
The first step in creating the ELF program is to unzip the export
package. Starting in the ``addon`` directory:
.. code-block:: shell
.. code-block:: console
$ cd addon
$ ls
gnu-elf.ld hello.c Makefile nuttx-export-7.25.zip
hello.c Makefile nuttx-export-x.y.zip
Where:
- ``gnu-elf.ld`` is the linker script.
- ``hello.c`` is the example source file.
- ``Makefile`` builds the ELF program.
- ``nuttx-export-7.25.zip`` is the export package from NuttX 7.25.
- ``nuttx-export-x.y.zip`` is the export package from NuttX version ``x.y``.
Unzip the export package as follows:
Unzip the export package and rename the folder for ease of use:
.. code-block:: shell
.. code-block:: console
$ unzip nuttx-export-7.25.zip
$ unzip nuttx-export-x.y.zip
$ mv nuttx-export-x.y nuttx-export
This creates a new directory called ``nuttx-export-7.25``, containing
This creates a new directory called ``nuttx-export``, containing
all the content from the released NuttX code required to build
the ELF program.
The Makefile
============
To build the ELF program, simply run:
.. code-block:: shell
.. code-block:: console
$ make
This uses the following Makefile to generate several files:
- ``hello.o``: The compiled object file for ``hello.c``.
- ``hello``: The linked ELF program.
Only the resulting ``hello`` file is needed.
- ``hello.o``: The compiled object file for ``hello.c``.
- ``hello``: The partially linked ELF program.
The Makefile used to create the ELF program is as follows:
.. code-block:: shell
.. note::
include nuttx-export-7.25/build/Make.defs
When copying the following contents, remember that Makefile indentations
must be made with proper tab characters and not just spaces.
# Long calls are need to call from RAM into FLASH
.. code-block:: makefile
include nuttx-export/scripts/Make.defs
# Long calls are needed to call from RAM into FLASH
ARCHCFLAGS += -mlong-calls
# You may want to check these options against the ones in "nuttx-export/scripts/Make.defs"
ARCHWARNINGS = -Wall -Wstrict-prototypes -Wshadow -Wundef
ARCHOPTIMIZATION = -Os -fno-strict-aliasing -fno-strength-reduce -fomit-frame-pointer
ARCHINCLUDES = -I. -isystem nuttx-export-7.25/include
ARCHINCLUDES = -I. -isystem nuttx-export/include
CFLAGS = $(ARCHCPUFLAGS) $(ARCHCFLAGS) $(ARCHWARNINGS) $(ARCHOPTIMIZATION) $(ARCHINCLUDES) -pipe
CROSSDEV = arm-none-eabi-
CC = $(CROSSDEV)gcc
LD = $(CROSSDEV)ld
STRIP = $(CROSSDEV)strip --strip-unneeded
CFLAGS = $(ARCHCFLAGS) $(ARCHWARNINGS) $(ARCHOPTIMIZATION) $(ARCHCPUFLAGS) $(ARCHINCLUDES) $(ARCHDEFINES) $(EXTRADEFINES)
# Setup up linker command line options
LDELFFLAGS = -r -e main
LDELFFLAGS += -T gnu-elf.ld
# This might change in a different environment
OBJEXT ?= .o
LDELFFLAGS = --relocatable -e main
LDELFFLAGS += -T nuttx-export/scripts/gnu-elf.ld
# This is the generated ELF program
@@ -268,27 +271,33 @@ The Makefile used to create the ELF program is as follows:
# Build targets
all: $(BIN)
.PHONY: clean
all: $(BIN)
$(OBJS): %$(OBJEXT): %.c
$(CC) -c $(CFLAGS) $< -o $@
$(CC) -c $(CFLAGS) -o $@ $<
$(BIN): $(OBJS)
$(LD) $(LDELFFLAGS) -o $@ $^
$(STRIP) $(BIN)
$(STRIP) $@
#$(CROSSDEV)objdump -f $@
clean:
rm -f $(BIN)
rm -f *.o
rm -f $(OBJS)
The Linker Script
=================
The linker script that I am using in this example, gnu-elf.ld,
contains the following:
The linker script used in this example is the one from the exported
NuttX package: ``nuttx-export/scripts/gnu-elf.ld``.
.. code-block:: shell
.. admonition:: Here is an alternative minimal (and possibly outdated) version
.. collapse:: Show content:
.. code-block:: text
SECTIONS
{
@@ -337,8 +346,6 @@ contains the following:
_ebss = . ;
}
/* Stabs debugging sections. */
.stab 0 : { *(.stab) }
.stabstr 0 : { *(.stabstr) }
.stab.excl 0 : { *(.stab.excl) }
@@ -357,49 +364,45 @@ Replacing NSH Built-In Functions
================================
Files can be executed by NSH from the command line by simply typing the name
of the ELF program. This requires (1) that the feature be enabled with
``CONFIG_NSH_FILE_APP=y`` and (2) that support for the PATH variable is
enabled with ``CONFIG_BINFMT_EXEPATH=y`` and ``CONFIG_PATH_INITIAL`` set to
the mount point of the file system that may contain ELF programs.
of the ELF program, given that the following requirements are met:
1. The feature is enabled with ``CONFIG_NSH_FILE_APP=y``.
2. Support for the PATH variable is enabled with ``CONFIG_LIBC_ENVPATH=y``.
3. The mount point of the file system that may contain ELF programs is
set in ``CONFIG_PATH_INITIAL``.
In this example, there is no application in the base firmware called
``hello``. So attempts to run ``hello`` will fail:
.. code-block:: shell
.. code-block:: text
nsh> hello
nsh: hello: command not found
nsh>
But if we mount the SD card containing the ``hello`` image that we created
But if we mount the SD card containing the ``hello`` binary that we created
above, then we can successfully execute the ``hello`` command:
.. code-block:: shell
.. code-block:: text
nsh> mount -t vfat /dev/mmcsd0 /bin
nsh> ls /bin
/bin:
System Volume Information/
nsh> mount -t vfat /dev/mmcsd0 /addons
nsh> ls /addons
/addons:
hello
nsh> hello
Hello from Add-On Program!
Hello from a partially linked Add-On Program!
nsh>
Here we showed how you can add a new command to NSH to a product without
modifying the base firmware. We can also replace or update an existing
built-in application in this way:
In the above configuration, NSH will first attempt to run the program called
``hello`` from the file system. This will fail because we have not yet put
our custom ``hello`` ELF program in the file system. So instead, NSH will
fallback and execute the built-in application called ``hello``. In this way,
This showed that you can add a new NSH command to a product without
modifying the base firmware, but you can also replace or update an existing
built-in application: in the above configuration, NSH will first attempt to
run the program called ``hello`` from the file system; this will fail because
the custom ``hello`` ELF program is not yet available. So instead, NSH will
fallback and execute the built-in application called ``hello``. This way,
any command known to NSH can be replaced from an ELF program installed in a
mounted file system directory that can be found via the PATH variable.
After we do add our custom ``hello`` to the file system, when NSH attempts to
run the program called ``hello`` from the file system it will run
successfully. The built-in version will be ignored. It has been replaced with
the version in the file system.
mounted file system directory specified in the PATH environment variable:
after adding the custom ``hello`` binary to the file system, NSH will prefer it
over the built-in version when attempting to run the program called ``hello``.
Tightly Coupled Memories
========================
@@ -407,28 +410,22 @@ Tightly Coupled Memories
Most MCUs based on ARMv7-M family processors support some kind of Tightly
Coupled Memory (TCM). These TCMs have somewhat different properties for
specialized operations. Depending on the bus matrix of the processor, you
may not be able to execute programs from the TCM. For instance, the STM32 F4
supports Core Coupled Memory (CCM), but since it is tied directly to the
D-bus, it cannot be used to execute programs! On the other hand, the STM32F3
may not be able to execute programs from the TCM. For instance, the STM32F4
supports Core Coupled Memory (CCM) but, since it is tied directly to the
D-bus, it cannot be used to execute programs. On the other hand, the STM32F3
has a CCM that is accessible to both the D-Bus and the I-Bus, in which case
it should be possible to execute programs from this TCM.
it should be possible to execute programs directly from this TCM.
.. image:: ./image/system_arch_stm32f42xx_and_f43xx.png
.. image:: ./image/system_arch_stm32f303xBC_and_f358xC.png
When ELF programs are loaded into memory, the memory is allocated from the
heap via a standard memory allocator. By default with the STM32 F4, the CCM
is included in the heap and will typically be allocated first. If CCM memory
is allocated to hold the ELF program in memory, then a hard-fault will occur
immediately when you try to execute the ELF program in memory.
Therefore, it is necessary on STM32 F4 platforms to include the following
configuration setting:
.. code-block:: shell
CONFIG_STM32_CCMEXCLUDE=y
With that setting, the CCM memory will be excluded from the heap and so will
never be allocated for ELF program memory.
When ELF programs are loaded into memory, such memory is allocated from the
heap via a standard memory allocator. With the STM32F4, the CCM is included
in the heap by default and will typically be allocated first. If CCM memory
is allocated to hold the loaded ELF program, then a hard-fault will occur
immediately when you try to execute it.
Therefore, on STM32F4 platforms it is necessary to include the
``CONFIG_STM32_CCMEXCLUDE=y`` configuration setting. With it, the CCM
memory will be excluded from the heap and will never be allocated for
ELF program memory.