1*** NOTE *** 2This document is copied from OPAL firmware 3(skiboot/doc/device-tree/ibm,powerpc-cpu-features/binding.txt) 4 5There is more complete overview and documentation of features in that 6source tree. All patches and modifications should go there. 7************ 8 9ibm,powerpc-cpu-features binding 10================================ 11 12This device tree binding describes CPU features available to software, with 13enablement, privilege, and compatibility metadata. 14 15More general description of design and implementation of this binding is 16found in design.txt, which also points to documentation of specific features. 17 18 19/cpus/ibm,powerpc-cpu-features node binding 20------------------------------------------- 21 22Node: ibm,powerpc-cpu-features 23 24Description: Container of CPU feature nodes. 25 26The node name must be "ibm,powerpc-cpu-features". 27 28It is implemented as a child of the node "/cpus", but this must not be 29assumed by parsers. 30 31The node is optional but should be provided by new OPAL firmware. 32 33Properties: 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 69Each child node of cpu-features represents a CPU feature / capability. 70 71Node: A string describing an architected CPU feature, e.g., "floating-point". 72 73Description: A feature or capability supported by the CPUs. 74 75The name of the node is a human readable string that forms the interface 76used to describe features to software. Features are currently documented 77in the code where they are implemented in skiboot/core/cpufeatures.c 78 79Presence of the node indicates the feature is available. 80 81Properties: 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 203Example 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 }; 249