Add GDB stub and step-debug support for x86 and arm64
cover Add GDB stub and step-debug support for x86 and arm64
This series adds a built-in GDB remote stub for kvmtool on x86 and arm64, including packet handling, architecture glue, and integration into the run loop.
It also adds documentation and basic test coverage so the feature can be validated and maintained across both architectures.
vince (2):
x86: Add GDB stub and step-debug support
arm64: Add GDB stub and step-debug support
Makefile | 13 +- README | 29 + arm/aarch64/gdb.c | 744 +++++++++++ builtin-run.c | 13 +- docs/gdb-stub-architecture.md | 142 +++ docs/gdb-stub-security-notes.md | 73 ++ docs/gdb-stub-test-spec.md | 191 +++ gdb.c | 2090 +++++++++++++++++++++++++++++++ include/kvm/gdb.h | 138 ++ include/kvm/kvm-config.h | 2 + kvm-cpu.c | 9 +- term.c | 18 +- tests/Makefile | 4 + tests/boot/Makefile | 10 +- tests/gdb/Makefile | 8 + tests/gdb/test-x86-gdb-stub.py | 178 +++ x86/gdb.c | 573 +++++++++ 17 files changed, 4223 insertions(+), 12 deletions(-) create mode 100644 arm/aarch64/gdb.c create mode 100644 docs/gdb-stub-architecture.md create mode 100644 docs/gdb-stub-security-notes.md create mode 100644 docs/gdb-stub-test-spec.md create mode 100644 gdb.c create mode 100644 include/kvm/gdb.h create mode 100644 tests/gdb/Makefile create mode 100644 tests/gdb/test-x86-gdb-stub.py create mode 100644 x86/gdb.c
Signature · 1 line
2.34.1
PATCH 1/2 x86: Add GDB stub and step-debug support
Add the x86 GDB remote stub implementation and wire it into lkvm run via --gdb/--gdb-wait. This includes step-debug stability fixes, software-breakpoint state handling, protocol hardening, and an x86 smoke test workflow.
Also include user-facing GDB documentation in README and convert the architecture/test/security stub documents to English for upstream review.
--- Makefile | 13 +- README | 29 + builtin-run.c | 13 +- docs/gdb-stub-architecture.md | 142 +++ docs/gdb-stub-security-notes.md | 73 ++ docs/gdb-stub-test-spec.md | 191 ++++ gdb.c | 1819 +++++++++++++++++++++++++++++++ include/kvm/gdb.h | 138 +++ include/kvm/kvm-config.h | 2 + kvm-cpu.c | 9 +- term.c | 18 +- tests/Makefile | 4 + tests/boot/Makefile | 10 +- tests/gdb/Makefile | 8 + tests/gdb/test-x86-gdb-stub.py | 178 +++ x86/gdb.c | 573 ++++++++++ 16 files changed, 3208 insertions(+), 12 deletions(-) create mode 100644 docs/gdb-stub-architecture.md create mode 100644 docs/gdb-stub-security-notes.md create mode 100644 docs/gdb-stub-test-spec.md create mode 100644 gdb.c create mode 100644 include/kvm/gdb.h create mode 100644 tests/gdb/Makefile create mode 100644 tests/gdb/test-x86-gdb-stub.py create mode 100644 x86/gdb.c
Makefile +12 -1
@@ -131,6 +131,8 @@ endif #x86 ifeq ($(ARCH),x86) DEFINES += -DCONFIG_X86 + DEFINES += -DCONFIG_HAS_GDB_STUB + OBJS += gdb.o OBJS += hw/i8042.o OBJS += hw/serial.o OBJS += x86/boot.o
@@ -140,6 +142,7 @@ ifeq ($(ARCH),x86) OBJS += x86/irq.o OBJS += x86/kvm.o OBJS += x86/kvm-cpu.o + OBJS += x86/gdb.o OBJS += x86/mptable.o # Exclude BIOS object files from header dependencies. OTHEROBJS += x86/bios.o
@@ -188,6 +191,7 @@ endif # ARM64 ifeq ($(ARCH), arm64) DEFINES += -DCONFIG_ARM64 + OBJS += gdb.o OBJS += $(OBJS_ARM_COMMON) OBJS += arm/aarch64/arm-cpu.o OBJS += arm/aarch64/kvm-cpu.o
@@ -551,10 +555,17 @@ x86/bios/bios-rom.h: x86/bios/bios.bin.elf $(E) " NM " $@ $(Q) cd x86/bios && sh gen-offsets.sh > bios-rom.h && cd .. + +BOOT_TEST_KERNEL ?= $(firstword $(wildcard /boot/vmlinuz-$(shell uname -r) /boot/vmlinuz-* /boot/vmlinuz)) + check: all $(MAKE) -C tests ./$(PROGRAM) run tests/pit/tick.bin - ./$(PROGRAM) run -d tests/boot/boot_test.iso -p "init=init" + @if [ -n "$(BOOT_TEST_KERNEL)" ] && [ -r "$(BOOT_TEST_KERNEL)" ]; then \ + ./$(PROGRAM) run -k "$(BOOT_TEST_KERNEL)" -d tests/boot/boot_test.iso -p "init=init"; \ + else \ + echo "SKIP: boot runtime check (no readable /boot/vmlinuz* found)."; \ + fi .PHONY: check install: all
README +29 -0
@@ -88,6 +88,35 @@ or --kernel ../../arch/x86/boot/bzImage \ --network virtio +GDB remote debugging +-------------------- + +kvmtool now supports a built-in GDB stub on x86 and arm64. + +Start a guest with a GDB server on localhost port 1234: + + ./lkvm run --gdb 1234 --kernel <guest-kernel> [other options] + +To wait for GDB to attach before running guest vCPUs: + + ./lkvm run --gdb 1234 --gdb-wait --kernel <guest-kernel> [other options] + +From GDB: + + (gdb) target remote :1234 + +Recommended kernel-debug workflow: + + - Use a single vCPU for stepping-sensitive sessions: + + ./lkvm run --gdb 1234 --gdb-wait -c 1 --kernel <guest-kernel> ... + + - Use nokaslr in the guest command line for stable symbol addresses. + +Quick validation command: + + make -C tests/gdb smoke + The tool has been written by Pekka Enberg, Cyrill Gorcunov, Asias He, Sasha Levin and Prasad Joshi. Special thanks to Avi Kivity for his help on KVM internals and Ingo Molnar for all-around support and encouragement!
builtin-run.c +11 -2
@@ -33,6 +33,7 @@#include "kvm/guest_compat.h" #include "kvm/kvm-ipc.h" #include "kvm/builtin-debug.h" +#include "kvm/gdb.h" #include <linux/types.h> #include <linux/err.h>
@@ -276,6 +277,10 @@ static int loglevel_parser(const struct option *opt, const char *arg, int unset) "Enable MMIO debugging"), \OPT_INTEGER ('\0' ,"debug-iodelay" , &(cfg)->debug_iodelay, \"Delay IO by millisecond" ), \ +OPT_INTEGER ('\0' ,"gdb" , &(cfg)->gdb_port, \ +"Start GDB stub on given TCP port" ), \ +OPT_BOOLEAN ('\0' ,"gdb-wait" , &(cfg)->gdb_wait, \ +"Wait for GDB connection before starting VM" ), \ \ OPT_ARCH(RUN, cfg) \OPT_END () \
@@ -734,8 +739,12 @@ static struct kvm *kvm_cmd_run_init(int argc, const char **argv) kvm->vmlinux = kvm->cfg.vmlinux_filename; } -if (kvm->cfg.nrcpus ==0 ) - kvm->cfg.nrcpus = nr_online_cpus; +if (kvm->cfg.nrcpus ==0 ) { +if (kvm->cfg.gdb_port) + kvm->cfg.nrcpus =1 ; +else + kvm->cfg.nrcpus = nr_online_cpus; + }if (!kvm->cfg.ram_size) kvm->cfg.ram_size =get_ram_size (kvm->cfg.nrcpus);
docs/gdb-stub-architecture.md new file +142 -0
142 lines not on this page · raw message
docs/gdb-stub-security-notes.md new file +73 -0
73 lines not on this page · raw message
docs/gdb-stub-test-spec.md new file +191 -0
191 lines not on this page · raw message
gdb.c new file +1819 -0
1,819 lines not on this page · raw message
include/kvm/gdb.h new file +138 -0
138 lines not on this page · raw message
include/kvm/kvm-config.h +2 -0
@@ -54,6 +54,8 @@ struct kvm_config {const char *real_cmdline;struct virtio_net_params *net_params;bool single_step; +int gdb_port;/* GDB stub TCP port (0 = disabled) */ +bool gdb_wait;/* Wait for GDB connection before starting */ bool vnc;bool gtk;bool sdl;
kvm-cpu.c +7 -2
@@ -3,6 +3,7 @@#include "kvm/symbol.h" #include "kvm/util.h" #include "kvm/kvm.h" +#include "kvm/gdb.h" #include "kvm/virtio.h" #include "kvm/mutex.h" #include "kvm/barrier.h"
@@ -174,8 +175,12 @@ int kvm_cpu__start(struct kvm_cpu *cpu)case KVM_EXIT_UNKNOWN :break ;case KVM_EXIT_DEBUG : -kvm_cpu__show_registers (cpu); -kvm_cpu__show_code (cpu); +if (kvm_gdb__active (cpu->kvm)) { +kvm_gdb__handle_debug (cpu); + }else { +kvm_cpu__show_registers (cpu); +kvm_cpu__show_code (cpu); + }break ;case KVM_EXIT_IO : {bool ret;
term.c +16 -2
@@ -26,6 +26,11 @@ static pthread_t term_poll_thread;/* ctrl-a is used for escape */ #define term_escape_char 0x01 +static bool guest_has_started (struct kvm *kvm) +{ +return kvm->cpus && kvm->cpus[0 ] && kvm->cpus[0 ]->thread !=0 ; +} +int term_getc (struct kvm *kvm,int term) {static bool term_got_escape = false;
@@ -36,12 +41,21 @@ int term_getc(struct kvm *kvm, int term)if (term_got_escape) { term_got_escape = false; -if (c =='x' ) -kvm__reboot (kvm); +if (c =='x' ) { +if (guest_has_started (kvm)) +kvm__reboot (kvm); +else +raise (SIGTERM ); + }if (c == term_escape_char)return c; } +if (c ==0x03 && !guest_has_started (kvm)) { +raise (SIGTERM ); +return -1 ; + } +if (c == term_escape_char) { term_got_escape = true;return -1 ;
tests/Makefile +4 -0
@@ -12,6 +12,10 @@ boot: $(MAKE) -C boot .PHONY: boot +gdb: + $(MAKE) -C gdb smoke +.PHONY: gdb + clean: $(MAKE) -C kernel clean $(MAKE) -C pit clean
tests/boot/Makefile +5 -5
@@ -1,17 +1,17 @@ NAME := init OBJ := $(NAME).o -MKISOFS := $(shell which mkisofs) -ifndef MKISOFS -MKISOFS := $(shell which xorrisofs) +MKISOFS := $(shell command -v mkisofs 2>/dev/null) +ifeq ($(MKISOFS),) +MKISOFS := $(shell command -v xorrisofs 2>/dev/null) endif -all: $(.o) +all: $(OBJ) rm -rf rootfs mkdir rootfs gcc -static init.c -o rootfs/init ifdef MKISOFS - $(MKISOFS) rootfs -o boot_test.iso + $(MKISOFS) -o boot_test.iso rootfs else $(error "mkisofs or xorriso needed to build boot_test.iso") endif
tests/gdb/Makefile new file +8 -0
@@ -0,0 +1,8 @@ +PORT ?= 12345 +LKVM ?= ../../lkvm +GUEST ?= ../pit/tick.bin +PYTHON ?= python3 + +smoke: $(LKVM) $(GUEST) + $(PYTHON) test-x86-gdb-stub.py --lkvm $(LKVM) --guest $(GUEST) --port $(PORT) +.PHONY: smoke
tests/gdb/test-x86-gdb-stub.py new file +178 -0
178 lines not on this page · raw message
x86/gdb.c new file +573 -0
250 lines not on this page · raw message
The rest of this diff is not shown. View the raw message.
Signature · 1 line
2.34.1
Part of the diff is not shown here. View the raw message.
PATCH 2/2 arm64: Add GDB stub and step-debug support
In reply to vinceAdd the arm64 architecture backend for the built-in GDB stub, including register mapping, software/hardware breakpoint handling, and step-debug resume behavior suitable for kernel debugging paths.
The generic protocol layer remains shared with x86, while arm64-specific state transitions and debug controls are implemented in arm/aarch64 code.
--- Makefile | 2 +- arm/aarch64/gdb.c | 744 ++++++++++++++++++++++++++++++++++++++++++++++ gdb.c | 323 ++++++++++++++++++-- include/kvm/gdb.h | 2 +- 4 files changed, 1043 insertions(+), 28 deletions(-) create mode 100644 arm/aarch64/gdb.c
Makefile +1 -1
@@ -131,7 +131,6 @@ endif #x86 ifeq ($(ARCH),x86) DEFINES += -DCONFIG_X86 - DEFINES += -DCONFIG_HAS_GDB_STUB OBJS += gdb.o OBJS += hw/i8042.o OBJS += hw/serial.o
@@ -198,6 +197,7 @@ ifeq ($(ARCH), arm64) OBJS += arm/aarch64/kvm.o OBJS += arm/aarch64/pvtime.o OBJS += arm/aarch64/pmu.o + OBJS += arm/aarch64/gdb.o ARCH_INCLUDE := $(HDRS_ARM_COMMON) ARCH_INCLUDE += -Iarm/aarch64/include
arm/aarch64/gdb.c new file +744 -0
744 lines not on this page · raw message
gdb.c +297 -26
423 lines not on this page · raw message
include/kvm/gdb.h +1 -1
@@ -16,7 +16,7 @@ struct kvm_gdb_hw_bp {bool active; }; -#ifdef CONFIG_HAS_GDB_STUB +#if defined(CONFIG_X86 ) || defined(CONFIG_ARM64 )/* * Public GDB stub API
Signature · 1 line
2.34.1
Re: [PATCH 2/2] arm64: Add GDB stub and step-debug support
Hi Vince,
I haven't given this a detailed review but I have a question on the insertion of software breakpoints.
Quoted 10 lines · vince
Add the arm64 architecture backend for the built-in GDB stub, including register mapping, software/hardware breakpoint handling, and step-debug resume behavior suitable for kernel debugging paths.
The generic protocol layer remains shared with x86, while arm64-specific state transitions and debug controls are implemented in arm/aarch64 code.
Signed-off-by vince <[email protected]>---
[...]
Quoted 5 lines
arm/aarch64/gdb.c new file +0
-0
[...]
Quoted 6 lines
arm/aarch64/gdb.c new file +0
-2@@ -704,21 +974,20 @@ static int sw_bp_insert(u64 addr, int len)if (gdb.sw_bp[i].refs >0 )continue ; -u8 orig; -if (!gdb_read_guest_mem (addr, &orig,1 )) {
arm/aarch64/gdb.c static int sw_bp_insert(u64 addr, int len) · line 984
Quoted 10 lines
arm/aarch64/gdb.c new file +4
-2+if (!gdb_read_guest_mem (addr, gdb.sw_bp[i].orig_bytes, +GDB_SW_BP_INSN_LEN )) {pr_warning ("GDB: sw_bp_insert read failed at GVA 0x%llx" , (unsigned long long )addr);return -1 ; } -u8 brk =GDB_SW_BP_INSN ; -if (!gdb_write_guest_mem (addr, &brk,1 )) { +if (!gdb_write_guest_mem (addr,GDB_SW_BP_INSN , +GDB_SW_BP_INSN_LEN )) {
How do we make sure the guest instruction fetch sees the software breakpoint?
Do we need a dsb and cache maintenance operations to flush to the point of coherence and invalidate the icache?
Thanks,
Ben
Quoted 10 lines
arm/aarch64/gdb.c new file +0
-1pr_warning ("GDB: sw_bp_insert write failed at GVA 0x%llx" , (unsigned long long )addr);return -1 ; } gdb.sw_bp[i].addr = addr; - gdb.sw_bp[i].orig_byte = orig; gdb.sw_bp[i].refs =1 ; gdb.sw_bp[i].active = true;return 0 ;
Re: [PATCH kvmtool 2/2] arm64: Add GDB stub and step-debug support
Hi Ryan,
Thanks, this is a good point.
On arm64, simply patching guest memory with a BRK instruction is not by itself enough to guarantee that a later guest instruction fetch will observe the new instruction. This is different from x86, where software breakpoint patching is generally sufficient without extra instruction-cache maintenance.
I checked QEMU's KVM path as well. While its software breakpoint handling also patches guest memory directly, I did not find an explicit cache maintenance sequence in the userspace insertion/removal path.
To make kvmtool's arm64 software breakpoint path more robust, I updated the implementation so that instruction patches (both inserting the BRK and restoring the original instruction when stepping over it) go through a dedicated guest-instruction write path, and arm64 now performs instruction cache synchronization for those patched bytes.
I have tested this locally and it works as expected.
I'll include this in the next version.
Thanks,
vince
Hi,
Gentle ping for this series.
The series adds built-in GDB remote stub and step-debug support for kvmtool on x86 and arm64, plus documentation and a basic x86 smoke test.
I'd appreciate any comments or review feedback when time permits.
Thanks,
vince
v2 cover Add GDB stub and step-debug support for x86 and arm64
In reply to vinceThis series adds a built-in GDB remote stub for kvmtool on x86 and arm64, including packet handling, architecture glue, and integration into the run loop.
It also adds basic documentation and test coverage so the feature can be validated and maintained across both architectures.
Changes in v2:
- address review comments on the arm64 software breakpoint instruction visibility path
- split guest memory writes from guest instruction patching in the GDB stub
- synchronize arm64 guest instruction patches when inserting, removing, and stepping over software breakpoints
- drop the test-spec and security-notes documents to keep the series focused
vince (2):
x86: Add GDB stub and step-debug support
arm64: Add GDB stub and step-debug support
Makefile | 13 +- README | 29 + arm/aarch64/gdb.c | 752 ++++++++++++ builtin-run.c | 13 +- docs/gdb-stub-architecture.md | 142 +++ gdb.c | 2104 ++++++++++++++++++++++++++++++++ include/kvm/gdb.h | 148 +++ include/kvm/kvm-config.h | 2 + kvm-cpu.c | 9 +- term.c | 18 +- tests/Makefile | 4 + tests/boot/Makefile | 10 +- tests/gdb/Makefile | 8 + tests/gdb/test-x86-gdb-stub.py | 178 +++ x86/gdb.c | 577 +++++++++ 15 files changed, 3995 insertions(+), 12 deletions(-) create mode 100644 arm/aarch64/gdb.c create mode 100644 docs/gdb-stub-architecture.md create mode 100644 gdb.c create mode 100644 include/kvm/gdb.h create mode 100644 tests/gdb/Makefile create mode 100644 tests/gdb/test-x86-gdb-stub.py create mode 100644 x86/gdb.c
Signature · 1 line
2.34.1
PATCH v2 1/2 x86: Add GDB stub and step-debug support
--- Makefile | 13 +- README | 29 + builtin-run.c | 13 +- docs/gdb-stub-architecture.md | 142 +++ gdb.c | 1819 ++++++++++++++++++++++++++++++++ include/kvm/gdb.h | 138 +++ include/kvm/kvm-config.h | 2 + kvm-cpu.c | 9 +- term.c | 18 +- tests/Makefile | 4 + tests/boot/Makefile | 10 +- tests/gdb/Makefile | 8 + tests/gdb/test-x86-gdb-stub.py | 178 ++++ x86/gdb.c | 573 ++++++++++ 14 files changed, 2944 insertions(+), 12 deletions(-) create mode 100644 docs/gdb-stub-architecture.md create mode 100644 gdb.c create mode 100644 include/kvm/gdb.h create mode 100644 tests/gdb/Makefile create mode 100644 tests/gdb/test-x86-gdb-stub.py create mode 100644 x86/gdb.c
Makefile +12 -1
@@ -131,6 +131,8 @@ endif #x86 ifeq ($(ARCH),x86) DEFINES += -DCONFIG_X86 + DEFINES += -DCONFIG_HAS_GDB_STUB + OBJS += gdb.o OBJS += hw/i8042.o OBJS += hw/serial.o OBJS += x86/boot.o
@@ -140,6 +142,7 @@ ifeq ($(ARCH),x86) OBJS += x86/irq.o OBJS += x86/kvm.o OBJS += x86/kvm-cpu.o + OBJS += x86/gdb.o OBJS += x86/mptable.o # Exclude BIOS object files from header dependencies. OTHEROBJS += x86/bios.o
@@ -188,6 +191,7 @@ endif # ARM64 ifeq ($(ARCH), arm64) DEFINES += -DCONFIG_ARM64 + OBJS += gdb.o OBJS += $(OBJS_ARM_COMMON) OBJS += arm/aarch64/arm-cpu.o OBJS += arm/aarch64/kvm-cpu.o
@@ -551,10 +555,17 @@ x86/bios/bios-rom.h: x86/bios/bios.bin.elf $(E) " NM " $@ $(Q) cd x86/bios && sh gen-offsets.sh > bios-rom.h && cd .. + +BOOT_TEST_KERNEL ?= $(firstword $(wildcard /boot/vmlinuz-$(shell uname -r) /boot/vmlinuz-* /boot/vmlinuz)) + check: all $(MAKE) -C tests ./$(PROGRAM) run tests/pit/tick.bin - ./$(PROGRAM) run -d tests/boot/boot_test.iso -p "init=init" + @if [ -n "$(BOOT_TEST_KERNEL)" ] && [ -r "$(BOOT_TEST_KERNEL)" ]; then \ + ./$(PROGRAM) run -k "$(BOOT_TEST_KERNEL)" -d tests/boot/boot_test.iso -p "init=init"; \ + else \ + echo "SKIP: boot runtime check (no readable /boot/vmlinuz* found)."; \ + fi .PHONY: check install: all
README +29 -0
@@ -88,6 +88,35 @@ or --kernel ../../arch/x86/boot/bzImage \ --network virtio +GDB remote debugging +-------------------- + +kvmtool now supports a built-in GDB stub on x86 and arm64. + +Start a guest with a GDB server on localhost port 1234: + + ./lkvm run --gdb 1234 --kernel <guest-kernel> [other options] + +To wait for GDB to attach before running guest vCPUs: + + ./lkvm run --gdb 1234 --gdb-wait --kernel <guest-kernel> [other options] + +From GDB: + + (gdb) target remote :1234 + +Recommended kernel-debug workflow: + + - Use a single vCPU for stepping-sensitive sessions: + + ./lkvm run --gdb 1234 --gdb-wait -c 1 --kernel <guest-kernel> ... + + - Use nokaslr in the guest command line for stable symbol addresses. + +Quick validation command: + + make -C tests/gdb smoke + The tool has been written by Pekka Enberg, Cyrill Gorcunov, Asias He, Sasha Levin and Prasad Joshi. Special thanks to Avi Kivity for his help on KVM internals and Ingo Molnar for all-around support and encouragement!
builtin-run.c +11 -2
@@ -33,6 +33,7 @@#include "kvm/guest_compat.h" #include "kvm/kvm-ipc.h" #include "kvm/builtin-debug.h" +#include "kvm/gdb.h" #include <linux/types.h> #include <linux/err.h>
@@ -276,6 +277,10 @@ static int loglevel_parser(const struct option *opt, const char *arg, int unset) "Enable MMIO debugging"), \OPT_INTEGER ('\0' ,"debug-iodelay" , &(cfg)->debug_iodelay, \"Delay IO by millisecond" ), \ +OPT_INTEGER ('\0' ,"gdb" , &(cfg)->gdb_port, \ +"Start GDB stub on given TCP port" ), \ +OPT_BOOLEAN ('\0' ,"gdb-wait" , &(cfg)->gdb_wait, \ +"Wait for GDB connection before starting VM" ), \ \ OPT_ARCH(RUN, cfg) \OPT_END () \
@@ -734,8 +739,12 @@ static struct kvm *kvm_cmd_run_init(int argc, const char **argv) kvm->vmlinux = kvm->cfg.vmlinux_filename; } -if (kvm->cfg.nrcpus ==0 ) - kvm->cfg.nrcpus = nr_online_cpus; +if (kvm->cfg.nrcpus ==0 ) { +if (kvm->cfg.gdb_port) + kvm->cfg.nrcpus =1 ; +else + kvm->cfg.nrcpus = nr_online_cpus; + }if (!kvm->cfg.ram_size) kvm->cfg.ram_size =get_ram_size (kvm->cfg.nrcpus);
docs/gdb-stub-architecture.md new file +142 -0
142 lines not on this page · raw message
gdb.c new file +1819 -0
1,819 lines not on this page · raw message
include/kvm/gdb.h new file +138 -0
138 lines not on this page · raw message
include/kvm/kvm-config.h +2 -0
@@ -54,6 +54,8 @@ struct kvm_config {const char *real_cmdline;struct virtio_net_params *net_params;bool single_step; +int gdb_port;/* GDB stub TCP port (0 = disabled) */ +bool gdb_wait;/* Wait for GDB connection before starting */ bool vnc;bool gtk;bool sdl;
kvm-cpu.c +7 -2
@@ -3,6 +3,7 @@#include "kvm/symbol.h" #include "kvm/util.h" #include "kvm/kvm.h" +#include "kvm/gdb.h" #include "kvm/virtio.h" #include "kvm/mutex.h" #include "kvm/barrier.h"
@@ -174,8 +175,12 @@ int kvm_cpu__start(struct kvm_cpu *cpu)case KVM_EXIT_UNKNOWN :break ;case KVM_EXIT_DEBUG : -kvm_cpu__show_registers (cpu); -kvm_cpu__show_code (cpu); +if (kvm_gdb__active (cpu->kvm)) { +kvm_gdb__handle_debug (cpu); + }else { +kvm_cpu__show_registers (cpu); +kvm_cpu__show_code (cpu); + }break ;case KVM_EXIT_IO : {bool ret;
term.c +16 -2
@@ -26,6 +26,11 @@ static pthread_t term_poll_thread;/* ctrl-a is used for escape */ #define term_escape_char 0x01 +static bool guest_has_started (struct kvm *kvm) +{ +return kvm->cpus && kvm->cpus[0 ] && kvm->cpus[0 ]->thread !=0 ; +} +int term_getc (struct kvm *kvm,int term) {static bool term_got_escape = false;
@@ -36,12 +41,21 @@ int term_getc(struct kvm *kvm, int term)if (term_got_escape) { term_got_escape = false; -if (c =='x' ) -kvm__reboot (kvm); +if (c =='x' ) { +if (guest_has_started (kvm)) +kvm__reboot (kvm); +else +raise (SIGTERM ); + }if (c == term_escape_char)return c; } +if (c ==0x03 && !guest_has_started (kvm)) { +raise (SIGTERM ); +return -1 ; + } +if (c == term_escape_char) { term_got_escape = true;return -1 ;
tests/Makefile +4 -0
@@ -12,6 +12,10 @@ boot: $(MAKE) -C boot .PHONY: boot +gdb: + $(MAKE) -C gdb smoke +.PHONY: gdb + clean: $(MAKE) -C kernel clean $(MAKE) -C pit clean
tests/boot/Makefile +5 -5
@@ -1,17 +1,17 @@ NAME := init OBJ := $(NAME).o -MKISOFS := $(shell which mkisofs) -ifndef MKISOFS -MKISOFS := $(shell which xorrisofs) +MKISOFS := $(shell command -v mkisofs 2>/dev/null) +ifeq ($(MKISOFS),) +MKISOFS := $(shell command -v xorrisofs 2>/dev/null) endif -all: $(.o) +all: $(OBJ) rm -rf rootfs mkdir rootfs gcc -static init.c -o rootfs/init ifdef MKISOFS - $(MKISOFS) rootfs -o boot_test.iso + $(MKISOFS) -o boot_test.iso rootfs else $(error "mkisofs or xorriso needed to build boot_test.iso") endif
tests/gdb/Makefile new file +8 -0
@@ -0,0 +1,8 @@ +PORT ?= 12345 +LKVM ?= ../../lkvm +GUEST ?= ../pit/tick.bin +PYTHON ?= python3 + +smoke: $(LKVM) $(GUEST) + $(PYTHON) test-x86-gdb-stub.py --lkvm $(LKVM) --guest $(GUEST) --port $(PORT) +.PHONY: smoke
tests/gdb/test-x86-gdb-stub.py new file +178 -0
178 lines not on this page · raw message
x86/gdb.c new file +573 -0
514 lines not on this page · raw message
The rest of this diff is not shown. View the raw message.
Signature · 1 line
2.34.1
Part of the diff is not shown here. View the raw message.
PATCH v2 2/2 arm64: Add GDB stub and step-debug support
In reply to vinceChanges in v2:
- add a dedicated guest-instruction write path for software breakpoint patching
- synchronize arm64 instruction patches when inserting, removing, and stepping over software breakpoints
--- Makefile | 2 +- arm/aarch64/gdb.c | 752 ++++++++++++++++++++++++++++++++++++++++++++++ gdb.c | 345 +++++++++++++++++++-- include/kvm/gdb.h | 12 +- x86/gdb.c | 4 + 5 files changed, 1083 insertions(+), 32 deletions(-) create mode 100644 arm/aarch64/gdb.c
Makefile +1 -1
@@ -131,7 +131,6 @@ endif #x86 ifeq ($(ARCH),x86) DEFINES += -DCONFIG_X86 - DEFINES += -DCONFIG_HAS_GDB_STUB OBJS += gdb.o OBJS += hw/i8042.o OBJS += hw/serial.o
@@ -198,6 +197,7 @@ ifeq ($(ARCH), arm64) OBJS += arm/aarch64/kvm.o OBJS += arm/aarch64/pvtime.o OBJS += arm/aarch64/pmu.o + OBJS += arm/aarch64/gdb.o ARCH_INCLUDE := $(HDRS_ARM_COMMON) ARCH_INCLUDE += -Iarm/aarch64/include
arm/aarch64/gdb.c new file +752 -0
752 lines not on this page · raw message
gdb.c +315 -30
468 lines not on this page · raw message
include/kvm/gdb.h +11 -1
@@ -16,7 +16,7 @@ struct kvm_gdb_hw_bp {bool active; }; -#ifdef CONFIG_HAS_GDB_STUB +#if defined(CONFIG_X86 ) || defined(CONFIG_ARM64 )/* * Public GDB stub API
@@ -90,6 +90,12 @@ size_t kvm_gdb__arch_reg_pkt_size(void);/* GDB signal number to report on stop (SIGTRAP=5) */ int kvm_gdb__arch_signal (struct kvm_cpu *vcpu); +/* +* Make a guest instruction patch visible to later instruction fetches. +* host points at the host virtual address backing the patched guest bytes. +*/ +void kvm_gdb__arch_sync_guest_insn (void *host,size_t len); +/* * Returns true if the KVM_EXIT_DEBUG exit was caused by a software * breakpoint (INT3 / #BP exception), as opposed to a hardware debug
@@ -133,6 +139,10 @@ static inline bool kvm_gdb__active(struct kvm *kvm)return false; } +static inline void kvm_gdb__arch_sync_guest_insn (void *host,size_t len) +{ +} +#endif #endif /* KVM__GDB_H */
x86/gdb.c +4 -0
@@ -107,6 +107,10 @@ size_t kvm_gdb__arch_reg_pkt_size(void)return GDB_REGS_SIZE ; } +void kvm_gdb__arch_sync_guest_insn (void *host,size_t len) +{ +} +/* ------------------------------------------------------------------ */ /* Helpers: read/write KVM register structures */ /* ------------------------------------------------------------------ */
Signature · 1 line
2.34.1
v3 cover Add GDB remote debug stub for x86 and arm64
In reply to vinceThis series adds a GDB Remote Serial Protocol (RSP) stub to kvmtool, enabling source-level debugging of guest kernels via gdb target remote.
Supported features:
- Software breakpoints (INT3 / BRK #0) with guest memory read/write
- Hardware breakpoints via DR7 (x86) / KVM_SET_GUEST_DEBUG (arm64)
- Single-step via RFLAGS.TF (x86) / PSTATE.SS (arm64)
- General-purpose and system register access
- ARM64 virtual-to-physical address translation (TTBR1 page-table walk)
- I-cache coherency after SW breakpoint patching (arm64)
Usage:
lkvm run --gdb 1234 --gdb-wait ...
(gdb) target remote :1234
Changes in v3:
- x86/gdb.c: Fix all C89 violations (mixed declarations, for-init)
- x86/gdb.c: Add empty kvm_gdb__arch_sync_guest_insn() (x86 coherent)
- gdb.c: Fix wrong PHYS_OFFSET comment (0x40000000 -> 0x80000000)
- gdb.c: Fix C89 violations in arm64_sw_walk_ttbr1()
- gdb.c: Fix gdb_disable_debug() to issue KVM_SET_GUEST_DEBUG(control=0)
- gdb.c: Add 'M' packet payload length validation
- gdb.c: Refactor gdb_write_guest_mem() to pass sync_icache flag
- arm/aarch64/gdb.c: Remove unused macros (BRK0_INSN, ESR_EC_*)
- arm/aarch64/gdb.c: Fix uninitialized pc in kvm_gdb__arch_reinject_sw_bp()
- All files: Replace non-ASCII Unicode characters with ASCII equivalents
- Drop gdb-stub-security-notes.md and gdb-stub-test-spec.md from the series
vince (3):
x86: Add GDB stub and step-debug support
arm64: Add GDB stub and step-debug support
arm64: Sync guest instruction patches for GDB breakpoints
Makefile | 13 +- README | 29 + arm/aarch64/gdb.c | 753 +++++++++++ builtin-run.c | 13 +- docs/gdb-stub-architecture.md | 142 ++ gdb.c | 2225 ++++++++++++++++++++++++++++++++ include/kvm/gdb.h | 148 +++ include/kvm/kvm-config.h | 2 + kvm-cpu.c | 9 +- term.c | 18 +- tests/Makefile | 4 + tests/boot/Makefile | 10 +- tests/gdb/Makefile | 8 + tests/gdb/test-x86-gdb-stub.py | 178 +++ x86/gdb.c | 582 +++++++++ 15 files changed, 4122 insertions(+), 12 deletions(-) create mode 100644 arm/aarch64/gdb.c create mode 100644 docs/gdb-stub-architecture.md create mode 100644 gdb.c create mode 100644 include/kvm/gdb.h create mode 100644 tests/gdb/Makefile create mode 100644 tests/gdb/test-x86-gdb-stub.py create mode 100644 x86/gdb.c
Signature · 1 line
2.34.1
PATCH v3 1/3 x86: Add GDB stub and step-debug support
Add the x86 GDB remote stub implementation and wire it into lkvm run via --gdb/--gdb-wait. This includes step-debug stability fixes, software-breakpoint state handling, protocol hardening, and an x86 smoke test workflow.
Also include user-facing GDB documentation in README and convert the architecture/test/security stub documents to English for upstream review.
gdb, x86: Fix post-review issues in GDB stub
- gdb.c: fix gdb_disable_debug() to actually clear KVM debug state. The previous implementation called kvm_gdb__arch_set_debug(vcpu, false, NULL) which still set KVM_GUESTDBG_ENABLE|USE_SW_BP, leaving the VM taking KVM_EXIT_DEBUG after GDB disconnects. Issue a direct KVM_SET_GUEST_DEBUG with control=0 to fully disable interception.
- gdb.c: validate 'M' packet payload length before calling hex_to_bin(). A malformed packet with a claimed len larger than the actual hex data in the packet could cause hex_to_bin() to read past the packet buffer and write unintended bytes into guest memory. Reject packets where the remaining packet bytes are fewer than len*2.
- gdb.c, x86/gdb.c: fix C89 style violations throughout. Linux kernel style requires all variable declarations at the top of their block, before any statements. Replace all for (int i = ...) loop initialisers with a pre-declared loop variable, and hoist all mixed declarations to the start of their enclosing block.
--- Makefile | 13 +- README | 29 + builtin-run.c | 13 +- docs/gdb-stub-architecture.md | 142 ++ gdb.c | 2225 ++++++++++++++++++++++++++++++++ include/kvm/gdb.h | 138 ++ include/kvm/kvm-config.h | 2 + kvm-cpu.c | 9 +- term.c | 18 +- tests/Makefile | 4 + tests/boot/Makefile | 10 +- tests/gdb/Makefile | 8 + tests/gdb/test-x86-gdb-stub.py | 178 +++ x86/gdb.c | 578 +++++++++ 14 files changed, 3355 insertions(+), 12 deletions(-) create mode 100644 docs/gdb-stub-architecture.md create mode 100644 gdb.c create mode 100644 include/kvm/gdb.h create mode 100644 tests/gdb/Makefile create mode 100644 tests/gdb/test-x86-gdb-stub.py create mode 100644 x86/gdb.c
Makefile +12 -1
@@ -131,6 +131,8 @@ endif #x86 ifeq ($(ARCH),x86) DEFINES += -DCONFIG_X86 + DEFINES += -DCONFIG_HAS_GDB_STUB + OBJS += gdb.o OBJS += hw/i8042.o OBJS += hw/serial.o OBJS += x86/boot.o
@@ -140,6 +142,7 @@ ifeq ($(ARCH),x86) OBJS += x86/irq.o OBJS += x86/kvm.o OBJS += x86/kvm-cpu.o + OBJS += x86/gdb.o OBJS += x86/mptable.o # Exclude BIOS object files from header dependencies. OTHEROBJS += x86/bios.o
@@ -188,6 +191,7 @@ endif # ARM64 ifeq ($(ARCH), arm64) DEFINES += -DCONFIG_ARM64 + OBJS += gdb.o OBJS += $(OBJS_ARM_COMMON) OBJS += arm/aarch64/arm-cpu.o OBJS += arm/aarch64/kvm-cpu.o
@@ -551,10 +555,17 @@ x86/bios/bios-rom.h: x86/bios/bios.bin.elf $(E) " NM " $@ $(Q) cd x86/bios && sh gen-offsets.sh > bios-rom.h && cd .. + +BOOT_TEST_KERNEL ?= $(firstword $(wildcard /boot/vmlinuz-$(shell uname -r) /boot/vmlinuz-* /boot/vmlinuz)) + check: all $(MAKE) -C tests ./$(PROGRAM) run tests/pit/tick.bin - ./$(PROGRAM) run -d tests/boot/boot_test.iso -p "init=init" + @if [ -n "$(BOOT_TEST_KERNEL)" ] && [ -r "$(BOOT_TEST_KERNEL)" ]; then \ + ./$(PROGRAM) run -k "$(BOOT_TEST_KERNEL)" -d tests/boot/boot_test.iso -p "init=init"; \ + else \ + echo "SKIP: boot runtime check (no readable /boot/vmlinuz* found)."; \ + fi .PHONY: check install: all
README +29 -0
@@ -88,6 +88,35 @@ or --kernel ../../arch/x86/boot/bzImage \ --network virtio +GDB remote debugging +-------------------- + +kvmtool now supports a built-in GDB stub on x86 and arm64. + +Start a guest with a GDB server on localhost port 1234: + + ./lkvm run --gdb 1234 --kernel <guest-kernel> [other options] + +To wait for GDB to attach before running guest vCPUs: + + ./lkvm run --gdb 1234 --gdb-wait --kernel <guest-kernel> [other options] + +From GDB: + + (gdb) target remote :1234 + +Recommended kernel-debug workflow: + + - Use a single vCPU for stepping-sensitive sessions: + + ./lkvm run --gdb 1234 --gdb-wait -c 1 --kernel <guest-kernel> ... + + - Use nokaslr in the guest command line for stable symbol addresses. + +Quick validation command: + + make -C tests/gdb smoke + The tool has been written by Pekka Enberg, Cyrill Gorcunov, Asias He, Sasha Levin and Prasad Joshi. Special thanks to Avi Kivity for his help on KVM internals and Ingo Molnar for all-around support and encouragement!
builtin-run.c +11 -2
@@ -33,6 +33,7 @@#include "kvm/guest_compat.h" #include "kvm/kvm-ipc.h" #include "kvm/builtin-debug.h" +#include "kvm/gdb.h" #include <linux/types.h> #include <linux/err.h>
@@ -276,6 +277,10 @@ static int loglevel_parser(const struct option *opt, const char *arg, int unset) "Enable MMIO debugging"), \OPT_INTEGER ('\0' ,"debug-iodelay" , &(cfg)->debug_iodelay, \"Delay IO by millisecond" ), \ +OPT_INTEGER ('\0' ,"gdb" , &(cfg)->gdb_port, \ +"Start GDB stub on given TCP port" ), \ +OPT_BOOLEAN ('\0' ,"gdb-wait" , &(cfg)->gdb_wait, \ +"Wait for GDB connection before starting VM" ), \ \ OPT_ARCH(RUN, cfg) \OPT_END () \
@@ -734,8 +739,12 @@ static struct kvm *kvm_cmd_run_init(int argc, const char **argv) kvm->vmlinux = kvm->cfg.vmlinux_filename; } -if (kvm->cfg.nrcpus ==0 ) - kvm->cfg.nrcpus = nr_online_cpus; +if (kvm->cfg.nrcpus ==0 ) { +if (kvm->cfg.gdb_port) + kvm->cfg.nrcpus =1 ; +else + kvm->cfg.nrcpus = nr_online_cpus; + }if (!kvm->cfg.ram_size) kvm->cfg.ram_size =get_ram_size (kvm->cfg.nrcpus);
docs/gdb-stub-architecture.md new file +142 -0
142 lines not on this page · raw message
gdb.c new file +2225 -0
2,225 lines not on this page · raw message
include/kvm/gdb.h new file +138 -0
138 lines not on this page · raw message
include/kvm/kvm-config.h +2 -0
@@ -54,6 +54,8 @@ struct kvm_config {const char *real_cmdline;struct virtio_net_params *net_params;bool single_step; +int gdb_port;/* GDB stub TCP port (0 = disabled) */ +bool gdb_wait;/* Wait for GDB connection before starting */ bool vnc;bool gtk;bool sdl;
kvm-cpu.c +7 -2
@@ -3,6 +3,7 @@#include "kvm/symbol.h" #include "kvm/util.h" #include "kvm/kvm.h" +#include "kvm/gdb.h" #include "kvm/virtio.h" #include "kvm/mutex.h" #include "kvm/barrier.h"
@@ -174,8 +175,12 @@ int kvm_cpu__start(struct kvm_cpu *cpu)case KVM_EXIT_UNKNOWN :break ;case KVM_EXIT_DEBUG : -kvm_cpu__show_registers (cpu); -kvm_cpu__show_code (cpu); +if (kvm_gdb__active (cpu->kvm)) { +kvm_gdb__handle_debug (cpu); + }else { +kvm_cpu__show_registers (cpu); +kvm_cpu__show_code (cpu); + }break ;case KVM_EXIT_IO : {bool ret;
term.c +16 -2
@@ -26,6 +26,11 @@ static pthread_t term_poll_thread;/* ctrl-a is used for escape */ #define term_escape_char 0x01 +static bool guest_has_started (struct kvm *kvm) +{ +return kvm->cpus && kvm->cpus[0 ] && kvm->cpus[0 ]->thread !=0 ; +} +int term_getc (struct kvm *kvm,int term) {static bool term_got_escape = false;
@@ -36,12 +41,21 @@ int term_getc(struct kvm *kvm, int term)if (term_got_escape) { term_got_escape = false; -if (c =='x' ) -kvm__reboot (kvm); +if (c =='x' ) { +if (guest_has_started (kvm)) +kvm__reboot (kvm); +else +raise (SIGTERM ); + }if (c == term_escape_char)return c; } +if (c ==0x03 && !guest_has_started (kvm)) { +raise (SIGTERM ); +return -1 ; + } +if (c == term_escape_char) { term_got_escape = true;return -1 ;
tests/Makefile +4 -0
@@ -12,6 +12,10 @@ boot: $(MAKE) -C boot .PHONY: boot +gdb: + $(MAKE) -C gdb smoke +.PHONY: gdb + clean: $(MAKE) -C kernel clean $(MAKE) -C pit clean
tests/boot/Makefile +5 -5
@@ -1,17 +1,17 @@ NAME := init OBJ := $(NAME).o -MKISOFS := $(shell which mkisofs) -ifndef MKISOFS -MKISOFS := $(shell which xorrisofs) +MKISOFS := $(shell command -v mkisofs 2>/dev/null) +ifeq ($(MKISOFS),) +MKISOFS := $(shell command -v xorrisofs 2>/dev/null) endif -all: $(.o) +all: $(OBJ) rm -rf rootfs mkdir rootfs gcc -static init.c -o rootfs/init ifdef MKISOFS - $(MKISOFS) rootfs -o boot_test.iso + $(MKISOFS) -o boot_test.iso rootfs else $(error "mkisofs or xorriso needed to build boot_test.iso") endif
tests/gdb/Makefile new file +8 -0
@@ -0,0 +1,8 @@ +PORT ?= 12345 +LKVM ?= ../../lkvm +GUEST ?= ../pit/tick.bin +PYTHON ?= python3 + +smoke: $(LKVM) $(GUEST) + $(PYTHON) test-x86-gdb-stub.py --lkvm $(LKVM) --guest $(GUEST) --port $(PORT) +.PHONY: smoke
tests/gdb/test-x86-gdb-stub.py new file +178 -0
178 lines not on this page · raw message
x86/gdb.c new file +578 -0
108 lines not on this page · raw message
The rest of this diff is not shown. View the raw message.
Signature · 1 line
2.34.1
Part of the diff is not shown here. View the raw message.
PATCH v3 2/3 arm64: Add GDB stub and step-debug support
Add the arm64 architecture backend for the built-in GDB stub, including register mapping, software/hardware breakpoint handling, and step-debug resume behavior suitable for kernel debugging paths.
The generic protocol layer remains shared with x86, while arm64-specific state transitions and debug controls are implemented in arm/aarch64 code.
--- Makefile | 2 +- arm/aarch64/gdb.c | 745 ++++++++++++++++++++++++++++++++++++++++++++++ include/kvm/gdb.h | 2 +- 3 files changed, 747 insertions(+), 2 deletions(-) create mode 100644 arm/aarch64/gdb.c
Makefile +1 -1
@@ -131,7 +131,6 @@ endif #x86 ifeq ($(ARCH),x86) DEFINES += -DCONFIG_X86 - DEFINES += -DCONFIG_HAS_GDB_STUB OBJS += gdb.o OBJS += hw/i8042.o OBJS += hw/serial.o
@@ -198,6 +197,7 @@ ifeq ($(ARCH), arm64) OBJS += arm/aarch64/kvm.o OBJS += arm/aarch64/pvtime.o OBJS += arm/aarch64/pmu.o + OBJS += arm/aarch64/gdb.o ARCH_INCLUDE := $(HDRS_ARM_COMMON) ARCH_INCLUDE += -Iarm/aarch64/include
arm/aarch64/gdb.c new file +745 -0
745 lines not on this page · raw message
include/kvm/gdb.h +1 -1
@@ -16,7 +16,7 @@ struct kvm_gdb_hw_bp {bool active; }; -#ifdef CONFIG_HAS_GDB_STUB +#if defined(CONFIG_X86 ) || defined(CONFIG_ARM64 )/* * Public GDB stub API
Signature · 1 line
2.34.1
PATCH v3 3/3 arm64: Sync guest instruction patches for GDB breakpoints
--- arm/aarch64/gdb.c | 8 ++++++++ include/kvm/gdb.h | 10 ++++++++++ x86/gdb.c | 4 ++++ 3 files changed, 22 insertions(+)
arm/aarch64/gdb.c +8 -0
@@ -203,6 +203,14 @@ size_t kvm_gdb__arch_reg_pkt_size(void)return GDB_REGS_SIZE ; } +void kvm_gdb__arch_sync_guest_insn (void *host,size_t len) +{ +char *start = host; +char *end = start + len; + +__builtin___clear_cache (start, end); +} +/* ------------------------------------------------------------------ */ /* Helpers: which SP to expose as GDB register 31 */ /* ------------------------------------------------------------------ */
include/kvm/gdb.h +10 -0
@@ -90,6 +90,12 @@ size_t kvm_gdb__arch_reg_pkt_size(void);/* GDB signal number to report on stop (SIGTRAP=5) */ int kvm_gdb__arch_signal (struct kvm_cpu *vcpu); +/* +* Make a guest instruction patch visible to later instruction fetches. +* host points at the host virtual address backing the patched guest bytes. +*/ +void kvm_gdb__arch_sync_guest_insn (void *host,size_t len); +/* * Returns true if the KVM_EXIT_DEBUG exit was caused by a software * breakpoint (INT3 / #BP exception), as opposed to a hardware debug
@@ -133,6 +139,10 @@ static inline bool kvm_gdb__active(struct kvm *kvm)return false; } +static inline void kvm_gdb__arch_sync_guest_insn (void *host,size_t len) +{ +} +#endif #endif /* KVM__GDB_H */
x86/gdb.c +4 -0
@@ -107,6 +107,10 @@ size_t kvm_gdb__arch_reg_pkt_size(void)return GDB_REGS_SIZE ; } +void kvm_gdb__arch_sync_guest_insn (void *host,size_t len) +{ +} +/* ------------------------------------------------------------------ */ /* Helpers: read/write KVM register structures */ /* ------------------------------------------------------------------ */
Signature · 1 line
2.34.1
Re: [PATCH v3 0/3] Add GDB remote debug stub for x86 and arm64
In reply to vinceHi,
Ping. Any feedback on this series would be appreciated.
Thanks,
Liu Wenfei