git: f7df2c03753a - stable/13 - pmc: clarify and strengthen statements about API/ABI

From: Mitchell Horne <mhorne_at_FreeBSD.org>
Date: Mon, 17 Jul 2023 16:49:41 UTC
The branch stable/13 has been updated by mhorne:

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

commit f7df2c03753aab249c075f5895df1e6fc591eaf6
Author:     Mitchell Horne <mhorne@FreeBSD.org>
AuthorDate: 2023-06-16 16:38:19 +0000
Commit:     Mitchell Horne <mhorne@FreeBSD.org>
CommitDate: 2023-07-17 16:45:39 +0000

    pmc: clarify and strengthen statements about API/ABI
    
    - Make it clear that applications are not only encouraged to use the
      pmc(3) library, but use of the hwpmc(4) interface directly is a
      use-case we do not support
    - Move the COMPATIBILITY section above PROGRAMMING API in hwpmc(4)
    - Drop statements about the driver and library being "under development"
    
    Reviewed by:    jkoshy, emaste
    MFC after:      1 week
    Sponsored by:   The FreeBSD Foundation
    Differential Revision:  https://reviews.freebsd.org/D40543
    
    (cherry picked from commit 3977781b987e369a9fe23bb642b9680b0a3887c1)
---
 lib/libpmc/pmc.3       |  8 ++------
 share/man/man4/hwpmc.4 | 27 +++++++++------------------
 2 files changed, 11 insertions(+), 24 deletions(-)

diff --git a/lib/libpmc/pmc.3 b/lib/libpmc/pmc.3
index 4bf2907db129..8cc7275bc338 100644
--- a/lib/libpmc/pmc.3
+++ b/lib/libpmc/pmc.3
@@ -23,7 +23,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd August 10, 2021
+.Dd June 16, 2023
 .Dt PMC 3
 .Os
 .Sh NAME
@@ -474,11 +474,7 @@ In order to ease forward compatibility with future versions of the
 driver, applications are urged to dynamically link with the
 .Nm pmc
 library.
-.Pp
-The
-.Nm pmc
-API is
-.Ud
+Doing otherwise is unsupported.
 .Sh SEE ALSO
 .Xr pmc.atom 3 ,
 .Xr pmc.core 3 ,
diff --git a/share/man/man4/hwpmc.4 b/share/man/man4/hwpmc.4
index 6bd5d571793a..3a4be77085bc 100644
--- a/share/man/man4/hwpmc.4
+++ b/share/man/man4/hwpmc.4
@@ -28,7 +28,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd November 2, 2012
+.Dd June 16, 2023
 .Dt HWPMC 4
 .Os
 .Sh NAME
@@ -288,14 +288,15 @@ Non-disabled hardware counters in such a row may be used
 for satisfying system scope allocation requests.
 No process scope PMCs will use hardware counters in this row.
 .El
-.Sh PROGRAMMING API
-The recommended way for application programs to use the facilities of
-the
-.Nm
-driver is using the API provided by the
+.Sh COMPATIBILITY
+The API and ABI documented in this manual page may change in the future.
+This interface is intended to be consumed by the
 .Xr pmc 3
-library.
-.Pp
+library; other consumers are unsupported.
+Applications targeting PMCs should use the
+.Xr pmc 3
+library API.
+.Sh PROGRAMMING API
 The
 .Nm
 driver operates using a system call number that is dynamically
@@ -526,16 +527,6 @@ The value for tunable
 .Va kern.hwpmc.nsamples
 was negative or greater than 65535.
 .El
-.Sh COMPATIBILITY
-The
-.Nm
-driver is
-.Ud
-The API and ABI documented in this manual page may change in
-the future.
-The recommended method of accessing this driver is using the
-.Xr pmc 3
-API.
 .Sh ERRORS
 A command issued to the
 .Nm