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
This commit is contained in:
Ludovic Vanasse
archer
parent
04c7391162
commit
b02a0758a7
3 changed files with 38 additions and 23 deletions
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue