This is an automated email from the ASF dual-hosted git repository. ccollins pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/mynewt-core.git
commit 72b3b92d90b375548a10f4360b1715709f9e9efe Author: Christopher Collins <[email protected]> AuthorDate: Tue Jan 8 16:19:25 2019 -0800 sys/mfg: Documentation --- docs/os/modules/mfg/mfg.rst | 127 ++++++++++++++++++++++++++++++++++++++++++++ docs/os/os_user_guide.rst | 1 + 2 files changed, 128 insertions(+) diff --git a/docs/os/modules/mfg/mfg.rst b/docs/os/modules/mfg/mfg.rst new file mode 100644 index 0000000..180740a --- /dev/null +++ b/docs/os/modules/mfg/mfg.rst @@ -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 diff --git a/docs/os/os_user_guide.rst b/docs/os/os_user_guide.rst index f707e6b..f69e6a2 100644 --- a/docs/os/os_user_guide.rst +++ b/docs/os/os_user_guide.rst @@ -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
