diff options
Diffstat (limited to 'llvm/docs')
| -rw-r--r-- | llvm/docs/CIBestPractices.rst | 22 | ||||
| -rw-r--r-- | llvm/docs/CommandGuide/llvm-readelf.rst | 4 | ||||
| -rw-r--r-- | llvm/docs/CommandGuide/llvm-readobj.rst | 4 | ||||
| -rw-r--r-- | llvm/docs/CommandGuide/llvm-size.rst | 7 | ||||
| -rw-r--r-- | llvm/docs/FuzzingLLVM.rst | 12 | ||||
| -rw-r--r-- | llvm/docs/GettingInvolved.rst | 14 | ||||
| -rw-r--r-- | llvm/docs/GlobalISel/InstructionSelect.rst | 18 | ||||
| -rw-r--r-- | llvm/docs/RISCVUsage.rst | 14 | ||||
| -rw-r--r-- | llvm/docs/SPIRVUsage.rst | 30 |
9 files changed, 92 insertions, 33 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/CommandGuide/llvm-readelf.rst b/llvm/docs/CommandGuide/llvm-readelf.rst index 284c3aa4..5403fea 100644 --- a/llvm/docs/CommandGuide/llvm-readelf.rst +++ b/llvm/docs/CommandGuide/llvm-readelf.rst @@ -143,6 +143,10 @@ OPTIONS Display all notes. +.. option:: --offloading + + Display list of HIP offload bundles. + .. option:: --pretty-print When used with :option:`--elf-output-style`, JSON output will be formatted in diff --git a/llvm/docs/CommandGuide/llvm-readobj.rst b/llvm/docs/CommandGuide/llvm-readobj.rst index 8bd29ea..0d05b94 100644 --- a/llvm/docs/CommandGuide/llvm-readobj.rst +++ b/llvm/docs/CommandGuide/llvm-readobj.rst @@ -104,6 +104,10 @@ file formats. Do not demangle symbol names in the output. This option is only for ELF and XCOFF file formats. The option is enabled by default. +.. option:: --offloading + + Display list of HIP offload bundles. + .. option:: --relocations, --relocs, -r Display the relocation entries in the file. diff --git a/llvm/docs/CommandGuide/llvm-size.rst b/llvm/docs/CommandGuide/llvm-size.rst index f244769..12e7c58 100644 --- a/llvm/docs/CommandGuide/llvm-size.rst +++ b/llvm/docs/CommandGuide/llvm-size.rst @@ -41,6 +41,13 @@ OPTIONS as a separate section entry for ``sysv`` output. If not specified, these symbols are ignored. +.. option:: --exclude-pagezero + + Do not include the ``__PAGEZERO`` segment when calculating size information + for Mach-O files. The ``__PAGEZERO`` segment is a virtual memory region used + for memory protection that does not contribute to actual size, and excluding + can provide a better representation of actual size. + .. option:: -d Equivalent to :option:`--radix` with a value of ``10``. diff --git a/llvm/docs/FuzzingLLVM.rst b/llvm/docs/FuzzingLLVM.rst index a0355d7..76eb428 100644 --- a/llvm/docs/FuzzingLLVM.rst +++ b/llvm/docs/FuzzingLLVM.rst @@ -33,7 +33,7 @@ clang-proto-fuzzer A |protobuf fuzzer| that compiles valid C++ programs generated from a protobuf class that describes a subset of the C++ language. -This fuzzer accepts clang command line options after `ignore_remaining_args=1`. +This fuzzer accepts clang command-line options after `ignore_remaining_args=1`. For example, the following command will fuzz clang with a higher optimization level: @@ -106,7 +106,7 @@ llvm-opt-fuzzer A |LLVM IR fuzzer| aimed at finding bugs in optimization passes. -It receives optimization pipeline and runs it for each fuzzer input. +It receives an optimization pipeline and runs it for each fuzzer input. Interface of this fuzzer almost directly mirrors ``llvm-isel-fuzzer``. Both ``mtriple`` and ``passes`` arguments are required. Passes are specified in a @@ -117,7 +117,7 @@ this format in the doxygen for ``PassBuilder::parsePassPipeline``. % bin/llvm-opt-fuzzer <corpus-dir> -ignore_remaining_args=1 -mtriple x86_64 -passes instcombine -Similarly to the ``llvm-isel-fuzzer`` arguments in some predefined configurations +Similarly to the ``llvm-isel-fuzzer``, arguments in some predefined configurations might be embedded directly into the binary file name: .. code-block:: shell @@ -176,7 +176,7 @@ mutations that a fuzzer in LLVM might want. Generic Random Fuzzing ---------------------- -The most basic form of input mutation is to use the built in mutators of +The most basic form of input mutation is to use the built-in mutators of LibFuzzer. These simply treat the input corpus as a bag of bits and make random mutations. This type of fuzzer is good for stressing the surface layers of a program, and is good at testing things like lexers, parsers, or binary @@ -244,7 +244,7 @@ by adding the following two flags to your CMake invocation: to avoid building the sanitizers themselves with sanitizers enabled. .. note:: You may run into issues if you build with BFD ld, which is the - default linker on many unix systems. These issues are being tracked + default linker on many Unix systems. These issues are being tracked in https://llvm.org/PR34636. Continuously Running and Finding Bugs @@ -280,6 +280,6 @@ your fuzzer can be built and tested when not built against libFuzzer. There is also some handling of the CMake config for fuzzers, where you should use the ``add_llvm_fuzzer`` to set up fuzzer targets. This function works -similarly to functions such as ``add_llvm_tool``, but they take care of linking +similarly to functions such as ``add_llvm_tool``, but it takes care of linking to LibFuzzer when appropriate and can be passed the ``DUMMY_MAIN`` argument to enable standalone testing. diff --git a/llvm/docs/GettingInvolved.rst b/llvm/docs/GettingInvolved.rst index 72716fa..f7e1374 100644 --- a/llvm/docs/GettingInvolved.rst +++ b/llvm/docs/GettingInvolved.rst @@ -42,7 +42,7 @@ LLVM welcomes contributions of all kinds. To get started, please review the foll in the LLVM system. :doc:`BugLifeCycle` - Describes how bugs are reported, triaged and closed. + Describes how bugs are reported, triaged, and closed. :doc:`CodingStandards` Details the LLVM coding standards and provides useful information on writing @@ -108,7 +108,7 @@ The :doc:`CodeOfConduct` applies to all these forums and mailing lists. `Commits Archive (llvm-commits)`__ This list contains all commit messages that are made when LLVM developers commit code changes to the repository. It also serves as a forum for - patch review (i.e. send patches here). It is useful for those who want to + patch review (i.e., send patches here). It is useful for those who want to stay on the bleeding edge of LLVM development. This list is very high volume. @@ -121,7 +121,7 @@ The :doc:`CodeOfConduct` applies to all these forums and mailing lists. .. __: http://lists.llvm.org/pipermail/llvm-bugs/ `LLVM Announcements`__ - If you just want project wide announcements such as releases, developers meetings, or blog posts, then you should check out the Announcement category on LLVM Discourse. + If you just want project-wide announcements such as releases, developers meetings, or blog posts, then you should check out the Announcement category on LLVM Discourse. .. __: https://discourse.llvm.org/c/announce/46 @@ -473,7 +473,7 @@ join one in your city. Or start a new one if there is none: Community wide proposals ------------------------ -Proposals for massive changes in how the community behaves and how the work flow +Proposals for large-scale changes in how the community behaves and how the work flow can be better. .. toctree:: @@ -518,7 +518,7 @@ also be seen inline below: Note that the web view of the LLVM community calendar shows events in Coordinated Universal Time (UTC). If you use Google Calendar, consider subscribing to it with the + button in the bottom-right corner to view all -events in your local timezone alongside your other calendars. +events in your local time zone alongside your other calendars. .. _llvm-community-calendar-host-guidance: @@ -554,9 +554,9 @@ An example invite looks as follows This event is a meetup for all developers of LLDB. Meeting agendas are posted on discourse before the event. - Attendees are required to adhere to the LLVM Code of Conduct + Attendees must adhere to the LLVM Code of Conduct (https://llvm.org/docs/CodeOfConduct.html). For any Code of Conduct reports, - please contact the organizers, and also email conduct@llvm.org. + please contact the organizers and also email conduct@llvm.org. Agenda/Meeting Minutes: Link to minutes diff --git a/llvm/docs/GlobalISel/InstructionSelect.rst b/llvm/docs/GlobalISel/InstructionSelect.rst index 9798ae7..5513824 100644 --- a/llvm/docs/GlobalISel/InstructionSelect.rst +++ b/llvm/docs/GlobalISel/InstructionSelect.rst @@ -5,8 +5,22 @@ InstructionSelect ----------------- This pass transforms generic machine instructions into equivalent -target-specific instructions. It traverses the ``MachineFunction`` bottom-up, -selecting uses before definitions, enabling trivial dead code elimination. +target-specific instructions. + +The legacy instruction selector, SelectionDAG, iterated over each function's +basic block and constructed a dataflow graph. Every backend defines +tree patterns in the ``XXXInstrInfo.td``. The legacy selector started +at the bottom and replaced the SDNodes greedily. + +The GlobalISel's instruction selector traverses the ``MachineFunction`` +bottom-up, selecting uses before definitions, enabling trivial dead code +elimination. It does that by iterating over the basic blocks in post-order. +Each gMIR instruction is then replaced by a MIR instruction when a matching +pattern is found. So, when there is a 1:1 mapping between gMIR and MIR, where +is the benefit of the global scope? Even in the case of a 1:1 mapping, +GlobalISel includes a combiner that can match and fuse multiple gMIR +instructions. The scope of the combination is not limited to a basic block, +but can extend across the entire function. .. _api-instructionselector: 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. | ++--------------------+---------------------------------------------------------+ |