You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/program-setup/bare_metal/mbed2_porting.md
+37-25Lines changed: 37 additions & 25 deletions
Original file line number
Diff line number
Diff line change
@@ -1,35 +1,37 @@
1
-
# Porting an Mbed OS 2 target to Mbed OS 6 bare metal
1
+
# Porting a target from Mbed OS 2 to Mbed OS 6 bare metal
2
2
3
-
The Mbed OS bare metal profile removes the RTOS and provides fewer features compared to Mbed OS 6. This profile offers the same functionality as Mbed OS 2 and allows targets to access features that we have added to more recent versions of Mbed OS. This document describes how to configure an Mbed OS 2 target for bare metal and validate the port.
3
+
The Mbed OS bare metal profile offers the same functionality as Mbed OS 2 and allows targets to access features that we have added to more recent versions of Mbed OS. At the same time, it removes the RTOS and provides fewer features than Mbed OS 6, so it's smaller and therefore suitable for ultraconstrained devices.
4
+
5
+
This document describes how to configure an Mbed OS 2 target for bare metal, and validate the port.
4
6
5
7
## Configuring your target
6
8
7
-
You will use the blinky bare metal Mbed OS example and make it run on your target. The configuration will be validated upon successful run of the example.
9
+
You will get the Blinky bare metal Mbed OS example running on your target. A successful run of the example will validate the configuration.
Find your target in `mbed-os/targets/targets.json` and update its configuration as described below.
25
27
26
28
Configure your target to support Mbed OS 6:
27
-
- Remove the `release_versions` property as it is no longer required.
29
+
1. Remove the `release_versions` property; it is no longer required:
28
30
```
29
31
"release_versions": ["2"]
30
32
```
31
33
32
-
- Add the `supported_application_profiles` property to indicate that the application profile supported by this target is bare metal.
34
+
1. To indicate that the application profile supported by this target is bare metal, add the `supported_application_profiles` property:
33
35
```
34
36
"supported_application_profiles" : ["bare-metal"]
35
37
```
@@ -43,69 +45,79 @@ Configure your target to support Mbed OS 6:
43
45
}
44
46
```
45
47
46
-
Both the ARM and GCC_ARM toolchains support optimized versions of the C standard libraries, microlib and newlib-nano respectively. We recommend using them with the bare metal profile to achieve lower memory footprints. Ultra constrained targets should override `supported_c_libs` as follows:
48
+
Both the ARM and GCC_ARM toolchains support optimized versions of the C standard libraries - microlib and newlib-nano, respectively. We recommend using them with the bare metal profile for lower memory footprints. Ultraconstrained targets should override `supported_c_libs`:
47
49
```
48
50
"supported_c_libs": {
49
51
"arm": ["small"],
50
52
"gcc_arm": ["small"]
51
53
}
52
54
```
53
55
54
-
For each toolchain, if there is enough memory to link with the standard library, add the corresponding "std" library to the list. For example:
56
+
For each toolchain, if there is enough memory to link with the standard library, add the corresponding `std` library to the list. For example:
55
57
```
56
58
"supported_c_libs": {
57
59
"arm": ["std", "small"],
58
60
"gcc_arm": ["std", "small"],
59
61
"iar": ["std"]
60
62
}
61
63
```
62
-
<spanclass="notes">**Note:** For ARM, your target scatter file needs to have a two-region memory model. If the build system throws an error (presence of undefined symbols `Image$$ARM_LIB_HEAP$$ZI$$Base`, `Image$$ARM_LIB_HEAP$$ZI$$Length`, `Image$$ARM_LIB_HEAP$$ZI$$Limit`) when compiling with microlib, you can find more information [here](https://os.mbed.com/docs/mbed-os/v6.0-preview/reference/using-small-c-libraries.html).</span>
64
+
<spanclass="notes">**Note:** For ARM, your target scatter file needs to have a two-region memory model. If the build system throws an error ("presence of undefined symbols `Image$$ARM_LIB_HEAP$$ZI$$Base`, `Image$$ARM_LIB_HEAP$$ZI$$Length`, `Image$$ARM_LIB_HEAP$$ZI$$Limit`") when compiling with microlib, you can find more information [in the small C libraries documentation](https://os.mbed.com/docs/mbed-os/v6.0-preview/reference/using-small-c-libraries.html).</span>
63
65
64
66
<spanclass="notes">**Note:** The IAR toolchain does not have a small C library.</span>
65
67
66
-
- Set the `c_lib` property to indicate which C library should be used by the build tools. If your target has `"default_lib": "small"` defined, then replace it with `"c_lib" : "small"`. Otherwise add `"c_lib" : "small"`. We recommend that ultra constrained devices running bare metal applications link with the small C libraries by default.
68
+
- We recommend that ultraconstrained devices running bare metal applications link with the small C libraries by default. To indicate which C library should be used by the build tools, set the `c_lib` property:
69
+
- If your target has `"default_lib": "small"` defined, then replace it with `"c_lib" : "small"`.
70
+
- Otherwise, add `"c_lib" : "small"`.
67
71
68
-
<spanclass="notes">**Note:** If a toolchain does not support a small C library and `c_lib` is set to `small`, the build tools will revert to linking with the standard C library, provided that it is listed in `supported_c_libs` for the given toolchain.</span>
72
+
<spanclass="notes">**Note:** If a toolchain does not support a small C library and `c_lib` is set to `small`, the build tools will revert to linking with the standard C library (provided that it is listed in `supported_c_libs` for the given toolchain).</span>
69
73
70
-
- If `default_toolchain` is set to `uARM`, then replace it with `ARM` and remove `uARM` from `supported_toolchains`. Support for the uARM toolchain, which is the ARM toolchain with microlib, has been removed. Setting `c_lib` to `small` ensures that microlib is used when the ARM toolchain is selected.
74
+
- If `default_toolchain` is set to `uARM`, then
75
+
1. Replace it with `ARM`.
76
+
1. Remove `uARM` from `supported_toolchains`.
77
+
Support for the uARM toolchain, which is the ARM toolchain with microlib, has been removed. Setting `c_lib` to `small`, as explained above, ensures that microlib is used when the ARM toolchain is selected.
71
78
72
-
<spanclass="notes">**Note:** As mentioned above, to successfully build with microlib, the target must define a two-region memory model. You might need to replace the content of the TOOLCHAIN_ARM_STD linker file with that of TOOLCHAIN_ARM_MICRO which includes a two-region memory model linker file.</span>
79
+
<spanclass="notes">**Note:** As mentioned above, to successfully build with microlib, the target must define a two-region memory model. You might need to replace the content of the `TOOLCHAIN_ARM_STD` linker file with that of `TOOLCHAIN_ARM_MICRO`, which includes a two-region memory model linker file.</span>
73
80
74
-
- If your board does not have a low power ticker, ensure that tickless is enabled using the microsecond ticker as follows:
81
+
- If your board does not have a low power ticker, ensure that tickless is enabled using the microsecond ticker:
75
82
```
76
83
"overrides": {
77
84
"tickless-from-us-ticker": true
78
85
}
79
86
```
80
87
81
-
- It might be necessary to reduce the stack size allocated for your target if it does not have enough RAM. The stack size is configured by setting a value for the `boot-stack-size` attribute; this value must be a multiple of 8 for alignment purposes. By default all targets are configured to have a boot stack size of 0x1000 (4096 bytes) in bare metal. However, this must be overridden if inadequate for your target. We recommend to reduce the boot stack size to 0x400 (1024 bytes) if your target has 8KB of RAM and to 0x300 (768 bytes) if your target has 4KB of RAM.
88
+
- By default, all bare metal targets are configured to have a boot stack size of 0x1000 (4,096 bytes). If this is too much for your target, you will need to override the stack allocation to match your target's available RAM.
89
+
90
+
The stack size is configured by setting a value for the `boot-stack-size` attribute; this value must be a multiple of 8 for alignment purposes. We recommend that you reduce the boot stack size to 0x400 (1,024 bytes) if your target has 8KB of RAM and to 0x300 (768 bytes) if your target has 4KB of RAM.
82
91
```
83
92
"overrides": {
84
93
"boot-stack-size": "0x400"
85
94
}
86
95
```
87
96
88
-
### Build and run mbed-os-example-blinky-baremetal
97
+
### Build and run the Blinky bare metal example
89
98
90
-
Build the application and program your target: `mbed compile -m <YOUR_TARGET> -t <TOOLCHAIN> --flash --sterm`.
The application running on the target should print a text on the console. Repeat for all supported toolchains.
93
105
94
106
Troubleshoot any issue.
95
107
96
108
## Validating the port
97
109
98
-
To validate the bare metal target configuration, you will execute the Mbed OS greentea test suite with the bare metal configuration. A subset of the tests are automatically skipped by the framework either because the underlying functionality has not been ported to bare metal or because some tests require RTOS features, for examples more complex tests based on multi-threading.
110
+
To validate the bare metal target configuration, execute the Mbed OS Greentea test suite with the bare metal profile. This profile causes Greentea to skip a subset of the tests, either because the underlying functionality has not been ported to bare metal or because some tests require RTOS features (for examples, more complex tests based on multi-threading).
99
111
100
-
- First, change directory.
112
+
1. Change directory:
101
113
```
102
114
cd mbed-os
103
115
```
104
-
- Then execute the greentea test suite with the bare metal configuration for the supported toolchains.
116
+
1. Execute the Greentea test suite with the bare metal configuration for the supported toolchains:
105
117
```
106
118
mbed test -m <YOUR_TARGET> -t <TOOLCHAIN> --app-config TESTS/configs/baremetal.json
107
119
```
108
-
It can be useful to append `--compile` and fix build issues first before running tests with `--run`.
120
+
<spanclass="tips">**Tip:** You can append `--compile` and fix build issues before running tests with `--run`.</span>
109
121
110
122
All tests should pass (or be automatically skipped).
0 commit comments