| <!DOCTYPE html> |
| <html lang="en"> |
| <head> |
| <meta charset="utf-8"> |
| <meta http-equiv="X-UA-Compatible" content="IE=edge"> |
| <meta name="viewport" content="width=device-width, initial-scale=1.0"> |
| |
| |
| <!-- This is broken by doc revisioning. |
| --> |
| <link rel="shortcut icon" href="../../../../img/favicon.ico"> |
| |
| <title>toc - Apache Mynewt</title> |
| |
| <link href="../../../../css/bootstrap-3.0.3.min.css" rel="stylesheet"> |
| <link rel="stylesheet" href="../../../../css/highlight.css"> |
| <link href="../../../../css/base.css" rel="stylesheet"> |
| <link href="../../../../css/custom.css" rel="stylesheet"> |
| <link href="../../../../css/v2.css" rel="stylesheet"> |
| <link href="https://fonts.googleapis.com/css?family=Lato" rel="stylesheet"> |
| <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/font-awesome/4.5.0/css/font-awesome.min.css"> |
| |
| <!-- HTML5 shim and Respond.js IE8 support of HTML5 elements and media queries --> |
| <!--[if lt IE 9]> |
| <script src="https://oss.maxcdn.com/libs/html5shiv/3.7.0/html5shiv.js"></script> |
| <script src="https://oss.maxcdn.com/libs/respond.js/1.3.0/respond.min.js"></script> |
| <![endif]--> |
| |
| |
| <script> |
| (function(i, s, o, g, r, a, m) { |
| i["GoogleAnalyticsObject"] = r; |
| (i[r] = |
| i[r] || |
| function() { |
| (i[r].q = i[r].q || []).push(arguments); |
| }), |
| (i[r].l = 1 * new Date()); |
| (a = s.createElement(o)), (m = s.getElementsByTagName(o)[0]); |
| a.async = 1; |
| a.src = g; |
| m.parentNode.insertBefore(a, m); |
| })(window, document, "script", "//www.google-analytics.com/analytics.js", "ga"); |
| |
| ga("create", "UA-72162311-1", "auto"); |
| ga("send", "pageview"); |
| </script> |
| |
| </head> |
| |
| |
| <body class="toc"> |
| |
| |
| <div class="container"> |
| <div class="row v2-main-banner"> |
| <a class="logo-cell" href="/"> |
| <img class="logo" src="/img/logo.png"> |
| </a> |
| <div class="tagline-cell"> |
| <h4 class="tagline">An OS to build, deploy and securely manage billions of devices</h4> |
| </div> |
| <div class="news-cell"> |
| <div class="well"> |
| <h4>Latest News:</h4> <a href="/download">Apache Mynewt 1.11.0, Apache NimBLE 1.6.0 </a> released (September 7, 2023) |
| </div> |
| </div> |
| </div> |
| </div> |
| |
| |
| |
| |
| |
| |
| |
| |
| <nav id="navbar" class="navbar navbar-inverse affix-top" data-spy="affix" data-offset-top="150" role="navigation"> |
| <div class="container"> |
| <!-- Collapsed navigation --> |
| <div class="navbar-header"> |
| <!-- Expander button --> |
| <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-collapse"> |
| <span class="sr-only">Toggle navigation</span> |
| <span class="icon-bar"></span> |
| <span class="icon-bar"></span> |
| <span class="icon-bar"></span> |
| </button> |
| |
| </div> |
| |
| <!-- Expanded navigation --> |
| <div class="navbar-collapse collapse"> |
| <!-- Main navigation --> |
| <ul class="nav navbar-nav navbar-right"> |
| <li |
| class="" |
| > |
| <a href="/"><i class="fa fa-home" style="font-size: larger;"></i></a> |
| </li> |
| <li |
| class="important" |
| > |
| <a href="/quick-start/">Quick Start</a> |
| </li> |
| <li |
| class="" |
| > |
| <a href="/about/">About</a> |
| </li> |
| <li |
| class="" |
| > |
| <a href="/talks/">Talks</a> |
| </li> |
| <li |
| class="active" |
| > |
| <a href="/documentation/">Documentation</a> |
| </li> |
| <li |
| class="" |
| > |
| <a href="/download/">Download</a> |
| </li> |
| <li |
| class="" |
| > |
| <a href="/community/">Community</a> |
| </li> |
| <li |
| class="" |
| > |
| <a href="/events/">Events</a> |
| </li> |
| </ul> |
| |
| </div> |
| </div> |
| </nav> |
| |
| |
| |
| <div class="container"> |
| |
| <div class="row"> |
| <div class="col-md-3 v2-sidebar sidebar-container"><div id="docSidebar" class="hidden-print" role="complementary"> |
| <div class="top"> |
| <div role="search"> |
| <form id="rtd-search-form" class="wy-form" action="../../../../search.html" method="get"> |
| <div class="form-group"> |
| <input type="text" name="q" class="form-control" placeholder="Search documentation" /> |
| </div> |
| </form> |
| </div> |
| </div> |
| <ul class="toc-nav"> |
| <li class="doc-version"><select class="form-control" onchange="if (this.value) window.location.href=this.value"> |
| <option value="/latest"> |
| Version: master |
| </option> |
| <option value="/v1_11_0/" > |
| Version: 1.11.0 |
| </option> |
| <option value="/v1_10_0/" > |
| Version: 1.10.0 |
| </option> |
| <option value="/v1_9_0/" > |
| Version: 1.9.0 |
| </option> |
| <option value="/v1_8_0/" > |
| Version: 1.8.0 |
| </option> |
| <option value="/v1_7_0/" > |
| Version: 1.7.0 |
| </option> |
| <option value="/v1_6_0/" > |
| Version: 1.6.0 |
| </option> |
| <option value="/v1_5_0/" > |
| Version: 1.5.0 |
| </option> |
| <option value="/v1_4_0/" > |
| Version: 1.4.0 |
| </option> |
| <option value="/v1_3_0/os/introduction" > |
| Version: 1.3.0 |
| </option> |
| <option value="/v1_2_0/os/introduction" > |
| Version: 1.2.0 |
| </option> |
| <option value="/v1_1_0/os/introduction" > |
| Version: 1.1.0 |
| </option> |
| <option value="/v1_0_0/os/introduction" > |
| Version: 1.0.0 |
| </option> |
| <option value="/v0_9_0/os/introduction" selected="selected" > |
| Version: 0.9.0 |
| </option> |
| </select></li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li ><a href="../../../introduction/">Mynewt Documentation</a> |
| |
| |
| <ul> |
| |
| |
| |
| |
| |
| |
| |
| <li ><a href="../../../get_started/get_started/">Basic Setup</a> |
| |
| |
| </li> |
| |
| |
| |
| |
| |
| <li > |
| <a href="../../../get_started/vocabulary/">Concepts</a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| <li ><a href="../../../tutorials/tutorials/">Tutorials</a> |
| |
| |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| <li ><a href="../../../os_user_guide/">OS User Guide</a> |
| |
| |
| <ul> |
| |
| |
| |
| |
| |
| |
| |
| <li ><a href="../../mynewt_os/">OS Core</a> |
| |
| |
| <ul> |
| |
| |
| |
| |
| |
| |
| |
| <li><a href=" |
| ../../os_init/ |
| ">System-level Functions</a> |
| |
| |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| <li ><a href="../../context_switch/context_switch/">Scheduler</a> |
| |
| |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| <li ><a href="../../time/os_time/">Time</a> |
| |
| |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| <li ><a href="../../task/task/">Tasks</a> |
| |
| |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| <li ><a href="../../event_queue/event_queue/">Event Queues</a> |
| |
| |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| <li ><a href="../../semaphore/semaphore/">Semaphores</a> |
| |
| |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| <li ><a href="../../mutex/mutex/">Mutexes</a> |
| |
| |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| <li class="active"><a href="./">Memory Pools</a> |
| |
| |
| <ul> |
| |
| |
| |
| |
| |
| |
| |
| <li><a href=" |
| ../os_memblock_get/ |
| ">Functions/Macros</a> |
| |
| |
| </li> |
| |
| |
| |
| </ul> |
| |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| <li ><a href="../../heap/heap/">Heap</a> |
| |
| |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| <li><a href=" |
| |
| |
| ../../mbuf/mbuf/ |
| |
| ">Memory Buffers</a> |
| |
| |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| <li ><a href="../../sanity/sanity/">Sanity</a> |
| |
| |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| <li ><a href="../../callout/callout/">Callouts</a> |
| |
| |
| </li> |
| |
| |
| |
| </ul> |
| |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| <li ><a href="../../porting/port_os/">Porting to your Platform</a> |
| |
| |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| <li ><a href="../../../modules/console/console/">Console</a> |
| |
| |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| <li ><a href="../../../modules/shell/shell/">Shell</a> |
| |
| |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| <li ><a href="../../../modules/bootloader/bootloader/">Bootloader</a> |
| |
| |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| <li><a href=" |
| |
| |
| ../../../modules/fs/fs/fs/ |
| |
| ">File System</a> |
| |
| |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| <li ><a href="../../../modules/hal/hal/">Hardware Abstraction Layer</a> |
| |
| |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| <li ><a href="../../../modules/testutil/testutil/">Test Utilities</a> |
| |
| |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| <li ><a href="../../../modules/imgmgr/imgmgr/">Image Manager</a> |
| |
| |
| </li> |
| |
| |
| |
| |
| |
| <li > |
| <a href="../../../modules/baselibc/">Baselibc library</a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| <li ><a href="../../../modules/elua/elua/">Embedded Lua</a> |
| |
| |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| <li ><a href="../../../modules/json/json/">JSON</a> |
| |
| |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| <li ><a href="../../../modules/stats/stats/">Stats</a> |
| |
| |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| <li ><a href="../../../modules/logs/logs/">Logs</a> |
| |
| |
| </li> |
| |
| |
| |
| </ul> |
| |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| <li><a href=" |
| ../../../../network/ble/ble_intro/ |
| ">BLE User Guide</a> |
| |
| |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| <li ><a href="../../../../newt/newt_intro/">Newt Tool Guide</a> |
| |
| |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| <li ><a href="../../../../newtmgr/overview/">Newt Manager Guide</a> |
| |
| |
| </li> |
| |
| |
| |
| |
| |
| <li > |
| <a href="../../../../known_issues/">Known Issues</a> |
| </li> |
| |
| |
| |
| </ul> |
| |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| <li><a href=" |
| ../../../../faq/how_to_edit_docs/ |
| ">Appendix</a> |
| |
| |
| </li> |
| |
| |
| |
| </ul> |
| </div></div> |
| |
| <div class="col-md-9" role="main"> |
| <div class="doc-header"> |
| <div role="navigation" aria-label="breadcrumbs navigation"> |
| <ul class="wy-breadcrumbs"> |
| <li><a href="/documentation/">Docs</a></li> |
| |
| |
| |
| <li>» Memory Pools</li> |
| |
| |
| |
| <li>» <a href="os/core_os/mynewt_os/">OS Core</a></li> |
| |
| |
| |
| <li>» <a href="os/os_user_guide/">OS User Guide</a></li> |
| |
| |
| |
| <li>» <a href="os/introduction/">Mynewt Documentation</a></li> |
| |
| |
| |
| |
| |
| </ul> |
| </div> |
| </div> |
| |
| |
| |
| |
| <div class="alert alert-warning"> |
| <p> |
| Version 0.9.0 is not the most recent version of the Apache Mynewt |
| documentation. Click <a href="/latest">here</a> to read the latest |
| version. |
| </p> |
| </div> |
| |
| |
| |
| |
| |
| <h1 id="memory-pools">Memory Pools</h1> |
| <p>A memory pool is a collection of fixed sized elements called memory blocks. Generally, memory pools are used when the developer wants to allocate a certain amount of memory to a given feature. Unlike the heap, where a code module is at the mercy of other code modules to insure there is sufficient memory, memory pools can insure sufficient memory allocation.</p> |
| <h3 id="description">Description</h3> |
| <p>In order to create a memory pool the developer needs to do a few things. The first task is to define the memory pool itself. This is a data structure which contains information about the pool itself (i.e. number of blocks, size of the blocks, etc).</p> |
| <div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code><span style="color: #A90D91">struct</span> <span style="color: #3F6E75">os_mempool</span> <span style="color: #000000">my_pool</span>; |
| </code></pre></div> |
| |
| <p><br> |
| The next order of business is to allocate the memory used by the memory pool. This memory can either be statically allocated (i.e. a global variable) or dynamically allocated (i.e. from the heap). When determining the amount of memory required for the memory pool, simply multiplying the number of blocks by the size of each block is not sufficient as the OS may have alignment requirements. The alignment size definition is named <code>OS_ALIGNMENT</code> and can be found in os_arch.h as it is architecture specific. The memory block alignment is usually for efficiency but may be due to other reasons. Generally, blocks are aligned on 32-bit boundaries. Note that memory blocks must also be of sufficient size to hold a list pointer as this is needed to chain memory blocks on the free list.</p> |
| <p>In order to simplify this for the user two macros have been provided: <code>OS_MEMPOOL_BYTES(n, blksize)</code> and <code>OS_MEMPOOL_SIZE(n, blksize)</code>. The first macro returns the number of bytes needed for the memory pool while the second returns the number of <code>os_membuf_t</code> elements required by the memory pool. The <code>os_membuf_t</code> type is used to guarantee that the memory buffer used by the memory pool is aligned on the correct boundary. </p> |
| <p>Here are some examples. Note that if a custom malloc implementation is used it must guarantee that the memory buffer used by the pool is allocated on the correct boundary (i.e. OS_ALIGNMENT).</p> |
| <div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code><span style="color: #A90D91">void</span> <span style="color: #000000">*my_memory_buffer</span>; |
| <span style="color: #000000">my_memory_buffer</span> <span style="color: #000000">=</span> <span style="color: #000000">malloc</span>(<span style="color: #000000">OS_MEMPOOL_BYTES</span>(<span style="color: #000000">NUM_BLOCKS</span>, <span style="color: #000000">BLOCK_SIZE</span>)); |
| </code></pre></div> |
| |
| <div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code><span style="color: #000000">os_membuf_t</span> <span style="color: #000000">my_memory_buffer</span>[<span style="color: #000000">OS_MEMPOOL_SIZE</span>(<span style="color: #000000">NUM_BLOCKS</span>, <span style="color: #000000">BLOCK_SIZE</span>)]; |
| </code></pre></div> |
| |
| <p><br> |
| Now that the memory pool has been defined as well as the memory required for the memory blocks which make up the pool the user needs to initialize the memory pool by calling <code>os_mempool_init</code>.</p> |
| <div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code><span style="color: #000000">os_mempool_init</span>(<span style="color: #000000">&my_pool</span>, <span style="color: #000000">NUM_BLOCKS</span>, <span style="color: #000000">BLOCK_SIZE</span>, <span style="color: #000000">my_memory_buffer</span>, |
| <span style="color: #C41A16">"MyPool"</span>); |
| </code></pre></div> |
| |
| <p><br> |
| Once the memory pool has been initialized the developer can allocate memory blocks from the pool by calling <code>os_memblock_get</code>. When the memory block is no longer needed the memory can be freed by calling <code>os_memblock_put</code>. </p> |
| <h3 id="data-structures">Data structures</h3> |
| <div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code><span style="color: #A90D91">struct</span> <span style="color: #3F6E75">os_mempool</span> { |
| <span style="color: #A90D91">int</span> <span style="color: #000000">mp_block_size</span>; |
| <span style="color: #A90D91">int</span> <span style="color: #000000">mp_num_blocks</span>; |
| <span style="color: #A90D91">int</span> <span style="color: #000000">mp_num_free</span>; |
| <span style="color: #A90D91">uint32_t</span> <span style="color: #000000">mp_membuf_addr</span>; |
| <span style="color: #000000">STAILQ_ENTRY</span>(<span style="color: #000000">os_mempool</span>) <span style="color: #000000">mp_list</span>; |
| <span style="color: #000000">SLIST_HEAD</span>(,<span style="color: #000000">os_memblock</span>); |
| <span style="color: #A90D91">char</span> <span style="color: #000000">*name</span>; |
| }; |
| </code></pre></div> |
| |
| <p><br></p> |
| <table> |
| <thead> |
| <tr> |
| <th><strong>Element</strong></th> |
| <th><strong>Description</strong></th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td>mp_block_size</td> |
| <td>Size of the memory blocks, in bytes. This is not the actual number of bytes used by each block; it is the requested size of each block. The actual memory block size will be aligned to OS_ALIGNMENT bytes</td> |
| </tr> |
| <tr> |
| <td>mp_num_blocks</td> |
| <td>Number of memory blocks in the pool</td> |
| </tr> |
| <tr> |
| <td>mp_num_free</td> |
| <td>Number of free blocks left</td> |
| </tr> |
| <tr> |
| <td>mp_membuf_addr</td> |
| <td>The address of the memory block. This is used to check that a valid memory block is being freed.</td> |
| </tr> |
| <tr> |
| <td>mp_list</td> |
| <td>List pointer to chain memory pools so they can be displayed by newt tools</td> |
| </tr> |
| <tr> |
| <td>SLIST_HEAD(,os_memblock)</td> |
| <td>List pointer to chain free memory blocks</td> |
| </tr> |
| <tr> |
| <td>name</td> |
| <td>Name for the memory block</td> |
| </tr> |
| </tbody> |
| </table> |
| <h3 id="list-of-functionsmacros">List of Functions/Macros</h3> |
| <p>The functions/macros available in mem_pool are:</p> |
| <table> |
| <thead> |
| <tr> |
| <th><strong>Function</strong></th> |
| <th><strong>Description</strong></th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td><a href="os_memblock_get">os_memblock_get</a></td> |
| <td>Allocate an element from the memory pool.</td> |
| </tr> |
| <tr> |
| <td><a href="os_mempool_init">os_mempool_init</a></td> |
| <td>Initializes the memory pool.</td> |
| </tr> |
| <tr> |
| <td><a href="os_memblock_put">os_memblock_put</a></td> |
| <td>Releases previously allocated element back to the pool.</td> |
| </tr> |
| <tr> |
| <td><a href="OS_MEMPOOL_BYTES">OS_MEMPOOL_BYTES</a></td> |
| <td>Calculates how many bytes of memory is used by n number of elements, when individual element size is blksize bytes.</td> |
| </tr> |
| <tr> |
| <td><a href="OS_MEMPOOL_SIZE">OS_MEMPOOL_SIZE</a></td> |
| <td>Calculates the number of os_membuf_t elements used by n blocks of size blksize bytes.</td> |
| </tr> |
| </tbody> |
| </table> |
| |
| <div class="row"> |
| |
| |
| |
| |
| <ul class="nav nav-pills" style="margin-bottom: 10px"> |
| <li> |
| |
| </li> |
| <li class="pull-right"> |
| |
| </li> |
| </ul> |
| </div> |
| <footer class="row"> |
| <div class="col-xs-12"> |
| |
| <p class="copyright">Apache Mynewt (incubating) is available under Apache License, version 2.0.</p> |
| |
| </div> |
| <div class="col-xs-12"> |
| <div class="logos"> |
| <a href="https://www.apache.org/"> |
| <img src="/img/asf_logo_wide_small.png" alt="Apache" title="Apache"> |
| </a> |
| <p> |
| Copyright © 2015-2021 The Apache Software Foundation.<br> |
| <small class="footnote"> |
| Apache Mynewt, Mynewt, Apache, the Apache feather logo, and the Apache Mynewt |
| project logo are either registered trademarks or trademarks of the Apache |
| Software Foundation in the United States and other countries. |
| </small> |
| </p> |
| <a href=""> |
| <img src="https://www.countit.com/images/add_to_slack.png" alt="Slack Icon" title="Join our Slack Community" /> |
| </a> |
| </div> |
| </div> |
| <a href="https://www.apache.org/licenses/"> |
| <button class="button-footer-asf"> |
| License |
| </button> |
| </a> |
| <a href="https://www.apache.org/foundation/sponsorship.html"> |
| <button class="button-footer-asf"> |
| Sponsorship |
| </button> |
| </a> |
| <a href="https://www.apache.org/foundation/thanks.html"> |
| <button class="button-footer-asf"> |
| Thanks |
| </button> |
| </a> |
| <a href="https://www.apache.org/security/"> |
| <button class="button-footer-asf"> |
| Security |
| </button> |
| </a> |
| <a href="https://apache.org/events/current-event"> |
| <button class="button-footer-asf"> |
| ASF Events |
| </button> |
| </a> |
| </footer> |
| </div> |
| </div> |
| |
| |
| </div> |
| |
| <script src="../../../../js/jquery-1.10.2.min.js"></script> |
| <script src="../../../../js/bootstrap-3.0.3.min.js"></script> |
| <script src="../../../../js/highlight.pack.js"></script> |
| <script src="../../../../js/base.js"></script> |
| <script src="../../../../js/custom.js"></script> |
| <script src="search/main.js"></script> |
| |
| </body> |
| </html> |
