ibm,powerpc-cpu-features Design¶
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.
Interfaces¶
This specification describes the ibm,powerpc-cpu-features binding (the formal definition of binding can be found in binding.txt in this directory).
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.
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.
Background¶
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.
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).
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.
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).
Overview¶
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).
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.
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.
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.
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).
Feature node properties:
“isa”, the Power ISA version where this feature first became available. In case of an implementation specific feature
“usable-privilege”, a bitmask (HV, OS, PR/user) specifying which privilege levels this feature may be used in.
“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.
“os-support”, similar to hv-support. FSCR recipe.
Features may have additional properties associated, must be documented with the feature.
Recipes may have additional properties associated. HFSCR recipe has hfscr-bit-nr, and FSCR recipe has fscr-bit-nr.
“dependencies” array of phandles. If this exists, it links to the features that must be enabled in order for this feature to be enabled.
“hwcap-bit-nr” if it exists provides a Linux ELF AUXV HWCAP bit number that can be used to advertise this feature to userspace.
Together, these compatibility, support, and dependencies properties allow unknown features to be enabled and advertised to lesser privilege levels (when possible).
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.
The policy for selecting and configuring which features to advertise and use is left for implementations.
Guidelines for defining features¶
As a rough guide, features should be based on functional groups of changes to the ISA, or related performance characteristics.
Grouping should be made by one or a combination of those that:
Share common enablement requirements (e.g., share particular registers or firmware setup requirements).
Share common usage patterns (e..g, likely to be used together).
Are implemented with a particular new hardware unit.
Are optional in the ISA.
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.
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.
New features that offer additional or incompatible functionality beyond an existing feature may contain an ISA version postfix.
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”.
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.