Greg Steiert / pegasus_dev

Development mbed library for MAX32630FTHR

Dependents:   blinky_max32630fthr

docs/mbed_targets.md@0:5c4d7b2438d3, 2016-11-11 (annotated)

Committer:
switches
Date:
Fri Nov 11 20:59:50 2016 +0000
Revision:
0:5c4d7b2438d3
Initial commit

Who changed what in which revision?

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