Update documentation for target definitions

docs/tools/mbed_targets.md

@@ -6,7 +6,7 @@ Arm Mbed uses JSON as a description language for its build targets. You can find
 
 You are not allowed to redefine existing targets in `custom_targets.json`. To better understand how a target is defined, we'll use this example (taken from `targets.json`):
 
-```
+```json
     "TEENSY3_1": {
         "inherits": ["Target"],
         "core": "Cortex-M4",
@@ -20,6 +20,7 @@ You are not allowed to redefine existing targets in `custom_targets.json`. To be
         },
         "device_name": "MK20DX256xxx7",
         "detect_code": ["0230"]
+    }
 ```
 
 The style that we use for targets is:
@@ -37,7 +38,7 @@ This section lists all the properties the Mbed build system understands. Unless
 
 The description of an Mbed target can "inherit" from one or more descriptions of other targets. When a target, called a _child_ inherits from another target, called its _parent_, the child automatically copies all the properties from the parent. After the child has copied the properties of the parent, it may then overwrite, add or remove from those properties. In our example above, `TEENSY3_1` inherits from `Target`. This is the definition of `Target`:
 
-```
+```json
 "Target": {
     "core": null,
     "default_toolchain": "ARM",
@@ -59,7 +60,7 @@ A child target may add properties that don't exist in any of its parents. For ex
 
 It's possible, but discouraged, to inherit from more than one target. For example:
 
-```
+```json
 "ImaginaryTarget": {
     "inherits": ["Target", "TEENSY3_1"]
 }
@@ -103,7 +104,7 @@ When a target inherits, it's possible to alter the values of `macros` in the chi
 
 For example:
 
-```
+```json
     "TargetA": {
         "macros": ["PARENT_MACRO1", "PARENT_MACRO2"]
     },
@@ -148,6 +149,40 @@ The build system errors when you use features outside of this list.
 
 When you use target inheritance, you may alter the values of `features` using `features_add` and `features_remove`. This is similar to the `macros_add` and `macros_remove` mechanism the previous section describes.
 
+#### `config` and `overrides`
+
+_configs_ provide a more flexible way to manage macros for a target. Each configuration has a macro name, as well as a default value and an optional help value. For example, this config flag defines a configuration `lf_clock_src` that defines the source for the low frequency clock on the nRF51 target, with a default value of `NRF_LF_SRC_XTAL`. Compiling sets this value for the macro `MBED_CONF_NORDIC_NRF_LF_CLOCK_SRC`:
+
+```json
+"config": {
+    "lf_clock_src": {
+        "value": "NRF_LF_SRC_XTAL",
+        "macro_name": "MBED_CONF_NORDIC_NRF_LF_CLOCK_SRC"
+    }
+}
+```
+
+_overrides_ allow a child target to change the value of a config. For example, if a child target of the nRF51 uses the internal RC clock instead of the crystal, it can add an override:
+
+```json
+"overrides": {
+    "lf_clock_src": "NRF_LF_SRC_RC"
+}
+```
+
+You can also modify a project's configurations in the `mbed_app.json file` by using `target_overrides`.
+
+```json
+"target_overrides": {
+    "*": {
+        "config1": "value_for_all_targets"
+    },
+    "NRF51_DK": {
+        "config2": "value_for_single_target"
+    }
+}
+```
+
 #### `device_has`
 
 The list in `device_has` defines what hardware a device has.
@@ -166,7 +201,7 @@ The `default_toolchain` property names the toolchain that compiles code for this
 
 Some targets require specific actions to generate a programmable binary image. Specify these actions using the `post_binary_hook` property and custom Python code. The value of `post_binary_hook` must be a JSON object with keys `function` and optionally `toolchain`. Within the `post_binary_hook` JSON object, the `function` key must contain a Python function that is accessible from the namespace of `tools/targets/__init__.py`, and the optional `toolchain` key must contain a list of toolchains that require processing from the `post_binary_hook`. When you do not specify the `toolchains` key for a `post_binary_hook`, you can assume the `post_binary_hook` applies to all toolcahins. For the `TEENSY3_1` target above, the definition of `post_binary_hook` looks like this:
 
-```
+```json
 "post_binary_hook": {
     "function": "TEENSY3_1Code.binary_hook",
     "toolchains": ["ARM_STD", "ARM_MICRO", "GCC_ARM"]
@@ -179,7 +214,7 @@ The build tools call `TEENSY3_1` `post_binary_hook` when they build using the `A
 
 As for the `TEENSY3_1` code, this is how it looks in `tools/targets/__init__.py`:
 
-```
+```python
 class TEENSY3_1Code:
     @staticmethod
     def binary_hook(t_self, resources, elf, binf):
@@ -290,9 +325,9 @@ For each of these target roles, some restrictions are in place:
   - `extra_labels`.
   - `public`.
   - `config`.
+  - `override`
   - `forced_reset_timeout`.
-  - `target_overrides`
-- `macros` are not used. That is intentional: they do not provide any benefit over `config` and `target_overrides` but can be very difficult to use. In practice it is very difficult to override the value of a macro with a value. `config` and `target_overries`, on the other hand, are designed for this use case.
+- `macros` are not used. That is intentional: they do not provide any benefit over `config` and `overrides` but can be very difficult to use. In practice it is very difficult to override the value of a macro with a value. `config` and `overrides`, on the other hand, are designed for this use case.
 - `extra_labels` may not contain any target names
 - `device_has` may only contain values from the following list:
   - `ANALOGIN`.
@@ -361,7 +396,7 @@ target errors:
 ---
 hierarchy: Family (LPCTarget) -> MCU (LPC11U24_301) -> ???
 hierarchy errors:
-- no boards found in heirarchy
+- no boards found in hierarchy
 target errors:
   LPC11U24_301:
   - release_versions not found, and is required