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

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>

  1. Region size: The size, in bytes, of the entire manufacturing meta region; includes TLVs and footer.

  2. Version: Manufacturing meta version number; always 0x02.

  3. Magic: Indicates the presence of the manufacturing meta region.

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
uint8_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