Initial stab at OPAL Spec and some API docs.

All very early. Comments/review needed.

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

4 files changed, 375 insertions, 0 deletions

diff --git a/doc/opal-api/opal-console-read-write-1-2.txt b/doc/opal-api/opal-console-read-write-1-2.txt
new file mode 100644
index 0000000..b8fbc12
--- /dev/null
+++ b/doc/opal-api/opal-console-read-write-1-2.txt
@@ -0,0 +1,66 @@
+OPAL Console calls
+------------------
+
+There are three OPAL calls relating to the OPAL console:
+
+#define OPAL_CONSOLE_WRITE			1
+#define OPAL_CONSOLE_READ			2
+#define OPAL_CONSOLE_WRITE_BUFFER_SPACE		25
+
+The OPAL console calls can support multiple consoles. Each console MUST
+be represented in the device tree.
+
+A conforming implementation SHOULD have at least one console. It is valid
+for it to simply be an in-memory buffer and only support writing.
+
+[TODO: details on device tree specs for console]
+
+OPAL_CONSOLE_WRITE
+------------------
+
+Parameters:
+	int64_t term_number
+	int64_t *length,
+        const uint8_t *buffer
+
+Returns:
+	OPAL_SUCCESS
+	OPAL_PARAMETER - invalid term_number
+	OPAL_CLOSED - console device closed
+	OPAL_BUSY_EVENT - unable to write any of buffer
+
+term_number is the terminal number as represented in the device tree.
+length is a pointer to the length of buffer.
+
+A conformining implementation SHOULD try to NOT do partial writes, although
+partial writes and not writing anything are valid.
+
+OPAL_CONSOLE_WRITE_BUFFER_SPACE
+-------------------------------
+
+Parameters:
+	int64_t term_number
+	int64_t *length
+
+Returns:
+	OPAL_SUCCESS
+	OPAL_PARAMETER - invalid term_number
+
+Returns the available buffer length for OPAL_CONSOLE_WRITE in *length.
+This call can be used to help work out if there is sufficient buffer
+space to write your full message to the console with OPAL_CONSOLE_WRITE.
+
+OPAL_CONSOLE_READ
+-----------------
+
+Parameters:
+	int64_t term_number
+	int64_t *length
+	uint8_t *buffer
+
+Returns:
+	OPAL_SUCCESS
+	OPAL_PARAMETER - invalid term_number
+	OPAL_CLOSED
+
+Use OPAL_POLL_EVENTS for how to determine
diff --git a/doc/opal-api/opal-test-0.txt b/doc/opal-api/opal-test-0.txt
new file mode 100644
index 0000000..f732227
--- /dev/null
+++ b/doc/opal-api/opal-test-0.txt
@@ -0,0 +1,30 @@
+OPAL_TEST
+---------
+
+OPAL_TEST is a REQUIRED call for OPAL and conforming implementations MUST
+have it.
+
+It is designed to test basic OPAL call functionality.
+
+Token:
+#define OPAL_TEST				0
+
+Arguments:
+	uint64_t	arg
+
+Returns:
+	0xfeedf00d
+
+
+Function:
+OPAL_TEST MAY print a string to the OPAL log with the value of argument.
+
+For example, the reference implementation (skiboot) implements OPAL_TEST as:
+
+static uint64_t opal_test_func(uint64_t arg)
+{
+        printf("OPAL: Test function called with arg 0x%llx\n", arg);
+
+        return 0xfeedf00d;
+}
+
diff --git a/doc/opal-api/return-codes.txt b/doc/opal-api/return-codes.txt
new file mode 100644
index 0000000..48e2c42
--- /dev/null
+++ b/doc/opal-api/return-codes.txt
@@ -0,0 +1,78 @@
+OPAL API Return Codes
+---------------------
+
+All OPAL calls return an integer relaying the success/failure of the OPAL
+call.
+
+Success is typically indicated by OPAL_SUCCESS. Failure is always indicated
+by a negative return code.
+
+Conforming host Operating Systems MUST handle return codes other than those
+listed here. In future OPAL versions, additional return codes may be added.
+
+In the reference implementation (skiboot) these are all in include/opal.h.
+
+
+The core set of return codes are:
+
+#define OPAL_SUCCESS		0
+Success!
+
+#define OPAL_PARAMETER		-1
+A parameter was invalid.
+
+#define OPAL_BUSY		-2
+Try again later.
+
+#define OPAL_PARTIAL		-3
+The operation partially succeeded.
+
+#define OPAL_CONSTRAINED	-4
+#define OPAL_CLOSED		-5
+#define OPAL_HARDWARE		-6
+
+#define OPAL_UNSUPPORTED	-7
+Unsupported operation. Non-fatal.
+
+#define OPAL_PERMISSION		-8
+Inadequate permission to perform the operation.
+
+
+#define OPAL_NO_MEM		-9
+Indicates a temporary or permanent lack of adequate memory to perform the
+operation. Ideally, this should never happen. Skiboot reserves a small amount
+of memory for its heap and some operations (such as I2C requests) are allocated
+from this heap.
+
+If this is ever hit, you should likely file a bug.
+
+
+#define OPAL_RESOURCE		-10
+#define OPAL_INTERNAL_ERROR	-11
+#define OPAL_BUSY_EVENT		-12
+#define OPAL_HARDWARE_FROZEN	-13
+#define OPAL_WRONG_STATE	-14
+
+#define OPAL_ASYNC_COMPLETION	-15
+For asynchronous calls, successfully queueing/starting executing the
+command is indicated by the OPAL_ASYNC_COMPLETION return code.
+pseudo-code for an async call:
+  token = opal_async_get_token();
+  rc = opal_async_example(foo, token);
+  if (rc != OPAL_ASYNC_COMPLETION)
+      handle_error(rc);
+  rc = opal_async_wait(token);
+  // handle result here
+
+#define OPAL_EMPTY		-16
+
+Added for I2C, only applicable to I2C calls:
+#define OPAL_I2C_TIMEOUT	-17
+#define OPAL_I2C_INVALID_CMD	-18
+#define OPAL_I2C_LBUS_PARITY	-19
+#define OPAL_I2C_BKEND_OVERRUN	-20
+#define OPAL_I2C_BKEND_ACCESS	-21
+#define OPAL_I2C_ARBT_LOST	-22
+#define OPAL_I2C_NACK_RCVD	-23
+#define OPAL_I2C_STOP_ERR	-24
+ 
diff --git a/doc/opal-spec.txt b/doc/opal-spec.txt
new file mode 100644
index 0000000..5f95557
--- /dev/null
+++ b/doc/opal-spec.txt
@@ -0,0 +1,201 @@
+OPAL Specification
+==================
+
+DRAFT - VERSION 0.0.1 AT BEST.
+
+COMMENTS ARE WELCOME - and indeed, needed.
+
+If you are reading this, congratulations: you're now reviewing it!
+
+
+This document aims to define what it means to be OPAL compliant.
+
+While skiboot is the reference implementation, this documentation should
+be complete enough that (given hardware documentation) create another
+implementation. It is not recommended that you do this though.
+
+Authors
+-------
+Stewart Smith <stewart@linux.vnet.ibm.com> : OPAL Architect, IBM
+
+
+Definitions
+-----------
+
+Host processor - the main POWER CPU (e.g. the POWER8 CPU)
+Host OS - the operating system running on the host processor.
+OPAL - OpenPOWER Abstraction Layer.
+
+What is OPAL?
+-------------
+
+The OpenPower Abstraction Layer (OPAL) is boot and runtime firmware for
+POWER systems. There are several components to what makes up a firmware
+image for OpenPower machines.
+
+For example, there may be:
+- BMC firmware
+  - Firmware that runs purely on the BMC.
+  - On IBM systems that have an FSP rather than a BMC, there is FSP firmware
+  - While essential to having the machine function, this firmware is not
+    part of the OPAL Specification.
+- HostBoot
+  - HostBoot ( https://github.com/open-power/hostboot ) performs all
+    processor, bus and memory initialization within IBM POWER based systems.
+- OCC Firmware
+  - On Chip Controller ( Firmware for OCC - a PPC405 core inside the IBM
+    POWER8 in charge of keeping the system thermally and power safe ).
+- SkiBoot
+  - Boot and runtime services.
+- A linux kernel and initramfs incorporating petitboot
+  - The bootloader. This is where a user chooses what OS to boot, and
+    petitboot will use kexec to switch to the host Operating System
+    (for example, PowerKVM).
+
+While all of these components may be absolutely essential to power on,
+boot and operate a specific OpenPower POWER8 system, the majority of
+the code mentioned above can be thought of as implementation details
+and not something that should form part of an OPAL Specification.
+
+For an OPAL system, we assume that the hardware is functioning and any
+hardware management that is specific to a platform is performed by OPAL
+firmware transparently to the host OS.
+
+The OPAL Specification focus on the interface between firmware and the
+Operating System. It does not dictate that any specific pieces of firmware
+code be used, although re-inventing the wheel is strongly discouraged.
+
+The OPAL Specification explicitly allows for:
+- A conforming implementation to not use any of the reference implementation
+  code.
+- A conforming implementation to use any 64bit POWER ISA conforming processor,
+  and not be limited to the IBM POWER8.
+- A conforming implementation to be a simulator, emulator or virtual environment
+- A host OS other than Linux
+
+Explicitly not covered in this specification:
+- A 32bit OPAL Specification
+  There is no reason this couldn't exist but the current specification is for
+  64bit POWER systems only.
+
+
+Boot Services
+-------------
+
+An OPAL compliant firmware implementation will load and execute a payload
+capable of booting a Host Operating System.
+
+The reference implementation loads a Linux kernel with an initramfs with
+a minimal userspace and the petitboot boot loader - collectively referred
+to as skiroot.
+
+The OPAL Specification explicitly allows variation in this payload.
+
+A requirement of the payload is that it MUST support loading and booting
+an uncomppressed vmlinux Linux kernel.
+[TODO: expand on what this actually means]
+
+An OPAL system MUST pass a device tree to the host kernel.
+[TODO: expand the details, add device-tree section and spec]
+
+An OPAL system MUST provide the host kernel with enough information to
+know how to call OPAL runtime services.
+[TODO: expand on this. ]
+
+Explicitly not covered by the OPAL Specification:
+- Kernel module ABI for skiroot kernel
+- Userspace environment of skiroot
+- That skiroot is Linux.
+
+Explicitly allowed:
+- Replacing the payload with something of equal/similar functionality
+  (weather replacing skiroot with an implementation of Zork would be compliant
+   is left as an exercise for the reader)
+
+
+Runtime Services
+----------------
+
+An OPAL Specification compliant system provides runtime services to the host
+Operating System via a standard interface.
+
+An OPAL call is made by calling opal_entry with:
+ *       r0: OPAL Token
+ *       r2: OPAL Base
+ *  r3..r11: Args
+
+The OPAL API is defined in skiboot/doc/opal-api/
+
+Not all OPAL APIs must be supported for a system to be compliant. When
+called with an unsupported token, a compliant firmware implementation
+MUST fail gracefully and not crash. Reporting a warning that an unsupported
+token was called is okay, as compliant host Operating Systems should use
+OPAL_CHECK_TOKEN to test for optional functionality.
+
+All parameters to OPAL calls are big endian. Little endian hosts MUST
+appropriately convert parameters before passing them to OPAL. 
+
+Detecting OPAL Support
+----------------------
+
+A Host OS may need to detect the presence of OPAL as it may support booting
+under other platforms. For example, a single Linux kernel can be built to boot
+under OPAL and under PowerVM or qemu pseries machine type.
+
+The root node of the device tree MUST have compatible = "ibm,powernv".
+See doc/device-tree.txt for more details
+[TODO: make doc/device-tree.txt better]
+
+The presence of the "/ibm,opal" entry in the device tree signifies running
+under OPAL. Additionally, the "/ibm,opal" node MUST have a compatibile property
+listing "ibm,opal-v3".
+
+The "/ibm,opal" node MUST have the following properties:
+
+ibm,opal {
+	  compatible = "ibm,opal-v3";
+	  opal-base-address = <>;
+	  opal-entry-address = <>;
+	  opal-runtime-size = <>;
+}
+
+The compatible property MAY have other strings, such as a future "ibm,opal-v4".
+These are reserved for future use.
+
+Some releases of the reference implementation (skiboot) have had compatible
+contain "ibm,opal-v2" as well as "ibm,opal-v3". Host operating systems MUST
+NOT rely on "ibm,opal-v2", this is a relic from early OPAL history.
+
+The "ibm,opal" node MUST have a child node named "firmware". It MUST contain
+the following:
+
+firmware {
+	 compatible = "ibm,opal-firmware";
+}
+
+It MUST contain one of the following two properties: git-id, version.
+The git-id property is deprecated, and version SHOULD be used. These
+are informative and MUST NOT be used by the host OS to determine anything
+about the firmware environment.
+
+The version property is a textual representation of the OPAL version.
+For example, it may be "skiboot-4.1" or other versioning described
+in more detail in doc/versioning.txt
+
+
+OPAL log
+--------
+
+OPAL implementations SHOULD have an in memory log where informational and
+error messages are stored. If present it MUST be human readable and text based.
+There is a separate facility (Platform Error Logs) for machine readable errors.
+
+A conforming implementation MAY also output the log to a serial port or similar.
+An implementation MAY choose to only output certain log messages to a serial
+port.
+
+For example, the reference implementation (skiboot) by default filters log
+messages so that only higher priority log messages go over the serial port
+while more messages go to the in memory buffer.
+
+[TODO: add device-tree bits here]