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
2cf7870864 ("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

sys/sys/bus.h

@@ -252,17 +252,19 @@ 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
+ * These flags may be passed by drivers to bus_setup_intr(9) when
- * spls implicit in names like INTR_TYPE_TTY. In the meantime, don't
+ * registering a new interrupt handler. The field is overloaded to
- * confuse things by renaming them (Grog, 18 July 2000).
+ * specify both the interrupt's type and any special properties.
  *
- * Buses which do interrupt remapping will want to change their type
+ * The INTR_TYPE* bits will be passed to intr_priority(9) to determine
- * to reflect what sort of devices are underneath.
+ * the scheduling priority of the handler's ithread. Historically, each
+ * type was assigned a unique scheduling preference, but now only
+ * INTR_TYPE_CLK receives a default priority higher than other
+ * interrupts. 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,