asf-site update Fri Jan 25 21:57:30 UTC 2019

master/_sources/os/modules/mfg/mfg.rst.txt

@@ -0,0 +1,127 @@
+Manufacturing Support
+=====================
+
+.. toctree::
+    :hidden:
+
+Description
+~~~~~~~~~~~
+
+An mfgimage is a binary that gets written to a Mynewt device at
+manufacturing time.  Unlike a Mynewt target which corresponds to a
+single executable image, an mfgimage represents the entire contents
+of a flash device.
+
+
+Definitions
+~~~~~~~~~~~
+
+=============  ============================  =======
+Term           Long Name                     Meaning
+=============  ============================  =======
+Flashdev       Flash device                  A single piece of flash hardware. A typical device might contain two flashdevs: 1) internal flash, and 2) external SPI flash.
+Mfgimage       Manufacturing image           A file with the entire contents of a single flashdev. At manufacturing time, a separate mfgimage is written to each of the device's flashdevs.
+Boot Mfgimage  Boot manufacturing image      The mfgimage containing the boot loader; always written to internal flash.
+MMR            Manufacturing Meta Region     A chunk of read-only data included in every mfgimage. Contains identifying information for the mfgimage and other data that stays with the device until end of life.
+TLV            Type Length Value             A simple extensible means of representing data. Contains three fields: 1) type of data, 2) length of data, and 3) the data itself.
+MfgID          Manufacturing ID              Identifies which set of mfgimages a device was built with.  Expressed as a list of SHA256 hashes.
+=============  ============================  =======
+
+
+Details
+~~~~~~~
+
+Typically, an mfgimage consists of:
+
+* 1 boot loader.
+* 1 or 2 Mynewt images.
+* Extra configuration (e.g., a pre-populated ``sys/config`` region).
+
+In addition, each mfgimage contains a manufacturing meta region (MMR).
+The MMR consists of read-only data that resides in flash for the
+lifetime of the device.  There is currently support for three MMR TLV
+types:
+
+* Hash of mfgimage
+* Flash map
+* Device / offset of next MMR
+
+The manufacturing hash indicates which manufacuturing image a device
+was built with.  A management system may need this information to
+determine which images a device can be upgraded to, for example.  A
+Mynewt device exposes its manufacturing hash via the ``id/mfghash``
+config setting.
+
+Since MMRs are not intended to be modified or erased, they must be placed in
+unmodifiable areas of flash.  In the boot mfgimage, the MMR *must* be placed in
+the flash area containing the boot loader.  For non-boot mfgimages, the MMR can go in any unused area in the relevant flashdev.
+
+Manufacturing ID
+~~~~~~~~~~~~~~~~
+
+Each mfgimage has its own MMR containing a hash.
+
+The MMR at the end of the boot mfgimage ("boot MMR") must be present. The boot
+MMR indicates the flash locations of other MMRs via the ``mmr_ref`` TLV type.
+
+At startup, the firmware reads the boot MMR. Next, it reads
+any additional MMRs indicated by ``mmr_ref`` TLVs. An ``mmr_ref`` TLV contains
+one field: The ID of the flash area where the next MMR is located.
+
+After all MMRs have been read, the firmware populates the ``id/mfghash``
+setting with a colon-separated list of hashes. By reading and parsing
+this setting, a client can derive the full list of mfgimages that the
+device was built with.
+
+One important implication is that MMR areas should never be moved in a BSP's
+flash map.  Such a change would produce firmware that is incompatible with
+older devices.
+
+
+MMR Structure
+~~~~~~~~~~~~~
+
+An MMR is always located at the end its flash area.  Any other placement is invalid.
+
+An MMR has the following structure:
+
+::
+
+     0                   1                   2                   3
+     0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+    |   TLV type    |   TLV size    | TLV data ("TLV size" bytes)   ~
+    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+                               ~
+    ~                                                               ~
+    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+    |   TLV type    |   TLV size    | TLV data ("TLV size" bytes)   ~
+    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+                               ~
+    ~                                                               ~
+    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+    |          Region size          |    Version    | 0xff padding  |
+    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+    |                       Magic (0x3bb2a269)                      |
+    +-+-+-+-+-+--+-+-+-+-+-+end of flash area-+-+-+-+-+-+-+-+-+-+-+-+
+
+
+The number of TLVs is variable; two are shown above for illustrative
+purposes.
+
+**Fields:**
+
+*<TLVs>*
+
+1. TLV type: Indicates the type of data to follow.
+2. TLV size: The number of bytes of data to follow.
+3. TLV data: "TLV size" bytes of data.
+
+*<Footer>*
+
+4. Region size: The size, in bytes, of the entire manufacturing meta region; includes TLVs and footer.
+5. Version: Manufacturing meta version number; always 0x02.
+6. Magic: Indicates the presence of the manufacturing meta region.
+
+API
+---
+
+.. doxygenfile:: sys/mfg/include/mfg/mfg.h

