diff options
author | Stewart Smith <stewart@linux.vnet.ibm.com> | 2015-02-16 14:28:25 +1100 |
---|---|---|
committer | Stewart Smith <stewart@linux.vnet.ibm.com> | 2015-02-16 14:28:25 +1100 |
commit | e0b730bb204b7bf7b62b093a54d9d3f2f0177486 (patch) | |
tree | 5e7a02f7f3ef56b2ad0c836360eed314762f9ac6 /doc | |
parent | 3147209d5be1cc9cd2f6633d72eef7aae742fbed (diff) | |
download | skiboot-e0b730bb204b7bf7b62b093a54d9d3f2f0177486.zip skiboot-e0b730bb204b7bf7b62b093a54d9d3f2f0177486.tar.gz skiboot-e0b730bb204b7bf7b62b093a54d9d3f2f0177486.tar.bz2 |
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>
Diffstat (limited to 'doc')
-rw-r--r-- | doc/opal-api/opal-get-message.txt | 43 | ||||
-rw-r--r-- | doc/opal-api/opal-messages.txt | 24 |
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 ------------------- |