0001 *** NOTE ***
0002 This document is copied from OPAL firmware
0003 (skiboot/doc/device-tree/ibm,powerpc-cpu-features/binding.txt)
0004
0005 There is more complete overview and documentation of features in that
0006 source tree. All patches and modifications should go there.
0007 ************
0008
0009 ibm,powerpc-cpu-features binding
0010 ================================
0011
0012 This device tree binding describes CPU features available to software, with
0013 enablement, privilege, and compatibility metadata.
0014
0015 More general description of design and implementation of this binding is
0016 found in design.txt, which also points to documentation of specific features.
0017
0018
0019 /cpus/ibm,powerpc-cpu-features node binding
0020 -------------------------------------------
0021
0022 Node: ibm,powerpc-cpu-features
0023
0024 Description: Container of CPU feature nodes.
0025
0026 The node name must be "ibm,powerpc-cpu-features".
0027
0028 It is implemented as a child of the node "/cpus", but this must not be
0029 assumed by parsers.
0030
0031 The node is optional but should be provided by new OPAL firmware.
0032
0033 Properties:
0034
0035 - compatible
0036 Usage: required
0037 Value type: string
0038 Definition: "ibm,powerpc-cpu-features"
0039
0040 This compatibility refers to backwards compatibility of the overall
0041 design with parsers that behave according to these guidelines. This can
0042 be extended in a backward compatible manner which would not warrant a
0043 revision of the compatible property.
0044
0045 - isa
0046 Usage: required
0047 Value type: <u32>
0048 Definition:
0049
0050 isa that the CPU is currently running in. This provides instruction set
0051 compatibility, less the individual feature nodes. For example, an ISA v3.0
0052 implementation that lacks the "transactional-memory" cpufeature node
0053 should not use transactional memory facilities.
0054
0055 Value corresponds to the "Power ISA Version" multiplied by 1000.
0056 For example, <3000> corresponds to Version 3.0, <2070> to Version 2.07.
0057 The minor digit is available for revisions.
0058
0059 - display-name
0060 Usage: optional
0061 Value type: string
0062 Definition:
0063
0064 A human readable name for the CPU.
0065
0066 /cpus/ibm,powerpc-cpu-features/example-feature node bindings
0067 ----------------------------------------------------------------
0068
0069 Each child node of cpu-features represents a CPU feature / capability.
0070
0071 Node: A string describing an architected CPU feature, e.g., "floating-point".
0072
0073 Description: A feature or capability supported by the CPUs.
0074
0075 The name of the node is a human readable string that forms the interface
0076 used to describe features to software. Features are currently documented
0077 in the code where they are implemented in skiboot/core/cpufeatures.c
0078
0079 Presence of the node indicates the feature is available.
0080
0081 Properties:
0082
0083 - isa
0084 Usage: required
0085 Value type: <u32>
0086 Definition:
0087
0088 First level of the Power ISA that the feature appears in.
0089 Software should filter out features when constraining the
0090 environment to a particular ISA version.
0091
0092 Value is defined similarly to /cpus/features/isa
0093
0094 - usable-privilege
0095 Usage: required
0096 Value type: <u32> bit mask
0097 Definition:
0098 Bit numbers are LSB0
0099 bit 0 - PR (problem state / user mode)
0100 bit 1 - OS (privileged state)
0101 bit 2 - HV (hypervisor state)
0102 All other bits reserved and should be zero.
0103
0104 This property describes the privilege levels and/or software components
0105 that can use the feature.
0106
0107 If bit 0 is set, then the hwcap-bit-nr property will exist.
0108
0109
0110 - hv-support
0111 Usage: optional
0112 Value type: <u32> bit mask
0113 Definition:
0114 Bit numbers are LSB0
0115 bit 0 - HFSCR
0116 All other bits reserved and should be zero.
0117
0118 This property describes the HV privilege support required to enable the
0119 feature to lesser privilege levels. If the property does not exist then no
0120 support is required.
0121
0122 If no bits are set, the hypervisor must have explicit/custom support for
0123 this feature.
0124
0125 If the HFSCR bit is set, then the hfscr-bit-nr property will exist and
0126 the feature may be enabled by setting this bit in the HFSCR register.
0127
0128
0129 - os-support
0130 Usage: optional
0131 Value type: <u32> bit mask
0132 Definition:
0133 Bit numbers are LSB0
0134 bit 0 - FSCR
0135 All other bits reserved and should be zero.
0136
0137 This property describes the OS privilege support required to enable the
0138 feature to lesser privilege levels. If the property does not exist then no
0139 support is required.
0140
0141 If no bits are set, the operating system must have explicit/custom support
0142 for this feature.
0143
0144 If the FSCR bit is set, then the fscr-bit-nr property will exist and
0145 the feature may be enabled by setting this bit in the FSCR register.
0146
0147
0148 - hfscr-bit-nr
0149 Usage: optional
0150 Value type: <u32>
0151 Definition: HFSCR bit position (LSB0)
0152
0153 This property exists when the hv-support property HFSCR bit is set. This
0154 property describes the bit number in the HFSCR register that the
0155 hypervisor must set in order to enable this feature.
0156
0157 This property also exists if an HFSCR bit corresponds with this feature.
0158 This makes CPU feature parsing slightly simpler.
0159
0160
0161 - fscr-bit-nr
0162 Usage: optional
0163 Value type: <u32>
0164 Definition: FSCR bit position (LSB0)
0165
0166 This property exists when the os-support property FSCR bit is set. This
0167 property describes the bit number in the FSCR register that the
0168 operating system must set in order to enable this feature.
0169
0170 This property also exists if an FSCR bit corresponds with this feature.
0171 This makes CPU feature parsing slightly simpler.
0172
0173
0174 - hwcap-bit-nr
0175 Usage: optional
0176 Value type: <u32>
0177 Definition: Linux ELF AUX vector bit position (LSB0)
0178
0179 This property may exist when the usable-privilege property value has PR bit set.
0180 This property describes the bit number that should be set in the ELF AUX
0181 hardware capability vectors in order to advertise this feature to userspace.
0182 Bits 0-31 correspond to bits 0-31 in AT_HWCAP vector. Bits 32-63 correspond
0183 to 0-31 in AT_HWCAP2 vector, and so on. Missing AT_HWCAPx vectors implies
0184 that the feature is not enabled or can not be advertised. Operating systems
0185 may provide a number of unassigned hardware capability bits to allow for new
0186 features to be advertised.
0187
0188 Some properties representing features created before this binding are
0189 advertised to userspace without a one-to-one hwcap bit number may not specify
0190 this bit. Operating system will handle those bits specifically. All new
0191 features usable by userspace will have a hwcap-bit-nr property.
0192
0193
0194 - dependencies
0195 Usage: optional
0196 Value type: <prop-encoded-array>
0197 Definition:
0198
0199 If this property exists then it is a list of phandles to cpu feature
0200 nodes that must be enabled for this feature to be enabled.
0201
0202
0203 Example
0204 -------
0205
0206 /cpus/ibm,powerpc-cpu-features {
0207 compatible = "ibm,powerpc-cpu-features";
0208
0209 isa = <3020>;
0210
0211 darn {
0212 isa = <3000>;
0213 usable-privilege = <1 | 2 | 4>;
0214 hwcap-bit-nr = <xx>;
0215 };
0216
0217 scv {
0218 isa = <3000>;
0219 usable-privilege = <1 | 2>;
0220 os-support = <0>;
0221 hwcap-bit-nr = <xx>;
0222 };
0223
0224 stop {
0225 isa = <3000>;
0226 usable-privilege = <2 | 4>;
0227 hv-support = <0>;
0228 os-support = <0>;
0229 };
0230
0231 vsx2 (hypothetical) {
0232 isa = <3010>;
0233 usable-privilege = <1 | 2 | 4>;
0234 hv-support = <0>;
0235 os-support = <0>;
0236 hwcap-bit-nr = <xx>;
0237 };
0238
0239 vsx2-newinsns {
0240 isa = <3020>;
0241 usable-privilege = <1 | 2 | 4>;
0242 os-support = <1>;
0243 fscr-bit-nr = <xx>;
0244 hwcap-bit-nr = <xx>;
0245 dependencies = <&vsx2>;
0246 };
0247
0248 };
