diff options
| author |   Angelos Mouzakitis <a.mouzakitis@virtualopensystems.com> | 2023-10-10 14:33:42 +0000 |
|---|---|---|
| committer | Angelos Mouzakitis <a.mouzakitis@virtualopensystems.com> | 2023-10-10 14:33:42 +0000 |
| commit | af1a266670d040d2f4083ff309d732d648afba2a (patch) | |
| tree | 2fc46203448ddcc6f81546d379abfaeb323575e9 /roms/skiboot/doc/device-tree | |
| parent | e02cda008591317b1625707ff8e115a4841aa889 (diff) | |
Change-Id: Iaf8d18082d3991dec7c0ebbea540f092188eb4ec
Diffstat (limited to 'roms/skiboot/doc/device-tree')
32 files changed, 2465 insertions, 0 deletions
diff --git a/roms/skiboot/doc/device-tree/ibm,cvc.rst b/roms/skiboot/doc/device-tree/ibm,cvc.rst new file mode 100644 index 000000000..c53df2405 --- /dev/null +++ b/roms/skiboot/doc/device-tree/ibm,cvc.rst @@ -0,0 +1,47 @@ +.. _device-tree/ibm,cvc: + +ibm,cvc +======= + +This describes the code (a.k.a container verification code) that skiboot uses +to verify signed firmware blobs. Each ibm,cvc child node describes CVC service, +which has a version and offset (reg). + +Added in the device tree from ``ibm,secureboot-v2``. + +Required properties +------------------- + +.. code-block:: none + + compatible: should be "ibm,container-verification-code" + + memory-region: this points to the reserved memory where the + container-verification-code is stored. + +Example +------- + +.. code-block:: dts + + ibm,cvc { + phandle = <0x10f>; + #address-cells = <0x1>; + #size-cells = <0x0>; + compatible = "ibm,container-verification-code"; + memory-region = <0xaa>; + + ibm,cvc-service@40 { + phandle = <0x110>; + compatible = "ibm,cvc-sha512"; + reg = <0x40>; + version = <0x1>; + }; + + ibm,cvc-service@50 { + phandle = <0x111>; + compatible = "ibm,cvc-verify"; + reg = <0x50>; + version = <0x1>; + }; + }; diff --git a/roms/skiboot/doc/device-tree/ibm,firmware-versions.rst b/roms/skiboot/doc/device-tree/ibm,firmware-versions.rst new file mode 100644 index 000000000..99cd6b22b --- /dev/null +++ b/roms/skiboot/doc/device-tree/ibm,firmware-versions.rst @@ -0,0 +1,139 @@ +ibm,firmware-versions node +========================== + +The `ibm,firmware-versions` node contains information on the versions of +various firmware components as they were **during boot**. It **does not** +change if there are pending or runtime updates. It represents (to the best +of boot firmware's ability) what versions of firmware were during this boot. + +================= ======== ============================================ +Property Required Value +================= ======== ============================================ +version POWER9 See below +skiboot N component version number +occ N component version number +buildroot N component version number +capp-ucode N component version number +petitboot N component version number +open-power N component version number +hostboot-binaries N component version number +MACHINE-xml N MACHINE (e.g. habanero) machine XML version +hostboot N component version number +linux N component version number +================= ======== ============================================ + +``version`` property +^^^^^^^^^^^^^^^^^^^^ + +This property **must** exist on POWER9 and above systems. It **may** exist +on POWER8 systems. + +If this property exists, it **must** conform to this specification. +It's a single version number of the firmware image. In the event of a system +supporting multiple firmware sides, this represents the **default** boot side. +That is, the version that is applicable when determining if a machine +requires a firmware update. + +Examples (for three different platforms): + +- ``IBM-sandwich-20170217`` +- ``open-power-habanero-v1.14-45-g78d89280c3f9-dirty`` +- ``open-power-SUPERMICRO-P8DTU-V2.00.GA2-20161028`` + +To compare two versions (for the purpose of determining if the current +installed firmware is in need of updating to the one being compared against) +we need a defined set of rules on how to do this comparison. + +Version numbers are **not** intended to be compared across platforms. + +The version string may include a description at the start of it. This +description can contain any set of characters but **must not** contain +a '-' followed by a digit. It also **must not** contain '-v' or '-V' followed +by a digit. + +Each part of the version string is separated by a '-' character. Leading +sections are ignored, until one starts with a digit (0-9) or a 'v' or 'V', +followed by a digit. Where there is a leading 'v' or 'V', it is also stripped. + +For the above three examples, we'd be left with: + +- ``20170217`` +- ``1.14-45-g78d89280c3f9-dirty`` +- ``2.00.GA2-20161028`` + +Each section is now compared until a difference is found. All comparisons +are done *lexically*. The lexical comparison sorts in this order: tilde (~), +all letters, non-letters. The tilde is special and sorts before an end of part. +This allows the common usage of designating pre-release builds by a tailing +section beginning with a '~'. + +For example: "1.0~20170217", "1.0~rc4" and "1.0~beta1" all sort +**before** "1.0" + +Note that "1.0beta" sorts **after** "1.0" + +The start of the version string contains an optional *epoch*. If not present, +it is zero. This allows a reset of versioning schemes. All versions with an +epoch of N+1 are greater than those with epoch N, no matter what the version +strings would compare. For example "0:4.0" is **less** than "1:1.0". Increasing +the epoch should **not** be a regular occurance. + +For the remainder of the version strings, each part (separated by '.' or '-') +is compared lexically. There are two exceptions: any part beginning with "-g" +or "-p" followed by a hexadecimal string is compared as a string, and if they +are different the versions are determined to be different. For example, the +sections "-g78d89280c3f9" and "-g123456789abc" differ and for all comparisons +(less than, greater than, equal) the result should be true. + +For those who have been paying attention, this scheme should look very +familiar to those who are familiar with RPM and Debian package versioning. + +The below table shows comparisons between versions and what the result should +be: + +=========================== =========================== ==================== +A B Result +=========================== =========================== ==================== +1.14-45-g78d89280c3f9-dirty 1.14-45-g78d89280c3f9-dirty Equal +1.14-45-g78d89280c3f9-dirty 1.14-45-g78d89280c3f9 A > B +1.14-45-g78d89280c3f9-dirty 1.14-45-g123456789abc A < B, A > B, A != B +1.14-45-g78d89280c3f9-dirty 1.14-46 A < B +1.14-45-g78d89280c3f9-dirty 1.15 A < B +1.14-45-g78d89280c3f9-dirty 1:1.0 A < B +1.0 1.0~daily20170201 A > B +1.0.1 1.0~daily20170201 A > B +1.0 1.0.1 A < B +1.0 1.0beta A < B +=========================== =========================== ==================== + +Examples +^^^^^^^^ + +New style (required for POWER9 and above): + +.. code-block:: dts + + ibm,firmware-versions { + version = "open-power-habanero-v1.14-45-g78d89280c3f9-dirty"; + skiboot = "5.4.0"; + occ = "d7efe30"; + linux = "4.4.32-openpower1"; + }; + +Old-style: + +.. code-block:: dts + + ibm,firmware-versions { + occ = "d7efe30-opdirty"; + skiboot = "5.4.0-opdirty"; + buildroot = "211bd05"; + capp-ucode = "1bb7503-opdirty"; + petitboot = "v1.3.1-opdirty-d695626"; + open-power = "habanero-f7b8f65-dirty"; + phandle = <0x1000012e>; + hostboot-binaries = "56532f5-opdirty"; + habanero-xml = "6a78496-opdirty-526ff79"; + hostboot = "09cfacb-opdirty"; + linux = "4.4.32-openpower1-opdirty-85cf528"; + }; diff --git a/roms/skiboot/doc/device-tree/ibm,opal.rst b/roms/skiboot/doc/device-tree/ibm,opal.rst new file mode 100644 index 000000000..25f905d46 --- /dev/null +++ b/roms/skiboot/doc/device-tree/ibm,opal.rst @@ -0,0 +1,83 @@ +.. _device-tree/ibm,opal: + +ibm,opal +======== + +.. toctree:: + :maxdepth: 1 + :glob: + + ibm,opal/* + + +Top level ibm,opal node +----------------------- + +.. code-block:: dts + + ibm,opal { + #address-cells = <0x0>; + #size-cells = <0x0>; + compatible = "ibm,opal-v2", "ibm,opal-v3"; + + /* v2 is maintained for possible compatibility with very, very old kernels + * it will go away at some point in the future. Detect and rely on ibm,opal-v3 + * ibm,opal-v2 is *NOT* present on POWER9 and above. + */ + + ibm,associativity-reference-points = <0x4 0x3, 0x2>; + ibm,heartbeat-ms = <0x7d0>; + + /* how often any OPAL call needs to be made to avoid a watchdog timer on BMC + * from kicking in + */ + + ibm,opal-memcons = <0x0 0x3007a000>; + + /* location of in memory OPAL console buffer. */ + + ibm,opal-trace-mask = <0x0 0x3008c3f0>; + ibm,opal-traces = <0x0 0x3007b010 0x0 0x10077 0x0 0x3b001010 0x0 0x1000a7 0x0 0x3b103010 0x0 0x1000a7 0x0 0x3b205010 0x0 0x1000a7 0x0 0x3b307010 0x0 0x1000a7 0x0 0x3b409010 0x0 0x1000a7 0x10 0x1801010 0x0 0x1000a7 0x10 0x1903010 0x0 0x1000a7 0x10 0x1a05010 0x0 0x1000a7 0x10 0x1b07010 0x0 0x1000a7 0x10 0x1c09010 0x0 0x1000a7 0x10 0x1d0b010 0x0 0x1000a7 0x10 0x1e0d010 0x0 0x1000a7 0x10 0x1f0f010 0x0 0x1000a7 0x10 0x2011010 0x0 0x1000a7 0x10 0x2113010 0x0 0x1000a7 0x10 0x2215010 0x0 0x1000a7 0x10 0x2317010 0x0 0x1000a7 0x10 0x2419010 0x0 0x1000a7 0x10 0x251b010 0x0 0x1000a7 0x10 0x261d010 0x0 0x1000a7>; + + /* see docs on tracing */ + + linux,phandle = <0x10000003>; + opal-base-address = <0x0 0x30000000>; + opal-entry-address = <0x0 0x300050c0>; + opal-interrupts = <0x10 0x11 0x12 0x13 0x14 0x20010 0x20011 0x20012 0x20013 0x20014 0xffe 0xfff 0x17fe 0x17ff 0x2ffe 0x2fff 0x37fe 0x37ff 0x20ffe 0x20fff 0x22ffe 0x22fff 0x237fe 0x237ff>; + opal-msg-async-num = <0x8>; + opal-msg-size = <0x48>; + opal-runtime-size = <0x0 0x9a00000>; + phandle = <0x10000003>; + }; + +.. ibm-heartbeat-ms: + +ibm,heartbeat-ms +^^^^^^^^^^^^^^^^ + +.. code-block:: dts + + ibm,opal { + ibm,heartbeat-ms = <0x7d0>; + } + + +Any OS targetting POWER9 processors *must* respect `ibm,heartbeat-ms`. + +Linux kernels prior to v4.1-rc1 would ignore `ibm,heartbeat-ms`. These only +supported POWER8 systems. + +On the earliest POWER8 OPAL systems, there was `ibm,heartbeat-freq` instead. +However, no OS at the time ever looked at that value, so it can be ignored +by any new operating systems. + +fast-reboot property +^^^^^^^^^^^^^^^^^^^^ + +This property of the `ibm,opal` node is an option property that will either be +the string `okay` or the reason the fast reboot feature was disabled on boot. + +The motivation behind adding this property is to help the OPAL test suite work +out if it should even try the fast reboot test on a particular platform +(without it having to resort to grepping firmware logs). 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. diff --git a/roms/skiboot/doc/device-tree/ibm,powerpc-cpu-features/binding.rst b/roms/skiboot/doc/device-tree/ibm,powerpc-cpu-features/binding.rst new file mode 100644 index 000000000..703823047 --- /dev/null +++ b/roms/skiboot/doc/device-tree/ibm,powerpc-cpu-features/binding.rst @@ -0,0 +1,302 @@ +ibm,powerpc-cpu-features Binding +================================ + +This device tree binding describes CPU features available to software, with +enablement, privilege, and compatibility metadata. + +More general description of design and implementation of this binding is +found in design.txt, which also points to documentation of specific features. + + +/cpus/ibm,powerpc-cpu-features node binding +------------------------------------------- + +Node: ibm,powerpc-cpu-features + +Description: Container of CPU feature nodes. + +The node name must be "ibm,powerpc-cpu-features". + +It is implemented as a child of the node "/cpus", but this must not be +assumed by parsers. + +The node is optional but should be provided by new OPAL firmware. + +Properties: + +- device_type + + Usage: + required + Value type: + string + Definition: + "cpu-features" + +- compatible + + Usage: + required + Value type: + string + Definition: + "ibm,powerpc-cpu-features" + + This compatibility refers to backwards compatibility of the overall + design with parsers that behave according to these guidelines. This can + be extended in a backward compatible manner which would not warrant a + revision of the compatible property. + +- isa + + Usage: + required + Value type: + <u32> + + Definition: + + isa that the CPU is currently running in. This provides instruction set + compatibility, less the individual feature nodes. For example, an ISA v3.0 + implementation that lacks the "transactional-memory" cpufeature node + should not use transactional memory facilities. + + Value corresponds to the "Power ISA Version" multiplied by 1000. + For example, <3000> corresponds to Version 3.0, <2070> to Version 2.07. + The minor digit is available for revisions. + +/cpus/ibm,powerpc-cpu-features/example-feature node bindings +---------------------------------------------------------------- + +Each child node of cpu-features represents a CPU feature / capability. + +Node: A string describing an architected CPU feature, e.g., "floating-point". + +Description: A feature or capability supported by the CPUs. + +The name of the node is a human readable string that forms the interface +used to describe features to software. Features are currently documented +in the code where they are implemented in skiboot/core/cpufeatures.c + +Presence of the node indicates the feature is available. + +Properties: + +- isa + + Usage: + required + Value type: + <u32> + + Definition: + + First level of the Power ISA that the feature appears in. + Software should filter out features when constraining the + environment to a particular ISA version. + + Value is defined similarly to /cpus/features/isa + +- usable-privilege + + Usage: + required + Value type: + <u32> bit mask + Definition: + Bit numbers are LSB0 + + bit 0: + PR (problem state / user mode) + bit 1: + OS (privileged state) + bit 2: + HV (hypervisor state) + + All other bits reserved and should be zero. + + This property describes the privilege levels and/or software components + that can use the feature. + + If bit 0 is set, then the hwcap-bit-nr property will exist. + + +- hv-support + + Usage: + optional + Value type: + <u32> bit mask + Definition: + Bit numbers are LSB0 + + bit 0: + HFSCR + + All other bits reserved and should be zero. + + This property describes the HV privilege support required to enable the + feature to lesser privilege levels. If the property does not exist then no + support is required. + + If no bits are set, the hypervisor must have explicit/custom support for + this feature. + + If the HFSCR bit is set, then the hfscr-bit-nr property will exist and + the feature may be enabled by setting this bit in the HFSCR register. + + +- os-support + + Usage: + optional + Value type: + <u32> bit mask + Definition: + Bit numbers are LSB0 + + bit 0: + FSCR + + All other bits reserved and should be zero. + + This property describes the OS privilege support required to enable the + feature to lesser privilege levels. If the property does not exist then no + support is required. + + If no bits are set, the operating system must have explicit/custom support + for this feature. + + If the FSCR bit is set, then the fscr-bit-nr property will exist and + the feature may be enabled by setting this bit in the FSCR register. + + +- hfscr-bit-nr + + Usage: + optional + Value type: + <u32> + Definition: + HFSCR bit position (LSB0) + + This property exists when the hv-support property HFSCR bit is set. This + property describes the bit number in the HFSCR register that the + hypervisor must set in order to enable this feature. + + This property also exists if an HFSCR bit corresponds with this feature. + This makes CPU feature parsing slightly simpler. + + +- fscr-bit-nr + + Usage: + optional + Value type: + <u32> + Definition: + FSCR bit position (LSB0) + + This property exists when the os-support property FSCR bit is set. This + property describes the bit number in the FSCR register that the + operating system must set in order to enable this feature. + + This property also exists if an FSCR bit corresponds with this feature. + This makes CPU feature parsing slightly simpler. + + +- hwcap-bit-nr + + Usage: + optional + Value type: + <u32> + Definition: + Linux ELF AUX vector bit position (LSB0) + + This property may exist when the usable-privilege property value has PR bit set. + This property describes the bit number that should be set in the ELF AUX + hardware capability vectors in order to advertise this feature to userspace. + Bits 0-31 correspond to bits 0-31 in AT_HWCAP vector. Bits 32-63 correspond + to 0-31 in AT_HWCAP2 vector, and so on. Missing AT_HWCAPx vectors implies + that the feature is not enabled or can not be advertised. Operating systems + may provide a number of unassigned hardware capability bits to allow for new + features to be advertised. + + Some properties representing features created before this binding are + advertised to userspace without a one-to-one hwcap bit number may not specify + this bit. Operating system will handle those bits specifically. All new + features usable by userspace will have a hwcap-bit-nr property. + + +- dependencies + + Usage: + optional + Value type: + <prop-encoded-array> + + Definition: + + If this property exists then it is a list of phandles to cpu feature + nodes that must be enabled for this feature to be enabled. + + +- Custom properties of the feature + + Usage: + optional + + Definition: + + Particular features may define their own properties. + + +Example +------- + +.. code-block:: dts + + /cpus/ibm,powerpc-cpu-features { + device_type = "ibm,powerpc-cpu-features"; + + isa = <3020>; + + darn { + isa = <3000>; + usable-privilege = <1 | 2 | 4>; + hwcap-bit-nr = <xx>; + }; + + scv { + isa = <3000>; + usable-privilege = <1 | 2>; + os-support = <0>; + hwcap-bit-nr = <xx>; + }; + + stop { + isa = <3000>; + usable-privilege = <2 | 4>; + hv-support = <0>; + os-support = <0>; + }; + + vsx2 (hypothetical) { + isa = <3010>; + usable-privilege = <1 | 2 | 4>; + hv-support = <0>; + os-support = <0>; + hwcap-bit-nr = <xx>; + }; + + vsx2-newinsns { + isa = <3020>; + usable-privilege = <1 | 2 | 4>; + os-support = <1>; + fscr-bit-nr = <xx>; + hwcap-bit-nr = <xx>; + dependencies = <&vsx2>; + }; + + }; diff --git a/roms/skiboot/doc/device-tree/ibm,powerpc-cpu-features/design.rst b/roms/skiboot/doc/device-tree/ibm,powerpc-cpu-features/design.rst new file mode 100644 index 000000000..baeb0e4c2 --- /dev/null +++ b/roms/skiboot/doc/device-tree/ibm,powerpc-cpu-features/design.rst @@ -0,0 +1,151 @@ +ibm,powerpc-cpu-features Design +=============================== + +The OPAL / skiboot code is the canonical location for this specification. All +definitions of features, constant, bit positions, etc. must be documented here +before being deployed in Linux. This is not presently part of LoPAPR. + + +Interfaces +---------- +This specification describes the ibm,powerpc-cpu-features binding (the formal +definition of binding can be found in binding.txt in this directory). + +This specification also involves the Linux ELF AUXV AT_HWCAP and AT_HWCAP2 +interfaces for PPC_FEATURE* bits. Allocation of new AT_HWCAP bits should be +done in coordination with OPAL / skiboot, Linux, and glibc projects. + +The binding is passed to the hypervisor by firmware. The hypervisor may +build a subset with unsupported/disabled features and hypervisor specifics +removed, and pass that to a guest OS. The OS may advertise features to +userspace. + + +Background +---------- +The cpu-features binding (subsequently "cpu-features") aims to provide an +extensible metadata and protocol between different levels of system software +(firmware, hypervisor, OS/guest, userspace) to advertise the CPU features +available on the system. With each level able to shape the features available +to the next. + +The binding specifies features common to all CPUs in the system. Heterogeneous +CPU features are not supported at present (such could be added by providing +additional cpu-features nodes and linking those to particular CPUs with +additional features). + +There is no strict definition for what a CPU feature must be, but an +architectural behaviour or performance characteristic (or group of related +behaviours). They must be documented in skiboot/core/cpufeatures.c sufficiently +precisely. More guidelines for feature definitions below. + +cpu-features is intended to provide fine grained control of CPU features at +all levels of the stack (firmware, hypervisor, OS, userspace), with the +ability for new CPU features to be used by some components without all +components being upgraded (e.g., a new floating point instruction could be +used by userspace math library without upgrading kernel and hypervisor). + + +Overview +-------- + +The cpu-features node is created by firmware and passed to the hypervisor. +The hypervisor may create cpu-features node to be passed to guest, based on +the features that have been enabled, and policy decisions. Hypervisor specific +features, and hypervisor bits and properties should not be advertised to +guests. Guest OS may advertise features to userspace using another method +(e.g., using AUXV vectors, userspace typically does not parse DT). + +When the cpu-features node is present, ibm,pa-features and individual feature +properties (e.g., "ibm,vsx"), and cpu-version under the "cpu" compatible nodes +can be ignored by the consumer. For compatibility, the provider must continue +to provide those older properties and the consumer must not assume cpu-features +exists. + +When this node exists, software may assume a base feature set which is ISA +v2.07B (BookS) minus the explicit features listed in core/cpufeatures.c +entries in this source tree. + +Each feature is advertised as a node underneath the cpu-features node, named +with a human-readable string name that uniquely identifies specification of +that capability. + +A feature node has a number of metadata properties describing privilege levels +a feature may be used (HV, OS, PR/user), and information about how it is to +be enabled and advertised to lesser privilege levels. Enabling means to make +it available at a lesser privilege level, (how to enable a given feature +for this privilege level is implicit: if the software know how to use a +feature, it also knows how to enable it). + +Feature node properties: + +- "isa", the Power ISA version where this feature first became available. + In case of an implementation specific feature +- "usable-privilege", a bitmask (HV, OS, PR/user) specifying which privilege + levels this feature may be used in. +- "hv-support", a bitmask. If this exists, the hypervisor must do some work + to enable support for lesser privilege levels. Bits can be set in this mask + to specify prescription/recipes to enable the feature without custom code. + If no bits are set, no recipe exists and custom code must be used. HFSCR + register enable bit is the only such recipe currently. +- "os-support", similar to hv-support. FSCR recipe. +- Features may have additional properties associated, must be documented with + the feature. +- Recipes may have additional properties associated. HFSCR recipe has + hfscr-bit-nr, and FSCR recipe has fscr-bit-nr. +- "dependencies" array of phandles. If this exists, it links to the + features that must be enabled in order for this feature to be enabled. +- "hwcap-bit-nr" if it exists provides a Linux ELF AUXV HWCAP bit number that + can be used to advertise this feature to userspace. + +Together, these compatibility, support, and dependencies properties allow +unknown features to be enabled and advertised to lesser privilege levels +(when possible). + +All bits not defined in usable, support masks must be 0, and should be ignored +by consumers. This allows extensibility to add new privilege levels and new +recipes. Unknown properties should also be ignored. This allows extensibility +for additional methods and metadata for enablement and advertisement. + +The policy for selecting and configuring which features to advertise and use +is left for implementations. + + +Guidelines for defining features +-------------------------------- + +As a rough guide, features should be based on functional groups of changes +to the ISA, or related performance characteristics. + +Grouping should be made by one or a combination of those that: + +- Share common enablement requirements (e.g., share particular registers or + firmware setup requirements). +- Share common usage patterns (e..g, likely to be used together). +- Are implemented with a particular new hardware unit. +- Are optional in the ISA. + +Granularity can be debated, but fine grained and encompassing is generally +preferable. For example, memory management unit may be considered fundamental, +but the MMU in POWER9 is very different and in many ways incompatible from +that in POWER8 even in hash mode. + +For example, "POWER9" would be too general, but a new feature for every +instruction would be too specific. The "summary of changes" preface in Power +ISA specification is a good starting point to give a guideline for granularity +of the architected features. + +New features that offer additional or incompatible functionality beyond +an existing feature may contain an ISA version postfix. + +Implementation specific behaviour should contain a CPU type postfix. E.g., +"machine-check-power9" gives exact MCE properties. If a future CPU has the same +MCE architecture, it should define the same property. If it has a +backward-compatible superset, it could additionally define +"machine-check-newcpu". + +Features should be "positive" as much as possible. That is, the presence of +a feature should indicate the presence of an additional CPU feature (e.g., a +new instruction or register). This requires some anticipation and foresight +for defining CPU features. "Negative" features may be unavoidable in some +cases. diff --git a/roms/skiboot/doc/device-tree/ibm,secureboot.rst b/roms/skiboot/doc/device-tree/ibm,secureboot.rst new file mode 100644 index 000000000..42f69b21b --- /dev/null +++ b/roms/skiboot/doc/device-tree/ibm,secureboot.rst @@ -0,0 +1,83 @@ +.. _device-tree/ibm,secureboot: + +ibm,secureboot +============== + +The ``ìbm,secureboot`` node provides secure boot and trusted boot information +up to the target OS. Further information can be found in :ref:`stb-overview`. + +Required properties +------------------- + +.. code-block:: none + + compatible: Either one of the following values: + + ibm,secureboot-v1 : The container-verification-code + is stored in a secure ROM memory. + + ibm,secureboot-v2 : The container-verification-code + is stored in a reserved memory. + It described by the ibm,cvc child + node. + + secure-enabled: this property exists when the firmware stack is booting + in secure mode (hardware secure boot jumper asserted). + + trusted-enabled: this property exists when the firmware stack is booting + in trusted mode. + + hw-key-hash: hash of the three hardware public keys trusted by the + platformw owner. This is used to verify if a firmware + code is signed with trusted keys. + + hw-key-hash-size: hw-key-hash size + + os-secureboot-enforcing: + this property is created by the secure variable backend + if it detects a desire by the owner to requre any + images (e.g. kernels) to be signed by an appropriate + key stored in secure variables. + + physical-presence-asserted: + this property exists to indicate the physical presence + of user to request key clearance. + + clear-os-keys: this property exists when the firmware indicates that + physical presence is asserted to clear only Host OS + secure boot keys. + + clear-all-keys: this property exists when the firmware indicates that + physical presence is asserted to clear all sensistive + data controlled by platform firmware. + + clear-mfg-keys: this property exists only during manufacturing process + when the firmware indicates to clear all senstive data + during manufacturing. It is only valid on development + drivers. + +Obsolete properties +------------------- + +.. code-block:: none + + hash-algo: Superseded by the hw-key-hash-size property in + 'ibm,secureboot-v2'. + +Example +------- + +.. code-block:: dts + + ibm,secureboot { + compatible = "ibm,secureboot-v2"; + secure-enabled; + trusted-enabled; + hw-key-hash-size = <0x40>; + hw-key-hash = <0x40d487ff 0x7380ed6a 0xd54775d5 0x795fea0d 0xe2f541fe + 0xa9db06b8 0x466a42a3 0x20e65f75 0xb4866546 0x0017d907 + 0x515dc2a5 0xf9fc5095 0x4d6ee0c9 0xb67d219d 0xfb708535 + 0x1d01d6d1>; + phandle = <0x100000fd>; + linux,phandle = <0x100000fd>; + }; diff --git a/roms/skiboot/doc/device-tree/imc.rst b/roms/skiboot/doc/device-tree/imc.rst new file mode 100644 index 000000000..bf9f14a35 --- /dev/null +++ b/roms/skiboot/doc/device-tree/imc.rst @@ -0,0 +1,124 @@ +.. _device-tree/imc: + +=========================== +IMC Device Tree Bindings +=========================== + +See :ref:`imc` for general In-Memory Collection (IMC) counter information. + +imc-counters top-level node +---------------------------- +.. code-block:: dts + + imc-counters { + compatible = "ibm,opal-in-memory-counters"; + #address-cells = <0x1>; + #size-cells = <0x1>; + phandle = <0x1000023a>; + version-id = <0xd>; + /* Denote IMC Events Catalog version used to build this DTS file. */ + + }; + +IMC device/units bindings +------------------------- + +.. code-block:: dts + + mcs3 { + compatible = "ibm,imc-counters"; + events-prefix = "PM_MCS3_"; /* denotes event name to be prefixed to get complete event name supported by this device */ + + phandle = <0x10000241>; + events = <0x10000242>; /* phandle of the events node supported by this device */ + + unit = "MiB"; + scale = "4"; /* unit and scale for all the events for this device */ + + reg = <0x118 0x8>; /* denotes base address for device event updates */ + type = <0x10>; + size = 0x40000; + offset = 0x180000; + base_addr = <Base address of the counter in reserve memory> + /* This is per-chip memory field and OPAL files it based on the no of chip in the system */ + /* base_addr property also indicates (or hints) kernel whether to memory */ + /* should be mmapped or allocated at system start for the counters */ + chipids = <chip-id for the base_addr > + }; + + trace@0 { + compatible = "ibm,imc-counters"; + events-prefix = "trace_"; + reg = <0x0 0x8>; + events = < &TRACE_IMC >; + type = <0x2>; + size = <0x40000>; + }; + +IMC device event bindings +------------------------- + +.. code-block:: dts + + nest-mcs-events { + #address-cells = <0x1>; + #size-cells = <0x1>; + phandle = <0x10000242>; + + event@98 { + desc = "Total Write Bandwidth seen on both MCS"; /* event description */ + + phandle = <0x1000023d>; + reg = <0x98 0x8>; /* event offset,when added with (nest-offset-address + device reg) will point to actual counter memory */ + + event-name = "DOWN_128B_DATA_XFER"; /* denotes the actual event name */ + + }; + + /* List of events supported */ + + }; + + TRACE_IMC: trace-events { + #address-cells = <0x1>; + #size-cells = <0x1>; + + event@10200000 { + event-name = "cycles" ; /* For trace node, we only have cycles event now */ + reg = <0x10200000 0x8>; + desc = "Reference cycles" ; + }; + }; + +Trace-mode SCOM +---------------- + +Trace scom is a 64 bit value which contains the event information for +IMC-trace mode. Following is the trace-scom layout. + +**TRACE_IMC_SCOM bit representation** + +:0-1: SAMPSEL + +:2-33: CPMC_LOAD + +:34-40: CPMC1SEL + +:41-47: CPMC2SEL + +:48-50: BUFFERSIZE + +:51-63: RESERVED + +*CPMC_LOAD* contains the sampling duration. *SAMPSEL* and *CPMC*SEL* +determines the event to count. *BUFFRSIZE* indicates the memory range. + +*BUFFERSIZE* can be + +.. code-block:: text + + b’000’ - 4K entries * 64 per entry = 256K + b’001’ - 8K entries * 64 per entry = 512K + b’010’ - 16K entries * 64 per entry = 1M + b’011’ - 32K entries * 64 per entry = 2M + b’100’ - 64K entries * 64 per entry = 4M diff --git a/roms/skiboot/doc/device-tree/index.rst b/roms/skiboot/doc/device-tree/index.rst new file mode 100644 index 000000000..1d9521a1b --- /dev/null +++ b/roms/skiboot/doc/device-tree/index.rst @@ -0,0 +1,12 @@ +Device Tree +=========== + +Device Tree for OPAL. Please refer to Device Tree Spec. + +.. toctree:: + :maxdepth: 1 + :glob: + + * + ibm,powerpc-cpu-features/* + diff --git a/roms/skiboot/doc/device-tree/memory-hierarchy.rst b/roms/skiboot/doc/device-tree/memory-hierarchy.rst new file mode 100644 index 000000000..c3c1d0349 --- /dev/null +++ b/roms/skiboot/doc/device-tree/memory-hierarchy.rst @@ -0,0 +1,26 @@ +P9 memory hierarchy +------------------- +P9 Nimbus supports direct attached DDR memory through 4 DDR ports per side +of the processor. Device tree contains memory hierarchy so that one can +traverse from chip to DIMM like below: + + xscom@<addr>/mcbist@<mcbist_id>/mcs@<mcs_id>/mca@<mca_id>/dimm@<resource_id> + +Example of dimm node: + +.. code-block:: dts + + dimm@d00e { + memory-id = <0xc>; /* DRAM Device Type. 0xc = DDR4 */ + product-version = <0x32>; /* Module Revision Code */ + device_type = "memory-dimm-ddr4"; + serial-number = <0x15d9ad1c>; + status = "okay"; + size = <0x4000>; + phandle = <0xd2>; + ibm,loc-code = "UOPWR.0000000-Node0-DIMM14"; + part-number = "36ASF2G72PZ-2G6B2 "; + reg = <0xd00e>; + manufacturer-id = <0x802c>; /* Vendor ID, we can get vendor name from this ID */ + }; + diff --git a/roms/skiboot/doc/device-tree/nvlink.rst b/roms/skiboot/doc/device-tree/nvlink.rst new file mode 100644 index 000000000..9f3fecb9b --- /dev/null +++ b/roms/skiboot/doc/device-tree/nvlink.rst @@ -0,0 +1,157 @@ +.. _device-tree/nvlink: + +=========================== +Nvlink Device Tree Bindings +=========================== + +See :ref:`nvlink` for general Nvlink information. + +NPU bindings: + +.. code-block:: dts + + xscom@3fc0000000000 { + npu@8013c00 { + reg = <0x8013c00 0x2c>; + compatible = "ibm,power8-npu"; + ibm,npu-index = <0x0>; + ibm,npu-links = <0x4>; /* Number of links wired up to this npu. */ + + phandle = <0x100002bc>; + linux,phandle = <0x100002bc>; + + link@0 { + ibm,npu-pbcq = <0x1000000b>; /* phandle to the pbcq which connects to the GPU. */ + ibm,npu-phy = <0x80000000 0x8010c3f>; /* SCOM address of the IBM PHY controlling this link. */ + compatible = "ibm,npu-link"; + ibm,npu-lane-mask = <0xff>; /* Mask specifying which IBM PHY lanes are used for this link. */ + + phandle = <0x100002bd>; + ibm,npu-link-index = <0x0>; /* Hardware link index. Naples systems + * contain links at index 0,1,4 & 5. + * Used to calculate various address offsets. */ + + linux,phandle = <0x100002bd>; + }; + + link@1 { + ibm,npu-pbcq = <0x1000000b>; + ibm,npu-phy = <0x80000000 0x8010c3f>; + compatible = "ibm,npu-link"; + ibm,npu-lane-mask = <0xff00>; + phandle = <0x100002be>; + ibm,npu-link-index = <0x1>; + linux,phandle = <0x100002be>; + }; + + link@4 { + ibm,npu-pbcq = <0x1000000a>; + ibm,npu-phy = <0x80000000 0x8010c7f>; + compatible = "ibm,npu-link"; + ibm,npu-lane-mask = <0xff00>; + phandle = <0x100002bf>; + ibm,npu-link-index = <0x4>; + linux,phandle = <0x100002bf>; + }; + + link@5 { + ibm,npu-pbcq = <0x1000000a>; + ibm,npu-phy = <0x80000000 0x8010c7f>; + compatible = "ibm,npu-link"; + ibm,npu-lane-mask = <0xff>; + phandle = <0x100002c0>; + ibm,npu-link-index = <0x5>; + linux,phandle = <0x100002c0>; + }; + }; + }; + +GPU memory bindings +------------------- + +.. code-block:: dts + + memory@100000000 { + device_type = "memory" + compatible = "ibm,coherent-device-memory"; + linux,usable-memory = <0x0 0x100000000 0x0 0x0>; + + ; denotes a region of unplugged system memory + + reg = <0x0 0x100000000 0x0 0x80000000>; + ibm,associativity = <0x4 0x0 0x0 0x0 0x64>; + + ; numa associativity for the memory once it is hotplugged + + phandle = <0x10000abc>; + linux,phandle = <0x10000abc>; + }; + +Emulated PCI device bindings +---------------------------- + +.. code-block:: dts + + pciex@3fff000400000 { + ibm,npcq = <0x100002bc>; /* phandle to the NPU node. Used to find associated PCI GPU devices. */ + compatible = "ibm,power8-npu-pciex", "ibm,ioda2-npu-phb"; + + pci@0 { + reg = <0x0 0x0 0x0 0x0 0x0>; + revision-id = <0x0>; + interrupts = <0x1>; + device-id = <0x4ea>; + ibm,pci-config-space-type = <0x1>; + vendor-id = <0x1014>; + ibm,gpu = <0x100002f7>; /* phandle pointing the associated GPU PCI device node */ + memory-region = <0x10000abc>; /* phandle pointing to the GPU memory */ + ibm,nvlink-speed = <0x1>; + + ; Denotes the speed the link is running at: + ; 0x3 == 20 Gbps, 0x8 = 25.78125 Gbps, 0x9 == 25.00000 Gbps + + phandle = <0x100002fc>; + }; + + pci@1 { + reg = <0x800 0x0 0x0 0x0 0x0>; + revision-id = <0x0>; + interrupts = <0x1>; + device-id = <0x4ea>; + ibm,pci-config-space-type = <0x1>; + vendor-id = <0x1014>; + ibm,gpu = <0x100002f5>; + memory-region = <0x10000def>; + phandle = <0x100002fe>; + class-code = <0x60400>; + linux,phandle = <0x100002fe>; + }; + + pci@0,1 { + reg = <0x100 0x0 0x0 0x0 0x0>; + revision-id = <0x0>; + interrupts = <0x2>; + device-id = <0x4ea>; + ibm,pci-config-space-type = <0x1>; + vendor-id = <0x1014>; + ibm,gpu = <0x100002f7>; + memory-region = <0x10000abc>; + phandle = <0x100002fd>; + class-code = <0x60400>; + linux,phandle = <0x100002fd>; + }; + + pci@1,1 { + reg = <0x900 0x0 0x0 0x0 0x0>; + revision-id = <0x0>; + interrupts = <0x2>; + device-id = <0x4ea>; + ibm,pci-config-space-type = <0x1>; + vendor-id = <0x1014>; + ibm,gpu = <0x100002f5>; + memory-region = <0x10000def>; + phandle = <0x100002ff>; + class-code = <0x60400>; + linux,phandle = <0x100002ff>; + }; + }; diff --git a/roms/skiboot/doc/device-tree/nx.rst b/roms/skiboot/doc/device-tree/nx.rst new file mode 100644 index 000000000..31e81e97f --- /dev/null +++ b/roms/skiboot/doc/device-tree/nx.rst @@ -0,0 +1,75 @@ +Nest (NX) Accelerator Coprocessor +================================= + +The NX coprocessor is present in P7+ or later processors. Each NX node +represents a unique NX coprocessor. The nodes are located under an +xscom node, as: :: + + /xscom@<xscom_addr>/nx@<nx_addr> + +With unique xscom and nx addresses. Their compatible node contains +"ibm,power-nx". + + +NX Compression Coprocessor +-------------------------- + +This is the memory compression coprocessor. which uses the IBM proprietary +842 compression algorithm and format. Each NX node contains an 842 engine. :: + + ibm,842-coprocessor-type : CT value common to all 842 coprocessors + ibm,842-coprocessor-instance : CI value unique to all 842 coprocessors + +Access to the coprocessor requires using the ICSWX instruction, which uses +a specific format including a Coprocessor Type (CT) and Coprocessor Instance +(CI) value to address each request to the right coprocessor. The driver should +use the CT and CI values for a particular node to communicate with it. For +all 842 coprocessors in the system, the CT value will (should) be the same, +while each will have a different CI value. The driver can use CI 0 to allow +the hardware to automatically select which coprocessor instance to use. + +On P9, this compression coprocessor also supports standard GZIP/ZLIB +compression algorithm and format. Virtual Accelerator Swirchboard (VAS) is used +to access this coprocessor. VAS writes each request to receive FIFOs (RXFIFO) +which are either high or normal priority and these FIFOs are bound to +coprocessor types (842 and gzip). + +VAS distinguishes NX requests for the target engines based on logical +partition ID (lpid), process ID (pid) and Thread ID (tid). So (lpid, pid, tid) +combination has to be unique in the system. Each NX node contains high and +normal FIFOs for each 842 and GZIP engines. :: + + /ibm,842-high-fifo : High priority 842 RxFIFO + /ibm,842-normal-fifo : Normal priority 842 RxFIFO + /ibm,gzip-high-fifo : High priority gzip RxFIFO + /ibm,gzip-normal-fifo : Normal priority gzip RxFIFO + +Each RxFIFO node contains: :: + + compatible : ibm,p9-nx-842 or ibm,p9-nx-gzip + priority : High or Normal + rx-fifo-address : RxFIFO buffer address + rx-fifo-size : RxFIFO size + lpid : 0xfff (1's for 12 bits in UMAC notify match + register) + pid : Coprocessor type (either 842 or gzip) + tid : counter in each coprocessor type + +During initialization, the driver invokes VAS interface for each coprocessor +type (842 and gzip) to configure the RxFIFO with rx_fifo_address, lpid, pid +and tid for high and nornmal priority FIFOs. + +NX RNG Coprocessor +------------------ + +This is the Random Number Generator (RNG) coprocessor, which is a part +of each NX coprocessor. Each node represents a unique RNG coprocessor. +Its nodes are not under the main nx node, they are located at: :: + + /hwrng@<addr> : RNG at address <addr> + ibm,chip-id : chip id where the RNG is + reg : address of the register to read from + +Each read from the RNG register will provide a new random number. + + diff --git a/roms/skiboot/doc/device-tree/opencapi.rst b/roms/skiboot/doc/device-tree/opencapi.rst new file mode 100644 index 000000000..497654aca --- /dev/null +++ b/roms/skiboot/doc/device-tree/opencapi.rst @@ -0,0 +1,70 @@ +.. _device-tree/opencapi: + +============================= +OpenCAPI Device Tree Bindings +============================= + +NPU bindings +------------ + +The NPU nodes are similar to those in :doc:`nvlink`. + +We distinguish between OpenCAPI and NVLink links using the +`ibm.npu-link-type` property. NPUs with a mixture of OpenCAPI and +NVLink links are currently unsupported. + +.. code-block:: dts + + xscom@603fc00000000 { + npu@5011000 { + compatible = "ibm,power9-npu"; + phandle = <0xe6>; + reg = <0x5011000 0x2c>; + ibm,npu-index = <0x0>; + ibm,npu-links = <0x2>; /* Number of links wired up to this npu. */ + + link@2 { + compatible = "ibm,npu-link"; + ibm,npu-link-type = "opencapi"; + ibm,npu-group-id = <0x1>; + ibm,npu-lane-mask = <0xf1e000>; /* Mask specifying which IBM PHY lanes + * are used for this link. 24-bit, + * lane 0 is most significant bit */ + ibm,npu-phy = <0x80000000 0x9010c3f>; /* SCOM address of the IBM PHY + * controlling this link. */ + ibm,npu-link-index = <0x2>; /* Hardware link index. + * Used to calculate various address offsets. */ + phandle = <0xe7>; + }; + + link@3 { + compatible = "ibm,npu-link"; + ibm,npu-link-type = "opencapi"; + ibm,npu-group-id = <0x2>; + ibm,npu-lane-mask = <0x78f>; + ibm,npu-phy = <0x80000000 0x9010c3f>; + ibm,npu-link-index = <0x3>; + phandle = <0xe8>; + }; + }; + }; + +PCI device bindings +------------------- + +The PCI devices mostly look like regular PCI devices (see :doc:`pci`), +but have a few additional fields to allow the devices to be associated +with the relevant NPU. These fields are presently not consumed by +anything but may be used in future. + +.. code-block:: dts + + pciex@600e800000000 { + /* OpenCAPI specific properties */ + compatible = "ibm,power9-npu-opencapi-pciex", "ibm,ioda2-npu2-opencapi-phb"; + ibm,npcq = <0xe6>; /* phandle to the NPU node */ + ibm,npu-index = <0x0>; + ibm,links = <0x1>; + /* Generic PCI fields here */ + } + diff --git a/roms/skiboot/doc/device-tree/pci.rst b/roms/skiboot/doc/device-tree/pci.rst new file mode 100644 index 000000000..dbc0981c1 --- /dev/null +++ b/roms/skiboot/doc/device-tree/pci.rst @@ -0,0 +1,69 @@ +.. _device-tree/pci: + +======================== +PCI Device Tree Bindings +======================== + +The following is an example PCI host bridge and device from a POWER9 machine. + +.. code-block:: dts + + pciex@600c3c0300000 { + ibm,capi-flags = <0x1>; + ibm,phb-stack-index = <0x0>; + compatible = "ibm,power9-pciex", "ibm,ioda3-phb"; + ibm,opal-single-pe; + ibm,opal-num-pes = <0x200>; + ibm,supported-tce-sizes = <0xc 0x10 0x15 0x1e>; + device_type = "pciex"; + ibm,opal-peltv-table = <0x0 0x543c0000 0x20000>; + ibm,associativity = <0x4 0x0 0x0 0x1 0x0>; + ibm,phb-diag-data-size = <0x2180>; + ranges = <0x2000000 0x0 0x80000000 0x600c1 0x80000000 0x0 0x7fff0000>; + ibm,lane-eq = <0x54545454 0x54545454 0x54545454 0x54545454 0x54545454 + 0x54545454 0x54545454 0x54545454 0x77777777 0x77777777 + 0x77777777 0x77777777>; + status = "okay"; + #interrupt-cells = <0x1>; + bus-range = <0x0 0xff>; + interrupt-parent = <0x126>; + #address-cells = <0x3>; + ibm,opal-phbid = <0x0 0x3>; + ibm,opal-pest-table = <0x0 0x543e2000 0x2000>; + ibm,chip-id = <0x0>; + #size-cells = <0x2>; + ibm,opal-m64-segment-splits = <0x200 0x1 0xc 0x0 0x1 0x2 0xc 0x0>; + ibm,opal-m64-window = <0x60200 0x0 0x60200 0x0 0x40 0x0>; + phandle = <0x617>; + ibm,phb-stack = <0xd8>; + ibm,phb-index = <0x3>; + ibm,phb-pec-index = <0x2>; /* skiboot-v6.2 or later */ + reg = <0x600c3 0xc0300000 0x0 0x1000 0x600c3 0x60000000 0x0 0x10000000>; + ibm,mmio-windows = <0x60200 0x0 0x40 0x0 0x600c1 0x80000000 0x0 0x80000000>; + clock-frequency = <0x200 0x0>; + ibm,xscom-bases = <0x4011400 0x4011440 0xf010800 0xf010840 0xf010900>; + ibm,opal-reserved-pe = <0x1ff>; + ibm,capp-timebase-sync = [00]; + ibm,opal-available-m64-ranges = <0x1 0x1f>; + ibm,opal-rtt-table = <0x0 0x54380000 0x20000>; + ibm,opal-msi-ranges = <0xfc000 0xff8>; + + pci@0 { + device_type = "pciex"; + revision-id = <0x0>; + ibm,pci-config-space-type = <0x1>; + interrupt-map-mask = <0x0 0x0 0x0 0x7>; + class-code = <0x60400>; + ranges = <0x2000000 0x0 0x0 0x2000000 0x0 0x0 0xf0000000 0x0>; + vendor-id = <0x1014>; + #interrupt-cells = <0x1>; + #address-cells = <0x3>; + interrupt-map = <0x0 0x0 0x0 0x1 0x126 0xfcff8 0x1 0x0 0x0 0x0 0x2 0x126 + 0xfcff9 0x1 0x0 0x0 0x0 0x3 0x126 0xfcffa 0x1 0x0 0x0 0x0 + 0x4 0x126 0xfcffb 0x1>; + #size-cells = <0x2>; + device-id = <0x4c1>; + phandle = <0x622>; + reg = <0x0 0x0 0x0 0x0 0x0>; + }; + }; diff --git a/roms/skiboot/doc/device-tree/reserved-memory.rst b/roms/skiboot/doc/device-tree/reserved-memory.rst new file mode 100644 index 000000000..c75d56414 --- /dev/null +++ b/roms/skiboot/doc/device-tree/reserved-memory.rst @@ -0,0 +1,32 @@ +reserved-memory device tree nodes +================================= + +OPAL exposes reserved memory through a top-level reserved-memory node, +containing subnodes that represent each reserved memory region. + +This follows the Linux specification for the /reserved-memory node, +described in the kernel source tree, in: + + Documentation/devicetree/bindings/reserved-memory/reserved-memory.txt + +The top-level /reserved-memory node contains: :: + + #size-cells = <2> + #address-cells = <2> + +Addresses and sizes are all 64-bits. + +``ranges`` + the empty ranges node indicates no translation of physical + addresses in the subnodes. + +The sub-nodes under the /reserved-memory node contain: + +``reg = <address size>`` + the address and size of the reserved memory region. The address + and size values are two cells each, as signified by the top-level + ``#{address,size}-cells`` + +``ibm,prd-label = "string"`` + a string token for use by the prd system. Specific ranges may be + used by prd - those will be referenced by this label. diff --git a/roms/skiboot/doc/device-tree/tpm.rst b/roms/skiboot/doc/device-tree/tpm.rst new file mode 100644 index 000000000..a8e67bc0f --- /dev/null +++ b/roms/skiboot/doc/device-tree/tpm.rst @@ -0,0 +1,47 @@ +.. _device-tree/tpm: + +Trusted Platform Module (TPM) +============================= + +The tpm node describes a TPM device present in the platform. It also includes +event log information. + +Required properties +------------------- + +All these properties are consumed by skiboot and the linux kernel (tpm and +vtpm codes) + +:: + + compatible : should have "nuvoton,npct650" + + linux,sml-base: 64-bit base address of the reserved memory allocated for firmware event log. + sml stands for shared memory log. + + linux,sml-size: size of the memory allocated for firmware event log. + + +Optional properties +------------------- + +:: + + status: indicates whether the device is enabled or disabled. "okay" for + enabled and "disabled" for disabled. + +Example +------- + +.. code-block:: dts + + tpm@57 { + reg = <0x57>; + compatible = "nuvoton,npct650", "nuvoton,npct601"; + linux,sml-base = <0x7f 0xfd450000>; + linux,sml-size = <0x10000>; + status = "okay"; + phandle = <0x10000017>; + linux,phandle = <0x10000017>; + }; + diff --git a/roms/skiboot/doc/device-tree/vas.rst b/roms/skiboot/doc/device-tree/vas.rst new file mode 100644 index 000000000..3ae77c0f8 --- /dev/null +++ b/roms/skiboot/doc/device-tree/vas.rst @@ -0,0 +1,38 @@ +.. _device-tree/vas: + + +Virtual Accelerator Switchboard (VAS) +===================================== + +VAS is present in P9 or later processors. In P9, each chip has one +instance of VAS. Each instance of VAS is represented as a "platform +device" i.e as a node in root of the device tree: :: + + /vas@<vas_addr> + +with unique VAS address which also represents the Hypervisor window +context address for the instance of VAS. + +Each VAS node contains: :: + + compatible: "ibm,power9-vas", "ibm,vas" + + ibm,chip-id: Chip-id of the chip containing this instance of VAS. + + ibm,vas-id: unique identifier for each instance of VAS in the system. + + ibm,vas-port: Port address for the interrupt. + + interrupts: <IRQ# level> for this VAS instance. + + interrupt-parent: Interrupt controller phandle. + + reg: contains 8 64-bit fields. + + Fields [0] and [1] represent the Hypervisor window context BAR + (start and length). Fields [2] and [3] represent the OS/User + window context BAR (start and length). Fields [4] and [5] + contain the start and length of paste power bus address region + for this chip. Fields [6] and [7] represent the bit field (start + bit and number of bits) where the window id of the window should + be encoded when computing the paste address for the window. diff --git a/roms/skiboot/doc/device-tree/vpd.rst b/roms/skiboot/doc/device-tree/vpd.rst new file mode 100644 index 000000000..b54c5599d --- /dev/null +++ b/roms/skiboot/doc/device-tree/vpd.rst @@ -0,0 +1,76 @@ +VPD (Vital Product Data) +======================== + +VPD provides the information about the FRUs (Field Replaceable Unit) present in +the system and each vpd node in the device tree represents a FRU. These +properties are passed to skiboot in the form of HDAT structure. Skiboot parses +these structures and adds respective nodes in the device tree. These properties +are available in all system except POWER8 BMC based system. + +.. code-block:: dts + + vpd { /* VPD root node */ + fru-name@rsrc-id { /* Node name formatted as such */ + ibm,vpd = < /* VPD data binary blob */ >; + ccin = "524D"; /* Customer Card Identification Number */ + fru-type = [ 41 56 ]; /* FRU type label (2 bytes ASCII character) */ + fru-number = "FRU stocking part number"; + ibm,loc-code = "Location code"; + part-number = "ABC123456"; + serial-number = "ABC123456"; + ibm,chip-id = <0x0>; /* If part is a chip, Processor Id */ + size = "0032768"; /* DIMM size (applicable for DIMM VPD only) */ + ibm,memory-bus-frequency = <0x0 0x0>; /* DIMM frequency (applicable for DIMM VPD only) */ + vendor = <vendor name> /* Vendor name */ + build-date = <build date> /* Manufacturing build date (applicate for P9 BMC systems only) */ + }; + }; + +The VPD tree in the device tree depicts the hierarchial structure of the +FRUs having parent-child relationship. :: + + root-node-vpd@a000 + |-- enclosure@1e00 + | |-- air-mover@3a00 + | |-- air-mover@3a01 + | |-- backplane@800 + | | |-- anchor-card@500 + | | |-- backplane-extender@900 + | | | |-- serial-connector@2a00 + | | | |-- usb-connector@2900 + | | | `-- usb-connector@2901 + | | |-- ethernet-connector@2800 + | | |-- ethernet-connector@2801 + | | |-- ms-dimm@d002 + | | |-- ms-dimm@d003 + | | |-- processor@1000 + | | |-- processor@1001 + | | |-- usb-connector@2902 + | | |-- usb-connector@2903 + | | |-- usb-connector@2904 + | | `-- usb-connector@2905 + | |-- dasd-backplane@2400 + | |-- dasd-backplane@2401 + | |-- power-supply@3103 + | `-- service-processor@200 + |-- enclosure-fault-led@a300 + |-- enclosure-led@a200 + |-- root-node-vpd@a001 + `-- system-vpd@1c00 + +Example vpd node: + +.. code-block:: dts + + anchor-card@500 { + ccin = "52FE"; + fru-number = "00E2147"; + description = "System Anchor Card - IBM Power 824"; + ibm,loc-code = "U78C9.001.WZS007X-P1-C13"; + serial-number = "YL10113BJ001"; + ibm,vpd = <0x84cc0052 0x54045649 0x4e494452 0x10414e43 0x484f5220 0x20202020 0x20202020 0x20434501 0x31565a02 0x3031464e 0x7303045 0x32313437 0x504e0730 0x30453231 0x3438534e 0xc594c31 0x30313133 0x424a3030 0x31434304 0x35324645 0x50520881 0x300000 0x48 0x45043030 0x31304354 0x440b400 0x485702 0x14233 0x6000000 0x142 0x34010042 0x370c0000 0x0 0x0 0x4239 0x3c435333 0x22071917 0xd1569c53 0x50973c87 0x71f9c40 0x1d4d3142 0x985e80f1 0x5cb3614d 0x32a902cb 0xd9d714ab 0x164d3322 0xdda4f986 0x5a618f4d 0x340b157c 0x2cac0a94 0x6504603 0x78 0x0>; + fru-type = [41 56]; + part-number = "00E2148"; + phandle = <0x8d>; + linux,phandle = <0x8d>; + }; |