Allow reopening CMSIS-DAP v2 adapters in v1 mode

[ALTracer]

Detailed description

• This sounds like a small new compatibilty feature.
• The existing problem is BMDA unusable on Windows with adapters implementing CMSIS-DAP v2 (Bulk) and v1 (HID) transports when no drivers are installed on them (WinUSB, libwdi, Zadig etc.)
• This PR solves it by attempting to open the adapter again (on a failed v2 call) via v1 API.

Tested on Windows Msys2 ucrt64 to allow working with RP2040 running free-dap again. Could test against other impls. I understand FS HID is worse performance than FS Bulk, but some users may have no admin rights to keep installing/associating drivers. So much for Plug&Play.

Your checklist for this pull request

• I've read the Code of Conduct
• I've read the guidelines for contributing to this repository
• It builds for hardware native (see Building the firmware) and should not affect it
• It builds as BMDA (see Building the BMDA)
• I've tested it to the best of my ability
• My commit messages provide a useful short description of what the commits do

Closing issues

[dragonmux]

The basic premise is reasonable, but this should not be the default behaviour as on, eg, Linux and macOS, it indicates an issue with the user's setup and that the user should explicitly opt into this behaviour with a command line option in addition to being told it's happening. Otherwise we run the very high risk of users unwittingly finding they're on CMSIS-DAP v1 and complaining that things are very slow as a bug against the project.

What we would suggest is a CMSIS-DAP specific command line option to allow protocol fallback (--allow-fallback, -k maybe) and only engage in this behaviour if that option is set. Either way we should also probably include a message to the user describing what was tried and that it didn't work.

[ALTracer]

but this should not be the default behaviour as on, eg, Linux and macOS, it indicates an issue with the user's setup

While I agree with this approach, so far I was unable to achieve such setup. While I'll attempt to edit the hosted/cli.c to pass one more commandline option (which is less trivial than auto-fallback), could you please provide me with a setup scenario for a faulty environment where a user launches BMDA and gets HID transport automatically, but has to do some (unobvious) extra steps to use BMDA libusb Bulk transport with some CMSIS-DAP implementation? Of course it has to be some cheap USB FS MCU firmware for a board I have (rp2040 free-dap, DragonProbe, ciniml/rust-dap; stm32f103cb plethora of binaries etc.), or I'll pause awaiting feedback from external testers with advanced boards. As stated on multiple previous PRs, I value performance of BMD, including flash reprogramming speed and SRAM block scrubbing speed (for e.g. RTT and CRC32), and the pitiful 26.5 KiB/s of FS HID is an Experience to work in constraints of. This PR mainly concerns Windows hosts.

What I have tried is flash https://github.com/WeActStudio/WeActStudio.MiniSTM32F4x1/tree/master/SDK/CMSIS-DAP to blackpill-f411ce, and this becomes a HID-only SWD-only CMSIS-DAP "v2.0.0" adapter, no Bulk transport, no fancy features. Then I disabled the /lib/udev/rules.d/60-openocd.rules provided by Ubuntu jammy openocd packages, and lost HID access (hidapi-hidraw?) to the adapter under normal user privileges (plus plugdev, dialout). How is it possible for BMDA (or for that matter OpenOCD) to discover a HID device (using libusb or not?) and open it but not be able to discover/open its Vendor-specific Bulk transport endpoints?

One other with is to have added some drivers/99-cmsis-dap.rules similar to blackmagic-plugdev.rules and stlink-plugdev.rules so the project does not depend on user proficiency or openocd rules to solve access issues.

[dragonmux]

could you please provide me with a setup scenario for a faulty environment where a user launches BMDA and gets HID transport automatically, but has to do some (unobvious) extra steps to use BMDA libusb Bulk transport with some CMSIS-DAP implementation?

Still don't entirely remember how we wound up with ORBTrace only able to talk CMSIS-DAP v1 on this machine (though we did) for a while.. but scenarios on macOS and Windows are quite trivial:

User plugs the device in for the first time on something like free-dap or DragonProbe firmware, or the original release ORBTrace gateware, they've never used a tool like this before so they do not have OOCD or another similar package installed that provides rules files (on macOS), and the firmware doesn't create WinUSB bindings. They ask BMDA to get a listing of the device, which on Windows will always succeed thanks to the HID interface, and on macOS likewise - it all looks fine and normal, so they try and use the device. Right now, as you note, BMDA will try and open the v2 interface, fail, and bail out.. with this patch, now the user sees their probe appears to work (but on v1 and, because they have no prior experience, they have no idea the significance of this or that they shot their own debugging speed in the foot).

This is why the fallback behaviour, even if not reproducible trivially on Linux, needs a command line option so the user has to do some thinking first and questions their setup. This would be a bad experience for an inexperienced user otherwise if it just happened automatically. They aren't going to know what the warning notice for fallback means and implies.

[ALTracer]

What we would suggest is a CMSIS-DAP specific command line option to allow protocol fallback (--allow-fallback, -k maybe) and only engage in this behaviour if that option is set. Either way we should also probably include a message to the user describing what was tried and that it didn't work.

Added the cmdline option as requested, to getopt short and long args. I may have forgotten to update the help block. Please review new user-facing message strings (UI).

Tested on Win11 Msys2 UCRT64 to behave better against rp2040 free-dap (after manually detaching the WinUSB driver in devmgmt.msc but it keeps coming back in a few minutes)

Using 6666:9930 C016A41B Alex Taradov
 Combined VCP and CMSIS-DAP Adapter ---
Using bulk transfer
libusb_claim_interface() failed
Could not setup a CMSIS-DAP device over Bulk interface, failing. Hint: pass --allow-fallback to retry HID interface
CMSIS-DAP write error: Entity not found (-5)

$ ./build-ucrt64/blackmagic.exe -tv 5 -k
Black Magic Debug App 5bf7d6e
 for Black Magic Probe, ST-Link v2 and v3, CMSIS-DAP, J-Link and FTDI (MPSSE)
Using 6666:9930 C016A41B Alex Taradov
 Combined VCP and CMSIS-DAP Adapter ---
Using bulk transfer
libusb_claim_interface() failed
Could not setup a CMSIS-DAP v2 device in Bulk mode (no drivers?), retrying HID mode
Using hid transfer
CMSIS-DAP v2.0.0, Capabilities: 03 (JTAG/SWD)
Adaptor supports DAP SWD sequences
Running in Test Mode
Target voltage: Unknown
Speed set to 4.000MHz for SWD
Switching out of dormant state into SWD
Deprecated JTAG to SWD sequence
No usable DP found
No target found

[dragonmux]

LGTM and we've seen it working via Discord, merging. Thank you for the contribution!