Add data sharing feature demo

AGlass0fMilk · AGlass0fMilk · commit 50e9cdec9822 · 2021-09-14T11:10:43.000-04:00
This commit adds a demonstration of MCUboot's data sharing feature to this repository. See mcu-tools/mcuboot#1115 for more details.
diff --git a/README.md b/README.md
@@ -366,3 +366,70 @@ int ret = boot_set_confirmed();
 ```
 
 In real world situations, your application should run a self test routine to ensure it can receive updates in the future (eg: the UART software works as expected, the BLE stack initializes successfully, etc).
+
+## Additional Features
+
+MCUboot integrates a number of additional features that are commonly used in bootloader situations. More details of these features can be found in the mcuboot documentation/code.
+
+The following sections detail how to enable and use these features in your Mbed-based bootloader/application.
+
+### [Direct XIP](https://www.mcuboot.com/documentation/design/#direct-xip)
+
+TODO
+
+### [Shared Data (experimental)](https://www.mcuboot.com/documentation/design/#boot-data-sharing)
+
+From the MCUboot documentation:
+
+> MCUBoot defines a mechanism for sharing boot status information (also known as measured boot) and an interface for sharing application specific information with the runtime software. 
+
+The data shared from the bootloader to the application is stored in a reserved section of RAM in the form of type-length-value (TLV) encoded entries. This allows you to share any arbitrary data from the bootloader to the application.
+
+#### Configuration
+
+Several configuration changes must be made in both the bootloader and application to enable this feature. Namely:
+
+- `mcuboot.share-data` must be configured to `true`
+- `mcuboot.share-data-base-address` must be set to a word-aligned memory address in RAM. Typically, a small section of RAM is reserved at the end of the MCU's RAM address space for data sharing, which brings us to the next configuration parameters
+- `mcuboot.share-data-size` is set to the number of bytes you want to reserve in RAM for the shared data
+- You must add the following entries to your `target.macros_add` configuration: `MBED_RAM_START=<address>` and `MBED_RAM_SIZE=<RAM size minus reserved region size>`.
+
+`MBED_RAM_START` should be the starting address of RAM as per your MCU's datasheet. `MBED_RAM_SIZE` should be the total size of your MCU's RAM minus the number of bytes you are reserving for shared data. Note that the required reserved RAM depends on how many entries you want to share with the application.
+
+As mentioned in the MCUboot documentation, the data share region has a global header that is 4 bytes. Each TLV entry has a header size of 4 bytes, plus the number of bytes required to store the data you are sharing.
+
+Let's say you want to reserve 512 bytes of RAM for data sharing, your MCU has a RAM address space that starts at `0x20000000` and your MCU physically has 64kB of RAM. In this case, your configuration file will look as follows:
+
+```
+[...]
+"mcuboot.share-data": true,
+"mcuboot.share-data-base-address": "0x2000FE00",
+"mcuboot.share-data-size": "0x200",
+"target.macros_add": ["MBED_RAM_START=0x20000000", 
+                      "MBED_RAM_SIZE=0xFE00"],
+[...]
+```
+
+Calculations to get the above:
+
+`mcuboot.share-data-size = reserved_bytes = 512`
+`MBED_RAM_START = 0x20000000`
+`mcuboot.share-data-base-address = MBED_RAM_START + total_RAM - reserved_bytes = 0x20000000 + 64kB - 512 = 0x20000000 + 0x10000 - 0x200 = 0x2000FE00`
+`MBED_RAM_SIZE = total_RAM - reserved_bytes = 0x10000 - 0x200 = 0xFE00`
+
+Note that you will have to add this configuration to both your bootloader and application builds. Setting `MBED_RAM_SIZE` prevents initialization code from clearing the reserved RAM region at startup, which would corrupt the shared data.
+
+Also note that any RAM reserved for data sharing will be unavailable to the application stack/heap (TODO: fix this, better mbed-os integration), so try to keep your reserved region as small as possible.
+For an example configuration that is already setup for the nRF52840_DK target, see the `mbed_app_data_sharing.json` file in this repository.
+
+**Note:** With Mbed CLI 1, you can use the `--app-config mbed_app_data_sharing.json` option flag to use the data sharing configuration without renaming any files. Building the bootloader and application with this flag will demonstrate usage of the data sharing feature.
+
+#### Code Changes - Bootloader
+
+With `mcuboot.shared-data` enabled, the MCUboot bootloader expects a C function to be defined called `boot_save_shared_data`. This function provides a hook for you to add custom TLVs to the shared data region as you require. For an example implementation, see the `shared_data.c/.h` files in this repository.
+
+#### Code Changes - Application
+
+Once you have shared data setup and configured for both the bootloader and application, you are ready to access the shared data. During boot, the bootloader will populate the shared data RAM region with the information as you specify in the `boot_save_shared_data` function. The application may then read that information back.
+
+An example of how to do this is built into the `mbed-mcuboot-blinky` application when `mcuboot.share-data` is set to true.
diff --git a/mbed_app_data_sharing.json b/mbed_app_data_sharing.json
@@ -0,0 +1,69 @@
+{
+    "requires": ["bare-metal", "mbedtls", "mcuboot", "flashiap-block-device", "mbed-trace", "qspif"],
+    "config": {
+        "serial-bootloader-enable": {
+            "help": "Build bootloader with serial update support",
+            "value": 0
+        }
+    },
+    "target_overrides": {
+        "*": {
+            "target.restrict_size": "0x20000",
+            "target.c_lib": "small",
+            "mcuboot.log-level": "MCUBOOT_LOG_LEVEL_DEBUG",
+            "mbed-trace.enable": false,
+            "mbed-trace.fea-ipv6": false,
+            "platform.crash-capture-enabled": false,
+            "platform.minimal-printf-enable-64-bit": false,
+            "platform.callback-comparable": false
+        },
+        "NRF52840_DK": {
+            "target.features_remove": ["CRYPTOCELL310"],
+            "target.macros_remove": ["MBEDTLS_CONFIG_HW_SUPPORT"],
+            "mcuboot.primary-slot-address": "0x20000",
+            "mcuboot.slot-size": "0xC0000",
+            "mcuboot.scratch-address": "0xE0000",
+            "mcuboot.scratch-size": "0x20000",
+            "mcuboot.max-img-sectors": "0x180",
+            "mcuboot.read-granularity": 4,
+            "qspif.QSPI_MIN_PROG_SIZE": 4,
+            "mcuboot.share-data": true,
+            "mcuboot.share-data-base-address": "0x2003FC00",
+            "mcuboot.share-data-size": "0x400",
+            "target.macros_add": ["MBED_RAM_START=0x20000000",
+                                  "MBED_RAM_SIZE=0x3FC00"]
+        },
+        "EP_AGORA": {
+            "target.features_remove": ["CRYPTOCELL310"],
+            "target.macros_remove": ["MBEDTLS_CONFIG_HW_SUPPORT"],
+            "mcuboot.primary-slot-address": "0x20000",
+            "mcuboot.slot-size": "0xC0000",
+            "mcuboot.scratch-address": "0xE0000",
+            "mcuboot.scratch-size": "0x20000",
+            "mcuboot.max-img-sectors": "0x180",
+            "mcuboot.read-granularity": 4,
+            "qspif.QSPI_MIN_PROG_SIZE": 4
+        },
+        "DISCO_L475VG_IOT01A": {
+            "mcuboot.primary-slot-address": "0x8020000",
+            "mcuboot.slot-size": "0xC0000",
+            "mcuboot.scratch-address": "0x80E0000",
+            "mcuboot.scratch-size": "0x20000",
+            "mcuboot.max-img-sectors": "0x180",
+            "mcuboot.read-granularity": 1,
+            "qspif.QSPI_MIN_PROG_SIZE": 1
+        },
+        "NRF52_DK": {
+            "target.components_add": ["FLASHIAP"],
+            "target.console-uart": false,
+            "mcuboot.primary-slot-address": "0x20000",
+            "mcuboot.slot-size": "0xC0000",
+            "mcuboot.scratch-address": "0xE0000",
+            "mcuboot.scratch-size": "0x20000",
+            "mcuboot.max-img-sectors": "0x180",
+            "mcuboot.read-granularity": 4,
+            "target.device_has_remove": ["STDIO_MESSAGES"],
+            "target.macros_add": ["MBED_FAULT_HANDLER_DISABLED"]
+        }
+    }
+}
diff --git a/mcuboot.lib b/mcuboot.lib
@@ -1 +1 @@
-https://github.com/mcu-tools/mcuboot.git
+https://github.com/mcu-tools/mcuboot.git
diff --git a/shared_data.c b/shared_data.c
@@ -0,0 +1,46 @@
+/**
+ * ep-oc-mcu
+ * Embedded Planet Open Core for Microcontrollers
+ *
+ * Built with ARM Mbed-OS
+ *
+ * Copyright (c) 2019-2021 Embedded Planet, Inc.
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#include "boot_record.h"
+#include "shared_data.h"
+
+#if MCUBOOT_DATA_SHARING && MCUBOOT_BOOTLOADER_BUILD
+
+int boot_save_shared_data(const struct image_header *hdr,
+                          const struct flash_area *fap) {
+
+    char msg[] = "hello world :)";
+    char second_msg[] = "abcdefghijklmnopqrstuvwxyz012345789";
+
+    int result = boot_add_data_to_shared_area(TLV_MAJOR_APP_SPECIFIC, TLV_MINOR_BOOTLOADER_VERSION, strlen(msg), msg);
+    if(result) {
+        return result;
+    }
+
+    result = boot_add_data_to_shared_area(TLV_MAJOR_APP_SPECIFIC, TLV_MINOR_MY_MESSAGE, strlen(second_msg), second_msg);
+
+    return result;
+
+}
+
+#endif /* MCUBOOT_DATA_SHARING */
+
diff --git a/shared_data.h b/shared_data.h
@@ -0,0 +1,30 @@
+/*
+ * Mbed-OS Microcontroller Library
+ * Copyright (c) 2021 Embedded Planet
+ * Copyright (c) 2021 ARM Limited
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License
+ */
+
+#ifndef SHARED_DATA_H_
+#define SHARED_DATA_H_
+
+/* See boot_status.h in mcuboot sources for more information
+ * on the format of the tlv_type field of the shared data TLVs
+ * The upper 4 bits are the major TLV category */
+#define TLV_MAJOR_APP_SPECIFIC 0xF
+#define TLV_MINOR_BOOTLOADER_VERSION 0x10D
+#define TLV_MINOR_MY_MESSAGE 0x10E
+
+#endif /* SHARED_DATA_H_ */

Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-https://github.com/mcu-tools/mcuboot.git`
	`1`	`+https://github.com/mcu-tools/mcuboot.git`