diff --git a/website/content/en/status/report-2025-04-2025-06/usb-debugging.adoc b/website/content/en/status/report-2025-04-2025-06/usb-debugging.adoc new file mode 100644 index 0000000000..12c3234e7b --- /dev/null +++ b/website/content/en/status/report-2025-04-2025-06/usb-debugging.adoc @@ -0,0 +1,27 @@ +=== USB Kernel Debugging + +Contact: Tom Jones + +XHCI USB controllers offer a mode which allows them to be used as a system debugging interface. +XHCI debug uses a special USB 3 cable with VBUS, D+ and D- disconnected. +The feature can used to live debug the FreeBSD kernel, enabling investigation of issues which cause the system video console to lock up and there is not an alternative such as a serial console. +This can happen when debugging issues with graphics drivers. + +mailto:hrs@FreeBSD.org[Hiroki Sato] developed support for the XHCI debug interface and made it available as some in progress git branches. +This implementation enables FreeBSD to operate as both a Debug Host and a Debug Target, with support for debugging from the loader through to the kernel. + +I have been updating and testing this support along with mailto:mhorne@FreeBSD.org[Mitchell Horne] and together we have a WIP branch which applies to FreeBSD main. +We are currently tidying up interfaces and testing for stability with the goal of introducing XHCI debug once 16 is branched. + +In doing the XHCI debug work I rediscovered a second form of kernel debugging implemented by Hans Petter Selasky (hselasky@) in 2009. +The FreeBSD USB stack supports using a USB serial device as a system console and includes support to continue polling the interface once the system has entered the debugger (such as during a panic). +USB Serial debugging allows a developer with two commodity USB serial interfaces to connect to a FreeBSD target and debug the kernel. +USB Serial debugging is available in all FreeBSD releases in FreeBSD 9, but changes in the kernel build process mean that it is not detected in modern kernels. + +In this quarter I have been working on documentation required to use this interface and changes to make it available in GENERIC kernels for newer FreeBSD releases. + +A core part of this work has been trying to document kernel debugging interfaces. +If you use live debug interfaces other than serial or network debugging please get in touch so I can add these to the FreeBSD Developers Handbook. + + +Sponsor: The FreeBSD Foundation