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

   1 *** NOTE ***
   2 This document is copied from OPAL firmware
   3 (skiboot/doc/device-tree/ibm,powerpc-cpu-features/binding.txt)
   4
   5 There is more complete overview and documentation of features in that
   6 source tree.  All patches and modifications should go there.
   7 ************
   8
   9 ibm,powerpc-cpu-features binding
  10 ================================
  11
  12 This device tree binding describes CPU features available to software, with
  13 enablement, privilege, and compatibility metadata.
  14
  15 More general description of design and implementation of this binding is
  16 found in design.txt, which also points to documentation of specific features.
  17
  18
  19 /cpus/ibm,powerpc-cpu-features node binding
  20 -------------------------------------------
  21
  22 Node: ibm,powerpc-cpu-features
  23
  24 Description: Container of CPU feature nodes.
  25
  26 The node name must be "ibm,powerpc-cpu-features".
  27
  28 It is implemented as a child of the node "/cpus", but this must not be
  29 assumed by parsers.
  30
  31 The node is optional but should be provided by new OPAL firmware.
  32
  33 Properties:
  34
  35 - compatible
  36   Usage: required
  37   Value type: string
  38   Definition: "ibm,powerpc-cpu-features"
  39
  40   This compatibility refers to backwards compatibility of the overall
  41   design with parsers that behave according to these guidelines. This can
  42   be extended in a backward compatible manner which would not warrant a
  43   revision of the compatible property.
  44
  45 - isa
  46   Usage: required
  47   Value type: <u32>
  48   Definition:
  49
  50   isa that the CPU is currently running in. This provides instruction set
  51   compatibility, less the individual feature nodes. For example, an ISA v3.0
  52   implementation that lacks the "transactional-memory" cpufeature node
  53   should not use transactional memory facilities.
  54
  55   Value corresponds to the "Power ISA Version" multiplied by 1000.
  56   For example, <3000> corresponds to Version 3.0, <2070> to Version 2.07.
  57   The minor digit is available for revisions.
  58
  59 - display-name
  60   Usage: optional
  61   Value type: string
  62   Definition:
  63
  64   A human readable name for the CPU.
  65
  66 /cpus/ibm,powerpc-cpu-features/example-feature node bindings
  67 ----------------------------------------------------------------
  68
  69 Each child node of cpu-features represents a CPU feature / capability.
  70
  71 Node: A string describing an architected CPU feature, e.g., "floating-point".
  72
  73 Description: A feature or capability supported by the CPUs.
  74
  75 The name of the node is a human readable string that forms the interface
  76 used to describe features to software. Features are currently documented
  77 in the code where they are implemented in skiboot/core/cpufeatures.c
  78
  79 Presence of the node indicates the feature is available.
  80
  81 Properties:
  82
  83 - isa
  84   Usage: required
  85   Value type: <u32>
  86   Definition:
  87
  88   First level of the Power ISA that the feature appears in.
  89   Software should filter out features when constraining the
  90   environment to a particular ISA version.
  91
  92   Value is defined similarly to /cpus/features/isa
  93
  94 - usable-privilege
  95   Usage: required
  96   Value type: <u32> bit mask
  97   Definition:
  98               Bit numbers are LSB0
  99               bit 0 - PR (problem state / user mode)
 100               bit 1 - OS (privileged state)
 101               bit 2 - HV (hypervisor state)
 102               All other bits reserved and should be zero.
 103
 104   This property describes the privilege levels and/or software components
 105   that can use the feature.
 106
 107   If bit 0 is set, then the hwcap-bit-nr property will exist.
 108
 109
 110 - hv-support
 111   Usage: optional
 112   Value type: <u32> bit mask
 113   Definition:
 114               Bit numbers are LSB0
 115               bit 0 -  HFSCR
 116               All other bits reserved and should be zero.
 117
 118   This property describes the HV privilege support required to enable the
 119   feature to lesser privilege levels. If the property does not exist then no
 120   support is required.
 121
 122   If no bits are set, the hypervisor must have explicit/custom support for
 123   this feature.
 124
 125   If the HFSCR bit is set, then the hfscr-bit-nr property will exist and
 126   the feature may be enabled by setting this bit in the HFSCR register.
 127
 128
 129 - os-support
 130   Usage: optional
 131   Value type: <u32> bit mask
 132   Definition:
 133               Bit numbers are LSB0
 134               bit 0 -  FSCR
 135               All other bits reserved and should be zero.
 136
 137   This property describes the OS privilege support required to enable the
 138   feature to lesser privilege levels. If the property does not exist then no
 139   support is required.
 140
 141   If no bits are set, the operating system must have explicit/custom support
 142   for this feature.
 143
 144   If the FSCR bit is set, then the fscr-bit-nr property will exist and
 145   the feature may be enabled by setting this bit in the FSCR register.
 146
 147
 148 - hfscr-bit-nr
 149   Usage: optional
 150   Value type: <u32>
 151   Definition: HFSCR bit position (LSB0)
 152
 153   This property exists when the hv-support property HFSCR bit is set. This
 154   property describes the bit number in the HFSCR register that the
 155   hypervisor must set in order to enable this feature.
 156
 157   This property also exists if an HFSCR bit corresponds with this feature.
 158   This makes CPU feature parsing slightly simpler.
 159
 160
 161 - fscr-bit-nr
 162   Usage: optional
 163   Value type: <u32>
 164   Definition: FSCR bit position (LSB0)
 165
 166   This property exists when the os-support property FSCR bit is set. This
 167   property describes the bit number in the FSCR register that the
 168   operating system must set in order to enable this feature.
 169
 170   This property also exists if an FSCR bit corresponds with this feature.
 171   This makes CPU feature parsing slightly simpler.
 172
 173
 174 - hwcap-bit-nr
 175   Usage: optional
 176   Value type: <u32>
 177   Definition: Linux ELF AUX vector bit position (LSB0)
 178
 179   This property may exist when the usable-privilege property value has PR bit set.
 180   This property describes the bit number that should be set in the ELF AUX
 181   hardware capability vectors in order to advertise this feature to userspace.
 182   Bits 0-31 correspond to bits 0-31 in AT_HWCAP vector. Bits 32-63 correspond
 183   to 0-31 in AT_HWCAP2 vector, and so on.  Missing AT_HWCAPx vectors implies
 184   that the feature is not enabled or can not be advertised. Operating systems
 185   may provide a number of unassigned hardware capability bits to allow for new
 186   features to be advertised.
 187
 188   Some properties representing features created before this binding are
 189   advertised to userspace without a one-to-one hwcap bit number may not specify
 190   this bit. Operating system will handle those bits specifically.  All new
 191   features usable by userspace will have a hwcap-bit-nr property.
 192
 193
 194 - dependencies
 195   Usage: optional
 196   Value type: <prop-encoded-array>
 197   Definition:
 198
 199   If this property exists then it is a list of phandles to cpu feature
 200   nodes that must be enabled for this feature to be enabled.
 201
 202
 203 Example
 204 -------
 205
 206         /cpus/ibm,powerpc-cpu-features {
 207                 compatible = "ibm,powerpc-cpu-features";
 208
 209                 isa = <3020>;
 210
 211                 darn {
 212                         isa = <3000>;
 213                         usable-privilege = <1 | 2 | 4>;
 214                         hwcap-bit-nr = <xx>;
 215                 };
 216
 217                 scv {
 218                         isa = <3000>;
 219                         usable-privilege = <1 | 2>;
 220                         os-support = <0>;
 221                         hwcap-bit-nr = <xx>;
 222                 };
 223
 224                 stop {
 225                         isa = <3000>;
 226                         usable-privilege = <2 | 4>;
 227                         hv-support = <0>;
 228                         os-support = <0>;
 229                 };
 230
 231                 vsx2 (hypothetical) {
 232                         isa = <3010>;
 233                         usable-privilege = <1 | 2 | 4>;
 234                         hv-support = <0>;
 235                         os-support = <0>;
 236                         hwcap-bit-nr = <xx>;
 237                 };
 238
 239                 vsx2-newinsns {
 240                         isa = <3020>;
 241                         usable-privilege = <1 | 2 | 4>;
 242                         os-support = <1>;
 243                         fscr-bit-nr = <xx>;
 244                         hwcap-bit-nr = <xx>;
 245                         dependencies = <&vsx2>;
 246                 };
 247
 248         };