From nobody Mon Jul 17 16:49:42 2023 X-Original-To: dev-commits-src-branches@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 4R4Sjf4pC1z4n4Y3; Mon, 17 Jul 2023 16:49:42 +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 4R4Sjf3t41z4JWW; Mon, 17 Jul 2023 16:49:42 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1689612582; 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=md2QhzK/PuBxe2eSr99ztQgR8/KWzUxj9BhFZhyf5vQ=; b=wCGC8Vi/OUF2e+Zg31f6h4PRwk+LJRQP4tpac88LeTWcpx33mkNS9A4+00AzA1bB4B7Ha0 Nt/UYg2Q4lD+7eIy552zXoM9aXKsYS9aXhN0kmPpnVGqGXL5vyQ0hlHa58v0fi9yY4LR7q KdTrCz0Hxd7fwYSm7//XxRt/SmMgcKqAo1mRKnxqlXrtk59XqaZozbpd3ybTJwy+x6HVir j8Y3T9i/f6pOtLQlP4evlgSJlSGV/JQ/95NNMUqErpuDACWGMhxR8GTBoGYNI68DU7FJb0 U7TMCKvvQ0uFRc+6lu4070t1HB8lhbxY7LCFsctEkLx1dO0muMpoKXRpfQxjXA== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1689612582; 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=md2QhzK/PuBxe2eSr99ztQgR8/KWzUxj9BhFZhyf5vQ=; b=IzJrA06IZL4DZ5VEo4v6CcYEk+snuObnMZf/nky3UVjVm4NlVh0tD045nO0IAqAxvQu/uJ EExlHaq63bhdHTLb+izf5O3v6EfvaQtQPbdfZx1wzAym4fEd9Dp0wyTgUj+YQh2M8raHGH 3S0YzuAUro4DA8290ihmYlODYP0qXx6OYLuTsXKtfniJqY9btcRiEpy1deGTUAq+3U1jeL u2XX1wg9FnMsvcWZr1fcR9sLGm+IMVNSRqAFMmY32obnmYeoOZSAg104g+IyOOQfstbUuT Y66n1FqA5ADltl3bX7g2D+mfYus2Tr1XP0tOYp/PYcdj2o9nIoThYwmHjcqCEg== ARC-Authentication-Results: i=1; mx1.freebsd.org; none ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1689612582; a=rsa-sha256; cv=none; b=MRUcqnDWoCS/40B/D3+Zxh/zyLAtnXK4oFR3UzJLuoMhrMZSRwg4jXt6uFmV9lFI5hTbn5 sFfaWgj90GE8gMESpG5wV+Vu5VoB82H0QE0PUObEQl+aJ5/IFio2eSKZvBMiIRhBlAf7fP SJF9RUVv0HPUln51QDGA1WRuGfW1S9svzTAHegGEQqG3INKh/QTl9COprel5lysfNHbMRK s42047BGgf2pSFlw32nrBZU51aYTOVaOhXMFLAiIAOAhpeReN53uF2v2QTixIeN0oNVR9P E79C2sNmskxl+8gQw/kvpMOWtY2JMZMDZCve+q8DBWFBCWTxepvp8NTMz35z+A== 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 4R4Sjf2ftxzWwx; Mon, 17 Jul 2023 16:49:42 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.17.1/8.17.1) with ESMTP id 36HGngBi081421; Mon, 17 Jul 2023 16:49:42 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.17.1/8.17.1/Submit) id 36HGngUL081420; Mon, 17 Jul 2023 16:49:42 GMT (envelope-from git) Date: Mon, 17 Jul 2023 16:49:42 GMT Message-Id: <202307171649.36HGngUL081420@gitrepo.freebsd.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-branches@FreeBSD.org From: Mitchell Horne Subject: git: 11b3648c4cbb - stable/13 - hwpmc(4): document debugging options List-Id: Commits to the stable branches of the FreeBSD src repository List-Archive: https://lists.freebsd.org/archives/dev-commits-src-branches List-Help: List-Post: List-Subscribe: List-Unsubscribe: Sender: owner-dev-commits-src-branches@freebsd.org X-BeenThere: dev-commits-src-branches@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/stable/13 X-Git-Reftype: branch X-Git-Commit: 11b3648c4cbbff70b4e74b9ac43546aece713b60 Auto-Submitted: auto-generated X-ThisMailContainsUnwantedMimeParts: N The branch stable/13 has been updated by mhorne: URL: https://cgit.FreeBSD.org/src/commit/?id=11b3648c4cbbff70b4e74b9ac43546aece713b60 commit 11b3648c4cbbff70b4e74b9ac43546aece713b60 Author: Mitchell Horne AuthorDate: 2023-06-16 16:38:43 +0000 Commit: Mitchell Horne CommitDate: 2023-07-17 16:48:48 +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 (cherry picked from commit 5fc97cc32553c4073c7dafd67a2d489b8af8563e) (cherry picked from commit 89240e0ab60a29a47c9af9f952a09a7f2e1bb72c) --- share/man/man4/hwpmc.4 | 140 ++++++++++++++++++++++++++++++++++++++++++++++++- sys/sys/pmc.h | 6 ++- 2 files changed, 143 insertions(+), 3 deletions(-) diff --git a/share/man/man4/hwpmc.4 b/share/man/man4/hwpmc.4 index 3a4be77085bc..bf9cb5e9e5e3 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 @@ -527,6 +540,126 @@ 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 names are as follows: +.Pp +.Bl -tag -width "sampling" -compact -offset indent +.It cpu +CPU events +.It csw +Context switch events +.It logging +Logging events +.It md +Machine-dependent/class-dependent events +.It module +Miscellaneous events +.It owner +PMC owner events +.It pmc +PMC management events +.It process +Process events +.It sampling +Sampling events +.El +.Pp +The minor flags for each major flag group can vary. +The individual minor flag names are: +.Bd -ragged -offset indent +allocaterow, +allocate, +attach, +bind, +config, +exec, +exit, +find, +flush, +fork, +getbuf, +hook, +init, +intr, +linktarget, +mayberemove, +ops, +read, +register, +release, +remove, +sample, +scheduleio, +select, +signal, +swi, +swo, +start, +stop, +syscall, +unlinktarget, +write +.Ed +.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 of +minor event names. +.Pp +For example, to trace all allocation and release events, set +.Va debugflags +as follows: +.Bd -literal -offset indent +kern.hwpmc.debugflags="pmc=allocate,release md=allocate,release" +.Ed +.Pp +To trace all events in the process and context switch major flag groups: +.Bd -literal -offset indent +kern.hwpmc.debugflags="process=* 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 @@ -752,8 +885,11 @@ operation is not being monitored by .Xr kenv 1 , .Xr pmc 3 , .Xr pmclog 3 , +.Xr ddb 4 , +.Xr ktr 4 , .Xr kgmon 8 , .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 12583e67b062..153d24ca250f 100644 --- a/sys/sys/pmc.h +++ b/sys/sys/pmc.h @@ -1080,7 +1080,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;