[docs] Add a RISC-V Usage page

[reames]

Summary

This follows the pattern set by e.g. SPIR-V, AMDGPU, and WebAssembly.

For the moment, this page is fairly minimal stub. I mostly want a place to record which extensions we support, and when that support is not complete, a central place to note that. I'm deliberately starting with a subset of extensions which are pretty straight forward with only one case needing a detail note.

I figure the partial support cases are going to need a bunch of discussion, and having each of them in their own review seemed worthwhile. Similarly, the experimental extensions probably fall into the same bucket of triggering a bunch of review discussion.

[reames]

Fix a couple minor formatting mistakes

[jrtc27]

llvm/docs/RISCVUsage.rst

28–29

Too much time spent with RVV?...

51

I don't believe so?

53

.. ish, the CSRs are there but we're still at I2P0 so Zicsr doesn't really exist

54

ditto

[craig.topper]

llvm/docs/RISCVUsage.rst

59

Zve32x and Zve32f are supported as long as used with Zvl64b or larger

73

bytes -> bits

[frasercrmck]

Thanks for doing this!

llvm/docs/RISCVUsage.rst

2

RISC-V

72

Maybe have these back-ticked for consistency?

[asb]

Thanks for kicking this off - it's a great idea! I left a few notes inline. One thing I'm wondering about is what level of information it might be useful to give beyond just "supported". It might for instance be useful to indicate whether support is just at the MC layer or MC layer + codegen. If we were to do so, would just having a "codegen" category that encompasses automatic ISel as well as intrinsics where relevant be sufficient (I think so?).

[EDIT: and sorry for not fully processing your description about leaving off the "less straightforward" extensions prior to submitting comments]

llvm/docs/RISCVUsage.rst

18

I think RV32E is typically described as a base instruction set too (albeit one that is actually a subset of RV32I).

53

Plus Zicbop, Zicboz, Zicbom

58

Also Zbkb, Zbkc, Zbkx. MC layer support for Zfinx/Zdinx too

Plus various Zk* extensions.

[kito-cheng]

llvm/docs/RISCVUsage.rst

64

Maybe mark as MC-layer only?

[reames]

llvm/docs/RISCVUsage.rst

18

Do we support RV32E? You're right that this seems to be a base instruction set. If we do support it, how do we name that argument wise?

For now, I updated the text to indicate we didn't support RV32E, but I'm unsure if this is correct.

28–29

Apparently, good catch.

51

I'm unclear. I thought it was supported, but hadn't investigated in detail. Removed for now, will move to future patch.

53

@jrtc27 I don't follow your comment here. For the moment, I'm going to remove these.

@asb I'd deliberately left those out for the moment as I wasn't sure if the C intrinsics were implemented. I'll add in a follow on patch once I've double checked.

54

@jrtc27 Moved to follow up. I'd checked this one and thought we did support IFENCE, but maybe I was mistaken.

58

Let's do these in follow up patches.

64

Is it even supported by assembler? It could be, but I hadn't thought to check.

[reames]

Address review comments - mostly by subsetting

[kito-cheng]

llvm/docs/RISCVUsage.rst

18

RV32E is supported in MC-layer[1] but not CodeGen[2], and we have RV64E ISA[2] now, that should be worth to mention that we are not support that here.

[1] https://reviews.llvm.org/D59470
[2] https://github.com/llvm/llvm-project/blob/main/llvm/lib/Target/RISCV/RISCVISelLowering.cpp#L53
[2] https://github.com/riscv/riscv-isa-manual/commit/b5f94a845760af00ff2743dd9f2269fd68236576

64

Zvl32b isn't define any instruction or CSRs, just a information about the VLEN is larger than 32 bits.

[reames]

Address Kito's comments.

[tschuett]

Are you going make a distinction between support on trunk and shipped with LLVM15?

[reames]

In D133063#3767071, @tschuett wrote:

Are you going make a distinction between support on trunk and shipped with LLVM15?

Docs always follow a release branch with the default being ToT. So, effectively LLVM 15 will not have this page, LLVM 16 will.

If you have specific extensions where documenting support isn't available in the 15 release, point them out. We might add text on a case by case basis.

llvm/docs/RISCVUsage.rst

18

I'll add in the RV32E bit - thanks for the links.

I'm not going to add RV64E as that's not yet in a ratified version of the specification. We can consider adding it under experimental once we have in tree code for it.

[reames]

Anything holding this back? I'd like to get it in so that we can build off it.

[craig.topper]

llvm/docs/RISCVUsage.rst

71

Why does this stop at 1024?

[reames]

llvm/docs/RISCVUsage.rst

72

Because the table in the spec stopped at 1024, and I skimmed over the "Longer vector length extensions should follow the same pattern. wording. Will update to add the others.

[reames]

Add missing ZvlNb variants.

[craig.topper]

llvm/docs/RISCVUsage.rst

72

Doesn't it go to Zvl65536b?

79

dissambler -> disassembler

[reames]

llvm/docs/RISCVUsage.rst

73

16k, 64k, what's the difference? Thanks for catching, apparently my brain hasn't returned from the long weekend yet.

[craig.topper]

Do we need a link from the main documentation to this page?

[craig.topper]

LGTM

llvm/docs/RISCVUsage.rst

+=============================
+User Guide for RISCV-V Target
+=============================
+
+.. contents::
+   :local:
+
+Introduction
+============
+
+The RISC-V target provides code generation for processors implementing
+supported variations of the RISC-V specification.  It lives in the
+``llvm/lib/Target/RISCV`` directory.
+
+Base ISAs
+=========
+
+The specification defines three base instruction sets: RV32I, RV64I, and RV128I.
+Currently, LLVM supports RV32I, and RV64I, but not RV128I.
+
+To specify the target triple:
+
+  .. table:: RISC-V Architectures
+
+     ============ ==============================================================
+     Architecture Description
+     ============ ==============================================================
+     ``riscv32``   RISC-V with ELEN=32
+     ``riscv64``   RISC-V with ELEN=64
+     ============ ==============================================================
+
+.. _riscv-extensions:
+
+Extensions
+==========
+
+The following table provides a status summary for extensions which have been
+ratified and thus have finalized specifications.  When relevant, detailed notes
+on support follow.
+
+  .. table:: Ratified Extensions by Status
+
+     =============  ========================
+     Extension      Status
+     =============  ========================
+     ``A``          Supported
+     ``C``          Supported
+     ``D``          Supported
+     ``F``          Supported
+     ``M``          Supported
+     ``Q``          Supported
+     ``V``          Supported
+     ``Zicsr``      Supported
+     ``Zifencei``   Supported
+     ``Zba``        Supported
+     ``Zbb``        Supported
+     ``Zbc``        Supported
+     ``Zbs``        Supported
+     ``Zve32x``     Unsupported
+     ``Zve32f``     Unsupported
+     ``Zve64x``     Supported
+     ``Zve64f``     Supported
+     ``Zve64d``     Supported
+     ``Zvl32b``     Unsupported
+     ``Zvl64b``     Supported
+     ``Zvl128b``    Supported
+     ``Zvl256b``    Supported
+     ``Zvl512b``    Supported
+     ``Zvl1024b``   Supported
+     =============  ========================
+
+Zve32x, Zve32f, Zvl32b
+  LLVM currently assumes a minimum VLEN (vector register width) of 64 bytes.
+
+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>`_.
+