diff options
Diffstat (limited to 'doc/device-tree/ibm,powerpc-cpu-features/design.rst')
| -rw-r--r-- | doc/device-tree/ibm,powerpc-cpu-features/design.rst | 151 |
1 files changed, 151 insertions, 0 deletions
diff --git a/doc/device-tree/ibm,powerpc-cpu-features/design.rst b/doc/device-tree/ibm,powerpc-cpu-features/design.rst new file mode 100644 index 0000000..baeb0e4 --- /dev/null +++ b/doc/device-tree/ibm,powerpc-cpu-features/design.rst @@ -0,0 +1,151 @@ +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. |