Add OPAL_GET_MESSAGE and struct opal_msg documentation

especially around backwards compatibility and what a host OS
should/should not do.

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

2 files changed, 66 insertions, 1 deletions

diff --git a/doc/opal-api/opal-get-message.txt b/doc/opal-api/opal-get-message.txt
new file mode 100644
index 0000000..05cc056
--- /dev/null
+++ b/doc/opal-api/opal-get-message.txt
@@ -0,0 +1,43 @@
+OPAL_GET_MESSAGE
+----------------
+
+OPAL_GET_MESSAGE will get the next pending OPAL_MESSAGE (see
+opal-messages.txt).
+
+Parameters:
+	buffer to copy message into
+	sizeof buffer to copy message into
+
+The maximum size of an opal message is specified in the device tree passed
+to the host OS:
+
+  ibm,opal {
+            opal-msg-size = <0x48>;
+  }
+
+It is ALWAYS at least 72 bytes. In the future, OPAL may have messages larger
+than 72 bytes. Naturally, a HOST OS will only be able to interpret these
+if it correctly uses opal-msg-size. Any OPAL message > 72 bytes, a host OS
+may safely ignore.
+
+A host OS *SHOULD* always supply a buffer to OPAL_GET_MESSAGE of either 72
+bytes or opal-msg-size. It MUST NOT supply a buffer of < 72 bytes.
+
+
+Return values:
+
+OPAL_RESOURCE - no available message.
+
+OPAL_PARAMETER - buffer is NULL or size is < 72 bytes.
+	         If buffer size < 72 bytes, the message will NOT be discarded
+		 by OPAL.
+
+OPAL_PARTIAL - If pending opal message is greater than supplied buffer.
+               In this case the message is *DISCARDED* by OPAL.
+	       This is to keep compatibility with host Operating Systems
+	       with a hard coded opal-msg-size of 72 bytes.
+	       NOT CURRENTLY IMPLEMENTED. Specified so that host OS can
+	       prepare for the possible future with either a sensible
+	       error message or by gracefully ignoring such OPAL messages.
+
+OPAL_SUCCESS - message successfully copied to buffer.
diff --git a/doc/opal-api/opal-messages.txt b/doc/opal-api/opal-messages.txt
index df10236..878ecc6 100644
--- a/doc/opal-api/opal-messages.txt
+++ b/doc/opal-api/opal-messages.txt
@@ -2,7 +2,29 @@ OAPL_MESSAGE
 ============
 
 The host OS can use OPAL_GET_MSG to retrive messages queued by OPAL. The
-messages are defined by enum OpalMessageType.
+messages are defined by enum OpalMessageType. The host is notified of there
+being messages to be consumed by the OPAL_EVENT_MSG_PENDING bit being set.
+
+An opal_msg is:
+struct opal_msg {
+	__be32 msg_type;
+	__be32 reserved;
+	__be64 params[8];
+};
+
+The data structure is ALWAYS at least this size (4+4+8*8 = 72 bytes). Some
+messages define fewer than eight parameters. For messages that do not
+define all eight parameters, the value in the undefined parameters is
+undefined, although can safely be memcpy()d or otherwise moved.
+
+In the device tree, there's an opal-msg-size property of the OPAL node that
+says the size of a struct opal-msg. In the future, OPAL may support larger
+messages. See OPAL_GET_MESSAGE documentation for details.
+
+  ibm,opal {
+            opal-msg-size = <0x48>;
+  }
+
 
 OPAL_MSG_ASYNC_COMP
 -------------------