mfg

Definitions:

Manifest

Each mfgimage contains a manifest.json file. A manufacturing manifest contains metadata describing the mfgimage.

Top-level

Manufacturing manifests are formatted as a JSON object consisting of key-value pairs. Complex entries are further described in follow-up tables.

Signatures

Mfgimages are signed to ensure integrity. Typically, Mynewt images embedded in the mfgimage are individually signed, so are already protected. The rest of the data in the mfgimage--boot loader, MMRs, configuration data, etc--is not individually signed. It is this second class of data that is protected by mfgimage signatures.

To sign an mfgimage, use the private key to sign the mfg_hash.

The signatures element is an array of objects, each consisting of the following key-value pairs:

Flash Map

Every mfgimage contains a flash map in its manifest. This information is present, even the MMR does not actually contain a flash map.

In the manifest, the flash_map entry is an array of flash area objects, each consisting of the following key-valur pairs:

Targets

Most mfgimages contain at least one target. A target can be either of 1) boot loader, or 2) Mynewt image. In the manifest, the targets entry indicates the targets present in the mfgimage. This entry is an array of target objects, each consisting of the following key-value pairs:

Meta

The meta manifest object describes the contents of an mfgimage's MMR. It consists of the following key-value pairs:

MMR Structure

Every mfgimage contains an MMR (manufacturing meta region). The MMR is always located at the end of a flash area (that is, the last byte in the MMR occupies the last byte in the flash area).

In a boot mfgimage, the MMR must go in the first flash area, i.e., the area containing the boot loader. A non-boot mfgimage can place its MMR in any flash area.

The reason a boot mfgimage‘s MMR must go in the boot loader area is to solve a boot strapping problem. The flash map that bsp.yml defines is not necessarily the flash map that every device uses; it is just the flash map that gets embedded in newly built mfg images. This is so becauase the flash map itself is embedded in the boot mfgimage’s MMR. If we change the contents of bsp.yml and then start manufacturing devices with a new mfgimage, we now have two different flash maps being used in the field, even after all devices get upgraded to the latest firmware. Since MMR-0 itself contains the flash map, the firmware must not require a flash map lookup to find this MMR (i.e., chicken and egg). So this initial MMR always gets placed in the boot loader area and the firmware is hardcoded to look for it there.

An MMR has three basic components: header, TLVs, and footer.

     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
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -,
    |Version (0x01) |                  0xff padding                 |   >-- Header
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -'
    |   TLV type    |   TLV size    | TLV data ("TLV size" bytes)   ~
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+                               ~
    ~                                                               ~
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    |   TLV type    |   TLV size    | TLV data ("TLV size" bytes)   ~
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+                               ~
    ~                                                               ~
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -,
    |   Region size                 |         0xff padding          |   \
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+    >- Footer
    |                       Magic (0x3bb2a269)                      |   /
    +-+-+-+-+-+--+-+-+-+-end of boot loader area+-+-+-+-+-+-+-+-+-+-+ -'

All numeric fields are in host byte order (typically little endian).

The number of TLVs is variable; two are shown above for illustrative purposes.

Header

TLVs

Footer

Design

artifact/mfg

The artifact library defines the Mfg type. An Mfg is a barebones representation of an mfgimage. It contains a raw binary of everything except the MMR, and a slice of MMR TLVs. An Mfg is be converted to a flat byte slice with the following sequence:

1. Calculate the SHA256 and add it to the MMR (Mfg#CalcHash())
2. Extract the byte-slice representation (Mfg#Bytes())

An Mfg can be parsed from a byte slice using the Parse() function.

newt/mfg

High level

The newt tool creates mfgimages from:

1. An mfg definition (including an mfg.yml file).
2. Build artifacts for each target specified in the mfg.yml file.

Therefore, mfgimage creation typically goes something like this:

1. Build boot loader: newt build <...>
2. Create [signed, encrypted] images: newt create-image -2 <...> 1.2.3.4
3. Build mfgimage: newt mfg create <...>

An mfgimage created by newt consists of:

1. The binary flashdev contents.
2. A manifest.json file describing the mfgimage.
3. Build artifacts that were used as inputs.

Details

Newt performs a sequence of data structure transformations to produce the outputs listed above. In the sequence depicted below, objects are enclosed in [brackets], steps are enclosed in (parentheses).

          (decode)          (build)          (emit)
[MfgDecoder] --> [MfgBuilder] --> [MfgEmitter] --> [OUTPUT]

The steps are described below.

1. Decode

Newt parses and verifies the mfg.yml file.

2. Build

Newt uses the output of the decode step to determine which targets are included in the mfgimage. It ensures the targets have been built and that they all share the same BSP. Finally, it produces an artifact/Mfg object from the necessary binary files.

3. Emit

Newt produces the manifest and writes all the mfgimage files to disk.

File structure

Below is an example of an mfgimage's file structure:

bin/mfgs/<mfg-name>/
├── manifest.json
├── mfgimg.bin
├── mfgimg.hex
└── targets
    ├── 0
    │   ├── binary.bin
    │   ├── elf.elf
    │   ├── image.hex
    │   └── manifest.json
    ├── 1
    │   ├── elf.elf
    │   ├── image.hex
    │   ├── image.img
    │   └── manifest.json
    └── <N>
        ├── <...>
      <...>

Each of these files is described below: