Magnificent7 / Hackathon

Includes library modifications to allow access to AIN_4 (AIN_0 / 5)

mbd_os/docs/mbed_targets.md@0:eafc3fd41f75, 2016-09-20 (annotated)

Committer:
bryantaylor
Date:
Tue Sep 20 21:26:12 2016 +0000
Revision:
0:eafc3fd41f75
hackathon

Who changed what in which revision?

UserRevisionLine numberNew contents of line
bryantaylor 0:eafc3fd41f75 1 # Adding and configuring mbed targets
bryantaylor 0:eafc3fd41f75 2
bryantaylor 0:eafc3fd41f75 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`):
bryantaylor 0:eafc3fd41f75 4
bryantaylor 0:eafc3fd41f75 5 ```
bryantaylor 0:eafc3fd41f75 6 "TEENSY3_1": {
bryantaylor 0:eafc3fd41f75 7 "inherits": ["Target"],
bryantaylor 0:eafc3fd41f75 8 "core": "Cortex-M4",
bryantaylor 0:eafc3fd41f75 9 "extra_labels": ["Freescale", "K20XX", "K20DX256"],
bryantaylor 0:eafc3fd41f75 10 "OUTPUT_EXT": "hex",
bryantaylor 0:eafc3fd41f75 11 "is_disk_virtual": true,
bryantaylor 0:eafc3fd41f75 12 "supported_toolchains": ["GCC_ARM", "ARM"],
bryantaylor 0:eafc3fd41f75 13 "post_binary_hook": {
bryantaylor 0:eafc3fd41f75 14 "function": "TEENSY3_1Code.binary_hook",
bryantaylor 0:eafc3fd41f75 15 "toolchains": ["ARM_STD", "ARM_MICRO", "GCC_ARM"]
bryantaylor 0:eafc3fd41f75 16 },
bryantaylor 0:eafc3fd41f75 17 "progen": {"target": "teensy-31"},
bryantaylor 0:eafc3fd41f75 18 "detect_code": ["0230"]
bryantaylor 0:eafc3fd41f75 19 ```
bryantaylor 0:eafc3fd41f75 20
bryantaylor 0:eafc3fd41f75 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.
bryantaylor 0:eafc3fd41f75 22
bryantaylor 0:eafc3fd41f75 23 # Standard properties
bryantaylor 0:eafc3fd41f75 24
bryantaylor 0:eafc3fd41f75 25 This section lists all the properties that are known to the mbed build system. Unless specified otherwise, all properties are optional.
bryantaylor 0:eafc3fd41f75 26
bryantaylor 0:eafc3fd41f75 27 ## inherits
bryantaylor 0:eafc3fd41f75 28
bryantaylor 0:eafc3fd41f75 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:
bryantaylor 0:eafc3fd41f75 30
bryantaylor 0:eafc3fd41f75 31 ```
bryantaylor 0:eafc3fd41f75 32 "Target": {
bryantaylor 0:eafc3fd41f75 33 "core": null,
bryantaylor 0:eafc3fd41f75 34 "default_toolchain": "ARM",
bryantaylor 0:eafc3fd41f75 35 "supported_toolchains": null,
bryantaylor 0:eafc3fd41f75 36 "extra_labels": [],
bryantaylor 0:eafc3fd41f75 37 "is_disk_virtual": false,
bryantaylor 0:eafc3fd41f75 38 "macros": [],
bryantaylor 0:eafc3fd41f75 39 "detect_code": [],
bryantaylor 0:eafc3fd41f75 40 "public": false
bryantaylor 0:eafc3fd41f75 41 }
bryantaylor 0:eafc3fd41f75 42 ```
bryantaylor 0:eafc3fd41f75 43
bryantaylor 0:eafc3fd41f75 44 Since `TEENSY3_1` inherits from `Target`:
bryantaylor 0:eafc3fd41f75 45
bryantaylor 0:eafc3fd41f75 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`.
bryantaylor 0:eafc3fd41f75 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`.
bryantaylor 0:eafc3fd41f75 48
bryantaylor 0:eafc3fd41f75 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`.
bryantaylor 0:eafc3fd41f75 50
bryantaylor 0:eafc3fd41f75 51 It's possible to inherit from more than one target. For example:
bryantaylor 0:eafc3fd41f75 52
bryantaylor 0:eafc3fd41f75 53 ```
bryantaylor 0:eafc3fd41f75 54 "ImaginaryTarget": {
bryantaylor 0:eafc3fd41f75 55 "inherits": ["Target", "TEENSY3_1"]
bryantaylor 0:eafc3fd41f75 56 }
bryantaylor 0:eafc3fd41f75 57 ```
bryantaylor 0:eafc3fd41f75 58
bryantaylor 0:eafc3fd41f75 59 In this case, `ImaginaryTarget` inherits the properties of both `Target` and `TEENSY3_1`, so:
bryantaylor 0:eafc3fd41f75 60
bryantaylor 0:eafc3fd41f75 61 - the value of `ImaginaryTarget.default_toolchain` will be `ARM` (from `Target`)
bryantaylor 0:eafc3fd41f75 62 - the value of `ImaginaryTarget.OUTPUT_EXT` will be `hex` (from `TEENSY3_1`).
bryantaylor 0:eafc3fd41f75 63 - the value of `ImaginaryTarget.core` will be `null` (from `Target`, since that's the first parent of `ImaginaryTarget` that defines `core`).
bryantaylor 0:eafc3fd41f75 64
bryantaylor 0:eafc3fd41f75 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:
bryantaylor 0:eafc3fd41f75 66
bryantaylor 0:eafc3fd41f75 67 - look for the property in the current target.
bryantaylor 0:eafc3fd41f75 68 - if not found, look for the property in the first target's parent, then in the parent of the parent and so on.
bryantaylor 0:eafc3fd41f75 69 - if not found, look for the property in the rest of the target's parents, relative to the current inheritance level.
bryantaylor 0:eafc3fd41f75 70
bryantaylor 0:eafc3fd41f75 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).
bryantaylor 0:eafc3fd41f75 72
bryantaylor 0:eafc3fd41f75 73 ## core
bryantaylor 0:eafc3fd41f75 74
bryantaylor 0:eafc3fd41f75 75 The name of the ARM core used by the target.
bryantaylor 0:eafc3fd41f75 76
bryantaylor 0:eafc3fd41f75 77 Possible values: `"Cortex-M0"`, `"Cortex-M0+"`, `"Cortex-M1"`, `"Cortex-M3"`, `"Cortex-M4"`, `"Cortex-M4F"`, `"Cortex-M7"`, `"Cortex-M7F"`, `"Cortex-A9"`
bryantaylor 0:eafc3fd41f75 78
bryantaylor 0:eafc3fd41f75 79 ## public
bryantaylor 0:eafc3fd41f75 80
bryantaylor 0:eafc3fd41f75 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.
bryantaylor 0:eafc3fd41f75 82
bryantaylor 0:eafc3fd41f75 83 If `public` is not defined for a target, it defaults to `true`.
bryantaylor 0:eafc3fd41f75 84
bryantaylor 0:eafc3fd41f75 85 Note that unlike other target properties, **the value of `public` is not inherited from a parent to its children**.
bryantaylor 0:eafc3fd41f75 86
bryantaylor 0:eafc3fd41f75 87 ## macros, macros_add, macros_remove
bryantaylor 0:eafc3fd41f75 88
bryantaylor 0:eafc3fd41f75 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`.
bryantaylor 0:eafc3fd41f75 90
bryantaylor 0:eafc3fd41f75 91 When target inheritance is used, it's possible to alter the values of `macros` in inherited targets without re-defining `macros` completely:
bryantaylor 0:eafc3fd41f75 92
bryantaylor 0:eafc3fd41f75 93 - an inherited target can use `macros_add` to add its own macros.
bryantaylor 0:eafc3fd41f75 94 - an inherited target can use `macros_remove` to remove macros defined by its parents.
bryantaylor 0:eafc3fd41f75 95
bryantaylor 0:eafc3fd41f75 96 For example, in this configuration:
bryantaylor 0:eafc3fd41f75 97
bryantaylor 0:eafc3fd41f75 98 ```
bryantaylor 0:eafc3fd41f75 99 "TargetA": {
bryantaylor 0:eafc3fd41f75 100 "macros": ["PARENT_MACRO1", "PARENT_MACRO2"]
bryantaylor 0:eafc3fd41f75 101 },
bryantaylor 0:eafc3fd41f75 102 "TargetB": {
bryantaylor 0:eafc3fd41f75 103 "inherits": ["TargetA"],
bryantaylor 0:eafc3fd41f75 104 "macros_add": ["CHILD_MACRO1"],
bryantaylor 0:eafc3fd41f75 105 "macros_remove": ["PARENT_MACRO2"]
bryantaylor 0:eafc3fd41f75 106 }
bryantaylor 0:eafc3fd41f75 107 ```
bryantaylor 0:eafc3fd41f75 108
bryantaylor 0:eafc3fd41f75 109 the value of `TargetB.macros` will be `["PARENT_MACRO1", "CHILD_MACRO1"]`.
bryantaylor 0:eafc3fd41f75 110
bryantaylor 0:eafc3fd41f75 111 ## extra_labels, extra_labels_add, extra_labels_remove
bryantaylor 0:eafc3fd41f75 112
bryantaylor 0:eafc3fd41f75 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.
bryantaylor 0:eafc3fd41f75 114
bryantaylor 0:eafc3fd41f75 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.
bryantaylor 0:eafc3fd41f75 116
bryantaylor 0:eafc3fd41f75 117 ## features, features_add, features_remove
bryantaylor 0:eafc3fd41f75 118
bryantaylor 0:eafc3fd41f75 119 The list of **features** defines what hardware a device has.
bryantaylor 0:eafc3fd41f75 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.
bryantaylor 0:eafc3fd41f75 121
bryantaylor 0:eafc3fd41f75 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.
bryantaylor 0:eafc3fd41f75 123
bryantaylor 0:eafc3fd41f75 124 ## supported_toolchains
bryantaylor 0:eafc3fd41f75 125
bryantaylor 0:eafc3fd41f75 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`.
bryantaylor 0:eafc3fd41f75 127
bryantaylor 0:eafc3fd41f75 128 ## default_toolchain
bryantaylor 0:eafc3fd41f75 129
bryantaylor 0:eafc3fd41f75 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`.
bryantaylor 0:eafc3fd41f75 131
bryantaylor 0:eafc3fd41f75 132 ## post_binary_hook
bryantaylor 0:eafc3fd41f75 133
bryantaylor 0:eafc3fd41f75 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:
bryantaylor 0:eafc3fd41f75 135
bryantaylor 0:eafc3fd41f75 136 ```
bryantaylor 0:eafc3fd41f75 137 "post_binary_hook": {
bryantaylor 0:eafc3fd41f75 138 "function": "TEENSY3_1Code.binary_hook",
bryantaylor 0:eafc3fd41f75 139 "toolchains": ["ARM_STD", "ARM_MICRO", "GCC_ARM"]
bryantaylor 0:eafc3fd41f75 140 }
bryantaylor 0:eafc3fd41f75 141 ```
bryantaylor 0:eafc3fd41f75 142
bryantaylor 0:eafc3fd41f75 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.
bryantaylor 0:eafc3fd41f75 144
bryantaylor 0:eafc3fd41f75 145 As for the `binary_hook` code, this is how it looks in *targets.py*:
bryantaylor 0:eafc3fd41f75 146
bryantaylor 0:eafc3fd41f75 147 ```
bryantaylor 0:eafc3fd41f75 148 class TEENSY3_1Code:
bryantaylor 0:eafc3fd41f75 149 @staticmethod
bryantaylor 0:eafc3fd41f75 150 def binary_hook(t_self, resources, elf, binf):
bryantaylor 0:eafc3fd41f75 151 from intelhex import IntelHex
bryantaylor 0:eafc3fd41f75 152 binh = IntelHex()
bryantaylor 0:eafc3fd41f75 153 binh.loadbin(binf, offset = 0)
bryantaylor 0:eafc3fd41f75 154
bryantaylor 0:eafc3fd41f75 155 with open(binf.replace(".bin", ".hex"), "w") as f:
bryantaylor 0:eafc3fd41f75 156 binh.tofile(f, format='hex')
bryantaylor 0:eafc3fd41f75 157 ```
bryantaylor 0:eafc3fd41f75 158
bryantaylor 0:eafc3fd41f75 159 In this case, it converts the output file (`binf`) from binary format to Intel HEX format.
bryantaylor 0:eafc3fd41f75 160
bryantaylor 0:eafc3fd41f75 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.
bryantaylor 0:eafc3fd41f75 162
bryantaylor 0:eafc3fd41f75 163 ## progen
bryantaylor 0:eafc3fd41f75 164
bryantaylor 0:eafc3fd41f75 165 This property is used to pass additional data to the project generator (used to export the mbed code to various 3rd party tools and IDEs). A definition for `progen` looks like this:
bryantaylor 0:eafc3fd41f75 166
bryantaylor 0:eafc3fd41f75 167 ```
bryantaylor 0:eafc3fd41f75 168 "progen": {
bryantaylor 0:eafc3fd41f75 169 "target": "lpc11u35_401",
bryantaylor 0:eafc3fd41f75 170 "uvision": {
bryantaylor 0:eafc3fd41f75 171 "template": ["uvision_microlib.uvproj.tmpl"]
bryantaylor 0:eafc3fd41f75 172 }
bryantaylor 0:eafc3fd41f75 173 ```
bryantaylor 0:eafc3fd41f75 174
bryantaylor 0:eafc3fd41f75 175 The `target` property of `progen` specifies the target name that must be used for the exporter (if different than the mbed target name).
bryantaylor 0:eafc3fd41f75 176 For each exporter, a template for exporting can also be specified. In this example, the template used for generating a uVision project file is in a file called `uvision_microlib.uvproj.tmpl`. It is assumed that all the templates are located in `tools/export`.