From nobody Fri Jun 16 16:45:07 2023 X-Original-To: dev-commits-src-main@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 4QjQ4g57zcz4dv3H; Fri, 16 Jun 2023 16:45:07 +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 4QjQ4g3Xwqz3HpY; Fri, 16 Jun 2023 16:45:07 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1686933907; 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=klvEhejoxoSTjLbqTQLwewfkNetTx3sLIBvjL8dLW8s=; b=uEik9UjSTfAYLTIAg/gHzBva1qFOf7s8TBLROZEfuP2YiZA/WNeKnwIiwITlocazVtGgvf 8GI+jjrFw9WaZRpEZ+gdS658avrkdfmCpLQM6yiQ45bAWtCulD7TAWACLiwywFDGkkGI2M PU5ZrR7hfQ8sPdAznIF8P/5OoZkMAZRFFXS3+oPxFfRHLS5x4QYAWC7flbU+3+5Iz4vDCX +W55dkBHCOvZickmwRJopIKurNpsti91Xyb0nn30IbMvze/RwgJJfRoFPttaaPj9EU31i+ heDzlzqlPRDh17gUNp3zEr29I0nHK1gY3op7pAA5Zl7CgNzQ60BSknGzNIllzA== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1686933907; 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=klvEhejoxoSTjLbqTQLwewfkNetTx3sLIBvjL8dLW8s=; b=hCp9rwwQ/+/4tUj0Jv488ZvVysqXMAXhyG5amAk3sfYt0YLqZf/B6DcI6qwUl/s+jrZ65g ANmpJCMuDoKlDfIFEXUJCCZE6lMTYU8clNXv2fVWAahNOGW2ywrUQMTTc1t3jodVhuu6ae 7IF87bXNRo55dN7AigdAF4VDOKYNVSyuLwQnhUFBF1EvhOTgMMk+QxAD7R1QGYV2XlnPfa Wt5Ipmw4tcBSXFIRv06BFaNleOaJ5rZZwVTJXCYzZFECNpmh7Zq+Boxc9wm1n2dLaG3Gta +vpLdv3iGbn2TySqKZqhMcUIWmslB8uc/lW/6vyph1KpC87K1KaYknSeIJp9Xw== ARC-Authentication-Results: i=1; mx1.freebsd.org; none ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1686933907; a=rsa-sha256; cv=none; b=XqxmXFZkO9srMcv5AKvfonxAt/0o8keGjmXlNROFUJLZikcjjYZ56qxRWYGox6nCZBvBnI Nw5JE4Ib4dXKojo7pwJ9CR3mCmEytLrIwe9bLH/ZwxlfRrV4NP7zXjeNfQ68lxZSQ6+67P YTAneeOoOeTkpEoaMFFIPSN35vEwGJonFOrDHsBKjEO0VBH8dOdbrMQ4QxsQJ973FkJDjj 9UatluRSp2miXDCX5+NARiX5gUkE7gWJYPazt6mX8cmq9+bSwD6O2BWmDvrTOyoTVWUeur 7QVS5qpu20ZHotmLfN+xYzczCXUjtPwMzVW+GNX+j/ejR+Uibx8mq3wgDzM9vg== 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 4QjQ4g2dzZzbPQ; Fri, 16 Jun 2023 16:45:07 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.16.1/8.16.1) with ESMTP id 35GGj7HX072867; Fri, 16 Jun 2023 16:45:07 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.16.1/8.16.1/Submit) id 35GGj7OU072866; Fri, 16 Jun 2023 16:45:07 GMT (envelope-from git) Date: Fri, 16 Jun 2023 16:45:07 GMT Message-Id: <202306161645.35GGj7OU072866@gitrepo.freebsd.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-main@FreeBSD.org From: Mitchell Horne Subject: git: 3977781b987e - main - pmc: clarify and strengthen statements about API/ABI List-Id: Commit messages for the main branch of the src repository List-Archive: https://lists.freebsd.org/archives/dev-commits-src-main List-Help: List-Post: List-Subscribe: List-Unsubscribe: Sender: owner-dev-commits-src-main@freebsd.org X-BeenThere: dev-commits-src-main@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/main X-Git-Reftype: branch X-Git-Commit: 3977781b987e369a9fe23bb642b9680b0a3887c1 Auto-Submitted: auto-generated X-ThisMailContainsUnwantedMimeParts: N The branch main has been updated by mhorne: URL: https://cgit.FreeBSD.org/src/commit/?id=3977781b987e369a9fe23bb642b9680b0a3887c1 commit 3977781b987e369a9fe23bb642b9680b0a3887c1 Author: Mitchell Horne AuthorDate: 2023-06-16 16:38:19 +0000 Commit: Mitchell Horne CommitDate: 2023-06-16 16:44:54 +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 --- 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 83f555a5a770..83906a8d9e44 100644 --- a/lib/libpmc/pmc.3 +++ b/lib/libpmc/pmc.3 @@ -23,7 +23,7 @@ .\" .\" $FreeBSD$ .\" -.Dd April 5, 2023 +.Dd June 16, 2023 .Dt PMC 3 .Os .Sh NAME @@ -542,11 +542,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 6c9e90b36c2d..c394af90cd8d 100644 --- a/share/man/man4/hwpmc.4 +++ b/share/man/man4/hwpmc.4 @@ -28,7 +28,7 @@ .\" .\" $FreeBSD$ .\" -.Dd May 31, 2023 +.Dd June 16, 2023 .Dt HWPMC 4 .Os .Sh NAME @@ -281,14 +281,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 @@ -519,16 +520,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