doc/device-tree/ibm,powerpc-cpu-features/design.html - skiboot - Git at Google

 <!DOCTYPE html>

 <html lang="en" data-content_root="../../">
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />

     <title>ibm,powerpc-cpu-features Design &#8212; skiboot d365a01
  documentation</title>
     <link rel="stylesheet" type="text/css" href="../../_static/pygments.css?v=fa44fd50" />
     <link rel="stylesheet" type="text/css" href="../../_static/classic.css?v=514cf933" />

     <script src="../../_static/documentation_options.js?v=e1fecbe9"></script>
     <script src="../../_static/doctools.js?v=888ff710"></script>
     <script src="../../_static/sphinx_highlight.js?v=dc90522c"></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 d365a01
  documentation</a> &#187;</li>
           <li class="nav-item nav-item-1"><a href="../index.html" accesskey="U">Device Tree</a> &#187;</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="Link to this heading">¶</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="Link to this heading">¶</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="Link to this heading">¶</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="Link to this heading">¶</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="Link to this heading">¶</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">
   <div>
     <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>

   </div>
   <div>
     <h4>Previous topic</h4>
     <p class="topless"><a href="binding.html"
                           title="previous chapter">ibm,powerpc-cpu-features Binding</a></p>
   </div>
   <div>
     <h4>Next topic</h4>
     <p class="topless"><a href="../../opal-api/index.html"
                           title="next chapter">OPAL API Documentation</a></p>
   </div>
   <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>document.getElementById('searchbox').style.display = "block"</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 d365a01
  documentation</a> &#187;</li>
           <li class="nav-item nav-item-1"><a href="../index.html" >Device Tree</a> &#187;</li>
         <li class="nav-item nav-item-this"><a href="">ibm,powerpc-cpu-features Design</a></li>
       </ul>
     </div>
     <div class="footer" role="contentinfo">
     &#169; Copyright 2016-2017, IBM, others.
       Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 7.2.6.
     </div>
   </body>
 </html>
	<!DOCTYPE html>

	<html lang="en" data-content_root="../../">
	<head>
	<meta charset="utf-8" />
	<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />

	<title>ibm,powerpc-cpu-features Design — skiboot d365a01
	documentation</title>
	<link rel="stylesheet" type="text/css" href="../../_static/pygments.css?v=fa44fd50" />
	<link rel="stylesheet" type="text/css" href="../../_static/classic.css?v=514cf933" />

	<script src="../../_static/documentation_options.js?v=e1fecbe9"></script>
	<script src="../../_static/doctools.js?v=888ff710"></script>
	<script src="../../_static/sphinx_highlight.js?v=dc90522c"></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 d365a01
	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="Link to this heading">¶</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="Link to this heading">¶</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="Link to this heading">¶</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="Link to this heading">¶</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="Link to this heading">¶</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">
	<div>
	<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>

	</div>
	<div>
	<h4>Previous topic</h4>
	<p class="topless"><a href="binding.html"
	title="previous chapter">ibm,powerpc-cpu-features Binding</a></p>
	</div>
	<div>
	<h4>Next topic</h4>
	<p class="topless"><a href="../../opal-api/index.html"
	title="next chapter">OPAL API Documentation</a></p>
	</div>
	<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>document.getElementById('searchbox').style.display = "block"</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 d365a01
	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> 7.2.6.
	</div>
	</body>
	</html>