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