Maxim nexpaq / nexpaq_dev

Preliminary main mbed library for nexpaq development

docs/mbed_targets.md@1:d96dbedaebdb, 2016-11-04 (annotated)

Committer:
nexpaq
Date:
Fri Nov 04 20:54:50 2016 +0000
Revision:
1:d96dbedaebdb
Parent:
0:6c56fb4bc5f0 
Removed extra directories for other platforms

Who changed what in which revision?

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