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
|
<!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 Design — skiboot 09fb954
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="OPAL API Documentation" href="../../opal-api/index.html" />
<link rel="prev" title="ibm,powerpc-cpu-features Binding" href="binding.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="../../opal-api/index.html" title="OPAL API Documentation"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="binding.html" title="ibm,powerpc-cpu-features Binding"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../../index.html">skiboot 09fb954
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 Design</a></li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="ibm-powerpc-cpu-features-design">
<h1>ibm,powerpc-cpu-features Design<a class="headerlink" href="#ibm-powerpc-cpu-features-design" title="Permalink to this headline">¶</a></h1>
<p>The OPAL / skiboot code is the canonical location for this specification. All
definitions of features, constant, bit positions, etc. must be documented here
before being deployed in Linux. This is not presently part of LoPAPR.</p>
<section id="interfaces">
<h2>Interfaces<a class="headerlink" href="#interfaces" title="Permalink to this headline">¶</a></h2>
<p>This specification describes the ibm,powerpc-cpu-features binding (the formal
definition of binding can be found in binding.txt in this directory).</p>
<p>This specification also involves the Linux ELF AUXV AT_HWCAP and AT_HWCAP2
interfaces for PPC_FEATURE* bits. Allocation of new AT_HWCAP bits should be
done in coordination with OPAL / skiboot, Linux, and glibc projects.</p>
<p>The binding is passed to the hypervisor by firmware. The hypervisor may
build a subset with unsupported/disabled features and hypervisor specifics
removed, and pass that to a guest OS. The OS may advertise features to
userspace.</p>
</section>
<section id="background">
<h2>Background<a class="headerlink" href="#background" title="Permalink to this headline">¶</a></h2>
<p>The cpu-features binding (subsequently “cpu-features”) aims to provide an
extensible metadata and protocol between different levels of system software
(firmware, hypervisor, OS/guest, userspace) to advertise the CPU features
available on the system. With each level able to shape the features available
to the next.</p>
<p>The binding specifies features common to all CPUs in the system. Heterogeneous
CPU features are not supported at present (such could be added by providing
additional cpu-features nodes and linking those to particular CPUs with
additional features).</p>
<p>There is no strict definition for what a CPU feature must be, but an
architectural behaviour or performance characteristic (or group of related
behaviours). They must be documented in skiboot/core/cpufeatures.c sufficiently
precisely. More guidelines for feature definitions below.</p>
<p>cpu-features is intended to provide fine grained control of CPU features at
all levels of the stack (firmware, hypervisor, OS, userspace), with the
ability for new CPU features to be used by some components without all
components being upgraded (e.g., a new floating point instruction could be
used by userspace math library without upgrading kernel and hypervisor).</p>
</section>
<section id="overview">
<h2>Overview<a class="headerlink" href="#overview" title="Permalink to this headline">¶</a></h2>
<p>The cpu-features node is created by firmware and passed to the hypervisor.
The hypervisor may create cpu-features node to be passed to guest, based on
the features that have been enabled, and policy decisions. Hypervisor specific
features, and hypervisor bits and properties should not be advertised to
guests. Guest OS may advertise features to userspace using another method
(e.g., using AUXV vectors, userspace typically does not parse DT).</p>
<p>When the cpu-features node is present, ibm,pa-features and individual feature
properties (e.g., “ibm,vsx”), and cpu-version under the “cpu” compatible nodes
can be ignored by the consumer. For compatibility, the provider must continue
to provide those older properties and the consumer must not assume cpu-features
exists.</p>
<p>When this node exists, software may assume a base feature set which is ISA
v2.07B (BookS) minus the explicit features listed in core/cpufeatures.c
entries in this source tree.</p>
<p>Each feature is advertised as a node underneath the cpu-features node, named
with a human-readable string name that uniquely identifies specification of
that capability.</p>
<p>A feature node has a number of metadata properties describing privilege levels
a feature may be used (HV, OS, PR/user), and information about how it is to
be enabled and advertised to lesser privilege levels. Enabling means to make
it available at a lesser privilege level, (how to enable a given feature
for this privilege level is implicit: if the software know how to use a
feature, it also knows how to enable it).</p>
<p>Feature node properties:</p>
<ul class="simple">
<li><p>“isa”, the Power ISA version where this feature first became available.
In case of an implementation specific feature</p></li>
<li><p>“usable-privilege”, a bitmask (HV, OS, PR/user) specifying which privilege
levels this feature may be used in.</p></li>
<li><p>“hv-support”, a bitmask. If this exists, the hypervisor must do some work
to enable support for lesser privilege levels. Bits can be set in this mask
to specify prescription/recipes to enable the feature without custom code.
If no bits are set, no recipe exists and custom code must be used. HFSCR
register enable bit is the only such recipe currently.</p></li>
<li><p>“os-support”, similar to hv-support. FSCR recipe.</p></li>
<li><p>Features may have additional properties associated, must be documented with
the feature.</p></li>
<li><p>Recipes may have additional properties associated. HFSCR recipe has
hfscr-bit-nr, and FSCR recipe has fscr-bit-nr.</p></li>
<li><p>“dependencies” array of phandles. If this exists, it links to the
features that must be enabled in order for this feature to be enabled.</p></li>
<li><p>“hwcap-bit-nr” if it exists provides a Linux ELF AUXV HWCAP bit number that
can be used to advertise this feature to userspace.</p></li>
</ul>
<p>Together, these compatibility, support, and dependencies properties allow
unknown features to be enabled and advertised to lesser privilege levels
(when possible).</p>
<p>All bits not defined in usable, support masks must be 0, and should be ignored
by consumers. This allows extensibility to add new privilege levels and new
recipes. Unknown properties should also be ignored. This allows extensibility
for additional methods and metadata for enablement and advertisement.</p>
<p>The policy for selecting and configuring which features to advertise and use
is left for implementations.</p>
</section>
<section id="guidelines-for-defining-features">
<h2>Guidelines for defining features<a class="headerlink" href="#guidelines-for-defining-features" title="Permalink to this headline">¶</a></h2>
<p>As a rough guide, features should be based on functional groups of changes
to the ISA, or related performance characteristics.</p>
<p>Grouping should be made by one or a combination of those that:</p>
<ul class="simple">
<li><p>Share common enablement requirements (e.g., share particular registers or
firmware setup requirements).</p></li>
<li><p>Share common usage patterns (e..g, likely to be used together).</p></li>
<li><p>Are implemented with a particular new hardware unit.</p></li>
<li><p>Are optional in the ISA.</p></li>
</ul>
<p>Granularity can be debated, but fine grained and encompassing is generally
preferable. For example, memory management unit may be considered fundamental,
but the MMU in POWER9 is very different and in many ways incompatible from
that in POWER8 even in hash mode.</p>
<p>For example, “POWER9” would be too general, but a new feature for every
instruction would be too specific. The “summary of changes” preface in Power
ISA specification is a good starting point to give a guideline for granularity
of the architected features.</p>
<p>New features that offer additional or incompatible functionality beyond
an existing feature may contain an ISA version postfix.</p>
<p>Implementation specific behaviour should contain a CPU type postfix. E.g.,
“machine-check-power9” gives exact MCE properties. If a future CPU has the same
MCE architecture, it should define the same property. If it has a
backward-compatible superset, it could additionally define
“machine-check-newcpu”.</p>
<p>Features should be “positive” as much as possible. That is, the presence of
a feature should indicate the presence of an additional CPU feature (e.g., a
new instruction or register). This requires some anticipation and foresight
for defining CPU features. “Negative” features may be unavoidable in some
cases.</p>
</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 Design</a><ul>
<li><a class="reference internal" href="#interfaces">Interfaces</a></li>
<li><a class="reference internal" href="#background">Background</a></li>
<li><a class="reference internal" href="#overview">Overview</a></li>
<li><a class="reference internal" href="#guidelines-for-defining-features">Guidelines for defining features</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="binding.html"
title="previous chapter">ibm,powerpc-cpu-features Binding</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="../../opal-api/index.html"
title="next chapter">OPAL API Documentation</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/design.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="../../opal-api/index.html" title="OPAL API Documentation"
>next</a> |</li>
<li class="right" >
<a href="binding.html" title="ibm,powerpc-cpu-features Binding"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../../index.html">skiboot 09fb954
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 Design</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>
|
