diff options
Diffstat (limited to 'clang/docs')
| -rw-r--r-- | clang/docs/ClangOffloadBundler.rst | 38 | ||||
| -rw-r--r-- | clang/docs/LanguageExtensions.rst | 76 | ||||
| -rw-r--r-- | clang/docs/SafeBuffers.rst | 4 |
3 files changed, 59 insertions, 59 deletions
diff --git a/clang/docs/ClangOffloadBundler.rst b/clang/docs/ClangOffloadBundler.rst index 5570dbb..f63037a7 100644 --- a/clang/docs/ClangOffloadBundler.rst +++ b/clang/docs/ClangOffloadBundler.rst @@ -28,7 +28,7 @@ A bundled code object may also be used to bundle just the offloaded code objects, and embedded as data into the host code object. The host compilation includes an ``init`` function that will use the runtime corresponding to the offload kind (see :ref:`clang-offload-kind-table`) to load the offload code -objects appropriate to the devices present when the host program is executed. +objects appropriate for the devices present when the host program is executed. :program:`clang-offload-bundler` is located in `clang/tools/clang-offload-bundler`. @@ -147,7 +147,7 @@ bundle file is: <end> ::== OFFLOAD_BUNDLER_MAGIC_STR__END__ **comment** - The symbol used for starting single-line comment in the file type of + The symbol used for starting a single-line comment in the file type of constituting bundles. E.g. it is ";" for ll ``File Type`` and "#" for "s" ``File Type``. @@ -155,13 +155,13 @@ bundle file is: The :ref:`clang-bundle-entry-id` for the enclosing bundle. **eol** - The end of line character. + The end-of-line character. **bundle** The code object stored in one of the supported text file formats. **OFFLOAD_BUNDLER_MAGIC_STR__** - Magic string that marks the existence of offloading data i.e. + The magic string that marks the existence of offloading data i.e. "__CLANG_OFFLOAD_BUNDLE__". .. _clang-bundled-code-object-layout: @@ -231,7 +231,7 @@ Where: ============= ============================================================== host Host code object. ``clang-offload-bundler`` always includes this entry as the first bundled code object entry. For an - embedded bundled code object this entry is not used by the + embedded bundled code object, this entry is not used by the runtime and so is generally an empty code object. hip Offload code object for the HIP language. Used for all @@ -272,7 +272,7 @@ without differentiation based on offload kind. ``<arch><sub>-<vendor>-<sys>-<env>`` However, in order to standardize outputs for tools that consume bitcode bundles - and to parse target ID containing dashes, the bundler only accepts target + and to parse a target ID containing dashes, the bundler only accepts target triples in the 4-field format: ``<arch><sub>-<vendor>-<sys>-<env>`` @@ -292,7 +292,7 @@ Bundled Code Object Composition * If there is an entry with a target feature specified as *Any*, then all entries must specify that target feature as *Any* for the same processor. -There may be additional target specific restrictions. +There may be additional target-specific restrictions. .. _compatibility-bundle-entry-id: @@ -300,9 +300,9 @@ Compatibility Rules for Bundle Entry ID --------------------------------------- A code object, specified using its Bundle Entry ID, can be loaded and - executed on a target processor, if: + executed on a target processor if: - * Their offload kinds are the same or comptible. + * Their offload kinds are the same or compatible. * Their target triples are compatible. * Their Target IDs are compatible as defined in :ref:`compatibility-target-id`. @@ -331,7 +331,7 @@ Target ID syntax is defined by the following BNF syntax: Where: **processor** - Is a the target specific processor or any alternative processor name. + Is the target-specific processor or any alternative processor name. **target-feature** Is a target feature name that is supported by the processor. Each target @@ -350,7 +350,7 @@ Where: can only be loaded on a processor configured with the target feature on. *Off* - specified by ``-``, indicating the target feature is disabled. A code + Specified by ``-``, indicating the target feature is disabled. A code object compiled with a target ID specifying a target feature off can only be loaded on a processor configured with the target feature off. @@ -360,9 +360,9 @@ Compatibility Rules for Target ID --------------------------------- A code object compiled for a Target ID is considered compatible for a - target, if: + target if: - * Their processor is same. + * Their processor is the same. * Their feature set is compatible as defined above. There are two forms of target ID: @@ -380,10 +380,10 @@ There are two forms of target ID: alphabetic order. Command line tools convert non-canonical form to canonical form. -Target Specific information +Target-Specific information =========================== -Target specific information is available for the following: +Target-specific information is available for the following: *AMD GPU* AMD GPU supports target ID and target features. See `User Guide for AMDGPU Backend @@ -397,7 +397,7 @@ Most other targets do not support target IDs. Archive Unbundling ================== -Unbundling of a heterogeneous device archive (HDA) is done to create device specific +Unbundling of a heterogeneous device archive (HDA) is done to create device-specific archives. HDA is in a format compatible with GNU ``ar`` utility and contains a collection of bundled device binaries where each bundle file will contain device binaries for a host and one or more targets. The output device-specific @@ -469,7 +469,7 @@ compatible with that particular offload target. Compatibility between a device binary in HDA and a target is based on the compatibility between their bundle entry IDs as defined in :ref:`compatibility-bundle-entry-id`. -Following cases may arise during compatibility testing: +The following cases may arise during compatibility testing: * A binary is compatible with one or more targets: Insert the binary into the device-specific archive of each compatible target. @@ -517,7 +517,7 @@ Compression and Decompression ``clang-offload-bundler`` provides features to compress and decompress the full bundle, leveraging inherent redundancies within the bundle entries. Use the -`-compress` command-line option to enable this compression capability. +``-compress`` command-line option to enable this compression capability. The compressed offload bundle begins with a header followed by the compressed binary data: @@ -542,4 +542,4 @@ The compressed offload bundle begins with a header followed by the compressed bi - **Compressed Data**: The actual compressed binary data follows the header. Its size can be inferred from the total size of the file minus the header size. - > **Note**: Version 3 is now the default format. For backward compatibility with older HIP runtimes that support version 2 only, set the environment variable `COMPRESSED_BUNDLE_FORMAT_VERSION=2`. + > **Note**: Version 3 is now the default format. For backward compatibility with older HIP runtimes that support version 2 only, set the environment variable ``COMPRESSED_BUNDLE_FORMAT_VERSION=2``. diff --git a/clang/docs/LanguageExtensions.rst b/clang/docs/LanguageExtensions.rst index bef6e9c1..495f2ab 100644 --- a/clang/docs/LanguageExtensions.rst +++ b/clang/docs/LanguageExtensions.rst @@ -32,7 +32,7 @@ Feature Checking Macros ======================= Language extensions can be very useful, but only if you know you can depend on -them. In order to allow fine-grain features checks, we support three builtin +them. In order to allow fine-grained feature checks, we support three builtin function-like macros. This allows you to directly test for a feature in your code without having to resort to something like autoconf or fragile "compiler version checks". @@ -137,7 +137,7 @@ feature) or 0 if not. They can be used like this: .. _langext-has-feature-back-compat: For backward compatibility, ``__has_feature`` can also be used to test -for support for non-standardized features, i.e. features not prefixed ``c_``, +for support for non-standardized features, i.e., features not prefixed ``c_``, ``cxx_`` or ``objc_``. Another use of ``__has_feature`` is to check for compiler features not related @@ -159,7 +159,7 @@ of ``cxx_rvalue_references``. This function-like macro is available in C++20 by default, and is provided as an extension in earlier language standards. It takes a single argument that is the -name of a double-square-bracket-style attribute. The argument can either be a +name of a double-square-bracket-style attribute. The argument can be either a single identifier or a scoped identifier. If the attribute is supported, a nonzero value is returned. If the attribute is a standards-based attribute, this macro returns a nonzero value based on the year and month in which the attribute @@ -320,7 +320,7 @@ To test for this feature, use ``#if defined(__has_include)``: .. code-block:: c++ - // To avoid problem with non-clang compilers not having this macro. + // To avoid problems with non-clang compilers not having this macro. #if defined(__has_include) #if __has_include("myinclude.h") # include "myinclude.h" @@ -345,7 +345,7 @@ or 0 otherwise: # include_next "myinclude.h" #endif - // To avoid problem with non-clang compilers not having this macro. + // To avoid problems with non-clang compilers not having this macro. #if defined(__has_include_next) #if __has_include_next("myinclude.h") # include_next "myinclude.h" @@ -361,7 +361,7 @@ absolute path is used in the file argument. ----------------- This function-like macro takes a string literal that represents a command line -option for a warning and returns true if that is a valid warning option. +option for a warning and returns ``true`` if that is a valid warning option. .. code-block:: c++ @@ -396,7 +396,7 @@ Builtin Macros file. ``__clang__`` - Defined when compiling with Clang + Defined when compiling with Clang. ``__clang_major__`` Defined to the major marketing version number of Clang (e.g., the 2 in @@ -599,7 +599,7 @@ NEON vector types are created using ``neon_vector_type`` and GCC vector types are created using the ``vector_size(N)`` attribute. The argument ``N`` specifies the number of bytes that will be allocated for an -object of this type. The size has to be multiple of the size of the vector +object of this type. The size has to be a multiple of the size of the vector element type. For example: .. code-block:: c++ @@ -620,7 +620,7 @@ element type. For example: Boolean Vectors --------------- -Clang also supports the ext_vector_type attribute with boolean element types in +Clang also supports the ``ext_vector_type`` attribute with boolean element types in C and C++. For example: .. code-block:: c++ @@ -674,7 +674,7 @@ Vector Literals Vector literals can be used to create vectors from a set of scalars, or vectors. Either parentheses or braces form can be used. In the parentheses -form the number of literal values specified must be one, i.e. referring to a +form the number of literal values specified must be one, i.e., referring to a scalar value, or must match the size of the vector type being created. If a single scalar literal value is specified, the scalar literal value will be replicated to all the components of the vector type. In the brackets form any @@ -725,12 +725,12 @@ address &v[i] no no no [#]_ no no See also :ref:`langext-__builtin_shufflevector`, :ref:`langext-__builtin_convertvector`. -.. [#] ternary operator(?:) has different behaviors depending on condition - operand's vector type. If the condition is a GNU vector (i.e. __vector_size__), +.. [#] ternary operator(?:) has different behaviors depending on the condition + operand's vector type. If the condition is a GNU vector (i.e., ``__vector_size__``), a NEON vector or an SVE vector, it's only available in C++ and uses normal bool conversions (that is, != 0). If it's an extension (OpenCL) vector, it's only available in C and OpenCL C. - And it selects based on signedness of the condition operands (OpenCL v1.1 s6.3.9). + And it selects based on the signedness of the condition operands (OpenCL v1.1 s6.3.9). .. [#] sizeof can only be used on vector length specific SVE types. .. [#] Clang does not allow the address of an element to be taken while GCC allows this. This is intentional for vectors with a boolean element type and @@ -747,7 +747,7 @@ to perform additional operations on certain scalar and vector types. Let ``T`` be one of the following types: * an integer type (as in C23 6.2.5p22), but excluding enumerated types and ``bool`` -* the standard floating types float or double +* the standard floating types ``float`` or ``double`` * a half-precision floating point type, if one is supported on the target * a vector type. @@ -833,7 +833,7 @@ of different sizes and signs is forbidden in binary and ternary builtins. T __builtin_elementwise_canonicalize(T x) return the platform specific canonical encoding floating point types of a floating-point number T __builtin_elementwise_copysign(T x, T y) return the magnitude of x with the sign of y. floating point types - T __builtin_elementwise_fmod(T x, T y) return The floating-point remainder of (x/y) whose sign floating point types + T __builtin_elementwise_fmod(T x, T y) return the floating-point remainder of (x/y) whose sign floating point types matches the sign of x. T __builtin_elementwise_max(T x, T y) return x or y, whichever is larger integer and floating point types For floating point types, follows semantics of maxNum @@ -948,7 +948,7 @@ Let ``VT`` be a vector type and ``ET`` the element type of ``VT``. Each builtin accesses memory according to a provided boolean mask. These are provided as ``__builtin_masked_load`` and ``__builtin_masked_store``. The first -argument is always boolean mask vector. The ``__builtin_masked_load`` builtin +argument is always a boolean mask vector. The ``__builtin_masked_load`` builtin takes an optional third vector argument that will be used for the result of the masked-off lanes. These builtins assume the memory is unaligned, use ``__builtin_assume_aligned`` if alignment is desired. @@ -1109,7 +1109,7 @@ to ``float``; see below for more information on this emulation. ``__fp16`` and ``_Float16`` both use the binary16 format from IEEE 754-2008, which provides a 5-bit exponent and an 11-bit significand -(counting the implicit leading 1). ``__bf16`` uses the `bfloat16 +(including the implicit leading 1). ``__bf16`` uses the `bfloat16 <https://en.wikipedia.org/wiki/Bfloat16_floating-point_format>`_ format, which provides an 8-bit exponent and an 8-bit significand; this is the same exponent range as `float`, just with greatly reduced precision. @@ -1143,7 +1143,7 @@ types with the ``-ffloat16-excess-precision=`` and * ``none``: meaning to perform strict operation-by-operation emulation * ``standard``: meaning that excess precision is permitted under the rules - described in the standard, i.e. never across explicit casts or statements + described in the standard, i.e., never across explicit casts or statements * ``fast``: meaning that excess precision is permitted whenever the optimizer sees an opportunity to avoid truncations; currently this has no effect beyond ``standard`` @@ -1899,7 +1899,7 @@ Type Trait Primitives Type trait primitives are special builtin constant expressions that can be used by the standard C++ library to facilitate or simplify the implementation of -user-facing type traits in the <type_traits> header. +user-facing type traits in the ``<type_traits>`` header. They are not intended to be used directly by user code because they are implementation-defined and subject to change -- as such they're tied closely to @@ -2054,7 +2054,7 @@ The following type trait primitives are supported by Clang. Those traits marked * ``__is_volatile`` (C++, Embarcadero) * ``__reference_binds_to_temporary(T, U)`` (Clang): Determines whether a reference of type ``T`` bound to an expression of type ``U`` would bind to a - materialized temporary object. If ``T`` is not a reference type the result + materialized temporary object. If ``T`` is not a reference type, the result is false. Note this trait will also return false when the initialization of ``T`` from ``U`` is ill-formed. Deprecated, use ``__reference_constructs_from_temporary``. @@ -2182,7 +2182,7 @@ Prior to clang-16, the output may only be used safely when the indirect branches are not taken. Query for this difference with ``__has_extension(gnu_asm_goto_with_outputs_full)``. -When using tied-outputs (i.e. outputs that are inputs and outputs, not just +When using tied-outputs (i.e., outputs that are inputs and outputs, not just outputs) with the `+r` constraint, there is a hidden input that's created before the label, so numeric references to operands must account for that. @@ -2361,7 +2361,7 @@ Loading from a ``__weak`` variable always implicitly retains the loaded value. In non-ARC modes, this retain is normally balanced by an implicit autorelease. This autorelease can be suppressed by performing the load in the receiver position of a ``-retain`` -message send (e.g. ``[weakReference retain]``); note that this performs +message send (e.g., ``[weakReference retain]``); note that this performs only a single retain (the retain done when primitively loading from the weak reference). @@ -2562,7 +2562,7 @@ When a method that's introduced in the OS newer than the target OS is called, a .. code-block:: objc void my_fun(NSSomeClass* var) { - // If fancyNewMethod was added in e.g. macOS 10.12, but the code is + // If fancyNewMethod was added in e.g., macOS 10.12, but the code is // built with -mmacos-version-min=10.11, then this unconditional call // will emit a -Wunguarded-availability warning: [var fancyNewMethod]; @@ -2725,7 +2725,7 @@ correctly in any circumstances. It can be used if: metaprogramming algorithms to be able to specify/detect types generically. - the generated kernel binary does not contain indirect calls because they - are eliminated using compiler optimizations e.g. devirtualization. + are eliminated using compiler optimizations e.g., devirtualization. - the selected target supports the function pointer like functionality e.g. most CPU targets. @@ -2755,12 +2755,12 @@ Extension Specification, section 1.2 <https://www.khronos.org/registry/OpenCL/specs/3.0-unified/html/OpenCL_Ext.html#extensions-overview>`_. This is not conformant behavior and it can only be used portably when the -functions with variadic prototypes do not get generated in binary e.g. the +functions with variadic prototypes do not get generated in binary e.g., the variadic prototype is used to specify a function type with any number of arguments in metaprogramming algorithms in C++ for OpenCL. This extension can also be used when the kernel code is intended for targets -supporting the variadic arguments e.g. majority of CPU targets. +supporting the variadic arguments e.g., majority of CPU targets. **Example of Use**: @@ -5170,8 +5170,8 @@ __builtin_amdgcn_fence ``__builtin_amdgcn_fence`` emits a fence. -* ``unsigned`` atomic ordering, e.g. ``__ATOMIC_ACQUIRE`` -* ``const char *`` synchronization scope, e.g. ``workgroup`` +* ``unsigned`` atomic ordering, e.g., ``__ATOMIC_ACQUIRE`` +* ``const char *`` synchronization scope, e.g., ``workgroup`` * Zero or more ``const char *`` address spaces names. The address spaces arguments must be one of the following string literals: @@ -5205,7 +5205,7 @@ boolean argument as a bit for every lane of the current wave that is currently active (i.e., that is converged with the executing thread), and a 0 bit for every lane that is not active. -The result is uniform, i.e. it is the same in every active thread of the wave. +The result is uniform, i.e., it is the same in every active thread of the wave. __builtin_amdgcn_inverse_ballot_w{32,64} ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -5374,7 +5374,7 @@ followed by ``off`` or ``on``. All function definitions in the region between an ``off`` and the following ``on`` will be decorated with the ``optnone`` attribute unless doing so would -conflict with explicit attributes already present on the function (e.g. the +conflict with explicit attributes already present on the function (e.g., the ones that control inlining). .. code-block:: c++ @@ -5472,12 +5472,12 @@ provides options for vectorization, interleaving, predication, unrolling and distribution. Loop hints can be specified before any loop and will be ignored if the optimization is not safe to apply. -There are loop hints that control transformations (e.g. vectorization, loop +There are loop hints that control transformations (e.g., vectorization, loop unrolling) and there are loop hints that set transformation options (e.g. ``vectorize_width``, ``unroll_count``). Pragmas setting transformation options -imply the transformation is enabled, as if it was enabled via the corresponding -transformation pragma (e.g. ``vectorize(enable)``). If the transformation is -disabled (e.g. ``vectorize(disable)``), that takes precedence over +imply the transformation is enabled, as if it were enabled via the corresponding +transformation pragma (e.g., ``vectorize(enable)``). If the transformation is +disabled (e.g., ``vectorize(disable)``), that takes precedence over transformations option pragmas implying that transformation. Vectorization, Interleaving, and Predication @@ -5704,7 +5704,7 @@ operation when supported by the target. The pragma can take three values: ``on``, ``fast`` and ``off``. The ``on`` option is identical to using ``#pragma STDC FP_CONTRACT(ON)`` and it allows fusion as specified the language standard. The ``fast`` option allows fusion -in cases when the language standard does not make this possible (e.g. across +in cases when the language standard does not make this possible (e.g., across statements in C). .. code-block:: c++ @@ -5859,14 +5859,14 @@ and ``ignore_denormal_mode``, each optionally prefixed with ``no_``. The meaning are as follows: - ``remote_memory`` means atomic operations may be performed on remote - memory, i.e. memory accessed through off-chip interconnects (e.g., PCIe). + memory, i.e., memory accessed through off-chip interconnects (e.g., PCIe). On ROCm platforms using HIP, remote memory refers to memory accessed via PCIe and is subject to specific atomic operation support. See `ROCm PCIe Atomics <https://rocm.docs.amd.com/en/latest/conceptual/ pcie-atomics.html>`_ for further details. Prefixing with ``no_remote_memory`` indicates that atomic operations should not be performed on remote memory. - ``fine_grained_memory`` means atomic operations may be performed on fine-grained - memory, i.e. memory regions that support fine-grained coherence, where updates to + memory, i.e., memory regions that support fine-grained coherence, where updates to memory are visible to other parts of the system even while modifications are ongoing. For example, in HIP, fine-grained coherence ensures that host and device share up-to-date data without explicit synchronization (see @@ -6088,7 +6088,7 @@ match rules are specified after the attribute. The compiler expects an identifier that corresponds to the subject set specifier. The ``apply_to`` specifier is currently the only supported subject set specifier. It allows you to specify match rules that form a subset of the attribute's allowed subject -set, i.e. the compiler doesn't require all of the attribute's subjects. For +set, i.e., the compiler doesn't require all of the attribute's subjects. For example, an attribute like ``[[nodiscard]]`` whose subject set includes ``enum``, ``record`` and ``hasType(functionType)``, requires the presence of at least one of these rules after ``apply_to``: diff --git a/clang/docs/SafeBuffers.rst b/clang/docs/SafeBuffers.rst index da75907..205e621 100644 --- a/clang/docs/SafeBuffers.rst +++ b/clang/docs/SafeBuffers.rst @@ -262,7 +262,7 @@ You can achieve this by refactoring the function to accept a ``std::span`` as a parameter:: int get_last_element(std::span<int> sp) { - return sp[size - 1]; + return sp[sp.size() - 1]; } This solution puts the responsibility for making sure the span is well-formed @@ -411,7 +411,7 @@ backwards compatibility -- in terms of both API and ABI -- by adding a "compatibility overload":: int get_last_element(std::span<int> sp) { - return sp[size - 1]; + return sp[sp.size() - 1]; } [[clang::unsafe_buffer_usage]] // Please use the new function. |