Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Doc: add migration warning to updating release system and elf programs #15378

Merged
merged 1 commit into from
Dec 29, 2024
Merged

Doc: add migration warning to updating release system and elf programs #15378

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 15 additions & 10 deletions Documentation/guides/fully_linked_elf.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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:
Expand Down Expand Up @@ -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:

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -486,7 +491,7 @@ replaced with the version in the file system:
nsh>

Version Dependency
------------------
==================

.. note::

Expand All @@ -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
Expand Down
25 changes: 15 additions & 10 deletions Documentation/guides/partially_linked_elf.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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,
Expand All @@ -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:
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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:

Expand All @@ -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
Expand All @@ -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:
Expand Down Expand Up @@ -209,7 +214,7 @@ the ELF program.


The Makefile
------------
============

To build the ELF program, simply run:

Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
11 changes: 8 additions & 3 deletions Documentation/guides/updating_release_system_elf.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -9,15 +14,15 @@ 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.

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.

Expand Down
Loading