Revision 14:9476f399341e, committed 2017-06-19

Comitter:

mbed_official

Date:

Mon Jun 19 22:00:16 2017 +0100

Parent:

13:a12ab11a4edb

Child:

15:152ee19cab10

Commit message:

Distinguish app and bootloader binaries. Use app config.

This attempts to clarify a few vague points in the README. It helps to
distinguish between the different binaries created during the bootloader
building process.

It takes care of the somewhat confusing '/sd/' mount path for the
SD card. This is now handled by the program, allowing the user to just
specify the name of the binary that is placed in the root of the SD card.

It makes more use of app config to support onboard SD card slots
for the K64F and the UBLOX_EVK_ODIN_W2. It will use the Arduino SPI pins
for any other target.

The application update binary name is now specified in the app config as
well.

.
Commit copied from https://github.com/ARMmbed/mbed-os-example-bootloader

Changed in this revision

--- a/README.md	Thu Jun 08 20:30:15 2017 +0100
+++ b/README.md	Mon Jun 19 22:00:16 2017 +0100
@@ -5,9 +5,9 @@
 To read more about the bootloader, please visit [bootloader tutorial](https://docs.mbed.com/docs/mbed-os-handbook/en/latest/advanced/bootloader/).
 
 ## Required hardware
-* A supported board - [u-blox EVK-ODIN-W2](https://developer.mbed.org/platforms/ublox-EVK-ODIN-W2/), [Nucleo F429ZI](https://developer.mbed.org/platforms/ST-Nucleo-F429ZI/) or [K64F](https://developer.mbed.org/platforms/FRDM-K64F/).
-* CI test shield.
+* A supported target - [u-blox EVK-ODIN-W2](https://developer.mbed.org/platforms/ublox-EVK-ODIN-W2/), [Nucleo F429ZI](https://developer.mbed.org/platforms/ST-Nucleo-F429ZI/) or [K64F](https://developer.mbed.org/platforms/FRDM-K64F/).
 * SD card.
+* If your supported target does not have an SD card port, you need a shield or breakout board with an SD card port that uses SPI pins.
 
 ## Import the example application
 
@@ -18,11 +18,40 @@
 cd mbed-os-example-bootloader
 ```
 
-## Set up application to be a bootloader
+## Connecting the SD card
+This example uses the **onboard SD card port** for the K64F and the UBLOX_EVK_ODIN_W2.
+
+Other targets use the following Arduino form-factor SPI pins by default:
+- `D11` - `MOSI`
+- `D12` - `MISO`
+- `D13` - `SCK`
+- `D10` - `CS`
+
+
+To use different SPI pins, you need to modify the `mbed_app.json` file. Add a key for your target to the `target_overrides` section with the following data (replace `<TARGET_NAME>` with your target's name):
 
-All supported boards mentioned above are set up to build as a bootloader image. To add support for a new board, you must specify the size of the bootloader.
+```
+{
+    ...
+    "target_overrides": {
+        ...
+        "<TARGET_NAME>": {
+            "sd_card_mosi": "<MOSI_PIN>",
+            "sd_card_miso": "<MISO_PIN>",
+            "sd_card_sck": "<SCK_PIN>",
+            "sd_card_cs": "<CS_PIN>"
+        }
+        ...
+    }
+    ...
+}
+```
 
-To do this, set the target (replace `<TARGET_NAME>` with your target name) value `restrict_size` to the maximum bootloader size in mbed_app.json:
+## Preparing the bootloader
+
+All supported targets mentioned above are set up to build as a bootloader image. To add support for a new target, you must specify the size of the bootloader.
+
+To do this, set the target value `restrict_size` to the maximum bootloader size in `mbed_app.json` (replace `<TARGET_NAME>` with your target name):
 
 ```
     "target_overrides": {
@@ -33,11 +62,11 @@
         ...
 ```
 
-Note - `restrict_size` pads the build image to the requested size.
+<span class="tips">**Note:** `restrict_size` pads the build image to the requested size.</span>
 
-## Now compile
+## Building the bootloader
 
-Invoke `mbed compile`, and specify the name of your platform and your favorite toolchain (`GCC_ARM`, `ARM`, `IAR`). For example, for the ARM Compiler 5:
+Invoke `mbed compile`, and specify the name of your target and your favorite toolchain (`GCC_ARM`, `ARM`, `IAR`). For example, for the ARM Compiler:
 
 ```
 mbed compile -m <TARGET_NAME> -t ARM
@@ -74,46 +103,55 @@
 Image: .\BUILD\<TARGET_NAME>\ARM\mbed-os-example-bootloader.bin
 ```
 
-It creates two binary files. The original uncombined image is in the output directory, <project-name>_application.bin, and the bootloader image is <project-name>.bin.
-
-When the build succeeds, you have created a bootloader for your target. This example defines the application file to be located at `/sd/mbed-os-example-blinky_application.bin` in the application config file ``mbed_app.json``. This is the application binary bootloader flashes and then jumps to.
+After the build completes, the build system creates two binary images in the `BUILD/<TARGET_NAME>/<TOOLCHAIN_NAME>` directory: `<project-name>.bin` and `<project-name>_application.bin`. `<project-name>.bin` is the padded bootloader (used for combining with applications). `<project-name>_application.bin` is the original unpadded bootloader.
 
-## Set up application to use bootloader
+In this example, `main.cpp` defines the update binary for the bootloader as `mbed-os-example-blinky_application.bin` (specified under the macro `UPDATE_FILE`). The bootloader looks for this file in the root of the SD card, flashes it to memory and then jumps to the application.
 
-### Program bootloader and application
+## Building the application with the bootloader
 
 The next step is to build an application you can combine with your bootloader to create a loadable image. 
 
-1. Update your board to use the newly created bootloader image. To do this, set the target (replace `<TARGET_NAME>` with your target name) value `bootloader_img` to the file path of the bootloader image.
+1. Instruct the build system to use the newly created padded bootloader image (named `<project-name>.bin` in the previous section). To do this, create a `target_overrides` section in your application's `mbed_app.json` file, and add a key for your target (see `<TARGET_NAME>` in the example below). If `mbed_app.json` does not already exist in your application, create one.
+
+2. Set the target value `bootloader_img` in `mbed_app.json` to the file path of the padded bootloader image. For the below example, copy the padded bootloader image to the project directory.
 
 ```
+{
     "target_overrides": {
         ...
         "<TARGET_NAME>": {
-            "target.bootloader_img": "bootloader/<TARGET_NAME>.bin"
+            "target.bootloader_img": "<path to padded bootloader binary>"
         },
         ...
+}
 ```
 
-2. Invoke `mbed compile`, and specify the name of your platform and the toolchain you are using (`GCC_ARM`, `ARM`, `IAR`). For example, for the ARM Compiler 5:
+2. Invoke `mbed compile`, and specify the name of your target and the toolchain you are using (`GCC_ARM`, `ARM`, `IAR`). For example, for the ARM Compiler:
 
     ```
     mbed compile -m <TARGET_NAME> -t ARM
     ```
 
+After the build completes, the build system creates two binary images in the `BUILD/<TARGET_NAME>/<TOOLCHAIN_NAME>` directory: `<project-name>.bin` and `<project-name>_application.bin`. `<project-name>.bin` is the combined bootloader and application (suitable for flashing to the device's ROM directly). `<project-name>_application.bin` is the update binary (the one you place on the SD card).
+
+### Program the application with the bootloader included
+
+Follow these steps to program the target with the combined bootloader and application image. You then can update the application from the SD card.
 
 1. Connect your mbed device to the computer over USB.
-1. Copy the binary file (``<program name.bin>``) to the mbed device.
+1. Copy the combined bootloader and application binary file (named `<project-name>.bin` in the previous section) to the mbed device.
 1. Press the reset button to start the program.
 
-### Program application using SD card
+### Program the application from the bootloader (load from SD card)
+
+<span class="tips">**Note:** You must first flash the combined bootloader and application image or just the bootloader image (padded or unpadded) before proceeding with the following steps.</span>
 
 1. Connect the SD card to your computer.
-1. Copy the application binary (``<program name>_application.bin``, we defined it earlier as ``mbed-os-example-blinky_application.bin``) to the root of the SD card.
-1. Remove the SD card from your PC, and plug it into the mbed board.
+1. Copy the update application binary (named `<project-name>_application.bin` in the previous section) to the root of the SD card.
+1. Remove the SD card from your PC, and connect it to your mbed (see the above section [Connecting the SD card](#connecting-the-sd-card))
 1. Press the reset button to start the firmware update.
 
-If a terminal is open, the following prints:
+If a terminal is open, the following prints at a baud rate of 9600:
 
 ```
 Firmware update found
@@ -128,7 +166,7 @@
     mbed --version
     ```
 
- If not, you can update it:
+    If not, you can update it:
 
     ```
     pip install mbed-cli --upgrade

--- a/main.cpp	Thu Jun 08 20:30:15 2017 +0100
+++ b/main.cpp	Mon Jun 19 22:00:16 2017 +0100
@@ -2,8 +2,13 @@
 #include "SDBlockDevice.h"
 #include "FATFileSystem.h"
 
-SDBlockDevice sd(D11, D12, D13, D10);
-FATFileSystem fs("sd");
+#define SD_MOUNT_PATH           "sd"
+#define FULL_UPDATE_FILE_PATH   "/" SD_MOUNT_PATH "/" MBED_CONF_APP_UPDATE_FILE
+
+//Pin order: MOSI, MISO, SCK, CS
+SDBlockDevice sd(MBED_CONF_APP_SD_CARD_MOSI, MBED_CONF_APP_SD_CARD_MISO,
+                 MBED_CONF_APP_SD_CARD_SCK, MBED_CONF_APP_SD_CARD_CS);
+FATFileSystem fs(SD_MOUNT_PATH);
 FlashIAP flash;
 
 void apply_update(FILE *file, uint32_t address);
@@ -13,14 +18,14 @@
     sd.init();
     fs.mount(&sd);
 
-    FILE *file = fopen(MBED_CONF_APP_UPDATE_FILE, "rb");
+    FILE *file = fopen(FULL_UPDATE_FILE_PATH, "rb");
     if (file != NULL) {
         printf("Firmware update found\r\n");
 
         apply_update(file, POST_APPLICATION_ADDR);
 
         fclose(file);
-        remove(MBED_CONF_APP_UPDATE_FILE);
+        remove(FULL_UPDATE_FILE_PATH);
     } else {
         printf("No update found to apply\r\n");
     }

--- a/mbed_app.json	Thu Jun 08 20:30:15 2017 +0100
+++ b/mbed_app.json	Mon Jun 19 22:00:16 2017 +0100
@@ -1,13 +1,40 @@
 {
+    "config": {
+        "update_file": {
+            "help": "Path to the application update binary on the SD card",
+            "value": "\"mbed-os-example-blinky_application.bin\""
+        },
+        "sd_card_mosi": {
+            "help": "MCU pin connected to the SD card's SPI MOSI pin",
+            "value": "D11"
+        },
+        "sd_card_miso": {
+            "help": "MCU pin connected to the SD card's SPI MISO pin",
+            "value": "D12"
+        },
+        "sd_card_sck": {
+            "help": "MCU pin connected to the SD card's SPI SCK pin",
+            "value": "D13"
+        },
+        "sd_card_cs": {
+            "help": "MCU pin connected to the SD card's SPI CS pin",
+            "value": "D10"
+        }
+    },
     "target_overrides": {
         "K64F": {
-            "target.restrict_size": "0x40000"
+            "target.restrict_size": "0x40000",
+            "sd_card_mosi": "PTE3",
+            "sd_card_miso": "PTE1",
+            "sd_card_sck": "PTE2",
+            "sd_card_cs": "PTE4"
         },
         "NUCLEO_F429ZI": {
             "target.restrict_size": "0x40000"
         },
         "UBLOX_EVK_ODIN_W2": {
-            "target.restrict_size": "0x40000"
+            "target.restrict_size": "0x40000",
+            "sd_card_cs": "D9"
         }
     },
     "config": {