diff options
Diffstat (limited to 'llvm/docs')
| -rw-r--r-- | llvm/docs/CIBestPractices.rst | 22 | ||||
| -rw-r--r-- | llvm/docs/CodingStandards.rst | 6 | ||||
| -rw-r--r-- | llvm/docs/RISCVUsage.rst | 14 | ||||
| -rw-r--r-- | llvm/docs/SPIRVUsage.rst | 30 |
4 files changed, 54 insertions, 18 deletions
diff --git a/llvm/docs/CIBestPractices.rst b/llvm/docs/CIBestPractices.rst index 8301b95..da92ed3 100644 --- a/llvm/docs/CIBestPractices.rst +++ b/llvm/docs/CIBestPractices.rst @@ -9,11 +9,11 @@ This document contains a list of guidelines and best practices to use when working on LLVM's CI systems. These are intended to keep our actions reliable, consistent, and secure. -Github Actions Best Practices +GitHub Actions Best Practices ============================= This section contains information on best practices/guidelines when working on -LLVM's github actions workflows. +LLVM's GitHub actions workflows. Disabling Jobs In Forks ----------------------- @@ -35,7 +35,7 @@ jobs specified within a workflow: if: github.repository_owner == 'llvm' We choose to use ``github.repository_owner`` rather than ``github.repository`` -to enable these workflows to run in forks inside the LLVM organization such as +to enable these workflows to run in forks inside the LLVM organization, such as the ClangIR fork. There are some exceptions to this rule where ``github.repository`` might be @@ -46,7 +46,7 @@ release tasks, which should not run anywhere else. Hash Pinning Dependencies ------------------------- -Github Actions allows the use of actions from other repositories as steps in +GitHub Actions allows the use of actions from other repositories as steps in jobs. We take advantage of various actions for a variety of different tasks, but especially tasks like checking out the repository, and downloading/uploading build caches. These actions are typically versioned with @@ -59,9 +59,9 @@ just a release, which looks like the following: uses: actions/checkout@v4 However, it is best practice to specify an exact commit SHA from which to pull -the action from, noting the version in a comment: +the action, noting the version in a comment: -We plan on revisiting this recommendation once Github's immutable actions have +We plan on revisiting this recommendation once GitHub's immutable actions have been rolled out as GA. .. code-block:: yaml @@ -72,11 +72,11 @@ been rolled out as GA. This is beneficial for two reasons: reliability and security. Specifying an exact SHA rather than just a major version ensures we end up running the same -action originally specified when the workflow as authored and/or updated, +action originally specified when the workflow was authored and/or updated, and that no breaking changes sneak in from new versions of a workflow being released. However, this effect could also be achieved by specifying an exact dot release. The biggest reason to prefer hash pinned dependencies is security. -Release assets on Github are mutable, allowing an attacker to change the code +Release assets on GitHub are mutable, allowing an attacker to change the code within a specific version of an action after the fact, potentially stealing sensitive tokens and credentials. Hash pinning the dependencies prevents this as the hash would change with the code. @@ -84,10 +84,10 @@ as the hash would change with the code. Using Versioned Runner Images ----------------------------- -Github actions allows the use of either specifically versioned runner images +GitHub actions allows the use of either specifically versioned runner images (e.g., ``ubuntu-22.04``), or just the latest runner image (e.g., ``ubuntu-latest``). It is best practice to use explicitly versioned -runner images. This prevents breakages when Github rolls the latest runner +runner images. This prevents breakages when GitHub rolls the latest runner image to a new version with potentially breaking changes, instead allowing us to explicitly opt-in to using the new image when we have done sufficient testing to ensure that our existing workflows work as expected in the new @@ -112,7 +112,7 @@ the principle of least privilege. Ensuring Workflows Run on the Correct Events -------------------------------------------- -Github allows workflows to run on a multitude of events and it is important to +GitHub allows workflows to run on a multitude of events, and it is important to configure a workflow such that it triggers on the correct events. There are two main best practices around events that trigger workflows: diff --git a/llvm/docs/CodingStandards.rst b/llvm/docs/CodingStandards.rst index dd275f2..65dd794 100644 --- a/llvm/docs/CodingStandards.rst +++ b/llvm/docs/CodingStandards.rst @@ -1790,6 +1790,12 @@ would help to avoid running into a "dangling else" situation. markAsIgnored(D); } +Use Unix line endings for files +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Use Unix line endings for all files. CRLF line endings are allowed as an +exception for test files that intend to test CRLF handling or when the file +format requires it (like ``.bat`` or ``.rc`` files). See Also ======== diff --git a/llvm/docs/RISCVUsage.rst b/llvm/docs/RISCVUsage.rst index 7b1a6ce..f9e2e4a 100644 --- a/llvm/docs/RISCVUsage.rst +++ b/llvm/docs/RISCVUsage.rst @@ -120,6 +120,8 @@ on support follow. ``H`` Assembly Support ``M`` Supported ``Q`` Assembly Support + ``Sdext`` Assembly Support (`See note <#riscv-debug-specification-note>`__) + ``Sdtrig`` Assembly Support (`See note <#riscv-debug-specification-note>`__) ``Sha`` Supported ``Shcounterenw`` Assembly Support (`See note <#riscv-profiles-extensions-note>`__) ``Shgatpa`` Assembly Support (`See note <#riscv-profiles-extensions-note>`__) @@ -132,6 +134,7 @@ on support follow. ``Smcdeleg`` Supported ``Smcntrpmf`` Supported ``Smcsrind`` Supported + ``Smctr`` Assembly Support ``Smdbltrp`` Supported ``Smepmp`` Supported ``Smmpm`` Supported @@ -144,6 +147,7 @@ on support follow. ``Sscofpmf`` Assembly Support ``Sscounterenw`` Assembly Support (`See note <#riscv-profiles-extensions-note>`__) ``Sscsrind`` Supported + ``Ssctr`` Assembly Support ``Ssdbltrp`` Supported ``Ssnpm`` Supported ``Sspm`` Supported @@ -306,6 +310,10 @@ Supported ``Za128rs``, ``Za64rs``, ``Zama16b``, ``Zic64b``, ``Ziccamoa``, ``Ziccamoc``, ``Ziccif``, ``Zicclsm``, ``Ziccrse``, ``Shcounterenvw``, ``Shgatpa``, ``Shtvala``, ``Shvsatpa``, ``Shvstvala``, ``Shvstvecd``, ``Ssccptr``, ``Sscounterenw``, ``Ssstateen``, ``Ssstrict``, ``Sstvala``, ``Sstvecd``, ``Ssu64xl``, ``Svade``, ``Svbare`` These extensions are defined as part of the `RISC-V Profiles specification <https://github.com/riscv/riscv-profiles/releases/tag/v1.0>`__. They do not introduce any new features themselves, but instead describe existing hardware features. +.. _riscv-debug-specification-note: + +``Sdext``, ``Sdtrig`` `The RISC-V Debug Specification <https://github.com/riscv/riscv-debug-spec/releases/download/1.0/riscv-debug-specification.pdf>`__. + .. _riscv-zacas-note: ``Zacas`` @@ -337,12 +345,6 @@ The primary goal of experimental support is to assist in the process of ratifica ``experimental-zvbc32e``, ``experimental-zvkgs`` LLVM implements the `0.7 release specification <https://github.com/user-attachments/files/16450464/riscv-crypto-spec-vector-extra_v0.0.7.pdf>`__. -``experimental-sdext``, ``experimental-sdtrig`` - LLVM implements the `1.0-rc4 specification <https://github.com/riscv/riscv-debug-spec/releases/download/1.0.0-rc4/riscv-debug-specification.pdf>`__. - -``experimental-smctr``, ``experimental-ssctr`` - LLVM implements the `1.0-rc3 specification <https://github.com/riscv/riscv-control-transfer-records/releases/tag/v1.0_rc3>`__. - ``experimental-svukte`` LLVM implements the `0.3 draft specification <https://github.com/riscv/riscv-isa-manual/pull/1564>`__. diff --git a/llvm/docs/SPIRVUsage.rst b/llvm/docs/SPIRVUsage.rst index fdefc53..b6cd4b4 100644 --- a/llvm/docs/SPIRVUsage.rst +++ b/llvm/docs/SPIRVUsage.rst @@ -232,7 +232,7 @@ Below is a list of supported SPIR-V extensions, sorted alphabetically by their e * - ``SPV_INTEL_int4`` - Adds support for 4-bit integer type, and allow this type to be used in cooperative matrices. * - ``SPV_KHR_float_controls2`` - - Adds ability to specify the floating-point environment in shaders. It can be used on whole modules and individual instructions. + - Adds execution modes and decorations to control floating-point computations in both kernels and shaders. It can be used on whole modules and individual instructions. SPIR-V representation in LLVM IR ================================ @@ -589,3 +589,31 @@ Group and Subgroup Operations For workgroup and subgroup operations, LLVM uses function calls to represent SPIR-V's group-based instructions. These builtins facilitate group synchronization, data sharing, and collective operations essential for efficient parallel computation. + +SPIR-V Instructions Mapped to LLVM Metadata +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Some SPIR-V instructions don't have a direct equivalent in the LLVM IR language. To +address this, the SPIR-V Target uses different specific LLVM named metadata to convey +the necessary information. The SPIR-V specification allows multiple module-scope +instructions, where as LLVM named metadata must be unique. Therefore, the encoding of +such instructions has the following format: + +.. code-block:: llvm + + !spirv.<OpCodeName> = !{!<InstructionMetadata1>, !<InstructionMetadata2>, ..} + !<InstructionMetadata1> = !{<Operand1>, <Operand2>, ..} + !<InstructionMetadata2> = !{<Operand1>, <Operand2>, ..} + +Below, you will find the mappings between SPIR-V instruction and their corresponding +LLVM IR representations. + ++--------------------+---------------------------------------------------------+ +| SPIR-V instruction | LLVM IR | ++====================+=========================================================+ +| OpExecutionMode | .. code-block:: llvm | +| | | +| | !spirv.ExecutionMode = !{!0} | +| | !0 = !{void @worker, i32 30, i32 262149} | +| | ; Set execution mode with id 30 (VecTypeHint) and | +| | ; literal `262149` operand. | ++--------------------+---------------------------------------------------------+ |