| <!-- |
| Documentation/_templates/layout.html |
| |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. The |
| ASF licenses this file to you under the Apache License, Version 2.0 (the |
| "License"); you may not use this file except in compliance with the |
| License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, WITHOUT |
| WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the |
| License for the specific language governing permissions and limitations |
| under the License. |
| --> |
| |
| |
| |
| <!DOCTYPE html> |
| <html class="writer-html5" lang="en"> |
| <head> |
| <meta charset="utf-8" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" /> |
| |
| <meta name="viewport" content="width=device-width, initial-scale=1.0" /> |
| <title>ELF Programs – With Symbol Tables — NuttX latest documentation</title> |
| <link rel="stylesheet" type="text/css" href="../_static/pygments.css" /> |
| <link rel="stylesheet" type="text/css" href="../_static/css/theme.css" /> |
| <link rel="stylesheet" type="text/css" href="../_static/copybutton.css" /> |
| <link rel="stylesheet" type="text/css" href="../_static/sphinx_collapse.css" /> |
| <link rel="stylesheet" type="text/css" href="../_static/design-style.1e8bd061cd6da7fc9cf755528e8ffc24.min.css" /> |
| <link rel="stylesheet" type="text/css" href="../_static/custom.css" /> |
| |
| |
| <link rel="shortcut icon" href="../_static/favicon.ico"/> |
| <script src="../_static/jquery.js"></script> |
| <script src="../_static/_sphinx_javascript_frameworks_compat.js"></script> |
| <script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script> |
| <script src="../_static/doctools.js"></script> |
| <script src="../_static/sphinx_highlight.js"></script> |
| <script src="../_static/clipboard.min.js"></script> |
| <script src="../_static/copybutton.js"></script> |
| <script src="../_static/design-tabs.js"></script> |
| <script src="../_static/js/theme.js"></script> |
| <link rel="index" title="Index" href="../genindex.html" /> |
| <link rel="search" title="Search" href="../search.html" /> |
| <link rel="next" title="ELF Programs – No Symbol Tables" href="fully_linked_elf.html" /> |
| <link rel="prev" title="Updating a Release System with ELF Programs" href="updating_release_system_elf.html" /> |
| </head> |
| |
| <body class="wy-body-for-nav"> |
| <div class="wy-grid-for-nav"> |
| <nav data-toggle="wy-nav-shift" class="wy-nav-side"> |
| <div class="wy-side-scroll"> |
| <div class="wy-side-nav-search" > |
| |
| <a href="../index.html" class="icon icon-home"> NuttX |
| |
| |
| |
| </a> |
| |
| <!-- this version selector is quite ugly, should be probably replaced by something |
| more modern --> |
| |
| <div class="version-selector"> |
| <select onchange="javascript:location.href = this.value;"> |
| |
| <option value="../../latest" selected="selected">latest</option> |
| |
| <option value="../../10.0.0" >10.0.0</option> |
| |
| <option value="../../10.0.1" >10.0.1</option> |
| |
| <option value="../../10.1.0" >10.1.0</option> |
| |
| <option value="../../10.2.0" >10.2.0</option> |
| |
| <option value="../../10.3.0" >10.3.0</option> |
| |
| <option value="../../11.0.0" >11.0.0</option> |
| |
| <option value="../../12.0.0" >12.0.0</option> |
| |
| <option value="../../12.1.0" >12.1.0</option> |
| |
| <option value="../../12.2.0" >12.2.0</option> |
| |
| <option value="../../12.2.1" >12.2.1</option> |
| |
| <option value="../../12.3.0" >12.3.0</option> |
| |
| <option value="../../12.4.0" >12.4.0</option> |
| |
| <option value="../../12.5.0" >12.5.0</option> |
| |
| <option value="../../12.5.1" >12.5.1</option> |
| |
| <option value="../../12.6.0" >12.6.0</option> |
| |
| <option value="../../12.7.0" >12.7.0</option> |
| |
| <option value="../../12.8.0" >12.8.0</option> |
| |
| <option value="../../12.9.0" >12.9.0</option> |
| |
| <option value="../../12.10.0" >12.10.0</option> |
| |
| <option value="../../12.11.0" >12.11.0</option> |
| |
| </select> |
| </div> |
| |
| |
| <div role="search"> |
| <form id="rtd-search-form" class="wy-form" action="../search.html" method="get"> |
| <input type="text" name="q" placeholder="Search docs" aria-label="Search docs" /> |
| <input type="hidden" name="check_keywords" value="yes" /> |
| <input type="hidden" name="area" value="default" /> |
| </form> |
| </div> |
| |
| </div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu"> |
| <p class="caption" role="heading"><span class="caption-text">Table of Contents</span></p> |
| <ul class="current"> |
| <li class="toctree-l1"><a class="reference internal" href="../index.html">Home</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../introduction/index.html">Introduction</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../quickstart/index.html">Getting Started</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../contributing/index.html">Contributing</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../introduction/inviolables.html">The Inviolable Principles of NuttX</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../platforms/index.html">Supported Platforms</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../components/index.html">OS Components</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../applications/index.html">Applications</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../implementation/index.html">Implementation Details</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../reference/index.html">API Reference</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../faq/index.html">FAQ</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../debugging/index.html">Debugging</a></li> |
| <li class="toctree-l1 current"><a class="reference internal" href="index.html">Guides</a><ul class="current"> |
| <li class="toctree-l2"><a class="reference internal" href="nfs.html">NFS Client How-To</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="nix_flake.html">Nix Flake for Reproducible Development</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="usbtrace.html">USB Device Trace</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="simulator.html">Simulator</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="rndis.html">How to use RNDIS</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="drivers.html">Drivers</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="cpp_cmake.html">C++ Example using CMake</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="pysimcoder.html">pysimCoder integration with NuttX</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="customboards.html">Custom Boards How-To</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="customapps.html">Custom Apps How-to</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="citests.html">Running CI Test Locally</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="zerolatencyinterrupts.html">High Performance: Zero Latency Interrupts, Maskable Nested Interrupts</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="fortify.html">Fortify</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="nestedinterrupts.html">Nested Interrupts</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="ofloader.html">Open Flash Loader</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="testingtcpip.html">Testing TCP/IP Network Stacks</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="automounter.html">Auto-Mounter</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="stm32nullpointer.html">STM32 Null Pointer Detection</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="stm32ccm.html">STM32 CCM Allocator</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="etcromfs.html">etc romfs</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="thread_local_storage.html">Thread Local Storage</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="devicetree.html">Device Tree</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="changing_systemclockconfig.html">Changing the System Clock Configuration</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="usingkernelthreads.html">Using Kernel Threads</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="armv7m_runtimestackcheck.html">ARMv7-M Run Time Stack Checking</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="include_files_board_h.html">Including Files in board.h</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="specialstuff_in_nuttxheaderfiles.html">Why can’t I put my special stuff in NuttX header files?</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="kernel_threads_with_custom_stacks.html">Kernel Threads with Custom Stacks</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="versioning_and_task_names.html">Versioning and Task Names</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="logging_rambuffer.html">Logging to a RAM Buffer</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="ipv6.html">IPv6</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="integrate_newlib.html">Integrating with Newlib</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="protected_build.html">NuttX Protected Build</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="platform_directories.html">Platform Directories</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="port_drivers_to_stm32f7.html">Porting Drivers to the STM32 F7</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="semihosting.html">Semihosting</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="renode.html">Run NuttX on Renode</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="signal_events_interrupt_handlers.html">Signaling Events from Interrupt Handlers</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="signaling_sem_priority_inheritance.html">Signaling Semaphores and Priority Inheritance</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="smaller_vector_tables.html">Smaller Vector Tables</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="port.html">How to port</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="updating_release_system_elf.html">Updating a Release System with ELF Programs</a></li> |
| <li class="toctree-l2 current"><a class="current reference internal" href="#">ELF Programs – With Symbol Tables</a><ul> |
| <li class="toctree-l3"><a class="reference internal" href="#creating-a-symbol-table">Creating a Symbol Table</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="#creating-the-export-package">Creating the Export Package</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="#preparing-the-add-on-build-directory">Preparing the Add-On Build Directory</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="#hello-example">Hello Example</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="#building-the-elf-program">Building the ELF Program</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="#the-makefile">The Makefile</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="#the-linker-script">The Linker Script</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="#replacing-nsh-built-in-functions">Replacing NSH Built-In Functions</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="#tightly-coupled-memories">Tightly Coupled Memories</a></li> |
| </ul> |
| </li> |
| <li class="toctree-l2"><a class="reference internal" href="fully_linked_elf.html">ELF Programs – No Symbol Tables</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="building_nuttx_with_app_out_of_src_tree.html">Building NuttX with Applications Outside the Source Tree</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="building_uclibcpp.html">Building uClibc++</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="custom_app_directories.html">Custom Application Directories</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="multiple_nsh_sessions.html">Multiple NSH Sessions</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="nsh_network_link_management.html">NSH Network Link Management</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="ram_rom_disks.html">RAM Disks and ROM Disks</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="reading_can_msgs.html">Reading CAN Messages</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="remove_device_drivers_nsh.html">Removing Device Drivers with NSH</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="rust.html">Rust in NuttX</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="optee.html">Interfacing with OP-TEE</a></li> |
| </ul> |
| </li> |
| <li class="toctree-l1"><a class="reference internal" href="../standards/index.html">Standards</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../glossary.html">Glossary</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../logos/index.html">NuttX Logos</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../_tags/tagsindex.html">Tags</a></li> |
| </ul> |
| |
| </div> |
| </div> |
| </nav> |
| |
| <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" > |
| <i data-toggle="wy-nav-top" class="fa fa-bars"></i> |
| <a href="../index.html">NuttX</a> |
| </nav> |
| |
| <div class="wy-nav-content"> |
| <div class="rst-content"> |
| <div role="navigation" aria-label="Page navigation"> |
| <ul class="wy-breadcrumbs"> |
| <li><a href="../index.html" class="icon icon-home" aria-label="Home"></a></li> |
| <li class="breadcrumb-item"><a href="index.html">Guides</a></li> |
| <li class="breadcrumb-item active">ELF Programs – With Symbol Tables</li> |
| <li class="wy-breadcrumbs-aside"> |
| <a href="https://github.com/apache/nuttx/blob/master/Documentation/guides/partially_linked_elf.rst" class="fa fa-github"> Edit on GitHub</a> |
| </li> |
| </ul> |
| <hr/> |
| </div> |
| <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article"> |
| <div itemprop="articleBody"> |
| |
| <section id="elf-programs-with-symbol-tables"> |
| <h1>ELF Programs – With Symbol Tables<a class="headerlink" href="#elf-programs-with-symbol-tables" title="Permalink to this heading"></a></h1> |
| <p>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, |
| downloaded into on-board SPI FLASH.</p> |
| <p>In order to support such post-release updates, your released firmware must |
| support execution of ELF programs loaded into RAM and symbol tables also |
| provided via the file system (see <cite>apps/examples/elf</cite>).</p> |
| <section id="creating-a-symbol-table"> |
| <h2>Creating a Symbol Table<a class="headerlink" href="#creating-a-symbol-table" title="Permalink to this heading"></a></h2> |
| <p>There are several ways to create an application symbol table. Only two are |
| compatible with the example provided here:</p> |
| <ol class="arabic"> |
| <li><p><strong>Board-specific Bring-up Logic</strong> |
| Build a symbol table into the base firmware and add it to your |
| board-specific bring-up logic. This technique is typically used in kernel |
| mode with <code class="docutils literal notranslate"><span class="pre">CONFIG_USER_INITPATH=y</span></code>.</p> |
| <p>In this setup, the system does not initialize using a standard C call like |
| <code class="docutils literal notranslate"><span class="pre">nsh_main()</span></code>. Instead, it starts with an <code class="docutils literal notranslate"><span class="pre">init</span></code> ELF program, similar to |
| how Linux initializes. The configuration option |
| <code class="docutils literal notranslate"><span class="pre">CONFIG_EXECFUNCS_SYMTAB_ARRAY</span></code> initializes the system with a minimal set |
| of symbols required by the <code class="docutils literal notranslate"><span class="pre">init</span></code> program. Once initialized, the <code class="docutils literal notranslate"><span class="pre">init</span></code> |
| program would typically call <code class="docutils literal notranslate"><span class="pre">boardctl()</span></code> to put the final symbol table in |
| place.</p> |
| <p>To enable this method, you must:</p> |
| <ul class="simple"> |
| <li><p>Set <code class="docutils literal notranslate"><span class="pre">CONFIG_EXECFUNCS_HAVE_SYMTAB=y</span></code> in your configuration.</p></li> |
| <li><p>Provide a symbol table with the global name |
| <code class="docutils literal notranslate"><span class="pre">CONFIG_EXECFUNCS_SYMTAB_ARRAY</span></code> with the variable name |
| <code class="docutils literal notranslate"><span class="pre">CONFIG_EXECFUNCS_NSYMBOLS_VAR</span></code> that holds the number of symbol entries. |
| The default symbol table name is <code class="docutils literal notranslate"><span class="pre">g_symtab</span></code> |
| and its length is <code class="docutils literal notranslate"><span class="pre">g_nsymbols</span></code>.</p></li> |
| </ul> |
| <p>In this example, let’s illustrate this using an STM32F4-Discovery |
| configuration. We will assume that you have modified the |
| <code class="docutils literal notranslate"><span class="pre">boards/arm/stm32/stm32fdiscovery/src/stm32_bringup.c</span></code> file, adding the |
| following:</p> |
| <div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="cp">#include</span><span class="w"> </span><span class="cpf"><nuttx/compiler.h></span> |
| <span class="cp">#include</span><span class="w"> </span><span class="cpf"><nuttx/symtab.h></span> |
| |
| <span class="k">const</span><span class="w"> </span><span class="k">struct</span><span class="w"> </span><span class="nc">symtab_s</span><span class="w"> </span><span class="n">g_symtab</span><span class="p">[]</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">{</span> |
| <span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="s">"printf"</span><span class="p">,</span><span class="w"> </span><span class="p">(</span><span class="n">FAR</span><span class="w"> </span><span class="k">const</span><span class="w"> </span><span class="kt">void</span><span class="w"> </span><span class="o">*</span><span class="p">)</span><span class="n">printf</span><span class="w"> </span><span class="p">}</span> |
| <span class="p">};</span> |
| |
| <span class="kt">int</span><span class="w"> </span><span class="n">g_nsymbols</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">1</span><span class="p">;</span> |
| </pre></div> |
| </div> |
| <p>This is a simple symbol table containing only the symbol string “printf”, |
| whose value is the address of the function <code class="docutils literal notranslate"><span class="pre">printf()</span></code>.</p> |
| <p>This example keeps things simple in order to focus on the core functionality, |
| but there is, of course, a lot more that could be said about generating symbol |
| tables. NuttX provides specialized tools in the <code class="docutils literal notranslate"><span class="pre">tools/</span></code> directory for |
| generating more extensive symbol tables: you can start by taking a look at |
| <code class="docutils literal notranslate"><span class="pre">tools/mksymtab.c</span></code>. An example invocation of that tool could be: |
| <code class="docutils literal notranslate"><span class="pre">./tools/mksymtab</span> <span class="pre">-d</span> <span class="pre">./libs/libc/libc.csv</span> <span class="pre"><path_to_generated_symtab.c></span></code>.</p> |
| </li> |
| <li><p><strong>Application Logic</strong> |
| Alternatively, the symbol table can be provided dynamically by the |
| application itself, using the <code class="docutils literal notranslate"><span class="pre">boardctl()</span></code> system interface. The specific |
| <code class="docutils literal notranslate"><span class="pre">boardctl()</span></code> command to use is <code class="docutils literal notranslate"><span class="pre">BOARDIOC_APP_SYMTAB</span></code>. This command |
| provides the symbol table in the same way as the board-specific logic but |
| allows for application-level control.</p> |
| <p>To use this approach, you need to: |
| - Enable the configurations <code class="docutils literal notranslate"><span class="pre">CONFIG_BOARDCTL=y</span></code> |
| and <code class="docutils literal notranslate"><span class="pre">CONFIG_BOARDCTL_APP_SYMTAB=y</span></code>. |
| - Include application logic to provide the symbol table. |
| If <code class="docutils literal notranslate"><span class="pre">CONFIG_EXAMPLES_NSH_SYMTAB=y</span></code> is set, NSH can handle this |
| automatically.</p> |
| </li> |
| </ol> |
| </section> |
| <section id="creating-the-export-package"> |
| <h2>Creating the Export Package<a class="headerlink" href="#creating-the-export-package" title="Permalink to this heading"></a></h2> |
| <p>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 |
| post-release add-on modules for your embedded system.</p> |
| <p>For demonstration purposes, we’ll use the STM32F4-Discovery with the network |
| NSH configuration. This setup assumes that you have the STM32F4DIS-BB |
| baseboard. The demonstration also requires support for externally modifiable |
| media, such as:</p> |
| <ul class="simple"> |
| <li><p>Removable media, like an SD card or USB flash drive.</p></li> |
| <li><p>An internal file system remotely accessible via USB MSC, FTP, or other |
| protocols.</p></li> |
| <li><p>A remote file system, such as NFS.</p></li> |
| </ul> |
| <p>In this demonstration, the networking NSH configuration uses the SD card on |
| the STM32 baseboard. Other NSH configurations can also be used, provided they |
| supply the necessary file system support.</p> |
| <div class="admonition tip"> |
| <p class="admonition-title">Tip</p> |
| <p>No baseboard? You can add file system support to the basic STM32F4-Discovery |
| board by following these instructions: <a class="reference external" href="https://www.youtube.com/watch?v=5hB5ZXpRoS4">USB FLASH drive</a> |
| or <a class="reference external" href="https://www.youtube.com/watch?v=H28t4RbOXqI">SD card</a>.</p> |
| </div> |
| <p>Initialize the environment:</p> |
| <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>make<span class="w"> </span>distclean |
| <span class="gp">$ </span>tools/configure.sh<span class="w"> </span>-c<span class="w"> </span>stm32f4discovery:netnsh |
| <span class="gp">$ </span>make<span class="w"> </span>menuconfig |
| </pre></div> |
| </div> |
| <p>Edit the configuration:</p> |
| <ul class="simple"> |
| <li><p>Disable networking (it is not needed in this example): |
| <code class="docutils literal notranslate"><span class="pre">#</span> <span class="pre">CONFIG_NET</span> <span class="pre">is</span> <span class="pre">not</span> <span class="pre">set</span></code>.</p></li> |
| <li><p>Enable ELF binary support with external symbol tables: |
| <code class="docutils literal notranslate"><span class="pre">CONFIG_ELF=y</span></code>, |
| <code class="docutils literal notranslate"><span class="pre">CONFIG_LIBC_EXECFUNCS=y</span></code>, |
| <code class="docutils literal notranslate"><span class="pre">CONFIG_EXECFUNCS_HAVE_SYMTAB=y</span></code>, |
| <code class="docutils literal notranslate"><span class="pre">CONFIG_EXECFUNCS_SYMTAB_ARRAY="g_symtab"</span></code>, |
| <code class="docutils literal notranslate"><span class="pre">CONFIG_EXECFUNCS_NSYMBOLS_VAR="g_nsymbols"</span></code>.</p></li> |
| <li><p>Enable PATH variable support: |
| <code class="docutils literal notranslate"><span class="pre">CONFIG_LIBC_ENVPATH=y</span></code>, |
| <code class="docutils literal notranslate"><span class="pre">CONFIG_PATH_INITIAL="/addons"</span></code>, |
| <code class="docutils literal notranslate"><span class="pre">#</span> <span class="pre">CONFIG_DISABLE_ENVIRON</span> <span class="pre">not</span> <span class="pre">set</span></code>.</p></li> |
| <li><p>Enable execution of ELF files from NSH: <code class="docutils literal notranslate"><span class="pre">CONFIG_NSH_FILE_APPS=y</span></code>.</p></li> |
| </ul> |
| <p>Then, build the NuttX firmware image and the export package:</p> |
| <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>make |
| <span class="gp">$ </span>make<span class="w"> </span><span class="nb">export</span> |
| </pre></div> |
| </div> |
| <p>When <code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">export</span></code> completes, you will find a ZIP package in the top-level |
| NuttX directory called <code class="docutils literal notranslate"><span class="pre">nuttx-export-x.y.zip</span></code> (where <code class="docutils literal notranslate"><span class="pre">x.y</span></code> corresponds to |
| the version determined by the <code class="docutils literal notranslate"><span class="pre">.version</span></code> file in the same directory). |
| The contents of this ZIP file are organized as follows:</p> |
| <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>nuttx-export-x.x |
| |- arch/ |
| |- include/ |
| |- libs/ |
| |- registry/ |
| |- scripts/ |
| |- startup/ |
| |- tools/ |
| |- System.map |
| `- .config |
| </pre></div> |
| </div> |
| </section> |
| <section id="preparing-the-add-on-build-directory"> |
| <h2>Preparing the Add-On Build Directory<a class="headerlink" href="#preparing-the-add-on-build-directory" title="Permalink to this heading"></a></h2> |
| <p>In order to create the add-on ELF program, you will need:</p> |
| <ol class="arabic simple"> |
| <li><p>The export package.</p></li> |
| <li><p>A Makefile to build the program.</p></li> |
| <li><p>A linker script to use in the Makefile.</p></li> |
| </ol> |
| <p>The example Makefile shown below assumes the use of a GNU toolchain. Note |
| that non-GNU toolchains would likely require a significantly different |
| Makefile and linker script.</p> |
| </section> |
| <section id="hello-example"> |
| <h2>Hello Example<a class="headerlink" href="#hello-example" title="Permalink to this heading"></a></h2> |
| <p>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 |
| source file <code class="docutils literal notranslate"><span class="pre">hello.c</span></code>:</p> |
| <div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="cp">#include</span><span class="w"> </span><span class="cpf"><stdio.h></span> |
| |
| <span class="kt">int</span><span class="w"> </span><span class="nf">main</span><span class="p">(</span><span class="kt">int</span><span class="w"> </span><span class="n">argc</span><span class="p">,</span><span class="w"> </span><span class="kt">char</span><span class="w"> </span><span class="o">**</span><span class="n">argv</span><span class="p">)</span> |
| <span class="p">{</span> |
| <span class="w"> </span><span class="n">printf</span><span class="p">(</span><span class="s">"Hello from a partially linked Add-On Program!</span><span class="se">\n</span><span class="s">"</span><span class="p">);</span> |
| <span class="w"> </span><span class="k">return</span><span class="w"> </span><span class="mi">0</span><span class="p">;</span> |
| <span class="p">}</span> |
| </pre></div> |
| </div> |
| <p>Let’s say that we have a directory called <code class="docutils literal notranslate"><span class="pre">addon</span></code> that contains |
| the following:</p> |
| <ol class="arabic simple"> |
| <li><p>The <code class="docutils literal notranslate"><span class="pre">hello.c</span></code> source file.</p></li> |
| <li><p>A Makefile to build the ELF program.</p></li> |
| <li><p>The export package <code class="docutils literal notranslate"><span class="pre">nuttx-export-x.y.zip</span></code>.</p></li> |
| </ol> |
| </section> |
| <section id="building-the-elf-program"> |
| <h2>Building the ELF Program<a class="headerlink" href="#building-the-elf-program" title="Permalink to this heading"></a></h2> |
| <p>The first step in creating the ELF program is to unzip the export |
| package. Starting in the <code class="docutils literal notranslate"><span class="pre">addon</span></code> directory:</p> |
| <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span><span class="nb">cd</span><span class="w"> </span>addon |
| <span class="gp">$ </span>ls |
| <span class="go">hello.c Makefile nuttx-export-x.y.zip</span> |
| </pre></div> |
| </div> |
| <p>Where: |
| - <code class="docutils literal notranslate"><span class="pre">hello.c</span></code> is the example source file. |
| - <code class="docutils literal notranslate"><span class="pre">Makefile</span></code> builds the ELF program. |
| - <code class="docutils literal notranslate"><span class="pre">nuttx-export-x.y.zip</span></code> is the export package from NuttX version <code class="docutils literal notranslate"><span class="pre">x.y</span></code>.</p> |
| <p>Unzip the export package and rename the folder for ease of use:</p> |
| <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>unzip<span class="w"> </span>nuttx-export-x.y.zip |
| <span class="gp">$ </span>mv<span class="w"> </span>nuttx-export-x.y<span class="w"> </span>nuttx-export |
| </pre></div> |
| </div> |
| <p>This creates a new directory called <code class="docutils literal notranslate"><span class="pre">nuttx-export</span></code>, containing |
| all the content from the released NuttX code required to build |
| the ELF program.</p> |
| </section> |
| <section id="the-makefile"> |
| <h2>The Makefile<a class="headerlink" href="#the-makefile" title="Permalink to this heading"></a></h2> |
| <p>To build the ELF program, simply run:</p> |
| <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>make |
| </pre></div> |
| </div> |
| <p>This uses the following Makefile to generate several files:</p> |
| <ul class="simple"> |
| <li><p><code class="docutils literal notranslate"><span class="pre">hello.o</span></code>: The compiled object file for <code class="docutils literal notranslate"><span class="pre">hello.c</span></code>.</p></li> |
| <li><p><code class="docutils literal notranslate"><span class="pre">hello</span></code>: The partially linked ELF program.</p></li> |
| </ul> |
| <p>The Makefile used to create the ELF program is as follows:</p> |
| <div class="admonition note"> |
| <p class="admonition-title">Note</p> |
| <p>When copying the following contents, remember that Makefile indentations |
| must be made with proper tab characters and not just spaces.</p> |
| </div> |
| <div class="highlight-makefile notranslate"><div class="highlight"><pre><span></span><span class="cp">include nuttx-export/scripts/Make.defs</span> |
| |
| <span class="c"># Long calls are needed to call from RAM into FLASH</span> |
| |
| <span class="nv">ARCHCFLAGS</span><span class="w"> </span><span class="o">+=</span><span class="w"> </span>-mlong-calls |
| |
| <span class="c"># You may want to check these options against the ones in "nuttx-export/scripts/Make.defs"</span> |
| |
| <span class="nv">ARCHWARNINGS</span><span class="w"> </span><span class="o">=</span><span class="w"> </span>-Wall<span class="w"> </span>-Wstrict-prototypes<span class="w"> </span>-Wshadow<span class="w"> </span>-Wundef |
| <span class="nv">ARCHOPTIMIZATION</span><span class="w"> </span><span class="o">=</span><span class="w"> </span>-Os<span class="w"> </span>-fno-strict-aliasing<span class="w"> </span>-fno-strength-reduce<span class="w"> </span>-fomit-frame-pointer |
| <span class="nv">ARCHINCLUDES</span><span class="w"> </span><span class="o">=</span><span class="w"> </span>-I.<span class="w"> </span>-isystem<span class="w"> </span>nuttx-export/include |
| |
| <span class="nv">CFLAGS</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="k">$(</span>ARCHCFLAGS<span class="k">)</span><span class="w"> </span><span class="k">$(</span>ARCHWARNINGS<span class="k">)</span><span class="w"> </span><span class="k">$(</span>ARCHOPTIMIZATION<span class="k">)</span><span class="w"> </span><span class="k">$(</span>ARCHCPUFLAGS<span class="k">)</span><span class="w"> </span><span class="k">$(</span>ARCHINCLUDES<span class="k">)</span><span class="w"> </span><span class="k">$(</span>ARCHDEFINES<span class="k">)</span><span class="w"> </span><span class="k">$(</span>EXTRADEFINES<span class="k">)</span> |
| |
| <span class="c"># Setup up linker command line options</span> |
| |
| <span class="nv">LDELFFLAGS</span><span class="w"> </span><span class="o">=</span><span class="w"> </span>--relocatable<span class="w"> </span>-e<span class="w"> </span>main |
| <span class="nv">LDELFFLAGS</span><span class="w"> </span><span class="o">+=</span><span class="w"> </span>-T<span class="w"> </span>nuttx-export/scripts/gnu-elf.ld |
| |
| <span class="c"># This is the generated ELF program</span> |
| |
| <span class="nv">BIN</span><span class="w"> </span><span class="o">=</span><span class="w"> </span>hello |
| |
| <span class="c"># These are the sources files that we use</span> |
| |
| <span class="nv">SRCS</span><span class="w"> </span><span class="o">=</span><span class="w"> </span>hello.c |
| <span class="nv">OBJS</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="k">$(</span>SRCS:.c<span class="o">=</span><span class="k">$(</span>OBJEXT<span class="k">))</span> |
| |
| <span class="c"># Build targets</span> |
| |
| <span class="nf">.PHONY</span><span class="o">:</span><span class="w"> </span><span class="n">clean</span> |
| |
| <span class="nf">all</span><span class="o">:</span><span class="w"> </span><span class="k">$(</span><span class="nv">BIN</span><span class="k">)</span> |
| |
| <span class="nf">$(OBJS)</span><span class="o">:</span><span class="w"> </span>%<span class="k">$(</span><span class="nv">OBJEXT</span><span class="k">)</span>: %.<span class="n">c</span> |
| <span class="w"> </span><span class="k">$(</span>CC<span class="k">)</span><span class="w"> </span>-c<span class="w"> </span><span class="k">$(</span>CFLAGS<span class="k">)</span><span class="w"> </span>-o<span class="w"> </span><span class="nv">$@</span><span class="w"> </span>$< |
| |
| <span class="nf">$(BIN)</span><span class="o">:</span><span class="w"> </span><span class="k">$(</span><span class="nv">OBJS</span><span class="k">)</span> |
| <span class="w"> </span><span class="k">$(</span>LD<span class="k">)</span><span class="w"> </span><span class="k">$(</span>LDELFFLAGS<span class="k">)</span><span class="w"> </span>-o<span class="w"> </span><span class="nv">$@</span><span class="w"> </span>$^ |
| <span class="w"> </span><span class="k">$(</span>STRIP<span class="k">)</span><span class="w"> </span><span class="nv">$@</span> |
| <span class="c"> #$(CROSSDEV)objdump -f $@</span> |
| |
| <span class="nf">clean</span><span class="o">:</span> |
| <span class="w"> </span>rm<span class="w"> </span>-f<span class="w"> </span><span class="k">$(</span>BIN<span class="k">)</span> |
| <span class="w"> </span>rm<span class="w"> </span>-f<span class="w"> </span><span class="k">$(</span>OBJS<span class="k">)</span> |
| </pre></div> |
| </div> |
| </section> |
| <section id="the-linker-script"> |
| <h2>The Linker Script<a class="headerlink" href="#the-linker-script" title="Permalink to this heading"></a></h2> |
| <p>The linker script used in this example is the one from the exported |
| NuttX package: <code class="docutils literal notranslate"><span class="pre">nuttx-export/scripts/gnu-elf.ld</span></code>.</p> |
| <div class="admonition-here-is-an-alternative-minimal-and-possibly-outdated-version admonition"> |
| <p class="admonition-title">Here is an alternative minimal (and possibly outdated) version</p> |
| <div class="sphinx_collapse docutils"> |
| <input class="sphinx_collapse__input" id="1c01d7d3-f1aa-4705-84cd-be57227d2cfa" name="1c01d7d3-f1aa-4705-84cd-be57227d2cfa" type="checkbox"><label class="sphinx_collapse__label" for="1c01d7d3-f1aa-4705-84cd-be57227d2cfa"><i class="sphinx_collapse__icon"></i>Show content:</label><div class="sphinx_collapse__content docutils"> |
| <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>SECTIONS |
| { |
| .text 0x00000000 : |
| { |
| _stext = . ; |
| *(.text) |
| *(.text.*) |
| *(.gnu.warning) |
| *(.stub) |
| *(.glue_7) |
| *(.glue_7t) |
| *(.jcr) |
| _etext = . ; |
| } |
| |
| .rodata : |
| { |
| _srodata = . ; |
| *(.rodata) |
| *(.rodata1) |
| *(.rodata.*) |
| *(.gnu.linkonce.r*) |
| _erodata = . ; |
| } |
| |
| .data : |
| { |
| _sdata = . ; |
| *(.data) |
| *(.data1) |
| *(.data.*) |
| *(.gnu.linkonce.d*) |
| _edata = . ; |
| } |
| |
| .bss : |
| { |
| _sbss = . ; |
| *(.bss) |
| *(.bss.*) |
| *(.sbss) |
| *(.sbss.*) |
| *(.gnu.linkonce.b*) |
| *(COMMON) |
| _ebss = . ; |
| } |
| |
| .stab 0 : { *(.stab) } |
| .stabstr 0 : { *(.stabstr) } |
| .stab.excl 0 : { *(.stab.excl) } |
| .stab.exclstr 0 : { *(.stab.exclstr) } |
| .stab.index 0 : { *(.stab.index) } |
| .stab.indexstr 0 : { *(.stab.indexstr) } |
| .comment 0 : { *(.comment) } |
| .debug_abbrev 0 : { *(.debug_abbrev) } |
| .debug_info 0 : { *(.debug_info) } |
| .debug_line 0 : { *(.debug_line) } |
| .debug_pubnames 0 : { *(.debug_pubnames) } |
| .debug_aranges 0 : { *(.debug_aranges) } |
| } |
| </pre></div> |
| </div> |
| </div> |
| </div> |
| </div> |
| </section> |
| <section id="replacing-nsh-built-in-functions"> |
| <h2>Replacing NSH Built-In Functions<a class="headerlink" href="#replacing-nsh-built-in-functions" title="Permalink to this heading"></a></h2> |
| <p>Files can be executed by NSH from the command line by simply typing the name |
| of the ELF program, given that the following requirements are met:</p> |
| <ol class="arabic simple"> |
| <li><p>The feature is enabled with <code class="docutils literal notranslate"><span class="pre">CONFIG_NSH_FILE_APP=y</span></code>.</p></li> |
| <li><p>Support for the PATH variable is enabled with <code class="docutils literal notranslate"><span class="pre">CONFIG_LIBC_ENVPATH=y</span></code>.</p></li> |
| <li><p>The mount point of the file system that may contain ELF programs is |
| set in <code class="docutils literal notranslate"><span class="pre">CONFIG_PATH_INITIAL</span></code>.</p></li> |
| </ol> |
| <p>In this example, there is no application in the base firmware called |
| <code class="docutils literal notranslate"><span class="pre">hello</span></code>. So attempts to run <code class="docutils literal notranslate"><span class="pre">hello</span></code> will fail:</p> |
| <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>nsh> hello |
| nsh: hello: command not found |
| nsh> |
| </pre></div> |
| </div> |
| <p>But if we mount the SD card containing the <code class="docutils literal notranslate"><span class="pre">hello</span></code> binary that we created |
| above, then we can successfully execute the <code class="docutils literal notranslate"><span class="pre">hello</span></code> command:</p> |
| <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>nsh> mount -t vfat /dev/mmcsd0 /addons |
| nsh> ls /addons |
| /addons: |
| hello |
| nsh> hello |
| Hello from a partially linked Add-On Program! |
| nsh> |
| </pre></div> |
| </div> |
| <p>This showed that you can add a new NSH command to a product without |
| modifying the base firmware, but you can also replace or update an existing |
| built-in application: in the above configuration, NSH will first attempt to |
| run the program called <code class="docutils literal notranslate"><span class="pre">hello</span></code> from the file system; this will fail because |
| the custom <code class="docutils literal notranslate"><span class="pre">hello</span></code> ELF program is not yet available. So instead, NSH will |
| fallback and execute the built-in application called <code class="docutils literal notranslate"><span class="pre">hello</span></code>. This way, |
| any command known to NSH can be replaced from an ELF program installed in a |
| mounted file system directory specified in the PATH environment variable: |
| after adding the custom <code class="docutils literal notranslate"><span class="pre">hello</span></code> binary to the file system, NSH will prefer it |
| over the built-in version when attempting to run the program called <code class="docutils literal notranslate"><span class="pre">hello</span></code>.</p> |
| </section> |
| <section id="tightly-coupled-memories"> |
| <h2>Tightly Coupled Memories<a class="headerlink" href="#tightly-coupled-memories" title="Permalink to this heading"></a></h2> |
| <p>Most MCUs based on ARMv7-M family processors support some kind of Tightly |
| Coupled Memory (TCM). These TCMs have somewhat different properties for |
| specialized operations. Depending on the bus matrix of the processor, you |
| may not be able to execute programs from the TCM. For instance, the STM32F4 |
| supports Core Coupled Memory (CCM) but, since it is tied directly to the |
| D-bus, it cannot be used to execute programs. On the other hand, the STM32F3 |
| has a CCM that is accessible to both the D-Bus and the I-Bus, in which case |
| it should be possible to execute programs directly from this TCM.</p> |
| <img alt="../_images/system_arch_stm32f42xx_and_f43xx.png" src="../_images/system_arch_stm32f42xx_and_f43xx.png" /> |
| <img alt="../_images/system_arch_stm32f303xBC_and_f358xC.png" src="../_images/system_arch_stm32f303xBC_and_f358xC.png" /> |
| <p>When ELF programs are loaded into memory, such memory is allocated from the |
| heap via a standard memory allocator. With the STM32F4, the CCM is included |
| in the heap by default and will typically be allocated first. If CCM memory |
| is allocated to hold the loaded ELF program, then a hard-fault will occur |
| immediately when you try to execute it. |
| Therefore, on STM32F4 platforms it is necessary to include the |
| <code class="docutils literal notranslate"><span class="pre">CONFIG_STM32_CCMEXCLUDE=y</span></code> configuration setting. With it, the CCM |
| memory will be excluded from the heap and will never be allocated for |
| ELF program memory.</p> |
| </section> |
| </section> |
| |
| |
| </div> |
| </div> |
| <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer"> |
| <a href="updating_release_system_elf.html" class="btn btn-neutral float-left" title="Updating a Release System with ELF Programs" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a> |
| <a href="fully_linked_elf.html" class="btn btn-neutral float-right" title="ELF Programs – No Symbol Tables" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a> |
| </div> |
| |
| <hr/> |
| |
| <div role="contentinfo"> |
| <p>© Copyright 2023, The Apache Software Foundation.</p> |
| </div> |
| |
| |
| |
| </footer> |
| </div> |
| </div> |
| </section> |
| </div> |
| <script> |
| jQuery(function () { |
| SphinxRtdTheme.Navigation.enable(true); |
| }); |
| </script> |
| |
| </body> |
| </html> |
