diff options
Diffstat (limited to 'doc/opal-spec.txt')
| -rw-r--r-- | doc/opal-spec.txt | 201 |
1 files changed, 201 insertions, 0 deletions
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] |