dt-bindings: riscv: deprecate riscv,isa

From: Conor Dooley <[email protected]>

intro
=====

When the RISC-V dt-bindings were accepted upstream in Linux, the base ISA etc had yet to be ratified. By the ratification of the base ISA, incompatible changes had snuck into the specifications - for example the Zicsr and Zifencei extensions were spun out of the base ISA.

Fast forward to today, and the reason for this patch. Currently the riscv,isa dt property permits only a specific subset of the ISA string - in particular it excludes version numbering. With the current constraints, it is not possible to discern whether "rv64i" means that the hart supports the fence.i instruction, for example.
Future systems may choose to implement their own instruction fencing, perhaps using a vendor extension, or they may not implement the optional counter extensions. Software needs a way to determine this.

versioning schemes
==================

"Use the extension versions that are described in the ISA manual" you may say, and it's not like this has not been considered. Firstly, software that parses the riscv,isa property at runtime will need to contain a lookup table of some sort that maps arbitrary versions to versions it understands. There is not a consistent application of version number applied to extensions, with a higgledy-piggledy collection of tags, "bare" and versioned documents awaiting the reader on the "recently ratified extensions" page:
https://wiki.riscv.org/display/HOME/Recently+Ratified+Extensions

As an aside, and this is reflected in the patch too, since many extensions have yet to appear in a release of the ISA specs, they are defined by commits in their respective "working draft" repositories.

Secondly, there is an issue of backwards compatibility, whereby allowing numbers in the ISA string, some parsers may be broken. This would require an additional property to be created to even use the versions in this manner.

~boolean properties~ string array property
==========================================

If a new property is needed, the whole approach may as well be looked at from the bottom up. A string with limited character choices etc is hardly the best approach for communicating extension information to software.

Switching to using properties that are defined on a per extension basis, allows us to define explicit meanings for the DT representation of each extension - rather than the current situation where different operating systems or other bits of software may impart different meanings to characters in the string.
Clearly the best source of meanings is the specifications themselves, this just provides us the ability to choose at what point in time the meaning is set. If an extension changes incompatibility in the future, a new property will be required.

Off-list, some of the RVI folks have committed to shoring up the wording in either the ISA specifications, the riscv-isa-manual or
so that in the future, modifications to and additions or removals of features will require a new extension. Codifying that assertion somewhere would make it quite unlikely that compatibility would be broken, but we have the tools required to deal with it, if & when it crops up.
It is in our collective interest, as consumers of extension meanings, to define a scheme that enforces compatibility.

The use of individual elements, rather than a single string, will also permit validation that the properties have a meaning, as well as potentially reject mutually exclusive combinations, or enforce dependencies between extensions. That would not have be possible with the current dt-schema infrastructure for arbitrary strings, as we would need to add a riscv,isa parser to dt-validate!
That's not implemented in this patch, but rather left as future work (for the brave, or the foolish).

parser simplicity
=================

Many systems that parse DT at runtime already implement an function that can check for the presence of a string in an array of string, as it is similar to the process for parsing a list of compatible strings, so a bunch of new, custom, DT parsing should not be needed. Getting rid of "riscv,isa" parsing would be a nice simplification, but unfortunately for backwards compatibility with old dtbs, existing parsers may not be removable - which may greatly simplify
dt parsing code. In Linux, for example, checking for whether a hart supports an extension becomes as simple as:
of_property_match_string(node, "riscv,isa-extensions", "zicbom")

vendor extensions
=================

Compared to riscv,isa, this proposed scheme promotes vendor extensions, oft touted as the strength of RISC-V, to first-class citizens. At present, extensions are defined as meaning what the RISC-V ISA specifications say they do. There is no realistic way of using that interface to provide cross-platform definitions for what vendor extensions mean. Vendor extensions may also have even less consistency than RVI do in terms of versioning, or no care about backwards compatibility.
The new property allows us to assign explicit meanings on a per vendor extension basis, backed up by a description of their meanings.

fin
===

Create a new file to store the extension meanings and a new riscv,isa-base property to replace the aspect of riscv,isa that is not represented by the new property - the base ISA implemented by a hart.

As a starting point, add properties for extensions currently used in Linux.

Finally, mark riscv,isa as deprecated, as removing support for it in existing programs would be an ABI break.

---
Changes in v5:
- s/oneOf/anyOf/ so that having both new and old properties passes dt-validate.

