diff options
Diffstat (limited to 'doc/device-tree')
| -rw-r--r-- | doc/device-tree/ibm,powerpc-cpu-features/binding.rst | 302 | ||||
| -rw-r--r-- | doc/device-tree/ibm,powerpc-cpu-features/design.rst | 151 | ||||
| -rw-r--r-- | doc/device-tree/index.rst | 1 |
3 files changed, 454 insertions, 0 deletions
diff --git a/doc/device-tree/ibm,powerpc-cpu-features/binding.rst b/doc/device-tree/ibm,powerpc-cpu-features/binding.rst new file mode 100644 index 0000000..7038230 --- /dev/null +++ b/doc/device-tree/ibm,powerpc-cpu-features/binding.rst @@ -0,0 +1,302 @@ +ibm,powerpc-cpu-features Binding +================================ + +This device tree binding describes CPU features available to software, with +enablement, privilege, and compatibility metadata. + +More general description of design and implementation of this binding is +found in design.txt, which also points to documentation of specific features. + + +/cpus/ibm,powerpc-cpu-features node binding +------------------------------------------- + +Node: ibm,powerpc-cpu-features + +Description: Container of CPU feature nodes. + +The node name must be "ibm,powerpc-cpu-features". + +It is implemented as a child of the node "/cpus", but this must not be +assumed by parsers. + +The node is optional but should be provided by new OPAL firmware. + +Properties: + +- device_type + + Usage: + required + Value type: + string + Definition: + "cpu-features" + +- compatible + + Usage: + required + Value type: + string + Definition: + "ibm,powerpc-cpu-features" + + 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. + +- isa + + Usage: + required + Value type: + <u32> + + Definition: + + 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. + + 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. + +/cpus/ibm,powerpc-cpu-features/example-feature node bindings +---------------------------------------------------------------- + +Each child node of cpu-features represents a CPU feature / capability. + +Node: A string describing an architected CPU feature, e.g., "floating-point". + +Description: A feature or capability supported by the CPUs. + +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 + +Presence of the node indicates the feature is available. + +Properties: + +- isa + + Usage: + required + Value type: + <u32> + + Definition: + + 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. + + Value is defined similarly to /cpus/features/isa + +- usable-privilege + + Usage: + required + Value type: + <u32> bit mask + Definition: + Bit numbers are LSB0 + + bit 0: + PR (problem state / user mode) + bit 1: + OS (privileged state) + bit 2: + HV (hypervisor state) + + All other bits reserved and should be zero. + + This property describes the privilege levels and/or software components + that can use the feature. + + If bit 0 is set, then the hwcap-bit-nr property will exist. + + +- hv-support + + Usage: + optional + Value type: + <u32> bit mask + Definition: + Bit numbers are LSB0 + + bit 0: + HFSCR + + All other bits reserved and should be zero. + + 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. + + If no bits are set, the hypervisor must have explicit/custom support for + this feature. + + 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. + + +- os-support + + Usage: + optional + Value type: + <u32> bit mask + Definition: + Bit numbers are LSB0 + + bit 0: + FSCR + + All other bits reserved and should be zero. + + 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. + + If no bits are set, the operating system must have explicit/custom support + for this feature. + + 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. + + +- hfscr-bit-nr + + Usage: + optional + Value type: + <u32> + Definition: + HFSCR bit position (LSB0) + + 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. + + This property also exists if an HFSCR bit corresponds with this feature. + This makes CPU feature parsing slightly simpler. + + +- fscr-bit-nr + + Usage: + optional + Value type: + <u32> + Definition: + FSCR bit position (LSB0) + + 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. + + This property also exists if an FSCR bit corresponds with this feature. + This makes CPU feature parsing slightly simpler. + + +- hwcap-bit-nr + + Usage: + optional + Value type: + <u32> + Definition: + Linux ELF AUX vector bit position (LSB0) + + 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. + + 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. + + +- dependencies + + Usage: + optional + Value type: + <prop-encoded-array> + + Definition: + + 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. + + +- Custom properties of the feature + + Usage: + optional + + Definition: + + Particular features may define their own properties. + + +Example +------- + +.. code-block:: dts + + /cpus/ibm,powerpc-cpu-features { + device_type = "ibm,powerpc-cpu-features"; + + isa = <3020>; + + darn { + isa = <3000>; + usable-privilege = <1 | 2 | 4>; + hwcap-bit-nr = <xx>; + }; + + scv { + isa = <3000>; + usable-privilege = <1 | 2>; + os-support = <0>; + hwcap-bit-nr = <xx>; + }; + + stop { + isa = <3000>; + usable-privilege = <2 | 4>; + hv-support = <0>; + os-support = <0>; + }; + + vsx2 (hypothetical) { + isa = <3010>; + usable-privilege = <1 | 2 | 4>; + hv-support = <0>; + os-support = <0>; + hwcap-bit-nr = <xx>; + }; + + vsx2-newinsns { + isa = <3020>; + usable-privilege = <1 | 2 | 4>; + os-support = <1>; + fscr-bit-nr = <xx>; + hwcap-bit-nr = <xx>; + dependencies = <&vsx2>; + }; + + }; 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. diff --git a/doc/device-tree/index.rst b/doc/device-tree/index.rst index 1d53440..1d9521a 100644 --- a/doc/device-tree/index.rst +++ b/doc/device-tree/index.rst @@ -8,4 +8,5 @@ Device Tree for OPAL. Please refer to Device Tree Spec. :glob: * + ibm,powerpc-cpu-features/* |