From b91c0887479b84fecf87a4059d2536d8e91f282b Mon Sep 17 00:00:00 2001
From: Eliza Weisman <eliza@elizas.website>
Date: Thu, 26 Dec 2024 11:19:32 -0800
Subject: [PATCH] docs: add missing `software_irq` KIPC docs

I [recently discovered][1] that the `software_irq` KIPC call is missing
reference documentation. In fact, the KIPC documentation doesn't even
mention it (in contrast to other KIPC calls that have no documentation
but are still listed in the reference). Instead, the reference
documentation currently incorrectly states that `find_faulted_task` is
KIPC number 8, when it's actually KIPC 9 and `software_irq` is number 8.

Not adding this KIPC to the docs was an oversight on my part in PR #1661
--- my bad, sorry!

This commit adds documentation for the `software_irq` KIPC to the
reference.

[1]: https://github.com/oxidecomputer/hubris/pull/1961#discussion_r1898058287
---
 doc/interrupts.adoc |  1 +
 doc/kipc.adoc       | 48 ++++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 48 insertions(+), 1 deletion(-)

diff --git a/doc/interrupts.adoc b/doc/interrupts.adoc
index 8824af511..faddfb48e 100644
--- a/doc/interrupts.adoc
+++ b/doc/interrupts.adoc
@@ -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
diff --git a/doc/kipc.adoc b/doc/kipc.adoc
index 7db2f3607..13eb875c2 100644
--- a/doc/kipc.adoc
+++ b/doc/kipc.adoc
@@ -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
+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