0.6: Selecting on connection

[mkroening]

I'm porting my use case to 0.6 and am not sure on how to make good use of the new state machine.

Specifically, I am using gdbstub to debug a KVM VCPU in uhyve. When running the VCPU, the current thread is blocked until it returns. The VCPU can be kicked out of KVM_RUN by another thread using a signal.

Currently, I kick the VCPU out of KVM_RUN every so often and check for any gdb_interrupts.

With the new state machine, I was thinking about having one thread block on the connection and kicking the VCPU out of KVM_RUN whenever a new byte is available.

Having had a look at the example, I am not sure how to do this, though. Whenever calling pump, the connection thread must already be set up, since pump might resume the target. Calling pump is not possible while having borrowed the connection, though.

What is the way to go here? Should I implement Connection for mpsc or similar to be able to split receiving and executing between two threads?

[daniel5151]

Apologies for lack of documentation in dev/0.6!

For context, the 0.6 state machine implementation was developed in response to the various needs + challenges discussed in #56. There's been a lot of churn in the API throughout development, and as such, I avoided writing documentation until the final API began to crystalize. The current API is pretty much what I expect the final 0.6 API to look like, modulo some minor tweaks I've got staged locally. Honestly, I've just been dragging my feet on sitting down and polishing things up - sorry 😅

Until those docs are written, the best way to understand how to use the state machine API would be by reading through #56, and then taking a look at https://github.com/betrusted-io/xous-core/blob/main/kernel/src/debug/gdb_server.rs, which shows off how to use the state machine API at the bare metal, with a custom Connection and everything. There are also some incomplete docs in dev/0.6 directly, which should also help fill in some gaps.

Oh, and of course, make sure to look at the in-tree https://github.com/daniel5151/gdbstub/blob/dev/0.6/examples/armv4t/main.rs

---

As for the specifics of your particular Connection implementation + integration, I'm not sure how much help I can be, as it'll entirely depend on the kind of project architecture you're working in. The idea behind the state machine API is that gdbstub no longer cares about how it receives new data, and defers that responsibility up to the person driving the gdbstub state machine loop. I explain that in the armv4t example:

                // An implementation that uses stop reasons would need to "select" on both the
                // data coming over the connection (which gets passed to `pump`) and whatever
                // mechanism it is using to detect stop events.
                //
                // The specifics of how this "select" mechanism might work will depends on where
                // `gdbstub` is being used.
                //
                // - A mpsc channel
                // - epoll/kqueue
                // - Running the target + stopping every so often to peek the connection
                // - Driving `GdbStub` from various interrupt handlers

---

I know that this has all been a bit "handwavey", and if it's not enough to go on, I might actually recommend holding off on upgrading to 0.6 until I've had the chance to update the docs + iron out any remaining API warts.

Best of luck, and let me know if you have any more questions / API suggestions!

[mkroening]

Thanks for the quick and detailed answer!

I already had a look at the examples, but wanted to avoid building a custom, fully fledged Connection between two threads. I did find a way to avoid that, though. TcpStreams can be cloned. In the wakeup thread, I block until new data is available, by reading into a slice with length zero and then kick the main thread out of simulation. To avoid kicking the main thread excessively, I wait some amount before checking the TcpStream again.

let parent_thread = pthread_self();
thread::spawn(move || {
    let kick_period = Duration::from_millis(20);
    loop {
        // Block on TCP stream without consuming any data.
        Read::read(&mut tcp_stream, &mut []).unwrap();

        // Kick VCPU out of KVM_RUN
        kick(parent_thread);

        // Wait for all inputs to be processed and for VCPU to be running again
        thread::sleep(kick_period);
    }
});

// proceed to run the state machine

That does the trick for me. That way, I can keep the logic for running the state machine quite simple and avoid implementing a byte stream between two threads.

Thanks again for your help!