diff options
Diffstat (limited to 'llvm/docs')
| -rw-r--r-- | llvm/docs/CommandGuide/llvm-ir2vec.rst | 120 | ||||
| -rw-r--r-- | llvm/docs/Coroutines.rst | 30 | ||||
| -rw-r--r-- | llvm/docs/LangRef.rst | 106 | ||||
| -rw-r--r-- | llvm/docs/ProgrammersManual.rst | 82 | ||||
| -rw-r--r-- | llvm/docs/RISCVUsage.rst | 2 | ||||
| -rw-r--r-- | llvm/docs/TestingGuide.rst | 110 |
6 files changed, 273 insertions, 177 deletions
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/Coroutines.rst b/llvm/docs/Coroutines.rst index 7472c68..dde73c9 100644 --- a/llvm/docs/Coroutines.rst +++ b/llvm/docs/Coroutines.rst @@ -37,7 +37,7 @@ then destroy it: .. _coroutine frame: -In addition to the function stack frame which exists when a coroutine is +In addition to the function stack frame, which exists when a coroutine is executing, there is an additional region of storage that contains objects that keep the coroutine state when a coroutine is suspended. This region of storage is called the **coroutine frame**. It is created when a coroutine is called @@ -145,7 +145,7 @@ lowerings: yielded values. The coroutine indicates that it has run to completion by returning - a null continuation pointer. Any yielded values will be `undef` + a null continuation pointer. Any yielded values will be `undef` and should be ignored. - In yield-once returned-continuation lowering, the coroutine must @@ -159,7 +159,7 @@ passed to the `coro.id` intrinsic, which guarantees a certain size and alignment statically. The same buffer must be passed to the continuation function(s). The coroutine will allocate memory if the buffer is insufficient, in which case it will need to store at -least that pointer in the buffer; therefore the buffer must always +least that pointer in the buffer; therefore, the buffer must always be at least pointer-sized. How the coroutine uses the buffer may vary between suspend points. @@ -182,7 +182,7 @@ handling of control-flow must be handled explicitly by the frontend. In this lowering, a coroutine is assumed to take the current `async context` as one of its arguments (the argument position is determined by `llvm.coro.id.async`). It is used to marshal arguments and return values of the -coroutine. Therefore an async coroutine returns `void`. +coroutine. Therefore, an async coroutine returns `void`. .. code-block:: llvm @@ -321,7 +321,7 @@ The `cleanup` block destroys the coroutine frame. The `coro.free`_ intrinsic, given the coroutine handle, returns a pointer of the memory block to be freed or `null` if the coroutine frame was not allocated dynamically. The `cleanup` block is entered when coroutine runs to completion by itself or destroyed via -call to the `coro.destroy`_ intrinsic. +a call to the `coro.destroy`_ intrinsic. The `suspend` block contains code to be executed when coroutine runs to completion or suspended. The `coro.end`_ intrinsic marks the point where @@ -337,7 +337,7 @@ Coroutine Transformation ------------------------ One of the steps of coroutine lowering is building the coroutine frame. The -def-use chains are analyzed to determine which objects need be kept alive across +def-use chains are analyzed to determine which objects need to be kept alive across suspend points. In the coroutine shown in the previous section, use of virtual register `%inc` is separated from the definition by a suspend point, therefore, it cannot reside on the stack frame since the latter goes away once the coroutine @@ -532,7 +532,7 @@ as follows: ret void } -If different cleanup code needs to get executed for different suspend points, +If different cleanup code needs to be executed for different suspend points, a similar switch will be in the `f.destroy` function. .. note :: @@ -740,7 +740,7 @@ looks like this: <SUSPEND final=true> // injected final suspend point } -and python iterator `__next__` would look like: +and Python iterator `__next__` would look like: .. code-block:: c++ @@ -829,7 +829,7 @@ A swifterror alloca or parameter can only be loaded, stored, or passed as a swif These rules, not coincidentally, mean that you can always perfectly model the data flow in the alloca, and LLVM CodeGen actually has to do that in order to emit code. For coroutine lowering the default treatment of allocas breaks those rules — splitting will try to replace the alloca with an entry in the coro frame, which can lead to trying to pass that as a swifterror argument. -To pass a swifterror argument in a split function, we need to still have the alloca around; but we also potentially need the coro frame slot, since useful data can (in theory) be stored in the swifterror alloca slot across suspensions in the presplit coroutine. +To pass a swifterror argument in a split function, we need to still have the alloca around, but we also potentially need the coro frame slot, since useful data can (in theory) be stored in the swifterror alloca slot across suspensions in the presplit coroutine. When split a coroutine it is consequently necessary to keep both the frame slot as well as the alloca itself and then keep them in sync. Intrinsics @@ -965,7 +965,7 @@ Semantics: Using this intrinsic on a coroutine that does not have a coroutine promise leads to undefined behavior. It is possible to read and modify coroutine promise of the coroutine which is currently executing. The coroutine author and -a coroutine user are responsible to makes sure there is no data races. +a coroutine user are responsible for ensuring no data races. Example: """""""" @@ -1181,7 +1181,7 @@ Overview: """"""""" The '``llvm.coro.alloc``' intrinsic returns `true` if dynamic allocation is -required to obtain a memory for the coroutine frame and `false` otherwise. +required to obtain memory for the coroutine frame and `false` otherwise. This is not supported for returned-continuation coroutines. Arguments: @@ -1628,7 +1628,7 @@ The second argument should be `true` if this coro.end is in the block that is part of the unwind sequence leaving the coroutine body due to an exception and `false` otherwise. -The third argument if present should specify a function to be called. +The third argument, if present, should specify a function to be called. If the third argument is present, the remaining arguments are the arguments to the function call. @@ -1700,7 +1700,7 @@ Semantics: If a coroutine that was suspended at the suspend point marked by this intrinsic is resumed via `coro.resume`_ the control will transfer to the basic block of the 0-case. If it is resumed via `coro.destroy`_, it will proceed to the -basic block indicated by the 1-case. To suspend, coroutine proceed to the +basic block indicated by the 1-case. To suspend, coroutine proceeds to the default label. If suspend intrinsic is marked as final, it can consider the `true` branch @@ -1717,7 +1717,7 @@ unreachable and can perform optimizations that can take advantage of that fact. Overview: """"""""" -The '``llvm.coro.save``' marks the point where a coroutine need to update its +The '``llvm.coro.save``' marks the point where a coroutine needs to update its state to prepare for resumption to be considered suspended (and thus eligible for resumption). It is illegal to merge two '``llvm.coro.save``' calls unless their '``llvm.coro.suspend``' users are also merged. So '``llvm.coro.save``' is currently @@ -1793,7 +1793,7 @@ The fourth to six argument are the arguments for the third argument. Semantics: """""""""" -The result of the intrinsic are mapped to the arguments of the resume function. +The results of the intrinsic are mapped to the arguments of the resume function. Execution is suspended at this intrinsic and resumed when the resume function is called. diff --git a/llvm/docs/LangRef.rst b/llvm/docs/LangRef.rst index 2a8f0af..3a3a74f 100644 --- a/llvm/docs/LangRef.rst +++ b/llvm/docs/LangRef.rst @@ -24243,6 +24243,92 @@ Examples: %also.r = call <8 x i8> @llvm.masked.load.v8i8.p0(ptr %ptr, i32 2, <8 x i1> %mask, <8 x i8> poison) +.. _int_vp_load_ff: + +'``llvm.vp.load_ff``' Intrinsic +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Syntax: +""""""" +This is an overloaded intrinsic. + +:: + + declare {<4 x float>, i32} @llvm.vp.load.ff.v4f32.p0(ptr %ptr, <4 x i1> %mask, i32 %evl) + declare {<vscale x 2 x i16>, i32} @llvm.vp.load.ff.nxv2i16.p0(ptr %ptr, <vscale x 2 x i1> %mask, i32 %evl) + declare {<8 x float>, i32} @llvm.vp.load.ff.v8f32.p1(ptr addrspace(1) %ptr, <8 x i1> %mask, i32 %evl) + declare {<vscale x 1 x i64>, i32} @llvm.vp.load.ff.nxv1i64.p6(ptr addrspace(6) %ptr, <vscale x 1 x i1> %mask, i32 %evl) + +Overview: +""""""""" + +The '``llvm.vp.load.ff.*``' intrinsic is similar to +'``llvm.vp.load.*``', but will not trap if there are not ``evl`` readable +lanes at the pointer. '``ff``' stands for fault-first or fault-only-first. + +Arguments: +"""""""""" + +The first argument is the base pointer for the load. The second argument is a +vector of boolean values with the same number of elements as the first return +type. The third is the explicit vector length of the operation. The first +return type and underlying type of the base pointer are the same vector types. + +The :ref:`align <attr_align>` parameter attribute can be provided for the first +argument. + +Semantics: +"""""""""" + +The '``llvm.vp.load.ff``' is designed for reading vector lanes in a single +IR operation where the number of lanes that can be read is not known and can +only be determined by looking at the data. This is useful for vectorizing +strcmp or strlen like loops where the data contains a null terminator. Some +targets have a fault-only-first load instruction that this intrinsic can be +lowered to. Other targets may support this intrinsic differently, for example by +lowering to a single scalar load guarded by ``evl!=0`` and ``mask[0]==1`` and +indicating only 1 lane could be read. + +Like '``llvm.vp.load``', this intrinsic reads memory based on a ``mask`` and an +``evl``. If ``evl`` is non-zero and the first lane is masked-on, then the +first lane of the vector needs to be inbounds of an allocation. The remaining +masked-on lanes with index less than ``evl`` do not need to be inbounds of +an the same allocation or any allocation. + +The second return value from the intrinsic indicates the index of the first +lane that could not be read for some reason or ``evl`` if all lanes could be +be read. Lanes at this index or higher in the first return value are +:ref:`poison value <poisonvalues>`. If ``evl`` is non-zero, the result in the +second return value must be at least 1, even if the first lane is masked-off. + +The second result is usually less than ``evl`` when an exception would occur +for reading that lane, but it can be reduced for any reason. This facilitates +emulating this intrinsic when the hardware only supports narrower vector +types natively or when when hardware does not support fault-only-first loads. + +Masked-on lanes that are not inbounds of the allocation that contains the first +lane are :ref:`poison value <poisonvalues>`. There should be a marker in the +allocation that indicates where valid data stops such as a null terminator. The +terminator should be checked for after calling this intrinsic to prevent using +any lanes past the terminator. Even if second return value is less than +``evl``, the terminator value may not have been read. + +This intrinsic will typically be called in a loop until a terminator is +found. The second result should be used to indicates how many elements are +valid to look for the null terminator. If the terminator is not found, the +pointer should be advanced by the number of elements in the second result and +the intrinsic called again. + +The default alignment is taken as the ABI alignment of the first return +type as specified by the :ref:`datalayout string<langref_datalayout>`. + +Examples: +""""""""" + +.. code-block:: text + + %r = call {<8 x i8>, i32} @llvm.vp.load.ff.v8i8.p0(ptr align 2 %ptr, <8 x i1> %mask, i32 %evl) + .. _int_vp_store: '``llvm.vp.store``' Intrinsic @@ -26658,14 +26744,17 @@ Arguments: The first argument is a constant integer, which is ignored and will be removed in the future. -The second argument is a pointer to an ``alloca`` instruction. +The second argument is either a pointer to an ``alloca`` instruction or +a ``poison`` value. Semantics: """""""""" -The stack-allocated object that ``ptr`` points to is initially marked as dead. -After '``llvm.lifetime.start``', the stack object is marked as alive and has an -uninitialized value. +If ``ptr`` is a ``poison`` value, the intrinsic has no effect. + +Otherwise, the stack-allocated object that ``ptr`` points to is initially +marked as dead. After '``llvm.lifetime.start``', the stack object is marked as +alive and has an uninitialized value. The stack object is marked as dead when either :ref:`llvm.lifetime.end <int_lifeend>` to the alloca is executed or the function returns. @@ -26699,13 +26788,16 @@ Arguments: The first argument is a constant integer, which is ignored and will be removed in the future. -The second argument is a pointer to an ``alloca`` instruction. +The second argument is either a pointer to an ``alloca`` instruction or +a ``poison`` value. Semantics: """""""""" -The stack-allocated object that ``ptr`` points to becomes dead after the call -to this intrinsic. +If ``ptr`` is a ``poison`` value, the intrinsic has no effect. + +Otherwise, the stack-allocated object that ``ptr`` points to becomes dead after +the call to this intrinsic. Calling ``llvm.lifetime.end`` on an already dead alloca is no-op. 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/RISCVUsage.rst b/llvm/docs/RISCVUsage.rst index 9f6ac55..a29e06c 100644 --- a/llvm/docs/RISCVUsage.rst +++ b/llvm/docs/RISCVUsage.rst @@ -136,7 +136,7 @@ on support follow. ``Smepmp`` Supported ``Smmpm`` Supported ``Smnpm`` Supported - ``Smrnmi`` Assembly Support + ``Smrnmi`` Supported ``Smstateen`` Assembly Support ``Ssaia`` Supported ``Ssccfg`` Supported diff --git a/llvm/docs/TestingGuide.rst b/llvm/docs/TestingGuide.rst index 76b6b4e..b1819c7 100644 --- a/llvm/docs/TestingGuide.rst +++ b/llvm/docs/TestingGuide.rst @@ -30,9 +30,9 @@ LLVM Testing Infrastructure Organization ======================================== The LLVM testing infrastructure contains three major categories of tests: -unit tests, regression tests and whole programs. The unit tests and regression +unit tests, regression tests, and whole programs. The unit tests and regression tests are contained inside the LLVM repository itself under ``llvm/unittests`` -and ``llvm/test`` respectively and are expected to always pass -- they should be +and ``llvm/test`` respectively and are expected to always pass. They should be run before every commit. The whole programs tests are referred to as the "LLVM test suite" (or @@ -48,7 +48,7 @@ Unit tests Unit tests are written using `Google Test <https://github.com/google/googletest/blob/master/docs/primer.md>`_ and `Google Mock <https://github.com/google/googletest/blob/master/docs/gmock_for_dummies.md>`_ and are located in the ``llvm/unittests`` directory. -In general unit tests are reserved for targeting the support library and other +In general, unit tests are reserved for targeting the support library and other generic data structure, we prefer relying on regression tests for testing transformations and analysis on the IR. @@ -61,7 +61,7 @@ written in depends on the part of LLVM being tested. These tests are driven by the :doc:`Lit <CommandGuide/lit>` testing tool (which is part of LLVM), and are located in the ``llvm/test`` directory. -Typically when a bug is found in LLVM, a regression test containing just +Typically, when a bug is found in LLVM, a regression test containing just enough code to reproduce the problem should be written and placed somewhere underneath this directory. For example, it can be a small piece of LLVM IR distilled from an actual application or benchmark. @@ -82,10 +82,10 @@ for an example of such test. The test suite contains whole programs, which are pieces of code which can be compiled and linked into a stand-alone program that can be -executed. These programs are generally written in high level languages -such as C or C++. +executed. These programs are generally written in high-level languages, +such as C and C++. -These programs are compiled using a user specified compiler and set of +These programs are compiled using a user-specified compiler and set of flags, and then executed to capture the program output and timing information. The output of these programs is compared to a reference output to ensure that the program is being compiled correctly. @@ -103,11 +103,11 @@ See the :doc:`TestSuiteGuide` for details. Debugging Information tests --------------------------- -The test suite contains tests to check quality of debugging information. -The test are written in C based languages or in LLVM assembly language. +The test suite contains tests to check the quality of debugging information. +The tests are written in C based languages or in LLVM assembly language. These tests are compiled and run under a debugger. The debugger output -is checked to validate of debugging information. See README.txt in the +is checked to validate the debugging information. See ``README.txt`` in the test suite for more information. This test suite is located in the ``cross-project-tests/debuginfo-tests`` directory. @@ -126,13 +126,13 @@ and C++ programs. See the :doc:`TestSuiteGuide` for details. Unit and Regression tests ------------------------- -To run all of the LLVM unit tests use the check-llvm-unit target: +To run all of the LLVM unit tests, use the ``check-llvm-unit`` target: .. code-block:: bash % make check-llvm-unit -To run all of the LLVM regression tests use the check-llvm target: +To run all of the LLVM regression tests, use the ``check-llvm`` target: .. code-block:: bash @@ -163,7 +163,7 @@ to enable testing with valgrind and with leak checking enabled. To run individual tests or subsets of tests, you can use the ``llvm-lit`` script which is built as part of LLVM. For example, to run the -``Integer/BitPacked.ll`` test by itself you can run: +``Integer/BitPacked.ll`` test by itself, you can run: .. code-block:: bash @@ -224,35 +224,35 @@ only directories does not need the ``lit.local.cfg`` file. Read the :doc:`Lit documentation <CommandGuide/lit>` for more information. Each test file must contain lines starting with "RUN:" that tell :program:`lit` -how to run it. If there are no RUN lines, :program:`lit` will issue an error +how to run it. If there are no ``RUN`` lines, :program:`lit` will issue an error while running a test. -RUN lines are specified in the comments of the test program using the +``RUN`` lines are specified in the comments of the test program using the keyword ``RUN`` followed by a colon, and lastly the command (pipeline) to execute. Together, these lines form the "script" that :program:`lit` -executes to run the test case. The syntax of the RUN lines is similar to a +executes to run the test case. The syntax of the ``RUN`` lines is similar to a shell's syntax for pipelines including I/O redirection and variable substitution. However, even though these lines may *look* like a shell -script, they are not. RUN lines are interpreted by :program:`lit`. +script, they are not. ``RUN`` lines are interpreted by :program:`lit`. Consequently, the syntax differs from shell in a few ways. You can specify -as many RUN lines as needed. +as many ``RUN`` lines as needed. -:program:`lit` performs substitution on each RUN line to replace LLVM tool names +:program:`lit` performs substitution on each ``RUN`` line to replace LLVM tool names with the full paths to the executable built for each tool (in ``$(LLVM_OBJ_ROOT)/bin``). This ensures that :program:`lit` does not invoke any stray LLVM tools in the user's path during testing. -Each RUN line is executed on its own, distinct from other lines unless -its last character is ``\``. This continuation character causes the RUN -line to be concatenated with the next one. In this way you can build up +Each ``RUN`` line is executed on its own, distinct from other lines unless +its last character is ``\``. This continuation character causes the ``RUN`` +line to be concatenated with the next one. In this way, you can build up long pipelines of commands without making huge line lengths. The lines -ending in ``\`` are concatenated until a RUN line that doesn't end in -``\`` is found. This concatenated set of RUN lines then constitutes one +ending in ``\`` are concatenated until a ``RUN`` line that doesn't end in +``\`` is found. This concatenated set of ``RUN`` lines then constitutes one execution. :program:`lit` will substitute variables and arrange for the pipeline to be executed. If any process in the pipeline fails, the entire line (and test case) fails too. -Below is an example of legal RUN lines in a ``.ll`` file: +Below is an example of legal ``RUN`` lines in a ``.ll`` file: .. code-block:: llvm @@ -260,19 +260,19 @@ Below is an example of legal RUN lines in a ``.ll`` file: ; RUN: llvm-dis < %s.bc-13 > %t2 ; RUN: diff %t1 %t2 -As with a Unix shell, the RUN lines permit pipelines and I/O +As with a Unix shell, the ``RUN`` lines permit pipelines and I/O redirection to be used. There are some quoting rules that you must pay attention to when writing -your RUN lines. In general nothing needs to be quoted. :program:`lit` won't -strip off any quote characters so they will get passed to the invoked program. +your ``RUN`` lines. In general, nothing needs to be quoted. :program:`lit` won't +strip off any quote characters, so they will get passed to the invoked program. To avoid this use curly braces to tell :program:`lit` that it should treat everything enclosed as one value. -In general, you should strive to keep your RUN lines as simple as possible, +In general, you should strive to keep your ``RUN`` lines as simple as possible, using them only to run tools that generate textual output you can then examine. The recommended way to examine output to figure out if the test passes is using -the :doc:`FileCheck tool <CommandGuide/FileCheck>`. *[The usage of grep in RUN +the :doc:`FileCheck tool <CommandGuide/FileCheck>`. *[The usage of grep in ``RUN`` lines is deprecated - please do not send or commit patches that use it.]* Put related tests into a single file rather than having a separate file per @@ -283,11 +283,11 @@ Generating assertions in regression tests ----------------------------------------- Some regression test cases are very large and complex to write/update by hand. -In that case to reduce the human work we can use the scripts available in -llvm/utils/ to generate the assertions. +In that case, to reduce the manual work, we can use the scripts available in +``llvm/utils/`` to generate the assertions. -For example to generate assertions in an :program:`llc`-based test, after -adding one or more RUN lines use: +For example, to generate assertions in an :program:`llc`-based test, after +adding one or more ``RUN`` lines, use: .. code-block:: bash @@ -368,7 +368,7 @@ Best practices for regression tests Extra files ----------- -If your test requires extra files besides the file containing the ``RUN:`` lines +If your test requires extra files besides the file containing the ``RUN:`` lines, and the extra files are small, consider specifying them in the same file and using ``split-file`` to extract them. For example, @@ -442,7 +442,7 @@ Elaborated tests Generally, IR and assembly test files benefit from being cleaned to remove unnecessary details. However, for tests requiring elaborate IR or assembly -files where cleanup is less practical (e.g., large amount of debug information +files where cleanup is less practical (e.g., a large amount of debug information output from Clang), you can include generation instructions within ``split-file`` part called ``gen``. Then, run ``llvm/utils/update_test_body.py`` on the test file to generate the needed @@ -472,7 +472,7 @@ then rewrite the part after ``gen`` with its stdout. For convenience, if the test needs one single assembly file, you can also wrap ``gen`` and its required files with ``.ifdef`` and ``.endif``. Then you can -skip ``split-file`` in RUN lines. +skip ``split-file`` in ``RUN`` lines. .. code-block:: none @@ -521,7 +521,7 @@ utilize ``split-file`` in ``RUN`` lines. Fragile tests ------------- -It is easy to write a fragile test that would fail spuriously if the tool being +It is easy to write a fragile test that could fail spuriously if the tool being tested outputs a full path to the input file. For example, :program:`opt` by default outputs a ``ModuleID``: @@ -552,7 +552,7 @@ default outputs a ``ModuleID``: This test will fail if placed into a ``download`` directory. -To make your tests robust, always use ``opt ... < %s`` in the RUN line. +To make your tests robust, always use ``opt ... < %s`` in the ``RUN`` line. :program:`opt` does not output a ``ModuleID`` when input comes from stdin. Platform-Specific Tests @@ -560,21 +560,21 @@ Platform-Specific Tests Whenever adding tests that require the knowledge of a specific platform, either related to code generated, specific output or back-end features, -you must make sure to isolate the features, so that buildbots that +you must isolate the features, so that buildbots that run on different architectures (and don't even compile all back-ends), don't fail. The first problem is to check for target-specific output, for example sizes of structures, paths and architecture names, for example: -* Tests containing Windows paths will fail on Linux and vice-versa. +* Tests containing Windows paths will fail on Linux and vice versa. * Tests that check for ``x86_64`` somewhere in the text will fail anywhere else. * Tests where the debug information calculates the size of types and structures. -Also, if the test rely on any behaviour that is coded in any back-end, it must +Also, if the test relies on any behaviour that is coded in any back-end, it must go in its own directory. So, for instance, code generator tests for ARM go into ``test/CodeGen/ARM`` and so on. Those directories contain a special -``lit`` configuration file that ensure all tests in that directory will +``lit`` configuration file that ensures all tests in that directory will only run if a specific back-end is compiled and available. For instance, on ``test/CodeGen/ARM``, the ``lit.local.cfg`` is: @@ -622,7 +622,7 @@ with debug builds or on particular platforms. Use ``REQUIRES`` and ``UNSUPPORTED`` to control when the test is enabled. Some tests are expected to fail. For example, there may be a known bug -that the test detect. Use ``XFAIL`` to mark a test as an expected failure. +that the test detects. Use ``XFAIL`` to mark a test as an expected failure. An ``XFAIL`` test will be successful if its execution fails, and will be a failure if its execution succeeds. @@ -645,7 +645,7 @@ list of boolean expressions. The values in each expression may be: expressions can appear inside an identifier, so for example ``he{{l+}}o`` would match ``helo``, ``hello``, ``helllo``, and so on. - The default target triple, preceded by the string ``target=`` (for example, - ``target=x86_64-pc-windows-msvc``). Typically regular expressions are used + ``target=x86_64-pc-windows-msvc``). Typically, regular expressions are used to match parts of the triple (for example, ``target={{.*}}-windows{{.*}}`` to match any Windows target triple). @@ -684,7 +684,7 @@ have different effects. ``UNSUPPORTED`` causes the test to be skipped; this saves execution time, but then you'll never know whether the test actually would start working. Conversely, ``XFAIL`` actually runs the test but expects a failure output, taking extra execution time but alerting you -if/when the test begins to behave correctly (an XPASS test result). You +if/when the test begins to behave correctly (an ``XPASS`` test result). You need to decide which is more appropriate in each case. **Using ``target=...``** @@ -698,7 +698,7 @@ and it's generally a good idea to use a trailing wildcard to allow for unexpected suffixes. Also, it's generally better to write regular expressions that use entire -triple components, than to do something clever to shorten them. For +triple components than to do something clever to shorten them. For example, to match both freebsd and netbsd in an expression, you could write ``target={{.*(free|net)bsd.*}}`` and that would work. However, it would prevent a ``grep freebsd`` from finding this test. Better to use: @@ -708,8 +708,8 @@ prevent a ``grep freebsd`` from finding this test. Better to use: Substitutions ------------- -Besides replacing LLVM tool names the following substitutions are performed in -RUN lines: +Besides replacing LLVM tool names, the following substitutions are performed in +``RUN`` lines: ``%%`` Replaced by a single ``%``. This allows escaping other substitutions. @@ -726,7 +726,7 @@ RUN lines: Example: ``/home/user/llvm/test/MC/ELF`` ``%t`` - File path to a temporary file name that could be used for this test case. + File path to a temporary file name that can be used for this test case. The file name won't conflict with other test cases. You can append to it if you need multiple temporaries. This is useful as the destination of some redirected output. @@ -811,7 +811,7 @@ RUN lines: optional integer offset. These expand only if they appear immediately in ``RUN:``, ``DEFINE:``, and ``REDEFINE:`` directives. Occurrences in substitutions defined elsewhere are never expanded. - For example, this can be used in tests with multiple RUN lines, + For example, this can be used in tests with multiple ``RUN`` lines, which reference the test file's line numbers. **LLVM-specific substitutions:** @@ -988,7 +988,7 @@ directives: - **Substitution value**: The value includes all text from the first non-whitespace character after ``=`` to the last non-whitespace character. If there is no non-whitespace character after ``=``, the value is the empty - string. Escape sequences that can appear in python ``re.sub`` replacement + string. Escape sequences that can appear in Python ``re.sub`` replacement strings are treated as plain text in the value. - **Line continuations**: If the last non-whitespace character on the line after ``:`` is ``\``, then the next directive must use the same directive keyword @@ -1057,7 +1057,7 @@ producing incorrect output. Options ------- -The llvm lit configuration allows to customize some things with user options: +The llvm lit configuration allows some things to be customized with user options: ``llc``, ``opt``, ... Substitute the respective llvm tool name with a custom command line. This @@ -1076,8 +1076,8 @@ The llvm lit configuration allows to customize some things with user options: Other Features -------------- -To make RUN line writing easier, there are several helper programs. These -helpers are in the PATH when running tests, so you can just call them using +To make ``RUN`` line writing easier, several helper programs are available. These +helpers are in the ``PATH`` when running tests, so you can just call them using their name. For example: ``not`` |