Changes in v4:
- Drop the ACPI section at Anup's request.
- Pick up tags from Rob.
- Reword some counter access clarification bits in I & Zicsr.

Changes in v3:
- Per Rob's suggestion, switch to an array of strings. Cuts down on the size, compared to booleans. It has a standard mechanism for parsing (you need to parse arrays of strings for compatibles). It still allows for having a limited set of explicitly defined properties - so the advantages over a free-form string still apply.
- Pick up Palmer's Ack and Review (although I expect that he will be the one to apply this).

---
 .../devicetree/bindings/riscv/cpus.yaml       |  43 ++-
 .../devicetree/bindings/riscv/extensions.yaml | 250 ++++++++++++++++++
 2 files changed, 270 insertions(+), 23 deletions(-)
 create mode 100644 Documentation/devicetree/bindings/riscv/extensions.yaml

index 67bd239ead0b..38c0b5213736 100644
@@ -25,6 +25,7 @@ description: |
 
 allOf:
   - $ref: /schemas/cpu.yaml#
+  - $ref: extensions.yaml
 
 properties:
   compatible:

@@ -82,25 +83,6 @@ properties:
     description:
       The blocksize in bytes for the Zicboz cache operations.
 
-  riscv,isa:
-    description:
-      Identifies the specific RISC-V instruction set architecture
-      supported by the hart.  These are documented in the RISC-V
-      User-Level ISA document, available from
-      https://riscv.org/specifications/
-
-      Due to revisions of the ISA specification, some deviations
-      have arisen over time.
-      Notably, riscv,isa was defined prior to the creation of the
-      Zicntr, Zicsr, Zifencei and Zihpm extensions and thus "i"
-      implies "zicntr_zicsr_zifencei_zihpm".
-
-      While the isa strings in ISA specification are case
-      insensitive, letters in the riscv,isa string must be all
-      lowercase.
-    $ref: /schemas/types.yaml#/definitions/string
-    pattern: ^rv(?:64|32)imaf?d?q?c?b?k?j?p?v?h?(?:[hsxz](?:[a-z])+)?(?:_[hsxz](?:[a-z])+)*$
-
   # RISC-V has multiple properties for cache op block sizes as the sizes
   # differ between individual CBO extensions
   cache-op-block-size: false

@@ -139,8 +121,17 @@ properties:
       DMIPS/MHz, relative to highest capacity-dmips-mhz
       in the system.
 
+anyOf:
+  - required:
+      - riscv,isa
+  - required:
+      - riscv,isa-base
+
+dependencies:
+  riscv,isa-base: [ "riscv,isa-extensions" ]
+  riscv,isa-extensions: [ "riscv,isa-base" ]
+
 required:
-  - riscv,isa
   - interrupt-controller
 
 unevaluatedProperties: false

@@ -160,7 +151,9 @@ examples:
                 i-cache-sets = <128>;
                 i-cache-size = <16384>;
                 reg = <0>;
-                riscv,isa = "rv64imac";
+                riscv,isa-base = "rv64i";
+                riscv,isa-extensions = "i", "m", "a", "c";
+
                 cpu_intc0: interrupt-controller {
                         #interrupt-cells = <1>;
                         compatible = "riscv,cpu-intc";

@@ -183,8 +176,10 @@ examples:
                 i-tlb-size = <32>;
                 mmu-type = "riscv,sv39";
                 reg = <1>;
-                riscv,isa = "rv64imafdc";
                 tlb-split;
+                riscv,isa-base = "rv64i";
+                riscv,isa-extensions = "i", "m", "a", "f", "d", "c";
+
                 cpu_intc1: interrupt-controller {
                         #interrupt-cells = <1>;
                         compatible = "riscv,cpu-intc";

@@ -202,8 +197,10 @@ examples:
                 device_type = "cpu";
                 reg = <0>;
                 compatible = "riscv";
-                riscv,isa = "rv64imafdc";
                 mmu-type = "riscv,sv48";
+                riscv,isa-base = "rv64i";
+                riscv,isa-extensions = "i", "m", "a", "f", "d", "c";
+
                 interrupt-controller {
                         #interrupt-cells = <1>;
                         interrupt-controller;

2.39.2

Applied, thanks!

[1/1] dt-bindings: riscv: deprecate riscv,isa

      https://git.kernel.org/palmer/c/aeb71e42caae

Best regards,

Palmer Dabbelt <[email protected]>