mbed-os-examples / Mbed OS mbed-os-example-mbed5-bootloader

.

README.md@5:d57adfa16284, 2017-03-28 (annotated)

Committer:
mbed_official
Date:
Tue Mar 28 10:45:25 2017 +0100
Revision:
5:d57adfa16284
Parent:
4:0daf612a367a
Child:
11:d396becb5d76
Merge pull request #8 from 0xc0170/fix_readme_blinky



Readme: remove blinky app reference

.

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

Who changed what in which revision?

UserRevisionLine numberNew contents of line
mbed_official 0:8df79c088b12 1 # Getting started with bootloader on mbed OS
mbed_official 0:8df79c088b12 2
mbed_official 5:d57adfa16284 3 This example shows how to create a bootloader.
mbed_official 0:8df79c088b12 4
mbed_official 2:fc74f70b51c3 5 To read more about the bootloader, please visit [bootloader tutorial](https://docs.mbed.com/docs/mbed-os-handbook/en/latest/advanced/bootloader/).
mbed_official 2:fc74f70b51c3 6
mbed_official 0:8df79c088b12 7 ## Required hardware
mbed_official 0:8df79c088b12 8 * 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/).
mbed_official 4:0daf612a367a 9 * CI test shield.
mbed_official 0:8df79c088b12 10 * SD card.
mbed_official 0:8df79c088b12 11
mbed_official 0:8df79c088b12 12 ## Import the example application
mbed_official 0:8df79c088b12 13
mbed_official 0:8df79c088b12 14 From the command-line, import the example:
mbed_official 0:8df79c088b12 15
mbed_official 0:8df79c088b12 16 ```
mbed_official 2:fc74f70b51c3 17 mbed import mbed-os-example-bootloader
mbed_official 2:fc74f70b51c3 18 cd mbed-os-example-bootloader
mbed_official 0:8df79c088b12 19 ```
mbed_official 0:8df79c088b12 20
mbed_official 0:8df79c088b12 21 ## Set up application to be a bootloader
mbed_official 0:8df79c088b12 22
mbed_official 0:8df79c088b12 23 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.
mbed_official 4:0daf612a367a 24
mbed_official 4:0daf612a367a 25 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:
mbed_official 0:8df79c088b12 26
mbed_official 0:8df79c088b12 27 ```
mbed_official 0:8df79c088b12 28 "target_overrides": {
mbed_official 0:8df79c088b12 29 ...
mbed_official 2:fc74f70b51c3 30 "<TARGET_NAME>": {
mbed_official 0:8df79c088b12 31 "target.restrict_size": "0x20000"
mbed_official 0:8df79c088b12 32 },
mbed_official 0:8df79c088b12 33 ...
mbed_official 0:8df79c088b12 34 ```
mbed_official 0:8df79c088b12 35
mbed_official 0:8df79c088b12 36 Note - `restrict_size` pads the build image to the requested size.
mbed_official 0:8df79c088b12 37
mbed_official 0:8df79c088b12 38 ## Now compile
mbed_official 0:8df79c088b12 39
mbed_official 0:8df79c088b12 40 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:
mbed_official 0:8df79c088b12 41
mbed_official 0:8df79c088b12 42 ```
mbed_official 2:fc74f70b51c3 43 mbed compile -m <TARGET_NAME> -t ARM
mbed_official 0:8df79c088b12 44 ```
mbed_official 0:8df79c088b12 45
mbed_official 0:8df79c088b12 46 Your PC may take a few minutes to compile your code. At the end, you see the following result:
mbed_official 0:8df79c088b12 47
mbed_official 0:8df79c088b12 48 ```
mbed_official 0:8df79c088b12 49 Merging Regions:
mbed_official 2:fc74f70b51c3 50 Filling region application with .\BUILD\<TARGET_NAME>\ARM\mbed-os-example-bootloader_application.bin
mbed_official 0:8df79c088b12 51 Padding region application with 0x11420 bytes
mbed_official 0:8df79c088b12 52 Space used after regions merged: 0x20000
mbed_official 0:8df79c088b12 53 +-----------------------------+-------+-------+-------+
mbed_official 0:8df79c088b12 54 | Module | .text | .data | .bss |
mbed_official 0:8df79c088b12 55 +-----------------------------+-------+-------+-------+
mbed_official 0:8df79c088b12 56 | Misc | 18481 | 24 | 1268 |
mbed_official 0:8df79c088b12 57 | drivers | 2132 | 8 | 184 |
mbed_official 0:8df79c088b12 58 | features/FEATURE_LWIP | 46 | 0 | 12560 |
mbed_official 0:8df79c088b12 59 | features/filesystem | 12756 | 12 | 540 |
mbed_official 0:8df79c088b12 60 | hal | 414 | 8 | 0 |
mbed_official 0:8df79c088b12 61 | hal/TARGET_FLASH_CMSIS_ALGO | 520 | 28 | 0 |
mbed_official 0:8df79c088b12 62 | platform | 2759 | 32 | 380 |
mbed_official 0:8df79c088b12 63 | rtos | 144 | 8 | 0 |
mbed_official 0:8df79c088b12 64 | rtos/rtx | 6954 | 100 | 8396 |
mbed_official 0:8df79c088b12 65 | targets/TARGET_STM | 15560 | 568 | 736 |
mbed_official 0:8df79c088b12 66 | Subtotals | 59766 | 788 | 24064 |
mbed_official 0:8df79c088b12 67 +-----------------------------+-------+-------+-------+
mbed_official 0:8df79c088b12 68 Allocated Heap: unknown
mbed_official 0:8df79c088b12 69 Allocated Stack: unknown
mbed_official 0:8df79c088b12 70 Total Static RAM memory (data + bss): 24852 bytes
mbed_official 0:8df79c088b12 71 Total RAM memory (data + bss + heap + stack): 24852 bytes
mbed_official 0:8df79c088b12 72 Total Flash memory (text + data + misc): 60554 bytes
mbed_official 0:8df79c088b12 73
mbed_official 2:fc74f70b51c3 74 Image: .\BUILD\<TARGET_NAME>\ARM\mbed-os-example-bootloader.bin
mbed_official 0:8df79c088b12 75 ```
mbed_official 0:8df79c088b12 76
mbed_official 4:0daf612a367a 77 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.
mbed_official 2:fc74f70b51c3 78
mbed_official 4:0daf612a367a 79 When the build succeeds, you have created a bootloader for your target. This bootloader defines the update file to be located at `/sd/mbed-os-example-bootloader-blinky_application.bin`. This is the binary bootloader flashes and then jumps to.
mbed_official 2:fc74f70b51c3 80
mbed_official 3:01d11bcf86eb 81 ## Set up application to use bootloader
mbed_official 3:01d11bcf86eb 82
mbed_official 3:01d11bcf86eb 83 The next step is to build an application you can combine with your bootloader to create a loadable image.
mbed_official 3:01d11bcf86eb 84
mbed_official 4:0daf612a367a 85 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.
mbed_official 3:01d11bcf86eb 86
mbed_official 3:01d11bcf86eb 87 ```
mbed_official 3:01d11bcf86eb 88 "target_overrides": {
mbed_official 3:01d11bcf86eb 89 ...
mbed_official 3:01d11bcf86eb 90 "<TARGET_NAME>": {
mbed_official 3:01d11bcf86eb 91 "target.bootloader_img": "bootloader/<TARGET_NAME>.bin"
mbed_official 3:01d11bcf86eb 92 },
mbed_official 3:01d11bcf86eb 93 ...
mbed_official 3:01d11bcf86eb 94 ```
mbed_official 3:01d11bcf86eb 95
mbed_official 3:01d11bcf86eb 96 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:
mbed_official 3:01d11bcf86eb 97
mbed_official 3:01d11bcf86eb 98 ```
mbed_official 3:01d11bcf86eb 99 mbed compile -m <TARGET_NAME> -t ARM
mbed_official 3:01d11bcf86eb 100 ```
mbed_official 3:01d11bcf86eb 101
mbed_official 3:01d11bcf86eb 102 ### Program bootloader and application
mbed_official 3:01d11bcf86eb 103
mbed_official 3:01d11bcf86eb 104 1. Connect your mbed device to the computer over USB.
mbed_official 3:01d11bcf86eb 105 1. Copy the application binary file to the mbed device.
mbed_official 3:01d11bcf86eb 106 1. Press the reset button to start the program.
mbed_official 3:01d11bcf86eb 107
mbed_official 3:01d11bcf86eb 108 ### Program application using SD card
mbed_official 3:01d11bcf86eb 109
mbed_official 3:01d11bcf86eb 110 1. Connect the SD card to your computer.
mbed_official 3:01d11bcf86eb 111 1. Copy the application binary to the root of the SD card.
mbed_official 3:01d11bcf86eb 112 1. Remove the SD card from your PC, and plug it into the mbed board.
mbed_official 3:01d11bcf86eb 113 1. Press the reset button to start the firmware update.
mbed_official 3:01d11bcf86eb 114
mbed_official 3:01d11bcf86eb 115 If a terminal is open, the following prints:
mbed_official 3:01d11bcf86eb 116
mbed_official 3:01d11bcf86eb 117 ```
mbed_official 3:01d11bcf86eb 118 Firmware update found
mbed_official 3:01d11bcf86eb 119 Starting application
mbed_official 3:01d11bcf86eb 120 ```
mbed_official 0:8df79c088b12 121
mbed_official 0:8df79c088b12 122 ## Troubleshooting
mbed_official 0:8df79c088b12 123
mbed_official 0:8df79c088b12 124 1. Make sure `mbed-cli` is working correctly and its version is `>1.0.0`.
mbed_official 0:8df79c088b12 125
mbed_official 0:8df79c088b12 126 ```
mbed_official 0:8df79c088b12 127 mbed --version
mbed_official 0:8df79c088b12 128 ```
mbed_official 0:8df79c088b12 129
mbed_official 0:8df79c088b12 130 If not, you can update it:
mbed_official 0:8df79c088b12 131
mbed_official 0:8df79c088b12 132 ```
mbed_official 0:8df79c088b12 133 pip install mbed-cli --upgrade
mbed_official 0:8df79c088b12 134 ```
mbed_official 0:8df79c088b12 135
mbed_official 2:fc74f70b51c3 136 2. If using Keil MDK, make sure you have a license installed. [MDK-Lite](http://www.keil.com/arm/mdk.asp) has a 32 KB restriction on code size.