west: runners: Add new -i/--dev-id device identifier common runner option #37509

carlescufi · 2021-08-06T16:49:56Z

In order to avoid different runners implementing device identification each in their own way, introduce a new -i/--dev-id command-line switch that allows the user to specify which board/debugger/node is to be targeted by the flash or debug operation.

henrikbrixandersen

Not sure if this is the right approach for all runners. Take for instance the CANopen Node ID; Everybody working with CANopen knows what a Node ID is, but would likely not associate --dev-id with being that from the generic description given. Compare it to e.g. an IP address of a remote debugger - it would not be obvious to pass that in as --dev-id? Same applies to serial numbers, USB VID:PID, board names, etc.

Blocking this to ensure we have a discussion about this.

carlescufi · 2021-08-06T17:40:13Z

Not sure if this is the right approach for all runners. Take for instance the CANopen Node ID; Everybody working with CANopen knows what a Node ID is, but would likely not associate --dev-id with being that from the generic description given. Compare it to e.g. an IP address of a remote debugger - it would not be obvious to pass that in as --dev-id? Same applies to serial numbers, USB VID:PID, board names, etc.

It's a matter of taste more than anything else. Personally I prefer having a single command-line option that is reused by all runners albeit with slight different meanings based on the context, but the opposite argument can be made. For me, anything that identifies a device can fall under the -i/--dev-id usage, and I am more comfortable using -i <node id/vid:pid/serial> than having to remember specific options for each runner.

mbolivar-nordic

Thanks for finally crossing off this longstanding TODO.

I defer to @henrikbrixandersen on the canopennode runner.

As for the rest, no objections to adding the option, but there's no need to break compatibility. See comments for details.

scripts/west_commands/runners/core.py

scripts/west_commands/runners/nrfjprog.py

scripts/west_commands/runners/dfu.py

scripts/west_commands/runners/pyocd.py

mbolivar-nordic · 2021-08-06T21:37:51Z

The test cases need updates too.

henrikbrixandersen · 2021-08-09T19:48:42Z

I am sorry. I still think these changes are making the command line options less obvious for an end-user. There is no way - except for reading the source code - for en end-user to know what --dev-id expects for a given runner. Serial number? Node ID? IP address? IP:port? USB VID:PID?

Unifying these into one also means that adding more ways of selecting a given instance is even more obscure. Say, a runner that supports selection via either serial number or USB VID:PID.

mbolivar-nordic · 2021-08-09T21:02:25Z

There is no way - except for reading the source code - for en end-user to know what --dev-id expects for a given runner. Serial number? Node ID? IP address? IP:port? USB VID:PID?

We can fix this in both the .rst files and in the command line help.

Unifying these into one also means that adding more ways of selecting a given instance is even more obscure. Say, a runner that supports selection via either serial number or USB VID:PID.

Do you actually have a such a situation? I can imagine IP vs. USB debugging with a J-Link, but that seems solvable with either some additional smarts in the runner ("is this argument an IP:port? Then it's IP. Is it just a number? Then it's USB.") or another option like --id-format.

Assuming we sort these things out, are you still opposed to the idea completely, or are you saying you have reservations about the current status?

carlescufi · 2021-08-10T17:11:36Z

We can fix this in both the .rst files and in the command line help.

I completely agree with @mbolivar-nordic. Documenting this properly and then getting the users to understand that a command-line option might take different formats based on the runner seems simpler for the user to me than having to remember a bunch of different ones. But again, this is purely cosmetic and so subject to individual taste.

@henrikbrixandersen an alternative to generalizing it entirely would be to do this only for those that identify a particular debugger instance. So only jlink, nrfjprog and pyocd would use -i/--dev-id.

mbolivar-nordic · 2021-08-11T16:41:00Z

I think it's time to document the individual runner backends on the .rst side. On the help string side, I think core.py should set the help text for the dev_id option using a self.dev_id_help attribute which subclasses can override. Then each runner can explain what the individual ID contents are via an override of that attribute.

