git: fd31c0946ee2 - main - cdefs.h: Add back comment about branch prediction

The branch main has been updated by imp:

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

commit fd31c0946ee2240491db1301c2d33eb846221a54
Author:     Warner Losh <imp@FreeBSD.org>
AuthorDate: 2024-07-03 18:52:38 +0000
Commit:     Warner Losh <imp@FreeBSD.org>
CommitDate: 2024-07-03 18:56:42 +0000

    cdefs.h: Add back comment about branch prediction
    
    Add back, with editing, the comments about branch prediction, when to
    use it, etc. Offer stronger opinions about this in style(9). Add in the
    convention for FreeBSD that we do only the entire expression in the if
    expression. Advise use only when it makes things measurably faster.
    
    Requested by:           jhb
    Sponsored by:           Netflix
    Reviewed by:            brooks, jhb
    Differential Revision:  https://reviews.freebsd.org/D45837
---
 share/man/man9/style.9 | 16 ++++++++++++++++
 sys/sys/cdefs.h        |  7 +++++++
 2 files changed, 23 insertions(+)

diff --git a/share/man/man9/style.9 b/share/man/man9/style.9
index 381f3aa3bfa3..daddc57bfb1f 100644
--- a/share/man/man9/style.9
+++ b/share/man/man9/style.9
@@ -897,6 +897,22 @@ New code should use
 .Fn _Static_assert
 instead of the older
 .Fn CTASSERT .
+.Pp
+.Fn __predict_true
+and
+.Fn __predict_false
+should only be used in frequently executed code when it makes the code
+measurably faster.
+It is wasteful to make predictions for infrequently run code, like subsystem
+initialization.
+When using branch prediction hints, atypical error conditions should use
+.Fn __predict_false
+(document the exceptions).
+Operations that almost always succeed use
+.Fn __predict_true .
+Only use the annotation for the entire if statement, rather than individual clauses.
+Do not add these annotations without empirical evidence of the likelihood of the
+branch.
 .Sh FILES
 .Bl -tag -width indent
 .It Pa /usr/src/tools/build/checkstyle9.pl
diff --git a/sys/sys/cdefs.h b/sys/sys/cdefs.h
index 7c4890ece8d5..b92992c1b5c3 100644
--- a/sys/sys/cdefs.h
+++ b/sys/sys/cdefs.h
@@ -321,6 +321,13 @@
 #define	__restrict	restrict
 #endif
 
+/*
+ * All modern compilers have explicit branch prediction so that the CPU back-end
+ * can hint to the processor and also so that code blocks can be reordered such
+ * that the predicted path sees a more linear flow, thus improving cache
+ * behavior, etc. Use sparingly, except in performance critical code where
+ * they make things measurably faster.
+ */
 #define	__predict_true(exp)     __builtin_expect((exp), 1)
 #define	__predict_false(exp)    __builtin_expect((exp), 0)