From 6ccb7b4eb9b2490ada998ccf207f34c616d3c8c2 Mon Sep 17 00:00:00 2001 From: Jimmy Brisson Date: Mon, 8 May 2017 14:39:25 -0500 Subject: [PATCH 1/5] Add documentation of the target liner script --- docs/advanced/mbed_targets.md | 117 ++++++++++++++++++++++++++++++++++ 1 file changed, 117 insertions(+) diff --git a/docs/advanced/mbed_targets.md b/docs/advanced/mbed_targets.md index e1b66a2b21..27330ced69 100644 --- a/docs/advanced/mbed_targets.md +++ b/docs/advanced/mbed_targets.md @@ -192,3 +192,120 @@ The `release_versions` property is a list of major versions of mbed OS that the ## `supported_form_factors` The `supported_form_factors` property is an optional list of form factors that a development board supports. You can use this property in C, C++ and assembly language by passing a macro prefixed with `TARGET_FF_` to the compiler. The accepted values for `supported_form_factors` are `ARDUINO`, which indicates compatibility with Arduino headers, and `MORPHO`, which indicates compatibility with ST Morpho headers. + +# Style guide + +A linting script for targets.json is avalible as tools/targets/lint.py in mbed OS. This script is a utility for avoiding common pit-falls of defining targets, and detecting style inconsistencies between targets. This linting script displays style errors based on a few rules outlined below. + +## Rules Enforced +There are two sets of rules: rules that impact how target inheritance must be structured, and rules that govern what each role within the inheritance hierarchy is allowed to do. + +### Inheritance rules +A target's inheritance must look like one of these: +``` +MCU -> Board +MCU -> Module -> Board +Family -> MCU -> Board +Family -> MCU -> Module -> Board +Family -> SubFamily -> MCU -> Board +Family -> SubFamily -> MCU -> Module -> Board +``` +The linting script takes it's best guess at where the Boards and Modules stop and the MCUs, Families and SubFamilies begin. +An MCU, Family or Subfamily must have at least one any Board or Module above it in any hierarchy. + +### Role rules + +For each of these target roles, some restrictions are in place: +- Families, MCUs and SubFamilies may contain the following keys: + - `core` + - `extra_labels` + - `features` + - `bootloader_supported` + - `device_name` + - `post_binary_hook` + - `default_tool chain` + - `config` + - `target_overrides` +- MCUs are required to have, and Families and SubFamilies may have: + - `release_versions` + - `supported_toolchains` + - `default_lib` + - `public` + - `device_has` +- Modules and Boards may have the following keys: + - `supported_form_factors` + - `is_disk_virtual` + - `detect_code` + - `extra_labels` + - `public` + - `config` + - `forced_reset_timeout` + - `target_overrides` +- `extra_labels` may not contain any target names +- if `release_versions` contains 5, then `supported_toolchains` must contain all of `GCC_ARM`, `ARM` and `IAR` +- MCUs, Families and SubFamilies must set `public` to `false` + + +## Sample output +The linting script takes three sub-commands: `targets`, `all-targets` and `orphans`. + +### `targets` and `all-targets` commands + +The `targets` and `all-targets` commands both show errors within public inheritance hierarchies. For example: + +`python tools/targets/lint.py targets EFM32GG_STK3700 EFM32WG_STK3800 LPC11U24_301` + +Could produce this output + +```yaml +hierarchy: Family (EFM32) -> MCU (EFM32GG990F1024) -> Board (EFM32GG_STK3700) +target errors: + EFM32: + - EFM32 is not allowed in extra_labels + EFM32GG990F1024: + - macros found, and is not allowed + - default_lib not found, and is required + - device_has not found, and is required + EFM32GG_STK3700: + - progen found, and is not allowed + - device_has found, and is not allowed +--- +hierarchy: Family (EFM32) -> MCU (EFM32WG990F256) -> Board (EFM32WG_STK3800) +target errors: + EFM32: + - EFM32 is not allowed in extra_labels + EFM32WG990F256: + - macros found, and is not allowed + - default_lib not found, and is required + - device_has not found, and is required + EFM32WG_STK3800: + - progen found, and is not allowed + - device_has found, and is not allowed +--- +hierarchy: Family (LPCTarget) -> MCU (LPC11U24_301) -> ??? +hierarchy errors: +- no boards found in heirarchy +target errors: + LPC11U24_301: + - release_versions not found, and is required + - default_lib not found, and is required + - public not found, and is required +``` + +The `all-targets` command is very verbose, with output that matches the format above, but too long to reproduce here. + +### `orphans` command + +The `orphans` command shows all targets that are not reachable from a public target. + +`python tools/targets/lint.py orphans` + +```yaml +- CM4_UARM +- CM4_ARM +- CM4F_UARM +- CM4F_ARM +- LPC1800 +- EFR32MG1P132F256GM48 +- EFR32MG1_BRD4150 +``` From 26ee2287c80c2effe2eb2d769d10f1402c16b740 Mon Sep 17 00:00:00 2001 From: Jimmy Brisson Date: Thu, 18 May 2017 15:14:58 -0500 Subject: [PATCH 2/5] Add rule about no macros --- docs/advanced/mbed_targets.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/advanced/mbed_targets.md b/docs/advanced/mbed_targets.md index 27330ced69..b063e6589d 100644 --- a/docs/advanced/mbed_targets.md +++ b/docs/advanced/mbed_targets.md @@ -241,6 +241,7 @@ For each of these target roles, some restrictions are in place: - `config` - `forced_reset_timeout` - `target_overrides` +- `macros` are not used. That is intentional: they do not provide any benefit over `config` and `target_overrides` but can be very difficult to use. In practice it is very difficult to override the value of a macro with a value. `config` and `target_overries`, on the other hand, are designed for this use case. - `extra_labels` may not contain any target names - if `release_versions` contains 5, then `supported_toolchains` must contain all of `GCC_ARM`, `ARM` and `IAR` - MCUs, Families and SubFamilies must set `public` to `false` From 6c8d1bac1829a1cbeacc5218bdd9056979c8d290 Mon Sep 17 00:00:00 2001 From: Amanda Butler Date: Thu, 1 Jun 2017 14:39:44 -0500 Subject: [PATCH 3/5] Copy edit mbed_targets.md Copy edit for active voice, precise language and typos. --- docs/advanced/mbed_targets.md | 76 +++++++++++++++++------------------ 1 file changed, 38 insertions(+), 38 deletions(-) diff --git a/docs/advanced/mbed_targets.md b/docs/advanced/mbed_targets.md index b063e6589d..da217d95b5 100644 --- a/docs/advanced/mbed_targets.md +++ b/docs/advanced/mbed_targets.md @@ -195,60 +195,60 @@ The `supported_form_factors` property is an optional list of form factors that a # Style guide -A linting script for targets.json is avalible as tools/targets/lint.py in mbed OS. This script is a utility for avoiding common pit-falls of defining targets, and detecting style inconsistencies between targets. This linting script displays style errors based on a few rules outlined below. +A linting script for `targets.json` is available as `tools/targets/lint.py` in mbed OS. This script is a utility for avoiding common errors when defining targets and detecting style inconsistencies between targets. This linting script displays style errors based on a few rules outlined below. -## Rules Enforced -There are two sets of rules: rules that impact how target inheritance must be structured, and rules that govern what each role within the inheritance hierarchy is allowed to do. +## Rules enforced +There are two sets of rules: rules that affect how you must structure target inheritance and rules that govern what each role within the inheritance hierarchy can do. ### Inheritance rules A target's inheritance must look like one of these: + ``` MCU -> Board MCU -> Module -> Board Family -> MCU -> Board Family -> MCU -> Module -> Board -Family -> SubFamily -> MCU -> Board -Family -> SubFamily -> MCU -> Module -> Board +Family -> Subfamily -> MCU -> Board +Family -> Subfamily -> MCU -> Module -> Board ``` -The linting script takes it's best guess at where the Boards and Modules stop and the MCUs, Families and SubFamilies begin. -An MCU, Family or Subfamily must have at least one any Board or Module above it in any hierarchy. + +The linting script guesses where the Boards and Modules stop and the MCUs, Families and Subfamilies begin. An MCU, Family or Subfamily must have at least one Board or Module above it in any hierarchy. ### Role rules For each of these target roles, some restrictions are in place: -- Families, MCUs and SubFamilies may contain the following keys: - - `core` - - `extra_labels` - - `features` - - `bootloader_supported` - - `device_name` - - `post_binary_hook` - - `default_tool chain` - - `config` - - `target_overrides` -- MCUs are required to have, and Families and SubFamilies may have: - - `release_versions` - - `supported_toolchains` - - `default_lib` - - `public` - - `device_has` +- Families, MCUs and Subfamilies may contain the following keys: + - `core`. + - `extra_labels`. + - `features`. + - `bootloader_supported`. + - `device_name`. + - `post_binary_hook`. + - `default_tool chain`. + - `config`. + - `target_overrides`. +- MCUs are required to have, and Families and Subfamilies may have: + - `release_versions`. + - `supported_toolchains`. + - `default_lib`. + - `public`. + - `device_has`. - Modules and Boards may have the following keys: - - `supported_form_factors` - - `is_disk_virtual` - - `detect_code` - - `extra_labels` - - `public` - - `config` - - `forced_reset_timeout` + - `supported_form_factors`. + - `is_disk_virtual`. + - `detect_code`. + - `extra_labels`. + - `public`. + - `config`. + - `forced_reset_timeout`. - `target_overrides` -- `macros` are not used. That is intentional: they do not provide any benefit over `config` and `target_overrides` but can be very difficult to use. In practice it is very difficult to override the value of a macro with a value. `config` and `target_overries`, on the other hand, are designed for this use case. -- `extra_labels` may not contain any target names -- if `release_versions` contains 5, then `supported_toolchains` must contain all of `GCC_ARM`, `ARM` and `IAR` -- MCUs, Families and SubFamilies must set `public` to `false` - +- `macros` are not used. That is intentional: They do not provide any benefit over `config` and `target_overrides` and can be difficult to use. In practice, it is difficult to override the value of a macro with a value. `config` and `target_overries`, however, are designed for this use case. +- `extra_labels` may not contain any target names. +- If `release_versions` contains 5, then `supported_toolchains` must contain all of `GCC_ARM`, `ARM` and `IAR`. +- MCUs, Families and Subfamilies must set `public` to `false`. ## Sample output -The linting script takes three sub-commands: `targets`, `all-targets` and `orphans`. +The linting script takes three subcommands: `targets`, `all-targets` and `orphans`. ### `targets` and `all-targets` commands @@ -293,11 +293,11 @@ target errors: - public not found, and is required ``` -The `all-targets` command is very verbose, with output that matches the format above, but too long to reproduce here. +The `all-targets` command is very verbose, with output that matches the format above but is too long to reproduce here. ### `orphans` command -The `orphans` command shows all targets that are not reachable from a public target. +The `orphans` command shows all targets that you cannot reach from a public target. `python tools/targets/lint.py orphans` From 08a9f141f24367164443b109e9b6d688b48dfc86 Mon Sep 17 00:00:00 2001 From: Jimmy Brisson Date: Tue, 27 Jun 2017 16:28:51 -0500 Subject: [PATCH 4/5] Document device has whitelist --- docs/advanced/mbed_targets.md | 33 +++++++++++++++++++++++++++++---- 1 file changed, 29 insertions(+), 4 deletions(-) diff --git a/docs/advanced/mbed_targets.md b/docs/advanced/mbed_targets.md index da217d95b5..1e86b3a99c 100644 --- a/docs/advanced/mbed_targets.md +++ b/docs/advanced/mbed_targets.md @@ -242,10 +242,35 @@ For each of these target roles, some restrictions are in place: - `config`. - `forced_reset_timeout`. - `target_overrides` -- `macros` are not used. That is intentional: They do not provide any benefit over `config` and `target_overrides` and can be difficult to use. In practice, it is difficult to override the value of a macro with a value. `config` and `target_overries`, however, are designed for this use case. -- `extra_labels` may not contain any target names. -- If `release_versions` contains 5, then `supported_toolchains` must contain all of `GCC_ARM`, `ARM` and `IAR`. -- MCUs, Families and Subfamilies must set `public` to `false`. +- `macros` are not used. That is intentional: they do not provide any benefit over `config` and `target_overrides` but can be very difficult to use. In practice it is very difficult to override the value of a macro with a value. `config` and `target_overries`, on the other hand, are designed for this use case. +- `extra_labels` may not contain any target names +- `device_has` may only contain values from the following list: + - `ANALOGIN`. + - `ANALOGOUT`. + - `CAN`. + - `ETHERNET`. + - `EMAC`. + - `FLASH`. + - `I2C`. + - `I2CSLAVE`. + - `I2C_ASYNCH`. + - `INTERRUPTIN`. + - `LOWPOWERTIMER`. + - `PORTIN`. + - `PORTINOUT`. + - `PORTOUT`. + - `PWMOUT`. + - `RTC`. + - `TRNG`. + - `SERIAL`. + - `SERIAL_ASYNCH`. + - `SERIAL_FC`. + - `SLEEP`. + - `SPI`. + - `SPI_ASYNCH`. + - `SPISLAVE`. +- if `release_versions` contains 5, then `supported_toolchains` must contain all of `GCC_ARM`, `ARM` and `IAR` +- MCUs, Families and SubFamilies must set `public` to `false` ## Sample output The linting script takes three subcommands: `targets`, `all-targets` and `orphans`. From 752da30ddf1e9f3018719c59698e2f0278edd77f Mon Sep 17 00:00:00 2001 From: Amanda Butler Date: Fri, 7 Jul 2017 11:20:36 -0500 Subject: [PATCH 5/5] Update mbed_targets.md Fix header sizes --- docs/advanced/mbed_targets.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/advanced/mbed_targets.md b/docs/advanced/mbed_targets.md index 1e86b3a99c..a7ccd55d4e 100644 --- a/docs/advanced/mbed_targets.md +++ b/docs/advanced/mbed_targets.md @@ -193,14 +193,14 @@ The `release_versions` property is a list of major versions of mbed OS that the The `supported_form_factors` property is an optional list of form factors that a development board supports. You can use this property in C, C++ and assembly language by passing a macro prefixed with `TARGET_FF_` to the compiler. The accepted values for `supported_form_factors` are `ARDUINO`, which indicates compatibility with Arduino headers, and `MORPHO`, which indicates compatibility with ST Morpho headers. -# Style guide +## Style guide A linting script for `targets.json` is available as `tools/targets/lint.py` in mbed OS. This script is a utility for avoiding common errors when defining targets and detecting style inconsistencies between targets. This linting script displays style errors based on a few rules outlined below. -## Rules enforced +### Rules enforced There are two sets of rules: rules that affect how you must structure target inheritance and rules that govern what each role within the inheritance hierarchy can do. -### Inheritance rules +#### Inheritance rules A target's inheritance must look like one of these: ``` @@ -214,7 +214,7 @@ Family -> Subfamily -> MCU -> Module -> Board The linting script guesses where the Boards and Modules stop and the MCUs, Families and Subfamilies begin. An MCU, Family or Subfamily must have at least one Board or Module above it in any hierarchy. -### Role rules +#### Role rules For each of these target roles, some restrictions are in place: - Families, MCUs and Subfamilies may contain the following keys: @@ -272,10 +272,10 @@ For each of these target roles, some restrictions are in place: - if `release_versions` contains 5, then `supported_toolchains` must contain all of `GCC_ARM`, `ARM` and `IAR` - MCUs, Families and SubFamilies must set `public` to `false` -## Sample output +### Sample output The linting script takes three subcommands: `targets`, `all-targets` and `orphans`. -### `targets` and `all-targets` commands +#### `targets` and `all-targets` commands The `targets` and `all-targets` commands both show errors within public inheritance hierarchies. For example: @@ -320,7 +320,7 @@ target errors: The `all-targets` command is very verbose, with output that matches the format above but is too long to reproduce here. -### `orphans` command +#### `orphans` command The `orphans` command shows all targets that you cannot reach from a public target.