Page MenuHomeFreeBSD

pmcstat(8): add -b batch-grouping flag
Needs ReviewPublic

Authored by afscoelho_gmail.com on Jun 18 2026, 7:06 AM.
Tags
None
Referenced Files
Unknown Object (File)
Wed, Oct 7, 6:39 AM
Unknown Object (File)
Wed, Oct 7, 1:29 AM
Unknown Object (File)
Wed, Oct 7, 1:29 AM
Unknown Object (File)
Wed, Oct 7, 1:13 AM
Unknown Object (File)
Tue, Oct 6, 4:41 AM
Unknown Object (File)
Tue, Oct 6, 3:07 AM
Unknown Object (File)
Mon, Oct 5, 10:36 AM
Unknown Object (File)
Mon, Oct 5, 9:17 AM
Subscribers

Details

Summary

Add the -b / --batch-grouping flag and the {a,b,c} brace syntax to
pmcstat(8). For brace expressions in -p / -P / -s / -S the tool now:

  1. creates a kernel group via pmc_group_create();
  2. for each event token allocates a deferred pmcid with pmc_allocate_group() and registers it via pmc_group_add(), marking the first one as the leader;
  3. commits the group with pmc_group_commit() before any pmc_attach.

A brace containing a single event falls back to the legacy
pmc_allocate path so that "{a}" stays equivalent to "a".

The man page documents the syntax, the multiplex semantics enabled by
PMC_F_GROUP_MUX, and the all-or-none commit guarantee.

Sponsored by: AMD
Signed-off-by: Raghavendra K T <raghavendra.kt@amd.com>

Diff Detail

Repository
rG FreeBSD src repository
Lint
Lint Skipped
Unit
Tests Skipped
Build Status
Buildable 77477
Build 74360: arc lint + arc unit

Event Timeline

afscoelho_gmail.com updated this revision to Diff 185751.

Update to the rebuilt PerfMonV2 grouping and multiplexing stack.

Can you please update the docs in this commit?

usr.sbin/pmcstat/pmcstat.8
45 ↗(On Diff #179982)

Can you use it like this or does the -b have to come first?

Rebase on main (D60141 and D60185 are committed). No change.

Document -b in this revision, including brace-list syntax and the requirement that -b precede the event options. The pmcstat.c change is unchanged.

Can you please update the docs in this commit?

Sorry I missed this. The basic -b documentation was in D59365; I've moved it into this revision and adjusted D59365 so it builds on that text without duplicating it. This diff now documents -b in the synopsis and options, the quoted brace-list syntax, and group commit behavior.

On the inline question: -b must come before the -p, -P, -s, or -S options whose events should be grouped. pmcstat parses options in order; a later -b does not reinterpret earlier event specifications. The man page now states that explicitly and uses:

pmcstat -b -p '{instructions,unhalted-cycles}' sleep 10

Both revised man pages pass mandoc -Tlint -Werror on FreeBSD. A source-derived parser check using FreeBSD getopt() confirms the ordering for all four event options; no hardware-counting run was needed for this documentation-only change.