| <!-- |
| 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 – No 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="Building NuttX with Applications Outside the Source Tree" href="building_nuttx_with_app_out_of_src_tree.html" /> |
| <link rel="prev" title="ELF Programs – With Symbol Tables" href="partially_linked_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"><a class="reference internal" href="partially_linked_elf.html">ELF Programs – With Symbol Tables</a></li> |
| <li class="toctree-l2 current"><a class="current reference internal" href="#">ELF Programs – No Symbol Tables</a><ul> |
| <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="#creating-the-defines-ld-linker-script">Creating the <code class="docutils literal notranslate"><span class="pre">defines.ld</span></code> 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="#version-dependency">Version Dependency</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="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 – No Symbol Tables</li> |
| <li class="wy-breadcrumbs-aside"> |
| <a href="https://github.com/apache/nuttx/blob/master/Documentation/guides/fully_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-no-symbol-tables"> |
| <h1>ELF Programs – No Symbol Tables<a class="headerlink" href="#elf-programs-no-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> |
| <p>Alan Carvalho de Assis has also made a video based on this example and |
| published it in the <a class="reference external" href="https://www.youtube.com/watch?v=oL6KAgkTb8M">NuttX YouTube channel</a>.</p> |
| <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 without 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">#</span> <span class="pre">CONFIG_EXECFUNCS_HAVE_SYMTAB</span> <span class="pre">is</span> <span class="pre">not</span> <span class="pre">set</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> |
| <div class="admonition note"> |
| <p class="admonition-title">Note</p> |
| <p>You must enable some application that uses <code class="docutils literal notranslate"><span class="pre">printf()</span></code>. This is necessary |
| to ensure that the symbol <code class="docutils literal notranslate"><span class="pre">printf()</span></code> is included in the base system. |
| Here we assume that the “Hello, World!” example from <code class="docutils literal notranslate"><span class="pre">apps/examples/hello</span></code> |
| has been enabled with the configuration option <code class="docutils literal notranslate"><span class="pre">CONFIG_EXAMPLES_HELLO=y</span></code>.</p> |
| </div> |
| <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 first linker script to use in the Makefile (<code class="docutils literal notranslate"><span class="pre">gnu-elf.ld</span></code>).</p></li> |
| <li><p>A Bash script to create a second linker script (<code class="docutils literal notranslate"><span class="pre">defines.ld</span></code>).</p></li> |
| </ol> |
| <div class="admonition note"> |
| <p class="admonition-title">Note</p> |
| <p>These example files implicitly assume a GNU tool chain is used and, in at |
| least one place, that the target is an ARMv7-M platform. A non-GNU tool |
| chain would probably require a significantly different Makefile and |
| linker script. There is at least one ARMv7-M specific change that would |
| have to be made for other platforms in the script that creates the linker |
| script (later on referred to as <code class="docutils literal notranslate"><span class="pre">mkdefines.sh</span></code>).</p> |
| </div> |
| </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 fully 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> |
| <li><p>A Bash script called <code class="docutils literal notranslate"><span class="pre">mkdefines.sh</span></code> that will create the second |
| (<code class="docutils literal notranslate"><span class="pre">defines.ld</span></code>) linker script.</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 mkdefines.sh 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">mkdefines.h</span></code> is the Bash script that will create the linker script that will serve as the symbol table. |
| - <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>The ELF program is created simply as:</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 <code class="docutils literal notranslate"><span class="pre">hello.c</span></code> object.</p></li> |
| <li><p><code class="docutils literal notranslate"><span class="pre">hello.r</span></code>: A partially linked ELF object that still has undefined symbols.</p></li> |
| <li><p><code class="docutils literal notranslate"><span class="pre">hello</span></code>: The fully linked, relocatable ELF program.</p></li> |
| <li><p><code class="docutils literal notranslate"><span class="pre">linker.ld</span></code>: The linker script created by <code class="docutils literal notranslate"><span class="pre">mkdefines.sh</span></code>.</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">LDRELFLAGS</span><span class="w"> </span><span class="o">=</span><span class="w"> </span>--relocatable |
| |
| <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>defines.ld<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="nv">REL</span><span class="w"> </span><span class="o">=</span><span class="w"> </span>hello.r |
| |
| <span class="c"># These are the source 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">System.map</span><span class="o">:</span><span class="w"> </span><span class="n">nuttx</span>-<span class="n">export</span>/<span class="n">System</span>.<span class="n">map</span> |
| <span class="w"> </span>cat<span class="w"> </span>nuttx-export/System.map<span class="w"> </span><span class="p">|</span><span class="w"> </span>sed<span class="w"> </span>-e<span class="w"> </span><span class="s2">"s/\r//g"</span><span class="w"> </span>><span class="w"> </span>System.map |
| |
| <span class="nf">$(REL)</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>LDRELFLAGS<span class="k">)</span><span class="w"> </span>-o<span class="w"> </span><span class="nv">$@</span><span class="w"> </span>$< |
| |
| <span class="nf">defines.ld</span><span class="o">:</span><span class="w"> </span><span class="n">System</span>.<span class="n">map</span> <span class="k">$(</span><span class="nv">REL</span><span class="k">)</span> |
| <span class="w"> </span>./mkdefines.sh<span class="w"> </span>System.map<span class="w"> </span><span class="s2">"</span><span class="k">$(</span>REL<span class="k">)</span><span class="s2">"</span><span class="w"> </span>><span class="w"> </span>defines.ld |
| |
| <span class="nf">$(BIN)</span><span class="o">:</span><span class="w"> </span><span class="n">defines</span>.<span class="n">ld</span> <span class="k">$(</span><span class="nv">REL</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="k">$(</span>REL<span class="k">)</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>REL<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> |
| <span class="w"> </span>rm<span class="w"> </span>-f<span class="w"> </span>defines.ld |
| <span class="w"> </span>rm<span class="w"> </span>-f<span class="w"> </span>System.map |
| </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>Two linker scripts are used: the main one, <code class="docutils literal notranslate"><span class="pre">gnu-elf.ld</span></code>, is a normal file, |
| while <code class="docutils literal notranslate"><span class="pre">defines.ld</span></code> is created on-the-fly as described in the next section.</p> |
| <p>The main 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="c50c326f-25fc-44af-9eaf-6c0285aef748" name="c50c326f-25fc-44af-9eaf-6c0285aef748" type="checkbox"><label class="sphinx_collapse__label" for="c50c326f-25fc-44af-9eaf-6c0285aef748"><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 = . ; |
| } |
| |
| /* Stabs debugging sections. */ |
| |
| .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="creating-the-defines-ld-linker-script"> |
| <h2>Creating the <code class="docutils literal notranslate"><span class="pre">defines.ld</span></code> Linker Script<a class="headerlink" href="#creating-the-defines-ld-linker-script" title="Permalink to this heading"></a></h2> |
| <p>The additional linker script, <code class="docutils literal notranslate"><span class="pre">defines.ld</span></code>, is created through a three-step |
| process:</p> |
| <ol class="arabic simple"> |
| <li><p>The Makefile generates a partially linked ELF object, <code class="docutils literal notranslate"><span class="pre">hello.r</span></code>.</p></li> |
| <li><p>The Makefile then invokes the <code class="docutils literal notranslate"><span class="pre">mkdefines.sh</span></code> script, which generates |
| the <code class="docutils literal notranslate"><span class="pre">defines.ld</span></code> linker script that provides values for all of the |
| undefined symbols.</p></li> |
| <li><p>Finally, the Makefile produces the fully linked, relocatable <code class="docutils literal notranslate"><span class="pre">hello</span></code> |
| ELF binary using the <code class="docutils literal notranslate"><span class="pre">defines.ld</span></code> linker script.</p></li> |
| </ol> |
| <p>Here are the contents of the <code class="docutils literal notranslate"><span class="pre">mkdefines.sh</span></code> script used in this example:</p> |
| <div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="ch">#!/bin/bash</span> |
| |
| <span class="nv">usage</span><span class="o">=</span><span class="s2">"Usage: </span><span class="nv">$0</span><span class="s2"> <system-map> <relprog>"</span> |
| |
| <span class="c1"># Check for the required path to the System.map file</span> |
| |
| <span class="nv">sysmap</span><span class="o">=</span><span class="nv">$1</span> |
| <span class="k">if</span><span class="w"> </span><span class="o">[</span><span class="w"> </span>-z<span class="w"> </span><span class="s2">"</span><span class="nv">$sysmap</span><span class="s2">"</span><span class="w"> </span><span class="o">]</span><span class="p">;</span><span class="w"> </span><span class="k">then</span> |
| <span class="nb">echo</span><span class="w"> </span><span class="s2">"ERROR: Missing <system-map>"</span> |
| <span class="nb">echo</span><span class="w"> </span><span class="s2">""</span> |
| <span class="nb">echo</span><span class="w"> </span><span class="s2">"</span><span class="nv">$usage</span><span class="s2">"</span> |
| <span class="nb">exit</span><span class="w"> </span><span class="m">1</span> |
| <span class="k">fi</span> |
| |
| <span class="c1"># Check for the required partially linked file</span> |
| |
| <span class="nv">relprog</span><span class="o">=</span><span class="nv">$2</span> |
| <span class="k">if</span><span class="w"> </span><span class="o">[</span><span class="w"> </span>-z<span class="w"> </span><span class="s2">"</span><span class="nv">$relprog</span><span class="s2">"</span><span class="w"> </span><span class="o">]</span><span class="p">;</span><span class="w"> </span><span class="k">then</span> |
| <span class="nb">echo</span><span class="w"> </span><span class="s2">"ERROR: Missing <program-list>"</span> |
| <span class="nb">echo</span><span class="w"> </span><span class="s2">""</span> |
| <span class="nb">echo</span><span class="w"> </span><span class="s2">"</span><span class="nv">$usage</span><span class="s2">"</span> |
| <span class="nb">exit</span><span class="w"> </span><span class="m">1</span> |
| <span class="k">fi</span> |
| |
| <span class="c1"># Verify the System.map and the partially linked file</span> |
| |
| <span class="k">if</span><span class="w"> </span><span class="o">[</span><span class="w"> </span>!<span class="w"> </span>-r<span class="w"> </span><span class="s2">"</span><span class="nv">$sysmap</span><span class="s2">"</span><span class="w"> </span><span class="o">]</span><span class="p">;</span><span class="w"> </span><span class="k">then</span> |
| <span class="nb">echo</span><span class="w"> </span><span class="s2">"ERROR: </span><span class="nv">$sysmap</span><span class="s2"> does not exist"</span> |
| <span class="nb">echo</span><span class="w"> </span><span class="s2">""</span> |
| <span class="nb">echo</span><span class="w"> </span><span class="s2">"</span><span class="nv">$usage</span><span class="s2">"</span> |
| <span class="nb">exit</span><span class="w"> </span><span class="m">1</span> |
| <span class="k">fi</span> |
| |
| <span class="k">if</span><span class="w"> </span><span class="o">[</span><span class="w"> </span>!<span class="w"> </span>-r<span class="w"> </span><span class="s2">"</span><span class="nv">$relprog</span><span class="s2">"</span><span class="w"> </span><span class="o">]</span><span class="p">;</span><span class="w"> </span><span class="k">then</span> |
| <span class="nb">echo</span><span class="w"> </span><span class="s2">"ERROR: </span><span class="nv">$relprog</span><span class="s2"> does not exist"</span> |
| <span class="nb">echo</span><span class="w"> </span><span class="s2">""</span> |
| <span class="nb">echo</span><span class="w"> </span><span class="s2">"</span><span class="nv">$usage</span><span class="s2">"</span> |
| <span class="nb">exit</span><span class="w"> </span><span class="m">1</span> |
| <span class="k">fi</span> |
| |
| <span class="c1"># Extract all of the undefined symbols from the partially linked file and create a</span> |
| <span class="c1"># list of sorted, unique undefined variable names.</span> |
| |
| <span class="nv">varlist</span><span class="o">=</span><span class="k">$(</span>nm<span class="w"> </span><span class="s2">"</span><span class="nv">$relprog</span><span class="s2">"</span><span class="w"> </span><span class="p">|</span><span class="w"> </span>grep<span class="w"> </span>-F<span class="w"> </span><span class="s1">' U '</span><span class="w"> </span><span class="p">|</span><span class="w"> </span>sed<span class="w"> </span>-e<span class="w"> </span><span class="s2">"s/^[ ]*//g"</span><span class="w"> </span><span class="p">|</span><span class="w"> </span>cut<span class="w"> </span>-d<span class="s1">' '</span><span class="w"> </span>-f2<span class="w"> </span><span class="p">|</span><span class="w"> </span>sort<span class="w"> </span>-<span class="w"> </span><span class="p">|</span><span class="w"> </span>uniq<span class="k">)</span> |
| |
| <span class="c1"># Now output the linker script that provides a value for all of the undefined symbols</span> |
| |
| <span class="k">for</span><span class="w"> </span>var<span class="w"> </span><span class="k">in</span><span class="w"> </span><span class="nv">$varlist</span><span class="p">;</span><span class="w"> </span><span class="k">do</span> |
| <span class="nv">map</span><span class="o">=</span><span class="k">$(</span>grep<span class="w"> </span><span class="s2">" </span><span class="si">${</span><span class="nv">var</span><span class="si">}</span>$<span class="s2">"</span><span class="w"> </span><span class="s2">"</span><span class="si">${</span><span class="nv">sysmap</span><span class="si">}</span><span class="s2">"</span><span class="k">)</span> |
| <span class="k">if</span><span class="w"> </span><span class="o">[</span><span class="w"> </span>-z<span class="w"> </span><span class="s2">"</span><span class="nv">$map</span><span class="s2">"</span><span class="w"> </span><span class="o">]</span><span class="p">;</span><span class="w"> </span><span class="k">then</span> |
| <span class="w"> </span><span class="nb">echo</span><span class="w"> </span><span class="s2">"ERROR: Variable </span><span class="nv">$var</span><span class="s2"> not found in </span><span class="nv">$sysmap</span><span class="s2">"</span> |
| <span class="w"> </span><span class="nb">echo</span><span class="w"> </span><span class="s2">""</span> |
| <span class="w"> </span><span class="nb">echo</span><span class="w"> </span><span class="s2">"</span><span class="nv">$usage</span><span class="s2">"</span> |
| <span class="w"> </span><span class="nb">exit</span><span class="w"> </span><span class="m">1</span> |
| <span class="k">fi</span> |
| |
| <span class="nv">varaddr</span><span class="o">=</span><span class="k">$(</span><span class="nb">echo</span><span class="w"> </span><span class="s2">"</span><span class="si">${</span><span class="nv">map</span><span class="si">}</span><span class="s2">"</span><span class="w"> </span><span class="p">|</span><span class="w"> </span>cut<span class="w"> </span>-d<span class="s1">' '</span><span class="w"> </span>-f1<span class="k">)</span> |
| <span class="nb">echo</span><span class="w"> </span><span class="s2">"</span><span class="si">${</span><span class="nv">var</span><span class="si">}</span><span class="s2"> = 0x</span><span class="si">${</span><span class="nv">varaddr</span><span class="si">}</span><span class="s2"> | 0x00000001;"</span> |
| <span class="k">done</span> |
| </pre></div> |
| </div> |
| <p>This script uses the <code class="docutils literal notranslate"><span class="pre">nm</span></code> utility to find all the undefined symbols in the |
| ELF binary, then searches for the address of each undefined symbol in the |
| <code class="docutils literal notranslate"><span class="pre">System.map</span></code> file that was created when the firmware was built. Finally, |
| it uses the symbols’ names and addresses to create each symbol table entry.</p> |
| <div class="admonition note"> |
| <p class="admonition-title">Note</p> |
| <p>For the ARMv7-M architecture, bit 0 of the address must be set to indicate |
| thumb mode. If you are using a different architecture that requires |
| normal aligned addresses, you will need to change the following line by |
| eliminating the ORed value:</p> |
| <div class="highlight-shell notranslate"><div class="highlight"><pre><span></span><span class="nb">echo</span><span class="w"> </span><span class="s2">"</span><span class="si">${</span><span class="nv">var</span><span class="si">}</span><span class="s2"> = 0x</span><span class="si">${</span><span class="nv">varaddr</span><span class="si">}</span><span class="s2"> | 0x00000001;"</span> |
| </pre></div> |
| </div> |
| </div> |
| <div class="admonition note"> |
| <p class="admonition-title">Note</p> |
| <p>If the new ELF binary uses a symbol that is not provided in the base |
| firmware (and hence not included in the <code class="docutils literal notranslate"><span class="pre">System.map</span></code> file) this script |
| will fail. In that case, you will need to provide the missing logic |
| within the ELF program itself, if possible.</p> |
| </div> |
| <div class="admonition important"> |
| <p class="admonition-title">Important</p> |
| <p>The technique described here is only valid in the FLAT build mode. It |
| could probably also be extended to work in the PROTECTED mode by |
| substituting <code class="docutils literal notranslate"><span class="pre">User.map</span></code> for <code class="docutils literal notranslate"><span class="pre">System.map</span></code>.</p> |
| </div> |
| <p>Here is a short example of a <code class="docutils literal notranslate"><span class="pre">defines.ld</span></code> script created by <code class="docutils literal notranslate"><span class="pre">mkdefines.sh</span></code>:</p> |
| <div class="highlight-shell notranslate"><div class="highlight"><pre><span></span><span class="nb">printf</span><span class="w"> </span><span class="o">=</span><span class="w"> </span>0x0800aefc<span class="w"> </span><span class="p">|</span><span class="w"> </span>0x00000001<span class="p">;</span> |
| </pre></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>Suppose, for example, that a built-in application called <code class="docutils literal notranslate"><span class="pre">hello</span></code> already |
| exist. Before the installation of the new replacement <code class="docutils literal notranslate"><span class="pre">hello</span></code> ELF program in |
| the file system, this is the version of <code class="docutils literal notranslate"><span class="pre">hello</span></code> that NSH will execute:</p> |
| <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>nsh> hello |
| Hello, World! |
| nsh> |
| </pre></div> |
| </div> |
| <p>Now suppose that we add our custom <code class="docutils literal notranslate"><span class="pre">hello</span></code> binary to the file system inside |
| the appropriate path (see <code class="docutils literal notranslate"><span class="pre">CONFIG_PATH_INITIAL</span></code> above). When NSH will attempt |
| to run the program called <code class="docutils literal notranslate"><span class="pre">hello</span></code>, it will prefer the new binary present on |
| the file system over the built-in version of the same program.</p> |
| <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>nsh> mount -t vfat /dev/mmcsd0 /bin |
| nsh> hello |
| Hello from a fully linked Add-On Program! |
| nsh> |
| </pre></div> |
| </div> |
| </section> |
| <section id="version-dependency"> |
| <h2>Version Dependency<a class="headerlink" href="#version-dependency" title="Permalink to this heading"></a></h2> |
| <div class="admonition warning"> |
| <p class="admonition-title">Warning</p> |
| <p>This technique generates ELF programs using fixed addresses from the |
| <code class="docutils literal notranslate"><span class="pre">System.map</span></code> file of a versioned release. The generated ELF programs can |
| only be used with that specific firmware version. A crash will most likely |
| happen if used with a different firmware version, because the addresses |
| from the <code class="docutils literal notranslate"><span class="pre">System.map</span></code> will not match.</p> |
| </div> |
| <p>The alternative approach using <a class="reference internal" href="partially_linked_elf.html"><span class="doc">Symbol Tables</span></a> is |
| more or less version independent.</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="partially_linked_elf.html" class="btn btn-neutral float-left" title="ELF Programs – With Symbol Tables" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a> |
| <a href="building_nuttx_with_app_out_of_src_tree.html" class="btn btn-neutral float-right" title="Building NuttX with Applications Outside the Source Tree" 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> |