master/_sources/os/os_user_guide.rst.txt

@@ -20,6 +20,7 @@ OS User Guide
    Sensor Framework <modules/sensor_framework/sensor_framework>
    Test Utilities <modules/testutil/testutil>
    JSON <modules/json/json>
+   Manufacturing support <modules/mfg/mfg>
 
 This guide provides comprehensive information about Mynewt OS, the
 real-time operating system for embedded systems. It is intended both for

master/genindex.html

@@ -240,6 +240,7 @@ <h1 id="index">Index</h1>
  | <a href="#H"><strong>H</strong></a>
  | <a href="#J"><strong>J</strong></a>
  | <a href="#L"><strong>L</strong></a>
+ | <a href="#M"><strong>M</strong></a>
  | <a href="#N"><strong>N</strong></a>
  | <a href="#O"><strong>O</strong></a>
  | <a href="#S"><strong>S</strong></a>
@@ -483,10 +484,10 @@ <h2 id="C">C</h2>
 </li>
       <li><a href="os/modules/config/config.html#c.conf_store_init">conf_store_init (C function)</a>
 </li>
-  </ul></td>
-  <td style="width: 33%; vertical-align: top;"><ul>
       <li><a href="os/modules/config/config.html#c.conf_str_from_bytes">conf_str_from_bytes (C function)</a>
 </li>
+  </ul></td>
+  <td style="width: 33%; vertical-align: top;"><ul>
       <li><a href="os/modules/config/config.html#c.conf_str_from_value">conf_str_from_value (C function)</a>
 </li>
       <li><a href="os/modules/config/config.html#c.conf_value_from_str">conf_value_from_str (C function)</a>
@@ -504,6 +505,8 @@ <h2 id="C">C</h2>
       <li><a href="os/modules/console/console.html#c.console_line_event_put">console_line_event_put (C function)</a>
 </li>
       <li><a href="os/modules/console/console.html#c.console_line_queue_set">console_line_queue_set (C function)</a>
+</li>
+      <li><a href="os/modules/console/console.html#c.console_lock">console_lock (C function)</a>
 </li>
       <li><a href="os/modules/console/console.html#c.console_non_blocking_mode">console_non_blocking_mode (C function)</a>
 </li>
@@ -518,6 +521,8 @@ <h2 id="C">C</h2>
       <li><a href="os/modules/console/console.html#c.console_set_completion_cb">console_set_completion_cb (C function)</a>
 </li>
       <li><a href="os/modules/console/console.html#c.console_silence">console_silence (C function)</a>
+</li>
+      <li><a href="os/modules/console/console.html#c.console_unlock">console_unlock (C function)</a>
 </li>
       <li><a href="os/modules/console/console.html#c.console_write">console_write (C function)</a>
 </li>
@@ -840,6 +845,8 @@ <h2 id="L">L</h2>
       <li><a href="os/modules/logs/logs.html#c.log_find">log_find (C function)</a>
 </li>
       <li><a href="os/modules/logs/logs.html#c.log_flush">log_flush (C function)</a>
+</li>
+      <li><a href="os/modules/logs/logs.html#c.log_get_level">log_get_level (C function)</a>
 </li>
       <li><a href="os/modules/logs/logs.html#c.log_init">log_init (C function)</a>
 </li>
@@ -872,6 +879,8 @@ <h2 id="L">L</h2>
       <li><a href="os/modules/logs/logs.html#c.log_register">log_register (C function)</a>
 </li>
       <li><a href="os/modules/logs/logs.html#c.log_set_append_cb">log_set_append_cb (C function)</a>
+</li>
+      <li><a href="os/modules/logs/logs.html#c.log_set_level">log_set_level (C function)</a>
 </li>
       <li><a href="os/modules/logs/logs.html#c.log_set_watermark">log_set_watermark (C function)</a>
 </li>
@@ -884,6 +893,28 @@ <h2 id="L">L</h2>
   </ul></td>
 </tr></table>
 
