Page MenuHomeFreeBSD

developers-handbook: update the section on Remote GDB
ClosedPublic

Authored by mhorne on Aug 10 2021, 11:06 PM.

Details

Summary

This is a first pass, as this section could use further improvements for
both language and content. This should at least provide enough advice to
make use of the feature on amd64.

  • Update list of required kernel options
  • Mention that the GDB backend is disabled on stable and release branches
  • Remove unneeded step (don't need to wait for kernel to trap again)
  • Update the example the console outputs
  • Some minor additions/improvements to wording

Diff Detail

Repository
R9 FreeBSD doc repository
Lint
Automatic diff as part of commit; lint not applicable.
Unit
Automatic diff as part of commit; unit tests not applicable.

Event Timeline

mhorne created this revision.
mhorne added inline comments.
documentation/content/en/books/developers-handbook/kerneldebug/_index.adoc
550

I'm not sure on the desired markup for stable and release.

608–609

I will fix this up to show msg, but this is what I got in a real session ;)

I can't speak about the actual content, but no typo, grammar nit, or awkward wording jumps out to me.

documentation/content/en/books/developers-handbook/kerneldebug/_index.adoc
550

OTOH, maybe do note that they are enabled in GENERIC on main?

601

I almost feel that the example should probably just use the sysctl instead, or perhaps the first example should just do that, and then we can add a later note that talks about toggling between the backends. Doing this would mean you don't need DDB in the kernel for your example, etc.

I'm also not sure about the ctrl-c comment, but if that's the literal output on the console that's fine.

608–609

Eh, people should get used to modern compilers not providing many variables sadly. I would keep the output you really get.

Thanks for writing this up @mhorne, much appreciated! I've left a few comments from my experience of setting it up with QEMU + KVM today and the confusion I had while reading the existing documentation, as well as the confusion that I would probably have while reading this.

I wonder if it might make sense to explicitly state that the procedure for virtualization gdb stubs may be different depending on which hypervisor/emulator is being used, and then in follow-up commits (by you or anyone else really) document the procedure for each given hypervisor?

documentation/content/en/books/developers-handbook/kerneldebug/_index.adoc
552

I'm not sure if I fully understand this -- however I can happily debug my VMs and nested VMs without ever doing it. The workflow I have is:

(1) Start the VM with a GDB stub (in QEMU, this is with -s or -gdb tcp::<port>)
(2) Do stuff in VM as normal

(3) Open up another FreeBSD machine, VM or not, copy over the kernel.debug and run:

kgdb /path/to/kernel.debug
(kgdb) target remote <ip>:<port>
(kgdb) ... 
(kgdb) continue

and what ends up happening is once my breakpoint gets hit, kgdb gets woken up and I can debug the kernel just fine.

Were I to read this while trying to set it up, I would probably end up getting confused (still am) by this sentence.

581–582

I didn't need this part for debugging VMs at least.

585–586

This is a huge improvement over the current documentation -- but I didn't need to do it for KVM.

608–609

I agree. I would leave it like this and maybe elaborate that users should expect this.

  • Change the flow of the example so that it doesn't require DDB
  • Mention that GDB is enabled in GENERIC on main
  • Add a tip about local vars and optimization levels
  • Other small wording/formatting improvements

Thanks for writing this up @mhorne, much appreciated! I've left a few comments from my experience of setting it up with QEMU + KVM today and the confusion I had while reading the existing documentation, as well as the confusion that I would probably have while reading this.

I wonder if it might make sense to explicitly state that the procedure for virtualization gdb stubs may be different depending on which hypervisor/emulator is being used, and then in follow-up commits (by you or anyone else really) document the procedure for each given hypervisor?

Right, the process for remote gdb is a little different when you are using a hypervisor, mainly because the hypervisor can pause execution automatically when it detects that a client has connected to its gdb stub. For the gdb stub implemented by the kernel, we must force a trap into the debugger in order to detect that a client has detected. That is why this chapter lists extra steps that you did not need.

I didn't come up with any text to really highlight this difference, but I think it will be easier to do once we add a separate [sub]section for remote gdb using bhyve/kvm/whatever. You can suggest specific text for the intro paragraph if you like.

Thanks for writing this up @mhorne, much appreciated! I've left a few comments from my experience of setting it up with QEMU + KVM today and the confusion I had while reading the existing documentation, as well as the confusion that I would probably have while reading this.

I wonder if it might make sense to explicitly state that the procedure for virtualization gdb stubs may be different depending on which hypervisor/emulator is being used, and then in follow-up commits (by you or anyone else really) document the procedure for each given hypervisor?

Right, the process for remote gdb is a little different when you are using a hypervisor, mainly because the hypervisor can pause execution automatically when it detects that a client has connected to its gdb stub. For the gdb stub implemented by the kernel, we must force a trap into the debugger in order to detect that a client has detected. That is why this chapter lists extra steps that you did not need.

I didn't come up with any text to really highlight this difference, but I think it will be easier to do once we add a separate [sub]section for remote gdb using bhyve/kvm/whatever. You can suggest specific text for the intro paragraph if you like.

Yes, I think we will want to add a separate section for bare-metal debugging with a hypervisor vs using serial to talk to the in-kernel stub which is what this currently documents.

This revision is now accepted and ready to land.Thu, Sep 23, 5:16 PM

Other than the one nit above, spelling, grammar, and wording still LGTM.

documentation/content/en/books/developers-handbook/kerneldebug/_index.adoc
552

Maybe mention that 'main' is the ongoing development branch if not explained elsewhere? Developers new to FreeBSD or its use of git may not know that.

ygy added a subscriber: ygy.

LGTM

In D31494#723995, @jhb wrote:

Thanks for writing this up @mhorne, much appreciated! I've left a few comments from my experience of setting it up with QEMU + KVM today and the confusion I had while reading the existing documentation, as well as the confusion that I would probably have while reading this.

I wonder if it might make sense to explicitly state that the procedure for virtualization gdb stubs may be different depending on which hypervisor/emulator is being used, and then in follow-up commits (by you or anyone else really) document the procedure for each given hypervisor?

Right, the process for remote gdb is a little different when you are using a hypervisor, mainly because the hypervisor can pause execution automatically when it detects that a client has connected to its gdb stub. For the gdb stub implemented by the kernel, we must force a trap into the debugger in order to detect that a client has detected. That is why this chapter lists extra steps that you did not need.

I didn't come up with any text to really highlight this difference, but I think it will be easier to do once we add a separate [sub]section for remote gdb using bhyve/kvm/whatever. You can suggest specific text for the intro paragraph if you like.

Yes, I think we will want to add a separate section for bare-metal debugging with a hypervisor vs using serial to talk to the in-kernel stub which is what this currently documents.

Agreed. Thanks again for writing this up @mhorne