Skip to content

Add BL parameter definitions as new document #408

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
Feb 28, 2018
Merged

Add BL parameter definitions as new document #408

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
59997d5
Add exact definitions of BL params as new doc
theotherjimmy Feb 12, 2018
f9873d0
Add exporter limitations; Remove dupe Unmanaged guide descirptions
theotherjimmy Feb 13, 2018
e0df642
Copy edit bootloader.md
Feb 15, 2018
94b2568
Update for Marcus' review
theotherjimmy Feb 22, 2018
03f1017
Edit bootloader.md
Feb 28, 2018
1bb469b
Edit bootloader.md
Feb 28, 2018
6ba228c
Swap managed + unmanaged BL Exporter paragrahs
theotherjimmy Feb 28, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 56 additions & 0 deletions docs/tools/bootloader.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
## Boot loader Configuration

This page describes each boot loader configuration parameter in detail.
For an guide on using the managed and unmanaged boot loader modes, see [the boot loader turorial](../tutorials/bootloder.md).

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` and may be defined 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`.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this intended? I assume one should be mbed_lib.json.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ha! Good catch. Yes, the second mbed_app.json should be mbed_lib.json in the last sentence.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed with a rebase.

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 currently being build will user 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. `target.mbed_app_start` may be used 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.

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 boot loader image to be used during the builtin post-build merge process. `target.bootloader_img` implicitly defines the start of the current application's code segment by taking the size of the boot loader and rounding up to the next flash erase block boundary. The builtin post-build merge process automatically combines the current application with the image referenced in this parameter.

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 boot loader.

This parameter may be used in conjunction with `target.restrict_size` and conflicts with `target.mbed_app_start` and `target.mbed_app_size`. When used with `target.restrict_size`, the size off the application is defined by that parameter; 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. 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 size of the application computed by rounding the end address down to the nearest flash erase block boundary and subtracting the start address. The post-build merge process will pad the resulting boot loader binary to it's end address.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not completely sure what is the difference between restrict_size and mbed_app_size? It seems like you can use them for the same thing: define the size of your application?

I also don't understand the rounding down part: "The size of the application computed by rounding the end address down to the nearest flash erase block boundary and subtracting the start address"

Copy link
Contributor Author

@theotherjimmy theotherjimmy Feb 15, 2018 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'll have to think about how to phrase that better. The difference is that restrict_size will generate the POST_APPLICATION_* stuff and pad your executable to the size mentioned and do the rounding down thingy.


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.

This parameter may be used in conjunction with `target.bootloader_img` and conflicts with `target.mbed_app_start` and `target.mbed_app_size`. When used with `target.bootloader_img`, the start off the application is defined by that parameter; Otherwise, the start is the start of ROM.

### Exporter limitations

While the exporters can export a project using the configuration parameters above, there are some limitations.

The exporters do not interpret Mbed OS Configuration, and any changes to configuration parameters, especially boot loader parameter, require you to re-run the `mbed export` command.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This problem is common to all configuration changes, right? It sounds like the bootloader is a special case.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's true. You could, in theory, modify mbed_config.h for other configuration parameters. BL configs don't even allow that.


Further, The exporters do not implement the post build merge used in managed boot loader builds. After exporting a project with the `target.bootloader_img` setting, you are responsible for flashing the binary mentioned in the configuration parameter.
19 changes: 14 additions & 5 deletions docs/tutorials/bootloader.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -95,16 +95,25 @@ It produces the following ROM layout:

For an example showing how to create an application that uses a bootloader, see the [Mbed OS bootloader example](https://github.com/armmbed/mbed-os-example-bootloader-blinky) repository.

#### Exporter limitations

While the exporters can export a project using the configuration parameters above, there are some limitations.

The exporters do not interpret Mbed OS Configuration, and any changes to configuration parameters, especially boot loader parameter, require you to re-run the `mbed export` command.

Further, The exporters do not implement the post build merge used in managed boot loader builds. 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 boot loader image, the device will not boot correctly.

### Unmanaged bootloader

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 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`. Please see [Boot Loader Configuration](../tools/bootloader.md) 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.
While the exporters can export an Unmanaged bootloader project using, there are some limitations.

#### `target.mbed_app_size`
The exporters do not interpret Mbed OS Configuration, and any changes to configuration parameters, especially boot loader parameter, require you to re-run 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 post build merge used in managed boot loader builds. 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.