+<h2 id="M">M</h2>
+<table style="width: 100%" class="indextable genindextable"><tr>
+  <td style="width: 33%; vertical-align: top;"><ul>
+      <li><a href="os/modules/mfg/mfg.html#c.mfg_init">mfg_init (C function)</a>
+</li>
+      <li><a href="os/modules/mfg/mfg.html#c.mfg_open">mfg_open (C function)</a>
+</li>
+      <li><a href="os/modules/mfg/mfg.html#c.mfg_read_tlv_flash_area">mfg_read_tlv_flash_area (C function)</a>
+</li>
+  </ul></td>
+  <td style="width: 33%; vertical-align: top;"><ul>
+      <li><a href="os/modules/mfg/mfg.html#c.mfg_read_tlv_hash">mfg_read_tlv_hash (C function)</a>
+</li>
+      <li><a href="os/modules/mfg/mfg.html#c.mfg_read_tlv_mmr_ref">mfg_read_tlv_mmr_ref (C function)</a>
+</li>
+      <li><a href="os/modules/mfg/mfg.html#c.mfg_seek_next">mfg_seek_next (C function)</a>
+</li>
+      <li><a href="os/modules/mfg/mfg.html#c.mfg_seek_next_with_type">mfg_seek_next_with_type (C function)</a>
+</li>
+  </ul></td>
+</tr></table>
+
 <h2 id="N">N</h2>
 <table style="width: 100%" class="indextable genindextable"><tr>
   <td style="width: 33%; vertical-align: top;"><ul>
@@ -1025,10 +1056,10 @@ <h2 id="O">O</h2>
 </li>
       <li><a href="os/core_os/memory_pool/memory_pool.html#c.os_memblock_get">os_memblock_get (C function)</a>
 </li>
-  </ul></td>
-  <td style="width: 33%; vertical-align: top;"><ul>
       <li><a href="os/core_os/memory_pool/memory_pool.html#c.os_memblock_put">os_memblock_put (C function)</a>
 </li>
+  </ul></td>
+  <td style="width: 33%; vertical-align: top;"><ul>
       <li><a href="os/core_os/memory_pool/memory_pool.html#c.os_memblock_put_from_cb">os_memblock_put_from_cb (C function)</a>
 </li>
       <li><a href="os/core_os/memory_pool/memory_pool.html#_CPPv310os_mempool">os_mempool (C++ class)</a>
@@ -1070,6 +1101,8 @@ <h2 id="O">O</h2>
       <li><a href="os/core_os/mutex/mutex.html#_CPPv38os_mutex">os_mutex (C++ class)</a>
 </li>
       <li><a href="os/core_os/mutex/mutex.html#c.os_mutex::SLIST_HEAD">os_mutex::SLIST_HEAD (C function)</a>
+</li>
+      <li><a href="os/core_os/mutex/mutex.html#c.os_mutex_get_level">os_mutex_get_level (C function)</a>
 </li>
       <li><a href="os/core_os/mutex/mutex.html#c.os_mutex_init">os_mutex_init (C function)</a>
 </li>

master/network/docs/ble_hs/ble_gattc.html

@@ -314,7 +314,7 @@ <h2>API<a class="headerlink" href="#api" title="Permalink to this headline">¶</
 
 <dl class="typedef">
 <dt id="c.ble_gatt_svc_foreach_fn">
-<span class="target" id="group__bt__gatt_1ga392c5ac85521665c3a6fee2b7cffe835"></span><em class="property">typedef </em>void<code class="descname">(* ble_gatt_svc_foreach_fn)</code><span class="sig-paren">(</span>const struct ble_gatt_svc_def<em>&nbsp;*svc</em>, uint16_t<em>&nbsp;handle</em>, uint16_t<em>&nbsp;end_group_handle</em><span class="sig-paren">)</span><a class="headerlink" href="#c.ble_gatt_svc_foreach_fn" title="Permalink to this definition">¶</a></dt>
+<span class="target" id="group__bt__gatt_1gad5aaaa4de2073fa6e7bb2fa020b7b481"></span><em class="property">typedef </em>void<code class="descname">(* ble_gatt_svc_foreach_fn)</code><span class="sig-paren">(</span>const struct ble_gatt_svc_def<em>&nbsp;*svc</em>, uint16_t<em>&nbsp;handle</em>, uint16_t<em>&nbsp;end_group_handle</em>, void<em>&nbsp;*arg</em><span class="sig-paren">)</span><a class="headerlink" href="#c.ble_gatt_svc_foreach_fn" title="Permalink to this definition">¶</a></dt>
 <dd></dd></dl>
 
 <dl class="function">

