West extension for querying runner capabilities

[mbolivar-nordic]

Is your enhancement proposal related to a problem? Please describe.

Environments such as IDEs may want to call commands like west flash in order to allow users to perform common workflow tasks using GUI widgets or keyboard shortcuts. Currently, such environments have no machine-readable access to the set of available runners and their individual capabilities. This forces them to maintain hacks or quirk tables as runner capabilities change over time. One example happened when the west flash --dev-id option came in and deprecated other runner-specific options with the same purpose (such as --snr for the nrfjprog runner).

This causes problems for the maintainers of such environments and bad user experiences when changes in the runner code regress GUI workflows.

Describe the solution you'd like

A new west extension which allows callers to introspect the capabilities of the runners associated with a build directory or independent of any build directory, named west runners. This should allow callers to dump runner capabilities (such as those captured in a runners.core.RunnerCaps object instance in the runners Python API) to standard output in a machine-readable format such as JSON. The command line interface should be flexible enough to accommodate new queries as time goes on without having to add new commands.

This would be similar in spirit to existing human-readable command output from west flash --context and friends, but with a stable and machine readable output format.

Describe alternatives you've considered

• asking such environments to query the runner API in Python: this isn't useful enough to all environments that may need this. Emacs's extension language is elisp, VS Code extensions aren't written in Python either, etc. Using JSON as a starting point seems like a better common denominator, especially given that format's usage in the language server protocol (LSP).
• adding a machine-readable file format with stability guarantees to the zephyr build directory: this is possible, but has two problems compared to the above approach. The first is that extending file formats in future-proof ways can be trickier than adding new command line options. For example, new file contents may break third-party parsers in calling environments that don't expect them, and which we have no control over. The second is that calling environments may want to get some information about runners totally independent of any build directory.

[mbolivar-nordic]

Here is a rough example of what I'm thinking about (details tbd):

$ west runners --capabilities -r nrfjprog -r jlink
{
    'nrfjprog': {
	'commands': ['flash'],
	'--softreset': true,
	'--recover': true,
	...,
	{'_common': {
	    '--dev-id': true,
	    'flash_addr': true,
	    '--erase': true,
	    '--tool-opt': true}
	}
    },
    'jlink': {
	'commands': ['flash', 'debug', 'debugserver', 'attach'],
	'--gdb-port': true,
	'--gdb-host': true,
	...,
	'_common': {
	    '--dev-id': true,
	    ...
	}
    }
}

That is, we should have a way to convey the common command line options (in _common) that may be shared by multiple runners, as well as other features and command line options that may be specific to individual runners.

[zephyrbot]

Hi @mbolivar-nordic,

This issue, marked as an Enhancement, was opened a while ago and did not get any traction. Please confirm the issue is correctly assigned and re-assign it otherwise.

Please take a moment to review if the issue is still relevant to the project. If it is, please provide feedback and direction on how to move forward. If it is not, has already been addressed, is a duplicate, or is no longer relevant, please close it with a short comment explaining the reason.

Thanks!