diff options
Diffstat (limited to 'roms/skiboot/doc/device-tree/ibm,opal')
| -rw-r--r-- | roms/skiboot/doc/device-tree/ibm,opal/diagnostics.rst | 21 | ||||
| -rw-r--r-- | roms/skiboot/doc/device-tree/ibm,opal/dump.rst | 37 | ||||
| -rw-r--r-- | roms/skiboot/doc/device-tree/ibm,opal/firmware.rst | 44 | ||||
| -rw-r--r-- | roms/skiboot/doc/device-tree/ibm,opal/flash.rst | 48 | ||||
| -rw-r--r-- | roms/skiboot/doc/device-tree/ibm,opal/led.rst | 39 | ||||
| -rw-r--r-- | roms/skiboot/doc/device-tree/ibm,opal/nvram.rst | 13 | ||||
| -rw-r--r-- | roms/skiboot/doc/device-tree/ibm,opal/oppanel.rst | 25 | ||||
| -rw-r--r-- | roms/skiboot/doc/device-tree/ibm,opal/power-mgt.rst | 146 | ||||
| -rw-r--r-- | roms/skiboot/doc/device-tree/ibm,opal/power-mgt/occ.rst | 76 | ||||
| -rw-r--r-- | roms/skiboot/doc/device-tree/ibm,opal/power-mgt/powercap.rst | 58 | ||||
| -rw-r--r-- | roms/skiboot/doc/device-tree/ibm,opal/power-mgt/psr.rst | 53 | ||||
| -rw-r--r-- | roms/skiboot/doc/device-tree/ibm,opal/secvar.rst | 190 | ||||
| -rw-r--r-- | roms/skiboot/doc/device-tree/ibm,opal/sensor-groups.rst | 47 | ||||
| -rw-r--r-- | roms/skiboot/doc/device-tree/ibm,opal/sensors.rst | 99 | ||||
| -rw-r--r-- | roms/skiboot/doc/device-tree/ibm,opal/sysparams.rst | 38 |
15 files changed, 934 insertions, 0 deletions
diff --git a/roms/skiboot/doc/device-tree/ibm,opal/diagnostics.rst b/roms/skiboot/doc/device-tree/ibm,opal/diagnostics.rst new file mode 100644 index 000000000..96e7669eb --- /dev/null +++ b/roms/skiboot/doc/device-tree/ibm,opal/diagnostics.rst @@ -0,0 +1,21 @@ +ibm,opal/diagnostics device tree entries +======================================== + +The diagnostics node under ibm,opal describes a userspace-to-firmware +interface, supporting the runtime processor recovery diagnostics functions. + +**Note:** Some systemd init scripts look for the presence of the path +``/ibm,opal/diagnostics`` in order to run the opal-prd daemon. + +The properties of a prd node are: + +.. code-block:: dts + + / { + ibm,opal { + diagnostics { + compatible = "ibm,opal-prd"; + }; + }; + }; + diff --git a/roms/skiboot/doc/device-tree/ibm,opal/dump.rst b/roms/skiboot/doc/device-tree/ibm,opal/dump.rst new file mode 100644 index 000000000..81a09ce26 --- /dev/null +++ b/roms/skiboot/doc/device-tree/ibm,opal/dump.rst @@ -0,0 +1,37 @@ +.. _device-tree/ibm,opal/dump: + +Dump (MPIPL) Device Tree Binding +================================= + +See :ref:`mpipl` for general MPIPL information. + +dump node +--------- +.. code-block:: dts + + dump { + /* + * Memory used by OPAL to load kernel/initrd from PNOR + * (KERNEL_LOAD_BASE & INITRAMFS_LOAD_BASE). This is the + * temporary memory used by OPAL during boot. Later Linux + * kernel is free to use this memory. During MPIPL boot + * also OPAL will overwrite this memory. + * + * OPAL will advertise these memory details to kernel. + * If kernel is using these memory and needs these memory + * content for proper dump creation, then it has to reserve + * destination memory to preserve these memory ranges. + * Also kernel should pass this detail during registration. + * During MPIPL firmware will take care of preserving memory + * and post MPIPL kernel can create proper dump. + */ + fw-load-area = <0x0 0x20000000 0x0 0x8000000 0x0 0x28000000 0x0 0x8000000>; + /* Compatible property */ + compatible = "ibm,opal-dump"; + phandle = <0x98>; + /* + * This property indicates that its MPIPL boot. Kernel will use OPAL API + * to retrieve metadata tags and use metadata to create dump. + */ + mpipl-boot + }; diff --git a/roms/skiboot/doc/device-tree/ibm,opal/firmware.rst b/roms/skiboot/doc/device-tree/ibm,opal/firmware.rst new file mode 100644 index 000000000..5e76199ec --- /dev/null +++ b/roms/skiboot/doc/device-tree/ibm,opal/firmware.rst @@ -0,0 +1,44 @@ +System Firmware +=============== + +The 'firmware' node under 'ibm,opal' lists system and OPAL firmware version. + +.. code-block:: dts + + firmware { + symbol-map = <0x0 0x300ac650 0x0 0x1b3f5>; + compatible = "ibm,opal-firmware"; + ml-version = [4d 4c 20 46 57 37 37 30 2e 32 30 20 46 57 37 37 30 2e 32 30 20 46 57 37 37 30 2e 32 30]; + mi-version = <0x4d49205a 0x4c373730 0x5f303735 0x205a4c37 0x37305f30 0x3735205a 0x4c373730 0x5f303735>; + version = "skiboot-5.0-rc2"; + phandle = <0x8e>; + linux,phandle = <0x8e>; + }; + +``compatible`` + property describes OPAL compatibility. + +``symbol-map`` + property describes OPAL symbol start address and size. + +``version`` + property describes OPAL version. It replaced a property named 'git-id' early + in the POWER8 lifecycle, so may not always be present. It will be absent on + IBM FSP based systems running firmware prior to FW840. The 'version' property + is present on all GA POWER8 BMC systems. + + On POWER9 and above, it is always present. + +``mi-version`` + property describes Microcode Image. Only on IBM FSP systems. + Will (likely) not be present on POWER9 systems. + +``ml-version`` + property describes Microcode Level. Only on IBM FSP systems. + Will (likely) not be present on POWER9 systems. + +MI/ML format +------------ +:: + + <ML/MI> <T side version> <P side version> <boot side version> diff --git a/roms/skiboot/doc/device-tree/ibm,opal/flash.rst b/roms/skiboot/doc/device-tree/ibm,opal/flash.rst new file mode 100644 index 000000000..85e008cb8 --- /dev/null +++ b/roms/skiboot/doc/device-tree/ibm,opal/flash.rst @@ -0,0 +1,48 @@ +.. _device-tree/ibm,opal/flash: + +ibm,opal/flash device tree entries +================================== + +The flash@<n> nodes under ibm,opal describe flash devices that can be +accessed through the OPAL_FLASH_{READ,ERASE,WRITE} interface. + +These interfaces take an 'id' parameter, which corresponds to the ibm,opal-id +property of the node. + +The properties under a flash node are: + +- ``compatible = "ibm,opal-flash"`` + +``ibm,opal-id = <id>`` + provides the index used for the OPAL_FLASH_XXX calls to reference this + flash device + +``reg = <0 size>`` + the offset and size of the flash device + +``ibm,flash-block-size`` + the read/write/erase block size for the flash interface. Calls + to read/write/erase must be aligned to the block size. + +``#address-cells = <1>``, ``#size-cells = <1>`` + flash devices are currently 32-bit addressable + +If valid partitions are found on the flash device, then ``partition@<offset>`` +sub-nodes are added to the flash node. These match the Linux binding for +flash partitions; the reg parameter contains the offset and size of the +partition. + + +Example: + +.. code-block:: dts + + flash@0 { + reg = <0x0 0x4000000>; + compatible = "ibm,opal-flash"; + ibm,opal-id = <0x0>; + ibm,flash-block-size = <0x1000>; + #address-cells = <0x1>; + phandle = <0x100002bf>; + #size-cells = <0x1>; + }; diff --git a/roms/skiboot/doc/device-tree/ibm,opal/led.rst b/roms/skiboot/doc/device-tree/ibm,opal/led.rst new file mode 100644 index 000000000..7e062fe19 --- /dev/null +++ b/roms/skiboot/doc/device-tree/ibm,opal/led.rst @@ -0,0 +1,39 @@ +.. _device-tree/ibm,opal/leds: + +Service Indicators (LEDS) +========================= + +The 'leds' node under 'ibm,opal' lists service indicators available in the +system and their capabilities. + +.. code-block:: dts + + leds { + compatible = "ibm,opal-v3-led"; + phandle = <0x1000006b>; + linux,phandle = <0x1000006b>; + led-mode = "lightpath"; + + U78C9.001.RST0027-P1-C1 { + led-types = "identify", "fault"; + phandle = <0x1000006f>; + linux,phandle = <0x1000006f>; + }; + /* Other LED nodes like the above one */ + }; + +compatible + property describes LEDs compatibility. + +led-mode + property describes service indicator mode (lightpath/guidinglight). + +Each node under 'leds' node describes location code of FRU/Enclosure. + +The properties under each node: + +led-types + Supported indicators (attention/identify/fault). + +These LEDs can be accessed through OPAL_LEDS_{GET/SET}_INDICATOR interfaces. +Refer to :ref:`opal-api-LEDs` for interface details. diff --git a/roms/skiboot/doc/device-tree/ibm,opal/nvram.rst b/roms/skiboot/doc/device-tree/ibm,opal/nvram.rst new file mode 100644 index 000000000..e1b432f42 --- /dev/null +++ b/roms/skiboot/doc/device-tree/ibm,opal/nvram.rst @@ -0,0 +1,13 @@ +.. _device-tree/ibm,opal/nvram: + +nvram Device Tree Node +====================== + +.. code-block:: dts + + nvram { + compatible = "ibm,opal-nvram"; + #bytes = <0x90000>; + }; + +Indicates support (and size of) the :ref:`nvram` facility. diff --git a/roms/skiboot/doc/device-tree/ibm,opal/oppanel.rst b/roms/skiboot/doc/device-tree/ibm,opal/oppanel.rst new file mode 100644 index 000000000..c13949f82 --- /dev/null +++ b/roms/skiboot/doc/device-tree/ibm,opal/oppanel.rst @@ -0,0 +1,25 @@ +.. _device-tree/ibm,opal/oppanel: + +Operator Panel (oppanel) +======================== + +.. code-block:: dts + + oppanel { + compatible = "ibm,opal-oppanel"; + #lines = <0x2>; + #length = <0x10>; + }; + +The Operator Panel is a device for displaying small amounts of textual +data to an administrator. On IBM POWER8 systems with an FSP, this is a +small 16x2 LCD panel that can be viewed either from the Web UI of the FSP +(known as ASM) or by physically going to the machine and looking at the +panel. + +The operator panel does not have to be present. + +If it is, there are OPAL calls to read and write to it. + +The device tree entry is so that the host OS knows the size of the panel +and can pass buffers of the appropriate size to the OPAL calls. diff --git a/roms/skiboot/doc/device-tree/ibm,opal/power-mgt.rst b/roms/skiboot/doc/device-tree/ibm,opal/power-mgt.rst new file mode 100644 index 000000000..c8c753dad --- /dev/null +++ b/roms/skiboot/doc/device-tree/ibm,opal/power-mgt.rst @@ -0,0 +1,146 @@ +.. _power-mgt-devtree: + +ibm,opal/power-mgt device tree entries +====================================== + +.. toctree:: + :maxdepth: 2 + + power-mgt/occ + power-mgt/powercap + power-mgt/psr + + +All available CPU idle states are listed in ibm,cpu-idle-state-names + +For example: + +.. code-block:: dts + + power-mgt { + ibm,cpu-idle-state-names = "nap", "fastsleep_", "winkle"; + ibm,cpu-idle-state-residency-ns = <0x1 0x2 0x3>; + ibm,cpu-idle-state-latencies-ns = <0x1 0x2 0x3>; + }; + +The idle states are characterized by latency and residency +numbers which determine the breakeven point for entry into them. The +latency is a measure of the exit overhead from the idle state and +residency is the minimum amount of time that a CPU must be predicted +to be idle so as to reap the powersavings from entering into that idle +state. + +These numbers are made use of by the cpuidle governors in the kernel to +arrive at the appropriate idle state that a CPU must enter into when there is +no work to be done. The values in ibm,cpu-idle-state-latencies-ns are the +the measured latency numbers for the idle states. The residency numbers have +been arrived at experimentally after ensuring that the performance of latency +sensitive workloads do not regress while allowing deeper idle states to be +entered into during low load situations. The kernel is expected to use these +values for optimal power efficiency. + +Example: + +.. code-block:: dts + + / { + ibm,opal { + power-mgt { + ibm,pstate-frequencies-mhz = <0xda3 0xd82 0xd60 0xd3f 0xd1e 0xcfd 0xcdb 0xcba 0xc99 0xc78 0xc56 0xc35 0xc14 0xbf3 0xbd1 0xbb0 0xb8f 0xb6e 0xb4c 0xb2b 0xb0a 0xae9 0xac7 0xaa6 0xa85 0xa64 0xa42 0xa21 0xa00 0x9df 0x9bd 0x99c 0x97b 0x95a 0x938 0x917 0x8f6 0x8d5 0x8b3 0x892 0x871 0x850 0x82e 0x80d>; + ibm,cpu-idle-state-latencies-ns = <0xfa0 0x9c40 0x989680>; + ibm,cpu-idle-state-flags = <0x11000 0x81003 0x47003>; + ibm,cpu-idle-state-names = "nap", "fastsleep_", "winkle"; + ibm,cpu-idle-state-pmicr = <0x0 0x0 0x20 0x0 0x0 0x0>; + ibm,pstate-nominal = <0xffffffef>; + ibm,cpu-idle-state-residency-ns = <0x186a0 0x11e1a300 0x3b9aca00>; + ibm,cpu-idle-state-pmicr-mask = <0x0 0x0 0x30 0x0 0x0 0x0>; + phandle = <0x100002a0>; + ibm,pstate-ids = <0x0 0xffffffff 0xfffffffe 0xfffffffd 0xfffffffc 0xfffffffb 0xfffffffa 0xfffffff9 0xfffffff8 0xfffffff7 0xfffffff6 0xfffffff5 0xfffffff4 0xfffffff3 0xfffffff2 0xfffffff1 0xfffffff0 0xffffffef 0xffffffee 0xffffffed 0xffffffec 0xffffffeb 0xffffffea 0xffffffe9 0xffffffe8 0xffffffe7 0xffffffe6 0xffffffe5 0xffffffe4 0xffffffe3 0xffffffe2 0xffffffe1 0xffffffe0 0xffffffdf 0xffffffde 0xffffffdd 0xffffffdc 0xffffffdb 0xffffffda 0xffffffd9 0xffffffd8 0xffffffd7 0xffffffd6 0xffffffd5>; + ibm,pstate-max = <0x0>; + ibm,pstate-min = <0xffffffd5>; + }; + }; + }; + + + +ibm,cpu-idle-state-pmicr ibm,cpu-idle-state-pmicr-mask +------------------------------------------------------ +In POWER8, idle states sleep and winkle have 2 modes- fast and deep. In fast +mode, idle state puts the core into threshold voltage whereas deep mode +completely turns off the core. Choosing fast vs deep mode for an idle state +can be done either via PM_GP1 scom or by writing to PMICR special register. +If using the PMICR path to choose fast/deep mode then ibm,cpu-idle-state-pmicr +and ibm,cpu-idle-state-pmicr-mask properties expose relevant PMICR bits and +values for corresponding idle states. + + +ibm,cpu-idle-state-psscr ibm,cpu-idle-state-psscr-mask +------------------------------------------------------ +In POWER ISA v3, there is a common instruction 'stop' to enter any idle state +and SPR PSSCR is used to specify which idle state needs to be entered upon +executing stop instruction. Properties ibm,cpu-idle-state-psscr and +ibm,cpu-idle-state-psscr-mask expose the relevant PSSCR bits and values for +corresponding idle states. + + +ibm,cpu-idle-state-flags +------------------------ +These flags are used to describe the characteristics of the idle states like +the kind of core state loss caused. These flags are used by the kernel to +save/restore appropriate context while using the idle states. + + +ibm,pstate-ids +-------------- + +This property lists the available pstate identifiers, as signed 32-bit +big-endian values. While the identifiers are somewhat arbitrary, these define +the order of the pstates in other ibm,pstate-* properties. + + +ibm,pstate-frequencies-mhz +-------------------------- + +This property lists the frequency, in MHz, of each of the pstates listed in the +ibm,pstate-ids file. Each frequency is a 32-bit big-endian word. + + +ibm,pstate-max ibm,pstate-min ibm,pstate-nominal +------------------------------------------------ + +These properties give the maximum, minimum and nominal pstate values, as an id +specified in the ibm,pstate-ids file. + +ibm,pstate-ultra-turbo ibm,pstate-turbo +--------------------------------------- + +These properties are added when ultra-turbo(WOF) is enabled. These properties +give the max turbo and max ultra-turbo pstate-id as specified in the +ibm,pstate-ids file. The frequencies present in turbo to ultra-turbo range are +referred to as boost/WOF frequencies and these are attained by the CPU under +favourable environmental conditions, low workloads and low active core counts. + +Example: + +.. code-block:: dts + + power-mgt { + ibm,pstate-core-max = <0x0 0x0 0x0 0x0 0x0 0x0 0x0>; + ibm,pstate-turbo = <0xfffffffb> + ibm,pstate-ultra-turbo = <0x0>; + }; + +ibm,pstate-core-max +------------------- + +This property is added when ultra_turbo(WOF) is enabled. This property gives +the list of max pstate for each 'n' number of active cores in the chip. + +ibm,pstate-base +---------------- + +This pstate points to the base frequency of the chip. POWER9 base frequency is +the highest frequency that is guaranteed when ALL cores are active in ANY +operating condition (ie. workloads, environmental conditions such as max +ambient temperature, active core counts) diff --git a/roms/skiboot/doc/device-tree/ibm,opal/power-mgt/occ.rst b/roms/skiboot/doc/device-tree/ibm,opal/power-mgt/occ.rst new file mode 100644 index 000000000..6d80a8eed --- /dev/null +++ b/roms/skiboot/doc/device-tree/ibm,opal/power-mgt/occ.rst @@ -0,0 +1,76 @@ +ibm,opal/power-mgt/occ device tree entries +========================================== + +This node exports the per-chip pstate table properties to kernel. + +Example: + +.. code-block:: dts + + occ@7ffddf8000 { + ibm,pstate-vdds = [45 45 46 46 46 47 48 49 4a 4b 4c 4d 4f 50 51 52 53 54 55 57 58 59 5a 5b 5c 5d 5e 5f 5f 60 61 62 63 64 65 65 66 67 68 69 6a 6a 6b 6c 6d 6e 6f 70 70 71]; + ibm,chip-id = <0x1>; + phandle = <0x100003b8>; + ibm,pstate-vcss = [3b 3d 3f 41 42 44 45 46 47 48 49 4a 4b 4c 4d 4e 4f 50 50 51 52 53 54 55 56 56 57 57 58 58 59 59 5a 5a 5b 5b 5c 5c 5d 5d 5e 5e 5f 5f 60 60 61 61 62 62]; + reg = <0x7f 0xfddf8000 0xb98>; + }; + +ibm,chip-id +----------- + +This property denotes the ID of chip to which OCC belongs to. + +reg +--- + +This tuple gives the statring address of the OPAL data in HOMER and +the size of the OPAL data. + +The top-level /ibm,opal/power-mgt contains : :: + + #size-cells = <1> + #address-cells = <2> + +ibm,pstate-vcss ibm,pstate-vdds +------------------------------- + +These properties list a voltage-identifier of each of the pstates listed in +ibm,pstate-ids for the Vcs and Vdd values used for that pstate in that chip. +Each VID is a single byte. + +ibm,opal/power-mgt/freq-domain-mask +----------------------------------- + +This property is a bitmask which will have different value depending upon the +generation of the processor. Frequency domain would indicate group of CPUs +which would share same frequency. Bitwise AND is taken between this bitmask +value and PIR of cpu. All the CPUs lying in the same frequency domain will have +same result for AND. Thus frequency management can be done based on frequency +domain. A frequency domain may be a core or a quad, etc depending upon the +generation of the processor. + +For example, for POWER8 0xFFF8 indicates core wide frequency domain. Taking AND +with the PIR of CPUs will yield us a frequency domain which is core wide +distribution as last 3 bits have been masked which represent the threads. + +For POWER9, 0xFFF0 indicates quad wide frequency domain. Taking AND with +the PIR of CPUs will yield us frequency domain which is quad wise +distribution as last 4 bits have been masked which represent the cores. + +ibm,opal/power-mgt/domain-runs-at +--------------------------------- + +There are two strategies in which the OCC can change the frequency of the cores +in the quad on P9. +1) FREQ_MAX_IN_DOMAIN : the OCC sets the frequency of the quad to the maximum +of the latest frequency requested by each of the component cores. +2) FREQ_MOST_RECENTLY_SET : the OCC sets the frequency of the quad to the most +recent frequency value requested by the CPUs in the quad + +In case of P8, the domain is the core and the strategy by default is +FREQ_MOST_RECENTLY_SET since the PMCRs of the threads in the core are mirrored. +However on P9, the domain is quad and the strategy is FREQ_MAX_IN_DOMAIN since +each core has its own PMCR. + +domain-runs-at denotes the strategy which OCC is using to change the frequency +of a frequency domain. diff --git a/roms/skiboot/doc/device-tree/ibm,opal/power-mgt/powercap.rst b/roms/skiboot/doc/device-tree/ibm,opal/power-mgt/powercap.rst new file mode 100644 index 000000000..e59f6c283 --- /dev/null +++ b/roms/skiboot/doc/device-tree/ibm,opal/power-mgt/powercap.rst @@ -0,0 +1,58 @@ +.. _device-tree/ibm,opal/power-mgt/powercap: + +power-mgt/powercap +------------------ + +The powercap sensors are populated in this node. Each child node in +the "powercap" node represents a power-cappable component. + +For example : :: + + system-powercap/ + +The :ref:`OPAL_GET_POWERCAP` and :ref:`OPAL_SET_POWERCAP` calls take a handle for +what powercap property to get/set which is defined in the child node. + +The compatible property for the linux driver which will be +"ibm,opal-powercap" + +Each child node has below properties: + +`powercap-current` + Handle to indicate the current powercap + +`powercap-min` + Absolute minimum possible powercap. This points to the soft powercap minimum + limit as exported by OCC. The powercap set in the soft powercap range may or + may not be maintained. + +`powercap-max` + Maximum possible powercap + +`powercap-hard-min` + This value points to the hard minimum powercap limit. The powercap set above + this limit is guaranteed unless there is a hardware failure + +Powercap handle uses the following encoding: :: + + | Class | Reserved | Attribute | + |-------|---------------|-----------| + +Note: The format of the powercap handle is ``NOT`` ABI and may change in +the future. + +.. code-block:: dts + + power-mgt { + powercap { + compatible = "ibm,opal-powercap"; + + system-powercap { + name = "system-powercap"; + powercap-current = <0x00000002>; + powercap-min = <0x00000000>; + powercap-max = <0x00000001>; + powercap-hard-min = <0x000000003>; + }; + }; + }; diff --git a/roms/skiboot/doc/device-tree/ibm,opal/power-mgt/psr.rst b/roms/skiboot/doc/device-tree/ibm,opal/power-mgt/psr.rst new file mode 100644 index 000000000..46165b0c1 --- /dev/null +++ b/roms/skiboot/doc/device-tree/ibm,opal/power-mgt/psr.rst @@ -0,0 +1,53 @@ +power-mgt/psr +------------------ + +Some systems allow modification of how power consumption throttling +is balanced between entities in a system. A typical one may be how the power +management complex should balance throttling CPU versus the GPU. An OPAL +call can be used to set these ratios, which are described in the device +tree. + +In the future, there may be more available settings than just CPU +versus GPU. + +Each child node in the "psr" node represents a configurable psr +sensor. + +For example : :: + cpu-to-gpu@1 + +The compatible property is set to "ibm,opal-power-shift-ratio". + +Each child node has below properties: + +`handle` + Handle to indicate the type of psr + +`label` + Name of the psr sensor + +The format of the handle is internal, and ``not`` ABI, although +currently it uses the following encoding :: + + | Class |Reserved| RID | Type | + |-------|--------|------|------| + +.. code-block:: dts + + power-mgt { + psr { + compatible = "ibm,opal-power-shift-ratio"; + + cpu-to-gpu@0 { + name = "cpu-to-gpu"; + handle = <0x00000000>; + label = "cpu_to_gpu_0"; + }; + + cpu-to-gpu@1 { + name = "cpu-to-gpu"; + handle = <0x00000100>; + label = "cpu_to_gpu_1"; + }; + }; + }; diff --git a/roms/skiboot/doc/device-tree/ibm,opal/secvar.rst b/roms/skiboot/doc/device-tree/ibm,opal/secvar.rst new file mode 100644 index 000000000..dd37cab6c --- /dev/null +++ b/roms/skiboot/doc/device-tree/ibm,opal/secvar.rst @@ -0,0 +1,190 @@ +.. _device-tree/ibm,opal/secvar: + +Secvar Binding +============== + +This device tree binding describes the status of secure variable support, +including any size values, or values relating to the secure state of the +system. + + +/ibm,opal/secvar node bindings +------------------------------ + +Node: secvar + +Description: Container of secvar related properties. + +The node name must be "secvar". + +It is implemented as a child of the node "/ibm,opal". + +The node is optional, will be defined if the platform supports secure +variables. It will not be created if the system does not. + +Properties: + +- compatible + + Usage: + required + Value type: + string + + Definition: + + This property defines the compatibility of the current running + backend. This defines the binary format of the data buffers passed + via the related secvar OPAL API functions. This also defines the + expected behavior of how updates should be processed, such as how + key updates should be signed, what the key hierarchy is, what + algorithms are in use, etc. + + This value also determines how a user can signal a desire to require + all further images to require signature validations. See the + "On Enforcing Secure Mode" section below. + + This property also contains a generic "ibm,secvar-backend" compatible, + which defines the basic-level compatibility of the secvar implementation. + This includes the basic behavior of the API (excluding the data format), + and the expected device tree properties contained in this node. + +- format + + Usage: + required + Value type: + string + + This property defines the format of data passed in and out of the secvar + API. In most cases, this should be the same string as the backend-specific + string in compatible. + + The format defined by this string should be documented by the corresponding + backend. + +- status + + Usage: + required + Value type: + string + + Definition: + + This property states the general status of secure variable support. This + will be set to "okay" if the secvar OPAL API should be working as expected, + and there were no unrecoverable faults in the basic secure variable + initialization logic. + + This property may be set to "fail" if the platform does not properly + select the drivers to use. Failures may also occur if the storage devices + are inaccessible for some reason. + + Failures are NOT caused by malformed data loaded or processed in either + storage or backend drivers, as these are faults correctable by a user. + +- update-status + + Usage: + required + Value type: + <u64> + + Definition: + + This property should contain the status code of the update processing + logic, as returned by the backend. This value is intended to be + consumed by userspace tools to confirm updates were processed as + intended. + + The value contained in this property should adhere to the table below. + Any additional error states that may be specific to a backend should + be stored in the backend node. + + +- max-var-size + + Usage: + required + Value type: + <u64> + + Definition: + + This is the maximum buffer size accepted for secure variables. The API + will reject updates larger than this value, and storage drivers must + reject loading variables larger than this value. + + As this may depend on the persistant storage devices in use, this + value is determined by the storage driver, and may differ across + platforms. + +- max-var-key-len + + Usage: + required + Value type: + <u64> + + Definition: + + This is the maximum size permitted for the key of a variable. As the + value is a constant, it should be the same across platforms unless + changed in code. + + +Example +------- + +.. code-block:: dts + + /ibm,opal/secvar { + compatible = "ibm,secvar-backend" "ibm,edk2-compat-v1"; + + status = "okay"; + max-var-size = <0x1000>; + max-var-key-len = <0x400> + }; + +Update Status Code Table +------------------------ + +The update status property should be set by the backend driver to a value +that best fits its error condition. The following table defines the +general intent of each error code, check backend specific documentation +for more detail. + ++-----------------+-----------------------------------------------+ +| update-status | Generic Reason | ++-----------------+-----------------------------------------------+ +| OPAL_SUCCESS | Updates were found and processed successfully | ++-----------------+-----------------------------------------------+ +| OPAL_EMPTY | No updates were found, none processed | ++-----------------+-----------------------------------------------+ +| OPAL_PARAMETER | Malformed, or unexpected update data blob | ++-----------------+-----------------------------------------------+ +| OPAL_PERMISSION | Update failed to apply, possible auth failure | ++-----------------+-----------------------------------------------+ +| OPAL_HARDWARE | Misc. storage-related error | ++-----------------+-----------------------------------------------+ +| OPAL_RESOURCE | Out of space (reported by storage | ++-----------------+-----------------------------------------------+ +| OPAL_NO_MEM | Out of memory | ++-----------------+-----------------------------------------------+ + + +On Enforcing Secure Mode +------------------------ + +The os-secureboot-enforcing property in /ibm,secureboot/ is created by the +backend if the owner has expressed a desire for boot loaders, kernels, etc +to require any images to be signed by an appropriate key stored in secure +variables. As this property is created by the backend, it is up to the +backend to define what the required state of the secure variables should +be to enter this mode. + +For example, we may want to only enable secure boot if we have a top- +level "Platform Key", so this property is created by the backend if +by the end of update processing, a "PK" variable exists. By enrolling a +PK, the system will be in "secure mode" until the PK is deleted. diff --git a/roms/skiboot/doc/device-tree/ibm,opal/sensor-groups.rst b/roms/skiboot/doc/device-tree/ibm,opal/sensor-groups.rst new file mode 100644 index 000000000..037092365 --- /dev/null +++ b/roms/skiboot/doc/device-tree/ibm,opal/sensor-groups.rst @@ -0,0 +1,47 @@ +.. _device-tree/ibm,opal/sensor-groups: + +ibm,opal/sensor-groups +---------------------- + +This node contains all sensor groups defined in the system. +Each child node here represents a sensor group. + +For example : :: + occ-csm@1c00020/ + +The compatible property is set to "ibm,opal-sensor-group" + +Each child node has below properties: + +`type` + string to indicate the sensor group + +`sensor-group-id` + Uniquely identifies a sensor group. + +`ibm,chip-id` + This property is added if the sensor group is chip specific + +`sensors` + Phandles of all sensors belonging to this sensor group + +`ops` + Array of opal call numbers to indicate the available sensor group + operations + +.. code-block:: dts + + ibm,opal { + sensor-groups { + compatible = "ibm,opal-sensor-group"; + + occ-csm@1c00020 { + name = "occ-csm"; + type = "csm"; + sensor-group-id = <0x01c00020>; + ibm,chip-id = <0x00000008>; + ops = <0x9c>; + sensors = <0x00000175 0x00000176 0x00000177 0x00000178 0x00000179 0x0000017a 0x0000017b 0x0000017c>; + }; + }; + }; diff --git a/roms/skiboot/doc/device-tree/ibm,opal/sensors.rst b/roms/skiboot/doc/device-tree/ibm,opal/sensors.rst new file mode 100644 index 000000000..2dbdb8ae1 --- /dev/null +++ b/roms/skiboot/doc/device-tree/ibm,opal/sensors.rst @@ -0,0 +1,99 @@ +ibm,opal/sensors/ device tree nodes +----------------------------------- + +All sensors of a POWER8 system are made available to the OS in the +ibm,opal/sensors/ directory. Each sensor is identified with a node +which name follows this pattern : :: + + <resource class name>@<resource identifier>/ + +For example : :: + + core-temp@20/ + +Each node has a minimum set of properties describing the sensor : + +- a "compatible" property which should be "ibm,opal-sensor" + +- a "sensor-type" property, which can be "temp", "fan", "power". + More will be added when new resources are supported. This type + is used "as is" by the Linux driver to map sensors in the sysfs + interface of the hwmon framework of Linux. + +- a "sensor-data" property giving a unique handler for the + OPAL_SENSOR_READ call to be used by Linux to get the value of + a sensor attribute. This value is opaque to the OS but is *currently* + constructed using the following encoding : :: + + | Attr. |Fam|Res. | Resource | + | Number |ily|Class| Id | + |--------|---|-----|----------------| + + The sensor family (FSP, DTS, etc) is used to dispatch the call to + the appriopriate skiboot component. + +- a "sensor-status" property giving the state of the sensor. The + status bits have the slightly meanings depending on the resource + type but testing against 0x6 should raise an alarm. + +- an optional "label" property + +Each node can have some extra properties depending on the resource +they represent. See the tree below for more information. + +.. code-block:: dts + + ibm,opal { + sensors { + + /* + * Core temperatures (DTS) nodes. + * + * We use the PIR of the core as a resource identifier. + */ + core-temp@20 { + compatible = "ibm,opal-sensor"; + name = "core-temp"; + sensor-type = "temp"; + + /* Status bits : + * + * 0x0003 FATAL + * 0x0002 CRITICAL + * 0x0001 WARNING + */ + sensor-data = <0x00800020>; + + /* + * These are extra properties to help Linux output. + */ + ibm,pir = <0x20>; + label = "Core"; + }; + + /* + * Centaur temperatures (DTS) nodes. Open Power only. + * + * We use the PIR of the core as a resource identifier. + */ + mem-temp@1 { + compatible = "ibm,opal-sensor"; + name = "mem-temp"; + sensor-type = "temp"; + + /* Status bits : + * + * 0x0003 FATAL + * 0x0002 CRITICAL + * 0x0001 WARNING + */ + sensor-data = <0x00810001>; + + /* + * These are extra properties to help Linux output. + */ + ibm,chip-id = <0x80000001>; + label = "Centaur"; + }; + }; + }; diff --git a/roms/skiboot/doc/device-tree/ibm,opal/sysparams.rst b/roms/skiboot/doc/device-tree/ibm,opal/sysparams.rst new file mode 100644 index 000000000..8b74650db --- /dev/null +++ b/roms/skiboot/doc/device-tree/ibm,opal/sysparams.rst @@ -0,0 +1,38 @@ +.. _device-tree/ibm,opal/sysparams: + +sysparams +========= + +.. code-block:: c + + /* System parameter permission */ + enum OpalSysparamPerm { + OPAL_SYSPARAM_READ = 0x1, + OPAL_SYSPARAM_WRITE = 0x2, + OPAL_SYSPARAM_RW = (OPAL_SYSPARAM_READ | OPAL_SYSPARAM_WRITE), + }; + + +.. code-block:: dts + + sysparams { + compatible = "ibm,opal-sysparams"; + param-id = <0xf0000001 0xf0000003 0xf0000012 0xf0000016 0xf000001d 0xf0000023 0xf0000024 0xf0000025 0xf0000026 0xf0000027>; + param-name = "surveillance", "hmc-management", "cupd-policy", "plat-hmc-managed", "fw-license-policy", "world-wide-port-num", "default-boot-device", "next-boot-device", "console-select", "boot-device-path"; + param-perm = [03 01 03 03 03 02 03 03 03 03]; + phandle = <0x10000032>; + param-len = <0x4 0x4 0x4 0x4 0x4 0xc 0x1 0x1 0x1 0x30>; + linux,phandle = <0x10000032>; + }; + +Device tree node for system parameters accessible through the +:ref:`opal-sysparams` calls :ref:`OPAL_GET_PARAM` and :ref:`OPAL_SET_PARAM`. + +While many systems and platforms will support parameters and configuration via +either nvram or over IPMI, some platforms may have parameters that need to be +set a different way. + +Some parameters may be set Read Only, so the `param-perm` property indicates +permissions. + +Currently, this is only something that exists on FSP based systems. |