dt: add /cpus/ibm, powerpc-cpu-features device tree bindings

This is a new CPU feature advertising interface that is fine-grained,
extensible, aware of privilege levels, and gives control of features
to all levels of the stack (firmware, hypervisor, and OS).

The design and binding specification is described in detail in doc/.

Signed-off-by: Nicholas Piggin <npiggin@gmail.com>
[stewart: fix maybe-uninitialized warning from older GCC, doc cleanup]
Signed-off-by: Stewart Smith <stewart@linux.vnet.ibm.com>

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/*