[Skiboot] [PATCH 1/2] Document OPAL_RETURN_CPU and OPAL_REINIT_CPUS

[Stewart Smith]

Signed-off-by: Stewart Smith <stewart at linux.vnet.ibm.com>
---
 doc/opal-api/opal-reinit-cpus-70.txt | 27 +++++++++++++++++++++++++++
 doc/opal-api/opal-return-cpu-69.txt  | 17 +++++++++++++++++
 2 files changed, 44 insertions(+)
 create mode 100644 doc/opal-api/opal-reinit-cpus-70.txt
 create mode 100644 doc/opal-api/opal-return-cpu-69.txt

diff --git a/doc/opal-api/opal-reinit-cpus-70.txt b/doc/opal-api/opal-reinit-cpus-70.txt
new file mode 100644
index 000000000000..27f6f2e89ba4
--- /dev/null
+++ b/doc/opal-api/opal-reinit-cpus-70.txt
@@ -0,0 +1,27 @@
+OPAL_REINIT_CPUS
+----------------
+
+static int64_t opal_reinit_cpus(uint64_t flags);
+
+This OPAL call reinitializes some bit of CPU state across *ALL* CPUs.
+Consequently, all CPUs must be in OPAL for this call to succeed (either
+at boot time or after OPAL_RETURN_CPU is called)
+
+Arguments:
+Currently, possible flags are:
+enum {
+	OPAL_REINIT_CPUS_HILE_BE	= (1 << 0),
+	OPAL_REINIT_CPUS_HILE_LE	= (1 << 1),
+};
+
+Extra flags may be added in the future, so other bits *must* be 0.
+
+On POWER7 CPUs, only OPAL_REINIT_CPUS_HILE_BE is supported. All other
+flags will return OPAL_UNSUPPORTED.
+
+On POWER8 CPUs, only OPAL_REINIT_CPUS_HILE_BE and OPAL_REINIT_CPUS_HILE_LE
+are support and other bits *MUST NOT* be set.
+
+Returns:
+- OPAL_SUCCESS
+- OPAL_UNSUPPORTED
diff --git a/doc/opal-api/opal-return-cpu-69.txt b/doc/opal-api/opal-return-cpu-69.txt
new file mode 100644
index 000000000000..db54caee9ead
--- /dev/null
+++ b/doc/opal-api/opal-return-cpu-69.txt
@@ -0,0 +1,17 @@
+OPAL_RETURN_CPU
+---------------
+
+int64_t opal_return_cpu(void);
+
+When OPAL first starts the host, all secondary CPUs are spinning in OPAL.
+To start them, one must call OPAL_START_CPU (you may want to OPAL_REINIT_CPU
+to set the HILE bit first).
+
+In cases where you need OPAL to do something for you across all CPUs, such
+as OPAL_REINIT_CPU, (on some platforms) a firmware update or get the machine
+back into a similar state as to when the host OS was started (e.g. for kexec)
+you may also need to return control of the CPU to OPAL.
+
+
+Returns:
+- this call does not return. You need to OPAL_START_CPU.
-- 
2.1.4