You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tvm.apache.org by GitBox <gi...@apache.org> on 2021/09/21 00:24:27 UTC
[GitHub] [tvm-rfcs] areusch commented on a change in pull request #30: Command Line Configuration Files
areusch commented on a change in pull request #30:
URL: https://github.com/apache/tvm-rfcs/pull/30#discussion_r712605365
##########
File path: rfcs/0030-tvmc-comand-line-configuration-files.md
##########
@@ -0,0 +1,119 @@
+- Feature Name: Command Line Configuration Files
+- Start Date: 2021-08-09
+- RFC PR: [apache/tvm-rfcs#30](https://github.com/apache/tvm-rfcs/pull/30)
+- GitHub Issue: [apache/tvm#0000](https://github.com/apache/tvm/issues/0000)
+
+# Summary
+[summary]: #summary
+
+Collecting common configurations for users of TVM and exposing them gracefully in `tvmc` using a `--config` option.
+
+# Motivation
+[motivation]: #motivation
+
+When a user first approaches TVM, choosing an appropriate configuration can be difficult, this is increasingly true in embedded systems where the configuration is not only a collection of devices but also how those devices are interfaced (see [Arm® Corstone™-300 reference package](https://developer.arm.com/ip-products/subsystem/corstone/corstone-300)). Trying to specify all of this in a target string or via command line arguments would be error prone and tedious. Predefining these in a common format allows users to get started and take the configurations for their own use cases easily.
+
+# Guide-level explanation
+[guide-level-explanation]: #guide-level-explanation
+
+## TVM Hosted Configurations
+Configurations will be stored as [JSON5](https://json5.org/) at `configs/<TYPE>/<NAME>.json`, this top level directory will enable other tooling to load configurations just as easily a `tvmc` and provide easy sign posting for users looking for configurations.
+
+A user coming to `tvmc` will begin with a default configuration which sets sensible defaults, such that `tvmc compile my_model.tflite` works out of the box. This is enabled by a `configs/host/default.json` which is likely to specify:
+
+```
+{
+ targets: [
+ {
+ kind: "llvm"
+ }
+ ]
+}
+```
+
+As a more substantial example, you can imagine an embedded board configuration such as the [Arm® Corstone™-300 reference package](https://developer.arm.com/ip-products/subsystem/corstone/corstone-300), which would exist under `configs/boards/corstone-300.json`:
+
+```json
+{
+ "output_format": "mlf",
+ "executor": {
+ "kind": "aot",
+ "unpacked-api": true
+ },
+ "targets": [
+ {
+ "kind": "ethos-u",
+ "accelerator_config": "ethos-u55-32"
+ },
+ {
+ "kind": "cmsisnn",
+ "mattr": "+fp"
+ },
+ {
+ "kind": "llvm"
+ }
+ ]
+}
+```
+
+This would be used if the user simply specifies `--config=corstone-300`, as in the following example:
+```
+tvmc compile --config=corstone-300 my_model.tflite
+```
+
+## User Provided Configurations
+The default search path, as illustrated above, is to find a matching `<NAME>.json` to an argument `--config=<NAME>`. A user can instead specify a path in the `--config` argument such as:
+
+```bash
+--config=./my.json
+--config=/etc/devices/my_secret_board.json
+```
+
+By default, TVM will prefer files explicitly specified as a path instead of hosted files.
+
+## Combination with existing parameters
+In the case of `tvmc`, `--config` will work alongside other arguments. Ideally anything specifiable in JSON will be specifiable in the command line to allow users to make small alterations such as:
Review comment:
usually we need to design this in. what's the "ideally" part here?
##########
File path: rfcs/0030-tvmc-comand-line-configuration-files.md
##########
@@ -0,0 +1,119 @@
+- Feature Name: Command Line Configuration Files
+- Start Date: 2021-08-09
+- RFC PR: [apache/tvm-rfcs#30](https://github.com/apache/tvm-rfcs/pull/30)
+- GitHub Issue: [apache/tvm#0000](https://github.com/apache/tvm/issues/0000)
+
+# Summary
+[summary]: #summary
+
+Collecting common configurations for users of TVM and exposing them gracefully in `tvmc` using a `--config` option.
+
+# Motivation
+[motivation]: #motivation
+
+When a user first approaches TVM, choosing an appropriate configuration can be difficult, this is increasingly true in embedded systems where the configuration is not only a collection of devices but also how those devices are interfaced (see [Arm® Corstone™-300 reference package](https://developer.arm.com/ip-products/subsystem/corstone/corstone-300)). Trying to specify all of this in a target string or via command line arguments would be error prone and tedious. Predefining these in a common format allows users to get started and take the configurations for their own use cases easily.
+
+# Guide-level explanation
+[guide-level-explanation]: #guide-level-explanation
+
+## TVM Hosted Configurations
+Configurations will be stored as [JSON5](https://json5.org/) at `configs/<TYPE>/<NAME>.json`, this top level directory will enable other tooling to load configurations just as easily a `tvmc` and provide easy sign posting for users looking for configurations.
+
+A user coming to `tvmc` will begin with a default configuration which sets sensible defaults, such that `tvmc compile my_model.tflite` works out of the box. This is enabled by a `configs/host/default.json` which is likely to specify:
+
+```
+{
+ targets: [
+ {
+ kind: "llvm"
+ }
+ ]
+}
+```
+
+As a more substantial example, you can imagine an embedded board configuration such as the [Arm® Corstone™-300 reference package](https://developer.arm.com/ip-products/subsystem/corstone/corstone-300), which would exist under `configs/boards/corstone-300.json`:
+
+```json
+{
+ "output_format": "mlf",
+ "executor": {
+ "kind": "aot",
+ "unpacked-api": true
+ },
+ "targets": [
+ {
+ "kind": "ethos-u",
+ "accelerator_config": "ethos-u55-32"
+ },
+ {
+ "kind": "cmsisnn",
+ "mattr": "+fp"
+ },
+ {
+ "kind": "llvm"
+ }
+ ]
+}
+```
+
+This would be used if the user simply specifies `--config=corstone-300`, as in the following example:
+```
+tvmc compile --config=corstone-300 my_model.tflite
+```
+
+## User Provided Configurations
+The default search path, as illustrated above, is to find a matching `<NAME>.json` to an argument `--config=<NAME>`. A user can instead specify a path in the `--config` argument such as:
+
+```bash
+--config=./my.json
+--config=/etc/devices/my_secret_board.json
+```
+
+By default, TVM will prefer files explicitly specified as a path instead of hosted files.
+
+## Combination with existing parameters
+In the case of `tvmc`, `--config` will work alongside other arguments. Ideally anything specifiable in JSON will be specifiable in the command line to allow users to make small alterations such as:
+
+```
+tvmc \
+ compile \
+ --config=corstone-300 \
+ --executor-aot-unpacked-api=0
+```
+
+Which allows experimentation with different parameters that can then be added to a custom JSON.
+
+# Reference-level explanation
+[reference-level-explanation]: #reference-level-explanation
+
+This will change the behaviour of how `tvmc` utilises `argparse`, it will first translate arguments from `argparse` into an internal dictionary of attributes and then apply those over the top of any specified configuration files. This means the default options for `argparse` are essentially nulled as they won't be aware of configuration files until after the arguments are parsed. The hierarchy is therefore:
+1. Arguments parsed by `argparse`
+2. Configuration file specified (defaults to `default`)
+3. Internal defaults for arguments in `tvmc`
+
+Because these results are additive the underlying defaults remain in `tvmc` rather than in `default.json` to ensure the user doesn't create a resulting configuration which additively makes no sense being based on an `llvm` target or other defaults.
+
+The configuration files will be loaded using [json5](https://pypi.org/project/json5/) to enable us to add comments and further details to the JSON files.
+
+# Drawbacks
+[drawbacks]: #drawbacks
+
+Although this presents a simpler interface for new users, the options become more complex for power users who want to mix and match arguments. This is mitigated by specifying simple rules for how these are composed.
+
+The convention of `--config` being read first then all other arguments is less intuitive than left to right parsing, but fits better with the current `argparse` infrastructure.
+
+# Rationale and alternatives
+[rationale-and-alternatives]: #rationale-and-alternatives
+
+# Prior art
+[prior-art]: #prior-art
+
+Such configuration files already exist in a number of platforms and tools to reduce the overhead on the user to define them, such as the [Zepyhr DeviceTree](https://github.com/zephyrproject-rtos/zephyr/tree/main/boards) or [gcc configurations for specific targets](https://github.com/gcc-mirror/gcc/blob/16e2427f50c208dfe07d07f18009969502c25dc8/gcc/config/arm/arm-cpus.in).
+
+# Unresolved questions
+[unresolved-questions]: #unresolved-questions
Review comment:
perhaps one is whether the direction of the Target specification is aligned with this (i think yes, but perhaps @junrushao1994 @mbs-octoml @jroesch could comment).
##########
File path: rfcs/0030-tvmc-comand-line-configuration-files.md
##########
@@ -0,0 +1,119 @@
+- Feature Name: Command Line Configuration Files
+- Start Date: 2021-08-09
+- RFC PR: [apache/tvm-rfcs#30](https://github.com/apache/tvm-rfcs/pull/30)
+- GitHub Issue: [apache/tvm#0000](https://github.com/apache/tvm/issues/0000)
+
+# Summary
+[summary]: #summary
+
+Collecting common configurations for users of TVM and exposing them gracefully in `tvmc` using a `--config` option.
+
+# Motivation
+[motivation]: #motivation
+
+When a user first approaches TVM, choosing an appropriate configuration can be difficult, this is increasingly true in embedded systems where the configuration is not only a collection of devices but also how those devices are interfaced (see [Arm® Corstone™-300 reference package](https://developer.arm.com/ip-products/subsystem/corstone/corstone-300)). Trying to specify all of this in a target string or via command line arguments would be error prone and tedious. Predefining these in a common format allows users to get started and take the configurations for their own use cases easily.
+
+# Guide-level explanation
+[guide-level-explanation]: #guide-level-explanation
+
+## TVM Hosted Configurations
+Configurations will be stored as [JSON5](https://json5.org/) at `configs/<TYPE>/<NAME>.json`, this top level directory will enable other tooling to load configurations just as easily a `tvmc` and provide easy sign posting for users looking for configurations.
+
+A user coming to `tvmc` will begin with a default configuration which sets sensible defaults, such that `tvmc compile my_model.tflite` works out of the box. This is enabled by a `configs/host/default.json` which is likely to specify:
+
+```
+{
+ targets: [
+ {
+ kind: "llvm"
+ }
+ ]
+}
+```
+
+As a more substantial example, you can imagine an embedded board configuration such as the [Arm® Corstone™-300 reference package](https://developer.arm.com/ip-products/subsystem/corstone/corstone-300), which would exist under `configs/boards/corstone-300.json`:
+
+```json
+{
+ "output_format": "mlf",
+ "executor": {
+ "kind": "aot",
+ "unpacked-api": true
+ },
+ "targets": [
+ {
+ "kind": "ethos-u",
+ "accelerator_config": "ethos-u55-32"
+ },
+ {
+ "kind": "cmsisnn",
+ "mattr": "+fp"
+ },
+ {
+ "kind": "llvm"
+ }
+ ]
+}
+```
+
+This would be used if the user simply specifies `--config=corstone-300`, as in the following example:
+```
+tvmc compile --config=corstone-300 my_model.tflite
+```
+
+## User Provided Configurations
+The default search path, as illustrated above, is to find a matching `<NAME>.json` to an argument `--config=<NAME>`. A user can instead specify a path in the `--config` argument such as:
+
+```bash
+--config=./my.json
Review comment:
can multiple `--config` be specified and then they are merged, or just one? how does merging work with other cmd line flags are given?
##########
File path: rfcs/0030-tvmc-comand-line-configuration-files.md
##########
@@ -0,0 +1,119 @@
+- Feature Name: Command Line Configuration Files
+- Start Date: 2021-08-09
+- RFC PR: [apache/tvm-rfcs#30](https://github.com/apache/tvm-rfcs/pull/30)
+- GitHub Issue: [apache/tvm#0000](https://github.com/apache/tvm/issues/0000)
+
+# Summary
+[summary]: #summary
+
+Collecting common configurations for users of TVM and exposing them gracefully in `tvmc` using a `--config` option.
+
+# Motivation
+[motivation]: #motivation
+
+When a user first approaches TVM, choosing an appropriate configuration can be difficult, this is increasingly true in embedded systems where the configuration is not only a collection of devices but also how those devices are interfaced (see [Arm® Corstone™-300 reference package](https://developer.arm.com/ip-products/subsystem/corstone/corstone-300)). Trying to specify all of this in a target string or via command line arguments would be error prone and tedious. Predefining these in a common format allows users to get started and take the configurations for their own use cases easily.
+
+# Guide-level explanation
+[guide-level-explanation]: #guide-level-explanation
+
+## TVM Hosted Configurations
+Configurations will be stored as [JSON5](https://json5.org/) at `configs/<TYPE>/<NAME>.json`, this top level directory will enable other tooling to load configurations just as easily a `tvmc` and provide easy sign posting for users looking for configurations.
+
+A user coming to `tvmc` will begin with a default configuration which sets sensible defaults, such that `tvmc compile my_model.tflite` works out of the box. This is enabled by a `configs/host/default.json` which is likely to specify:
+
+```
+{
+ targets: [
+ {
+ kind: "llvm"
+ }
+ ]
+}
+```
+
+As a more substantial example, you can imagine an embedded board configuration such as the [Arm® Corstone™-300 reference package](https://developer.arm.com/ip-products/subsystem/corstone/corstone-300), which would exist under `configs/boards/corstone-300.json`:
+
+```json
+{
+ "output_format": "mlf",
+ "executor": {
+ "kind": "aot",
+ "unpacked-api": true
+ },
+ "targets": [
+ {
+ "kind": "ethos-u",
+ "accelerator_config": "ethos-u55-32"
+ },
+ {
+ "kind": "cmsisnn",
+ "mattr": "+fp"
+ },
+ {
+ "kind": "llvm"
+ }
+ ]
+}
+```
+
+This would be used if the user simply specifies `--config=corstone-300`, as in the following example:
+```
+tvmc compile --config=corstone-300 my_model.tflite
+```
+
+## User Provided Configurations
+The default search path, as illustrated above, is to find a matching `<NAME>.json` to an argument `--config=<NAME>`. A user can instead specify a path in the `--config` argument such as:
+
+```bash
+--config=./my.json
+--config=/etc/devices/my_secret_board.json
+```
+
+By default, TVM will prefer files explicitly specified as a path instead of hosted files.
+
+## Combination with existing parameters
+In the case of `tvmc`, `--config` will work alongside other arguments. Ideally anything specifiable in JSON will be specifiable in the command line to allow users to make small alterations such as:
+
+```
+tvmc \
+ compile \
+ --config=corstone-300 \
+ --executor-aot-unpacked-api=0
+```
+
+Which allows experimentation with different parameters that can then be added to a custom JSON.
+
+# Reference-level explanation
+[reference-level-explanation]: #reference-level-explanation
+
+This will change the behaviour of how `tvmc` utilises `argparse`, it will first translate arguments from `argparse` into an internal dictionary of attributes and then apply those over the top of any specified configuration files. This means the default options for `argparse` are essentially nulled as they won't be aware of configuration files until after the arguments are parsed. The hierarchy is therefore:
+1. Arguments parsed by `argparse`
+2. Configuration file specified (defaults to `default`)
+3. Internal defaults for arguments in `tvmc`
+
+Because these results are additive the underlying defaults remain in `tvmc` rather than in `default.json` to ensure the user doesn't create a resulting configuration which additively makes no sense being based on an `llvm` target or other defaults.
Review comment:
couldn't you still do this when `--config` specifies one `llvm` and cmd line specifies another?
##########
File path: rfcs/0030-tvmc-comand-line-configuration-files.md
##########
@@ -0,0 +1,119 @@
+- Feature Name: Command Line Configuration Files
+- Start Date: 2021-08-09
+- RFC PR: [apache/tvm-rfcs#30](https://github.com/apache/tvm-rfcs/pull/30)
+- GitHub Issue: [apache/tvm#0000](https://github.com/apache/tvm/issues/0000)
+
+# Summary
+[summary]: #summary
+
+Collecting common configurations for users of TVM and exposing them gracefully in `tvmc` using a `--config` option.
+
+# Motivation
+[motivation]: #motivation
+
+When a user first approaches TVM, choosing an appropriate configuration can be difficult, this is increasingly true in embedded systems where the configuration is not only a collection of devices but also how those devices are interfaced (see [Arm® Corstone™-300 reference package](https://developer.arm.com/ip-products/subsystem/corstone/corstone-300)). Trying to specify all of this in a target string or via command line arguments would be error prone and tedious. Predefining these in a common format allows users to get started and take the configurations for their own use cases easily.
+
+# Guide-level explanation
+[guide-level-explanation]: #guide-level-explanation
+
+## TVM Hosted Configurations
+Configurations will be stored as [JSON5](https://json5.org/) at `configs/<TYPE>/<NAME>.json`, this top level directory will enable other tooling to load configurations just as easily a `tvmc` and provide easy sign posting for users looking for configurations.
+
+A user coming to `tvmc` will begin with a default configuration which sets sensible defaults, such that `tvmc compile my_model.tflite` works out of the box. This is enabled by a `configs/host/default.json` which is likely to specify:
+
+```
+{
+ targets: [
+ {
+ kind: "llvm"
+ }
+ ]
+}
+```
+
+As a more substantial example, you can imagine an embedded board configuration such as the [Arm® Corstone™-300 reference package](https://developer.arm.com/ip-products/subsystem/corstone/corstone-300), which would exist under `configs/boards/corstone-300.json`:
+
+```json
+{
+ "output_format": "mlf",
+ "executor": {
+ "kind": "aot",
+ "unpacked-api": true
+ },
+ "targets": [
+ {
+ "kind": "ethos-u",
+ "accelerator_config": "ethos-u55-32"
+ },
+ {
+ "kind": "cmsisnn",
+ "mattr": "+fp"
+ },
+ {
+ "kind": "llvm"
+ }
+ ]
+}
+```
+
+This would be used if the user simply specifies `--config=corstone-300`, as in the following example:
+```
+tvmc compile --config=corstone-300 my_model.tflite
+```
+
+## User Provided Configurations
+The default search path, as illustrated above, is to find a matching `<NAME>.json` to an argument `--config=<NAME>`. A user can instead specify a path in the `--config` argument such as:
+
+```bash
+--config=./my.json
+--config=/etc/devices/my_secret_board.json
+```
+
+By default, TVM will prefer files explicitly specified as a path instead of hosted files.
+
+## Combination with existing parameters
+In the case of `tvmc`, `--config` will work alongside other arguments. Ideally anything specifiable in JSON will be specifiable in the command line to allow users to make small alterations such as:
+
+```
+tvmc \
+ compile \
+ --config=corstone-300 \
+ --executor-aot-unpacked-api=0
+```
+
+Which allows experimentation with different parameters that can then be added to a custom JSON.
+
+# Reference-level explanation
+[reference-level-explanation]: #reference-level-explanation
+
+This will change the behaviour of how `tvmc` utilises `argparse`, it will first translate arguments from `argparse` into an internal dictionary of attributes and then apply those over the top of any specified configuration files. This means the default options for `argparse` are essentially nulled as they won't be aware of configuration files until after the arguments are parsed. The hierarchy is therefore:
Review comment:
can you explain how you merge complex object e.g. target?
##########
File path: rfcs/0030-tvmc-comand-line-configuration-files.md
##########
@@ -0,0 +1,119 @@
+- Feature Name: Command Line Configuration Files
+- Start Date: 2021-08-09
+- RFC PR: [apache/tvm-rfcs#30](https://github.com/apache/tvm-rfcs/pull/30)
+- GitHub Issue: [apache/tvm#0000](https://github.com/apache/tvm/issues/0000)
+
+# Summary
+[summary]: #summary
+
+Collecting common configurations for users of TVM and exposing them gracefully in `tvmc` using a `--config` option.
+
+# Motivation
+[motivation]: #motivation
+
+When a user first approaches TVM, choosing an appropriate configuration can be difficult, this is increasingly true in embedded systems where the configuration is not only a collection of devices but also how those devices are interfaced (see [Arm® Corstone™-300 reference package](https://developer.arm.com/ip-products/subsystem/corstone/corstone-300)). Trying to specify all of this in a target string or via command line arguments would be error prone and tedious. Predefining these in a common format allows users to get started and take the configurations for their own use cases easily.
+
+# Guide-level explanation
+[guide-level-explanation]: #guide-level-explanation
+
+## TVM Hosted Configurations
+Configurations will be stored as [JSON5](https://json5.org/) at `configs/<TYPE>/<NAME>.json`, this top level directory will enable other tooling to load configurations just as easily a `tvmc` and provide easy sign posting for users looking for configurations.
+
+A user coming to `tvmc` will begin with a default configuration which sets sensible defaults, such that `tvmc compile my_model.tflite` works out of the box. This is enabled by a `configs/host/default.json` which is likely to specify:
+
+```
+{
+ targets: [
+ {
+ kind: "llvm"
+ }
+ ]
+}
+```
+
+As a more substantial example, you can imagine an embedded board configuration such as the [Arm® Corstone™-300 reference package](https://developer.arm.com/ip-products/subsystem/corstone/corstone-300), which would exist under `configs/boards/corstone-300.json`:
+
+```json
+{
+ "output_format": "mlf",
+ "executor": {
+ "kind": "aot",
+ "unpacked-api": true
+ },
+ "targets": [
+ {
+ "kind": "ethos-u",
+ "accelerator_config": "ethos-u55-32"
+ },
+ {
+ "kind": "cmsisnn",
+ "mattr": "+fp"
+ },
+ {
+ "kind": "llvm"
+ }
+ ]
+}
+```
+
+This would be used if the user simply specifies `--config=corstone-300`, as in the following example:
+```
+tvmc compile --config=corstone-300 my_model.tflite
+```
+
+## User Provided Configurations
+The default search path, as illustrated above, is to find a matching `<NAME>.json` to an argument `--config=<NAME>`. A user can instead specify a path in the `--config` argument such as:
+
+```bash
+--config=./my.json
+--config=/etc/devices/my_secret_board.json
+```
+
+By default, TVM will prefer files explicitly specified as a path instead of hosted files.
+
+## Combination with existing parameters
+In the case of `tvmc`, `--config` will work alongside other arguments. Ideally anything specifiable in JSON will be specifiable in the command line to allow users to make small alterations such as:
+
+```
+tvmc \
+ compile \
+ --config=corstone-300 \
+ --executor-aot-unpacked-api=0
+```
+
+Which allows experimentation with different parameters that can then be added to a custom JSON.
+
+# Reference-level explanation
+[reference-level-explanation]: #reference-level-explanation
+
+This will change the behaviour of how `tvmc` utilises `argparse`, it will first translate arguments from `argparse` into an internal dictionary of attributes and then apply those over the top of any specified configuration files. This means the default options for `argparse` are essentially nulled as they won't be aware of configuration files until after the arguments are parsed. The hierarchy is therefore:
+1. Arguments parsed by `argparse`
+2. Configuration file specified (defaults to `default`)
+3. Internal defaults for arguments in `tvmc`
+
+Because these results are additive the underlying defaults remain in `tvmc` rather than in `default.json` to ensure the user doesn't create a resulting configuration which additively makes no sense being based on an `llvm` target or other defaults.
+
+The configuration files will be loaded using [json5](https://pypi.org/project/json5/) to enable us to add comments and further details to the JSON files.
+
+# Drawbacks
+[drawbacks]: #drawbacks
+
+Although this presents a simpler interface for new users, the options become more complex for power users who want to mix and match arguments. This is mitigated by specifying simple rules for how these are composed.
+
+The convention of `--config` being read first then all other arguments is less intuitive than left to right parsing, but fits better with the current `argparse` infrastructure.
+
+# Rationale and alternatives
+[rationale-and-alternatives]: #rationale-and-alternatives
Review comment:
while JSON5 seems okay, there are other config languages with comments e.g. yaml. could you speak to why you don't prefer that? looks like `json5` python package does not require any other packages--is that the one you propose to use?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@tvm.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org