[docs][RISCV] Document experimental extensions

[reames]

Summary

This adds a description of the currently existing experimental extensions. I took all information about versions and specifications from either the original commits, or current code. I'm not terribly familiar with any of these, so double checking my facts is much appreciated.

[sunshaoce]

llvm/docs/RISCVUsage.rst

106

Zihintntl can be found in chapter 4 of riscv-isa-manual .

[reames]

llvm/docs/RISCVUsage.rst

106

Agreed, thanks for the link.

Do you happen to know if RVI has a convention for referring to unreleased version of the specification. I'd default to something like: "The 20220831 draft version of the X specification". (I definitely want a PDF, and not a link to the repo itself.)

[kito-cheng]

llvm/docs/RISCVUsage.rst

106

You can found pdf in github release page: https://github.com/riscv/riscv-isa-manual/releases

[reames]

llvm/docs/RISCVUsage.rst

106

I know, that wasn't my question.

[reames]

Add zihintntl doc link and fix a couple typos.

[frasercrmck]

llvm/docs/RISCVUsage.rst

100

bitmanpip -> bitmanip

[eopXD]

Maybe add description that says -menable-experimental-extensions is required to use them in Clang?

[reames]

Address review comments and add recently landed Ztso experimental extension.

[craig.topper]

llvm/docs/RISCVUsage.rst

100

similiar -> similar

114

preceed -> precede. Though "prefix" might be better in this context?

[reames]

Fix typos

[asb]

LGTM in that I'd be happy for this to land as-is and to continue iterating in future reviews. I've left a couple of comments inline though.

llvm/docs/RISCVUsage.rst

97

Two thoughts here - if there's something you'd like to take from it in another revision of this patch that's great, but I'm also equally happy to land this as-is and continue work in follow-up patches.

I actually have a slightly different perspective on this. I think there's a second goal that is at least as important as supporting ratification, which is to help avoid duplicated or wasted effort on downstream forks and to avoid the problems (technical, potentially even licensing) that would ensue from later trying to merge a work from a long-lived downstream work that had been developed outside of LLVM's standard collaboration infrastructure and methodologies.

I'd maybe clarify that our policies on experimental extensions as they stand only apply to extensions that are understood to be on a path towards ratification as a standard extension. Perhaps changing "The decision on whether to accept an experimental extension is currently done on an entirely case by case basis, though as it stands we've only agreed a policy that allows accepting such extensions if they are understood to be on a path towards eventual ratification as a standard RISC-V extension."

In case you hadn't seen it, see here for more background.

[reames]

llvm/docs/RISCVUsage.rst

97

This gets complicated. :)

In this review, I was specifically trying not to take a position on a couple of potentially controversial cases. I do think we need to incorporate these, but I figured some discussion at a sync call was probably warranted. I used the case by case wording to try to leave maximum flexibility until we'd had that conversation.

Case 1 - Extension on clear path to ratification. This is the easy case.

Case 2 - Extension which has stalled on path to ratification with no significant uptake. Ex: Several of the bitmanip variants. Maybe we want to consider extensions with alternatives different than those without?

Case 3 - Vendor extension which is "done" and exists in real hardware. Assume custom encoding space for this item.

Case 4 - In development vendor extensions which haven't yet shipped.

Case 5 - Experimental extension which isn't ratified, but is shipped by a vendor. With sub-cases for encodings chosen in the custom space, and overlapping the general space. (i.e. someone thought it was getting ratified and misjudged.)

Case 6 - Vendor has a hardware bug, and we have a defacto vendor extension which overlaps with generic encoding space and maybe even claims generic extension support. (Narrower in scope than 5, but probably the most annoying.)

My, not completely thought through, take is that we need to define a vendor extension policy, and then our stance on which experimental ones to accept gets broadened to include either on path to ratification or on path to vendor status.

p.s. Thanks for the link. I'd forgotten that. Most of the discussion seemed focus on the mechanics (which this change documents), as opposed to the boundaries on what we should accept. Unless I misread?

[asb]

llvm/docs/RISCVUsage.rst

97

You're right, the discussion was very focused on mechanics and on the very narrow topic of extensions believed to be on a path towards ratification. Extension being stuck in limbo (like a number of the bitmanip extensions) is also an eventuality that wasn't really considered.

llvm/docs/RISCVUsage.rst

 
 Supported
   Fully supported by the compiler.  This includes everything in Assembly Support, along with - if relevant - C language intrinsics for the instructions and pattern matching by the compiler to recognize idiomatic patterns which can be lowered to the associated instructions.
 
 ``Zve32x``, ``Zve32f``, ``Zvl32b``
   LLVM currently assumes a minimum VLEN (vector register width) of 64 bits during compilation, and as a result ``Zve32x`` and ``Zve32f`` are supported only for VLEN>=64.  Assembly support doesn't have this restriction.
 
 
+Experimental Extensions
+=======================
+
+LLVM supports (to various degrees) a number of experimental extensions.  All experimental extensions have ``experimental-`` as a prefix.  There is explicitly no compatibility promised between versions of the toolchain, and regular users are strongly advised *not* to make use of experimental extensions before they reach ratification.
+
+The primary goal of experimental support is to assist in the process of ratification by providing an existence proof of an implementation, and simplifying efforts to validate the value of a proposed extension against large code bases.  Experimental extensions are expected to either transition to ratified status, or be eventually removed.  The decision on whether to accept an experimental extension is currently done on an entirely case by case basis; if you want to propose one, attending the bi-weekly RISC-V sync-up call is strongly advised.
+
+``experimental-zbe``, ``experimental-zbf``, ``experimental-zbm``, ``experimental-zbp``, ``experimental-zbr``, ``experimental-zbt``
+  LLVM implements the `latest state of the bitmanip working branch <https://github.com/riscv/riscv-bitmanip/tree/main-history>`_, which is largely similar to the 0.93 draft specification but with some instruction naming changes.  These are individual portions of the bitmanip efforts which did *not* get ratified.  Given ratification for these sub-extensions appears stalled; they are a likely candidate for removal in the future.
+
+``experimental-zca``
+  LLVM implements the `0.70 draft specification <https://github.com/riscv/riscv-code-size-reduction/releases/tag/V0.70.1-TOOLCHAIN-DEV>`_.
+
+``experimental-zihintntl``
+  LLVM implements the `0.2 draft specification <https://github.com/riscv/riscv-isa-manual/releases/tag/draft-20220831-bf5a151>`_.
+
+``experimental-ztso``
+  LLVM implements the `v0.1 proposed specification <https://github.com/riscv/riscv-isa-manual/releases/download/draft-20220723-10eea63/riscv-spec.pdf>`_ (see Chapter 25).  Using will set appropriate ELF flags and attributes, but does not yet change code generation.
+
+``experimental-zvfh``
+  LLVM implements `this draft text <https://github.com/riscv/riscv-v-spec/pull/780>`_.
+
+To use an experimental extension from `clang`, you must add `-menable-experimental-extensions` to the command line, and specify the exact version of the experimental extension you are using.  To use an experimental extension with LLVM's internal developer tools (e.g. `llc`, `llvm-objdump`, `llvm-mc`), you must prefix the extension name with `experimental-`.  Note that you don't need to specify the version with internal tools, and shouldn't include the `experimental-` prefix with `clang`.
+
 Specification Documents
 =======================
 For ratified specifications, please refer to the `official RISC-V International
 page <https://riscv.org/technical/specifications/>`_.  Make sure to check the
 `wiki for not yet integrated extensions
 <https://wiki.riscv.org/display/HOME/Recently+Ratified+Extensions>`_.