From nobody Fri Jun 16 16:45:09 2023 X-Original-To: dev-commits-src-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 4QjQ4j5p6Sz4dvDR; Fri, 16 Jun 2023 16:45:09 +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 "R3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4QjQ4j5M4pz3J7d; Fri, 16 Jun 2023 16:45:09 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1686933909; 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=f8I370R3F+56Ew3DAW65wKppUzrpJMYndy3Op3zHYhA=; b=u2k6TF/6RHzoyvK7Up2TXQro3aoGH3NlovTMN71xoJJkCj1WGGKJHxoal5ILTi4HeyJocO cP769R8oz16E2kZK4b8ODO039In9UenoZ3n0OccvbM7oucxlHrMWvUjeTUPSJ811/CqzmV tZXOhIkWbyqpBVmzNFbOs3IpA/DXbbjpztr4ifV6JFMFkVCqNNM0bJIYCTYeHgMxYFk7lp ywkXX/V2DFt+iPL6g6IlPO17bElLl5ufxRq2/CjoyHrFbMoCKRNw/yAXE0yGWOVb60rJn3 aV6pqJYE99WlhyYp0RkjuA7BBOTGjVzSbQDfii7LGHml8kUWgx0QegByC11lKw== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1686933909; 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=f8I370R3F+56Ew3DAW65wKppUzrpJMYndy3Op3zHYhA=; b=ED8CqdvO9UvZZqwv/DdLVGR2VxpjBfCHDKvKyx31RY+3nQMwx2ScGn1uWMC7kawcSluxLm VGiIsLLAb8tb0IpRwMEA7kNEUfAAeIXZKyKBhesJuvFdK5SKWwFHunwgAD4Tlmw243xcl6 XPQVkYEoDDePvRDQb5B9CCemzqSLEE7/+CkWHcDzTjY3648ntR6drh6psbSuKr2txRAida k9P7HgH4/p7sZEhSUwQLldnrTueuct0H/sFGPuGnEkernTECIy2LeTdceTiq4qxkjPpulA f+n9K6qPDtuhtgJ5u373sdl46Jdc2wPAr0BGt9KzoN1JDO+dK5c3hZdSiPBgRQ== ARC-Authentication-Results: i=1; mx1.freebsd.org; none ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1686933909; a=rsa-sha256; cv=none; b=YR4jx1aMHjfKx6IF3avTe/h9TsYCQ2wbuPXn6rQQf0RdGCScoYBBjJ54OoyeOON9xKdAF9 AJ0++0AwVEPOQMPBKogldg2EH/EXo3/NRinviGlZuROd8d81Fa/VHbz+45YHRal2Bs+xwR PihM+uLVocA9NiPoJW8qHdrVUy2gUQfCH0ELZyWh+3SPktXFyl4IT2P+lN+NFUXcwhPz1S yl15FyHRVY+Uqw5NTgKCBGl4TDtHoQ1qiae71OSXlg6TW8OOPt/cr63S1kwcTZxlrUkXIK d4ZeXN7PQtPtIokdum5yUT4jdc32KsIvXUcwjcczr3w0D7xz5+GuwWrnQ0oLOQ== 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 4QjQ4j4CYVzbPR; Fri, 16 Jun 2023 16:45:09 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.16.1/8.16.1) with ESMTP id 35GGj9ks072909; Fri, 16 Jun 2023 16:45:09 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.16.1/8.16.1/Submit) id 35GGj9tb072908; Fri, 16 Jun 2023 16:45:09 GMT (envelope-from git) Date: Fri, 16 Jun 2023 16:45:09 GMT Message-Id: <202306161645.35GGj9tb072908@gitrepo.freebsd.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-main@FreeBSD.org From: Mitchell Horne Subject: git: 5fc97cc32553 - main - hwpmc(4): document debugging options List-Id: Commit messages for all branches of the src repository List-Archive: https://lists.freebsd.org/archives/dev-commits-src-all List-Help: List-Post: List-Subscribe: List-Unsubscribe: Sender: owner-dev-commits-src-all@freebsd.org X-BeenThere: dev-commits-src-all@freebsd.org MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: mhorne X-Git-Repository: src X-Git-Refname: refs/heads/main X-Git-Reftype: branch X-Git-Commit: 5fc97cc32553c4073c7dafd67a2d489b8af8563e Auto-Submitted: auto-generated X-ThisMailContainsUnwantedMimeParts: N The branch main has been updated by mhorne: URL: https://cgit.FreeBSD.org/src/commit/?id=5fc97cc32553c4073c7dafd67a2d489b8af8563e commit 5fc97cc32553c4073c7dafd67a2d489b8af8563e Author: Mitchell Horne AuthorDate: 2023-06-16 16:38:43 +0000 Commit: Mitchell Horne CommitDate: 2023-06-16 16:44:54 +0000 hwpmc(4): document debugging options The debug options for hwpmc are not documented in detail anywhere, and setting it up was error-prone the first time I had to figure it out (and each time I've had to remember it). Add some explanation of the required options and describe the kern.hwpmc.debugflags sysctl format. Reviewed by: emaste MFC after: 1 week Sponsored by: The FreeBSD Foundation Differential Revision: https://reviews.freebsd.org/D40545 --- share/man/man4/hwpmc.4 | 106 ++++++++++++++++++++++++++++++++++++++++++++++++- sys/sys/pmc.h | 6 ++- 2 files changed, 109 insertions(+), 3 deletions(-) diff --git a/share/man/man4/hwpmc.4 b/share/man/man4/hwpmc.4 index c394af90cd8d..3ae3ce726395 100644 --- a/share/man/man4/hwpmc.4 +++ b/share/man/man4/hwpmc.4 @@ -1,10 +1,12 @@ .\" Copyright (c) 2003-2008 Joseph Koshy -.\" Copyright (c) 2007 The FreeBSD Foundation -.\" All rights reserved. +.\" Copyright (c) 2007,2023 The FreeBSD Foundation .\" .\" Portions of this software were developed by A. Joseph Koshy under .\" sponsorship from the FreeBSD Foundation and Google, Inc. .\" +.\" Portions of this documentation were written by Mitchell Horne +.\" under sponsorship from the FreeBSD Foundation. +.\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: @@ -56,6 +58,17 @@ Alternatively, to compile this driver into the kernel: .Bd -ragged -offset indent .Cd "device hwpmc" .Ed +.Pp +To enable debugging features +.Po see +.Sx DEBUGGING +.Pc : +.Bd -ragged -offset indent +.Cd "options KTR" +.Cd "options KTR_COMPILE=(KTR_SUBSYS)" +.Cd "options KTR_MASK=(KTR_SUBSYS)" +.Cd "options HWPMC_DEBUG" +.Ed .Sh DESCRIPTION The .Nm @@ -520,6 +533,92 @@ The value for tunable .Va kern.hwpmc.nsamples was negative or greater than 65535. .El +.Sh DEBUGGING +The +.Nm +module can be configured to record trace entries using the +.Xr ktr 4 +interface. +This is useful for debugging the driver's functionality, primarily during +development. +This debugging functionality is not enabled by default, and requires +recompiling the kernel and +.Nm +module after adding the following to the kernel config: +.Bd -literal -offset indent +.Cd options KTR +.Cd options KTR_COMPILE=(KTR_SUBSYS) +.Cd options KTR_MASK=(KTR_SUBSYS) +.Cd options HWPMC_DEBUG +.Ed +.Pp +This alone is not enough to enable tracing; one must also configure the +.Va kern.hwpmc.debugflags +.Xr sysctl 8 +variable, which provides fine-grained control over which types of events are +logged to the trace buffer. +.Pp +.Nm +trace events are grouped by 'major' and 'minor' flag types. +The major flag groups are as follows: +.Pp +.Bl -tag -compact -offset indent +.It CPU +CPU events +.It CSW +Context switch events +.It LOG +Logging events +.It MDP +Machine-dependent/class-dependent events +.It MOD +Miscellaneous events +.It OWN +PMC owner events +.It PMC +PMC management events +.It PRC +Process events +.It SAM +Sampling events +.El +.Pp +The minor flags for each major flag group can vary. +For the full list of flag groups, consult +.In sys/pmc.h . +.Pp +The +.Va kern.hwpmc.debugflags +variable is a string with a custom format. +The string should contain a space-separated list of event specifiers. +Each event specifier consists of the major flag name, followed by an equal sign +(=), followed by a comma-separated list of minor event types. +To track all events for a major group, an asterisk (*) can be given instead. +.Pp +For example, to trace all allocation and release events, set +.Va debugflags +as follows: +.Bd -literal -offset indent +kern.hwpmc.debugflags="pmc=all,rel mdp=all,rel" +.Ed +.Pp +To trace all process events, as well as context switches: +.Bd -literal -offset indent +kern.hwpmc.debugflags="prc=* csw=*" +.Ed +.Pp +To disable all trace events, set the variable to an empty string. +.Bd -literal -offset indent +kern.hwpmc.debugflags="" +.Ed +.Pp +Trace events are recorded by +.Xr ktr 4 , +and can be inspected at run-time using the +.Xr ktrdump 8 +utility, or at the +.Xr ddb 4 +prompt after a panic with the 'show ktr' command. .Sh ERRORS A command issued to the .Nm @@ -751,7 +850,10 @@ operation is not being monitored by .Xr kenv 1 , .Xr pmc 3 , .Xr pmclog 3 , +.Xr ddb 4 , +.Xr ktr 4 , .Xr kldload 8 , +.Xr ktrdump 8 , .Xr pmccontrol 8 , .Xr pmcstat 8 , .Xr sysctl 8 , diff --git a/sys/sys/pmc.h b/sys/sys/pmc.h index cbb82408dcbf..d1b688df6c2b 100644 --- a/sys/sys/pmc.h +++ b/sys/sys/pmc.h @@ -1079,7 +1079,11 @@ extern struct pmc_driverstats pmc_stats; #define __pmcdbg_used /* unused variable annotation */ -/* debug flags, major flag groups */ +/* + * Debug flags, major flag groups. + * + * Please keep the DEBUGGING section of the hwpmc(4) man page in sync. + */ struct pmc_debugflags { int pdb_CPU; int pdb_CSW;