ithread(9): update existing function descriptions

[mhorne]

Summary

Document new arguments and behaviours for these functions as compared to
the old ithread_* variants.

[imp]

So what role does the filter function play?

share/man/man9/ithread.9

210–211 ↗

(On Diff #100088)

It might be better to put this as

The pri argument specifies the priority of this handler.
It determines the order it is called relative to the other handlers for this evet.

[mhorne]

In D33478#756699, @imp wrote:

So what role does the filter function play?

I added some text describing the filter and ithread handler functions in D33477, so feedback there would be welcome :)

As I understand it the filter is useful in reducing the overall latency of interrupt handlers, by performing some work ahead of the ithread or eliminating the need for the ithread at all. Exactly how it is used really depends on the device/interrupt being serviced.

share/man/man9/ithread.9

210–211 ↗

(On Diff #100088)

That is indeed better, but it seems I was wrong about the fact that the priority is still set for the ithread in ithread_update(). So I will just drop this hunk.

[pauamma_gundo.com]

share/man/man9/ithread.9

129 ↗

(On Diff #100088)

My C is very rusty, but "*" looks out of place here to me. If event points to a pointer that in turn points to a struct intr_event, this should be clarified.

158 ↗

(On Diff #100088)

Or maybe "waking up"

177 ↗

(On Diff #100088)

"of the" here I think, as in the other review, if you mean the same interrupt thread as above.

[mhorne]

Rebase, handle review comments.

[jhb]

share/man/man9/intr_event.9

174

This is not correct. We call post_filter once per interrupt. In fact, more accurate is that after running filters, we call either pre_ithread (if the ithread is going to be scheduled) which should mask level-triggered interrupts in the PIC) or we call post_filter (if no ithread is going to be scheduled, so the interrupt should be considered fully handled). It might be more useful to describe the callbacks in those terms. post_ithread is then called from the ithread after executing all of the threaded handlers.

[mhorne]

Describe the callback functions more completely and correctly. Split it out to a separate subsection, as the intr_event_create() paragraph was becoming unwieldly.

[mhorne]

share/man/man9/intr_event.9

171

Is is preferred to state the name of the .Ss I am referring to? Is there a canonical way of doing so?

[pauamma_gundo.com]

Getting there as far as I'm concerned.

share/man/man9/intr_event.9

171

Is is preferred to state the name of the .Ss I am referring to? Is there a canonical way of doing so?

.Sx (also works for subsections IIRC)

290–296

So pre_ithread is only called if there are threaded handlers, but post_ithread is always called? If so, that should be made explicit so post_ithread doesn't require state information from pre_ithread, since that's not guaranteed to exist - or worse, may be related to an earlier interrupt.

[mhorne]

Handle feedback.

[mhorne]

share/man/man9/intr_event.9

290–296

Clarified that it is only run when there are threaded handlers assigned to the interrupt.

[pauamma_gundo.com]

English LGTM now; thanks.

[jhb]

share/man/man9/intr_event.9

287

The only wrinkle here is that it is not the mere presence of threaded handlers that triggers pre_ithread. You have to have a handler whose filter requests the threaded handler to run. If a handler doesn't have a filter, then it is treated as if the filter always requests the threaded handler to run. You might want to say something like this:

When an interrupt is triggered, all filters are run to determine if any threaded interrupt handlers should be scheduled for execution by the associated interrupt thread.
If no threaded handlers are scheduled,
the
.Fa post_filter
callback is invoked which should acknowledge the interrupt and permit it to trigger in the future.
If any threaded handlers are scheduled,
the
.Fa pre_ithread
callback is invoked instead.
This handler should acknowledge the interrupt, but it should also ensure that the interrupt will not fire continuously until after the threaded handlers have executed.
Typically this callback masks level-triggered interrupts in an interrupt controller while leaving edge-triggered interrupts alone.
Once all threaded handlers have executed,
the
.Fa post_ithread
callback is invoked from the interrupt thread to enable future interrupts.
Typically this callback unmasks level-triggered interrupts in an interrupt controller.

[mhorne]

Just about there now, I think :)

Adopt jhb's text for the Handler Callbacks subsection, keeping a couple of my sentences.

Touch up the function description of intr_event_remove_handler().

[mhorne]

share/man/man9/intr_event.9

287

Thanks, the bit about level vs edge triggered interrupts is especially enlightening.

[pauamma_gundo.com]

If it's good enough for SMEs, it's good enough for me.