master/network/docs/ble_hs/ble_gatts.html

@@ -314,7 +314,7 @@ <h2>API<a class="headerlink" href="#api" title="Permalink to this headline">¶</
 
 <dl class="typedef">
 <dt id="c.ble_gatt_svc_foreach_fn">
-<span class="target" id="group__bt__gatt_1ga392c5ac85521665c3a6fee2b7cffe835"></span><em class="property">typedef </em>void<code class="descname">(* ble_gatt_svc_foreach_fn)</code><span class="sig-paren">(</span>const struct ble_gatt_svc_def<em>&nbsp;*svc</em>, uint16_t<em>&nbsp;handle</em>, uint16_t<em>&nbsp;end_group_handle</em><span class="sig-paren">)</span><a class="headerlink" href="#c.ble_gatt_svc_foreach_fn" title="Permalink to this definition">¶</a></dt>
+<span class="target" id="group__bt__gatt_1gad5aaaa4de2073fa6e7bb2fa020b7b481"></span><em class="property">typedef </em>void<code class="descname">(* ble_gatt_svc_foreach_fn)</code><span class="sig-paren">(</span>const struct ble_gatt_svc_def<em>&nbsp;*svc</em>, uint16_t<em>&nbsp;handle</em>, uint16_t<em>&nbsp;end_group_handle</em>, void<em>&nbsp;*arg</em><span class="sig-paren">)</span><a class="headerlink" href="#c.ble_gatt_svc_foreach_fn" title="Permalink to this definition">¶</a></dt>
 <dd></dd></dl>
 
 <dl class="function">

master/network/docs/index.html

@@ -42,7 +42,7 @@
           <link rel="search" title="Search" href="../../search.html"/>
       <link rel="top" title="Apache Mynewt latest documentation" href="../../index.html"/>
           <link rel="next" title="NimBLE Security" href="ble_sec.html"/>
-          <link rel="prev" title="JSON" href="../../os/modules/json/json.html"/> 
+          <link rel="prev" title="Manufacturing Support" href="../../os/modules/mfg/mfg.html"/> 
 
 
     <script src="../../_static/js/modernizr.min.js"></script>
@@ -366,7 +366,7 @@ <h2><a class="toc-backref" href="#id4">Example NimBLE projects</a><a class="head
         <a href="ble_sec.html" class="btn btn-neutral float-right" title="NimBLE Security" accesskey="n">Next: NimBLE Security <span class="fa fa-arrow-circle-right"></span></a>
 
 
-        <a href="../../os/modules/json/json.html" class="btn btn-neutral" title="JSON" accesskey="p"><span class="fa fa-arrow-circle-left"></span> Previous: JSON</a>
+        <a href="../../os/modules/mfg/mfg.html" class="btn btn-neutral" title="Manufacturing Support" accesskey="p"><span class="fa fa-arrow-circle-left"></span> Previous: Manufacturing Support</a>
 
     </div>
 

master/os/core_os/callout/callout.html

