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.