diff --git a/Documentation/guides/fully_linked_elf.rst b/Documentation/guides/fully_linked_elf.rst index 69e3d2b715..b00f3df0c4 100644 --- a/Documentation/guides/fully_linked_elf.rst +++ b/Documentation/guides/fully_linked_elf.rst @@ -1,6 +1,11 @@ +=============================== ELF Programs – No Symbol Tables =============================== +.. warning:: + Migrated from: + https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=139629542 + 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 downloaded into on-board SPI FLASH). In order to support such post-release updates, your @@ -13,7 +18,7 @@ Alan Carvalho de Assis has also made a video based on this example in the YouTube `NuttX Channel `_. Creating the Export Package ---------------------------- +=========================== At the time that you release the firmware, you should create and save an export package. The export package is all that you need to create @@ -104,7 +109,7 @@ content of this ZIP file is the following directory structure: `- .config The Add-On Build Directory --------------------------- +========================== In order to create the add-on ELF program, you will need (1) the export package, (2) the program build ``Makefile``, (3) a linker script used by the @@ -121,7 +126,7 @@ package, (2) the program build ``Makefile``, (3) a linker script used by the script (``mkdefines.sh``). Hello Example -------------- +============= To keep things manageable, let's use a concrete example. Suppose the ELF program that we wish to add to the release code is the single source file @@ -142,7 +147,7 @@ Let's say that we have a directory called ``addon`` and it contains the Bash script called ``mkdefines.sh`` that will create a linker script. Building the ELF Program ------------------------- +======================== The first step in creating the ELF program is to unzip the Export Package. We start with our ``addon`` directory containing the following: @@ -173,7 +178,7 @@ the content from the released NuttX code that we need to build the ELF program. The Makefile ------------- +============ The ELF program is created simply as: @@ -261,7 +266,7 @@ Below is the ``Makefile`` used to create the ELF program: rm -f *.o The Linker Script ------------------ +================= Two linker scripts are used. One is a normal file (we'll call it the main linker script), and the other, ``defines.ld``, is created on-the-fly as @@ -335,7 +340,7 @@ The main linker script, ``gnu-elf.ld``, contains the following: } Creating the ``defines.ld`` Linker Script ------------------------------------------ +========================================= The additional linker script ``defines.ld`` is created through a three-step process: @@ -444,7 +449,7 @@ Here is an example ``defines.ld`` created by ``mkdefines.sh``: printf = 0x0800aefc | 0x00000001 ; Replacing an NSH Built-In Function ----------------------------------- +================================== Files can be executed by ``NSH`` from the command line by simply typing the name of the ELF program. This requires: @@ -486,7 +491,7 @@ replaced with the version in the file system: nsh> Version Dependency ------------------- +================== .. note:: @@ -501,7 +506,7 @@ The alternative approach using :doc:`Symbol Tables ` is more or less version independent. 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 diff --git a/Documentation/guides/partially_linked_elf.rst b/Documentation/guides/partially_linked_elf.rst index 507e6e2c63..bade7df974 100644 --- a/Documentation/guides/partially_linked_elf.rst +++ b/Documentation/guides/partially_linked_elf.rst @@ -1,8 +1,13 @@ +================================= 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, @@ -16,7 +21,7 @@ The files shown in this Wiki page can be downloaded `here `_ Creating a Symbol Table ------------------------ +======================= There are several ways to create an application symbol table. Only two are compatible with the example provided here: @@ -75,7 +80,7 @@ compatible with the example provided here: - Include application logic to provide the symbol table. If ``CONFIG_EXAMPLES_NSH_SYMTAB=y`` is set, NSH can handle this automatically. 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 @@ -142,7 +147,7 @@ of this ZIP file are organized as follows: `- .config Add-On Build Directory ------------------------ +====================== In order to create the add-on ELF program, you will need: @@ -155,7 +160,7 @@ that non-GNU toolchains would likely require a significantly different Makefile and linker script. Hello Example -------------- +============= To keep things manageable, let's use a concrete example. Suppose the ELF program that we wish to add to the release code is the simple @@ -180,7 +185,7 @@ Let's say that we have a directory called ``addon`` that contains the following: Building the ELF Program ------------------------- +======================== The first step in creating the ELF program is to unzip the export package. Starting in the ``addon`` directory: @@ -209,7 +214,7 @@ the ELF program. The Makefile ------------- +============ To build the ELF program, simply run: @@ -278,7 +283,7 @@ The Makefile used to create the ELF program is as follows: rm -f *.o The Linker Script ------------------ +================= The linker script that I am using in this example, gnu-elf.ld, contains the following: @@ -349,7 +354,7 @@ contains the following: } 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 @@ -397,7 +402,7 @@ successfully. The built-in version will be ignored. It has been replaced with the version in the file system. 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 diff --git a/Documentation/guides/updating_release_system_elf.rst b/Documentation/guides/updating_release_system_elf.rst index 2b13913e7c..7b83e909d5 100644 --- a/Documentation/guides/updating_release_system_elf.rst +++ b/Documentation/guides/updating_release_system_elf.rst @@ -1,5 +1,10 @@ +=========================================== Updating a Release System with ELF Programs -============================================ +=========================================== + +.. warning:: + Migrated from: + https://cwiki.apache.org/confluence/display/NUTTX/Updating+a+Release+System+with+ELF+Programs You can enhance the functionality of your released embedded system by adding ELF programs, which can be loaded from a file system. These programs can be @@ -9,7 +14,7 @@ easy updates or extensions to the system's firmware. There are two ways you can accomplish this: Partially linked ----------------- +================ This describes building the partially linked, relocatable ELF program that depends on a symbol table provided by the base firmware in FLASH. @@ -17,7 +22,7 @@ Reference: - See :doc:`Partially Linked ELF Programs ` Fully linked ------------- +============ This describes building a fully linked, relocatable ELF program that does not depend on any symbol table information.