Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: add missing software_irq KIPC docs #1965

Merged
merged 4 commits into from
Jan 15, 2025
Merged
Show file tree
Hide file tree
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions doc/interrupts.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,7 @@ routine. That can occur when...
- The `pending` bit is set while `enable` was already set.
- The `enable` bit is set when `pending` was previously set.

[#interrupts-from-a-tasks-perspective]
== Interrupts from a task's perspective

The `app.toml` configuration file can route interrupts to tasks, by binding
Expand Down
48 changes: 47 additions & 1 deletion doc/kipc.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -290,7 +290,53 @@ returned by a call to `get_task_dump_region` for the specified task.
A copy of the memory referred to by the specified region, starting
at `base` and running for `size` bytes.

=== `find_faulted_task` (8)
=== `software_irq` (8)

For a given task index and a notification mask for that task, this will
trigger software interrupts for any IRQ(s) mapped to bits in that task's
notification set.

Any interrupts triggered through this mechanism will be delivered to the
that task identically to an actual hardware interrupt, as described in
the <<interrupts-from-a-tasks-perspective,the documentation on interrupts>>.

==== Request

[source,rust]
----
type SoftwareIrqRequest = (u32, u32);
----

==== Preconditions

The task index (`SoftwareIrqRequest.0`) must be a valid task index.

The notification mask (`SoftwareIrqRequest.1`) should be a valid notification
mask for the specified task, and should have at least one bit set. Any bits
set in the notification mask should be assigned to hardware interrupts in
the task's build-time configuration.

The caller *must* be the supervisor (task index 0).

==== Response

[source,rust]
----
type SoftwareIrqResponse = ();
----

==== Notes

This interface is primarily intended for testing interrupt handling, and can
only be called by a task running as the supervisor. When this KIPC is called,
an actual machine interrupt is triggered and dispatched by the kernel to the
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would split this up to make it more obvious that the KIPC only triggers the interrupt, something like

When this KIPC is called, an actual machine interrupt is triggered for the relevant hardware interrupt source. The kernel then responds to the interrupt using its normal interrupt-handling infrastructure, which dispatches a notification to the subscribed task.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, I agree that's nicer.

subscribed task.

This KIPC is *not* intended for use as a general-purpose inter-task signalling
mechanism. For that purpose, a <<notifications,notification>> should be used
instead.

=== `find_faulted_task` (9)

Scans forward from a given task index searching for a faulted task. If a faulted
task is found, returns its index. Otherwise, returns zero, the index of the
Expand Down
Loading