diff options
Diffstat (limited to 'llvm/docs')
| -rw-r--r-- | llvm/docs/CodeGenerator.rst | 40 | ||||
| -rw-r--r-- | llvm/docs/CommandGuide/dsymutil.rst | 8 | ||||
| -rw-r--r-- | llvm/docs/CommandGuide/llvm-config.rst | 5 | ||||
| -rw-r--r-- | llvm/docs/GettingInvolved.rst | 2 | ||||
| -rw-r--r-- | llvm/docs/HowToReleaseLLVM.rst | 8 | ||||
| -rw-r--r-- | llvm/docs/LangRef.rst | 158 | ||||
| -rw-r--r-- | llvm/docs/MIRLangRef.rst | 56 | ||||
| -rw-r--r-- | llvm/docs/ProgrammersManual.rst | 108 | ||||
| -rw-r--r-- | llvm/docs/ReleaseNotes.md | 4 |
9 files changed, 203 insertions, 186 deletions
diff --git a/llvm/docs/CodeGenerator.rst b/llvm/docs/CodeGenerator.rst index fc704a3..a74f16d 100644 --- a/llvm/docs/CodeGenerator.rst +++ b/llvm/docs/CodeGenerator.rst @@ -498,7 +498,7 @@ The ``MachineBasicBlock`` class The ``MachineBasicBlock`` class contains a list of machine instructions (:raw-html:`<tt>` `MachineInstr`_ :raw-html:`</tt>` instances). It roughly corresponds to the LLVM code input to the instruction selector, but there can be -a one-to-many mapping (i.e. one LLVM basic block can map to multiple machine +a one-to-many mapping (i.e., one LLVM basic block can map to multiple machine basic blocks). The ``MachineBasicBlock`` class has a "``getBasicBlock``" method, which returns the LLVM basic block that it comes from. @@ -522,7 +522,7 @@ LLVM code generator can model sequences of instructions as MachineInstr bundles. A MI bundle can model a VLIW group / pack which contains an arbitrary number of parallel instructions. It can also be used to model a sequential list of instructions (potentially with data dependencies) that cannot be legally -separated (e.g. ARM Thumb2 IT blocks). +separated (e.g., ARM Thumb2 IT blocks). Conceptually a MI bundle is a MI with a number of other MIs nested within: @@ -583,8 +583,8 @@ Packing / bundling of MachineInstrs for VLIW architectures should generally be done as part of the register allocation super-pass. More specifically, the pass which determines what MIs should be bundled together should be done after code generator exits SSA form -(i.e. after two-address pass, PHI elimination, and copy coalescing). -Such bundles should be finalized (i.e. adding BUNDLE MIs and input and +(i.e., after two-address pass, PHI elimination, and copy coalescing). +Such bundles should be finalized (i.e., adding BUNDLE MIs and input and output register MachineOperands) after virtual registers have been rewritten into physical registers. This eliminates the need to add virtual register operands to BUNDLE instructions which would @@ -615,7 +615,7 @@ The ``MCStreamer`` API ---------------------- MCStreamer is best thought of as an assembler API. It is an abstract API which -is *implemented* in different ways (e.g. to output a ``.s`` file, output an ELF ``.o`` +is *implemented* in different ways (e.g., to output a ``.s`` file, output an ELF ``.o`` file, etc) but whose API corresponds directly to what you see in a ``.s`` file. MCStreamer has one method per directive, such as EmitLabel, EmitSymbolAttribute, switchSection, emitValue (for .byte, .word), etc, which directly correspond to @@ -631,7 +631,7 @@ directives through MCStreamer. On the implementation side of MCStreamer, there are two major implementations: one for writing out a ``.s`` file (MCAsmStreamer), and one for writing out a ``.o`` file (MCObjectStreamer). MCAsmStreamer is a straightforward implementation -that prints out a directive for each method (e.g. ``EmitValue -> .byte``), but +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. @@ -681,7 +681,7 @@ The ``MCSection`` class ----------------------- The ``MCSection`` class represents an object-file specific section. It is -subclassed by object file specific implementations (e.g. ``MCSectionMachO``, +subclassed by object file specific implementations (e.g., ``MCSectionMachO``, ``MCSectionCOFF``, ``MCSectionELF``) and these are created and uniqued by MCContext. The MCStreamer has a notion of the current section, which can be changed with the SwitchToSection method (which corresponds to a ".section" @@ -696,7 +696,7 @@ The ``MCInst`` class is a target-independent representation of an instruction. It is a simple class (much more so than `MachineInstr`_) that holds a target-specific opcode and a vector of MCOperands. MCOperand, in turn, is a simple discriminated union of three cases: 1) a simple immediate, 2) a target -register ID, 3) a symbolic expression (e.g. "``Lfoo-Lbar+42``") as an MCExpr. +register ID, 3) a symbolic expression (e.g., "``Lfoo-Lbar+42``") as an MCExpr. MCInst is the common currency used to represent machine instructions at the MC layer. It is the type used by the instruction encoder, the instruction printer, @@ -711,9 +711,9 @@ The MC layer's object writers support a variety of object formats. Because of target-specific aspects of object formats each target only supports a subset of the formats supported by the MC layer. Most targets support emitting ELF objects. Other vendor-specific objects are generally supported only on targets -that are supported by that vendor (i.e. MachO is only supported on targets +that are supported by that vendor (i.e., MachO is only supported on targets supported by Darwin, and XCOFF is only supported on targets that support AIX). -Additionally some targets have their own object formats (i.e. DirectX, SPIR-V +Additionally some targets have their own object formats (i.e., DirectX, SPIR-V and WebAssembly). The table below captures a snapshot of object file support in LLVM: @@ -769,7 +769,7 @@ Introduction to SelectionDAGs The SelectionDAG provides an abstraction for code representation in a way that is amenable to instruction selection using automatic techniques -(e.g. dynamic-programming based optimal pattern matching selectors). It is also +(e.g., dynamic-programming based optimal pattern matching selectors). It is also well-suited to other phases of code generation; in particular, instruction scheduling (SelectionDAG's are very close to scheduling DAGs post-selection). Additionally, the SelectionDAG provides a host representation where a large @@ -898,7 +898,7 @@ Initial SelectionDAG Construction The initial SelectionDAG is na\ :raw-html:`ï`\ vely peephole expanded from the LLVM input by the ``SelectionDAGBuilder`` class. The intent of this pass is to expose as much low-level, target-specific details to the SelectionDAG as -possible. This pass is mostly hard-coded (e.g. an LLVM ``add`` turns into an +possible. This pass is mostly hard-coded (e.g., an LLVM ``add`` turns into an ``SDNode add`` while a ``getelementptr`` is expanded into the obvious arithmetic). This pass requires target-specific hooks to lower calls, returns, varargs, etc. For these features, the :raw-html:`<tt>` `TargetLowering`_ @@ -944,7 +944,7 @@ The Legalize phase is in charge of converting a DAG to only use the operations that are natively supported by the target. Targets often have weird constraints, such as not supporting every operation on -every supported data type (e.g. X86 does not support byte conditional moves and +every supported data type (e.g., X86 does not support byte conditional moves and PowerPC does not support sign-extending loads from a 16-bit memory location). Legalize takes care of this by open-coding another sequence of operations to emulate the operation ("expansion"), by promoting one type to a larger type that @@ -995,7 +995,7 @@ SelectionDAG Optimization Phase: the DAG Combiner The SelectionDAG optimization phase is run multiple times for code generation, immediately after the DAG is built and once after each legalization. The first -run of the pass allows the initial code to be cleaned up (e.g. performing +run of the pass allows the initial code to be cleaned up (e.g., performing optimizations that depend on knowing that the operators have restricted type inputs). Subsequent runs of the pass clean up the messy code generated by the Legalize passes, which allows Legalize to be very simple (it can focus on making @@ -1120,10 +1120,10 @@ for your target. It has the following strengths: 16-bits of the immediate). * When using the 'Pat' class to map a pattern to an instruction that has one - or more complex operands (like e.g. `X86 addressing mode`_), the pattern may + or more complex operands (like e.g., `X86 addressing mode`_), the pattern may either specify the operand as a whole using a ``ComplexPattern``, or else it may specify the components of the complex operand separately. The latter is - done e.g. for pre-increment instructions by the PowerPC back end: + done e.g., for pre-increment instructions by the PowerPC back end: :: @@ -1145,13 +1145,13 @@ While it has many strengths, the system currently has some limitations, primarily because it is a work in progress and is not yet finished: * Overall, there is no way to define or match SelectionDAG nodes that define - multiple values (e.g. ``SMUL_LOHI``, ``LOAD``, ``CALL``, etc). This is the + multiple values (e.g., ``SMUL_LOHI``, ``LOAD``, ``CALL``, etc). This is the biggest reason that you currently still *have to* write custom C++ code for your instruction selector. * There is no great way to support matching complex addressing modes yet. In the future, we will extend pattern fragments to allow them to define multiple - values (e.g. the four operands of the `X86 addressing mode`_, which are + values (e.g., the four operands of the `X86 addressing mode`_, which are currently matched with custom C++ code). In addition, we'll extend fragments so that a fragment can match multiple different patterns. @@ -1175,7 +1175,7 @@ SelectionDAG Scheduling and Formation Phase The scheduling phase takes the DAG of target instructions from the selection phase and assigns an order. The scheduler can pick an order depending on -various constraints of the machines (i.e. order for minimal register pressure or +various constraints of the machines (i.e., order for minimal register pressure or try to cover instruction latencies). Once an order is established, the DAG is converted to a list of :raw-html:`<tt>` `MachineInstr`_\s :raw-html:`</tt>` and the SelectionDAG is destroyed. @@ -1615,7 +1615,7 @@ Since the MC layer works at the level of abstraction of object files, it doesn't have a notion of functions, global variables etc. Instead, it thinks about labels, directives, and instructions. A key class used at this time is the MCStreamer class. This is an abstract API that is implemented in different ways -(e.g. to output a ``.s`` file, output an ELF ``.o`` file, etc) that is effectively an +(e.g., to output a ``.s`` file, output an ELF ``.o`` file, etc) that is effectively an "assembler API". MCStreamer has one method per directive, such as EmitLabel, EmitSymbolAttribute, switchSection, etc, which directly correspond to assembly level directives. diff --git a/llvm/docs/CommandGuide/dsymutil.rst b/llvm/docs/CommandGuide/dsymutil.rst index 8e61e01..0e442d6 100644 --- a/llvm/docs/CommandGuide/dsymutil.rst +++ b/llvm/docs/CommandGuide/dsymutil.rst @@ -70,6 +70,14 @@ OPTIONS Print this help output. +.. option:: --include-swiftmodules-from-interface + + Whether or not to copy binary swiftmodules built from textual .swiftinterface + files into the dSYM bundle. These typically come only from the SDK (since + textual interfaces require library evolution) and thus are a waste of space to + copy into the bundle. Turn this on if the swiftmodules are different from + those in the SDK. + .. option:: --keep-function-for-static Make a static variable keep the enclosing function even if it would have been diff --git a/llvm/docs/CommandGuide/llvm-config.rst b/llvm/docs/CommandGuide/llvm-config.rst index 63658d0..1c5c9c7 100644 --- a/llvm/docs/CommandGuide/llvm-config.rst +++ b/llvm/docs/CommandGuide/llvm-config.rst @@ -126,6 +126,11 @@ OPTIONS Print the installation prefix for LLVM. +**--quote-paths** + + Quote and escape paths when needed, most notably when a quote, space, backslash + or dollar sign characters are present in the path. + **--shared-mode** Print how the provided components can be collectively linked (`shared` or `static`). diff --git a/llvm/docs/GettingInvolved.rst b/llvm/docs/GettingInvolved.rst index 039d616..0dba941 100644 --- a/llvm/docs/GettingInvolved.rst +++ b/llvm/docs/GettingInvolved.rst @@ -225,7 +225,7 @@ what to add to your calendar invite. - * - GlobalISel - Every 2nd Tuesday of the month - - `gcal <https://calendar.google.com/calendar/u/0?cid=ZDcyMjc0ZjZiZjNhMzFlYmE3NTNkMWM2MGM2NjM5ZWU3ZDE2MjM4MGFlZDc2ZjViY2UyYzMwNzVhZjk4MzQ4ZEBncm91cC5jYWxlbmRhci5nb29nbGUuY29t>`__ + - `gcal <https://calendar.google.com/calendar/u/0?cid=YWZjNzhmMzE4MDNlNTAyNGY1NmE1MDIyODY0YTYwZmJmYzRjYTEwNTE1NmUxODA2NzBkYTliY2ZhYTVkNjk0NUBncm91cC5jYWxlbmRhci5nb29nbGUuY29t>`__ - `Meeting details/agenda <https://docs.google.com/document/d/1Ry8O4-Tm5BFj9AMjr8qTQFU80z-ptiNQ62687NaIvLs/edit?usp=sharing>`__ diff --git a/llvm/docs/HowToReleaseLLVM.rst b/llvm/docs/HowToReleaseLLVM.rst index 171bf88..c269cc4 100644 --- a/llvm/docs/HowToReleaseLLVM.rst +++ b/llvm/docs/HowToReleaseLLVM.rst @@ -311,10 +311,10 @@ This section describes how to triage bug reports: to backport. You should also review the bug yourself to ensure that it meets the requirements for committing to the release branch. -#. Once a bug has been reviewed, add the release:reviewed label and update the - issue's status to "Needs Merge". Check the pull request associated with the - issue. If all the tests pass, then the pull request can be merged. If not, - then add a comment on the issue asking someone to take a look at the failures. +#. Once a bug has been reviewed, update the status to "Needs Merge". Check the + pull request associated with the issue. If all the tests pass, then the pull + request can be merged. If not, then add a comment on the issue asking + someone to take a look at the failures. Release Patch Rules diff --git a/llvm/docs/LangRef.rst b/llvm/docs/LangRef.rst index 1c6823b..3c089b5 100644 --- a/llvm/docs/LangRef.rst +++ b/llvm/docs/LangRef.rst @@ -159,7 +159,7 @@ There are two kinds of escapes. * ``\\`` represents a single ``\`` character. * ``\`` followed by two hexadecimal characters (0-9, a-f, or A-F) - represents the byte with the given value (e.g. ``\00`` represents a + represents the byte with the given value (e.g., ``\00`` represents a null byte). To represent a ``"`` character, use ``\22``. (``\"`` will end the string @@ -168,7 +168,7 @@ with a trailing ``\``.) Newlines do not terminate string constants; strings can span multiple lines. -The interpretation of string constants (e.g. their character encoding) +The interpretation of string constants (e.g., their character encoding) depends on context. @@ -330,7 +330,7 @@ added in the future: the function (as does normal C). "``fastcc``" - The fast calling convention This calling convention attempts to make calls as fast as possible - (e.g. by passing things in registers). This calling convention + (e.g., by passing things in registers). This calling convention allows the target to use whatever tricks it wants to produce fast code for the target, without having to conform to an externally specified ABI (Application Binary Interface). `Tail calls can only @@ -465,7 +465,7 @@ added in the future: This calling convention doesn't preserve any general registers. So all general registers are caller saved registers. It also uses all general registers to pass arguments. This attribute doesn't impact non-general - purpose registers (e.g. floating point registers, on X86 XMMs/YMMs). + purpose registers (e.g., floating point registers, on X86 XMMs/YMMs). Non-general purpose registers still follow the standard C calling convention. Currently it is for x86_64 and AArch64 only. "``cxx_fast_tlscc``" - The `CXX_FAST_TLS` calling convention for access functions @@ -668,7 +668,7 @@ representation is not just an integer address are called "non-integral". Non-integral pointers have at least one of the following three properties: * the pointer representation contains non-address bits -* the pointer representation is unstable (may changed at any time in a +* the pointer representation is unstable (may change at any time in a target-specific way) * the pointer representation has external state @@ -700,7 +700,7 @@ Unstable pointer representation ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Pointers in this address space have an *unspecified* bitwise representation -(i.e. not backed by a fixed integer). The bitwise pattern of such pointers is +(i.e., not backed by a fixed integer). The bitwise pattern of such pointers is allowed to change in a target-specific way. For example, this could be a pointer type used with copying garbage collection where the garbage collector could update the pointer at any time in the collection sweep. @@ -757,7 +757,7 @@ The following restrictions apply to IR level optimization passes: The ``inttoptr`` instruction does not recreate the external state and therefore it is target dependent whether it can be used to create a dereferenceable -pointer. In general passes should assume that the result of such an inttoptr +pointer. In general passes should assume that the result of such an ``inttoptr`` is not dereferenceable. For example, on CHERI targets an ``inttoptr`` will yield a capability with the external state (the validity tag bit) set to zero, which will cause any dereference to trap. @@ -784,7 +784,7 @@ be performed as loads and stores of the correct type since stores of other types may not propagate the external data. Therefore it is not legal to convert an existing load/store (or a ``llvm.memcpy`` / ``llvm.memmove`` intrinsic) of pointer types with external -state to a load/store of an integer type with same bitwidth, as that may drop +state to a load/store of an integer type with the same bitwidth, as that may drop the external state. @@ -806,7 +806,7 @@ Global variables can optionally specify a :ref:`linkage type <linkage>`. Either global variable definitions or declarations may have an explicit section to be placed in and may have an optional explicit alignment specified. If there is a mismatch between the explicit or inferred section information for the -variable declaration and its definition the resulting behavior is undefined. +variable declaration and its definition, the resulting behavior is undefined. A variable may be defined as a global ``constant``, which indicates that the contents of the variable will **never** be modified (enabling better @@ -903,7 +903,7 @@ size is unknown at compile time. They are allowed in structs to facilitate intrinsics returning multiple values. Generally, structs containing scalable vectors are not considered "sized" and cannot be used in loads, stores, allocas, or GEPs. The only exception to this rule is for structs that contain scalable -vectors of the same type (e.g. ``{<vscale x 2 x i32>, <vscale x 2 x i32>}`` +vectors of the same type (e.g., ``{<vscale x 2 x i32>, <vscale x 2 x i32>}`` contains the same type while ``{<vscale x 2 x i32>, <vscale x 2 x i64>}`` doesn't). These kinds of structs (we may call them homogeneous scalable vector structs) are considered sized and can be used in loads, stores, allocas, but @@ -1221,7 +1221,7 @@ sections. Note that certain IR constructs like global variables and functions may create COMDATs in the object file in addition to any which are specified using COMDAT IR. This arises when the code generator is configured to emit globals -in individual sections (e.g. when `-data-sections` or `-function-sections` +in individual sections (e.g., when `-data-sections` or `-function-sections` is supplied to `llc`). .. _namedmetadatastructure: @@ -1334,7 +1334,7 @@ Currently, only the following parameter attributes are defined: The byval type argument indicates the in-memory value type. The byval attribute also supports specifying an alignment with the - align attribute. It indicates the alignment of the stack slot to + ``align`` attribute. It indicates the alignment of the stack slot to form and the known alignment of the pointer specified to the call site. If the alignment is not specified, then the code generator makes a target-specific assumption. @@ -1355,7 +1355,7 @@ Currently, only the following parameter attributes are defined: This is not a valid attribute for return values. - The alignment for an ``byref`` parameter can be explicitly + The alignment for a ``byref`` parameter can be explicitly specified by combining it with the ``align`` attribute, similar to ``byval``. If the alignment is not specified, then the code generator makes a target-specific assumption. @@ -1382,7 +1382,7 @@ Currently, only the following parameter attributes are defined: The preallocated attribute requires a type argument. The preallocated attribute also supports specifying an alignment with the - align attribute. It indicates the alignment of the stack slot to + ``align`` attribute. It indicates the alignment of the stack slot to form and the known alignment of the pointer specified to the call site. If the alignment is not specified, then the code generator makes a target-specific assumption. @@ -1550,7 +1550,7 @@ Currently, only the following parameter attributes are defined: ``nonnull`` This indicates that the parameter or return pointer is not null. This - attribute may only be applied to pointer typed parameters. This is not + attribute may only be applied to pointer-typed parameters. This is not checked or enforced by LLVM; if the parameter or return pointer is null, :ref:`poison value <poisonvalues>` is returned or passed instead. The ``nonnull`` attribute should be combined with the ``noundef`` attribute @@ -1558,7 +1558,7 @@ Currently, only the following parameter attributes are defined: ``dereferenceable(<n>)`` This indicates that the parameter or return pointer is dereferenceable. This - attribute may only be applied to pointer typed parameters. A pointer that + attribute may only be applied to pointer-typed parameters. A pointer that is dereferenceable can be loaded from speculatively without a risk of trapping. The number of bytes known to be dereferenceable must be provided in parentheses. It is legal for the number of bytes to be less than the @@ -1584,7 +1584,7 @@ Currently, only the following parameter attributes are defined: implies that a pointer is at least one of ``dereferenceable(<n>)`` or ``null`` (i.e., it may be both ``null`` and ``dereferenceable(<n>)``). This attribute may only be applied to - pointer typed parameters. + pointer-typed parameters. ``swiftself`` This indicates that the parameter is the self/context parameter. This is not @@ -1601,7 +1601,7 @@ Currently, only the following parameter attributes are defined: ``swifterror`` This attribute is motivated to model and optimize Swift error handling. It - can be applied to a parameter with pointer to pointer type or a + can be applied to a parameter with pointer-to-pointer type or a pointer-sized alloca. At the call site, the actual argument that corresponds to a ``swifterror`` parameter has to come from a ``swifterror`` alloca or the ``swifterror`` parameter of the caller. A ``swifterror`` value (either @@ -1722,7 +1722,7 @@ Currently, only the following parameter attributes are defined: The function parameter marked with this attribute is the alignment in bytes of the newly allocated block returned by this function. The returned value must either have the specified alignment or be the null pointer. The return value MAY be more aligned - than the requested alignment, but not less aligned. Invalid (e.g. non-power-of-2) + than the requested alignment, but not less aligned. Invalid (e.g., non-power-of-2) alignments are permitted for the allocalign parameter, so long as the returned pointer is null. This attribute may only be applied to integer parameters. @@ -1989,7 +1989,7 @@ functions will use the same set of attributes. In the degenerate case of a group will capture the important command line flags used to build that file. An attribute group is a module-level object. To use an attribute group, an -object references the attribute group's ID (e.g. ``#37``). An object may refer +object references the attribute group's ID (e.g., ``#37``). An object may refer to more than one attribute group. In that situation, the attributes from the different groups are merged. @@ -2222,7 +2222,7 @@ For example: - ``errnomem``: This refers to accesses to the ``errno`` variable. - The default access kind (specified without a location prefix) applies to all locations that haven't been specified explicitly, including those that - don't currently have a dedicated location kind (e.g. accesses to globals + don't currently have a dedicated location kind (e.g., accesses to globals or captured pointers). If the ``memory`` attribute is not specified, then ``memory(readwrite)`` @@ -2713,7 +2713,7 @@ For example: ``mustprogress`` This attribute indicates that the function is required to return, unwind, - or interact with the environment in an observable way e.g. via a volatile + or interact with the environment in an observable way e.g., via a volatile memory access, I/O, or other synchronization. The ``mustprogress`` attribute is intended to model the requirements of the first section of [intro.progress] of the C++ Standard. As a consequence, a loop in a @@ -2851,7 +2851,7 @@ are grouped into a single :ref:`attribute group <attrgrp>`. with `__attribute__((no_sanitize("memtag")))`, `__attribute__((disable_sanitizer_instrumentation))`, or included in the `-fsanitize-ignorelist` file. The AArch64 Globals Tagging pass may remove - this attribute when it's not possible to tag the global (e.g. it's a TLS + this attribute when it's not possible to tag the global (e.g., it's a TLS variable). ``sanitize_address_dyninit`` This attribute indicates that the global variable, when instrumented with @@ -3076,7 +3076,7 @@ the behavior is undefined, unless one of the following exceptions applies: * ``dereferenceable(<n>)`` operand bundles only guarantee the pointer is dereferenceable at the point of the assumption. The pointer may not be - dereferenceable at later pointers, e.g. because it could have been freed. + dereferenceable at later pointers, e.g., because it could have been freed. In addition to allowing operand bundles encoding function and parameter attributes, an assume operand bundle may also encode a ``separate_storage`` @@ -3270,7 +3270,7 @@ as follows: address space 0. Note: variable declarations without an address space are always created in address space 0, this property only affects the default value to be used - when creating globals without additional contextual information (e.g. in + when creating globals without additional contextual information (e.g., in LLVM passes). .. _alloca_addrspace: @@ -3282,7 +3282,7 @@ as follows: This specifies the properties of a pointer in address space ``as``. The ``<size>`` parameter specifies the size of the bitwise representation. For :ref:`non-integral pointers <nointptrtype>` the representation size may - be larger than the address width of the underlying address space (e.g. to + be larger than the address width of the underlying address space (e.g., to accommodate additional metadata). The alignment requirements are specified via the ``<abi>`` and ``<pref>``\erred alignments parameters. @@ -3478,7 +3478,7 @@ variables) may *not* change their size. (``realloc``-style operations do not change the size of an existing allocated object; instead, they create a new allocated object. Even if the object is at the same location as the old one, old pointers cannot be used to access this new object.) However, allocated objects -can also be created by means not recognized by LLVM, e.g. by directly calling +can also be created by means not recognized by LLVM, e.g., by directly calling ``mmap``. Those allocated objects are allowed to grow to the right (i.e., keeping the same base address, but increasing their size) while maintaining the validity of existing pointers, as long as they always satisfy the properties @@ -3632,7 +3632,7 @@ through the return value only: } However, we always consider direct inspection of the pointer address -(e.g. using ``ptrtoint``) to be location-independent. The following example +(e.g., using ``ptrtoint``) to be location-independent. The following example is *not* considered a return-only capture, even though the ``ptrtoint`` ultimately only contributes to the return value: @@ -4145,7 +4145,7 @@ output, given the original flags. ``a * (c / b)`` can be rewritten into ``a / (b / c)``. ``contract`` - Allow floating-point contraction (e.g. fusing a multiply followed by an + Allow floating-point contraction (e.g., fusing a multiply followed by an addition into a fused multiply-and-add). This does not enable reassociation to form arbitrary contractions. For example, ``(a*b) + (c*d) + e`` can not be transformed into ``(a*b) + ((c*d) + e)`` to create two fma operations. @@ -4440,7 +4440,7 @@ the default globals address space and ``addrspace("P")`` the program address space. The representation of pointers can be different for each address space and does -not necessarily need to be a plain integer address (e.g. for +not necessarily need to be a plain integer address (e.g., for :ref:`non-integral pointers <nointptrtype>`). In addition to a representation bits size, pointers in each address space also have an index size which defines the bitwidth of indexing operations as well as the size of `integer addresses` @@ -4750,7 +4750,7 @@ is inserted as defined by the DataLayout string in the module, which is required to match what the underlying code generator expects. Structures can either be "literal" or "identified". A literal structure -is defined inline with other types (e.g. ``[2 x {i32, i32}]``) whereas +is defined inline with other types (e.g., ``[2 x {i32, i32}]``) whereas identified types are always defined at the top level with a name. Literal types are uniqued by their contents and can never be recursive or opaque since there is no way to write one. Identified types can be @@ -4791,7 +4791,7 @@ Simple Constants Standard integers (such as '4') are constants of the :ref:`integer <t_integer>` type. They can be either decimal or hexadecimal. Decimal integers can be prefixed with - to represent - negative integers, e.g. '``-1234``'. Hexadecimal integers must be + negative integers, e.g., '``-1234``'. Hexadecimal integers must be prefixed with either u or s to indicate whether they are unsigned or signed respectively. e.g '``u0x8000``' gives 32768, whilst '``s0x8000``' gives -32768. @@ -4801,7 +4801,7 @@ Simple Constants zeros. So '``s0x0001``' of type '``i16``' will be -1, not 1. **Floating-point constants** Floating-point constants use standard decimal notation (e.g. - 123.421), exponential notation (e.g. 1.23421e+2), or a more precise + 123.421), exponential notation (e.g., 1.23421e+2), or a more precise hexadecimal notation (see below). The assembler requires the exact decimal value of a floating-point constant. For example, the assembler accepts 1.25 but rejects 1.3 because 1.3 is a repeating @@ -4883,7 +4883,7 @@ constants and smaller complex constants. The string '``zeroinitializer``' can be used to zero initialize a value to zero of *any* type, including scalar and :ref:`aggregate <t_aggregate>` types. This is often used to avoid - having to print large zero initializers (e.g. for large arrays) and + having to print large zero initializers (e.g., for large arrays) and is always exactly equivalent to using explicit zero initializers. **Metadata node** A metadata node is a constant tuple without types. For example: @@ -5286,7 +5286,7 @@ Constant Expressions Constant expressions are used to allow expressions involving other constants to be used as constants. Constant expressions may be of any :ref:`first class <t_firstclass>` type and may involve any LLVM operation -that does not have side effects (e.g. load and call are not supported). +that does not have side effects (e.g., load and call are not supported). The following is the syntax for constant expressions: ``trunc (CST to TYPE)`` @@ -5472,7 +5472,7 @@ There are also three different categories of constraint codes: Output constraints """""""""""""""""" -Output constraints are specified by an "``=``" prefix (e.g. "``=r``"). This +Output constraints are specified by an "``=``" prefix (e.g., "``=r``"). This indicates that the assembly will write to this operand, and the operand will then be made available as a return value of the ``asm`` expression. Output constraints do not consume an argument from the call instruction. (Except, see @@ -5480,10 +5480,10 @@ below about indirect outputs). Normally, it is expected that no output locations are written to by the assembly expression until *all* of the inputs have been read. As such, LLVM may assign -the same register to an output and an input. If this is not safe (e.g. if the +the same register to an output and an input. If this is not safe (e.g., if the assembly contains two instructions, where the first writes to one output, and the second reads an input and writes to a second output), then the "``&``" -modifier must be used (e.g. "``=&r``") to specify that the output is an +modifier must be used (e.g., "``=&r``") to specify that the output is an "early-clobber" output. Marking an output as "early-clobber" ensures that LLVM will not use the same register for any inputs (other than an input tied to this output). @@ -5523,17 +5523,17 @@ However, this feature is often not as useful as you might think. Firstly, the registers are *not* guaranteed to be consecutive. So, on those architectures that have instructions which operate on multiple consecutive -instructions, this is not an appropriate way to support them. (e.g. the 32-bit +instructions, this is not an appropriate way to support them. (e.g., the 32-bit SparcV8 has a 64-bit load, which instruction takes a single 32-bit register. The hardware then loads into both the named register, and the next register. This feature of inline asm would not be useful to support that.) A few of the targets provide a template string modifier allowing explicit access -to the second register of a two-register operand (e.g. MIPS ``L``, ``M``, and +to the second register of a two-register operand (e.g., MIPS ``L``, ``M``, and ``D``). On such an architecture, you can actually access the second allocated register (yet, still, not any subsequent ones). But, in that case, you're still probably better off simply splitting the value into two separate operands, for -clarity. (e.g. see the description of the ``A`` constraint on X86, which, +clarity. (e.g., see the description of the ``A`` constraint on X86, which, despite existing only for use with this feature, is not really a good idea to use) @@ -5549,11 +5549,11 @@ rather than producing a return value. An indirect output constraint is an "output" only in that the asm is expected to write to the contents of the input memory location, instead of just read from it). -This is most typically used for memory constraint, e.g. "``=*m``", to pass the +This is most typically used for memory constraint, e.g., "``=*m``", to pass the address of a variable as a value. It is also possible to use an indirect *register* constraint, but only on output -(e.g. "``=*r``"). This will cause LLVM to allocate a register for an output +(e.g., "``=*r``"). This will cause LLVM to allocate a register for an output value normally, and then, separately emit a store to the address provided as input, after the provided inline asm. (It's not clear what value this functionality provides, compared to writing the store explicitly after the asm @@ -5570,7 +5570,7 @@ Clobber constraints A clobber constraint is indicated by a "``~``" prefix. A clobber does not consume an input operand, nor generate an output. Clobbers cannot use any of the general constraint code letters -- they may use only explicit register -constraints, e.g. "``~{eax}``". The one exception is that a clobber string of +constraints, e.g., "``~{eax}``". The one exception is that a clobber string of "``~{memory}``" indicates that the assembly writes to arbitrary undeclared memory locations -- not only the memory pointed to by a declared indirect output. @@ -5594,9 +5594,9 @@ Constraint Codes """""""""""""""" After a potential prefix comes constraint code, or codes. -A Constraint Code is either a single letter (e.g. "``r``"), a "``^``" character -followed by two letters (e.g. "``^wc``"), or "``{``" register-name "``}``" -(e.g. "``{eax}``"). +A Constraint Code is either a single letter (e.g., "``r``"), a "``^``" character +followed by two letters (e.g., "``^wc``"), or "``{``" register-name "``}``" +(e.g., "``{eax}``"). The one and two letter constraint codes are typically chosen to be the same as GCC's constraint codes. @@ -5973,11 +5973,11 @@ Target-independent: - ``a``: Print a memory reference. Targets might customize the output. - ``c``: Print an immediate integer constant unadorned, without - the target-specific immediate punctuation (e.g. no ``$`` prefix). + the target-specific immediate punctuation (e.g., no ``$`` prefix). - ``n``: Negate and print immediate integer constant unadorned, without the - target-specific immediate punctuation (e.g. no ``$`` prefix). + target-specific immediate punctuation (e.g., no ``$`` prefix). - ``l``: Print as an unadorned label, without the target-specific label - punctuation (e.g. no ``$`` prefix). + punctuation (e.g., no ``$`` prefix). AArch64: @@ -5998,7 +5998,7 @@ ARM: register). - ``P``: No effect. - ``q``: No effect. -- ``y``: Print a VFP single-precision register as an indexed double (e.g. print +- ``y``: Print a VFP single-precision register as an indexed double (e.g., print as ``d4[1]`` instead of ``s9``) - ``B``: Bitwise invert and print an immediate integer constant without ``#`` prefix. @@ -6114,18 +6114,18 @@ X86: - ``c``: Print an unadorned integer or symbol name. (The latter is target-specific behavior for this typically target-independent modifier). - ``A``: Print a register name with a '``*``' before it. -- ``b``: Print an 8-bit register name (e.g. ``al``); do nothing on a memory +- ``b``: Print an 8-bit register name (e.g., ``al``); do nothing on a memory operand. -- ``h``: Print the upper 8-bit register name (e.g. ``ah``); do nothing on a +- ``h``: Print the upper 8-bit register name (e.g., ``ah``); do nothing on a memory operand. -- ``w``: Print the 16-bit register name (e.g. ``ax``); do nothing on a memory +- ``w``: Print the 16-bit register name (e.g., ``ax``); do nothing on a memory operand. -- ``k``: Print the 32-bit register name (e.g. ``eax``); do nothing on a memory +- ``k``: Print the 32-bit register name (e.g., ``eax``); do nothing on a memory operand. -- ``q``: Print the 64-bit register name (e.g. ``rax``), if 64-bit registers are +- ``q``: Print the 64-bit register name (e.g., ``rax``), if 64-bit registers are available, otherwise the 32-bit register name; do nothing on a memory operand. - ``n``: Negate and print an unadorned integer, or, for operands other than an - immediate integer (e.g. a relocatable symbol expression), print a '-' before + immediate integer (e.g., a relocatable symbol expression), print a '-' before the operand. (The behavior for relocatable symbol expressions is a target-specific behavior for this typically target-independent modifier) - ``H``: Print a memory reference with additional offset +8. @@ -6883,7 +6883,7 @@ See :ref:`diexpression` for details. .. note:: ``DIExpression``\s are always printed and parsed inline; they can never be - referenced by an ID (e.g. ``!1``). + referenced by an ID (e.g., ``!1``). Some examples of expressions: @@ -8469,8 +8469,8 @@ that was typically cold and one allocating memory that was typically not cold. The format of the metadata describing a context specific profile (e.g. ``!1`` and ``!3`` above) requires a first operand that is a metadata node describing the context, followed by a list of string metadata tags describing -the profile behavior (e.g. ``cold`` and ``notcold``) above. The metadata nodes -describing the context (e.g. ``!2`` and ``!4`` above) are unique ids +the profile behavior (e.g., ``cold`` and ``notcold``) above. The metadata nodes +describing the context (e.g., ``!2`` and ``!4`` above) are unique ids corresponding to callsites, which can be matched to associated IR calls via :ref:`callsite metadata<md_callsite>`. In practice these ids are formed via a hash of the callsite's debug info, and the associated call may be in a @@ -8946,7 +8946,7 @@ in syntax by a caret ('``^``'). The summary is parsed into a bitcode output, along with the Module IR, via the "``llvm-as``" tool. Tools that parse the Module IR for the purposes -of optimization (e.g. "``clang -x ir``" and "``opt``"), will ignore the +of optimization (e.g., "``clang -x ir``" and "``opt``"), will ignore the summary entries (just as they currently ignore summary entries in a bitcode input file). @@ -9176,7 +9176,7 @@ The optional ``Refs`` field looks like: refs: ((Ref)[, (Ref)]*) where each ``Ref`` contains a reference to the summary id of the referenced -value (e.g. ``^1``). +value (e.g., ``^1``). .. _typeidinfo_summary: @@ -10385,7 +10385,7 @@ bit width of the result. Because LLVM integers use a two's complement representation, and the result is the same width as the operands, this instruction returns the correct result for both signed and unsigned integers. If a full product -(e.g. ``i32`` * ``i32`` -> ``i64``) is needed, the operands should be +(e.g., ``i32`` * ``i32`` -> ``i64``) is needed, the operands should be sign-extended or zero-extended as appropriate to the width of the full product. @@ -11378,7 +11378,7 @@ allocation on any convenient boundary compatible with the type. '``type``' may be any sized type. Structs containing scalable vectors cannot be used in allocas unless all -fields are the same scalable vector type (e.g. ``{<vscale x 2 x i32>, +fields are the same scalable vector type (e.g., ``{<vscale x 2 x i32>, <vscale x 2 x i32>}`` contains the same type while ``{<vscale x 2 x i32>, <vscale x 2 x i64>}`` doesn't). @@ -12766,7 +12766,7 @@ pointer then a truncation is done. If ``value`` is smaller than the size of a pointer then a zero extension is done. If they are the same size, nothing is done (*no-op cast*). The behavior is equivalent to a ``bitcast``, however, the resulting value is not -guaranteed to be dereferenceable (e.g. if the result type is a +guaranteed to be dereferenceable (e.g., if the result type is a :ref:`non-integral pointers <nointptrtype>`). Example: @@ -14697,7 +14697,7 @@ C++ object with a non-trivial destructor. ``llvm.seh.scope.begin`` is used to m the start of the region; it is always called with ``invoke``, with the unwind block being the desired unwind destination for any potentially-throwing instructions within the region. `llvm.seh.scope.end` is used to mark when the scope ends -and the EH cleanup is no longer required (e.g. because the destructor is being +and the EH cleanup is no longer required (e.g., because the destructor is being called). .. _int_read_register: @@ -14737,7 +14737,7 @@ return the current value of the register, where possible. The where possible. A call to '``llvm.read_volatile_register``' is assumed to have side-effects -and possibly return a different value each time (e.g. for a timer register). +and possibly return a different value each time (e.g., for a timer register). This is useful to implement named register global variables that need to always be mapped to a specific register, as is common practice on @@ -15008,9 +15008,9 @@ flushes the instruction cache. Semantics: """""""""" -On platforms with coherent instruction and data caches (e.g. x86), this +On platforms with coherent instruction and data caches (e.g., x86), this intrinsic is a nop. On platforms with non-coherent instruction and data -cache (e.g. ARM, MIPS), the intrinsic is lowered either to appropriate +cache (e.g., ARM, MIPS), the intrinsic is lowered either to appropriate instructions or a system call, if cache flushing requires special privileges. @@ -15462,7 +15462,7 @@ A call to '``llvm.call.preallocated.arg``' must have a call site ``preallocated`` attribute. The type of the ``preallocated`` attribute must match the type used by the ``preallocated`` attribute of the corresponding argument at the preallocated call. The type is used in the case that an -``llvm.call.preallocated.setup`` does not have a corresponding call (e.g. due +``llvm.call.preallocated.setup`` does not have a corresponding call (e.g., due to DCE), where otherwise we cannot know how large the arguments are. It is undefined behavior if this is called with a token from an @@ -16656,7 +16656,7 @@ for large input values. .. note:: Currently, the default lowering of this intrinsic relies on the ``sincospi[f|l]`` - functions being available in the target's runtime (e.g. libc). + functions being available in the target's runtime (e.g., libc). When specified with the fast-math-flag 'afn', the result may be approximated using a less accurate calculation. @@ -19719,7 +19719,7 @@ Arguments: """""""""" The integer operand is the loop trip count of the hardware-loop, and thus -not e.g. the loop back-edge taken count. +not e.g., the loop back-edge taken count. Semantics: """""""""" @@ -19758,7 +19758,7 @@ Arguments: """""""""" The integer operand is the loop trip count of the hardware-loop, and thus -not e.g. the loop back-edge taken count. +not e.g., the loop back-edge taken count. Semantics: """""""""" @@ -19794,7 +19794,7 @@ Arguments: """""""""" The integer operand is the loop trip count of the hardware-loop, and thus -not e.g. the loop back-edge taken count. +not e.g., the loop back-edge taken count. Semantics: """""""""" @@ -19832,7 +19832,7 @@ Arguments: """""""""" The integer operand is the loop trip count of the hardware-loop, and thus -not e.g. the loop back-edge taken count. +not e.g., the loop back-edge taken count. Semantics: """""""""" @@ -20768,7 +20768,7 @@ of the result's type, while maintaining the same element type. Semantics: """""""""" -Other than the reduction operator (e.g. add) the way in which the concatenated +Other than the reduction operator (e.g., add) the way in which the concatenated arguments is reduced is entirely unspecified. By their nature these intrinsics are not expected to be useful in isolation but instead implement the first phase of an overall reduction operation. @@ -24286,7 +24286,7 @@ The arguments are scalar types to accommodate scalable vector types, for which it is unknown what the type of the step vector needs to be that enumerate its lanes without overflow. -This mask ``%m`` can e.g. be used in masked load/store instructions. These +This mask ``%m`` can e.g., be used in masked load/store instructions. These intrinsics provide a hint to the backend. I.e., for a vector loop, the back-edge taken count of the original scalar loop is explicit as the second argument. @@ -27966,7 +27966,7 @@ The quiet comparison operation performed by if either argument is a SNAN. The signaling comparison operation performed by '``llvm.experimental.constrained.fcmps``' will raise an exception if either argument is a NAN (QNAN or SNAN). Such an exception -does not preclude a result being produced (e.g. exception might only +does not preclude a result being produced (e.g., exception might only set a flag), therefore the distinction between ordered and unordered comparisons is also relevant for the '``llvm.experimental.constrained.fcmps``' intrinsic. @@ -29983,7 +29983,7 @@ Semantics: On some platforms, the value returned by this intrinsic remains unchanged between loads in the same thread. On other platforms, it returns the same -global variable value, if any, e.g. ``@__stack_chk_guard``. +global variable value, if any, e.g., ``@__stack_chk_guard``. Currently some platforms have IR-level customized stack guard loading (e.g. X86 Linux) that is not handled by ``llvm.stackguard()``, while they should be diff --git a/llvm/docs/MIRLangRef.rst b/llvm/docs/MIRLangRef.rst index 3f4c3cd..f7647c8 100644 --- a/llvm/docs/MIRLangRef.rst +++ b/llvm/docs/MIRLangRef.rst @@ -86,25 +86,25 @@ Tests are more accessible and future proof when simplified: - Use the ``-simplify-mir`` option with llc. - Machine function attributes often have default values or the test works just - as well with default values. Typical candidates for this are: `alignment:`, - `exposesReturnsTwice`, `legalized`, `regBankSelected`, `selected`. + as well with default values. Typical candidates for this are: ``alignment:``, + ``exposesReturnsTwice``, ``legalized``, ``regBankSelected``, ``selected``. The whole `frameInfo` section is often unnecessary if there is no special - frame usage in the function. `tracksRegLiveness` on the other hand is often + frame usage in the function. ``tracksRegLiveness`` on the other hand is often necessary for some passes that care about block livein lists. -- The (global) `liveins:` list is typically only interesting for early +- The (global) ``liveins:`` list is typically only interesting for early instruction selection passes and can be removed when testing later passes. - The per-block `liveins:` on the other hand are necessary if + The per-block ``liveins:`` on the other hand are necessary if `tracksRegLiveness` is true. -- Branch probability data in block `successors:` lists can be dropped if the +- Branch probability data in block ``successors:`` lists can be dropped if the test doesn't depend on it. Example: - `successors: %bb.1(0x40000000), %bb.2(0x40000000)` can be replaced with - `successors: %bb.1, %bb.2`. + ``successors: %bb.1(0x40000000), %bb.2(0x40000000)`` can be replaced with + ``successors: %bb.1, %bb.2``. - MIR code contains a whole IR module. This is necessary because there are no equivalents in MIR for global variables, references to external functions, - function attributes, metadata, debug info. Instead some MIR data references + function attributes, metadata, debug info. Instead, some MIR data references the IR constructs. You can often remove them if the test doesn't depend on them. @@ -114,16 +114,16 @@ Tests are more accessible and future proof when simplified: dropped: `:: (load 8)` - MIR blocks can reference IR blocks for debug printing, profile information, - or debug locations. Example: `bb.42.myblock` in MIR references the IR block - `myblock`. It is usually possible to drop the `.myblock` reference and simply - use `bb.42`. + or debug locations. Example: ``bb.42.myblock`` in MIR references the IR block + ``myblock``. It is usually possible to drop the ``.myblock`` reference and simply + use ``bb.42``. - If there are no memory operands or blocks referencing the IR, then the IR function can be replaced by a parameterless dummy function like - `define @func() { ret void }`. + ``define @func() { ret void }``. - It is possible to drop the whole IR section of the MIR file if it only - contains dummy functions (see above). The .mir loader will create the + contains dummy functions (see above). The ``.mir`` loader will create the IR functions automatically in this case. .. _limitations: @@ -131,7 +131,7 @@ Tests are more accessible and future proof when simplified: Limitations ----------- -Currently the MIR format has several limitations in terms of which state it +Currently, the MIR format has several limitations in terms of which state it can serialize: - The target-specific state in the target-specific ``MachineFunctionInfo`` @@ -150,7 +150,7 @@ These limitations impose restrictions on what you can test with the MIR format. For now, tests that would like to test some behaviour that depends on the state of temporary or local ``MCSymbol`` operands or the exception handling state in MMI, can't use the MIR format. As well as that, tests that test some behaviour -that depends on the state of the target specific ``MachineFunctionInfo`` or +that depends on the state of the target-specific ``MachineFunctionInfo`` or ``MachineConstantPoolValue`` subclasses can't use the MIR format at the moment. High Level Structure @@ -286,7 +286,7 @@ Example: Successors ^^^^^^^^^^ -The machine basic block's successors have to be specified before any of the +The machine basic block's successors must be specified before any of the instructions: .. code-block:: text @@ -489,13 +489,13 @@ In case this is true, the Machine Operand is printed according to the target. For example: -In AArch64RegisterInfo.td: +In ``AArch64RegisterInfo.td``: .. code-block:: text def sub_32 : SubRegIndex<32>; -If the third operand is an immediate with the value ``15`` (target-dependent +If the third operand is an immediate with the value ``15`` (a target-dependent value), based on the instruction's opcode and the operand's index the operand will be printed as ``%subreg.sub_32``: @@ -503,7 +503,7 @@ will be printed as ``%subreg.sub_32``: %1:gpr64 = SUBREG_TO_REG 0, %0, %subreg.sub_32 -For integers > 64 bits, we use a special machine operand, ``MO_CImmediate``, +For integers larger than 64 bits, we use a special machine operand, ``MO_CImmediate``, which stores the immediate in a ``ConstantInt`` using an ``APInt`` (LLVM's arbitrary-precision integers). @@ -552,7 +552,7 @@ corresponding internal ``llvm::RegState`` representation: * - ``implicit`` - ``RegState::Implicit`` - - Not emitted register (e.g. carry, or temporary result). + - Not emitted register (e.g., carry, or temporary result). * - ``implicit-def`` - ``RegState::ImplicitDefine`` @@ -625,7 +625,7 @@ For a CPI with the index 0 and offset -12: %1:gr64 = MOV64ri %const.0 - 12 -A constant pool entry is bound to a LLVM IR ``Constant`` or a target-specific +A constant pool entry is bound to an LLVM IR ``Constant`` or a target-specific ``MachineConstantPoolValue``. When serializing all the function's constants, the following format is used: @@ -670,12 +670,12 @@ a global value operand named ``G``: $rax = MOV64rm $rip, 1, _, @G, _ -The named global values are represented using an identifier with the '@' prefix. +The named global values are represented using an identifier with the ``@`` prefix. If the identifier doesn't match the regular expression -`[-a-zA-Z$._][-a-zA-Z$._0-9]*`, then this identifier must be quoted. +``[-a-zA-Z$._][-a-zA-Z$._0-9]*``, then this identifier must be quoted. The unnamed global values are represented using an unsigned numeric value with -the '@' prefix, like in the following examples: ``@0``, ``@989``. +the ``@`` prefix, as in the following examples: ``@0``, ``@989``. Target-dependent Index Operands ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -741,7 +741,7 @@ Example: MCSymbol Operands ^^^^^^^^^^^^^^^^^ -A MCSymbol operand holds a pointer to a ``MCSymbol``. For the limitations +An ``MCSymbol`` operand holds a pointer to an ``MCSymbol``. For the limitations of this operand in MIR, see :ref:`limitations <limitations>`. The syntax is: @@ -825,7 +825,7 @@ Comments ^^^^^^^^ Machine operands can have C/C++ style comments, which are annotations enclosed -between ``/*`` and ``*/`` to improve readability of e.g. immediate operands. +between ``/*`` and ``*/`` to improve readability of e.g., immediate operands. In the example below, ARM instructions EOR and BCC and immediate operands ``14`` and ``0`` have been annotated with their condition codes (CC) definitions, i.e. the ``always`` and ``eq`` condition codes: @@ -920,7 +920,7 @@ Instruction referencing locations This experimental feature aims to separate the specification of variable *values* from the program point where a variable takes on that value. Changes -in variable value occur in the same manner as ``DBG_VALUE`` meta instructions +in a variable value occur in the same manner as ``DBG_VALUE`` meta instructions but using ``DBG_INSTR_REF``. Variable values are identified by a pair of instruction number and operand number. Consider the example below: diff --git a/llvm/docs/ProgrammersManual.rst b/llvm/docs/ProgrammersManual.rst index d99b584..270a635 100644 --- a/llvm/docs/ProgrammersManual.rst +++ b/llvm/docs/ProgrammersManual.rst @@ -113,7 +113,7 @@ rarely have to include this file directly). ``isa<>``: The ``isa<>`` operator works exactly like the Java "``instanceof``" operator. - It returns true or false depending on whether a reference or pointer points to + It returns ``true`` or ``false`` depending on whether a reference or pointer points to an instance of the specified class. This can be very useful for constraint checking of various sorts (example below). @@ -167,7 +167,7 @@ rarely have to include this file directly). ``isa_and_present<>``: The ``isa_and_present<>`` operator works just like the ``isa<>`` operator, except that it allows for a null pointer as an argument (which it then - returns false). This can sometimes be useful, allowing you to combine several + returns ``false``). This can sometimes be useful, allowing you to combine several null checks into one. ``cast_if_present<>``: @@ -402,7 +402,7 @@ doxygen documentation or by looking at the unit test suite. Error handling -------------- -Proper error handling helps us identify bugs in our code, and helps end-users +Proper error handling helps us identify bugs in our code, and helps end users understand errors in their tool usage. Errors fall into two broad categories: *programmatic* and *recoverable*, with different strategies for handling and reporting. @@ -449,10 +449,10 @@ violations even in builds that do not enable assertions: Recoverable Errors ^^^^^^^^^^^^^^^^^^ -Recoverable errors represent an error in the program's environment, for example +Recoverable errors represent an error in the program's environment, for example, a resource failure (a missing file, a dropped network connection, etc.), or malformed input. These errors should be detected and communicated to a level of -the program where they can be handled appropriately. Handling the error may be +the program that can handle them appropriately. Handling the error may be as simple as reporting the issue to the user, or it may involve attempts at recovery. @@ -668,7 +668,7 @@ Since the list of handlers passed to ``handleErrors`` may not cover every error type that can occur, the ``handleErrors`` function also returns an Error value that must be checked or propagated. If the error value that is passed to ``handleErrors`` does not match any of the handlers it will be returned from -handleErrors. Idiomatic use of ``handleErrors`` thus looks like: +``handleErrors``. Idiomatic use of ``handleErrors`` thus looks like: .. code-block:: c++ @@ -683,18 +683,18 @@ handleErrors. Idiomatic use of ``handleErrors`` thus looks like: })) return Err; -In cases where you truly know that the handler list is exhaustive the +In cases where you truly know that the handler list is exhaustive, the ``handleAllErrors`` function can be used instead. This is identical to ``handleErrors`` except that it will terminate the program if an unhandled error is passed in, and can therefore return void. The ``handleAllErrors`` function should generally be avoided: the introduction of a new error type elsewhere in the program can easily turn a formerly exhaustive list of errors into a non-exhaustive list, risking unexpected program termination. Where -possible, use handleErrors and propagate unknown errors up the stack instead. +possible, use ``handleErrors`` and propagate unknown errors up the stack instead. For tool code, where errors can be handled by printing an error message then exiting with an error code, the :ref:`ExitOnError <err_exitonerr>` utility -may be a better choice than handleErrors, as it simplifies control flow when +may be a better choice than ``handleErrors``, as it simplifies control flow when calling fallible functions. In situations where it is known that a particular call to a fallible function @@ -706,9 +706,9 @@ simplifying control flow. StringError """"""""""" -Many kinds of errors have no recovery strategy, the only action that can be +Many kinds of errors have no recovery strategy; the only action that can be taken is to report them to the user so that the user can attempt to fix the -environment. In this case representing the error as a string makes perfect +environment. In this case, representing the error as a string makes perfect sense. LLVM provides the ``StringError`` class for this purpose. It takes two arguments: A string error message, and an equivalent ``std::error_code`` for interoperability. It also provides a ``createStringError`` function to simplify @@ -721,7 +721,7 @@ common usage of this class: createStringError(errc::executable_format_error, "Bad executable"); If you're certain that the error you're building will never need to be converted -to a ``std::error_code`` you can use the ``inconvertibleErrorCode()`` function: +to a ``std::error_code``, you can use the ``inconvertibleErrorCode()`` function: .. code-block:: c++ @@ -791,18 +791,18 @@ actually recognises three different forms of handler signature: Error(std::unique_ptr<UserDefinedError> E); Any error returned from a handler will be returned from the ``handleErrors`` -function so that it can be handled itself, or propagated up the stack. +function so that it can be handled itself or propagated up the stack. .. _err_exitonerr: Using ExitOnError to simplify tool code """"""""""""""""""""""""""""""""""""""" -Library code should never call ``exit`` for a recoverable error, however in tool +Library code should never call ``exit`` for a recoverable error; however, in tool code (especially command line tools) this can be a reasonable approach. Calling ``exit`` upon encountering an error dramatically simplifies control flow as the error no longer needs to be propagated up the stack. This allows code to be -written in straight-line style, as long as each fallible call is wrapped in a +written in a straight-line style, as long as each fallible call is wrapped in a check and call to exit. The ``ExitOnError`` class supports this pattern by providing call operators that inspect ``Error`` values, stripping the error away in the success case and logging to ``stderr`` then exiting in the failure case. @@ -827,7 +827,7 @@ turning them into non-failing calls: } On failure, the error's log message will be written to ``stderr``, optionally -preceded by a string "banner" that can be set by calling the setBanner method. A +preceded by a string "banner" that can be set by calling the ``setBanner`` method. A mapping can also be supplied from ``Error`` values to exit codes using the ``setExitCodeMapper`` method: @@ -854,8 +854,8 @@ Some functions may only fail for a subset of their inputs, so calls using known safe inputs can be assumed to succeed. The cantFail functions encapsulate this by wrapping an assertion that their -argument is a success value and, in the case of Expected<T>, unwrapping the -T value: +argument is a success value and, in the case of ``Expected<T>``, unwrapping the +``T`` value: .. code-block:: c++ @@ -868,16 +868,16 @@ T value: ... } -Like the ExitOnError utility, cantFail simplifies control flow. Their treatment +Like the ExitOnError utility, ``cantFail`` simplifies control flow. Their treatment of error cases is very different, however: Where ExitOnError is guaranteed to -terminate the program on an error input, cantFail simply asserts that the result +terminate the program on an error input, ``cantFail`` simply asserts that the result is success. In debug builds this will result in an assertion failure if an error -is encountered. In release builds, the behavior of cantFail for failure values is -undefined. As such, care must be taken in the use of cantFail: clients must be -certain that a cantFail wrapped call really can not fail with the given +is encountered. In release builds, the behavior of ``cantFail`` for failure values is +undefined. As such, care must be taken in the use of ``cantFail``: clients must be +certain that a ``cantFail`` wrapped call really can not fail with the given arguments. -Use of the cantFail functions should be rare in library code, but they are +Use of the ``cantFail`` functions should be rare in library code, but they are likely to be of more use in tool and unit-test code where inputs and/or mocked-up classes or functions may be known to be safe. @@ -979,7 +979,7 @@ completing the walk over the archive they could use the ``joinErrors`` utility: } The ``joinErrors`` routine builds a special error type called ``ErrorList``, -which holds a list of user defined errors. The ``handleErrors`` routine +which holds a list of user-defined errors. The ``handleErrors`` routine recognizes this type and will attempt to handle each of the contained errors in order. If all contained errors can be handled, ``handleErrors`` will return ``Error::success()``; otherwise, ``handleErrors`` will concatenate the remaining @@ -1043,7 +1043,7 @@ compared to ``end`` and found to be unequal (in particular, this marks the error as checked throughout the body of a range-based for loop), enabling early exit from the loop without redundant error checking. -Instances of the fallible iterator interface (e.g. FallibleChildIterator above) +Instances of the fallible iterator interface (e.g., FallibleChildIterator above) are wrapped using the ``make_fallible_itr`` and ``make_fallible_end`` functions. E.g.: @@ -1146,7 +1146,7 @@ be passed by value. The ``LDBG`` and ``LLVM_DEBUG()`` macros and ``-debug`` option -------------------------------------------------------------- -Often when working on your pass you will put a bunch of debugging printouts and +Often, when working on your pass, you will put a bunch of debugging printouts and other code into your pass. After you get it working, you want to remove it, but you may need it again in the future (to work out new bugs that you run across). @@ -1183,7 +1183,7 @@ The debug output can be enabled by passing the ``-debug`` command line argument. $ opt < a.bc > /dev/null -mypass -debug [my-pass MyPass.cpp:123 2] I am here! -While `LDBG()` is useful to add debug output to your code, there are cases +While ``LDBG()`` is useful to add debug output to your code, there are cases where you may need to guard a block of code with a debug check. The ``llvm/Support/Debug.h`` (`doxygen <https://llvm.org/doxygen/Debug_8h_source.html>`__) file provides a macro named @@ -1220,7 +1220,7 @@ with ``-debug``. Fine grained debug info with ``DEBUG_TYPE`` and the ``-debug-only`` option ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Sometimes you may find yourself in a situation where enabling ``-debug`` just +Sometimes, you may find yourself in a situation where enabling ``-debug`` just turns on **too much** information (such as when working on the code generator). If you want to enable debug information with more fine-grained control, you can control the debug type and level with associate with each logging statement @@ -1389,7 +1389,7 @@ maintainable and useful. Adding debug counters to aid in debugging your code --------------------------------------------------- -Sometimes, when writing new passes, or trying to track down bugs, it +Sometimes, when writing new passes or trying to track down bugs, it is useful to be able to control whether certain things in your pass happen or not. For example, there are times the minimization tooling can only easily give you large testcases. You would like to narrow @@ -1640,7 +1640,7 @@ dynamically smaller than N, no malloc is performed. This can be a big win in cases where the malloc/free call is far more expensive than the code that fiddles around with the elements. -This is good for vectors that are "usually small" (e.g. the number of +This is good for vectors that are "usually small" (e.g., the number of predecessors/successors of a block is usually less than 8). On the other hand, this makes the size of the ``SmallVector`` itself large, so you don't want to allocate lots of them (doing so will waste a lot of space). As such, @@ -1684,7 +1684,7 @@ to keep ``sizeof(SmallVector<T>)`` around 64 bytes). .. code-block:: c++ - // DISCOURAGED: Clients cannot pass e.g. raw arrays. + // DISCOURAGED: Clients cannot pass e.g., raw arrays. hardcodedContiguousStorage(const SmallVectorImpl<Foo> &In); // ENCOURAGED: Clients can pass any contiguous storage of Foo. allowsAnyContiguousStorage(ArrayRef<Foo> In); @@ -1695,7 +1695,7 @@ to keep ``sizeof(SmallVector<T>)`` around 64 bytes). allowsAnyContiguousStorage(Vec); // Works. } - // DISCOURAGED: Clients cannot pass e.g. SmallVector<Foo, 8>. + // DISCOURAGED: Clients cannot pass e.g., SmallVector<Foo, 8>. hardcodedSmallSize(SmallVector<Foo, 2> &Out); // ENCOURAGED: Clients can pass any SmallVector<Foo, N>. allowsAnySmallSize(SmallVectorImpl<Foo> &Out); @@ -1729,17 +1729,17 @@ 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 -pointer per page might become too high) and not too big (otherwise the memory +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). Moreover, while retaining the order of the elements based on their insertion index, like a vector, iterating over the elements via ``begin()`` and ``end()`` -is not provided in the API, due to the fact accessing the elements in order +is not provided in the API, due to the fact that accessing the elements in order would allocate all the iterated pages, defeating memory savings and the purpose of the ``PagedVector``. -Finally a ``materialized_begin()`` and ``materialized_end`` iterators are +Finally, ``materialized_begin()`` and ``materialized_end`` iterators are provided to access the elements associated to the accessed pages, which could speed up operations that need to iterate over initialized elements in a non-ordered manner. @@ -1782,9 +1782,9 @@ loop. ^^^^^^^ ``std::deque`` is, in some senses, a generalized version of ``std::vector``. -Like ``std::vector``, it provides constant time random access and other similar +Like ``std::vector``, it provides constant-time random access and other similar properties, but it also provides efficient access to the front of the list. It -does not guarantee continuity of elements within memory. +does not guarantee the continuity of elements within memory. In exchange for this extra flexibility, ``std::deque`` has significantly higher constant factor costs than ``std::vector``. If possible, use ``std::vector`` or @@ -1843,7 +1843,7 @@ Related classes of interest are explained in the following subsections: llvm/ADT/PackedVector.h ^^^^^^^^^^^^^^^^^^^^^^^ -Useful for storing a vector of values using only a few number of bits for each +Useful for storing a vector of values using only a few bits for each value. Apart from the standard operations of a vector-like container, it can also perform an 'or' set operation. @@ -1901,13 +1901,13 @@ non-empty ``ilist``\ s. The only sensible solution to this problem is to allocate a so-called *sentinel* along with the intrusive list, which serves as the ``end`` iterator, providing -the back-link to the last element. However conforming to the C++ convention it +the back-link to the last element. However, conforming to the C++ convention it is illegal to ``operator++`` beyond the sentinel and it also must not be dereferenced. These constraints allow for some implementation freedom to the ``ilist`` how to allocate and store the sentinel. The corresponding policy is dictated by -``ilist_traits<T>``. By default a ``T`` gets heap-allocated whenever the need +``ilist_traits<T>``. By default, a ``T`` gets heap-allocated whenever the need for a sentinel arises. While the default policy is sufficient in most cases, it may break down when @@ -1941,7 +1941,7 @@ String-like containers There are a variety of ways to pass around and use strings in C and C++, and LLVM adds a few new options to choose from. Pick the first option on this list -that will do what you need, they are ordered according to their relative cost. +that will do what you need; they are ordered according to their relative cost. Note that it is generally preferred to *not* pass strings around as ``const char*``'s. These have a number of problems, including the fact that they @@ -1973,12 +1973,12 @@ either because they are C string literals, ``std::string``, a C array, or a ``StringRef`` has a few major limitations which make more powerful string containers useful: -#. You cannot directly convert a ``StringRef`` to a 'const char*' because there is +#. You cannot directly convert a ``StringRef`` to a ``const char*`` because there is no way to add a trailing nul (unlike the ``.c_str()`` method on various stronger classes). #. ``StringRef`` doesn't own or keep alive the underlying string bytes. - As such it can easily lead to dangling pointers, and is not suitable for + As such, it can easily lead to dangling pointers, and is not suitable for embedding in datastructures in most cases (instead, use an ``std::string`` or something like that). @@ -2064,7 +2064,7 @@ so it can be embedded into heap data structures and returned by-value. On the other hand, ``std::string`` is highly inefficient for inline editing (e.g. concatenating a bunch of stuff together) and because it is provided by the standard library, its performance characteristics depend a lot of the host -standard library (e.g. libc++ and MSVC provide a highly optimized string class, +standard library (e.g., libc++ and MSVC provide a highly optimized string class, GCC contains a really slow implementation). The major disadvantage of ``std::string`` is that almost every operation that makes @@ -2198,7 +2198,7 @@ physical registers, virtual registers, or numbered basic blocks. ``SparseMultiSet`` is useful for algorithms that need very fast clear/find/insert/erase of the entire collection, and iteration over sets of elements sharing a key. It is often a more efficient choice than using composite -data structures (e.g. vector-of-vectors, map-of-vectors). It is not intended for +data structures (e.g., vector-of-vectors, map-of-vectors). It is not intended for building composite data structures. .. _dss_FoldingSet: @@ -2268,7 +2268,7 @@ 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 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 +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. @@ -2473,7 +2473,7 @@ pair in the map, etc. ``std::map`` is most useful when your keys or values are very large, if you need to iterate over the collection in sorted order, or if you need stable iterators -into the map (i.e. they don't get invalidated if an insertion or deletion of +into the map (i.e., they don't get invalidated if an insertion or deletion of another element takes place). .. _dss_mapvector: @@ -2542,7 +2542,7 @@ There are several bit storage containers, and choosing when to use each is relatively straightforward. One additional option is ``std::vector<bool>``: we discourage its use for two -reasons 1) the implementation in many common compilers (e.g. commonly +reasons 1) the implementation in many common compilers (e.g., commonly available versions of GCC) is extremely inefficient and 2) the C++ standards committee is likely to deprecate this container and/or change it significantly somehow. In any case, please don't use it. @@ -2557,7 +2557,7 @@ 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 -the number of set bits to be high (i.e. a dense set). +the number of set bits to be high (i.e., a dense set). .. _dss_smallbitvector: @@ -3305,7 +3305,7 @@ naming value definitions. The symbol table can provide a name for any Value_. Note that the ``SymbolTable`` class should not be directly accessed by most clients. It should only be used when iteration over the symbol table names themselves are required, which is very special purpose. Note that not all LLVM -Value_\ s have names, and those without names (i.e. they have an empty name) do +Value_\ s have names, and those without names (i.e., they have an empty name) do not exist in the symbol table. Symbol tables support iteration over the values in the symbol table with @@ -3871,7 +3871,7 @@ Important Public Members of the ``Instruction`` class * ``bool mayWriteToMemory()`` - Returns true if the instruction writes to memory, i.e. it is a ``call``, + Returns true if the instruction writes to memory, i.e., it is a ``call``, ``free``, ``invoke``, or ``store``. * ``unsigned getOpcode()`` @@ -3881,7 +3881,7 @@ Important Public Members of the ``Instruction`` class * ``Instruction *clone() const`` Returns another instance of the specified instruction, identical in all ways - to the original except that the instruction has no parent (i.e. it's not + to the original except that the instruction has no parent (i.e., it's not embedded into a BasicBlock_), and it has no name. .. _Constant: diff --git a/llvm/docs/ReleaseNotes.md b/llvm/docs/ReleaseNotes.md index 49158fb..bfe6827 100644 --- a/llvm/docs/ReleaseNotes.md +++ b/llvm/docs/ReleaseNotes.md @@ -180,6 +180,10 @@ Changes to the LLVM tools * Some code paths for supporting Python 2.7 in `llvm-lit` have been removed. * Support for `%T` in lit has been removed. +* `llvm-config` gained a new flag `--quote-paths` which quotes and escapes paths + emitted on stdout, to account for spaces or other special characters in path. + (`#97305 <https://github.com/llvm/llvm-project/pull/97305>`_). + Changes to LLDB --------------------------------- |