diff options
Diffstat (limited to 'llvm/docs')
32 files changed, 170 insertions, 162 deletions
diff --git a/llvm/docs/AMDGPUDwarfExtensionsForHeterogeneousDebugging.rst b/llvm/docs/AMDGPUDwarfExtensionsForHeterogeneousDebugging.rst index 95ae4f7..ba670d3 100644 --- a/llvm/docs/AMDGPUDwarfExtensionsForHeterogeneousDebugging.rst +++ b/llvm/docs/AMDGPUDwarfExtensionsForHeterogeneousDebugging.rst @@ -1187,7 +1187,7 @@ There are five kinds of location storage: operations. It would specify the debugger information entry and byte offset provided by the operations. -*Location descriptions are a language independent representation of addressing +*Location descriptions are a language-independent representation of addressing rules.* * *They can be the result of evaluating a debugger information entry attribute @@ -1523,8 +1523,8 @@ expression. states that relocation of references from one executable or shared object file to another must be performed by the consumer. But given that DR is defined as an offset in a ``.debug_info`` section this seems impossible. - If DR was defined as an implementation defined value, then the consumer - could choose to interpret the value in an implementation defined manner to + If DR was defined as an implementation-defined value, then the consumer + could choose to interpret the value in an implementation-defined manner to reference a debug information in another executable or shared object. In ELF the ``.debug_info`` section is in a non-\ ``PT_LOAD`` segment so @@ -4188,7 +4188,7 @@ The register rules are: conversion as the bit contents of the register is simply interpreted as a value of the address. - GDB has a per register hook that allows a target specific conversion on a + GDB has a per register hook that allows a target-specific conversion on a register by register basis. It defaults to truncation of bigger registers, and to actually reading bytes from the next register (or reads out of bounds for the last register) for smaller registers. There are no GDB tests that diff --git a/llvm/docs/AMDGPUUsage.rst b/llvm/docs/AMDGPUUsage.rst index c3d4833..5343d66 100644 --- a/llvm/docs/AMDGPUUsage.rst +++ b/llvm/docs/AMDGPUUsage.rst @@ -1890,7 +1890,7 @@ The AMDGPU backend supports the following calling conventions: AMDGPU MCExpr ------------- -As part of the AMDGPU MC layer, AMDGPU provides the following target specific +As part of the AMDGPU MC layer, AMDGPU provides the following target-specific ``MCExpr``\s. .. table:: AMDGPU MCExpr types: diff --git a/llvm/docs/CodeGenerator.rst b/llvm/docs/CodeGenerator.rst index 020eb09..8260b5c 100644 --- a/llvm/docs/CodeGenerator.rst +++ b/llvm/docs/CodeGenerator.rst @@ -323,7 +323,7 @@ provide one of these objects through the ``getJITInfo`` method. Machine code description classes ================================ -At the high-level, LLVM code is translated to a machine specific representation +At the high-level, LLVM code is translated to a machine-specific representation formed out of :raw-html:`<tt>` `MachineFunction`_ :raw-html:`</tt>`, :raw-html:`<tt>` `MachineBasicBlock`_ :raw-html:`</tt>`, and :raw-html:`<tt>` `MachineInstr`_ :raw-html:`</tt>` instances (defined in @@ -462,7 +462,7 @@ code: ret This approach is extremely general (if it can handle the X86 architecture, it -can handle anything!) and allows all of the target specific knowledge about the +can handle anything!) and allows all of the target-specific knowledge about the instruction stream to be isolated in the instruction selector. Note that physical registers should have a short lifetime for good code generation, and all physical registers are assumed dead on entry to and exit from basic blocks @@ -634,7 +634,7 @@ file (MCObjectStreamer). MCAsmStreamer is a straightforward implementation that prints out a directive for each method (e.g. ``EmitValue -> .byte``), but MCObjectStreamer implements a full assembler. -For target specific directives, the MCStreamer has a MCTargetStreamer instance. +For target-specific directives, the MCStreamer has a MCTargetStreamer instance. Each target that needs it defines a class that inherits from it and is a lot like MCStreamer itself: It has one method per directive and two classes that inherit from it, a target object streamer and a target asm streamer. The target diff --git a/llvm/docs/CommandGuide/llvm-bcanalyzer.rst b/llvm/docs/CommandGuide/llvm-bcanalyzer.rst index 8f15e03..1e0b581 100644 --- a/llvm/docs/CommandGuide/llvm-bcanalyzer.rst +++ b/llvm/docs/CommandGuide/llvm-bcanalyzer.rst @@ -14,7 +14,7 @@ DESCRIPTION The :program:`llvm-bcanalyzer` command is a small utility for analyzing bitcode files. The tool reads a bitcode file (such as generated with the :program:`llvm-as` tool) and produces a statistical report on the contents of -the bitcode file. The tool can also dump a low level but human readable +the bitcode file. The tool can also dump a low level but human-readable version of the bitcode file. This tool is probably not of much interest or utility except for those working directly with the bitcode file format. Most LLVM users can just ignore this tool. @@ -30,7 +30,7 @@ OPTIONS .. option:: --dump - Causes :program:`llvm-bcanalyzer` to dump the bitcode in a human readable + Causes :program:`llvm-bcanalyzer` to dump the bitcode in a human-readable format. This format is significantly different from LLVM assembly and provides details about the encoding of the bitcode file. diff --git a/llvm/docs/CommandGuide/llvm-debuginfo-analyzer.rst b/llvm/docs/CommandGuide/llvm-debuginfo-analyzer.rst index 1264f80..6a4e348 100644 --- a/llvm/docs/CommandGuide/llvm-debuginfo-analyzer.rst +++ b/llvm/docs/CommandGuide/llvm-debuginfo-analyzer.rst @@ -14,7 +14,7 @@ DESCRIPTION ----------- :program:`llvm-debuginfo-analyzer` parses debug and text sections in binary object files and prints their contents in a logical view, which -is a human readable representation that closely matches the structure +is a human-readable representation that closely matches the structure of the original user source code. Supported object file formats include ELF, Mach-O, WebAssembly, PDB and COFF. diff --git a/llvm/docs/CommandGuide/llvm-exegesis.rst b/llvm/docs/CommandGuide/llvm-exegesis.rst index 25e8969..5996026 100644 --- a/llvm/docs/CommandGuide/llvm-exegesis.rst +++ b/llvm/docs/CommandGuide/llvm-exegesis.rst @@ -106,7 +106,7 @@ properly. using the loop repetition mode. :program:`llvm-exegesis` needs to keep track of the current loop iteration within the loop repetition mode in a performant manner (i.e., no memory accesses), and uses a register to do this. This register - has an architecture specific default (e.g., `R8` on X86), but this might conflict + has an architecture-specific default (e.g., `R8` on X86), but this might conflict with some snippets. This annotation allows changing the register to prevent interference between the loop index register and the snippet. diff --git a/llvm/docs/CommandGuide/llvm-ifs.rst b/llvm/docs/CommandGuide/llvm-ifs.rst index 1fe81c2..e3582b3 100644 --- a/llvm/docs/CommandGuide/llvm-ifs.rst +++ b/llvm/docs/CommandGuide/llvm-ifs.rst @@ -11,7 +11,7 @@ SYNOPSIS DESCRIPTION ----------- -:program:`llvm-ifs` is a tool that jointly produces human readable text-based +:program:`llvm-ifs` is a tool that jointly produces human-readable text-based stubs (.ifs files) for shared objects and linkable shared object stubs (.so files) from either ELF shared objects or text-based stubs. The text-based stubs is useful for monitoring ABI changes of the shared object. The linkable diff --git a/llvm/docs/CommandGuide/llvm-ir2vec.rst b/llvm/docs/CommandGuide/llvm-ir2vec.rst index 2f00c9f..0c9fb6e 100644 --- a/llvm/docs/CommandGuide/llvm-ir2vec.rst +++ b/llvm/docs/CommandGuide/llvm-ir2vec.rst @@ -6,27 +6,27 @@ llvm-ir2vec - IR2Vec Embedding Generation Tool SYNOPSIS -------- -:program:`llvm-ir2vec` [*options*] *input-file* +:program:`llvm-ir2vec` [*subcommand*] [*options*] DESCRIPTION ----------- :program:`llvm-ir2vec` is a standalone command-line tool for IR2Vec. It generates IR2Vec embeddings for LLVM IR and supports triplet generation -for vocabulary training. It provides three main operation modes: +for vocabulary training. The tool provides three main subcommands: -1. **Triplet Mode**: Generates numeric triplets in train2id format for vocabulary +1. **triplets**: Generates numeric triplets in train2id format for vocabulary training from LLVM IR. -2. **Entity Mode**: Generates entity mapping files (entity2id.txt) for vocabulary +2. **entities**: Generates entity mapping files (entity2id.txt) for vocabulary training. -3. **Embedding Mode**: Generates IR2Vec embeddings using a trained vocabulary +3. **embeddings**: Generates IR2Vec embeddings using a trained vocabulary at different granularity levels (instruction, basic block, or function). The tool is designed to facilitate machine learning applications that work with LLVM IR by converting the IR into numerical representations that can be used by -ML models. The triplet mode generates numeric IDs directly instead of string +ML models. The `triplets` subcommand generates numeric IDs directly instead of string triplets, streamlining the training data preparation workflow. .. note:: @@ -53,111 +53,115 @@ for details). See `llvm/utils/mlgo-utils/IR2Vec/generateTriplets.py` for more details on how these two modes are used to generate the triplets and entity mappings. -Triplet Generation Mode -~~~~~~~~~~~~~~~~~~~~~~~ +Triplet Generation +~~~~~~~~~~~~~~~~~~ -In triplet mode, :program:`llvm-ir2vec` analyzes LLVM IR and extracts numeric -triplets consisting of opcode IDs, type IDs, and operand IDs. These triplets -are generated in the standard format used for knowledge graph embedding training. -The tool outputs numeric IDs directly using the ir2vec::Vocabulary mapping +With the `triplets` subcommand, :program:`llvm-ir2vec` analyzes LLVM IR and extracts +numeric triplets consisting of opcode IDs, type IDs, and operand IDs. These triplets +are generated in the standard format used for knowledge graph embedding training. +The tool outputs numeric IDs directly using the ir2vec::Vocabulary mapping infrastructure, eliminating the need for string-to-ID preprocessing. Usage: .. code-block:: bash - llvm-ir2vec --mode=triplets input.bc -o triplets_train2id.txt + llvm-ir2vec triplets input.bc -o triplets_train2id.txt -Entity Mapping Generation Mode -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Entity Mapping Generation +~~~~~~~~~~~~~~~~~~~~~~~~~ -In entity mode, :program:`llvm-ir2vec` generates the entity mappings supported by -IR2Vec in the standard format used for knowledge graph embedding training. This -mode outputs all supported entities (opcodes, types, and operands) with their -corresponding numeric IDs, and is not specific for an LLVM IR file. +With the `entities` subcommand, :program:`llvm-ir2vec` generates the entity mappings +supported by IR2Vec in the standard format used for knowledge graph embedding +training. This subcommand outputs all supported entities (opcodes, types, and +operands) with their corresponding numeric IDs, and is not specific for an +LLVM IR file. Usage: .. code-block:: bash - llvm-ir2vec --mode=entities -o entity2id.txt + llvm-ir2vec entities -o entity2id.txt -Embedding Generation Mode -~~~~~~~~~~~~~~~~~~~~~~~~~~ +Embedding Generation +~~~~~~~~~~~~~~~~~~~~ -In embedding mode, :program:`llvm-ir2vec` uses a pre-trained vocabulary to +With the `embeddings` subcommand, :program:`llvm-ir2vec` uses a pre-trained vocabulary to generate numerical embeddings for LLVM IR at different levels of granularity. Example Usage: .. code-block:: bash - llvm-ir2vec --mode=embeddings --ir2vec-vocab-path=vocab.json --level=func input.bc -o embeddings.txt + llvm-ir2vec embeddings --ir2vec-vocab-path=vocab.json --level=func input.bc -o embeddings.txt OPTIONS ------- -.. option:: --mode=<mode> +Global options: + +.. option:: -o <filename> + + Specify the output filename. Use ``-`` to write to standard output (default). + +.. option:: --help + + Print a summary of command line options. - Specify the operation mode. Valid values are: +Subcommand-specific options: - * ``triplets`` - Generate triplets for vocabulary training - * ``entities`` - Generate entity mappings for vocabulary training - * ``embeddings`` - Generate embeddings using trained vocabulary (default) +**embeddings** subcommand: + +.. option:: <input-file> + + The input LLVM IR or bitcode file to process. This positional argument is + required for the `embeddings` subcommand. .. option:: --level=<level> - Specify the embedding generation level. Valid values are: + Specify the embedding generation level. Valid values are: - * ``inst`` - Generate instruction-level embeddings - * ``bb`` - Generate basic block-level embeddings - * ``func`` - Generate function-level embeddings (default) + * ``inst`` - Generate instruction-level embeddings + * ``bb`` - Generate basic block-level embeddings + * ``func`` - Generate function-level embeddings (default) .. option:: --function=<name> - Process only the specified function instead of all functions in the module. + Process only the specified function instead of all functions in the module. .. option:: --ir2vec-vocab-path=<path> - Specify the path to the vocabulary file (required for embedding mode). - The vocabulary file should be in JSON format and contain the trained - vocabulary for embedding generation. See `llvm/lib/Analysis/models` - for pre-trained vocabulary files. + Specify the path to the vocabulary file (required for embedding generation). + The vocabulary file should be in JSON format and contain the trained + vocabulary for embedding generation. See `llvm/lib/Analysis/models` + for pre-trained vocabulary files. .. option:: --ir2vec-opc-weight=<weight> - Specify the weight for opcode embeddings (default: 1.0). This controls - the relative importance of instruction opcodes in the final embedding. + Specify the weight for opcode embeddings (default: 1.0). This controls + the relative importance of instruction opcodes in the final embedding. .. option:: --ir2vec-type-weight=<weight> - Specify the weight for type embeddings (default: 0.5). This controls - the relative importance of type information in the final embedding. + Specify the weight for type embeddings (default: 0.5). This controls + the relative importance of type information in the final embedding. .. option:: --ir2vec-arg-weight=<weight> - Specify the weight for argument embeddings (default: 0.2). This controls - the relative importance of operand information in the final embedding. + Specify the weight for argument embeddings (default: 0.2). This controls + the relative importance of operand information in the final embedding. -.. option:: -o <filename> - Specify the output filename. Use ``-`` to write to standard output (default). +**triplets** subcommand: -.. option:: --help - - Print a summary of command line options. - -.. note:: +.. option:: <input-file> - ``--level``, ``--function``, ``--ir2vec-vocab-path``, ``--ir2vec-opc-weight``, - ``--ir2vec-type-weight``, and ``--ir2vec-arg-weight`` are only used in embedding - mode. These options are ignored in triplet and entity modes. + The input LLVM IR or bitcode file to process. This positional argument is + required for the `triplets` subcommand. -INPUT FILE FORMAT ------------------ +**entities** subcommand: -:program:`llvm-ir2vec` accepts LLVM bitcode files (``.bc``) and LLVM IR files -(``.ll``) as input. The input file should contain valid LLVM IR. + No subcommand-specific options. OUTPUT FORMAT ------------- diff --git a/llvm/docs/CommandGuide/llvm-locstats.rst b/llvm/docs/CommandGuide/llvm-locstats.rst index 3186566..7f436c1 100644 --- a/llvm/docs/CommandGuide/llvm-locstats.rst +++ b/llvm/docs/CommandGuide/llvm-locstats.rst @@ -13,7 +13,7 @@ DESCRIPTION :program:`llvm-locstats` works like a wrapper around :program:`llvm-dwarfdump`. It parses :program:`llvm-dwarfdump` statistics regarding debug location by -pretty printing it in a more human readable way. +pretty printing it in a more human-readable way. The line 0% shows the number and the percentage of DIEs with no location information, but the line 100% shows the information for DIEs where there is diff --git a/llvm/docs/CommandGuide/llvm-mca.rst b/llvm/docs/CommandGuide/llvm-mca.rst index bea1931..1daae5d 100644 --- a/llvm/docs/CommandGuide/llvm-mca.rst +++ b/llvm/docs/CommandGuide/llvm-mca.rst @@ -241,7 +241,7 @@ option specifies "``-``", then the output will also be sent to standard output. .. option:: -disable-cb Force usage of the generic CustomBehaviour and InstrPostProcess classes rather - than using the target specific implementation. The generic classes never + than using the target-specific implementation. The generic classes never detect any custom hazards or make any post processing modifications to instructions. @@ -1125,9 +1125,9 @@ CustomBehaviour class can be used in these cases to enforce proper instruction modeling (often by customizing data dependencies and detecting hazards that :program:`llvm-mca` has no way of knowing about). -:program:`llvm-mca` comes with one generic and multiple target specific +:program:`llvm-mca` comes with one generic and multiple target-specific CustomBehaviour classes. The generic class will be used if the ``-disable-cb`` -flag is used or if a target specific CustomBehaviour class doesn't exist for +flag is used or if a target-specific CustomBehaviour class doesn't exist for that target. (The generic class does nothing.) Currently, the CustomBehaviour class is only a part of the in-order pipeline, but there are plans to add it to the out-of-order pipeline in the future. @@ -1141,7 +1141,7 @@ if you don't know the exact number and a value of 0 represents no stall). If you'd like to add a CustomBehaviour class for a target that doesn't already have one, refer to an existing implementation to see how to set it -up. The classes are implemented within the target specific backend (for +up. The classes are implemented within the target-specific backend (for example `/llvm/lib/Target/AMDGPU/MCA/`) so that they can access backend symbols. Instrument Manager @@ -1177,12 +1177,12 @@ classes (MCSubtargetInfo, MCInstrInfo, etc.), please add it to the AND requires unexposed backend symbols or functionality, you can define it in the `/lib/Target/<TargetName>/MCA/` directory. -To enable this target specific View, you will have to use this target's +To enable this target-specific View, you will have to use this target's CustomBehaviour class to override the `CustomBehaviour::getViews()` methods. There are 3 variations of these methods based on where you want your View to appear in the output: `getStartViews()`, `getPostInstrInfoViews()`, and `getEndViews()`. These methods returns a vector of Views so you will want to -return a vector containing all of the target specific Views for the target in +return a vector containing all of the target-specific Views for the target in question. Because these target specific (and backend dependent) Views require the diff --git a/llvm/docs/CommandGuide/llvm-profdata.rst b/llvm/docs/CommandGuide/llvm-profdata.rst index b2c0457..0b1cd02 100644 --- a/llvm/docs/CommandGuide/llvm-profdata.rst +++ b/llvm/docs/CommandGuide/llvm-profdata.rst @@ -338,7 +338,7 @@ OPTIONS Instruct the profile dumper to show profile counts in the text format of the instrumentation-based profile data representation. By default, the profile - information is dumped in a more human readable form (also in text) with + information is dumped in a more human-readable form (also in text) with annotations. .. option:: --topn=<n> diff --git a/llvm/docs/CommandGuide/llvm-symbolizer.rst b/llvm/docs/CommandGuide/llvm-symbolizer.rst index 2da1b24..fb86a69 100644 --- a/llvm/docs/CommandGuide/llvm-symbolizer.rst +++ b/llvm/docs/CommandGuide/llvm-symbolizer.rst @@ -371,7 +371,7 @@ OPTIONS * Prints an address's debug-data discriminator when it is non-zero. One way to produce discriminators is to compile with clang's -fdebug-info-for-profiling. - ``JSON`` style provides a machine readable output in JSON. If addresses are + ``JSON`` style provides a machine-readable output in JSON. If addresses are supplied via stdin, the output JSON will be a series of individual objects. Otherwise, all results will be contained in a single array. @@ -444,7 +444,7 @@ OPTIONS .. option:: --pretty-print, -p - Print human readable output. If :option:`--inlining` is specified, the + Print human-readable output. If :option:`--inlining` is specified, the enclosing scope is prefixed by (inlined by). For JSON output, the option will cause JSON to be indented and split over new lines. Otherwise, the JSON output will be printed in a compact form. diff --git a/llvm/docs/CommandGuide/opt.rst b/llvm/docs/CommandGuide/opt.rst index f067f62..da93b8e 100644 --- a/llvm/docs/CommandGuide/opt.rst +++ b/llvm/docs/CommandGuide/opt.rst @@ -46,12 +46,12 @@ OPTIONS Write output in LLVM intermediate language (instead of bitcode). -.. option:: -{passname} +.. option:: -passes=<string> - :program:`opt` provides the ability to run any of LLVM's optimization or - analysis passes in any order. The :option:`-help` option lists all the passes - available. The order in which the options occur on the command line are the - order in which they are executed (within pass constraints). + A textual (comma-separated) description of the pass pipeline, + e.g., ``-passes="sroa,instcombine"``. See + `invoking opt <../NewPassManager.html#invoking-opt>`_ for more details on the + pass pipeline syntax. .. option:: -strip-debug diff --git a/llvm/docs/DirectX/DXContainer.rst b/llvm/docs/DirectX/DXContainer.rst index 4ace8a1..17452d9 100644 --- a/llvm/docs/DirectX/DXContainer.rst +++ b/llvm/docs/DirectX/DXContainer.rst @@ -280,7 +280,7 @@ elements are: This represents ``f5`` in the source. The LLVM ``obj2yaml`` tool can parse this data out of the PSV and present it in -human readable YAML. For the example above it produces the output: +human-readable YAML. For the example above it produces the output: .. code-block:: YAML diff --git a/llvm/docs/Frontend/PerformanceTips.rst b/llvm/docs/Frontend/PerformanceTips.rst index 4baf127..b81df70 100644 --- a/llvm/docs/Frontend/PerformanceTips.rst +++ b/llvm/docs/Frontend/PerformanceTips.rst @@ -35,7 +35,7 @@ The Basics ^^^^^^^^^^^ #. Make sure that your Modules contain both a data layout specification and - target triple. Without these pieces, non of the target specific optimization + target triple. Without these pieces, non of the target-specific optimization will be enabled. This can have a major effect on the generated code quality. #. For each function or global emitted, use the most private linkage type diff --git a/llvm/docs/FuzzingLLVM.rst b/llvm/docs/FuzzingLLVM.rst index 6b32eea..a0355d7 100644 --- a/llvm/docs/FuzzingLLVM.rst +++ b/llvm/docs/FuzzingLLVM.rst @@ -128,7 +128,7 @@ llvm-mc-assemble-fuzzer ----------------------- A |generic fuzzer| that fuzzes the MC layer's assemblers by treating inputs as -target specific assembly. +target-specific assembly. Note that this fuzzer has an unusual command line interface which is not fully compatible with all of libFuzzer's features. Fuzzer arguments must be passed diff --git a/llvm/docs/GettingStarted.rst b/llvm/docs/GettingStarted.rst index e4dbb64b..8d0adf3 100644 --- a/llvm/docs/GettingStarted.rst +++ b/llvm/docs/GettingStarted.rst @@ -919,11 +919,11 @@ the `Command Guide <CommandGuide/index.html>`_. ``llvm-as`` - The assembler transforms the human readable LLVM assembly to LLVM bitcode. + The assembler transforms the human-readable LLVM assembly to LLVM bitcode. ``llvm-dis`` - The disassembler transforms the LLVM bitcode to human readable LLVM assembly. + The disassembler transforms the LLVM bitcode to human-readable LLVM assembly. ``llvm-link`` diff --git a/llvm/docs/GlobalISel/GMIR.rst b/llvm/docs/GlobalISel/GMIR.rst index 633dfb8..be7e677 100644 --- a/llvm/docs/GlobalISel/GMIR.rst +++ b/llvm/docs/GlobalISel/GMIR.rst @@ -26,7 +26,7 @@ Generic Machine Instructions Reference. Whereas MIR deals largely in Target Instructions and only has a small set of -target independent opcodes such as ``COPY``, ``PHI``, and ``REG_SEQUENCE``, +target-independent opcodes such as ``COPY``, ``PHI``, and ``REG_SEQUENCE``, gMIR defines a rich collection of ``Generic Opcodes`` which are target independent and describe operations which are typically supported by targets. One example is ``G_ADD`` which is the generic opcode for an integer addition. diff --git a/llvm/docs/GlobalISel/GenericOpcode.rst b/llvm/docs/GlobalISel/GenericOpcode.rst index 4816094..eefd76d 100644 --- a/llvm/docs/GlobalISel/GenericOpcode.rst +++ b/llvm/docs/GlobalISel/GenericOpcode.rst @@ -1105,7 +1105,7 @@ G_TRAP, G_DEBUGTRAP, G_UBSANTRAP ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Represents :ref:`llvm.trap <llvm.trap>`, :ref:`llvm.debugtrap <llvm.debugtrap>` -and :ref:`llvm.ubsantrap <llvm.ubsantrap>` that generate a target dependent +and :ref:`llvm.ubsantrap <llvm.ubsantrap>` that generate a target-dependent trap instructions. .. code-block:: none diff --git a/llvm/docs/GlobalISel/Pipeline.rst b/llvm/docs/GlobalISel/Pipeline.rst index 01bd4df..b9085e8 100644 --- a/llvm/docs/GlobalISel/Pipeline.rst +++ b/llvm/docs/GlobalISel/Pipeline.rst @@ -80,7 +80,7 @@ Combiner alternatives but Combiners can also focus on code size or other metrics. Additional passes such as these can be inserted to support higher optimization -levels or target specific needs. A likely pipeline is: +levels or target-specific needs. A likely pipeline is: .. image:: pipeline-overview-with-combiners.png diff --git a/llvm/docs/HowToUpdateDebugInfo.rst b/llvm/docs/HowToUpdateDebugInfo.rst index 915e289..ca420e7 100644 --- a/llvm/docs/HowToUpdateDebugInfo.rst +++ b/llvm/docs/HowToUpdateDebugInfo.rst @@ -499,7 +499,7 @@ a JSON file as follows: $ opt -verify-debuginfo-preserve -verify-di-preserve-export=sample.json -pass-to-test sample.ll and then use the ``llvm/utils/llvm-original-di-preservation.py`` script -to generate an HTML page with the issues reported in a more human readable form +to generate an HTML page with the issues reported in a more human-readable form as follows: .. code-block:: bash diff --git a/llvm/docs/JITLink.rst b/llvm/docs/JITLink.rst index 8902712..370281b 100644 --- a/llvm/docs/JITLink.rst +++ b/llvm/docs/JITLink.rst @@ -1072,7 +1072,7 @@ Major outstanding projects include: * Refactor architecture support to maximize sharing across formats. - All formats should be able to share the bulk of the architecture specific + All formats should be able to share the bulk of the architecture-specific code (especially relocations) for each supported architecture. * Refactor ELF link graph construction. diff --git a/llvm/docs/LangRef.rst b/llvm/docs/LangRef.rst index 28746bf..2a8f0af 100644 --- a/llvm/docs/LangRef.rst +++ b/llvm/docs/LangRef.rst @@ -26,7 +26,7 @@ readable assembly language representation. This allows LLVM to provide a powerful intermediate representation for efficient compiler transformations and analysis, while providing a natural means to debug and visualize the transformations. The three different forms of LLVM are -all equivalent. This document describes the human readable +all equivalent. This document describes the human-readable representation and notation. The LLVM representation aims to be light-weight and low-level while @@ -21289,7 +21289,7 @@ Semantics: On some architectures the address of the code to be executed needs to be different than the address where the trampoline is actually stored. This intrinsic returns the executable address corresponding to ``tramp`` -after performing the required machine specific adjustments. The pointer +after performing the required machine-specific adjustments. The pointer returned can then be :ref:`bitcast and executed <int_trampoline>`. @@ -29382,7 +29382,7 @@ None. Semantics: """""""""" -This intrinsic is lowered to the target dependent trap instruction. If +This intrinsic is lowered to the target-dependent trap instruction. If the target does not have a trap instruction, this intrinsic will be lowered to a call of the ``abort()`` function. diff --git a/llvm/docs/Lexicon.rst b/llvm/docs/Lexicon.rst index 1d4894f..05315a8 100644 --- a/llvm/docs/Lexicon.rst +++ b/llvm/docs/Lexicon.rst @@ -192,7 +192,7 @@ L **LSDA** Language Specific Data Area. C++ "zero cost" unwinding is built on top a generic unwinding mechanism. As the unwinder walks each frame, it calls - a "personality" function to do language specific analysis. Each function's + a "personality" function to do language-specific analysis. Each function's FDE points to an optional LSDA which is passed to the personality function. For C++, the LSDA contain info about the type and location of catch statements in that function. diff --git a/llvm/docs/MIRLangRef.rst b/llvm/docs/MIRLangRef.rst index b4b59db..a505c1e 100644 --- a/llvm/docs/MIRLangRef.rst +++ b/llvm/docs/MIRLangRef.rst @@ -12,7 +12,7 @@ Introduction ============ This document is a reference manual for the Machine IR (MIR) serialization -format. MIR is a human readable serialization format that is used to represent +format. MIR is a human-readable serialization format that is used to represent LLVM's :ref:`machine specific intermediate representation <machine code representation>`. @@ -221,7 +221,7 @@ Machine Instructions Format Reference ===================================== The machine basic blocks and their instructions are represented using a custom, -human readable serialization language. This language is used in the +human-readable serialization language. This language is used in the `YAML block literal string`_ that corresponds to the machine function's body. A source string that uses this language contains a list of machine basic diff --git a/llvm/docs/PDB/CodeViewTypes.rst b/llvm/docs/PDB/CodeViewTypes.rst index 7a93ebe..996d8f9 100644 --- a/llvm/docs/PDB/CodeViewTypes.rst +++ b/llvm/docs/PDB/CodeViewTypes.rst @@ -123,7 +123,7 @@ The ``Size`` field of the Attributes bitmask is a 1-byte value indicating the pointer size. For example, a `void*` would have a size of either 4 or 8 depending on the target architecture. On the other hand, if ``Mode`` indicates that this is a pointer to member function or pointer to data member, then the size can be any -implementation defined number. +implementation-defined number. The ``Member Ptr Info`` field of the ``LF_POINTER`` record is only present if the attributes indicate that this is a pointer to member. diff --git a/llvm/docs/ProgrammersManual.rst b/llvm/docs/ProgrammersManual.rst index 9ddeebd..1e1e5b3 100644 --- a/llvm/docs/ProgrammersManual.rst +++ b/llvm/docs/ProgrammersManual.rst @@ -486,7 +486,7 @@ Success values are very cheap to construct and return - they have minimal impact on program performance. Failure values are constructed using ``make_error<T>``, where ``T`` is any class -that inherits from the ErrorInfo utility, E.g.: +that inherits from the ``ErrorInfo`` utility, E.g.: .. code-block:: c++ @@ -1351,7 +1351,7 @@ The ``llvm/Support/DebugCounter.h`` (`doxygen provides a class named ``DebugCounter`` that can be used to create command-line counter options that control execution of parts of your code. -Define your DebugCounter like this: +Define your ``DebugCounter`` like this: .. code-block:: c++ @@ -1677,7 +1677,7 @@ page and one extra indirection when accessing elements with their positional index. In order to minimise the memory footprint of this container, it's important to -balance the PageSize so that it's not too small (otherwise the overhead of the +balance the ``PageSize`` so that it's not too small (otherwise the overhead of the pointer per page might become too high) and not too big (otherwise the memory is wasted if the page is not fully used). @@ -2203,17 +2203,17 @@ inserting elements into both a set-like container and the sequential container, using the set-like container for uniquing and the sequential container for iteration. -The difference between SetVector and other sets is that the order of iteration -is guaranteed to match the order of insertion into the SetVector. This property +The difference between ``SetVector`` and other sets is that the order of iteration +is guaranteed to match the order of insertion into the ``SetVector``. This property is really important for things like sets of pointers. Because pointer values are non-deterministic (e.g. vary across runs of the program on different machines), iterating over the pointers in the set will not be in a well-defined order. -The drawback of SetVector is that it requires twice as much space as a normal +The drawback of ``SetVector`` is that it requires twice as much space as a normal set and has the sum of constant factors from the set-like container and the sequential container that it uses. Use it **only** if you need to iterate over -the elements in a deterministic order. SetVector is also expensive to delete +the elements in a deterministic order. ``SetVector`` is also expensive to delete elements out of (linear time), unless you use its "pop_back" method, which is faster. @@ -2369,22 +2369,22 @@ llvm/IR/ValueMap.h ValueMap is a wrapper around a :ref:`DenseMap <dss_densemap>` mapping ``Value*``\ s (or subclasses) to another type. When a Value is deleted or -RAUW'ed, ValueMap will update itself so the new version of the key is mapped to +RAUW'ed, ``ValueMap`` will update itself so the new version of the key is mapped to the same value, just as if the key were a WeakVH. You can configure exactly how this happens, and what else happens on these two events, by passing a ``Config`` -parameter to the ValueMap template. +parameter to the ``ValueMap`` template. .. _dss_intervalmap: llvm/ADT/IntervalMap.h ^^^^^^^^^^^^^^^^^^^^^^ -IntervalMap is a compact map for small keys and values. It maps key intervals +``IntervalMap`` is a compact map for small keys and values. It maps key intervals instead of single keys, and it will automatically coalesce adjacent intervals. When the map only contains a few intervals, they are stored in the map object itself to avoid allocations. -The IntervalMap iterators are quite big, so they should not be passed around as +The ``IntervalMap`` iterators are quite big, so they should not be passed around as STL iterators. The heavyweight iterators allow a smaller data structure. .. _dss_intervaltree: @@ -2396,7 +2396,7 @@ llvm/ADT/IntervalTree.h allows finding all intervals that overlap with any given point. At this time, it does not support any deletion or rebalancing operations. -The IntervalTree is designed to be set up once, and then queried without any +The ``IntervalTree`` is designed to be set up once, and then queried without any further additions. .. _dss_map: @@ -2435,10 +2435,10 @@ necessary to remove elements, it's best to remove them in bulk using llvm/ADT/IntEqClasses.h ^^^^^^^^^^^^^^^^^^^^^^^ -IntEqClasses provides a compact representation of equivalence classes of small +``IntEqClasses`` provides a compact representation of equivalence classes of small integers. Initially, each integer in the range 0..n-1 has its own equivalence class. Classes can be joined by passing two class representatives to the -join(a, b) method. Two integers are in the same class when findLeader() returns +``join(a, b)`` method. Two integers are in the same class when ``findLeader()`` returns the same representative. Once all equivalence classes are formed, the map can be compressed so each @@ -2451,11 +2451,11 @@ it can be edited again. llvm/ADT/ImmutableMap.h ^^^^^^^^^^^^^^^^^^^^^^^ -ImmutableMap is an immutable (functional) map implementation based on an AVL +``ImmutableMap`` is an immutable (functional) map implementation based on an AVL tree. Adding or removing elements is done through a Factory object and results -in the creation of a new ImmutableMap object. If an ImmutableMap already exists +in the creation of a new ``ImmutableMap`` object. If an ``ImmutableMap`` already exists with the given key set, then the existing one is returned; equality is compared -with a FoldingSetNodeID. The time and space complexity of add or remove +with a ``FoldingSetNodeID``. The time and space complexity of add or remove operations is logarithmic in the size of the original map. .. _dss_othermap: @@ -2490,11 +2490,11 @@ somehow. In any case, please don't use it. BitVector ^^^^^^^^^ -The BitVector container provides a dynamic size set of bits for manipulation. +The ``BitVector`` container provides a dynamic size set of bits for manipulation. It supports individual bit setting/testing, as well as set operations. The set operations take time O(size of bitvector), but operations are performed one word -at a time, instead of one bit at a time. This makes the BitVector very fast for -set operations compared to other containers. Use the BitVector when you expect +at a time, instead of one bit at a time. This makes the ``BitVector`` very fast for +set operations compared to other containers. Use the ``BitVector`` when you expect the number of set bits to be high (i.e. a dense set). .. _dss_smallbitvector: @@ -2516,29 +2516,29 @@ its operator[] does not provide an assignable lvalue. SparseBitVector ^^^^^^^^^^^^^^^ -The SparseBitVector container is much like BitVector, with one major difference: -Only the bits that are set, are stored. This makes the SparseBitVector much -more space efficient than BitVector when the set is sparse, as well as making +The ``SparseBitVector`` container is much like ``BitVector``, with one major difference: +Only the bits that are set, are stored. This makes the ``SparseBitVector`` much +more space efficient than ``BitVector`` when the set is sparse, as well as making set operations O(number of set bits) instead of O(size of universe). The -downside to the SparseBitVector is that setting and testing of random bits is -O(N), and on large SparseBitVectors, this can be slower than BitVector. In our +downside to the ``SparseBitVector`` is that setting and testing of random bits is +O(N), and on large ``SparseBitVectors``, this can be slower than ``BitVector``. In our implementation, setting or testing bits in sorted order (either forwards or reverse) is O(1) worst case. Testing and setting bits within 128 bits (depends on size) of the current bit is also O(1). As a general statement, -testing/setting bits in a SparseBitVector is O(distance away from last set bit). +testing/setting bits in a ``SparseBitVector`` is O(distance away from last set bit). .. _dss_coalescingbitvector: CoalescingBitVector ^^^^^^^^^^^^^^^^^^^ -The CoalescingBitVector container is similar in principle to a SparseBitVector, +The ``CoalescingBitVector`` container is similar in principle to a ``SparseBitVector``, but is optimized to represent large contiguous ranges of set bits compactly. It does this by coalescing contiguous ranges of set bits into intervals. Searching -for a bit in a CoalescingBitVector is O(log(gaps between contiguous ranges)). +for a bit in a ``CoalescingBitVector`` is O(log(gaps between contiguous ranges)). -CoalescingBitVector is a better choice than BitVector when gaps between ranges -of set bits are large. It's a better choice than SparseBitVector when find() +``CoalescingBitVector`` is a better choice than ``BitVector`` when gaps between ranges +of set bits are large. It's a better choice than ``SparseBitVector`` when find() operations must have fast, predictable performance. However, it's not a good choice for representing sets which have lots of very short ranges. E.g. the set `{2*x : x \in [0, n)}` would be a pathological input. @@ -2773,7 +2773,7 @@ Turning an iterator into a class pointer (and vice-versa) Sometimes, it'll be useful to grab a reference (or pointer) to a class instance when all you've got at hand is an iterator. Well, extracting a reference or a -pointer from an iterator is very straight-forward. Assuming that ``i`` is a +pointer from an iterator is very straightforward. Assuming that ``i`` is a ``BasicBlock::iterator`` and ``j`` is a ``BasicBlock::const_iterator``: .. code-block:: c++ @@ -2805,7 +2805,7 @@ Say that you're writing a FunctionPass and would like to count all the locations in the entire module (that is, across every ``Function``) where a certain function (i.e., some ``Function *``) is already in scope. As you'll learn later, you may want to use an ``InstVisitor`` to accomplish this in a much more -straight-forward manner, but this example will allow us to explore how you'd do +straightforward manner, but this example will allow us to explore how you'd do it if you didn't have ``InstVisitor`` around. In pseudo-code, this is what we want to do: @@ -2932,7 +2932,7 @@ Creating and inserting new ``Instruction``\ s *Instantiating Instructions* -Creation of ``Instruction``\ s is straight-forward: simply call the constructor +Creation of ``Instruction``\ s is straightforward: simply call the constructor for the kind of instruction to instantiate and provide the necessary parameters. For example, an ``AllocaInst`` only *requires* a (const-ptr-to) ``Type``. Thus: @@ -3050,7 +3050,7 @@ Deleting Instructions ^^^^^^^^^^^^^^^^^^^^^ Deleting an instruction from an existing sequence of instructions that form a -BasicBlock_ is very straight-forward: just call the instruction's +``BasicBlock`` is very straightforward: just call the instruction's ``eraseFromParent()`` method. For example: .. code-block:: c++ @@ -3850,16 +3850,16 @@ Important Subclasses of Constant any width. * ``const APInt& getValue() const``: Returns the underlying - value of this constant, an APInt value. + value of this constant, an ``APInt`` value. * ``int64_t getSExtValue() const``: Converts the underlying APInt value to an - int64_t via sign extension. If the value (not the bit width) of the APInt - is too large to fit in an int64_t, an assertion will result. For this + ``int64_t`` via sign extension. If the value (not the bit width) of the APInt + is too large to fit in an ``int64_t``, an assertion will result. For this reason, use of this method is discouraged. - * ``uint64_t getZExtValue() const``: Converts the underlying APInt value - to a uint64_t via zero extension. IF the value (not the bit width) of the - APInt is too large to fit in a uint64_t, an assertion will result. For this + * ``uint64_t getZExtValue() const``: Converts the underlying ``APInt`` value + to a ``uint64_t`` via zero extension. If the value (not the bit width) of the + APInt is too large to fit in a ``uint64_t``, an assertion will result. For this reason, use of this method is discouraged. * ``static ConstantInt* get(const APInt& Val)``: Returns the ConstantInt @@ -4148,7 +4148,7 @@ Important Public Members of the ``BasicBlock`` class new block, and a :ref:`Function <c_Function>` to insert it into. If the ``Parent`` parameter is specified, the new ``BasicBlock`` is automatically inserted at the end of the specified :ref:`Function <c_Function>`, if not - specified, the BasicBlock must be manually inserted into the :ref:`Function + specified, the ``BasicBlock`` must be manually inserted into the :ref:`Function <c_Function>`. * | ``BasicBlock::iterator`` - Typedef for instruction list iterator diff --git a/llvm/docs/SPIRVUsage.rst b/llvm/docs/SPIRVUsage.rst index 1f563fb..fdefc53 100644 --- a/llvm/docs/SPIRVUsage.rst +++ b/llvm/docs/SPIRVUsage.rst @@ -131,9 +131,23 @@ Extensions The SPIR-V backend supports a variety of `extensions <https://github.com/KhronosGroup/SPIRV-Registry/tree/main/extensions>`_ that enable or enhance features beyond the core SPIR-V specification. -These extensions can be enabled using the ``-spirv-extensions`` option -followed by the name of the extension(s) you wish to enable. Below is a -list of supported SPIR-V extensions, sorted alphabetically by their extension names: +The enabled extensions can be controlled using the ``-spirv-ext`` option followed by a list of +extensions to enable or disable, each prefixed with ``+`` or ``-``, respectively. + +To enable multiple extensions, list them separated by comma. For example, to enable support for atomic operations on floating-point numbers and arbitrary precision integers, use: + +``-spirv-ext=+SPV_EXT_shader_atomic_float_add,+SPV_INTEL_arbitrary_precision_integers`` + +To enable all extensions, use the following option: +``-spirv-ext=all`` + +To enable all KHR extensions, use the following option: +``-spirv-ext=khr`` + +To enable all extensions except specified, specify ``all`` followed by a list of disallowed extensions. For example: +``-spirv-ext=all,-SPV_INTEL_arbitrary_precision_integers`` + +Below is a list of supported SPIR-V extensions, sorted alphabetically by their extension names: .. list-table:: Supported SPIR-V Extensions :widths: 50 150 @@ -220,16 +234,6 @@ list of supported SPIR-V extensions, sorted alphabetically by their extension na * - ``SPV_KHR_float_controls2`` - Adds ability to specify the floating-point environment in shaders. It can be used on whole modules and individual instructions. -To enable multiple extensions, list them separated by comma. For example, to enable support for atomic operations on floating-point numbers and arbitrary precision integers, use: - -``-spirv-ext=+SPV_EXT_shader_atomic_float_add,+SPV_INTEL_arbitrary_precision_integers`` - -To enable all extensions, use the following option: -``-spirv-ext=all`` - -To enable all extensions except specified, specify ``all`` followed by a list of disallowed extensions. For example: -``-spirv-ext=all,-SPV_INTEL_arbitrary_precision_integers`` - SPIR-V representation in LLVM IR ================================ diff --git a/llvm/docs/SymbolizerMarkupFormat.rst b/llvm/docs/SymbolizerMarkupFormat.rst index d5b17d7..75ead44 100644 --- a/llvm/docs/SymbolizerMarkupFormat.rst +++ b/llvm/docs/SymbolizerMarkupFormat.rst @@ -315,7 +315,7 @@ Trigger elements ================ These elements cause an external action and will be presented to the user in a -human readable form. Generally they trigger an external action to occur that +human-readable form. Generally they trigger an external action to occur that results in a linkable page. The link or some other informative information about the external action can then be presented to the user. diff --git a/llvm/docs/WritingAnLLVMBackend.rst b/llvm/docs/WritingAnLLVMBackend.rst index 3c5d594..cab6471 100644 --- a/llvm/docs/WritingAnLLVMBackend.rst +++ b/llvm/docs/WritingAnLLVMBackend.rst @@ -150,7 +150,7 @@ any other naming scheme will confuse ``llvm-config`` and produce a lot of To make your target actually do something, you need to implement a subclass of ``TargetMachine``. This implementation should typically be in the file ``lib/Target/DummyTargetMachine.cpp``, but any file in the ``lib/Target`` -directory will be built and should work. To use LLVM's target independent code +directory will be built and should work. To use LLVM's target-independent code generator, you should do what all current machine backends do: create a subclass of ``CodeGenTargetMachineImpl``. (To create a target from scratch, create a subclass of ``TargetMachine``.) @@ -1671,7 +1671,7 @@ For example in ``SparcTargetAsmInfo.cpp``: } The X86 assembly printer implementation (``X86TargetAsmInfo``) is an example -where the target specific ``TargetAsmInfo`` class uses an overridden methods: +where the target-specific ``TargetAsmInfo`` class uses an overridden methods: ``ExpandInlineAsm``. A target-specific implementation of ``AsmPrinter`` is written in diff --git a/llvm/docs/WritingAnLLVMPass.rst b/llvm/docs/WritingAnLLVMPass.rst index 9c2c383..eec9887 100644 --- a/llvm/docs/WritingAnLLVMPass.rst +++ b/llvm/docs/WritingAnLLVMPass.rst @@ -431,7 +431,7 @@ The ``print`` method virtual void print(llvm::raw_ostream &O, const Module *M) const; The ``print`` method must be implemented by "analyses" in order to print a -human readable version of the analysis results. This is useful for debugging +human-readable version of the analysis results. This is useful for debugging an analysis itself, as well as for other people to figure out how an analysis works. Use the opt ``-analyze`` argument to invoke this method. diff --git a/llvm/docs/tutorial/MyFirstLanguageFrontend/LangImpl10.rst b/llvm/docs/tutorial/MyFirstLanguageFrontend/LangImpl10.rst index 7b9105b..a739936 100644 --- a/llvm/docs/tutorial/MyFirstLanguageFrontend/LangImpl10.rst +++ b/llvm/docs/tutorial/MyFirstLanguageFrontend/LangImpl10.rst @@ -129,7 +129,7 @@ course, C source code is not actually portable in general either - ever port a really old application from 32- to 64-bits?). The problem with C (again, in its full generality) is that it is heavily -laden with target specific assumptions. As one simple example, the +laden with target-specific assumptions. As one simple example, the preprocessor often destructively removes target-independence from the code when it processes the input text: |