ithread(9): update top-level description

[mhorne]

Summary

The ithread has been subsumed by the 'interrupt event' object, so
update the description to reflect this by describing an interrupt event
and its contents. We've also moved on from having a single handler
function to the split filter-and-handler model. Explain the purpose and
constraints of these two handlers.

[mhorne]

Looking for content review primarily before wording/grammer/formatting.

[imp]

share/man/man9/ithread.9

76–78 ↗

(On Diff #100087)

line breaks here are weird.

[pauamma_gundo.com]

share/man/man9/ithread.9

129 ↗

(On Diff #100087)

Typo for "intr"?

[mhorne]

Rebase. Handle feedback, rework text describing locks and sleeping, and add subsections to organize the description somewhat.

[jhb]

share/man/man9/intr_event.9

92

107

I think you want to be careful here about the phrase "interrupt handler" to avoid ambiguity. Here I think you mean the threaded handler?

114

Not sure if you want to clarify that you can't call malloc at all in a filter?

[pauamma_gundo.com]

Other than these nits (and bumping .Dd), English in this LGTM.

share/man/man9/intr_event.9

81

96

107

Seconded.

114

The clearer, the better.

[mhorne]

Update Handler Constraints to address review comments.
Avoid referring to "filter" and "handler" functions as "callbacks".

I discovered that the filter and threaded routines are described in detail
already in bus_setup_intr(9). I think the overlap is acceptable, however.

[mhorne]

Small further tweaks, mainly, clarify that filters are executed in a critical section.

[bcr]

OK from manpages.

[jhb]

share/man/man9/intr_event.9

114

Suggestion: s/disallowed/not permitted/? (Not a strong preference either way though)

121–122

You could maybe just say "non-sleepable locks"

[pauamma_gundo.com]

share/man/man9/intr_event.9

114

"forbidden" feels more less stilted than "disallowed" and less likely to be misread by missing "not" than "not permitted".

121–122

Seconded.

124

"should", not "must"?

128

Or "later, outside (mumble) context".

[mhorne]

Handle feedback.

[pauamma_gundo.com]

English LGTM. Can't say beyond that.