Merge pull request #408 from theotherjimmy/split-bl

Add BL parameter definitions as new document

Author: Amanda Butler

docs/tools/bootloader.md

@@ -0,0 +1,46 @@
+## Bootloader configuration
+
+This page describes each bootloader configuration parameter in detail. For a guide on using the managed and unmanaged bootloader modes, please see [the bootloader tutorial](/docs/v5.7/tutorials/bootloader.html).
+
+There are 4 configuration parameters that affect the location of an application in ROM:
+
+- `target.mbed_app_start`
+- `target.mbed_app_size`
+- `target.bootloader_img`
+- `target.restrict_size`
+ 
+All of these parameters are valid in `targets.json`, `mbed_lib.json` and `mbed_app.json`. You may define them for individual targets and the wildcard target, `*`. A parameter in `mbed_lib.json` overrides a parameter in `targets.json`, and a parameter in `mbed_app.json` overrides one in `mbed_lib.json`.
+
+The presence of any of these parameters defines `APPLICATION_ADDR` and `APPLICATION_SIZE` for C and C++ and `MBED_APP_START` and `MBED_APP_SIZE` for the linker.
+ 
+### `target.mbed_app_start`
+
+This parameter defines the start address of your application. You are responsible for the alignment of this address with respect to the flash layout and vector table size of the MCU you are using. When not used in conjunction with `target.mbed_app_size`, the application being built uses the remainder of ROM.
+
+The value of this parameter is available to C and C++ as `APPLICATION_ADDR` and to the linker as `MBED_APP_START`.
+
+This configuration parameter conflicts with `target.bootloader_img` and `target.restrict_size`. 
+
+### `target.mbed_app_size`
+
+This parameter defines the size of your application. You may use `target.mbed_app_start` in conjunction with this parameter to set the start address, as well as the size. When `target.mbed_app_start` is not present, the application starts at the beginning of ROM. You are responsible for the alignment of the end address of the application with respect to the flash layout and vector table size of the MCU you are using.
+
+The value of this parameter is available to C and C++ as `APPLICATION_SIZE` and to the linker as `MBED_APP_SIZE`.
+
+This parameter conflicts with `target.bootloader_img` and `target.restrict_size`.
+
+### `target.bootloader_img`
+
+This parameter defines the bootloader image to be used during the built-in postbuild merge process. `target.bootloader_img` implicitly defines the start of the current application's code segment by taking the size of the bootloader and rounding up to the next flash erase block boundary. The built-in postbuild merge process automatically combines the current application with the image this parameter references.
+
+The start address of the current application, as computed above, is available to C and C++ as `APPLICATION_ADDR` and to the linker as `MBED_APP_START`. The size of the current application is available as `APPLICATION_SIZE` and `MBED_APP_SIZE`. This parameter also defines `BOOTLOADER_ADDR` and `BOOTLOADER_SIZE` as the start address and size of the provided bootloader.
+
+You may use this parameter in conjunction with `target.restrict_size`. It conflicts with `target.mbed_app_start` and `target.mbed_app_size`. When you use it with `target.restrict_size`, that parameter defines the size of the application. Otherwise, the size is the remainder of ROM.
+
+### `target.restrict_size`
+
+This parameter restricts the size of the application to be at most the specified size rounded down to the nearest integer multiple of flash erase blocks. When `target.bootloader_img` is present, the start of the current application's code segment is computed as above; otherwise, the start address is the beginning of ROM. The postbuild merge process pads the resulting bootloader binary to its end address.
+
+The start address of the current application, as computed above, is available to C and C++ as `APPLICATION_ADDR` and to the linker as `MBED_APP_START`. The size of the current application is available as `APPLICATION_SIZE` and `MBED_APP_SIZE`. This parameter also defines `POST_APPLICATION_ADDR` and `POST_APPLICATION_SIZE` as the start address and size of the region after the application.
+
+You may use this parameter in conjunction with `target.bootloader_img`. It conflicts with `target.mbed_app_start` and `target.mbed_app_size`. When used with `target.bootloader_img`, that parameter defines the start of the application. Otherwise, the start is the start of ROM.

