[Skiboot] [PATCH 051/110] doc: Flesh out OPAL_(READ|WRITE)_TPO and OPAL_GET_DPO_STATUS docs
Stewart Smith
stewart at linux.ibm.com
Fri May 31 16:12:52 AEST 2019
Fixes: https://github.com/open-power/skiboot/issues/130
Signed-off-by: Stewart Smith <stewart at linux.ibm.com>
---
doc/opal-api/opal-messages.rst | 1 +
doc/opal-api/opal-read-write-tpo-103-104.rst | 15 ----
.../opal-read-write-tpo-dpo-103-104-105.rst | 82 +++++++++++++++++++
3 files changed, 83 insertions(+), 15 deletions(-)
delete mode 100644 doc/opal-api/opal-read-write-tpo-103-104.rst
create mode 100644 doc/opal-api/opal-read-write-tpo-dpo-103-104-105.rst
diff --git a/doc/opal-api/opal-messages.rst b/doc/opal-api/opal-messages.rst
index e7de77d96850..54ef340b7173 100644
--- a/doc/opal-api/opal-messages.rst
+++ b/doc/opal-api/opal-messages.rst
@@ -125,6 +125,7 @@ Notes:
} u;
};
+.. _OPAL_MSG_DPO:
OPAL_MSG_DPO
------------
diff --git a/doc/opal-api/opal-read-write-tpo-103-104.rst b/doc/opal-api/opal-read-write-tpo-103-104.rst
deleted file mode 100644
index b46500650376..000000000000
--- a/doc/opal-api/opal-read-write-tpo-103-104.rst
+++ /dev/null
@@ -1,15 +0,0 @@
-OPAL_READ_TPO and OPAL_WRITE_TPO
-================================
-
-TPO is a Timed Power On facility.
-
-It is an OPTIONAL part of the OPAL spec.
-
-If a platform supports Timed Power On (TPO), the RTC node in the device tree (itself under the "ibm,opal" node will have the has-tpo property: ::
-
- rtc {
- compatible = "ibm,opal-rtc";
- has-tpo;
- };
-
-If the "has-tpo" proprety is *NOT* present then OPAL does *NOT* support TPO.
diff --git a/doc/opal-api/opal-read-write-tpo-dpo-103-104-105.rst b/doc/opal-api/opal-read-write-tpo-dpo-103-104-105.rst
new file mode 100644
index 000000000000..52bb67e3870a
--- /dev/null
+++ b/doc/opal-api/opal-read-write-tpo-dpo-103-104-105.rst
@@ -0,0 +1,82 @@
+
+=========================================
+OPAL Timed Power On and Delayed Power Off
+=========================================
+
+.. code-block:: c
+
+ #define OPAL_WRITE_TPO 103
+ #define OPAL_READ_TPO 104
+ #define OPAL_GET_DPO_STATUS 105
+
+TPO is a Timed Power On facility, and DPO is Delayed Power Off.
+
+It is an OPTIONAL part of the OPAL spec.
+
+If a platform supports Timed Power On (TPO), the RTC node in the device tree
+(itself under the "ibm,opal" node will have the has-tpo property:
+
+.. code-block:: dts
+
+ rtc {
+ compatible = "ibm,opal-rtc";
+ has-tpo;
+ };
+
+If the "has-tpo" proprety is *NOT* present then OPAL does *NOT* support TPO.
+
+.. _OPAL_READ_TPO:
+
+OPAL_READ_TPO
+=============
+
+.. code-block:: c
+
+ #define OPAL_READ_TPO 104
+
+ static int64_t opal_read_tpo(uint64_t async_token, uint32_t *y_m_d, uint32_t *hr_min);
+
+
+.. _OPAL_WRITE_TPO:
+
+OPAL_WRITE_TPO
+==============
+
+.. code-block:: c
+
+ #define OPAL_WRITE_TPO 103
+
+ int64_t fsp_opal_tpo_write(uint64_t async_token, uint32_t y_m_d, uint32_t hr_min);
+
+
+.. _OPAL_GET_DPO_STATUS:
+
+OPAL_GET_DPO_STATUS
+===================
+
+.. code-block:: c
+
+ #define OPAL_GET_DPO_STATUS 105
+
+ static int64_t opal_get_dpo_status(int64_t *dpo_timeout);
+
+A :ref:`OPAL_MSG_DPO` message may be sent to indicate that there will shortly
+be a forced system shutdown. In this case, an OS can call
+:ref:`OPAL_GET_DPO_STATUS` to find out how many seconds it has before power
+is cut to the system.
+
+This call could be present on systems where the service processor is integrated
+with a UPS or similar.
+
+Returns zero if Delayed Power Off is not active, positive value indicating
+number of seconds remaining for a forced system shutdown. This will enable
+the host to schedule for shutdown voluntarily before timeout occurs.
+
+Returns
+-------
+
+:ref:`OPAL_SUCCESS`
+ ``dpo_timeout`` is set to the number of seconds remaining before power is
+ cut.
+:ref:`OPAL_WRONG_STATE`
+ A Delayed Power Off is not pending, ``dpo_timeout`` is set to zero.
--
2.21.0
More information about the Skiboot
mailing list