1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
|
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>ibm,powerpc-cpu-features Binding — skiboot 5c1dc62
documentation</title>
<link rel="stylesheet" type="text/css" href="../../_static/pygments.css" />
<link rel="stylesheet" type="text/css" href="../../_static/classic.css" />
<script data-url_root="../../" id="documentation_options" src="../../_static/documentation_options.js"></script>
<script src="../../_static/jquery.js"></script>
<script src="../../_static/underscore.js"></script>
<script src="../../_static/doctools.js"></script>
<link rel="index" title="Index" href="../../genindex.html" />
<link rel="search" title="Search" href="../../search.html" />
<link rel="next" title="ibm,powerpc-cpu-features Design" href="design.html" />
<link rel="prev" title="VPD (Vital Product Data)" href="../vpd.html" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="design.html" title="ibm,powerpc-cpu-features Design"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="../vpd.html" title="VPD (Vital Product Data)"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../../index.html">skiboot 5c1dc62
documentation</a> »</li>
<li class="nav-item nav-item-1"><a href="../index.html" accesskey="U">Device Tree</a> »</li>
<li class="nav-item nav-item-this"><a href="">ibm,powerpc-cpu-features Binding</a></li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="ibm-powerpc-cpu-features-binding">
<h1>ibm,powerpc-cpu-features Binding<a class="headerlink" href="#ibm-powerpc-cpu-features-binding" title="Permalink to this headline">¶</a></h1>
<p>This device tree binding describes CPU features available to software, with
enablement, privilege, and compatibility metadata.</p>
<p>More general description of design and implementation of this binding is
found in design.txt, which also points to documentation of specific features.</p>
<section id="cpus-ibm-powerpc-cpu-features-node-binding">
<h2>/cpus/ibm,powerpc-cpu-features node binding<a class="headerlink" href="#cpus-ibm-powerpc-cpu-features-node-binding" title="Permalink to this headline">¶</a></h2>
<p>Node: ibm,powerpc-cpu-features</p>
<p>Description: Container of CPU feature nodes.</p>
<p>The node name must be “ibm,powerpc-cpu-features”.</p>
<p>It is implemented as a child of the node “/cpus”, but this must not be
assumed by parsers.</p>
<p>The node is optional but should be provided by new OPAL firmware.</p>
<p>Properties:</p>
<ul>
<li><p>device_type</p>
<dl class="simple">
<dt>Usage:</dt><dd><p>required</p>
</dd>
<dt>Value type:</dt><dd><p>string</p>
</dd>
<dt>Definition:</dt><dd><p>“cpu-features”</p>
</dd>
</dl>
</li>
<li><p>compatible</p>
<dl class="simple">
<dt>Usage:</dt><dd><p>required</p>
</dd>
<dt>Value type:</dt><dd><p>string</p>
</dd>
<dt>Definition:</dt><dd><p>“ibm,powerpc-cpu-features”</p>
</dd>
</dl>
<p>This compatibility refers to backwards compatibility of the overall
design with parsers that behave according to these guidelines. This can
be extended in a backward compatible manner which would not warrant a
revision of the compatible property.</p>
</li>
<li><p>isa</p>
<dl class="simple">
<dt>Usage:</dt><dd><p>required</p>
</dd>
<dt>Value type:</dt><dd><p><u32></p>
</dd>
</dl>
<p>Definition:</p>
<p>isa that the CPU is currently running in. This provides instruction set
compatibility, less the individual feature nodes. For example, an ISA v3.0
implementation that lacks the “transactional-memory” cpufeature node
should not use transactional memory facilities.</p>
<p>Value corresponds to the “Power ISA Version” multiplied by 1000.
For example, <3000> corresponds to Version 3.0, <2070> to Version 2.07.
The minor digit is available for revisions.</p>
</li>
</ul>
</section>
<section id="cpus-ibm-powerpc-cpu-features-example-feature-node-bindings">
<h2>/cpus/ibm,powerpc-cpu-features/example-feature node bindings<a class="headerlink" href="#cpus-ibm-powerpc-cpu-features-example-feature-node-bindings" title="Permalink to this headline">¶</a></h2>
<p>Each child node of cpu-features represents a CPU feature / capability.</p>
<p>Node: A string describing an architected CPU feature, e.g., “floating-point”.</p>
<p>Description: A feature or capability supported by the CPUs.</p>
<p>The name of the node is a human readable string that forms the interface
used to describe features to software. Features are currently documented
in the code where they are implemented in skiboot/core/cpufeatures.c</p>
<p>Presence of the node indicates the feature is available.</p>
<p>Properties:</p>
<ul>
<li><p>isa</p>
<dl class="simple">
<dt>Usage:</dt><dd><p>required</p>
</dd>
<dt>Value type:</dt><dd><p><u32></p>
</dd>
</dl>
<p>Definition:</p>
<p>First level of the Power ISA that the feature appears in.
Software should filter out features when constraining the
environment to a particular ISA version.</p>
<p>Value is defined similarly to /cpus/features/isa</p>
</li>
<li><p>usable-privilege</p>
<dl>
<dt>Usage:</dt><dd><p>required</p>
</dd>
<dt>Value type:</dt><dd><p><u32> bit mask</p>
</dd>
<dt>Definition:</dt><dd><p>Bit numbers are LSB0</p>
<dl class="simple">
<dt>bit 0:</dt><dd><p>PR (problem state / user mode)</p>
</dd>
<dt>bit 1:</dt><dd><p>OS (privileged state)</p>
</dd>
<dt>bit 2:</dt><dd><p>HV (hypervisor state)</p>
</dd>
</dl>
<p>All other bits reserved and should be zero.</p>
</dd>
</dl>
<p>This property describes the privilege levels and/or software components
that can use the feature.</p>
<p>If bit 0 is set, then the hwcap-bit-nr property will exist.</p>
</li>
<li><p>hv-support</p>
<dl>
<dt>Usage:</dt><dd><p>optional</p>
</dd>
<dt>Value type:</dt><dd><p><u32> bit mask</p>
</dd>
<dt>Definition:</dt><dd><p>Bit numbers are LSB0</p>
<dl class="simple">
<dt>bit 0:</dt><dd><p>HFSCR</p>
</dd>
</dl>
<p>All other bits reserved and should be zero.</p>
</dd>
</dl>
<p>This property describes the HV privilege support required to enable the
feature to lesser privilege levels. If the property does not exist then no
support is required.</p>
<p>If no bits are set, the hypervisor must have explicit/custom support for
this feature.</p>
<p>If the HFSCR bit is set, then the hfscr-bit-nr property will exist and
the feature may be enabled by setting this bit in the HFSCR register.</p>
</li>
<li><p>os-support</p>
<dl>
<dt>Usage:</dt><dd><p>optional</p>
</dd>
<dt>Value type:</dt><dd><p><u32> bit mask</p>
</dd>
<dt>Definition:</dt><dd><p>Bit numbers are LSB0</p>
<dl class="simple">
<dt>bit 0:</dt><dd><p>FSCR</p>
</dd>
</dl>
<p>All other bits reserved and should be zero.</p>
</dd>
</dl>
<p>This property describes the OS privilege support required to enable the
feature to lesser privilege levels. If the property does not exist then no
support is required.</p>
<p>If no bits are set, the operating system must have explicit/custom support
for this feature.</p>
<p>If the FSCR bit is set, then the fscr-bit-nr property will exist and
the feature may be enabled by setting this bit in the FSCR register.</p>
</li>
<li><p>hfscr-bit-nr</p>
<dl class="simple">
<dt>Usage:</dt><dd><p>optional</p>
</dd>
<dt>Value type:</dt><dd><p><u32></p>
</dd>
<dt>Definition:</dt><dd><p>HFSCR bit position (LSB0)</p>
</dd>
</dl>
<p>This property exists when the hv-support property HFSCR bit is set. This
property describes the bit number in the HFSCR register that the
hypervisor must set in order to enable this feature.</p>
<p>This property also exists if an HFSCR bit corresponds with this feature.
This makes CPU feature parsing slightly simpler.</p>
</li>
<li><p>fscr-bit-nr</p>
<dl class="simple">
<dt>Usage:</dt><dd><p>optional</p>
</dd>
<dt>Value type:</dt><dd><p><u32></p>
</dd>
<dt>Definition:</dt><dd><p>FSCR bit position (LSB0)</p>
</dd>
</dl>
<p>This property exists when the os-support property FSCR bit is set. This
property describes the bit number in the FSCR register that the
operating system must set in order to enable this feature.</p>
<p>This property also exists if an FSCR bit corresponds with this feature.
This makes CPU feature parsing slightly simpler.</p>
</li>
<li><p>hwcap-bit-nr</p>
<dl class="simple">
<dt>Usage:</dt><dd><p>optional</p>
</dd>
<dt>Value type:</dt><dd><p><u32></p>
</dd>
<dt>Definition:</dt><dd><p>Linux ELF AUX vector bit position (LSB0)</p>
</dd>
</dl>
<p>This property may exist when the usable-privilege property value has PR bit set.
This property describes the bit number that should be set in the ELF AUX
hardware capability vectors in order to advertise this feature to userspace.
Bits 0-31 correspond to bits 0-31 in AT_HWCAP vector. Bits 32-63 correspond
to 0-31 in AT_HWCAP2 vector, and so on. Missing AT_HWCAPx vectors implies
that the feature is not enabled or can not be advertised. Operating systems
may provide a number of unassigned hardware capability bits to allow for new
features to be advertised.</p>
<p>Some properties representing features created before this binding are
advertised to userspace without a one-to-one hwcap bit number may not specify
this bit. Operating system will handle those bits specifically. All new
features usable by userspace will have a hwcap-bit-nr property.</p>
</li>
<li><p>dependencies</p>
<dl class="simple">
<dt>Usage:</dt><dd><p>optional</p>
</dd>
<dt>Value type:</dt><dd><p><prop-encoded-array></p>
</dd>
</dl>
<p>Definition:</p>
<p>If this property exists then it is a list of phandles to cpu feature
nodes that must be enabled for this feature to be enabled.</p>
</li>
<li><p>Custom properties of the feature</p>
<dl class="simple">
<dt>Usage:</dt><dd><p>optional</p>
</dd>
</dl>
<p>Definition:</p>
<p>Particular features may define their own properties.</p>
</li>
</ul>
</section>
<section id="example">
<h2>Example<a class="headerlink" href="#example" title="Permalink to this headline">¶</a></h2>
<div class="highlight-dts notranslate"><div class="highlight"><pre><span></span><span class="err">/cpus/</span><span class="nc">ibm,powerpc-cpu-features</span> <span class="p">{</span>
<span class="nf">device_type</span> <span class="o">=</span> <span class="s">"ibm,powerpc-cpu-features"</span><span class="p">;</span>
<span class="nf">isa</span> <span class="o">=</span> <span class="p"><</span><span class="mi">3020</span><span class="p">>;</span>
<span class="nc">darn</span> <span class="p">{</span>
<span class="nf">isa</span> <span class="o">=</span> <span class="p"><</span><span class="mi">3000</span><span class="p">>;</span>
<span class="nf">usable-privilege</span> <span class="o">=</span> <span class="p"><</span><span class="mi">1</span> <span class="err">|</span> <span class="mi">2</span> <span class="err">|</span> <span class="mi">4</span><span class="p">>;</span>
<span class="nf">hwcap-bit-nr</span> <span class="o">=</span> <span class="p"><</span><span class="err">xx</span><span class="p">>;</span>
<span class="p">};</span>
<span class="nc">scv</span> <span class="p">{</span>
<span class="nf">isa</span> <span class="o">=</span> <span class="p"><</span><span class="mi">3000</span><span class="p">>;</span>
<span class="nf">usable-privilege</span> <span class="o">=</span> <span class="p"><</span><span class="mi">1</span> <span class="err">|</span> <span class="mi">2</span><span class="p">>;</span>
<span class="nf">os-support</span> <span class="o">=</span> <span class="p"><</span><span class="mi">0</span><span class="p">>;</span>
<span class="nf">hwcap-bit-nr</span> <span class="o">=</span> <span class="p"><</span><span class="err">xx</span><span class="p">>;</span>
<span class="p">};</span>
<span class="nc">stop</span> <span class="p">{</span>
<span class="nf">isa</span> <span class="o">=</span> <span class="p"><</span><span class="mi">3000</span><span class="p">>;</span>
<span class="nf">usable-privilege</span> <span class="o">=</span> <span class="p"><</span><span class="mi">2</span> <span class="err">|</span> <span class="mi">4</span><span class="p">>;</span>
<span class="nf">hv-support</span> <span class="o">=</span> <span class="p"><</span><span class="mi">0</span><span class="p">>;</span>
<span class="nf">os-support</span> <span class="o">=</span> <span class="p"><</span><span class="mi">0</span><span class="p">>;</span>
<span class="p">};</span>
<span class="err">vsx2</span> <span class="err">(hypothetical)</span> <span class="err">{</span>
<span class="nf">isa</span> <span class="o">=</span> <span class="p"><</span><span class="mi">3010</span><span class="p">>;</span>
<span class="nf">usable-privilege</span> <span class="o">=</span> <span class="p"><</span><span class="mi">1</span> <span class="err">|</span> <span class="mi">2</span> <span class="err">|</span> <span class="mi">4</span><span class="p">>;</span>
<span class="nf">hv-support</span> <span class="o">=</span> <span class="p"><</span><span class="mi">0</span><span class="p">>;</span>
<span class="nf">os-support</span> <span class="o">=</span> <span class="p"><</span><span class="mi">0</span><span class="p">>;</span>
<span class="nf">hwcap-bit-nr</span> <span class="o">=</span> <span class="p"><</span><span class="err">xx</span><span class="p">>;</span>
<span class="p">};</span>
<span class="nc">vsx2-newinsns</span> <span class="p">{</span>
<span class="nf">isa</span> <span class="o">=</span> <span class="p"><</span><span class="mi">3020</span><span class="p">>;</span>
<span class="nf">usable-privilege</span> <span class="o">=</span> <span class="p"><</span><span class="mi">1</span> <span class="err">|</span> <span class="mi">2</span> <span class="err">|</span> <span class="mi">4</span><span class="p">>;</span>
<span class="nf">os-support</span> <span class="o">=</span> <span class="p"><</span><span class="mi">1</span><span class="p">>;</span>
<span class="nf">fscr-bit-nr</span> <span class="o">=</span> <span class="p"><</span><span class="err">xx</span><span class="p">>;</span>
<span class="nf">hwcap-bit-nr</span> <span class="o">=</span> <span class="p"><</span><span class="err">xx</span><span class="p">>;</span>
<span class="nf">dependencies</span> <span class="o">=</span> <span class="p"><</span><span class="o">&</span>vsx2<span class="p">>;</span>
<span class="p">};</span>
<span class="err">};</span>
</pre></div>
</div>
</section>
</section>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="../../index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">ibm,powerpc-cpu-features Binding</a><ul>
<li><a class="reference internal" href="#cpus-ibm-powerpc-cpu-features-node-binding">/cpus/ibm,powerpc-cpu-features node binding</a></li>
<li><a class="reference internal" href="#cpus-ibm-powerpc-cpu-features-example-feature-node-bindings">/cpus/ibm,powerpc-cpu-features/example-feature node bindings</a></li>
<li><a class="reference internal" href="#example">Example</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="../vpd.html"
title="previous chapter">VPD (Vital Product Data)</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="design.html"
title="next chapter">ibm,powerpc-cpu-features Design</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../../_sources/device-tree/ibm,powerpc-cpu-features/binding.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="design.html" title="ibm,powerpc-cpu-features Design"
>next</a> |</li>
<li class="right" >
<a href="../vpd.html" title="VPD (Vital Product Data)"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../../index.html">skiboot 5c1dc62
documentation</a> »</li>
<li class="nav-item nav-item-1"><a href="../index.html" >Device Tree</a> »</li>
<li class="nav-item nav-item-this"><a href="">ibm,powerpc-cpu-features Binding</a></li>
</ul>
</div>
<div class="footer" role="contentinfo">
© Copyright 2016-2017, IBM, others.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.3.2.
</div>
</body>
</html>
|
