This is an automated email from the ASF dual-hosted git repository.
archer pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/nuttx.git
The following commit(s) were added to refs/heads/master by this push:
new b02a0758a7 Doc: add migration warning to updating release system and
elf programs
b02a0758a7 is described below
commit b02a0758a72aa98d73ab42485cd718495465ae5e
Author: Ludovic Vanasse <ludovicvana...@gmail.com>
AuthorDate: Sun Dec 29 09:25:32 2024 -0500
Doc: add migration warning to updating release system and elf programs
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
---
Documentation/guides/fully_linked_elf.rst | 25 +++++++++++++---------
Documentation/guides/partially_linked_elf.rst | 25 +++++++++++++---------
.../guides/updating_release_system_elf.rst | 11 +++++++---
3 files changed, 38 insertions(+), 23 deletions(-)
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 <https://www.youtube.com/watch?v=oL6KAgkTb8M>`_.
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
<fully_linked_elf>` 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
<https://cwiki.apache.org/confluence/download/attachments/139629402/elfprog-wsymtab.tar.gz?version=1&modificationDate=1576735523000&api=v2>`_
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 <partially_linked_elf>`
Fully linked
-------------
+============
This describes building a fully linked, relocatable ELF program that does
not depend on any symbol table information.