galak · 2021-08-11T22:58:27Z

Would using -u like pyocd be any clearier?

  -u UNIQUE_ID, --uid UNIQUE_ID, --probe UNIQUE_ID
                        Choose a probe by its unique ID or a substring thereof. Optionally prefixed with
                        '<probe-type>:' where <probe-type> is the name of a probe plugin.

henrikbrixandersen · 2021-08-12T14:07:29Z

Would using -u like pyocd be any clearier?

Not as I see it. What I questioning here is what the benefit by combining these different configuration options into one and leave the user to parse a help text/source code in order to find out what kind of argument the given runner expects when specifying that option.

I am all for combining options for common parameters (e.g. --serial-number or --remote-host or similiar`), but I fail to see the benefit of combining them into one, when they do not accept the same arguments.

If I do a west -r canopen -H and see e.g. --node-id I don't need to read any more help text in order to figure out what to pass as argument. If I run the same command and see --dev-id or --uid I would not know what to pass without reading the help text.

We could even (I don't believe we have that today?) have bash completion of runner specific arguments, which would make it even more intuitive to use. Type in west -r canopen --<TAB>, see --node-id in the list and from the option name already there know what to pass as argument - without even looking at the help output or other documentation.

Just to clarify: The above goes for other runner device selection arguments than the CANopen runner --node-id, which is just used as an example.

galak · 2021-08-12T15:26:00Z

dev-review (Aug 12, 2021):

suggestion is to support both the old and new option. All runners for debug/flash should support the new option at min going forward. Docs/usage help to clarify.

carlescufi · 2021-08-12T16:52:14Z

I think core.py should set the help text for the dev_id option using a self.dev_id_help attribute which subclasses can override

This sounds like a very good idea. I will start with that, given that anyway we are keeping the old options I can actually reuse the same text for both on each runner.

carlescufi · 2021-09-28T17:27:00Z

@mbolivar-nordic

I think it's time to document the individual runner backends on the .rst side

I am not sure about this one for this PR, but I am happy to discuss this with you to see if we can make it happen.

I think core.py should set the help text for the dev_id option using a self.dev_id_help attribute which subclasses can override. Then each runner can explain what the individual ID contents are via an override of that attribute.

This is now done.

@henrikbrixandersen

suggestion is to support both the old and new option.

I did that for the runners that are controversial.

gmarull

LGTM, I've added one comment. I think deprecation notice would be a useful addition.

scripts/west_commands/runners/nrfjprog.py

henrikbrixandersen

A few minor nits, otherwise looks good, thank you for updating.

scripts/west_commands/runners/canopen_program.py

scripts/west_commands/runners/nrfjprog.py

carlescufi · 2021-10-05T13:57:27Z

@mbolivar-nordic and @henrikbrixandersen could you please take another look?
@gmarull thanks for the suggestion, I implemented the deprecation helper Action

scripts/west_commands/runners/canopen_program.py

mbolivar-nordic

Looking good now; just a couple of things. Thanks again.

scripts/west_commands/runners/jlink.py

scripts/west_commands/runners/nrfjprog.py

mbolivar-nordic · 2021-10-11T17:38:53Z

scripts/west_commands/runners/nrfjprog.py

+                            action=partial(depr_action,
+                                           replacement='-i/--dev-id'),


It feels like this should be structured as:

A commit adding DeprecatedAction

A commit adding the new common option

Commits updating the existing runners to use the new option and deprecating the old one using DeprecatedAction (as needed; I know not all runners are deprecating their specific options)

But it's not a huge deal so I'm not blocking on this comment.

I agree with you, but honestly I think it's not worth the rebase effort. I need to pick my fights :)

In an effort to standardize the way that a particular debugger or device instance is identified when there are multiple present, introduce a new -i/--dev-id option common to all runners that allows the user to specify which device to interact with when there are multiple connected. Signed-off-by: Carles Cufi <[email protected]>

Remove the previous jlink-specific --id option and switch to the common -i/--dev-id one. Signed-off-by: Carles Cufi <[email protected]>

Remove the previous nrfjprog-specific --id option and switch to the common -i/--dev-id one. Signed-off-by: Carles Cufi <[email protected]>

Remove the previous canopen-specific --node-id option and switch to the common -i/--dev-id one. Signed-off-by: Carles Cufi <[email protected]>

Remove the previous dfu-util-specific --pid option and switch to the common -i/--dev-id one. Signed-off-by: Carles Cufi <[email protected]>

Remove the previous pyocd-specific --board-id option and switch to the common -i/--dev-id one. Signed-off-by: Carles Cufi <[email protected]>

In order to allow for further options to be deprecated with minimal impact, add a deprecation argparse Action and a callable instantiator that can be used to deprecate options in favor of new ones. Signed-off-by: Carles Cufi <[email protected]>

carlescufi requested a review from mbolivar-nordic as a code owner August 6, 2021 16:49

carlescufi requested review from henrikbrixandersen, mbolivar-nordic and MaureenHelm and removed request for mbolivar-nordic August 6, 2021 16:50

henrikbrixandersen requested changes Aug 6, 2021

View reviewed changes

carlescufi requested review from jfischer-no, alexanderwachter and anangl August 6, 2021 17:40

mbolivar-nordic suggested changes Aug 6, 2021

View reviewed changes

carlescufi force-pushed the runners-devsel branch from 4e89644 to 3af1ffd Compare August 9, 2021 15:09

carlescufi requested review from henrikbrixandersen and mbolivar-nordic August 9, 2021 15:09

carlescufi force-pushed the runners-devsel branch from 3af1ffd to 33d1e85 Compare August 10, 2021 17:07

carlescufi added the dev-review To be discussed in dev-review meeting label Aug 11, 2021

galak removed the dev-review To be discussed in dev-review meeting label Aug 12, 2021

zephyrbot added the area: West West utility label Aug 19, 2021

zephyrbot requested a review from swinslow August 19, 2021 12:43

zephyrbot assigned mbolivar-nordic Aug 19, 2021

carlescufi force-pushed the runners-devsel branch from 33d1e85 to 09401e5 Compare September 28, 2021 17:21

carlescufi requested a review from gmarull September 29, 2021 08:33

gmarull approved these changes Sep 29, 2021

View reviewed changes

scripts/west_commands/runners/nrfjprog.py Outdated Show resolved Hide resolved

henrikbrixandersen requested changes Sep 29, 2021

View reviewed changes

scripts/west_commands/runners/canopen_program.py Outdated Show resolved Hide resolved

scripts/west_commands/runners/canopen_program.py Outdated Show resolved Hide resolved

scripts/west_commands/runners/nrfjprog.py Show resolved Hide resolved

carlescufi force-pushed the runners-devsel branch from 09401e5 to 1e00e68 Compare October 5, 2021 10:41

carlescufi requested a review from henrikbrixandersen October 5, 2021 10:42

carlescufi force-pushed the runners-devsel branch from 50c9354 to 06b776c Compare October 5, 2021 13:56

henrikbrixandersen requested changes Oct 5, 2021

View reviewed changes

scripts/west_commands/runners/canopen_program.py Outdated Show resolved Hide resolved

carlescufi force-pushed the runners-devsel branch from 06b776c to 8d61186 Compare October 5, 2021 14:25

carlescufi requested a review from henrikbrixandersen October 5, 2021 14:25

henrikbrixandersen approved these changes Oct 5, 2021

View reviewed changes

carlescufi force-pushed the runners-devsel branch 3 times, most recently from 8449e4a to eeccf51 Compare October 6, 2021 12:54

mbolivar-nordic suggested changes Oct 11, 2021

View reviewed changes

carlescufi added 7 commits October 11, 2021 21:07

runners: jlink: Convert to -i/--dev-id

6b521fc

Remove the previous jlink-specific --id option and switch to the common -i/--dev-id one. Signed-off-by: Carles Cufi <[email protected]>

runners: nrfjprog: Convert to -i/--dev-id

5b222c1

Remove the previous nrfjprog-specific --id option and switch to the common -i/--dev-id one. Signed-off-by: Carles Cufi <[email protected]>

runners: canopen: Convert to -i/--dev-id

57065bd

Remove the previous canopen-specific --node-id option and switch to the common -i/--dev-id one. Signed-off-by: Carles Cufi <[email protected]>

runners: dfu-util: Convert to -i/--dev-id

473b603

Remove the previous dfu-util-specific --pid option and switch to the common -i/--dev-id one. Signed-off-by: Carles Cufi <[email protected]>

runners: pyocd: Convert to -i/--dev-id

e6afece

Remove the previous pyocd-specific --board-id option and switch to the common -i/--dev-id one. Signed-off-by: Carles Cufi <[email protected]>

carlescufi force-pushed the runners-devsel branch from eeccf51 to ccd75e7 Compare October 11, 2021 19:23

carlescufi requested a review from mbolivar-nordic October 11, 2021 19:24

mbolivar-nordic approved these changes Oct 11, 2021

View reviewed changes

MaureenHelm approved these changes Oct 11, 2021

View reviewed changes

cfriedt merged commit 6a3593f into zephyrproject-rtos:main Oct 12, 2021

gmarull mentioned this pull request Jan 31, 2023

runners: restore obsolete synonyms for -i/--dev-id #53951

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

west: runners: Add new -i/--dev-id device identifier common runner option #37509

west: runners: Add new -i/--dev-id device identifier common runner option #37509

carlescufi commented Aug 6, 2021

henrikbrixandersen left a comment •

edited

Loading

carlescufi commented Aug 6, 2021

mbolivar-nordic left a comment

mbolivar-nordic commented Aug 6, 2021

henrikbrixandersen commented Aug 9, 2021

mbolivar-nordic commented Aug 9, 2021

carlescufi commented Aug 10, 2021

mbolivar-nordic commented Aug 11, 2021

galak commented Aug 11, 2021

henrikbrixandersen commented Aug 12, 2021

galak commented Aug 12, 2021

carlescufi commented Aug 12, 2021

carlescufi commented Sep 28, 2021

gmarull left a comment •

edited

Loading

henrikbrixandersen left a comment

carlescufi commented Oct 5, 2021

mbolivar-nordic left a comment

mbolivar-nordic Oct 11, 2021

carlescufi Oct 11, 2021

west: runners: Add new -i/--dev-id device identifier common runner option #37509

west: runners: Add new -i/--dev-id device identifier common runner option #37509

Conversation

carlescufi commented Aug 6, 2021

henrikbrixandersen left a comment • edited Loading

Choose a reason for hiding this comment

carlescufi commented Aug 6, 2021

mbolivar-nordic left a comment

Choose a reason for hiding this comment

mbolivar-nordic commented Aug 6, 2021

henrikbrixandersen commented Aug 9, 2021

mbolivar-nordic commented Aug 9, 2021

carlescufi commented Aug 10, 2021

mbolivar-nordic commented Aug 11, 2021

galak commented Aug 11, 2021

henrikbrixandersen commented Aug 12, 2021

galak commented Aug 12, 2021

carlescufi commented Aug 12, 2021

carlescufi commented Sep 28, 2021

gmarull left a comment • edited Loading

Choose a reason for hiding this comment

henrikbrixandersen left a comment

Choose a reason for hiding this comment

carlescufi commented Oct 5, 2021

mbolivar-nordic left a comment

Choose a reason for hiding this comment

mbolivar-nordic Oct 11, 2021

Choose a reason for hiding this comment

carlescufi Oct 11, 2021

Choose a reason for hiding this comment

henrikbrixandersen left a comment •

edited

Loading

gmarull left a comment •

edited

Loading