content/docs/10.0.1/components/nxflat.html - nuttx-website - Git at Google

 <!--
  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="viewport" content="width=device-width, initial-scale=1.0">

   <title>NXFLAT &mdash; NuttX latest documentation</title>


   <link rel="stylesheet" href="../_static/css/theme.css" type="text/css" />
   <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
   <link rel="stylesheet" href="../_static/sphinx_tabs/semantic-ui-2.4.1/segment.min.css" type="text/css" />
   <link rel="stylesheet" href="../_static/sphinx_tabs/semantic-ui-2.4.1/menu.min.css" type="text/css" />
   <link rel="stylesheet" href="../_static/sphinx_tabs/semantic-ui-2.4.1/tab.min.css" type="text/css" />
   <link rel="stylesheet" href="../_static/sphinx_tabs/tabs.css" type="text/css" />
   <link rel="stylesheet" href="../_static/custom.css" type="text/css" />


     <link rel="shortcut icon" href="../_static/favicon.ico"/>


   <!--[if lt IE 9]>
     <script src="../_static/js/html5shiv.min.js"></script>
   <![endif]-->


       <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
         <script src="../_static/jquery.js"></script>
         <script src="../_static/underscore.js"></script>
         <script src="../_static/doctools.js"></script>
         <script src="../_static/language_data.js"></script>

     <script type="text/javascript" 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="NX Graphics Subsystem" href="nxgraphics/index.html" />
     <link rel="prev" title="NuttX File System" href="filesystem.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


     <img src="../_static/NuttX.png" class="logo" alt="Logo"/>

   </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" />
     <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="main navigation">


               <p class="caption"><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="../introduction/inviolables.html">The Inviolable Principles of NuttX</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../quickstart/index.html">Getting Started</a></li>
 <li class="toctree-l1 current"><a class="reference internal" href="index.html">OS Components</a><ul class="current">
 <li class="toctree-l2"><a class="reference internal" href="nsh/index.html">NuttShell (NSH)</a></li>
 <li class="toctree-l2"><a class="reference internal" href="power.html">Power Management</a></li>
 <li class="toctree-l2"><a class="reference internal" href="socketcan.html">SocketCAN Device Drivers</a></li>
 <li class="toctree-l2"><a class="reference internal" href="syslog.html">SYSLOG</a></li>
 <li class="toctree-l2"><a class="reference internal" href="binfmt.html">Binary Loader</a></li>
 <li class="toctree-l2"><a class="reference internal" href="drivers/index.html">Device Drivers</a></li>
 <li class="toctree-l2"><a class="reference internal" href="filesystem.html">NuttX File System</a></li>
 <li class="toctree-l2 current"><a class="current reference internal" href="#">NXFLAT</a><ul>
 <li class="toctree-l3"><a class="reference internal" href="#overview">Overview</a><ul>
 <li class="toctree-l4"><a class="reference internal" href="#functionality">Functionality</a></li>
 <li class="toctree-l4"><a class="reference internal" href="#background">Background</a></li>
 <li class="toctree-l4"><a class="reference internal" href="#limitations">Limitations</a></li>
 <li class="toctree-l4"><a class="reference internal" href="#supported-processors">Supported Processors</a></li>
 <li class="toctree-l4"><a class="reference internal" href="#development-status">Development Status</a></li>
 </ul>
 </li>
 <li class="toctree-l3"><a class="reference internal" href="#nxflat-toolchain">NXFLAT Toolchain</a><ul>
 <li class="toctree-l4"><a class="reference internal" href="#building-the-nxflat-toolchain">Building the NXFLAT Toolchain</a></li>
 <li class="toctree-l4"><a class="reference internal" href="#mknxflat">mknxflat</a></li>
 <li class="toctree-l4"><a class="reference internal" href="#ldnxflat">ldnxflat</a></li>
 <li class="toctree-l4"><a class="reference internal" href="#mksymtab">mksymtab</a></li>
 <li class="toctree-l4"><a class="reference internal" href="#making-an-nxflat-module">Making an NXFLAT module</a></li>
 </ul>
 </li>
 <li class="toctree-l3"><a class="reference internal" href="#appendix-a-no-got-operation">Appendix A: No GOT Operation</a></li>
 <li class="toctree-l3"><a class="reference internal" href="#appendix-b-pic-text-workaround">Appendix B: PIC Text Workaround</a></li>
 </ul>
 </li>
 <li class="toctree-l2"><a class="reference internal" href="nxgraphics/index.html">NX Graphics Subsystem</a></li>
 <li class="toctree-l2"><a class="reference internal" href="nxwidgets.html">NxWidgets</a></li>
 <li class="toctree-l2"><a class="reference internal" href="paging.html">On-Demand Paging</a></li>
 </ul>
 </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="../boards/index.html">Supported Boards</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="../guides/index.html">Guides</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../releases/index.html">Releases</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="../glossary.html">Glossary</a></li>
 </ul>


         </div>

       </div>
     </nav>

     <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">


       <nav class="wy-nav-top" aria-label="top navigation">

           <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="breadcrumbs navigation">

   <ul class="wy-breadcrumbs">

       <li><a href="../index.html" class="icon icon-home"></a> &raquo;</li>

           <li><a href="index.html">OS Components</a> &raquo;</li>

       <li>NXFLAT</li>


       <li class="wy-breadcrumbs-aside">


             <a href="../_sources/components/nxflat.rst.txt" rel="nofollow"> View page source</a>


       </li>

   </ul>


   <hr/>
 </div>
           <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
            <div itemprop="articleBody">

   <div class="section" id="nxflat">
 <h1>NXFLAT<a class="headerlink" href="#nxflat" title="Permalink to this headline">¶</a></h1>
 <div class="section" id="overview">
 <h2>Overview<a class="headerlink" href="#overview" title="Permalink to this headline">¶</a></h2>
 <div class="section" id="functionality">
 <h3>Functionality<a class="headerlink" href="#functionality" title="Permalink to this headline">¶</a></h3>
 <p>NXFLAT is a customized and simplified version of binary format
 implemented a few years ago called
 <a class="reference external" href="http://xflat.sourceforge.net/">XFLAT</a> With the NXFLAT binary format
 you will be able to do the following:</p>
 <blockquote>
 <div><ul class="simple">
 <li><p>Place separately linked programs in a file system, and</p></li>
 <li><p>Execute those programs by dynamically linking them to the base NuttX
 code.</p></li>
 </ul>
 </div></blockquote>
 <p>This allows you to extend the NuttX base code after it has been written
 into FLASH. One motivation for implementing NXFLAT is support clean CGI
 under an HTTPD server.</p>
 <p>This feature is especially attractive when combined with the NuttX ROMFS
 support: ROMFS allows you to execute programs in place (XIP) in flash
 without copying anything other than the .data section to RAM. In fact,
 the initial NXFLAT release only worked on ROMFS. Later extensions also
 support execution NXFLAT binaries from an SRAM copy as well.</p>
 <p>This NuttX feature includes:</p>
 <blockquote>
 <div><ul class="simple">
 <li><p>A dynamic loader that is built into the NuttX core (See
 <a class="reference external" href="https://bitbucket.org/nuttx/nuttx/src/master/binfmt/">GIT</a>).</p></li>
 <li><p>Minor changes to RTOS to support position independent code, and</p></li>
 <li><p>A linker to bind ELF binaries to produce the NXFLAT binary format
 (See GIT).</p></li>
 </ul>
 </div></blockquote>
 </div>
 <div class="section" id="background">
 <h3>Background<a class="headerlink" href="#background" title="Permalink to this headline">¶</a></h3>
 <p>NXFLAT is derived from <a class="reference external" href="http://xflat.sourceforge.net/">XFLAT</a>. XFLAT
 is a toolchain add that provides full shared library and XIP executable
 support for processors that have no Memory Management Unit
 (MMU:sup:<cite>1</cite>). NXFLAT is greatly simplified for the deeply embedded
 environment targeted by Nuttx:</p>
 <blockquote>
 <div><ul class="simple">
 <li><p>NXFLAT does not support shared libraries, because</p></li>
 <li><p>NXFLAT does not support <em>exportation</em> of symbol values from a module</p></li>
 </ul>
 </div></blockquote>
 <p>Rather, the NXFLAT module only <em>imports</em> symbol values. In the NXFLAT
 model, the (PIC:sup:<cite>2</cite>) NXFLAT module resides in a FLASH file system
 and when it is loaded at run time, it is dynamically linked only to the
 (non-PIC) base NuttX code: The base NuttX <em>exports</em> a symbol table; the
 NXFLAT module <em>imports</em> those symbol value to dynamically bind the
 module to the base code.</p>
 </div>
 <div class="section" id="limitations">
 <h3>Limitations<a class="headerlink" href="#limitations" title="Permalink to this headline">¶</a></h3>
 <blockquote>
 <div><ul>
 <li><p><strong>ROMFS (or RAM mapping) Only</strong>:
 The current NXFLAT release will work only with either (1) NXFLAT
 executable modules residing on a ROMFS file system, or (2) executables
 residing on other file systems provided that CONFIG_FS_RAMMAP is
 defined. This limitation is because the loader depends on the capability
 to mmap() the code segment. See the NuttX User Guide for further information.</p>
 <p>NUTTX does not provide any general kind of file mapping capability.
 In fact, true file mapping is only possible with MCUs that provide an MMU1.
 Without an MMU, file system may support eXecution In Place (XIP) to mimic
 file mapping. Only the ROMFS file system supports that kind of XIP execution
 need by NXFLAT.</p>
 <p>It is also possible to simulate file mapping by allocating memory, copying
 the NXFLAT binary file into memory, and executing from the copy of the
 executable file in RAM. That capability can be enabled with the CONFIG_FS_RAMMAP
 configuration option. With that option enabled, NXFLAT will work that kind
 of file system but will require copying of all NXFLAT executables to RAM.</p>
 </li>
 <li><p><strong>GCC/ARM/Cortex-M3/4 Only</strong>:
 At present, the NXFLAT toolchain is only available for ARM and Cortex-M3/4 (thumb2) targets.</p></li>
 <li><p><strong>Read-Only Data in RAM</strong>:
 With older GCC compilers (at least up to 4.3.3), read-only data must
 reside in RAM. In code generated by GCC, all data references are
 indexed by the PIC2 base register (that is usually R10 or sl for the
 ARM processors). The includes read-only data (.rodata). Embedded
 firmware developers normally like to keep .rodata in FLASH with
 the code sections. But because all data is referenced with the
 PIC base register, all of that data must lie in RAM. A NXFLAT
 change to work around this is under investigation3.</p>
 <p>Newer GCC compilers (at least from 4.6.3), read-only data is
 no long GOT-relative, but is now accessed PC-relative.
 With PC relative addressing, read-only data must reside in the I-Space.</p>
 </li>
 <li><p><strong>Globally Scoped Function Function Pointers</strong>:
 If a function pointer is taken to a statically defined function,
 then (at least for ARM) GCC will generate a relocation that NXFLAT
 cannot handle. The workaround is make all such functions global in
 scope. A fix would involve a change to the GCC compiler as described
 in Appendix B.</p></li>
 <li><p><strong>Special Handling of Callbacks</strong>:
 Callbacks through function pointers must be avoided or, when
 then cannot be avoided, handled very specially. The reason
 for this is that the PIC module requires setting of a special
 value in a PIC register. If the callback does not set the PIC
 register, then the called back function will fail because it
 will be unable to correctly access data memory. Special logic
 is in place to handle some NuttX callbacks: Signal callbacks
 and watchdog timer callbacks. But other callbacks (like those
 used with qsort() must be avoided in an NXFLAT module.</p></li>
 </ul>
 </div></blockquote>
 </div>
 <div class="section" id="supported-processors">
 <h3>Supported Processors<a class="headerlink" href="#supported-processors" title="Permalink to this headline">¶</a></h3>
 <p>As mentioned <a class="reference external" href="#limitations">above</a>, the NXFLAT toolchain is only
 available for ARM and Cortex-M3 (thumb2) targets. Furthermore, NXFLAT
 has only been tested on the Eagle-100 LMS6918 Cortex-M3 board.</p>
 </div>
 <div class="section" id="development-status">
 <h3>Development Status<a class="headerlink" href="#development-status" title="Permalink to this headline">¶</a></h3>
 <p>The initial release of NXFLAT was made in NuttX version 0.4.9. Testing
 is limited to the tests found under <code class="docutils literal notranslate"><span class="pre">apps/examples/nxflat</span></code> in the
 source tree. Some known problems exist (see the
 <a class="reference external" href="https://bitbucket.org/nuttx/nuttx/src/master/TODO">TODO</a> list). As
 such, NXFLAT is currently in an early alpha phase.</p>
 </div>
 </div>
 <div class="section" id="nxflat-toolchain">
 <h2>NXFLAT Toolchain<a class="headerlink" href="#nxflat-toolchain" title="Permalink to this headline">¶</a></h2>
 <div class="section" id="building-the-nxflat-toolchain">
 <h3>Building the NXFLAT Toolchain<a class="headerlink" href="#building-the-nxflat-toolchain" title="Permalink to this headline">¶</a></h3>
 <p>In order to use NXFLAT, you must use special NXFLAT tools to create the
 binary module in FLASH. To do this, you will need to download the
 buildroot package and build it on your Linux or Cygwin machine. The
 buildroot can be downloaded from
 <a class="reference external" href="https://bitbucket.org/nuttx/buildroot/downloads">Bitbucket.org</a>. You
 will need version 0.1.7 or later.</p>
 <p>Here are some general build instructions:</p>
 <ul class="simple">
 <li><p>You must have already configured Nuttx in <code class="docutils literal notranslate"><span class="pre">&lt;some-dir&gt;/nuttx</span></code></p></li>
 <li><p>Download the buildroot package <code class="docutils literal notranslate"><span class="pre">buildroot-0.x.y</span></code> into
 <code class="docutils literal notranslate"><span class="pre">&lt;some-dir&gt;</span></code></p></li>
 <li><p>Unpack <code class="docutils literal notranslate"><span class="pre">&lt;some-dir&gt;/buildroot-0.x.y.tar.gz</span></code> using a command like <code class="docutils literal notranslate"><span class="pre">tar</span> <span class="pre">zxf</span> <span class="pre">buildroot-0.x.y</span></code>. This will result in a new directory like <code class="docutils literal notranslate"><span class="pre">&lt;some-dir&gt;/buildroot-0.x.y</span></code></p></li>
 <li><p>Move this into position:
 <code class="docutils literal notranslate"><span class="pre">mv</span> <span class="pre">&lt;some-dir&gt;/buildroot-0.x.y</span></code>&lt;some-dir&gt;/buildroot</p></li>
 <li><p><code class="docutils literal notranslate"><span class="pre">cd</span></code>&lt;some-dir&gt;/buildroot</p></li>
 <li><p>Copy a configuration file into the top buildroot directory:
 <code class="docutils literal notranslate"><span class="pre">cp</span> <span class="pre">boards/abc-defconfig-x.y.z</span> <span class="pre">.config</span></code>.</p></li>
 <li><p>Enable building of the NXFLAT tools by <code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">menuconfig</span></code>. Select to
 build the NXFLAT toolchain with GCC (you can also select omit
 building GCC with and only build the NXFLAT toolchain for use with
 your own GCC toolchain).</p></li>
 <li><p>Make the toolchain: <code class="docutils literal notranslate"><span class="pre">make</span></code>. When the make completes, the tool
 binaries will be available under
 <code class="docutils literal notranslate"><span class="pre">&lt;some-dir&gt;/buildroot/build_abc/staging_dir/bin</span></code></p></li>
 </ul>
 </div>
 <div class="section" id="mknxflat">
 <h3>mknxflat<a class="headerlink" href="#mknxflat" title="Permalink to this headline">¶</a></h3>
 <p><code class="docutils literal notranslate"><span class="pre">mknxflat</span></code> is used to build a <em>thunk</em> file. See below
 for usage:</p>
 <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>Usage: mknxflat [options] &lt;bfd-filename&gt;

 Where options are one or more of the following.  Note
 that a space is always required between the option and
 any following arguments.

   -d Use dynamic symbol table. [symtab]
   -f &lt;cmd-filename&gt;
       Take next commands from &lt;cmd-filename&gt; [cmd-line]
   -o &lt;out-filename&gt;
      Output to  [stdout]
   -v Verbose output [no output]
   -w Import weakly declared functions, i.e., weakly
      declared functions are expected to be provided at
      load-time [not imported]
 </pre></div>
 </div>
 </div>
 <div class="section" id="ldnxflat">
 <h3>ldnxflat<a class="headerlink" href="#ldnxflat" title="Permalink to this headline">¶</a></h3>
 <p><code class="docutils literal notranslate"><span class="pre">ldnxflat</span></code> is use to link your object files along with the <em>thunk</em>
 file generated by <code class="docutils literal notranslate"><span class="pre">mknxflat</span></code> to produce the NXFLAT
 binary module. See below for usage:</p>
 <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>Usage: ldnxflat [options] &lt;bfd-filename&gt;

 Where options are one or more of the following.  Note
 that a space is always required between the option and
 any following arguments.

   -d Use dynamic symbol table [Default: symtab]
   -e &lt;entry-point&gt;
      Entry point to module [Default: _start]
   -o &lt;out-filename&gt;
      Output to &lt;out-filename&gt; [Default: &lt;bfd-filename&gt;.nxf]
   -s &lt;stack-size&gt;
      Set stack size to &lt;stack-size&gt; [Default: 4096]
   -v Verbose output. If -v is applied twice, additional
      debug output is enabled [Default: no verbose output].
 </pre></div>
 </div>
 </div>
 <div class="section" id="mksymtab">
 <h3>mksymtab<a class="headerlink" href="#mksymtab" title="Permalink to this headline">¶</a></h3>
 <p>There is a small helper program available in <code class="docutils literal notranslate"><span class="pre">nuttx/tools</span></code> call
 <code class="docutils literal notranslate"><span class="pre">mksymtab</span></code>. <code class="docutils literal notranslate"><span class="pre">mksymtab</span></code> can be sued to generate symbol tables for the
 NuttX base code that would be usable by the typical NXFLAT application.
 <code class="docutils literal notranslate"><span class="pre">mksymtab</span></code> builds symbol tables from common-separated value (CSV)
 files. In particular, the CSV files:</p>
 <blockquote>
 <div><ol class="arabic simple">
 <li><p><code class="docutils literal notranslate"><span class="pre">nuttx/syscall/syscall.csv</span></code> that describes the NuttX RTOS
 interface, and</p></li>
 <li><p><code class="docutils literal notranslate"><span class="pre">nuttx/libc/libc.csv</span></code> that describes the NuttX C library interface.</p></li>
 <li><p><code class="docutils literal notranslate"><span class="pre">nuttx/libc/math.cvs</span></code> that descirbes any math library.</p></li>
 </ol>
 </div></blockquote>
 <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>USAGE: ./mksymtab &lt;cvs-file&gt; &lt;symtab-file&gt;

 Where:

   &lt;cvs-file&gt;   : The path to the input CSV file
   &lt;symtab-file&gt;: The path to the output symbol table file
   -d           : Enable debug output
 </pre></div>
 </div>
 <p>For example,</p>
 <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>cd nuttx/tools
 cat ../syscall/syscall.csv ../libc/libc.csv | sort &gt;tmp.csv
 ./mksymtab.exe tmp.csv tmp.c
 </pre></div>
 </div>
 </div>
 <div class="section" id="making-an-nxflat-module">
 <h3>Making an NXFLAT module<a class="headerlink" href="#making-an-nxflat-module" title="Permalink to this headline">¶</a></h3>
 <p>Below is a snippet from an NXFLAT make file (simplified from NuttX
 <a class="reference external" href="https://bitbucket.org/nuttx/apps/src/master/apps/examples/nxflat/tests/hello/Makefile">Hello,
 World!</a>
 example).</p>
 <ul>
 <li><p>Target 1:</p>
 <div class="highlight-makefile notranslate"><div class="highlight"><pre><span></span><span class="nf">hello.r1</span><span class="o">:</span> <span class="n">hello</span>.<span class="n">o</span>
   abc-nuttx-elf-ld -r -d -warn-common -o <span class="nv">$@</span> $^
 </pre></div>
 </div>
 </li>
 <li><p>Target 2:</p>
 <div class="highlight-makefile notranslate"><div class="highlight"><pre><span></span><span class="nf">hello-thunk.S</span><span class="o">:</span> <span class="n">hello</span>.<span class="n">r</span>1
   mknxflat -o <span class="nv">$@</span> $^
 </pre></div>
 </div>
 </li>
 <li><p>Target 3:</p>
 <div class="highlight-makefile notranslate"><div class="highlight"><pre><span></span><span class="nf">hello.r2</span><span class="o">:</span> <span class="n">hello</span>-<span class="n">thunk</span>.<span class="n">S</span>
   abc-nuttx-elf-ld -r -d -warn-common -T binfmt/libnxflat/gnu-nxflat-gotoff.ld -no-check-sections -o <span class="nv">$@</span> hello.o hello-thunk.o
 </pre></div>
 </div>
 </li>
 <li><p>Target 4:</p>
 <div class="highlight-makefile notranslate"><div class="highlight"><pre><span></span><span class="nf">hello</span><span class="o">:</span> <span class="n">hello</span>.<span class="n">r</span>2
   ldnxflat -e main -s <span class="m">2048</span> -o <span class="nv">$@</span> $^
 </pre></div>
 </div>
 </li>
 </ul>
 <p><strong>Target 1</strong>. This target links all of the module’s object files
 together into one relocatable object. Two relocatable objects will be
 generated; this is the first one (hence, the suffic <code class="docutils literal notranslate"><span class="pre">.r1</span></code>). In this
 “Hello, World!” case, there is only a single object file, <code class="docutils literal notranslate"><span class="pre">hello.o</span></code>,
 that is linked to produce the <code class="docutils literal notranslate"><span class="pre">hello.r1</span></code> object.</p>
 <p>When the module’s object files are compiled, some special compiler
 CFLAGS must be provided. First, the option <code class="docutils literal notranslate"><span class="pre">-fpic</span></code> is required to tell
 the compiler to generate position independent code (other GCC options,
 like <code class="docutils literal notranslate"><span class="pre">-fno-jump-tables</span></code> might also be desirable). For ARM compilers,
 two additional compilation options are required: <code class="docutils literal notranslate"><span class="pre">-msingle-pic-base</span></code>
 and <code class="docutils literal notranslate"><span class="pre">-mpic-register=r10</span></code>.</p>
 <p><strong>Target 2</strong>. Given the <code class="docutils literal notranslate"><span class="pre">hello.r1</span></code> relocatable object, this target
 will invoke <code class="docutils literal notranslate"><span class="pre">`mknxflat</span></code> &lt;#mknxflat&gt;`__ to make the <em>thunk</em> file,
 <code class="docutils literal notranslate"><span class="pre">hello-thunk.S</span></code>. This <em>thunk</em> file contains all of the information
 needed to create the imported function list.</p>
 <p><strong>Target 3</strong> This target is similar to <strong>Target 1</strong>. In this case, it
 will link together the module’s object files (only <code class="docutils literal notranslate"><span class="pre">hello.o</span></code> here)
 along with the assembled <em>thunk</em> file, <code class="docutils literal notranslate"><span class="pre">hello-thunk.o</span></code> to create the
 second relocatable object, <code class="docutils literal notranslate"><span class="pre">hello.r2</span></code>. The linker script,
 <code class="docutils literal notranslate"><span class="pre">gnu-nxflat-gotoff.ld</span></code> is required at this point to correctly position
 the sections. This linker script produces two segments: An <em>I-Space</em>
 (Instruction Space) segment containing mostly <code class="docutils literal notranslate"><span class="pre">.text</span></code> and a <em>D-Space</em>
 (Data Space) segment containing <code class="docutils literal notranslate"><span class="pre">.got</span></code>, <code class="docutils literal notranslate"><span class="pre">.data</span></code>, and <code class="docutils literal notranslate"><span class="pre">.bss</span></code>
 sections. The I-Space section must be origined at address 0 (so that the
 segment’s addresses are really offsets into the I-Space segment) and the
 D-Space section must also be origined at address 0 (so that segment’s
 addresses are really offsets into the I-Space segment). The option
 <code class="docutils literal notranslate"><span class="pre">-no-check-sections</span></code> is required to prevent the linker from failing
 because these segments overlap.</p>
 <p><strong>NOTE:</strong> There are two linker scripts located at <code class="docutils literal notranslate"><span class="pre">binfmt/libnxflat/</span></code>.</p>
 <blockquote>
 <div><ol class="arabic simple">
 <li><p><code class="docutils literal notranslate"><span class="pre">binfmt/libnxflat/gnu-nxflat-gotoff.ld</span></code>. Older versions of GCC
 (at least up to GCC 4.3.3), use GOT-relative addressing to access RO
 data. In that case, read-only data (.rodata) must reside in D-Space
 and this linker script should be used.</p></li>
 <li><p><code class="docutils literal notranslate"><span class="pre">binfmt/libnxflat/gnu-nxflat-pcrel.ld</span></code>. Newer versions of GCC
 (at least as of GCC 4.6.3), use PC-relative addressing to access RO
 data. In that case, read-only data (.rodata) must reside in I-Space
 and this linker script should be used.</p></li>
 </ol>
 </div></blockquote>
 <p><strong>Target 4</strong>. Finally, this target will use the <code class="docutils literal notranslate"><span class="pre">hello.r2</span></code> relocatable
 object to create the final, NXFLAT module <code class="docutils literal notranslate"><span class="pre">hello</span></code> by executing
 <code class="docutils literal notranslate"><span class="pre">ldnxflat</span></code>.</p>
 <p><strong>binfmt Registration</strong> NXFLAT calls <a class="reference internal" href="binfmt.html#c.register_binfmt" title="register_binfmt"><code class="xref c c-func docutils literal notranslate"><span class="pre">register_binfmt()</span></code></a> to
 incorporate itself into the system.</p>
 </div>
 </div>
 <div class="section" id="appendix-a-no-got-operation">
 <h2>Appendix A: No GOT Operation<a class="headerlink" href="#appendix-a-no-got-operation" title="Permalink to this headline">¶</a></h2>
 <p>When GCC generate position independent code, new code sections will
 appear in your programs. One of these is the GOT (Global Offset Table)
 and, in ELF environments, another is the PLT (Procedure Lookup Table.
 For example, if your C code generated (ARM) assembly language like this
 without PIC:</p>
 <div class="highlight-asm notranslate"><div class="highlight"><pre><span></span>        <span class="nf">ldr</span>     <span class="no">r1</span><span class="p">,</span> <span class="no">.L0</span>         <span class="cm">/* Fetch the offset to &#39;x&#39; */</span>
         <span class="nf">ldr</span>     <span class="no">r0</span><span class="p">,</span> <span class="p">[</span><span class="no">r10</span><span class="p">,</span> <span class="no">r1</span><span class="p">]</span>   <span class="cm">/* Load the value of &#39;x&#39; with PIC offset */</span>
         <span class="cm">/* ... */</span>
 <span class="nl">.L0:</span>    <span class="na">.word</span>   <span class="no">x</span>               <span class="cm">/* Offset to &#39;x&#39; */</span>
 </pre></div>
 </div>
 <p>Then when PIC is enabled (say with the -fpic compiler option), it will
 generate code like this:</p>
 <div class="highlight-asm notranslate"><div class="highlight"><pre><span></span>        <span class="nf">ldr</span>     <span class="no">r1</span><span class="p">,</span> <span class="no">.L0</span>         <span class="cm">/* Fetch the offset to the GOT entry */</span>
         <span class="nf">ldr</span>     <span class="no">r1</span><span class="p">,</span> <span class="p">[</span><span class="no">r10</span><span class="p">,</span> <span class="no">r1</span><span class="p">]</span>   <span class="cm">/* Fetch the (relocated) address of &#39;x&#39; from the GOT */</span>
         <span class="nf">ldr</span>     <span class="no">r0</span><span class="p">,</span> <span class="p">[</span><span class="no">r1</span><span class="p">,</span> <span class="c1">#0]    /* Fetch the value of &#39;x&#39; */</span>
         <span class="cm">/* ... */</span>
 <span class="na">.L1</span>     <span class="no">.word</span>   <span class="no">x</span><span class="p">(</span><span class="no">GOT</span><span class="p">)</span>          <span class="cm">/* Offset to entry in the GOT */</span>
 </pre></div>
 </div>
 <p>See
 <a class="reference external" href="http://xflat.sourceforge.net/NoMMUSharedLibs.html#shlibsgot">reference</a></p>
 <p>Notice that the generates an extra level of indirection through the GOT.
 This indirection is not needed by NXFLAT and only adds more RAM usage
 and execution time.</p>
 <p>NXFLAT (like <a class="reference external" href="http://xflat.sourceforge.net/">XFLAT</a>) can work even
 better without the GOT. Patches against older version of GCC exist to
 eliminate the GOT indirections. Several are available
 <a class="reference external" href="http://xflat.cvs.sourceforge.net/viewvc/xflat/xflat/gcc/">here</a> if
 you are inspired to port them to a new GCC version.</p>
 </div>
 <div class="section" id="appendix-b-pic-text-workaround">
 <h2>Appendix B: PIC Text Workaround<a class="headerlink" href="#appendix-b-pic-text-workaround" title="Permalink to this headline">¶</a></h2>
 <p>There is a problem with the memory model in GCC that prevents it from
 being used as you need to use it in the NXFLAT context. The problem is
 that GCC PIC model assumes that the executable lies in a flat,
 contiguous (virtual) address space like:</p>
 <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>Virtual
 .text
 .got
 .data
 .bss
 </pre></div>
 </div>
 <p>It assumes that the PIC base register (usually r10 for ARM) points to
 the base of <code class="docutils literal notranslate"><span class="pre">.text</span></code> so that any address in <code class="docutils literal notranslate"><span class="pre">.text</span></code>, <code class="docutils literal notranslate"><span class="pre">.got</span></code>,
 <code class="docutils literal notranslate"><span class="pre">.data</span></code>, <code class="docutils literal notranslate"><span class="pre">.bss</span></code> can be found with an offset from the same base
 address. But that is not the memory arrangement that we need in the XIP
 embedded environment. We need two memory regions, one in FLASH
 containing shared code and on per task in RAM containing task-specific
 data:</p>
 <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>Flash   RAM
 .text   .got
         .data
         .bss
 </pre></div>
 </div>
 <p>The PIC base register needs to point to the base of the <code class="docutils literal notranslate"><span class="pre">.got</span></code> and
 only addresses in the <code class="docutils literal notranslate"><span class="pre">.got</span></code>, <code class="docutils literal notranslate"><span class="pre">.data</span></code>, and <code class="docutils literal notranslate"><span class="pre">.bss</span></code> sections can be
 accessed as an offset from the PIC base register. See also this <a class="reference external" href="http://xflat.cvs.sourceforge.net/viewvc/*checkout*/xflat/xflat/gcc/README?revision=1.1.1.1">XFLAT
 discussion</a>.</p>
 <p>Patches against older version of GCC exist to correct this GCC behavior.
 Several are available
 <a class="reference external" href="http://xflat.cvs.sourceforge.net/viewvc/xflat/xflat/gcc/">here</a> if
 you are inspired to port them to a new GCC version.</p>
 </div>
 </div>


            </div>

           </div>
           <footer>


   <hr/>

   <div role="contentinfo">
     <p>

         &copy; Copyright 2020, The Apache Software Foundation

     </p>
   </div>

 </footer>

         </div>
       </div>

     </section>

   </div>


   <script type="text/javascript">
       jQuery(function () {
           SphinxRtdTheme.Navigation.enable(true);
       });
   </script>


 </body>
 </html>