Page MenuHomeFreeBSD
Files F102549767

D40545.diff
No OneTemporary
Actions

D40545.diff
View Options

diff --git a/share/man/man4/hwpmc.4 b/share/man/man4/hwpmc.4
--- 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 @@
.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 @@
.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 @@
.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
--- a/sys/sys/pmc.h
+++ b/sys/sys/pmc.h
@@ -1079,7 +1079,11 @@
#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;

File Metadata

Mime Type
text/plain
Expires
Thu, Nov 14, 10:29 PM (8 h, 27 m)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
14625752
Default Alt Text
D40545.diff (3 KB)

Event Timeline