git: ef2aa7753012 - stable/13 - Reapply: "bus.h: rewrite comment describing intr_type"

The branch stable/13 has been updated by mhorne:

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

commit ef2aa77530127fe76711246cd5c4f1b95143e57a
Author:     Mitchell Horne <mhorne@FreeBSD.org>
AuthorDate: 2022-10-07 22:21:49 +0000
Commit:     Mitchell Horne <mhorne@FreeBSD.org>
CommitDate: 2022-10-18 14:32:29 +0000

    Reapply: "bus.h: rewrite comment describing intr_type"
    
    Describe more clearly the purpose of these flags and where they are
    used.
    
    Remove grog's comment about revisiting the flags. At this point it does
    not make sense to change this long-standing API, especially in light of
    2cf7870864ea ("Collapse interrupt thread priorities").
    
    Give a better example of a bus modifying these flags; I did not find any
    existing instance where a bus changes the interrupt's type.
    
    Reviewed by:    imp, markj, jhb
    MFC after:      1 week
    Sponsored by:   The FreeBSD Foundation
    Differential Revision:  https://reviews.freebsd.org/D36896
    
    Note: 2cf7870864ea is not present in stable/13 and likely will never be.
    While reapplying this change, I have modified the comment further to
    eliminate any inaccuracy Re: priorities. It should be applicable even if
    the change is merged some day.
    
    (cherry picked from commit af390486010e8fc78c4d715e751cd1175d0752c7)
---
 sys/sys/bus.h | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/sys/sys/bus.h b/sys/sys/bus.h
index 430beaecc6d0..c017f38dcf11 100644
--- a/sys/sys/bus.h
+++ b/sys/sys/bus.h
@@ -251,17 +251,17 @@ typedef void driver_intr_t(void*);
 
 /**
  * @brief Interrupt type bits.
- * 
- * These flags are used both by newbus interrupt
- * registration (nexus.c) and also in struct intrec, which defines
- * interrupt properties.
  *
- * XXX We should probably revisit this and remove the vestiges of the
- * spls implicit in names like INTR_TYPE_TTY. In the meantime, don't
- * confuse things by renaming them (Grog, 18 July 2000).
+ * These flags may be passed by drivers to bus_setup_intr(9) when
+ * registering a new interrupt handler. The field is overloaded to
+ * specify both the interrupt's type and any special properties.
  *
- * Buses which do interrupt remapping will want to change their type
- * to reflect what sort of devices are underneath.
+ * The INTR_TYPE* bits will be passed to intr_priority(9) to determine the
+ * scheduling priority of the handler's ithread. For the specific priority
+ * values assigned to each type, see sys/priority.h.
+ *
+ * Buses may choose to modify or augment these flags as appropriate,
+ * e.g. nexus may apply INTR_EXCL.
  */
 enum intr_type {
 	INTR_TYPE_TTY = 1,