git: 89240e0ab60a - main - hwpmc(4): update DEBUGGING section details

The branch main has been updated by mhorne:

URL: https://cgit.FreeBSD.org/src/commit/?id=89240e0ab60a29a47c9af9f952a09a7f2e1bb72c

commit 89240e0ab60a29a47c9af9f952a09a7f2e1bb72c
Author:     Mitchell Horne <mhorne@FreeBSD.org>
AuthorDate: 2023-07-09 19:01:55 +0000
Commit:     Mitchell Horne <mhorne@FreeBSD.org>
CommitDate: 2023-07-09 19:03:54 +0000

    hwpmc(4): update DEBUGGING section details
    
    The examples I wrote previously do not work. We parse the flags using
    explicit names, not the shortened flag suffix. Fix the list of major
    flags, and add a compact list of minor flags. Fix the examples, and
    tweak some wording for clarity.
    
    Reviewed by:    jkoshy, emaste
    MFC after:      1 week
    Sponsored by:   The FreeBSD Foundation
    Fixes:          5fc97cc32553 ("hwpmc(4): document debugging options")
    Differential Revision:  https://reviews.freebsd.org/D40913
---
 share/man/man4/hwpmc.4 | 68 +++++++++++++++++++++++++++++++++++++-------------
 1 file changed, 51 insertions(+), 17 deletions(-)

diff --git a/share/man/man4/hwpmc.4 b/share/man/man4/hwpmc.4
index 1794adb66460..1b99e8c8439c 100644
--- a/share/man/man4/hwpmc.4
+++ b/share/man/man4/hwpmc.4
@@ -558,32 +558,65 @@ logged to the trace buffer.
 .Pp
 .Nm
 trace events are grouped by 'major' and 'minor' flag types.
-The major flag groups are as follows:
+The major flag names are as follows:
 .Pp
-.Bl -tag -compact -offset indent
-.It CPU
+.Bl -tag -width "sampling" -compact -offset indent
+.It cpu
 CPU events
-.It CSW
+.It csw
 Context switch events
-.It LOG
+.It logging
 Logging events
-.It MDP
+.It md
 Machine-dependent/class-dependent events
-.It MOD
+.It module
 Miscellaneous events
-.It OWN
+.It owner
 PMC owner events
-.It PMC
+.It pmc
 PMC management events
-.It PRC
+.It process
 Process events
-.It SAM
+.It sampling
 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 .
+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
@@ -591,18 +624,19 @@ 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.
+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=all,rel mdp=all,rel"
+kern.hwpmc.debugflags="pmc=allocate,release md=allocate,release"
 .Ed
 .Pp
-To trace all process events, as well as context switches:
+To trace all events in the process and context switch major flag groups:
 .Bd -literal -offset indent
-kern.hwpmc.debugflags="prc=* csw=*"
+kern.hwpmc.debugflags="process=* csw=*"
 .Ed
 .Pp
 To disable all trace events, set the variable to an empty string.