From aa527e9a60eb1f28847ab0faded599b4b97d593b Mon Sep 17 00:00:00 2001 From: Stewart Smith Date: Wed, 24 Dec 2014 12:09:26 +1100 Subject: Initial stab at OPAL Spec and some API docs. All very early. Comments/review needed. Signed-off-by: Stewart Smith --- doc/opal-api/opal-console-read-write-1-2.txt | 66 +++++++++ doc/opal-api/opal-test-0.txt | 30 ++++ doc/opal-api/return-codes.txt | 78 +++++++++++ doc/opal-spec.txt | 201 +++++++++++++++++++++++++++ 4 files changed, 375 insertions(+) create mode 100644 doc/opal-api/opal-console-read-write-1-2.txt create mode 100644 doc/opal-api/opal-test-0.txt create mode 100644 doc/opal-api/return-codes.txt create mode 100644 doc/opal-spec.txt 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 : 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] -- cgit v1.1