+
+ +
+

Manufacturing Support

+
+
+
+

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

+ +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TermLong NameMeaning
FlashdevFlash deviceA single piece of flash hardware. A typical device might contain two flashdevs: 1) internal flash, and 2) external SPI flash.
MfgimageManufacturing imageA 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 MfgimageBoot manufacturing imageThe mfgimage containing the boot loader; always written to internal flash.
MMRManufacturing Meta RegionA 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.
TLVType Length ValueA simple extensible means of representing data. Contains three fields: 1) type of data, 2) length of data, and 3) the data itself.
MfgIDManufacturing IDIdentifies 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. +
  2. TLV size: The number of bytes of data to follow.
    3. +
  3. TLV data: “TLV size” bytes of data.
    4. +
+

<Footer>

+
    +
  1. Region size: The size, in bytes, of the entire manufacturing meta region; includes TLVs and footer.
    2. +
  2. Version: Manufacturing meta version number; always 0x02.
    3. +
  3. Magic: Indicates the presence of the manufacturing meta region.
    4. +
+
+

API

+
+

Defines

+
+
+MFG_HASH_SZ
+
+ +
+
+MFG_META_TLV_TYPE_HASH
+
+ +
+
+MFG_META_TLV_TYPE_FLASH_AREA
+
+ +
+
+MFG_META_TLV_TYPE_FLASH_TRAITS
+

Informational only; not read by firmware.

+
+ +
+
+MFG_META_TLV_TYPE_MMR_REF
+
+ +
+
+MFG_LOG(lvl_, ...)
+
+ +
+
+

Functions

+
+
+void mfg_open(struct mfg_reader * out_reader)
+

Opens the manufacturing space for reading.

+

The resulting mfg_reader object should be passed to subsequent seek and read functions.

+
+ +
+
+int mfg_seek_next(struct mfg_reader * reader)
+

Seeks to the next mfg TLV.

+

The caller must initialize the supplied mfg_reader with mfg_open() prior to calling this function.

+

+
Return
+
0 if the next TLV was successfully seeked to. SYS_EDONE if there are no additional TLVs available. Other MFG error code on failure.
+
Parameters
+
    +
  • reader: The reader to seek with.
    • +
+
+
+

+
+ +
+
+int mfg_seek_next_with_type(struct mfg_reader * reader, uint8_t type)
+

Seeks to the next mfg TLV with the specified type.

+

The caller must initialize the supplied mfg_reader with mfg_open() prior to calling this function.

+

+
Return
+
0 if the next TLV was successfully seeked to. SYS_EDONE if there are no additional TLVs with the specified type available. Other MFG error code on failure.
+
Parameters
+
    +
  • reader: The reader to seek with.
    • +
  • type: The type of TLV to seek to; one of the MFG_META_TLV_TYPE_[…] constants.
    • +
+
+
+

+
+ +
+
+int mfg_read_tlv_hash(const struct mfg_reader * reader, void * out_hash)
+

Reads a hash TLV from the manufacturing space.

+

This function should only be called when the provided reader is pointing at a TLV with the MFG_META_TLV_TYPE_HASH type.

+

+
Return
+
0 on success; MFG error code on failure.
+
Parameters
+
    +
  • reader: The reader to read with.
    • +
  • out_mr: (out) On success, the retrieved MMR reference information gets written here.
    • +
+
+
+

+
+ +
+
+int mfg_read_tlv_flash_area(const struct mfg_reader * reader, struct mfg_meta_flash_area * out_mfa)
+

Reads a flash-area TLV from the manufacturing space.

+

This function should only be called when the provided reader is pointing at a TLV with the MFG_META_TLV_TYPE_FLASH_AREA type.

+

+
Return
+
0 on success; MFG error code on failure.
+
Parameters
+
    +
  • reader: The reader to read with.
    • +
  • out_mfa: (out) On success, the retrieved flash area information gets written here.
    • +
+
+
+

+
+ +
+
+int mfg_read_tlv_mmr_ref(const struct mfg_reader * reader, struct mfg_meta_mmr_ref * out_mr)
+

Reads an MMR ref TLV from the manufacturing space.

+

This function should only be called when the provided reader is pointing at a TLV with the MFG_META_TLV_TYPE_MMR_REF type.

+

+
Return
+
0 on success; MFG error code on failure.
+
Parameters
+
    +
  • reader: The reader to read with.
    • +
  • out_mr: (out) On success, the retrieved MMR reference information gets written here.
    • +
+
+
+

+
+ +
+
+void mfg_init(void)
+

Initializes the mfg package.

+
+ +
+
+

Variables

+
+
+uint8_t type
+
+ +
+
+uint32_t size
+
+ +
+
+uint8_t area_id
+
+ +
+
+uint8_t device_id
+
+ +
+
+uint32_t offset
+
+ +
+
+uint8_t min_write_sz
+
+ +
+
+
+struct mfg_meta_tlv
+
#include <mfg.h>
+

Public Members

+
+
+uint8_t type
+
+ +
+
+uint8_t size
+
+ +
+
+ +
+
+struct mfg_meta_flash_area
+
#include <mfg.h>
+

Public Members

+
+
+uint8_t area_id
+
+ +
+
+uint8_t device_id
+
+ +
+
+uint32_t offset
+
+ +
+
+uint32_t size
+
+ +
+
+ +
+
+struct mfg_meta_flash_traits
+
#include <mfg.h>

Informational only; not read by firmware.

+
+

Public Members

+
+
+uint8_t device_id
+
+ +
+
+uint8_t min_write_sz
+
+ +
+
+ +
+
+struct mfg_meta_mmr_ref
+
#include <mfg.h>
+

Public Members

+
+
+uint8_t area_id
+
+ +
+
+ +
+
+struct mfg_reader
+
#include <mfg.h>

Object used for reading records from the manufacturing space.

+

The mfg_open() function should be used to construct a reader object.

+
+

Public Members

+
+
+struct mfg_meta_tlv cur_tlv
+

Public (read-only).

+
+ +
+
+uint8_t mmr_idx
+

Private.

+
+ +
+
+uint32_t offset
+
+ +
+
+ +
+
+
+ + +
+