TEXT   158
powerpc cpu features
Guest on 6th May 2022 02:23:46 AM


  1. *** NOTE ***
  2. This document is copied from OPAL firmware
  3. (skiboot/doc/device-tree/ibm,powerpc-cpu-features/binding.txt)
  4.  
  5. There is more complete overview and documentation of features in that
  6. source tree.  All patches and modifications should go there.
  7. ************
  8.  
  9. ibm,powerpc-cpu-features binding
  10. ================================
  11.  
  12. This device tree binding describes CPU features available to software, with
  13. enablement, privilege, and compatibility metadata.
  14.  
  15. More general description of design and implementation of this binding is
  16. found in design.txt, which also points to documentation of specific features.
  17.  
  18.  
  19. /cpus/ibm,powerpc-cpu-features node binding
  20. -------------------------------------------
  21.  
  22. Node: ibm,powerpc-cpu-features
  23.  
  24. Description: Container of CPU feature nodes.
  25.  
  26. The node name must be "ibm,powerpc-cpu-features".
  27.  
  28. It is implemented as a child of the node "/cpus", but this must not be
  29. assumed by parsers.
  30.  
  31. The node is optional but should be provided by new OPAL firmware.
  32.  
  33. Properties:
  34.  
  35. - compatible
  36.   Usage: required
  37.   Value type: string
  38.   Definition: "ibm,powerpc-cpu-features"
  39.  
  40.   This compatibility refers to backwards compatibility of the overall
  41.   design with parsers that behave according to these guidelines. This can
  42.   be extended in a backward compatible manner which would not warrant a
  43.   revision of the compatible property.
  44.  
  45. - isa
  46.   Usage: required
  47.   Value type: <u32>
  48.   Definition:
  49.  
  50.   isa that the CPU is currently running in. This provides instruction set
  51.   compatibility, less the individual feature nodes. For example, an ISA v3.0
  52.   implementation that lacks the "transactional-memory" cpufeature node
  53.   should not use transactional memory facilities.
  54.  
  55.   Value corresponds to the "Power ISA Version" multiplied by 1000.
  56.   For example, <3000> corresponds to Version 3.0, <2070> to Version 2.07.
  57.   The minor digit is available for revisions.
  58.  
  59. - display-name
  60.   Usage: optional
  61.   Value type: string
  62.   Definition:
  63.  
  64.   A human readable name for the CPU.
  65.  
  66. /cpus/ibm,powerpc-cpu-features/example-feature node bindings
  67. ----------------------------------------------------------------
  68.  
  69. Each child node of cpu-features represents a CPU feature / capability.
  70.  
  71. Node: A string describing an architected CPU feature, e.g., "floating-point".
  72.  
  73. Description: A feature or capability supported by the CPUs.
  74.  
  75. The name of the node is a human readable string that forms the interface
  76. used to describe features to software. Features are currently documented
  77. in the code where they are implemented in skiboot/core/cpufeatures.c
  78.  
  79. Presence of the node indicates the feature is available.
  80.  
  81. Properties:
  82.  
  83. - isa
  84.   Usage: required
  85.   Value type: <u32>
  86.   Definition:
  87.  
  88.   First level of the Power ISA that the feature appears in.
  89.   Software should filter out features when constraining the
  90.   environment to a particular ISA version.
  91.  
  92.   Value is defined similarly to /cpus/features/isa
  93.  
  94. - usable-privilege
  95.   Usage: required
  96.   Value type: <u32> bit mask
  97.   Definition:
  98.               Bit numbers are LSB0
  99.               bit 0 - PR (problem state / user mode)
  100.               bit 1 - OS (privileged state)
  101.               bit 2 - HV (hypervisor state)
  102.               All other bits reserved and should be zero.
  103.  
  104.   This property describes the privilege levels and/or software components
  105.   that can use the feature.
  106.  
  107.   If bit 0 is set, then the hwcap-bit-nr property will exist.
  108.  
  109.  
  110. - hv-support
  111.   Usage: optional
  112.   Value type: <u32> bit mask
  113.   Definition:
  114.               Bit numbers are LSB0
  115.               bit 0 -  HFSCR
  116.               All other bits reserved and should be zero.
  117.  
  118.   This property describes the HV privilege support required to enable the
  119.   feature to lesser privilege levels. If the property does not exist then no
  120.   support is required.
  121.  
  122.   If no bits are set, the hypervisor must have explicit/custom support for
  123.   this feature.
  124.  
  125.   If the HFSCR bit is set, then the hfscr-bit-nr property will exist and
  126.   the feature may be enabled by setting this bit in the HFSCR register.
  127.  
  128.  
  129. - os-support
  130.   Usage: optional
  131.   Value type: <u32> bit mask
  132.   Definition:
  133.               Bit numbers are LSB0
  134.               bit 0 -  FSCR
  135.               All other bits reserved and should be zero.
  136.  
  137.   This property describes the OS privilege support required to enable the
  138.   feature to lesser privilege levels. If the property does not exist then no
  139.   support is required.
  140.  
  141.   If no bits are set, the operating system must have explicit/custom support
  142.   for this feature.
  143.  
  144.   If the FSCR bit is set, then the fscr-bit-nr property will exist and
  145.   the feature may be enabled by setting this bit in the FSCR register.
  146.  
  147.  
  148. - hfscr-bit-nr
  149.   Usage: optional
  150.   Value type: <u32>
  151.   Definition: HFSCR bit position (LSB0)
  152.  
  153.   This property exists when the hv-support property HFSCR bit is set. This
  154.   property describes the bit number in the HFSCR register that the
  155.   hypervisor must set in order to enable this feature.
  156.  
  157.   This property also exists if an HFSCR bit corresponds with this feature.
  158.   This makes CPU feature parsing slightly simpler.
  159.  
  160.  
  161. - fscr-bit-nr
  162.   Usage: optional
  163.   Value type: <u32>
  164.   Definition: FSCR bit position (LSB0)
  165.  
  166.   This property exists when the os-support property FSCR bit is set. This
  167.   property describes the bit number in the FSCR register that the
  168.   operating system must set in order to enable this feature.
  169.  
  170.   This property also exists if an FSCR bit corresponds with this feature.
  171.   This makes CPU feature parsing slightly simpler.
  172.  
  173.  
  174. - hwcap-bit-nr
  175.   Usage: optional
  176.   Value type: <u32>
  177.   Definition: Linux ELF AUX vector bit position (LSB0)
  178.  
  179.   This property may exist when the usable-privilege property value has PR bit set.
  180.   This property describes the bit number that should be set in the ELF AUX
  181.   hardware capability vectors in order to advertise this feature to userspace.
  182.   Bits 0-31 correspond to bits 0-31 in AT_HWCAP vector. Bits 32-63 correspond
  183.   to 0-31 in AT_HWCAP2 vector, and so on.  Missing AT_HWCAPx vectors implies
  184.   that the feature is not enabled or can not be advertised. Operating systems
  185.   may provide a number of unassigned hardware capability bits to allow for new
  186.   features to be advertised.
  187.  
  188.   Some properties representing features created before this binding are
  189.   advertised to userspace without a one-to-one hwcap bit number may not specify
  190.   this bit. Operating system will handle those bits specifically.  All new
  191.   features usable by userspace will have a hwcap-bit-nr property.
  192.  
  193.  
  194. - dependencies
  195.   Usage: optional
  196.   Value type: <prop-encoded-array>
  197.   Definition:
  198.  
  199.   If this property exists then it is a list of phandles to cpu feature
  200.   nodes that must be enabled for this feature to be enabled.
  201.  
  202.  
  203. Example
  204. -------
  205.  
  206.         /cpus/ibm,powerpc-cpu-features {
  207.                 compatible = "ibm,powerpc-cpu-features";
  208.  
  209.                 isa = <3020>;
  210.  
  211.                 darn {
  212.                         isa = <3000>;
  213.                         usable-privilege = <1 | 2 | 4>;
  214.                         hwcap-bit-nr = <xx>;
  215.                 };
  216.  
  217.                 scv {
  218.                         isa = <3000>;
  219.                         usable-privilege = <1 | 2>;
  220.                         os-support = <0>;
  221.                         hwcap-bit-nr = <xx>;
  222.                 };
  223.  
  224.                 stop {
  225.                         isa = <3000>;
  226.                         usable-privilege = <2 | 4>;
  227.                         hv-support = <0>;
  228.                         os-support = <0>;
  229.                 };
  230.  
  231.                 vsx2 (hypothetical) {
  232.                         isa = <3010>;
  233.                         usable-privilege = <1 | 2 | 4>;
  234.                         hv-support = <0>;
  235.                         os-support = <0>;
  236.                         hwcap-bit-nr = <xx>;
  237.                 };
  238.  
  239.                 vsx2-newinsns {
  240.                         isa = <3020>;
  241.                         usable-privilege = <1 | 2 | 4>;
  242.                         os-support = <1>;
  243.                         fscr-bit-nr = <xx>;
  244.                         hwcap-bit-nr = <xx>;
  245.                         dependencies = <&vsx2>;
  246.                 };
  247.  
  248.         };
Raw Paste

Login or Register to edit or fork this paste. It's free.