Documentation / devicetree / bindings / powerpc / ibm,powerpc-cpu-features.txt


Based on kernel version 6.8. Page generated on 2024-03-11 21:26 EST.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248
*** NOTE ***
This document is copied from OPAL firmware
(skiboot/doc/device-tree/ibm,powerpc-cpu-features/binding.txt)

There is more complete overview and documentation of features in that
source tree.  All patches and modifications should go there.
************

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:

- 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.

- display-name
  Usage: optional
  Value type: string
  Definition:

  A human readable name for the CPU.

/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.


Example
-------

	/cpus/ibm,powerpc-cpu-features {
		compatible = "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>;
		};

	};