From nobody Mon Jul 14 07:55:02 2025 X-Original-To: dev-commits-doc-all@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 4bgZNk2kkjz60g3K for ; Mon, 14 Jul 2025 07:55:02 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "R10" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4bgZNk0t9Jz3Ql2; Mon, 14 Jul 2025 07:55:02 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1752479702; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=PT9bgmnkBm948uCx8+LLSgoXvXjqC20FXyLXuO37iCI=; b=rfYbaenrXk/1l0U7RSTi6gdBtmuk7VzESfUTMmpFiUrpgA7QRPYM1jUMzvAXbSWxEr2Txx M1sb/RDzm4Ig8HW6/PXfI474WMDrPJpDISGYwdvKGa67dmSEYeTQhWJsRB3C0kVH8DTHwq yh+YwQaefIiT1+k//eEgfza4GIXNd8Hi+XfiXyFw8s4KeocojZxm9SxOPHu7IgEgKBwBuF 2PbFdLMSh2KHDNgope6plUTMdD3jUZcUe7AejivuZk9h29zrG1b/gpKKjKb9vcSW8OBNqw HKCG2pR84s3lETxNCzf0jlgwqokZq7o/tEPhEOIH4TAqjoc2tFN1CGhmjEHaRA== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1752479702; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=PT9bgmnkBm948uCx8+LLSgoXvXjqC20FXyLXuO37iCI=; b=wD9woW6lu2PaRjhiKRPcn4ggwdS8X60Ln0duuAELmvc9SDp7SqHd2jym26r9dnEsetaCCK UVtbIOguoryYoBYx7jTMQj1ki5Wg6FLdtWLSvimnUccdr6xJnQnoa3atDuvSZbq2d3C3iG pQfsQ8yhyh5CUbMx3368uw/BT606AqTG7FVT2+92zjt02hV/1iN/SGdZaPf+RnSrR188lP VkX6wfafJjHiItBYenXUbhvaFvXh2TNqb+QaNSaEWMJ+c1xDz/Au3NK37JXCTWOKoQMz+G W6YjgbiCATqcAQ6wv/HfC+v7RvPgXVpXQah/6/9FDWLKGXzeD2iOkOHTr0YxTA== ARC-Authentication-Results: i=1; mx1.freebsd.org; none ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1752479702; a=rsa-sha256; cv=none; b=J4ClP/8RHLiFCY0vNAU+3mPHxtpXBeLwKReiEMpz0ox3YIIqVWfjlxBD/d6wb3E8itA73B 9WvtJ/DY7dAI0Quo453GrzkdkIQkrbR/S6HrIKw4LtAJpVYlnHZfVFQV8ltLaX3xZe0A8z VJrvlNjggQKxeYSmsXPAbe2gKk+fNOinTAjYkUmVVtcujCUpTPDdfNpAJfc8rr050tVT1Y bnYvJPAQBAcZE4CZ9taFcKePeA4L6QVFdhhmQAO1A9otnijJE0inS3zOIANPjkVfmerEvQ JQ66N2LruNf/641aj2HR634mNDHMpNW7xdCsSO8KN9VET4ZSRE4/2qSyLC77+Q== Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 4bgZNk0V0gzm1Q; Mon, 14 Jul 2025 07:55:02 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.18.1/8.18.1) with ESMTP id 56E7t2kN066484; Mon, 14 Jul 2025 07:55:02 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.18.1/8.18.1/Submit) id 56E7t2vQ066481; Mon, 14 Jul 2025 07:55:02 GMT (envelope-from git) Date: Mon, 14 Jul 2025 07:55:02 GMT Message-Id: <202507140755.56E7t2vQ066481@gitrepo.freebsd.org> To: doc-committers@FreeBSD.org, dev-commits-doc-all@FreeBSD.org From: Tom Jones Subject: git: 87bfd93c0b - main - Status/2025/Q2/usb-debugging.adoc: Add status report List-Id: Commit messages for all branches of the doc repository List-Archive: https://lists.freebsd.org/archives/dev-commits-doc-all List-Help: List-Post: List-Subscribe: List-Unsubscribe: X-BeenThere: dev-commits-doc-all@freebsd.org Sender: owner-dev-commits-doc-all@FreeBSD.org MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: thj X-Git-Repository: doc X-Git-Refname: refs/heads/main X-Git-Reftype: branch X-Git-Commit: 87bfd93c0b8644080e71b2c99d99d0448b2cf70c Auto-Submitted: auto-generated The branch main has been updated by thj: URL: https://cgit.FreeBSD.org/doc/commit/?id=87bfd93c0b8644080e71b2c99d99d0448b2cf70c commit 87bfd93c0b8644080e71b2c99d99d0448b2cf70c Author: Tom Jones AuthorDate: 2025-06-24 08:18:06 +0000 Commit: Tom Jones CommitDate: 2025-07-14 07:53:47 +0000 Status/2025/Q2/usb-debugging.adoc: Add status report Add a status report for USB debugging interface. Reviewed by: salvadore, Pau Amma Differential Revision: https://reviews.freebsd.org/D51003 --- .../report-2025-04-2025-06/usb-debugging.adoc | 27 ++++++++++++++++++++++ 1 file changed, 27 insertions(+) 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