new file mode 100644
@@ -0,0 +1,195 @@
+powerpc cpufeatures binding
+===========================
+
+The device tree allows the supported architected CPU features to be
+described as nodes containing compatibility and enablement information.
+
+The cpufeatures binding specifies features supported by all CPUs in a
+homogeneous system. Heterogeneous CPU features are not supported at
+present.
+
+The cpufeatures binding passes from firmware to hypervisor, which may
+filter out features based on privilege, compatibility, and other
+configuration settings. Then device tree with this filtered cpufeatures
+binding is passed to the operating systems, which in turn filter and
+expose features to user programs using AT_HWCAP ELF AUX vectors. This is
+done in such a way that an old OS that is unaware of a new hardware
+feature may be able to advertise it to user programs.
+
+There will be a standardized convention for the base level of
+architected CPU features available when the cpufeatures binding exists.
+(XXX TBD)
+
+cpufeatures node binding
+------------------------
+
+Node: cpufeatures
+
+Description: Container of CPU feature nodes.
+
+The node name must be "cpufeatures" and should be a child of the root
+node "/".
+
+The node is optional but should be provided by new firmware.
+
+Each child node of cpufeatures represents an architected CPU feature.
+
+
+feature node bindings
+---------------------
+
+Node: A string describing an architected CPU feature, e.g., "vsx".
+
+Description: An architected feature supported by the CPUs.
+
+The name of the node will follow a convention such that software will
+match known features by a string comparison with the node name. Presence
+of the node indicates the feature is available to use (XXX: could
+advertise all supported by hardware, with disabled/enabled status
+property).
+
+The name of the child node corresponds to the name of the feature.
+Software will detect known features by string matching.
+
+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.
+
+- usable_mask
+ Usage: required
+ Value type: <u32> bit mask
+ Definition:
+ 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>
+ Definition:
+ 1 - Custom
+ 2 - HFSCR
+ Other values reserved.
+
+ This property describes the HV privilege state support required to
+ enable the feature. If the property does not exist then no support is
+ required.
+
+ If the value of this property is 1, then the hypervisor must have
+ explicit support for this feature.
+
+ If the value of this property is 2, then the hfscr_bit_nr property
+ will exist.
+
+- os_support
+ Usage: optional
+ Value type: <u32>
+ Definition:
+ 1 - Custom
+ 2 - FSCR
+ Other values reserved.
+
+ This property describes the OS privilege state support required to
+ enable the feature. If the property does not exist then no support is
+ required.
+
+ If the value of this property is 1, then the operating system must
+ have explicit support for this feature.
+
+ If the value of this property is 2, then the fscr_bit_nr property will
+ exist.
+
+- hfscr_bit_nr
+ Usage: optional
+ Value type: <u32>
+ Definition:
+
+ This property exists when the hv_support property value is 2. This
+ property describes the bit number in the HFSCR register that the
+ hypervisor must set in order to enable this feature.
+
+- fscr_bit_nr
+ Usage: optional
+ Value type: <u32>
+ Definition:
+
+ This property exists when the os_support property value is 2. This
+ property describes the bit number in the FSCR register that the
+ operating system must set in order to enable this feature.
+
+- hwcap_bit_nr
+ Usage: optional
+ Value type: <u32>
+ Definition:
+
+ This property exists when the usable_mask property value has bit 0
+ (PR) set. This property describes the bit number that must be set in
+ the AT_HWCAP ELF AUX vectors in order to advertise this feature to
+ userspace.
+
+- 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.
+
+
+Example
+-------
+
+ cpufeatures {
+
+ darn {
+ isa = <3000>;
+ usable_mask = <1 | 2 | 4>;
+ hwcap_bit_nr = <xx>;
+ };
+
+ scv {
+ isa = <3000>;
+ usable_mask = <1 | 2>;
+ os_support = <1>;
+ hwcap_bit_nr = <xx>;
+ };
+
+ stop {
+ isa = <3000>;
+ usable_mask = <2 | 4>;
+ hv_support = <1>;
+ os_support = <1>;
+ };
+
+ vsx2 (hypothetical) {
+ isa = <3010>;
+ usable_mask = <1 | 2 | 4>;
+ hv_support = <1>;
+ os_support = <1>;
+ hwcap_bit_nr = <xx>;
+ };
+
+ vsx2_newinsns {
+ isa = <3020>;
+ usable_mask = <1 | 2 | 4>;
+ os_support = <2>;
+ fscr_bit_nr = <xx>;
+ hwcap_bit_nr = <xx>;
+ dependencies = <&vsx2>;
+ };
+
+ };
+