@@ -246,6 +246,7 @@ <h4>Latest News:</h4> <a href="/download">Apache Mynewt 1.5.0 </a> released (Nov
 <li class="toctree-l2"><a class="reference internal" href="../../modules/sensor_framework/sensor_framework.html">Sensor Framework</a></li>
 <li class="toctree-l2"><a class="reference internal" href="../../modules/testutil/testutil.html">Test Utilities</a></li>
 <li class="toctree-l2"><a class="reference internal" href="../../modules/json/json.html">JSON</a></li>
+<li class="toctree-l2"><a class="reference internal" href="../../modules/mfg/mfg.html">Manufacturing support</a></li>
 </ul>
 </li>
 <li class="toctree-l1"><a class="reference internal" href="../../../network/docs/index.html">BLE User Guide</a></li>

master/os/core_os/context_switch/context_switch.html

@@ -246,6 +246,7 @@ <h4>Latest News:</h4> <a href="/download">Apache Mynewt 1.5.0 </a> released (Nov
 <li class="toctree-l2"><a class="reference internal" href="../../modules/sensor_framework/sensor_framework.html">Sensor Framework</a></li>
 <li class="toctree-l2"><a class="reference internal" href="../../modules/testutil/testutil.html">Test Utilities</a></li>
 <li class="toctree-l2"><a class="reference internal" href="../../modules/json/json.html">JSON</a></li>
+<li class="toctree-l2"><a class="reference internal" href="../../modules/mfg/mfg.html">Manufacturing support</a></li>
 </ul>
 </li>
 <li class="toctree-l1"><a class="reference internal" href="../../../network/docs/index.html">BLE User Guide</a></li>

master/os/core_os/cputime/os_cputime.html

@@ -246,6 +246,7 @@ <h4>Latest News:</h4> <a href="/download">Apache Mynewt 1.5.0 </a> released (Nov
 <li class="toctree-l2"><a class="reference internal" href="../../modules/sensor_framework/sensor_framework.html">Sensor Framework</a></li>
 <li class="toctree-l2"><a class="reference internal" href="../../modules/testutil/testutil.html">Test Utilities</a></li>
 <li class="toctree-l2"><a class="reference internal" href="../../modules/json/json.html">JSON</a></li>
+<li class="toctree-l2"><a class="reference internal" href="../../modules/mfg/mfg.html">Manufacturing support</a></li>
 </ul>
 </li>
 <li class="toctree-l1"><a class="reference internal" href="../../../network/docs/index.html">BLE User Guide</a></li>

master/os/core_os/event_queue/event_queue.html

@@ -246,6 +246,7 @@ <h4>Latest News:</h4> <a href="/download">Apache Mynewt 1.5.0 </a> released (Nov
 <li class="toctree-l2"><a class="reference internal" href="../../modules/sensor_framework/sensor_framework.html">Sensor Framework</a></li>
 <li class="toctree-l2"><a class="reference internal" href="../../modules/testutil/testutil.html">Test Utilities</a></li>
 <li class="toctree-l2"><a class="reference internal" href="../../modules/json/json.html">JSON</a></li>
+<li class="toctree-l2"><a class="reference internal" href="../../modules/mfg/mfg.html">Manufacturing support</a></li>
 </ul>
 </li>
 <li class="toctree-l1"><a class="reference internal" href="../../../network/docs/index.html">BLE User Guide</a></li>

master/os/core_os/heap/heap.html

@@ -246,6 +246,7 @@ <h4>Latest News:</h4> <a href="/download">Apache Mynewt 1.5.0 </a> released (Nov
 <li class="toctree-l2"><a class="reference internal" href="../../modules/sensor_framework/sensor_framework.html">Sensor Framework</a></li>
 <li class="toctree-l2"><a class="reference internal" href="../../modules/testutil/testutil.html">Test Utilities</a></li>
 <li class="toctree-l2"><a class="reference internal" href="../../modules/json/json.html">JSON</a></li>
+<li class="toctree-l2"><a class="reference internal" href="../../modules/mfg/mfg.html">Manufacturing support</a></li>
 </ul>
 </li>
 <li class="toctree-l1"><a class="reference internal" href="../../../network/docs/index.html">BLE User Guide</a></li>

master/os/core_os/mbuf/mbuf.html

@@ -246,6 +246,7 @@ <h4>Latest News:</h4> <a href="/download">Apache Mynewt 1.5.0 </a> released (Nov
 <li class="toctree-l2"><a class="reference internal" href="../../modules/sensor_framework/sensor_framework.html">Sensor Framework</a></li>
 <li class="toctree-l2"><a class="reference internal" href="../../modules/testutil/testutil.html">Test Utilities</a></li>
 <li class="toctree-l2"><a class="reference internal" href="../../modules/json/json.html">JSON</a></li>
+<li class="toctree-l2"><a class="reference internal" href="../../modules/mfg/mfg.html">Manufacturing support</a></li>
 </ul>
 </li>
 <li class="toctree-l1"><a class="reference internal" href="../../../network/docs/index.html">BLE User Guide</a></li>

master/os/core_os/memory_pool/memory_pool.html

@@ -246,6 +246,7 @@ <h4>Latest News:</h4> <a href="/download">Apache Mynewt 1.5.0 </a> released (Nov
 <li class="toctree-l2"><a class="reference internal" href="../../modules/sensor_framework/sensor_framework.html">Sensor Framework</a></li>
 <li class="toctree-l2"><a class="reference internal" href="../../modules/testutil/testutil.html">Test Utilities</a></li>
 <li class="toctree-l2"><a class="reference internal" href="../../modules/json/json.html">JSON</a></li>
+<li class="toctree-l2"><a class="reference internal" href="../../modules/mfg/mfg.html">Manufacturing support</a></li>
 </ul>
 </li>
 <li class="toctree-l1"><a class="reference internal" href="../../../network/docs/index.html">BLE User Guide</a></li>