Add documentation for OPAL_(UN)REGISTER_DUMP_REGION

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

2 files changed, 61 insertions, 0 deletions

diff --git a/doc/opal-api/opal-register-dump-region-101.txt b/doc/opal-api/opal-register-dump-region-101.txt
new file mode 100644
index 0000000..e88e8cf
--- /dev/null
+++ b/doc/opal-api/opal-register-dump-region-101.txt
@@ -0,0 +1,43 @@
+OPAL_REGISTER_DUMP_REGION
+-------------------------
+
+This call is used to register regions of memory for a service processor to capture
+when the host crashes.
+
+e.g. if an assert is hit in OPAL, a service processor will copy 
+
+This is an OPTIONAL feature that may be unsupported, the host OS should use an
+OPAL_CHECK_TOKEN call to find out if OPAL_REGISTER_DUMP_REGION is supported.
+
+OPAL_REGISTER_DUMP_REGION accepts 3 parameters:
+- region ID
+- address
+- length
+
+There is a range of region IDs that can be used by the host OS. A host OS should
+start from OPAL_DUMP_REGION_HOST_END and work down if it wants to add a not well
+defined region to dump. Currently the only well defined region is for the host
+OS log buffer (e.g. dmesg on linux).
+
+/*
+ * Dump region ID range usable by the OS
+ */
+#define OPAL_DUMP_REGION_HOST_START		0x80
+#define OPAL_DUMP_REGION_LOG_BUF		0x80
+#define OPAL_DUMP_REGION_HOST_END		0xFF
+
+OPAL_REGISTER_DUMP_REGION will return OPAL_UNSUPPORTED if the call is present but
+the system doesn't support registering regions to be dumped.
+
+In the event of being passed an invalid region ID, OPAL_REGISTER_DUMP_REGION will
+return OPAL_PARAMETER.
+
+Systems likely have a limit as to how many regions they can support being dumped. If
+this limit is reached, OPAL_REGISTER_DUMP_REGION will return OPAL_INTERNAL_ERROR.
+
+BUGS:
+Some skiboot versions incorrectly returned OPAL_SUCCESS in the case of
+OPAL_REGISTER_DUMP_REGION being supported on a platform (so the call was present)
+but the call being unsupported for some reason (e.g. on an IBM POWER7 machine).
+
+See also: OPAL_UNREGISTER_DUMP_REGION
diff --git a/doc/opal-api/opal-unregister-dump-region-102.txt b/doc/opal-api/opal-unregister-dump-region-102.txt
new file mode 100644
index 0000000..268d501
--- /dev/null
+++ b/doc/opal-api/opal-unregister-dump-region-102.txt
@@ -0,0 +1,18 @@
+OPAL_UNREGISTER_DUMP_REGION
+---------------------------
+
+While OPAL_REGISTER_DUMP_REGION registers a region, OPAL_UNREGISTER_DUMP_REGION
+will unregister a region by region ID.
+
+OPAL_UNREGISTER_DUMP_REGION takes one argument: the region ID.
+
+A host OS should check OPAL_UNREGISTER_DUMP_REGION is supported through a call to
+OPAL_CHECK_TOKEN.
+
+If OPAL_UNREGISTER_DUMP_REGION is called on a system where the call is present but
+unsupported, it will return OPAL_UNSUPPORTED.
+
+BUGS:
+Some skiboot versions incorrectly returned OPAL_SUCCESS in the case of
+OPAL_UNREGISTER_DUMP_REGION being supported on a platform (so the call was present)
+but the call being unsupported for some reason (e.g. on an IBM POWER7 machine).