ON Semiconductor / mbed-os

5.2.1 - Updated I2C files

Dependents:   mbed-TFT-example-NCS36510 mbed-Accelerometer-example-NCS36510 mbed-Accelerometer-example-NCS36510

docs/mbed_targets.md@0:098463de4c5d, 2017-01-25 (annotated)

Committer:
group-onsemi
Date:
Wed Jan 25 20:34:15 2017 +0000
Revision:
0:098463de4c5d
Initial commit

Who changed what in which revision?

UserRevisionLine numberNew contents of line
group-onsemi 0:098463de4c5d 1 # Adding and configuring mbed targets
group-onsemi 0:098463de4c5d 2
group-onsemi 0:098463de4c5d 3 mbed uses JSON as a description language for its build targets. The JSON description of mbed targets can be found in `tools/targets.json`. To better understand how a target is defined, we'll use this example (taken from `targets.json`):
group-onsemi 0:098463de4c5d 4
group-onsemi 0:098463de4c5d 5 ```
group-onsemi 0:098463de4c5d 6 "TEENSY3_1": {
group-onsemi 0:098463de4c5d 7 "inherits": ["Target"],
group-onsemi 0:098463de4c5d 8 "core": "Cortex-M4",
group-onsemi 0:098463de4c5d 9 "extra_labels": ["Freescale", "K20XX", "K20DX256"],
group-onsemi 0:098463de4c5d 10 "OUTPUT_EXT": "hex",
group-onsemi 0:098463de4c5d 11 "is_disk_virtual": true,
group-onsemi 0:098463de4c5d 12 "supported_toolchains": ["GCC_ARM", "ARM"],
group-onsemi 0:098463de4c5d 13 "post_binary_hook": {
group-onsemi 0:098463de4c5d 14 "function": "TEENSY3_1Code.binary_hook",
group-onsemi 0:098463de4c5d 15 "toolchains": ["ARM_STD", "ARM_MICRO", "GCC_ARM"]
group-onsemi 0:098463de4c5d 16 },
group-onsemi 0:098463de4c5d 17 "device_name": "MK20DX256xxx7",
group-onsemi 0:098463de4c5d 18 "detect_code": ["0230"]
group-onsemi 0:098463de4c5d 19 ```
group-onsemi 0:098463de4c5d 20
group-onsemi 0:098463de4c5d 21 The definition of the target called **TEENSY3_1** is a JSON object. The properties in the object are either "standard" (understood by the mbed build system) or specific to the target.
group-onsemi 0:098463de4c5d 22
group-onsemi 0:098463de4c5d 23 # Standard properties
group-onsemi 0:098463de4c5d 24
group-onsemi 0:098463de4c5d 25 This section lists all the properties that are known to the mbed build system. Unless specified otherwise, all properties are optional.
group-onsemi 0:098463de4c5d 26
group-onsemi 0:098463de4c5d 27 ## inherits
group-onsemi 0:098463de4c5d 28
group-onsemi 0:098463de4c5d 29 The description of a mbed target can "inherit" from one of more descriptions of other targets. When a target **A** inherits from another target **B** (**A** is the _child_ of **B** and **B** is the _parent_ of **A**), it automatically "borrows" all the definitions of properties from **B** and can modify them as needed (if you're familiar with Python, this is very similar with how class inheritance works in Python). In our example above, `TEENSY3_1` inherits from `Target` (most mbed targets inherit from `Target`). This is how `Target` is defined:
group-onsemi 0:098463de4c5d 30
group-onsemi 0:098463de4c5d 31 ```
group-onsemi 0:098463de4c5d 32 "Target": {
group-onsemi 0:098463de4c5d 33 "core": null,
group-onsemi 0:098463de4c5d 34 "default_toolchain": "ARM",
group-onsemi 0:098463de4c5d 35 "supported_toolchains": null,
group-onsemi 0:098463de4c5d 36 "extra_labels": [],
group-onsemi 0:098463de4c5d 37 "is_disk_virtual": false,
group-onsemi 0:098463de4c5d 38 "macros": [],
group-onsemi 0:098463de4c5d 39 "detect_code": [],
group-onsemi 0:098463de4c5d 40 "public": false
group-onsemi 0:098463de4c5d 41 }
group-onsemi 0:098463de4c5d 42 ```
group-onsemi 0:098463de4c5d 43
group-onsemi 0:098463de4c5d 44 Since `TEENSY3_1` inherits from `Target`:
group-onsemi 0:098463de4c5d 45
group-onsemi 0:098463de4c5d 46 - `core` is a property defined both in `TEENSY3_1` and `Target`. Since `TEENSY3_1` redefines it, the value of `core` for `TEENSY3_1` will be `Cortex-M4`.
group-onsemi 0:098463de4c5d 47 - `default_toolchain` is not defined in `TEENSY3_1`, but since it is defined in `Target`, `TEENSY3_1` borrows it, so the value of `default_toolchain` for `TEENSY3_1` will be `ARM`.
group-onsemi 0:098463de4c5d 48
group-onsemi 0:098463de4c5d 49 A target can add properties that don't exist in its parent(s). For example, `OUTPUT_EXT` is defined in `TEENSY3_1`, but doesn't exist in `Target`.
group-onsemi 0:098463de4c5d 50
group-onsemi 0:098463de4c5d 51 It's possible to inherit from more than one target. For example:
group-onsemi 0:098463de4c5d 52
group-onsemi 0:098463de4c5d 53 ```
group-onsemi 0:098463de4c5d 54 "ImaginaryTarget": {
group-onsemi 0:098463de4c5d 55 "inherits": ["Target", "TEENSY3_1"]
group-onsemi 0:098463de4c5d 56 }
group-onsemi 0:098463de4c5d 57 ```
group-onsemi 0:098463de4c5d 58
group-onsemi 0:098463de4c5d 59 In this case, `ImaginaryTarget` inherits the properties of both `Target` and `TEENSY3_1`, so:
group-onsemi 0:098463de4c5d 60
group-onsemi 0:098463de4c5d 61 - the value of `ImaginaryTarget.default_toolchain` will be `ARM` (from `Target`)
group-onsemi 0:098463de4c5d 62 - the value of `ImaginaryTarget.OUTPUT_EXT` will be `hex` (from `TEENSY3_1`).
group-onsemi 0:098463de4c5d 63 - the value of `ImaginaryTarget.core` will be `null` (from `Target`, since that's the first parent of `ImaginaryTarget` that defines `core`).
group-onsemi 0:098463de4c5d 64
group-onsemi 0:098463de4c5d 65 Avoid using multiple inheritance for your targets if possible, since it can get pretty tricky to figure out how a property is inherited if multiple inheritance is used. If you have to use multiple inheritance, keep in mind that the mbed target description mechanism uses the old (pre 2.3) Python mechanism for finding the method resolution order:
group-onsemi 0:098463de4c5d 66
group-onsemi 0:098463de4c5d 67 - look for the property in the current target.
group-onsemi 0:098463de4c5d 68 - if not found, look for the property in the first target's parent, then in the parent of the parent and so on.
group-onsemi 0:098463de4c5d 69 - if not found, look for the property in the rest of the target's parents, relative to the current inheritance level.
group-onsemi 0:098463de4c5d 70
group-onsemi 0:098463de4c5d 71 For more details about the Python method resolution order, check for example [this link](http://makina-corpus.com/blog/metier/2014/python-tutorial-understanding-python-mro-class-search-path).
group-onsemi 0:098463de4c5d 72
group-onsemi 0:098463de4c5d 73 ## core
group-onsemi 0:098463de4c5d 74
group-onsemi 0:098463de4c5d 75 The name of the ARM core used by the target.
group-onsemi 0:098463de4c5d 76
group-onsemi 0:098463de4c5d 77 Possible values: `"Cortex-M0"`, `"Cortex-M0+"`, `"Cortex-M1"`, `"Cortex-M3"`, `"Cortex-M4"`, `"Cortex-M4F"`, `"Cortex-M7"`, `"Cortex-M7F"`, `"Cortex-A9"`
group-onsemi 0:098463de4c5d 78
group-onsemi 0:098463de4c5d 79 ## public
group-onsemi 0:098463de4c5d 80
group-onsemi 0:098463de4c5d 81 Some mbed targets might be defined solely for the purpose of serving as an inheritance base for other targets (as opposed to being used to build mbed code). When such a target is defined, its description must have the `public` property set to `false` to prevent the mbed build system from considering it as a build target. An example is the `Target` target shown in a previous paragraph.
group-onsemi 0:098463de4c5d 82
group-onsemi 0:098463de4c5d 83 If `public` is not defined for a target, it defaults to `true`.
group-onsemi 0:098463de4c5d 84
group-onsemi 0:098463de4c5d 85 Note that unlike other target properties, **the value of `public` is not inherited from a parent to its children**.
group-onsemi 0:098463de4c5d 86
group-onsemi 0:098463de4c5d 87 ## macros, macros_add, macros_remove
group-onsemi 0:098463de4c5d 88
group-onsemi 0:098463de4c5d 89 The macros in this list will be defined when compiling mbed code. The macros can be defined with or without a value. For example, the declaration `"macros": ["NO_VALUE", "VALUE=10"]` will add these definitions to the compiler's command line: `-DNO_VALUE -DVALUE=10`.
group-onsemi 0:098463de4c5d 90
group-onsemi 0:098463de4c5d 91 When target inheritance is used, it's possible to alter the values of `macros` in inherited targets without re-defining `macros` completely:
group-onsemi 0:098463de4c5d 92
group-onsemi 0:098463de4c5d 93 - an inherited target can use `macros_add` to add its own macros.
group-onsemi 0:098463de4c5d 94 - an inherited target can use `macros_remove` to remove macros defined by its parents.
group-onsemi 0:098463de4c5d 95
group-onsemi 0:098463de4c5d 96 For example, in this configuration:
group-onsemi 0:098463de4c5d 97
group-onsemi 0:098463de4c5d 98 ```
group-onsemi 0:098463de4c5d 99 "TargetA": {
group-onsemi 0:098463de4c5d 100 "macros": ["PARENT_MACRO1", "PARENT_MACRO2"]
group-onsemi 0:098463de4c5d 101 },
group-onsemi 0:098463de4c5d 102 "TargetB": {
group-onsemi 0:098463de4c5d 103 "inherits": ["TargetA"],
group-onsemi 0:098463de4c5d 104 "macros_add": ["CHILD_MACRO1"],
group-onsemi 0:098463de4c5d 105 "macros_remove": ["PARENT_MACRO2"]
group-onsemi 0:098463de4c5d 106 }
group-onsemi 0:098463de4c5d 107 ```
group-onsemi 0:098463de4c5d 108
group-onsemi 0:098463de4c5d 109 the value of `TargetB.macros` will be `["PARENT_MACRO1", "CHILD_MACRO1"]`.
group-onsemi 0:098463de4c5d 110
group-onsemi 0:098463de4c5d 111 ## extra_labels, extra_labels_add, extra_labels_remove
group-onsemi 0:098463de4c5d 112
group-onsemi 0:098463de4c5d 113 The list of **labels** defines how the build system looks for sources, libraries, include directories and any other additional files that are needed at compile time. `extra_labels` can be used to make the build system aware of additional directories that must be scanned for such files.
group-onsemi 0:098463de4c5d 114
group-onsemi 0:098463de4c5d 115 If target inheritance is used, it's possible to alter the values of `extra_labels` using `extra_labels_add` and `extra_labels_remove`. This is similar to the `macros_add` and `macros_remove` mechanism described in the previous paragraph.
group-onsemi 0:098463de4c5d 116
group-onsemi 0:098463de4c5d 117 ## features, features_add, features_remove
group-onsemi 0:098463de4c5d 118
group-onsemi 0:098463de4c5d 119 The list of **features** defines what hardware a device has.
group-onsemi 0:098463de4c5d 120 This allows allowing mbed, libraries, or application source code to select between different implementations of drivers based on hardware availability, to selectively compile drivers for only the hardware that exists, or to test only the tests that apply to a particular platform.
group-onsemi 0:098463de4c5d 121
group-onsemi 0:098463de4c5d 122 If target inheritance is used, it's possible to alter the values of `features` using `features_add` and `features_remove`. This is similar to the `macros_add` and `macros_remove` mechanism described in the previous two paragraphs.
group-onsemi 0:098463de4c5d 123
group-onsemi 0:098463de4c5d 124 ## supported_toolchains
group-onsemi 0:098463de4c5d 125
group-onsemi 0:098463de4c5d 126 This is the list of toolchains that can be used to compile code for the target. The known toolchains are `ARM`, `uARM`, `GCC_ARM`, `GCC_CR`, `IAR`.
group-onsemi 0:098463de4c5d 127
group-onsemi 0:098463de4c5d 128 ## default_toolchain
group-onsemi 0:098463de4c5d 129
group-onsemi 0:098463de4c5d 130 The name of the toolchain that will be used by default to compile this target (if another toolchain is not specified). Possible values are `ARM` or `uARM`.
group-onsemi 0:098463de4c5d 131
group-onsemi 0:098463de4c5d 132 ## post_binary_hook
group-onsemi 0:098463de4c5d 133
group-onsemi 0:098463de4c5d 134 Some mbed targets require specific actions for generating a binary image that can be flashed to the target. If that's the case, these specific actions can be specified using the `post_binary_hook` property and custom Python code. For the `TEENSY3_1` target above, the definition of `post_binary_hook` looks like this:
group-onsemi 0:098463de4c5d 135
group-onsemi 0:098463de4c5d 136 ```
group-onsemi 0:098463de4c5d 137 "post_binary_hook": {
group-onsemi 0:098463de4c5d 138 "function": "TEENSY3_1Code.binary_hook",
group-onsemi 0:098463de4c5d 139 "toolchains": ["ARM_STD", "ARM_MICRO", "GCC_ARM"]
group-onsemi 0:098463de4c5d 140 }
group-onsemi 0:098463de4c5d 141 ```
group-onsemi 0:098463de4c5d 142
group-onsemi 0:098463de4c5d 143 Following this definition, the build system will call the function `binary_hook` in the `TEENSY3_1Code` class after the initial binary image for the target is generated. The definition of the `TEENSY3_1Code` class **must** exist in the *targets.py* file. Since `toolchains` is also specified, `binary_hook` will only be called if the toolchain used for compiling the code is either `ARM_STD`, `ARM_MICRO` or `GCC_ARM`. Note that specifying `toolchains` is optional: if it's not specified, the hook will be called no matter what toolchain is used.
group-onsemi 0:098463de4c5d 144
group-onsemi 0:098463de4c5d 145 As for the `binary_hook` code, this is how it looks in *targets.py*:
group-onsemi 0:098463de4c5d 146
group-onsemi 0:098463de4c5d 147 ```
group-onsemi 0:098463de4c5d 148 class TEENSY3_1Code:
group-onsemi 0:098463de4c5d 149 @staticmethod
group-onsemi 0:098463de4c5d 150 def binary_hook(t_self, resources, elf, binf):
group-onsemi 0:098463de4c5d 151 from intelhex import IntelHex
group-onsemi 0:098463de4c5d 152 binh = IntelHex()
group-onsemi 0:098463de4c5d 153 binh.loadbin(binf, offset = 0)
group-onsemi 0:098463de4c5d 154
group-onsemi 0:098463de4c5d 155 with open(binf.replace(".bin", ".hex"), "w") as f:
group-onsemi 0:098463de4c5d 156 binh.tofile(f, format='hex')
group-onsemi 0:098463de4c5d 157 ```
group-onsemi 0:098463de4c5d 158
group-onsemi 0:098463de4c5d 159 In this case, it converts the output file (`binf`) from binary format to Intel HEX format.
group-onsemi 0:098463de4c5d 160
group-onsemi 0:098463de4c5d 161 The hook code can look quite different between different targets. Take a look at the other classes in *targets.py* for more examples of hook code.
group-onsemi 0:098463de4c5d 162
group-onsemi 0:098463de4c5d 163 ## device_name
group-onsemi 0:098463de4c5d 164
group-onsemi 0:098463de4c5d 165 This property is used to pass necessary data for exporting the mbed code to various 3rd party tools and IDEs.
group-onsemi 0:098463de4c5d 166
group-onsemi 0:098463de4c5d 167 Please see [exporters.md](exporters.md) for information about this field.
group-onsemi 0:098463de4c5d 168