feat: Enable gdb debugging on x86 #4797

JackThomson2 · 2024-09-12T12:54:05Z

This PR is adding GDB support into Firecracker. This is will allow us to connect GDB to the guest kernel and enable step through debugging.

This is achieved by leveraging https://github.com/daniel5151/gdbstub which allows us to debug the kernel over the GDB Remote Serial Protocol. The way this is managed is through a new GDB thread which is used to manage the interaction between the VCPUs and the GDB server.

A list of the current features supported in x86

Multithreaded Debugging (multi core VM's)
Register Read/Write
Guest Memory Read/Write
Software Breakpoints Add/Remove
Hardware Breakpoints Add/Remove
Single Step
Continue

The implementation is feature gated behind the debug flag which aims to allow us to remove all the dependencies at compiletime

Changes

Adding GDB support for guest kernel debugging
Added new debug feature to firecracker which when enabled will start the GDB server and block the boot until GDB connects and resumes the execution

Reason

Allow us to debug the guest kernel with GDB

License Acceptance

By submitting this pull request, I confirm that my contribution is made under
the terms of the Apache 2.0 license. For more information on following Developer
Certificate of Origin and signing off your commits, please check
CONTRIBUTING.md.

PR Checklist

If a specific issue led to this PR, this PR closes the issue.
The description of changes is clear and encompassing.
Any required documentation changes (code and docs) are included in this
PR.
API changes follow the Runbook for Firecracker API changes.
User-facing changes are mentioned in CHANGELOG.md.
All added/changed functionality is tested.
New TODOs link to an issue.
Commits meet
contribution quality standards.

This functionality cannot be added in rust-vmm.

codecov · 2024-09-12T13:08:11Z

Codecov Report

Attention: Patch coverage is 33.72093% with 57 lines in your changes missing coverage. Please review.

Project coverage is 83.96%. Comparing base (36ecc4f) to head (898ee9a).
Report is 3 commits behind head on main.

Files with missing lines	Patch %	Lines
src/vmm/src/gdb/arch/aarch64.rs	4.76%	40 Missing ⚠️
src/vmm/src/builder.rs	55.26%	17 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #4797      +/-   ##
==========================================
- Coverage   84.38%   83.96%   -0.43%     
==========================================
  Files         249      250       +1     
  Lines       27496    27758     +262     
==========================================
+ Hits        23203    23306     +103     
- Misses       4293     4452     +159

Flag	Coverage Δ
5.10-c5n.metal	`84.58% <61.36%> (-0.04%)`	⬇️
5.10-m5n.metal	`84.56% <61.36%> (-0.05%)`	⬇️
5.10-m6a.metal	`83.86% <61.36%> (-0.05%)`	⬇️
5.10-m6g.metal	`80.51% <33.72%> (-0.44%)`	⬇️
5.10-m6i.metal	`84.56% <61.36%> (-0.05%)`	⬇️
5.10-m7g.metal	`80.51% <33.72%> (-0.44%)`	⬇️
6.1-c5n.metal	`84.58% <61.36%> (-0.04%)`	⬇️
6.1-m5n.metal	`84.56% <61.36%> (-0.05%)`	⬇️
6.1-m6a.metal	`83.85% <61.36%> (-0.05%)`	⬇️
6.1-m6g.metal	`80.51% <33.72%> (-0.43%)`	⬇️
6.1-m6i.metal	`84.56% <61.36%> (-0.05%)`	⬇️
6.1-m7g.metal	`80.51% <33.72%> (-0.44%)`	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

src/vmm/src/vstate/vcpu/mod.rs

src/vmm/src/gdb/target.rs

ShadowCurse

Please squash 1 and 2 commits.

src/vmm/src/vstate/vcpu/mod.rs

src/vmm/src/gdb/target.rs

src/vmm/src/gdb/server.rs

docs/gdb-debugging.md

roypat

I've had a very haphazard look at it. Mostly it's just nits about Rust style things. The one thing I'd like to discuss is the passing of Tids all over the place. I outlined in a comment how we might be able to avoid this. Could you have a look at that? :o

src/vmm/src/gdb/event_loop.rs

src/vmm/src/gdb/server.rs

src/vmm/src/gdb/target.rs

src/vmm/src/gdb/hw_breakpoint_store.rs

src/vmm/src/gdb/target.rs

src/vmm/src/vstate/vcpu/mod.rs

src/vmm/src/gdb/target.rs

src/vmm/src/vstate/vcpu/mod.rs

src/vmm/src/gdb/target.rs

clicked the wrong button, sorry

src/vmm/src/gdb/target.rs

src/vmm/src/gdb/kvm_debug.rs

src/vmm/Cargo.toml

ShadowCurse

LGTM

roypat

Overall, looks good to me, good job! No concerns really, just a bunch of small things. I guess the biggest open question is how to deal with someone doing cargo build --feature gdb --target aarch64-unknown-linux-gnu. At least it should give a nice error message about that not being supported.

src/vmm/src/vstate/vcpu/mod.rs

tests/integration_tests/build/test_gdb.py

src/vmm/src/gdb/target.rs

docs/gdb-debugging.md

tests/integration_tests/build/test_gdb.py

Enabling GDB support for debugging the guest kernel. This allows us to connect a gdb server to firecracker and debug the guest. Signed-off-by: Jack Thomson <jackabt@amazon.com>

Add documentation on how to use gdb with firecracker with examples on how to use the basic functionality to debug the guest kernel Signed-off-by: Jack Thomson <jackabt@amazon.com>

Adding a test to ensure that firecracker will build with the gdb flag enabled Signed-off-by: Jack Thomson <jackabt@amazon.com>

kalyazin

doc LGTM

ShadowCurse reviewed Sep 13, 2024

View reviewed changes

JackThomson2 force-pushed the feat/gdb_server_x86 branch 4 times, most recently from ea73a87 to a496d60 Compare September 17, 2024 14:33

JackThomson2 marked this pull request as ready for review September 18, 2024 08:31

ShadowCurse reviewed Sep 20, 2024

View reviewed changes

roypat reviewed Sep 23, 2024

View reviewed changes

JackThomson2 force-pushed the feat/gdb_server_x86 branch 4 times, most recently from 49973fb to 15d5537 Compare September 26, 2024 09:14

roypat reviewed Sep 26, 2024

View reviewed changes

src/vmm/src/gdb/hw_breakpoint_store.rs Outdated Show resolved Hide resolved

src/vmm/src/gdb/target.rs Outdated Show resolved Hide resolved

roypat previously approved these changes Sep 26, 2024

View reviewed changes

JackThomson2 force-pushed the feat/gdb_server_x86 branch from 15d5537 to b006856 Compare September 30, 2024 15:31

ShadowCurse reviewed Sep 30, 2024

View reviewed changes

src/vmm/src/gdb/target.rs Outdated Show resolved Hide resolved

src/vmm/src/gdb/target.rs Outdated Show resolved Hide resolved

src/vmm/src/gdb/kvm_debug.rs Outdated Show resolved Hide resolved

JackThomson2 force-pushed the feat/gdb_server_x86 branch from b006856 to c689f40 Compare October 1, 2024 09:06

ShadowCurse reviewed Oct 1, 2024

View reviewed changes

src/vmm/Cargo.toml Outdated Show resolved Hide resolved

JackThomson2 force-pushed the feat/gdb_server_x86 branch 4 times, most recently from 5497cdc to 4b02872 Compare October 2, 2024 12:14

ShadowCurse reviewed Oct 2, 2024

View reviewed changes

roypat reviewed Oct 3, 2024

View reviewed changes

JackThomson2 force-pushed the feat/gdb_server_x86 branch 4 times, most recently from 360a6fd to 0dc3bc8 Compare October 8, 2024 12:52

kalyazin reviewed Oct 8, 2024

View reviewed changes

JackThomson2 force-pushed the feat/gdb_server_x86 branch 2 times, most recently from 964ccab to 4d022b2 Compare October 9, 2024 12:50

feat: Enable gdb debugging on x86

48003ec

Enabling GDB support for debugging the guest kernel. This allows us to connect a gdb server to firecracker and debug the guest. Signed-off-by: Jack Thomson <jackabt@amazon.com>

JackThomson2 force-pushed the feat/gdb_server_x86 branch 2 times, most recently from d9b94da to b36cfff Compare October 9, 2024 13:02

JackThomson2 added 2 commits October 9, 2024 14:30

docs: Add documentation on how to use GDB

082db60

Add documentation on how to use gdb with firecracker with examples on how to use the basic functionality to debug the guest kernel Signed-off-by: Jack Thomson <jackabt@amazon.com>

tests: Add build test for GDB

2ab155f

Adding a test to ensure that firecracker will build with the gdb flag enabled Signed-off-by: Jack Thomson <jackabt@amazon.com>

JackThomson2 force-pushed the feat/gdb_server_x86 branch from b36cfff to 2ab155f Compare October 9, 2024 14:30

kalyazin approved these changes Oct 9, 2024

View reviewed changes

ShadowCurse approved these changes Oct 9, 2024

View reviewed changes

Merge branch 'main' into feat/gdb_server_x86

898ee9a

roypat approved these changes Oct 9, 2024

View reviewed changes

JackThomson2 merged commit 32332d9 into firecracker-microvm:main Oct 10, 2024
4 of 7 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: Enable gdb debugging on x86 #4797

feat: Enable gdb debugging on x86 #4797

JackThomson2 commented Sep 12, 2024

codecov bot commented Sep 12, 2024 •

edited

Loading

ShadowCurse left a comment

roypat left a comment

ShadowCurse left a comment

roypat left a comment

kalyazin left a comment

feat: Enable gdb debugging on x86 #4797

feat: Enable gdb debugging on x86 #4797

Conversation

JackThomson2 commented Sep 12, 2024

Changes

Reason

License Acceptance

PR Checklist

codecov bot commented Sep 12, 2024 • edited Loading

Codecov Report

ShadowCurse left a comment

Choose a reason for hiding this comment

roypat left a comment

Choose a reason for hiding this comment

ShadowCurse left a comment

Choose a reason for hiding this comment

roypat left a comment

Choose a reason for hiding this comment

kalyazin left a comment

Choose a reason for hiding this comment

codecov bot commented Sep 12, 2024 •

edited

Loading