docs/tutorials/bootloader.md

@@ -21,9 +21,9 @@ Creating a bootloader is similar to creating a regular application. The only add
 
 Adding this field:
 
-* Restricts the bootloader code from growing larger than the specified size.
-* Pads the output image to exactly the size specified.
-* Defines the symbols `APPLICATION_ADDR`, `APPLICATION_SIZE`, `POST_APPLICATION_ADDR`, `POST_APPLICATION_SIZE`.
+- Restricts the bootloader code from growing larger than the specified size.
+- Pads the output image to exactly the size specified.
+- Defines the symbols `APPLICATION_ADDR`, `APPLICATION_SIZE`, `POST_APPLICATION_ADDR`, `POST_APPLICATION_SIZE`.
 
 It produces the following ROM layout:
 
@@ -99,12 +99,18 @@ For an example showing how to create an application that uses a bootloader, see
 
 You want to have an unmanaged bootloader when your bootloader's requirements conflict with the requirements of the managed bootloader. You need an unmanaged bootloader when your bootloader does not come before your application in ROM or your application does not start immediately after your bootloader. Unlike a managed bootloader, an unmanaged bootloader does not automatically merge the bootloader image with the application image after building the application. We expect users of an unmanaged bootloader build to construct their own set of scripts built atop the `mbed compile` primitive to perform bootloader and application merging.
 
-An unmanaged bootloader build is a method for controlling the link location of a program within Mbed OS. There are two configuration options available for changing the link location: `target.mbed_app_start` and `target.mbed_app_size`.
+An unmanaged bootloader build is a method of controlling the link location of a program within Mbed OS. There are two configuration options available for changing the link location: `target.mbed_app_start` and `target.mbed_app_size`. Please see [bootloader configuration](docs/v5.7/tools/bootloader.html) for complete descriptions of these options.
 
-#### `target.mbed_app_start`
+### Exporter limitations
 
-The configuration option `target.mbed_app_start` sets the starting address of the linker script by defining the `MBED_APP_START` macro for the linker script. You may only define this configuration option within the `target_overrides` section of an Mbed application configuration, and you may not define it for the metatarget `*`. When you do not define this configuration option, it defaults to the start of a target's ROM. This configuration option must be an address within ROM.
+Although the exporters can export bootloader projects using the bootloader parameters, there are some limitations. 
 
-#### `target.mbed_app_size`
+The exporters do not interpret Mbed OS configuration, and any changes to configuration parameters, especially bootloader parameters, require you to rerun the `mbed export` command. 
 
-The configuration option `target.mbed_app_size` defines the size of an application image in ROM by defining the `MBED_APP_SIZE` macro for the linker script. You may only define this configuration option on a per-target basis defined within the `target_overrides` section of an Mbed application configuration, and you may not define it for the metatarget `*`. When you do not define this configuration option, it defaults to the remaining ROM. The Mbed OS tools calculate the remaining ROM by subtracting the image's offset into ROM from the total size of ROM. Together with `target.mbed_app_start`, these configuration options define a continuous region of memory that an image may use. The tools verify that this region of memory is in ROM, but the tools do not perform any other checks for consistency or validity.
+Further, the exporters do not implement the postbuild merge that bootloader builds use. 
+
+For a managed bootloader:
+After exporting a project with the `target.bootloader_img` setting, you are responsible for flashing the binary mentioned in the configuration parameter. Without flashing this bootloader image, the device will not boot correctly.
+
+For an unmanaged bootloader: 
+After exporting a project with the `target.mbed_app_start` setting, you are responsible for ensuring that a boot loader is present, if needed. Without flashing this boot loader image, the device will not boot correctly.