249 lines · plain
1*** NOTE ***2This document is copied from OPAL firmware3(skiboot/doc/device-tree/ibm,powerpc-cpu-features/binding.txt)4 5There is more complete overview and documentation of features in that6source tree. All patches and modifications should go there.7************8 9ibm,powerpc-cpu-features binding10================================11 12This device tree binding describes CPU features available to software, with13enablement, privilege, and compatibility metadata.14 15More general description of design and implementation of this binding is16found in design.txt, which also points to documentation of specific features.17 18 19/cpus/ibm,powerpc-cpu-features node binding20-------------------------------------------21 22Node: ibm,powerpc-cpu-features23 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 be29assumed by parsers.30 31The node is optional but should be provided by new OPAL firmware.32 33Properties:34 35- compatible36 Usage: required37 Value type: string38 Definition: "ibm,powerpc-cpu-features"39 40 This compatibility refers to backwards compatibility of the overall41 design with parsers that behave according to these guidelines. This can42 be extended in a backward compatible manner which would not warrant a43 revision of the compatible property.44 45- isa46 Usage: required47 Value type: <u32>48 Definition:49 50 isa that the CPU is currently running in. This provides instruction set51 compatibility, less the individual feature nodes. For example, an ISA v3.052 implementation that lacks the "transactional-memory" cpufeature node53 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-name60 Usage: optional61 Value type: string62 Definition:63 64 A human readable name for the CPU.65 66/cpus/ibm,powerpc-cpu-features/example-feature node bindings67----------------------------------------------------------------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 interface76used to describe features to software. Features are currently documented77in the code where they are implemented in skiboot/core/cpufeatures.c78 79Presence of the node indicates the feature is available.80 81Properties:82 83- isa84 Usage: required85 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 the90 environment to a particular ISA version.91 92 Value is defined similarly to /cpus/features/isa93 94- usable-privilege95 Usage: required96 Value type: <u32> bit mask97 Definition:98 Bit numbers are LSB099 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 components105 that can use the feature.106 107 If bit 0 is set, then the hwcap-bit-nr property will exist.108 109 110- hv-support111 Usage: optional112 Value type: <u32> bit mask113 Definition:114 Bit numbers are LSB0115 bit 0 - HFSCR116 All other bits reserved and should be zero.117 118 This property describes the HV privilege support required to enable the119 feature to lesser privilege levels. If the property does not exist then no120 support is required.121 122 If no bits are set, the hypervisor must have explicit/custom support for123 this feature.124 125 If the HFSCR bit is set, then the hfscr-bit-nr property will exist and126 the feature may be enabled by setting this bit in the HFSCR register.127 128 129- os-support130 Usage: optional131 Value type: <u32> bit mask132 Definition:133 Bit numbers are LSB0134 bit 0 - FSCR135 All other bits reserved and should be zero.136 137 This property describes the OS privilege support required to enable the138 feature to lesser privilege levels. If the property does not exist then no139 support is required.140 141 If no bits are set, the operating system must have explicit/custom support142 for this feature.143 144 If the FSCR bit is set, then the fscr-bit-nr property will exist and145 the feature may be enabled by setting this bit in the FSCR register.146 147 148- hfscr-bit-nr149 Usage: optional150 Value type: <u32>151 Definition: HFSCR bit position (LSB0)152 153 This property exists when the hv-support property HFSCR bit is set. This154 property describes the bit number in the HFSCR register that the155 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-nr162 Usage: optional163 Value type: <u32>164 Definition: FSCR bit position (LSB0)165 166 This property exists when the os-support property FSCR bit is set. This167 property describes the bit number in the FSCR register that the168 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-nr175 Usage: optional176 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 AUX181 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 correspond183 to 0-31 in AT_HWCAP2 vector, and so on. Missing AT_HWCAPx vectors implies184 that the feature is not enabled or can not be advertised. Operating systems185 may provide a number of unassigned hardware capability bits to allow for new186 features to be advertised.187 188 Some properties representing features created before this binding are189 advertised to userspace without a one-to-one hwcap bit number may not specify190 this bit. Operating system will handle those bits specifically. All new191 features usable by userspace will have a hwcap-bit-nr property.192 193 194- dependencies195 Usage: optional196 Value type: <prop-encoded-array>197 Definition:198 199 If this property exists then it is a list of phandles to cpu feature200 nodes that must be enabled for this feature to be enabled.201 202 203Example204-------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