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:

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: