Refactor how launch and attach requests work.

[noppej]

This PR was motivated by discussions in #7, and will require rework of the equivalent functionality in probe-rs-debugger. It will involve a big code change in both repo's.

In the first iterations of this extension, the launch and attach terminology was interpreted to apply to the debug adapter process. In other words, "launch a new instance of the debug adapter", or "attach to a to an existing debug adapter process". - Both operations allowed flashing and resetting of the target process running on the probe.

• Neither operations allowed the debug adapter session to last for more than one session of the target process on the probe.

The proposed change will reinterpret the launch and attach terminology to apply to the target process running on the probe. To help clarify the different behaviours, I will use the following terminology:

• debug session: This refers to host side process, and ...
  • Starts when a user initiates either a launch or attach request, and ...
  • Ends when the user either initiates disconnect request, or chooses to Stop a host side debug session.
• target session: This refers to the target side process, and ...
  • Starts when the target device boots and executes the firmware program, and ...
  • Ends when the target device processing halts as a result of a unrecoverable exception, or as part of a Reset request, or when the device looses power.

launch request type

1. Start a debug session :
   i. Connect to the target device and executes a Reset request so that a new target session is started
   ii. Optionally flashes the target device firmware with the binary to be executed

attach request type

2. Start a debug session :
   i. Connect to the target device, but do NOT issue `Reset, so that the existing target session is uninterrupted

Common behaviour to both launch and attach request types

3. Support all standard debug behaviours, such as "Pause", "Breakpoints", RTT, etc.
4. The Reset request will cause probe-rs, to restart the target device, and associated target session.
   i. This will honour the value of the halt_after_reset flag.
   ii. The debug session is not affected.
5. The Disconnect request in the debug session will ...
   i. Instruct probe-rs to disconnect from the target device.
   ii. This implicitly ends the debug session.
   iii. The state of the target session is not affected.
   iv. There are some subtleties depending on launch vs attach as described in the MS DAP Specification for the Disconnect Request
6. The Stop function (Terminate request) in the debug session will behave the same as the disconnect, except ...
   i. The debug session will send a stop request to halt the target session before disconnecting.
   ii. There are some subtleties depending on launch vs attach as described in the MS DAP Specification for the Terminate Request

Running probe-rs-debugger as a standalone for a VSCode debug session

In most cases, the VSCode debug extension will take care of automatically launching (and ending) the probe-rs-debugger executable to act as the debug adapter for probe-rs.

It is possible for the user to take control of this, by running probe-rs-debugger from the command line, with the following command

• probe-rs-debugger debug --dap --port <any availably TCP/IP port number>

Any VSCode debug session can then attach to the specified on the server where probe-rs-debugger runs, and use the functionality above.

7. Such a server debug session implies the following:
   i. In order for VSCode to know where to find the debug adapter, the user needs to add the appropriate TCP host IP address and port number to the launch.json configuration, by adding the option "server":"<host address>:<port number>" (e.g. "server":"127.0.0.1:50000")
   ii. Such a server debug session will put the management (start and stop) of the probe-rs-debugger process completely under control of the user.

Further reading:

The above proposal aims to be consistent with the process described in the VSCode debug docs

[noppej]

@Tiwalun , @Yatekii , @huntc, @MabezDev

I would really appreciate if you could take a few minutes to review (and comment on) this proposal. It is a big chunk of work, and I'd like to get at least your alignment before I make the investment. I think it will be worth it to improve the user experience and ensure long term success/adoption of the debug extension.

Also, please feel free to invite others to comment if you think they can add to this discussion.

[Tiwalun]

Sounds good to me 👍.

I wrote the original issue, and this is exactly the kind of change I had in mind.

[noppej]

@Tiwalun Please review this PR, and keep in mind that it has to be synched with both:

• Refactor how launch and attach requests work. probe-rs#854
• Updated VSCode documentation for extension release 0.3.0 webpage#30

cc: @Yatekii

[Yatekii]

Nice work :)

Just 2 smaller nits. Other than that it is looking great :)

bors d=noppej

[bors]

✌️ noppej can now approve this pull request. To approve and merge a pull request, simply reply with bors r+. More detailed instructions are available here.

[noppej]

bors r+

[bors]

Build succeeded:

• Build (macos-latest)
• Build (ubuntu-latest)
• Build (windows-latest)