areusch commented on a change in pull request #33: URL: https://github.com/apache/tvm-rfcs/pull/33#discussion_r716956895
########## File path: rfcs/0020-project_api_extend_metadata.md ########## @@ -0,0 +1,252 @@ +- Feature Name: extend_metadata_in_projectoption +- Start Date: 2021-09-09 +- RFC PR: [apache/tvm-rfcs#0020](https://github.com/apache/tvm-rfcs/pull/0000) +- GitHub Issue: [apache/tvm#0020](https://github.com/apache/tvm/issues/0000) + +# Summary +[summary]: #summary + +This RFC proposes to extend the current metadata associated with project options +provided by the Project API to allow a better integration with command line +interface tools, like TVMC. + +# Motivation +[motivation]: #motivation + +Currently metadata associated with project options provided by the Project API +is insufficent to allow building easily and automatically command line parsers +used by CLI tool like TVMC. + +The metadata available for the project options, stored in instances of the +ProjectOption class are limited as they do not: + +1. Provide a list of the API methods which support the options; +2. Allow determination if the options are required or optional; +3. Provide a default value if one is used by the Project API server. + +As a consequence it complicates the integration with command line interfaces +that need to create command line arguments based on the project options +available for a platform. + +This RFC proposes to extend the existing metadata with four new members in +`ProjectOption` (`required`, `optional`, `type`, and `default`) to address +issues **1.**, **2.**, and **3.** and ease the integration of Project API with +CLI tools. + +# Guide-level explanation +[guide-level-explanation]: #guide-level-explanation + +Below it is explained in detail the need and properties of the four new members +(`required`, `optional`, `type`, and `default`) proposed to be added to the +`ProjectOption` class to extend the project option metadata returned by Project +API `server_info_query` method. `required`, `optional`, and `type` are proposed +as **required fields**, whilst `default` is proposed as an **optional field**. + +Modals like "must", "may" and similar ones are interpreted in this RFC +accordingly to the semantics defined by the IETF RFC-2119, 1997. + +## On "required" and "optional" metadata + +Currently even though all options available for a given project can be +discovered via the Project API `server_info_query` interface there is no way to +know which options belong (or apply) to which API method (like the +`generate_project`, `build`, `flash`, and `open_transport` methods). + +This is fine when the user knowns beforehand which method accepts a set of +options, so it's possible to manually select which options will be passed to a +given API method, like when using the API in a Python script. + +However that's a problem when the API user (e.g. TVMC) needs to automatically +determine the options available for the API methods, like when automatically +building a command line parser with subcommand domains that closely mapped to +the API methods (e.g. subcommands to create, build, and flash a project). + +Moreover, currently it's impossible to determine which option is required and +which one is optional, so it would be at least necessary for the API user to +build a static ad hoc table with all options available on a given project +stating which option is required and which one is optional for the project. This +is impractical to maintain and would result in the API user having to update the +the static table every time an option is added, removed, or modified in the +Project API server. + +Hence to ease the automatic detection of the options available on each Project +API method the following two new metadata are proposed: `required` and +`optional`. + +Both will contain a list of method names for which the option is available, +either as a required option (if in `required` list), or as an optional option +(if in `optional` list). At least one API method must be listed in `required` or +in the `optional` list. A method name must be listed only in the `required` or +in the `optional` list, i.e. an option can't be required and optional at the +same time for given API method. An option can be required for a method and +optional for another method. + +The elements in the lists `required` and `optional` must be in the set of method +names implemented by the ProjectAPIClient class and that have the parameter +`options` defined. These methods are dispatched to the server, which implements +the server counterparts to properly handle the client dispatches and +ultimately defines the options available for each API method. The current method +name that satisfy these criteria are `generate_project`, `build`, `flash`, and +`open_transport`. + +`required` metadatum or `optional` metadatum (or both) must be provided for +every option. + +## On "type" metadatum + +The option type can sometimes be determined implicitly by what's return +in metadatum `choices`, but this not ideal. For example, for option `verbose` it +would be possible to infer it is a boolean option and therefore it can be +converted to a command line flag if metadatum `choices` is a couple of True and +False. Nonetheless that would lead to cumbersome logic at API user side (e.g. +TVMC) to infer the option type, like iterating over the tuple elements to search +for True or False. This can be solved directly if the option type is returned +explicitly with the option. + +Thus adding a `type` metadatum allows a much simpler way for the API users to +determine the type of an option when that is necessary for various reasons, like +when building a command line parser based on the available project options. + +The following types, passed as strings, are proposed for the `type` metadatum: Review comment: do you mean `struct.pack` or `PackedFunc`? I don't think `PackedFunc` has a place in this RPC, as it's using JSON-RPC not TVM RPC. I would think we would use JS objects to represent more complex values if we did go that direction, but honestly i prefer to not if possible to avoid over-complicating this. -- 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: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
