doc/opal-spec.rst - skiboot - Git at Google

 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.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 uncompressed 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
   (whether replacing skiroot with an implementation of Zork would be compliant
   is left as an exercise for the reader)

 Payload Environment
 -------------------
 The payload is started with:

 ======== =====
 Register Value
 ======== =====
 r3       address of flattened device-tree (fdt)
 r8       OPAL base
 r9       OPAL entry
 ======== =====

 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..r10: Args (up to 8)

 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.

 Machine state across OPAL calls:

 * r1 is preserved
 * r12 is scratch
 * r13 - 31 preserved
 * 64bit HV real mode
 * big endian
 * external interrupts disabled

 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 :ref:`device-tree` for more details.

 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:

 .. code-block:: dts

  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:

 .. code-block:: dts

  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 :ref:`versioning`.


 OPAL log
 --------

 OPAL implementation 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]
	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.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 uncompressed 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
	(whether replacing skiroot with an implementation of Zork would be compliant
	is left as an exercise for the reader)

	Payload Environment
	-------------------
	The payload is started with:

	======== =====
	Register Value
	======== =====
	r3 address of flattened device-tree (fdt)
	r8 OPAL base
	r9 OPAL entry
	======== =====

	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..r10: Args (up to 8)

	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.

	Machine state across OPAL calls:

	* r1 is preserved
	* r12 is scratch
	* r13 - 31 preserved
	* 64bit HV real mode
	* big endian
	* external interrupts disabled

	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 :ref:`device-tree` for more details.

	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:

	.. code-block:: dts

	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:

	.. code-block:: dts

	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 :ref:`versioning`.


	OPAL log
	--------

	OPAL implementation 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]