[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

29–30

Too much time spent with RVV?...

52

I don't believe so?

54

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

55

ditto

[craig.topper]

llvm/docs/RISCVUsage.rst

60

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

74

bytes -> bits

[frasercrmck]

Thanks for doing this!

llvm/docs/RISCVUsage.rst

3

RISC-V

73

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

19

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

54

Plus Zicbop, Zicboz, Zicbom

59

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

Plus various Zk* extensions.

[kito-cheng]

llvm/docs/RISCVUsage.rst

65

Maybe mark as MC-layer only?

[reames]

llvm/docs/RISCVUsage.rst

19

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.

29–30

Apparently, good catch.

52

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

54

@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.

55

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

59

Let's do these in follow up patches.

65

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

19

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

65

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

19

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

73

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

73

Doesn't it go to Zvl65536b?

79

dissambler -> disassembler

[reames]

llvm/docs/RISCVUsage.rst

74

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 RISC-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 four base instruction sets: RV32I, RV32E, RV64I,
+and RV128I. Currently, LLVM fully supports RV32I, and RV64I.  RV32E is
+supported by the assembly-based tools only.  RV128I is not supported.
+
+To specify the target triple:
+
+  .. table:: RISC-V Architectures
+
+     ============ ==============================================================
+     Architecture Description
+     ============ ==============================================================
+     ``riscv32``   RISC-V with XLEN=32 (i.e. RV32I or RV32E)
+     ``riscv64``   RISC-V with XLEN=64 (i.e. RV64I)
+     ============ ==============================================================
+
+To select an E variant ISA (e.g. RV32E instead of RV32I), use the base
+architecture string (e.g. ``riscv32``) with the extension ``e``.
+
+.. _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
+     ``V``          Supported
+     ``Zba``        Supported
+     ``Zbb``        Supported
+     ``Zbc``        Supported
+     ``Zbs``        Supported
+     ``Zve32x``     Partially Supported
+     ``Zve32f``     Partially Supported
+     ``Zve64x``     Supported
+     ``Zve64f``     Supported
+     ``Zve64d``     Supported
+     ``Zvl32b``     Partially Supported
+     ``Zvl64b``     Supported
+     ``Zvl128b``    Supported
+     ``Zvl256b``    Supported
+     ``Zvl512b``    Supported
+     ``Zvl1024b``   Supported
+     ``Zvl2048b``   Supported
+     ``Zvl4096b``   Supported
+     ``Zvl8192b``   Supported
+     ``Zvl16384b``  Supported
+     ``Zvl32768b``  Supported
+     ``Zvl65536b``  Supported
+     =============  ========================
+
+``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 tools (e.g. assembler, disassembler, llvm-objdump, etc..) don't have this restriction.
+
+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>`_.
+

llvm/docs/UserGuides.rst

.. toctree::
    JITLink
    NewPassManager
    NVPTXUsage
    Phabricator
    Passes
    ReportingGuide
    ResponseGuide
    Remarks
+   RISCVUsage
    SourceLevelDebugging
    SPIRVUsage
    StackSafetyAnalysis
    SupportLibrary
    TableGen/index
    TableGenFundamentals
    Vectorizers
    WritingAnLLVMPass
:doc:`AMDGPUDwarfExtensionAllowLocationDescriptionOnTheDwarfExpressionStack/AMDGPUDwarfExtensionAllowLocationDescriptionOnTheDwarfExpressionStack`
    :doc:`AMDGPUDwarfExtensionsForHeterogeneousDebugging`.
 
 :doc:`SPIRVUsage`
    This document describes using the SPIR-V target to compile GPU kernels.
 
 :doc:`DirectXUsage`
    This document describes using the DirectX target to compile GPU code for the
    DirectX runtime.
+
+:doc:`RISCVUsage`
+   This document describes using the RISCV-V target.
+