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-newt.git
The following commit(s) were added to refs/heads/master by this push: new e484676 newt/mfg: Update documentation e484676 is described below commit e48467639cab7a14c844e60f0bf146f08cf5167f Author: Christopher Collins <ccoll...@apache.org> AuthorDate: Tue Jan 8 16:47:58 2019 -0800 newt/mfg: Update documentation Add a description of the mfgimage file structure. --- newt/mfg/README.md | 113 ++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 112 insertions(+), 1 deletion(-) diff --git a/newt/mfg/README.md b/newt/mfg/README.md index 52dc5f0..80fba02 100644 --- a/newt/mfg/README.md +++ b/newt/mfg/README.md @@ -26,9 +26,85 @@ | Term | Long Name | Meaning | | ---- | --------- | ------- | | Flashdev | Flash device | A single piece of flash hardware. E.g., "internal flash", or "external SPI flash". | -| Mfgimage | Manufacturing image | A file with the entire contents of a single flashdev. At manufacturing time, a separate mfgimage is typically written to each of the device's flashdevs. | +| Mfgimage | Manufacturing image | A set of files describing the entire contents of a single flashdev. At manufacturing time, a separate mfgimage is created for each of the device's flashdevs. | +| Mfgimage main binary | The binary file in an mfgimage that actually gets written to a flashdev. | | MMR | Manufacturing Meta Region | A chunk of read-only data included in an mfgimage. Contains identifying information for the mfgimage and other data that stays with the device until end of life. | +### 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. + +| Key | Description | +| ------------- | ----------- | +| `name` | Name of mfgimage (informational). | +| `build_time` | Time mfgimage was created (informational). | +| `format` | The format version of the mfgimage binary. The current version is 2 | +| `mfg_hash` | The SHA256 of the mfgimage binary. To verify this hash, the embedded hash (if any) must be zeroed out prior to the calculation. | +| `version` | The version number of this particular mfgimage (informational). | +| `device` | The integer index of the flash device this mfgimage is intended for. | +| `bin_path` | The relative path of the main binary within the mfgimage. | +| `bsp` | The name of the BSP package that mfgimage was build for. | +| `signatures` | If the mfgimage is signed, this is an array of all the signatures. | +| `flash_map` | The BSP flash map at the time the mfgimage was created. | +| `targets` | An array of entries, each corresponding to a Mynewt target that is present in the mfgimage. | +| `meta` | A set of key-value pairs describing the manufacturing meta region (MMR) | + +#### 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: + +| Key | Description | +| ------------- | ----------- | +| key | The first four bytes of the SHA256 of the public key (hex string format). | +| sig | The full signature (hex string format). | + +#### 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: + +| Key | Description | +| ------------- | ----------- | +| `name` | The name of the flash area, as specified in `bsp.yml`. | +| `id` | The numeric ID of the flash area. | +| `device` | The numeric identifer of the flash device where the area resides. | +| `offset` | The offset of the start of the flash area within its flash device. | +| `size` | The size of the flash area, in bytes. | + +#### 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: + +| Key | Description | +| ------------- | ----------- | +| `name` | The name of the target, as specified in its `pkg.yml` file. | +| `offset` | The offset of the target binary within the mfgimage main binary. | +| `image_path` | Only present for image targets. The relative path of the Mynewt image file. | +| `bin_path` | Only present for non-image targets. The relative path of the target binary. | +| `manifest_path` | The relative path of the target manifest. | + +#### Meta + +The `meta` manifest object describes the contents of an mfgimage's MMR. It consists of the following key-value pairs: + +| Key | Description | +| --------------------- | ----------- | +| `end_offset` | One past the end of the MMR region, within the mfgimage main binary. | +| `size` | The size of the MMR, in bytes. | +| `hash_present` | `true` if the MMR contains a hash TLV; `false` otherwise. | +| `flash_map_present` | `true` if the MMR contains a set of flash area TLVs; `false` otherwise. | +| `mmrs` | An array of references to external MMRs. | + + ### Design #### artifact/mfg @@ -83,3 +159,38 @@ Newt uses the output of the decode step to determine which targets are included ###### 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 +└── targets + ├── 0 + │ ├── binary.bin + │ ├── elf.elf + │ └── manifest.json + ├── 1 + │ ├── elf.elf + │ ├── image.img + │ └── manifest.json + └── <N> + ├── <...> + <...> +``` + +Each of these files is described below: + +| Filename | Description | +| --------- | ----------- | +| `manifest.json` | JSON file describing the mfgimage contents. | +| `mfgimg.bin` | The mfgimage binary. This gets written to a Mynewt device. | +| `targets` | A directory containing information about each target embedded in the mfgimage. | +| `0/1/N` | Correponds to an individual target. Targets are numbered in the order they appear in `mfg.yml`. | +| `x/binary.bin` | Only present for boot loader targets. Contains the boot loader binary generated from the target. | +| `x/elf.elf` | The ELF file corresponding to the target binary. | +| `x/image.img` | Only present for non-boot targets. Contains the image generated from the target. | +| `x/manifest.json` | JSON file describing the target. |