nuttx/nuttx-mirror
1
2
Fork 0
mirror of https://github.com/apache/nuttx.git synced 2025-01-12 22:08:35 +08:00
Code Issues Projects Releases Packages Wiki Activity Actions

Doc: add migration warning to updating release system and elf programs
Some checks are pending
Build Documentation / build-html (push) Waiting to run
Details

Browse source 
Add a migration warning to the update release system and the elf
programs documentation pages. This is just to add a papertrail from
where the documentation originate in case of error during the migration
process. Also fix a bit of formatting in the pages
This commit is contained in:
Ludovic Vanasse 2024-12-29 09:25:32 -05:00 committed by archer
parent 04c7391162
commit b02a0758a7
3 changed files with 38 additions and 23 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

25
Documentation/guides/fully_linked_elf.rst
View file

@ -1,6 +1,11 @@
===============================
ELF Programs – No Symbol Tables 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 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 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 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 <https://www.youtube.com/watch?v=oL6KAgkTb8M>`_. YouTube `NuttX Channel <https://www.youtube.com/watch?v=oL6KAgkTb8M>`_.
Creating the Export Package Creating the Export Package
--------------------------- ===========================
At the time that you release the firmware, you should create and save an 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 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 `- .config
The Add-On Build Directory The Add-On Build Directory
-------------------------- ==========================
In order to create the add-on ELF program, you will need (1) the export 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 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``). script (``mkdefines.sh``).
Hello Example Hello Example
------------- =============
To keep things manageable, let's use a concrete example. Suppose the ELF 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 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. Bash script called ``mkdefines.sh`` that will create a linker script.
Building the ELF Program Building the ELF Program
------------------------ ========================
The first step in creating the ELF program is to unzip the Export Package. We The first step in creating the ELF program is to unzip the Export Package. We
start with our ``addon`` directory containing the following: 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. program.
The Makefile The Makefile
------------ ============
The ELF program is created simply as: The ELF program is created simply as:
@ -261,7 +266,7 @@ Below is the ``Makefile`` used to create the ELF program:
rm -f *.o rm -f *.o
The Linker Script The Linker Script
----------------- =================
Two linker scripts are used. One is a normal file (we'll call it the main 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 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 Creating the ``defines.ld`` Linker Script
----------------------------------------- =========================================
The additional linker script ``defines.ld`` is created through a three-step The additional linker script ``defines.ld`` is created through a three-step
process: process:
@ -444,7 +449,7 @@ Here is an example ``defines.ld`` created by ``mkdefines.sh``:
printf = 0x0800aefc | 0x00000001 ; printf = 0x0800aefc | 0x00000001 ;
Replacing an NSH Built-In Function Replacing an NSH Built-In Function
---------------------------------- ==================================
Files can be executed by ``NSH`` from the command line by simply typing the Files can be executed by ``NSH`` from the command line by simply typing the
name of the ELF program. This requires: name of the ELF program. This requires:
@ -486,7 +491,7 @@ replaced with the version in the file system:
nsh> nsh>
Version Dependency Version Dependency
------------------ ==================
.. note:: .. note::
@ -501,7 +506,7 @@ The alternative approach using :doc:`Symbol Tables <fully_linked_elf>` is more
or less version independent. or less version independent.
Tightly Coupled Memories Tightly Coupled Memories
------------------------ ========================
Most MCUs based on ARMv7-M family processors support some kind of Tightly Most MCUs based on ARMv7-M family processors support some kind of Tightly
Coupled Memory (TCM). These TCMs have somewhat different properties for Coupled Memory (TCM). These TCMs have somewhat different properties for

25
Documentation/guides/partially_linked_elf.rst
View file

@ -1,8 +1,13 @@
=================================
ELF Programs – With Symbol Tables 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 Updating a Release System with ELF Programs – With Symbol Tables
----------------------------------------------------------------- ================================================================
You can easily extend the firmware in your released, embedded system using 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, 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 <https://cwiki.apache.org/confluence/download/attachments/139629402/elfprog-wsymtab.tar.gz?version=1&modificationDate=1576735523000&api=v2>`_ `here <https://cwiki.apache.org/confluence/download/attachments/139629402/elfprog-wsymtab.tar.gz?version=1&modificationDate=1576735523000&api=v2>`_
Creating a Symbol Table Creating a Symbol Table
----------------------- =======================
There are several ways to create an application symbol table. Only two are There are several ways to create an application symbol table. Only two are
compatible with the example provided here: 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. - Include application logic to provide the symbol table. If ``CONFIG_EXAMPLES_NSH_SYMTAB=y`` is set, NSH can handle this automatically.
Export Package Export Package
-------------- ==============
At the time of firmware release, you should create and save an 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 This export package contains all the necessary files required to create
@ -142,7 +147,7 @@ of this ZIP file are organized as follows:
`- .config `- .config
Add-On Build Directory Add-On Build Directory
----------------------- ======================
In order to create the add-on ELF program, you will need: 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. Makefile and linker script.
Hello Example Hello Example
------------- =============
To keep things manageable, let's use a concrete example. Suppose the ELF 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 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 Building the ELF Program
------------------------ ========================
The first step in creating the ELF program is to unzip the export The first step in creating the ELF program is to unzip the export
package. Starting in the ``addon`` directory: package. Starting in the ``addon`` directory:
@ -209,7 +214,7 @@ the ELF program.
The Makefile The Makefile
------------ ============
To build the ELF program, simply run: 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 rm -f *.o
The Linker Script The Linker Script
----------------- =================
The linker script that I am using in this example, gnu-elf.ld, The linker script that I am using in this example, gnu-elf.ld,
contains the following: contains the following:
@ -349,7 +354,7 @@ contains the following:
} }
Replacing NSH Built-In Functions Replacing NSH Built-In Functions
-------------------------------- ================================
Files can be executed by NSH from the command line by simply typing the name 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 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. the version in the file system.
Tightly Coupled Memories Tightly Coupled Memories
------------------------ ========================
Most MCUs based on ARMv7-M family processors support some kind of Tightly Most MCUs based on ARMv7-M family processors support some kind of Tightly
Coupled Memory (TCM). These TCMs have somewhat different properties for Coupled Memory (TCM). These TCMs have somewhat different properties for

11
Documentation/guides/updating_release_system_elf.rst
View file

@ -1,5 +1,10 @@
===========================================
Updating a Release System with ELF Programs 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 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 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: There are two ways you can accomplish this:
Partially linked Partially linked
---------------- ================
This describes building the partially linked, relocatable ELF program that This describes building the partially linked, relocatable ELF program that
depends on a symbol table provided by the base firmware in FLASH. depends on a symbol table provided by the base firmware in FLASH.
@ -17,7 +22,7 @@ Reference:
- See :doc:`Partially Linked ELF Programs <partially_linked_elf>` - See :doc:`Partially Linked ELF Programs <partially_linked_elf>`
Fully linked Fully linked
------------ ============
This describes building a fully linked, relocatable ELF program that does This describes building a fully linked, relocatable ELF program that does
not depend on any symbol table information. not depend on any symbol table information.