| <!-- |
| 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.18.1: http://docutils.sourceforge.net/" /> |
| |
| <meta name="viewport" content="width=device-width, initial-scale=1.0" /> |
| <title>Memory Management — 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/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/js/theme.js"></script> |
| <link rel="index" title="Index" href="../../genindex.html" /> |
| <link rel="search" title="Search" href="../../search.html" /> |
| <link rel="next" title="Shared Memory Support" href="shm.html" /> |
| <link rel="prev" title="Work Queue Deadlocks" href="../net/wqueuedeadlocks.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 current"><a class="reference internal" href="../index.html">OS Components</a><ul class="current"> |
| <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="../nxflat.html">NXFLAT</a></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="../paging.html">On-Demand Paging</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="../audio/index.html">Audio Subsystem</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="../filesystem/index.html">NuttX File System</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="../libs/index.html">NuttX libraries</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="../net/index.html">Network Support</a></li> |
| <li class="toctree-l2 current"><a class="current reference internal" href="#">Memory Management</a><ul> |
| <li class="toctree-l3"><a class="reference internal" href="shm.html">Shared Memory Support</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="#standard-memory-management-functions">Standard Memory Management Functions</a><ul> |
| <li class="toctree-l4"><a class="reference internal" href="#standard-functions">Standard Functions</a></li> |
| <li class="toctree-l4"><a class="reference internal" href="#memory-models">Memory Models</a></li> |
| <li class="toctree-l4"><a class="reference internal" href="#multiple-heaps">Multiple Heaps</a></li> |
| <li class="toctree-l4"><a class="reference internal" href="#user-kernel-heaps">User/Kernel Heaps</a></li> |
| <li class="toctree-l4"><a class="reference internal" href="#sub-directories">Sub-Directories</a></li> |
| <li class="toctree-l4"><a class="reference internal" href="#debugging">Debugging</a></li> |
| </ul> |
| </li> |
| <li class="toctree-l3"><a class="reference internal" href="#granule-allocator">Granule Allocator</a><ul> |
| <li class="toctree-l4"><a class="reference internal" href="#general-usage-example">General Usage Example</a></li> |
| </ul> |
| </li> |
| <li class="toctree-l3"><a class="reference internal" href="#page-allocator">Page Allocator</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="#shared-memory-management">Shared Memory Management</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="#i-o-buffers">I/O Buffers</a></li> |
| </ul> |
| </li> |
| <li class="toctree-l2"><a class="reference internal" href="../syscall.html">Syscall Layer</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="../tools/index.html"><code class="docutils literal notranslate"><span class="pre">/tools</span></code> Host Tools</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="../arch/index.html">Architecture-Specific Code</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="../boards.html">Boards Support</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="../cmake.html">CMake Support</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="../openamp.html">OpenAMP Support</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="../video.html">Video Subsystem</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="../crypto.html">Crypto API Subsystem</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="../wireless.html">Wireless Subsystem</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="../../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="../../guides/index.html">Guides</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> |
| </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">OS Components</a></li> |
| <li class="breadcrumb-item active">Memory Management</li> |
| <li class="wy-breadcrumbs-aside"> |
| <a href="../../_sources/components/mm/index.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"> |
| |
| <section id="memory-management"> |
| <h1>Memory Management<a class="headerlink" href="#memory-management" title="Permalink to this heading"></a></h1> |
| <p>This page discusses the NuttX memory management logic.</p> |
| <div class="toctree-wrapper compound"> |
| <ul> |
| <li class="toctree-l1"><a class="reference internal" href="shm.html">Shared Memory Support</a></li> |
| </ul> |
| </div> |
| <section id="standard-memory-management-functions"> |
| <h2>Standard Memory Management Functions<a class="headerlink" href="#standard-memory-management-functions" title="Permalink to this heading"></a></h2> |
| <section id="standard-functions"> |
| <h3>Standard Functions<a class="headerlink" href="#standard-functions" title="Permalink to this heading"></a></h3> |
| <p>The standard memory management functions as prototyped in stdlib.h as |
| specified in the Base definitions volume of IEEE Std 1003.1-2001. This |
| include the files:</p> |
| <ul class="simple"> |
| <li><p>Standard Interfaces: <code class="docutils literal notranslate"><span class="pre">mm_malloc.c</span></code>, <code class="docutils literal notranslate"><span class="pre">mm_calloc.c</span></code>, <code class="docutils literal notranslate"><span class="pre">mm_realloc.c</span></code>, |
| <code class="docutils literal notranslate"><span class="pre">mm_memalign.c</span></code>, <code class="docutils literal notranslate"><span class="pre">mm_free.c</span></code></p></li> |
| <li><p>Less-Standard Interfaces: <code class="docutils literal notranslate"><span class="pre">mm_zalloc.c</span></code>, <code class="docutils literal notranslate"><span class="pre">mm_mallinfo.c</span></code></p></li> |
| <li><p>Internal Implementation: <code class="docutils literal notranslate"><span class="pre">mm_initialize.c</span></code> <code class="docutils literal notranslate"><span class="pre">mm_sem.c</span></code> |
| <code class="docutils literal notranslate"><span class="pre">mm_addfreechunk.c</span></code> <code class="docutils literal notranslate"><span class="pre">mm_size2ndx.c</span></code> <code class="docutils literal notranslate"><span class="pre">mm_shrinkchunk.c</span></code></p></li> |
| <li><p>Build and Configuration files: <code class="docutils literal notranslate"><span class="pre">Kconfig</span></code>, <code class="docutils literal notranslate"><span class="pre">Makefile</span></code></p></li> |
| </ul> |
| </section> |
| <section id="memory-models"> |
| <h3>Memory Models<a class="headerlink" href="#memory-models" title="Permalink to this heading"></a></h3> |
| <ul> |
| <li><p>Small Memory Model. If the MCU supports only 16-bit data addressing |
| then the small memory model is automatically used. The maximum size |
| of the heap is then 64K. The small memory model can also be forced |
| MCUs with wider addressing by defining CONFIG_SMALL_MEMORY in the |
| NuttX configuration file.</p></li> |
| <li><p>Large Memory Model. Otherwise, the allocator uses a model that |
| supports a heap of up to 4G.</p> |
| <p>This implementation uses a variable length allocator with the following |
| properties:</p> |
| <blockquote> |
| <div><ul class="simple"> |
| <li><p>Overhead: Either 8- or 4-bytes per allocation for large and small |
| models, respectively.</p></li> |
| <li><p>Alignment: All allocations are aligned to 8- or 4-bytes for large |
| and small models, respectively.</p></li> |
| </ul> |
| </div></blockquote> |
| </li> |
| </ul> |
| </section> |
| <section id="multiple-heaps"> |
| <h3>Multiple Heaps<a class="headerlink" href="#multiple-heaps" title="Permalink to this heading"></a></h3> |
| <p>This allocator can be used to manage multiple heaps (albeit with some |
| non-standard interfaces). A heap is represented by <code class="docutils literal notranslate"><span class="pre">struct</span> <span class="pre">mm_heap_s</span></code> |
| as defined in the file <code class="docutils literal notranslate"><span class="pre">include/nuttx/mm/mm.h</span></code>. To create another heap |
| instance, you would allocate a heap structure, most likely statically |
| in memory:</p> |
| <div class="highlight-C notranslate"><div class="highlight"><pre><span></span><span class="n">include</span><span class="w"> </span><span class="o"><</span><span class="n">nuttx</span><span class="o">/</span><span class="n">mm</span><span class="o">/</span><span class="n">mm</span><span class="p">.</span><span class="n">h</span><span class="o">></span> |
| <span class="k">static</span><span class="w"> </span><span class="k">struct</span><span class="w"> </span><span class="nc">mm_heap_s</span><span class="w"> </span><span class="o">*</span><span class="n">g_myheap</span><span class="p">;</span> |
| </pre></div> |
| </div> |
| <p>Then initialize the heap using:</p> |
| <div class="highlight-C notranslate"><div class="highlight"><pre><span></span><span class="n">g_myheap</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">mm_initialize</span><span class="p">(</span><span class="n">myheap_start</span><span class="p">,</span><span class="w"> </span><span class="n">myheap_size</span><span class="p">);</span> |
| </pre></div> |
| </div> |
| <p>Where <code class="docutils literal notranslate"><span class="pre">mm_initialize()</span></code> and all related interfaces are prototyped in the |
| header file <code class="docutils literal notranslate"><span class="pre">include/nuttx/mm/mm.h</span></code>.</p> |
| <p>After the new heap instance has been initialized, it can then be used |
| with these almost familiar interfaces: <code class="docutils literal notranslate"><span class="pre">mm_malloc()</span></code>, <code class="docutils literal notranslate"><span class="pre">mm_realloc()</span></code>, |
| <code class="docutils literal notranslate"><span class="pre">mm_free()</span></code>, etc. These are ‘almost familiar’ because they are analogous |
| of the standard <code class="docutils literal notranslate"><span class="pre">malloc()</span></code>, <code class="docutils literal notranslate"><span class="pre">realloc()</span></code>, <code class="docutils literal notranslate"><span class="pre">free()</span></code>, etc. except that |
| they expect a reference to the initialized heap structure as the first |
| parameter.</p> |
| <p>In fact, the standard <code class="docutils literal notranslate"><span class="pre">malloc()</span></code>, <code class="docutils literal notranslate"><span class="pre">realloc()</span></code>, <code class="docutils literal notranslate"><span class="pre">free()</span></code> use this |
| same mechanism, but with a global heap structure called <code class="docutils literal notranslate"><span class="pre">g_mmheap</span></code>.</p> |
| </section> |
| <section id="user-kernel-heaps"> |
| <h3>User/Kernel Heaps<a class="headerlink" href="#user-kernel-heaps" title="Permalink to this heading"></a></h3> |
| <p>This multiple heap capability is exploited in some of the more complex NuttX |
| build configurations to provide separate kernel-mode and user-mode heaps.</p> |
| </section> |
| <section id="sub-directories"> |
| <h3>Sub-Directories<a class="headerlink" href="#sub-directories" title="Permalink to this heading"></a></h3> |
| <ul class="simple"> |
| <li><p><code class="docutils literal notranslate"><span class="pre">mm/mm_heap</span></code> - Holds the common base logic for all heap allocators</p></li> |
| <li><p><code class="docutils literal notranslate"><span class="pre">mm/umm_heap</span></code> - Holds the user-mode memory allocation interfaces</p></li> |
| <li><p><code class="docutils literal notranslate"><span class="pre">mm/kmm_heap</span></code> - Holds the kernel-mode memory allocation interfaces</p></li> |
| </ul> |
| </section> |
| <section id="debugging"> |
| <h3>Debugging<a class="headerlink" href="#debugging" title="Permalink to this heading"></a></h3> |
| <p>Please follow these steps to hook all memory related routines:</p> |
| <ol class="arabic"> |
| <li><p>Add a new header file(e.g. <code class="docutils literal notranslate"><span class="pre">xxx_malloc.h</span></code>):</p> |
| <div class="highlight-C notranslate"><div class="highlight"><pre><span></span><span class="p">...</span> |
| <span class="cp">#include</span><span class="w"> </span><span class="cpf"><malloc.h></span> |
| <span class="cp">#include</span><span class="w"> </span><span class="cpf"><stdlib.h></span> |
| <span class="cp">#include</span><span class="w"> </span><span class="cpf"><string.h></span> |
| <span class="cp">#include</span><span class="w"> </span><span class="cpf"><strings.h></span> |
| |
| <span class="cp">#ifndef __ASSEMBLY__</span> |
| <span class="n">FAR</span><span class="w"> </span><span class="kt">void</span><span class="w"> </span><span class="o">*</span><span class="n">xxx_malloc</span><span class="p">(</span><span class="n">FAR</span><span class="w"> </span><span class="k">const</span><span class="w"> </span><span class="kt">char</span><span class="w"> </span><span class="o">*</span><span class="n">file</span><span class="p">,</span><span class="w"> </span><span class="kt">int</span><span class="w"> </span><span class="n">line</span><span class="p">,</span><span class="w"> </span><span class="kt">size_t</span><span class="w"> </span><span class="n">size</span><span class="p">);</span> |
| <span class="kt">void</span><span class="w"> </span><span class="nf">xxx_free</span><span class="p">(</span><span class="n">FAR</span><span class="w"> </span><span class="k">const</span><span class="w"> </span><span class="kt">char</span><span class="w"> </span><span class="o">*</span><span class="n">file</span><span class="p">,</span><span class="w"> </span><span class="kt">int</span><span class="w"> </span><span class="n">line</span><span class="p">,</span><span class="w"> </span><span class="n">FAR</span><span class="w"> </span><span class="k">const</span><span class="w"> </span><span class="kt">void</span><span class="w"> </span><span class="o">*</span><span class="n">ptr</span><span class="p">);</span> |
| <span class="n">FAR</span><span class="w"> </span><span class="kt">void</span><span class="w"> </span><span class="o">*</span><span class="n">xxx_memcpy</span><span class="p">(</span><span class="n">FAR</span><span class="w"> </span><span class="k">const</span><span class="w"> </span><span class="kt">char</span><span class="w"> </span><span class="o">*</span><span class="n">file</span><span class="p">,</span><span class="w"> </span><span class="kt">int</span><span class="w"> </span><span class="n">line</span><span class="p">,</span> |
| <span class="w"> </span><span class="n">FAR</span><span class="w"> </span><span class="kt">void</span><span class="w"> </span><span class="o">*</span><span class="n">dst</span><span class="p">,</span><span class="w"> </span><span class="n">FAR</span><span class="w"> </span><span class="k">const</span><span class="w"> </span><span class="kt">void</span><span class="w"> </span><span class="o">*</span><span class="n">src</span><span class="p">,</span><span class="w"> </span><span class="kt">size_t</span><span class="w"> </span><span class="n">len</span><span class="p">);</span> |
| <span class="p">...</span> |
| <span class="cp">#define malloc(s) xxx_malloc(__FILE__, __LINE__, s)</span> |
| <span class="cp">#define free(p) xxx_free(__FILE__, __LINE__, p)</span> |
| <span class="cp">#define memcpy(d, s, l) xxx_memcpy(__FILE__, __LINE__, d, s, l)</span> |
| <span class="p">...</span> |
| <span class="cp">#endif</span> |
| <span class="p">...</span> |
| </pre></div> |
| </div> |
| </li> |
| <li><p>Implement <code class="docutils literal notranslate"><span class="pre">xxx_malloc</span></code>, <code class="docutils literal notranslate"><span class="pre">xxx_free</span></code>, <code class="docutils literal notranslate"><span class="pre">xxx_memcpy</span></code>… in source code, |
| you can:</p> |
| <ul class="simple"> |
| <li><p>Modify some arguments(e.g. extend the allocation size for redzone)</p></li> |
| <li><p>Check the critical arguments(e.g. pointer and length) in the range</p></li> |
| <li><p>Forward to the original implementation(call malloc/free/memcpy)</p></li> |
| <li><p>Attach the context info(e.g. file and line) before return</p></li> |
| </ul> |
| </li> |
| <li><p>Enable the hook by either:</p> |
| <ul class="simple"> |
| <li><p>Include <code class="docutils literal notranslate"><span class="pre">xxx_malloc.h</span></code> in your source code to hook one file</p></li> |
| <li><p>Add <code class="docutils literal notranslate"><span class="pre">-include</span> <span class="pre">xxx_malloc.h</span></code> to <code class="docutils literal notranslate"><span class="pre">CFLAGS</span></code> to hook all source code</p></li> |
| </ul> |
| </li> |
| </ol> |
| </section> |
| </section> |
| <section id="granule-allocator"> |
| <h2>Granule Allocator<a class="headerlink" href="#granule-allocator" title="Permalink to this heading"></a></h2> |
| <p>A non-standard granule allocator is also available in this directory The |
| granule allocator allocates memory in units of a fixed sized block (“granule”). |
| Allocations may be aligned to a user-provided address boundary.</p> |
| <p>The granule allocator interfaces are defined in <code class="docutils literal notranslate"><span class="pre">nuttx/include/nuttx/mm/gran.h</span></code>. |
| The granule allocator consists of these files in this directory: |
| <code class="docutils literal notranslate"><span class="pre">mm_gran.h</span></code>, <code class="docutils literal notranslate"><span class="pre">mm_granalloc.c</span></code>, <code class="docutils literal notranslate"><span class="pre">mm_grancritical.c</span></code>, <code class="docutils literal notranslate"><span class="pre">mm_granfree.c</span></code> |
| <code class="docutils literal notranslate"><span class="pre">mm_graninit.c</span></code></p> |
| <p>The granule allocator is not used anywhere within the base NuttX code |
| as of this writing. The intent of the granule allocator is to provide |
| a tool to support platform-specific management of aligned DMA memory.</p> |
| <p>NOTE: Because each granule may be aligned and each allocation is in |
| units of the granule size, selection of the granule size is important: |
| Larger granules will give better performance and less overhead but more |
| losses of memory due to quantization waste. Additional memory waste |
| can occur from alignment; Of course, heap alignment should no be |
| used unless (a) you are using the granule allocator to manage DMA memory |
| and (b) your hardware has specific memory alignment requirements.</p> |
| <p>The current implementation also restricts the maximum allocation size |
| to 32 granules. That restriction could be eliminated with some |
| additional coding effort, but currently requires larger granule |
| sizes for larger allocations.</p> |
| <section id="general-usage-example"> |
| <h3>General Usage Example<a class="headerlink" href="#general-usage-example" title="Permalink to this heading"></a></h3> |
| <p>This is an example using the GCC section attribute to position a DMA |
| heap in memory (logic in the linker script would assign the section |
| .dmaheap to the DMA memory:</p> |
| <div class="highlight-C notranslate"><div class="highlight"><pre><span></span><span class="n">FAR</span><span class="w"> </span><span class="kt">uint32_t</span><span class="w"> </span><span class="n">g_dmaheap</span><span class="p">[</span><span class="n">DMAHEAP_SIZE</span><span class="p">]</span><span class="w"> </span><span class="n">locate_data</span><span class="p">(.</span><span class="n">dmaheap</span><span class="p">);</span> |
| </pre></div> |
| </div> |
| <p>The heap is created by calling gran_initialize. Here the granule size |
| is set to 64 bytes and the alignment to 16 bytes:</p> |
| <div class="highlight-C notranslate"><div class="highlight"><pre><span></span><span class="n">GRAN_HANDLE</span><span class="w"> </span><span class="n">handle</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">gran_initialize</span><span class="p">(</span><span class="n">g_dmaheap</span><span class="p">,</span><span class="w"> </span><span class="n">DMAHEAP_SIZE</span><span class="p">,</span><span class="w"> </span><span class="mi">6</span><span class="p">,</span><span class="w"> </span><span class="mi">4</span><span class="p">);</span> |
| </pre></div> |
| </div> |
| <p>Then the <code class="docutils literal notranslate"><span class="pre">GRAN_HANDLE</span></code> can be used to allocate memory:</p> |
| <div class="highlight-C notranslate"><div class="highlight"><pre><span></span><span class="n">FAR</span><span class="w"> </span><span class="kt">uint8_t</span><span class="w"> </span><span class="o">*</span><span class="n">dma_memory</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">(</span><span class="n">FAR</span><span class="w"> </span><span class="kt">uint8_t</span><span class="w"> </span><span class="o">*</span><span class="p">)</span><span class="n">gran_alloc</span><span class="p">(</span><span class="n">handle</span><span class="p">,</span><span class="w"> </span><span class="mi">47</span><span class="p">);</span> |
| </pre></div> |
| </div> |
| <p>The actual memory allocates will be 64 byte (wasting 17 bytes) and |
| will be aligned at least to (<code class="docutils literal notranslate"><span class="pre">1</span> <span class="pre"><<</span> <span class="pre">log2align</span></code>).</p> |
| <p>Sub-Directories:</p> |
| <ul class="simple"> |
| <li><p><code class="docutils literal notranslate"><span class="pre">mm/mm_gran</span></code> - Holds the granule allocation logic</p></li> |
| </ul> |
| </section> |
| </section> |
| <section id="page-allocator"> |
| <h2>Page Allocator<a class="headerlink" href="#page-allocator" title="Permalink to this heading"></a></h2> |
| <p>The page allocator is an application of the granule allocator. It is a |
| special purpose memory allocator intended to allocate physical memory |
| pages for use with systems that have a memory management unit (MMU).</p> |
| <p>Sub-Directories:</p> |
| <ul class="simple"> |
| <li><p><code class="docutils literal notranslate"><span class="pre">mm/mm_gran</span></code> - The page allocator cohabits the same directory as the |
| granule allocator.</p></li> |
| </ul> |
| </section> |
| <section id="shared-memory-management"> |
| <h2>Shared Memory Management<a class="headerlink" href="#shared-memory-management" title="Permalink to this heading"></a></h2> |
| <p>When NuttX is build in kernel mode with a separate, privileged, kernel- |
| mode address space and multiple, unprivileged, user-mode address spaces, |
| then shared memory regions must also be managed. Shared memory regions |
| are user-accessible memory regions that can be attached into the user |
| process address space for sharing between user process.</p> |
| <p>Sub-Directories:</p> |
| <ul class="simple"> |
| <li><p><code class="docutils literal notranslate"><span class="pre">mm/shm</span></code> - The shared memory logic</p></li> |
| </ul> |
| <p>The shared memory management logic has its own page that can be |
| found at <a class="reference internal" href="shm.html"><span class="doc">Shared Memory Support</span></a>.</p> |
| </section> |
| <section id="i-o-buffers"> |
| <h2>I/O Buffers<a class="headerlink" href="#i-o-buffers" title="Permalink to this heading"></a></h2> |
| <p>The iob subdirectory contains a simple allocator of I/O buffers. These |
| I/O buffers, IOBs, are used extensively for networking but are generally |
| available for usage by drivers. The I/O buffers have these properties:</p> |
| <ol class="arabic simple"> |
| <li><p>Uses a pool of a fixed number of fixed fixed size buffers.</p></li> |
| <li><p>Free buffers are retained in free list: When a buffer is allocated |
| it is removed from the free list; when a buffer is freed it is |
| returned to the free list.</p></li> |
| <li><p>The calling application will wait if there are not free buffers.</p></li> |
| </ol> |
| </section> |
| </section> |
| |
| |
| </div> |
| </div> |
| <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer"> |
| <a href="../net/wqueuedeadlocks.html" class="btn btn-neutral float-left" title="Work Queue Deadlocks" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a> |
| <a href="shm.html" class="btn btn-neutral float-right" title="Shared Memory Support" 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> |
