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 };
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.