[Skiboot] [PATCH 043/110] doc: OPAL_START_CPU and OPAL_RETURN_CPU

[Stewart Smith]

Fixes: https://github.com/open-power/skiboot/issues/103
Signed-off-by: Stewart Smith <stewart at linux.ibm.com>
---
 doc/opal-api/opal-return-cpu-69.rst          | 19 -------
 doc/opal-api/opal-start-return-cpu-41-69.rst | 57 ++++++++++++++++++++
 2 files changed, 57 insertions(+), 19 deletions(-)
 delete mode 100644 doc/opal-api/opal-return-cpu-69.rst
 create mode 100644 doc/opal-api/opal-start-return-cpu-41-69.rst

diff --git a/doc/opal-api/opal-return-cpu-69.rst b/doc/opal-api/opal-return-cpu-69.rst
deleted file mode 100644
index 4a9631c8778f..000000000000
--- a/doc/opal-api/opal-return-cpu-69.rst
+++ /dev/null
@@ -1,19 +0,0 @@
-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_CPUS
-to set the HILE bit first).
-
-In cases where you need OPAL to do something for you across all CPUs, such
-as OPAL_REINIT_CPUS, (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.
diff --git a/doc/opal-api/opal-start-return-cpu-41-69.rst b/doc/opal-api/opal-start-return-cpu-41-69.rst
new file mode 100644
index 000000000000..7bb73a769d28
--- /dev/null
+++ b/doc/opal-api/opal-start-return-cpu-41-69.rst
@@ -0,0 +1,57 @@
+====================================
+Starting and stopping secondary CPUs
+====================================
+
+In this context, each thread is a CPU. That is, you start and stop threads of
+CPUs.
+
+.. _OPAL_START_CPU:
+
+OPAL_START_CPU
+==============
+
+.. code-block:: c
+
+   #define OPAL_START_CPU				41
+
+   int64_t opal_start_cpu_thread(uint64_t server_no, uint64_t start_address);
+
+Returns
+-------
+
+:ref:`OPAL_SUCCESS`
+     The CPU was instructed to start executing instructions from the specified
+     `start_address`.
+     This is an *asynchronous* operation, so it may take a short period of
+     time before the CPU actually starts at that address.
+:ref:`OPAL_PARAMETER`
+     Invalid CPU.
+:ref:`OPAL_WRONG_STATE`
+     If the CPU thread is not in OPAL, or is being re-initialized through :ref:`OPAL_REINIT_CPUS`
+:ref:`OPAL_INTERNAL_ERROR`
+     Something else went horribly wrong.
+
+.. _OPAL_RETURN_CPU:
+
+OPAL_RETURN_CPU
+===============
+
+.. code-block:: c
+
+   #define OPAL_RETURN_CPU				69
+
+   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_CPUS
+to set the HILE bit first).
+
+In cases where you need OPAL to do something for you across all CPUs, such
+as OPAL_REINIT_CPUS, (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.21.0