Add some more docs for OPAL_POLL_EVENTS and OPAL_HANDLE_INTERRUPT

This is so skeleton and incomplete it's not funny

Signed-off-by: Stewart Smith <stewart@linux.vnet.ibm.com>

2 files changed, 110 insertions, 0 deletions

diff --git a/doc/opal-api/opal-handle-interrupt.txt b/doc/opal-api/opal-handle-interrupt.txt
new file mode 100644
index 0000000..efae29e
--- /dev/null
+++ b/doc/opal-api/opal-handle-interrupt.txt
@@ -0,0 +1,26 @@
+OPAL_HANDLE_INTERRUPT
+---------------------
+
+The host OS must pass all interrupts in "ibm,opal/opal-interrupts" in the
+device tree to OPAL.
+
+An example dt snippet is:
+
+  ibm,opal {
+            ...
+            opal-interrupts = <0x10 0x11 0x12 0x13 0x14 0x20010 0x20011 0x20012 0x20013 0x20014 0xffe 0xfff 0x17fe 0x17ff 0x2ffe 0x2fff 0x37fe 0x37ff 0x20ffe 0x20fff 0x217fe 0x217ff 0x22ffe 0x22fff 0x237fe 0x237ff>;
+  }
+
+When the host OS gets any of these interrupts, it must call
+OPAL_HANDLE_INTERRUPT.
+
+The OPAL_HANDLE_INTERRUPT call takes two parameters, one input and one output.
+
+uint32_t isn - the interrupt
+
+uint64_t *outstanding_event_mask - returns outstanding events for host
+	 			   OS to handle
+
+The host OS should then handle any outstanding events.
+
+See opal-poll-events.txt for documentation on events.
diff --git a/doc/opal-api/opal-poll-events.txt b/doc/opal-api/opal-poll-events.txt
new file mode 100644
index 0000000..6a0832e
--- /dev/null
+++ b/doc/opal-api/opal-poll-events.txt
@@ -0,0 +1,84 @@
+OPAL_POLL_EVENTS
+----------------
+
+Poll for outstanding events.
+
+Fills in a bitmask of pending events.
+
+Current events are:
+
+OPAL_EVENT_OPAL_INTERNAL = 0x1
+------------------------------
+Currently unused.
+
+
+OPAL_EVENT_NVRAM = 0x2
+----------------------
+Unused
+
+
+OPAL_EVENT_RTC = 0x4
+--------------------
+
+TODO: clean this up, this is just copied from hw/fsp/fsp-rtc.c:
+
+ * Because the RTC calls can be pretty slow, these functions will shoot
+ * an asynchronous request to the FSP (if none is already pending)
+ *
+ * The requests will return OPAL_BUSY_EVENT as long as the event has
+ * not been completed.
+ *
+ * WARNING: An attempt at doing an RTC write while one is already pending
+ * will simply ignore the new arguments and continue returning
+ * OPAL_BUSY_EVENT. This is to be compatible with existing Linux code.
+ *
+ * Completion of the request will result in an event OPAL_EVENT_RTC
+ * being signaled, which will remain raised until a corresponding call
+ * to opal_rtc_read() or opal_rtc_write() finally returns OPAL_SUCCESS,
+ * at which point the operation is complete and the event cleared.
+ *
+ * If we end up taking longer than rtc_read_timeout_ms millieconds waiting
+ * for the response from a read request, we simply return a cached value (plus
+ * an offset calculated from the timebase. When the read request finally
+ * returns, we update our cache value accordingly.
+ *
+ * There is two separate set of state for reads and writes. If both are
+ * attempted at the same time, the event bit will remain set as long as either
+ * of the two has a pending event to signal.
+
+
+
+OPAL_EVENT_CONSOLE_OUTPUT = 0x8
+-------------------------------
+TODO
+
+OPAL_EVENT_CONSOLE_INPUT = 0x10
+-------------------------------
+TODO
+
+OPAL_EVENT_ERROR_LOG_AVAIL = 0x20
+---------------------------------
+TODO
+
+OPAL_EVENT_ERROR_LOG = 0x40
+---------------------------
+TODO
+
+OPAL_EVENT_EPOW = 0x80
+----------------------
+TODO
+
+OPAL_EVENT_LED_STATUS = 0x100
+-----------------------------
+TODO
+
+OPAL_EVENT_PCI_ERROR = 0x200
+----------------------------
+TODO
+
+OPAL_EVENT_DUMP_AVAIL = 0x400
+-----------------------------
+Signifies that there is a pending system dump available. See OPAL_DUMP suite
+of calls for details.
+
+OPAL_EVENT_MSG_PENDING = 0x800,