joey shelton / LED_Demo2

dhgdh

Dependencies:   MAX44000 PWM_Tone_Library nexpaq_mdk

Fork of LED_Demo by joey shelton

mbd_os/docs/mbed_targets.md@1:55a6170b404f, 2016-09-17 (annotated)

Committer:
nexpaq
Date:
Sat Sep 17 16:32:05 2016 +0000
Revision:
1:55a6170b404f
checking in for sharing

Who changed what in which revision?

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