diff options
Diffstat (limited to 'clang/docs')
| -rw-r--r-- | clang/docs/InternalsManual.rst | 110 | ||||
| -rw-r--r-- | clang/docs/OpenMPSupport.rst | 8 | ||||
| -rw-r--r-- | clang/docs/PointerAuthentication.rst | 30 | ||||
| -rw-r--r-- | clang/docs/ReleaseNotes.rst | 35 | ||||
| -rw-r--r-- | clang/docs/UsersManual.rst | 46 | ||||
| -rw-r--r-- | clang/docs/analyzer/checkers.rst | 50 | ||||
| -rw-r--r-- | clang/docs/analyzer/developer-docs/Statistics.rst | 2 |
7 files changed, 211 insertions, 70 deletions
diff --git a/clang/docs/InternalsManual.rst b/clang/docs/InternalsManual.rst index c677ddfa..eff46ab 100644 --- a/clang/docs/InternalsManual.rst +++ b/clang/docs/InternalsManual.rst @@ -10,7 +10,7 @@ Introduction This document describes some of the more important APIs and internal design decisions made in the Clang C front-end. The purpose of this document is to -both capture some of this high level information and also describe some of the +both capture some of this high-level information and also describe some of the design decisions behind it. This is meant for people interested in hacking on Clang, not for end-users. The description below is categorized by libraries, and does not describe any of the clients of the libraries. @@ -20,7 +20,7 @@ LLVM Support Library The LLVM ``libSupport`` library provides many underlying libraries and `data-structures <https://llvm.org/docs/ProgrammersManual.html>`_, including -command line option processing, various containers and a system abstraction +command line option processing, various containers, and a system abstraction layer, which is used for file system access. The Clang "Basic" Library @@ -34,7 +34,7 @@ and information about the subset of the language being compiled for. Part of this infrastructure is specific to C (such as the ``TargetInfo`` class), other parts could be reused for other non-C-based languages (``SourceLocation``, ``SourceManager``, ``Diagnostics``, ``FileManager``). -When and if there is future demand we can figure out if it makes sense to +When and if there is future demand, we can figure out if it makes sense to introduce a new library, move the general classes somewhere else, or introduce some other solution. @@ -96,7 +96,7 @@ The ``EXTENSION`` and ``EXTWARN`` severities are used for extensions to the language that Clang accepts. This means that Clang fully understands and can represent them in the AST, but we produce diagnostics to tell the user their code is non-portable. The difference is that the former are ignored by -default, and the later warn by default. The ``WARNING`` severity is used for +default, and the latter warn by default. The ``WARNING`` severity is used for constructs that are valid in the currently selected source language but that are dubious in some way. The ``REMARK`` severity provides generic information about the compilation that is not necessarily related to any dubious code. The @@ -106,7 +106,7 @@ These *severities* are mapped into a smaller set (the ``Diagnostic::Level`` enum, {``Ignored``, ``Note``, ``Remark``, ``Warning``, ``Error``, ``Fatal``}) of output *levels* by the diagnostics subsystem based on various configuration options. -Clang internally supports a fully fine grained mapping mechanism that allows +Clang internally supports a fully fine-grained mapping mechanism that allows you to map almost any diagnostic to the output level that you want. The only diagnostics that cannot be mapped are ``NOTE``\ s, which always follow the severity of the previously emitted diagnostic and ``ERROR``\ s, which can only @@ -116,18 +116,18 @@ example). Diagnostic mappings are used in many ways. For example, if the user specifies ``-pedantic``, ``EXTENSION`` maps to ``Warning``, if they specify ``-pedantic-errors``, it turns into ``Error``. This is used to implement -options like ``-Wunused_macros``, ``-Wundef`` etc. +options like ``-Wunused_macros``, ``-Wundef``, etc. Mapping to ``Fatal`` should only be used for diagnostics that are considered so severe that error recovery won't be able to recover sensibly from them (thus -spewing a ton of bogus errors). One example of this class of error are failure +spewing a ton of bogus errors). One example of this class of error is failure to ``#include`` a file. Diagnostic Wording ^^^^^^^^^^^^^^^^^^ The wording used for a diagnostic is critical because it is the only way for a user to know how to correct their code. Use the following suggestions when -wording a diagnostic. +wording a diagnostic: * Diagnostics in Clang do not start with a capital letter and do not end with punctuation. @@ -162,7 +162,7 @@ wording a diagnostic. cannot be null in well-defined C++ code``. * Prefer diagnostic wording without contractions whenever possible. The single quote in a contraction can be visually distracting due to its use with - syntactic constructs and contractions can be harder to understand for non- + syntactic constructs, and contractions can be harder to understand for non- native English speakers. The Format String @@ -195,14 +195,14 @@ the C++ code that :ref:`produces them <internals-producing-diag>`, and are referenced by ``%0`` .. ``%9``. If you have more than 10 arguments to your diagnostic, you are doing something wrong :). Unlike ``printf``, there is no requirement that arguments to the diagnostic end up in the output in the same -order as they are specified, you could have a format string with "``%1 %0``" +order as they are specified; you could have a format string with "``%1 %0``" that swaps them, for example. The text in between the percent and digit are formatting instructions. If there are no instructions, the argument is just turned into a string and substituted in. Here are some "best practices" for writing the English format string: -* Keep the string short. It should ideally fit in the 80 column limit of the +* Keep the string short. It should ideally fit in the 80-column limit of the ``DiagnosticKinds.td`` file. This avoids the diagnostic wrapping when printed, and forces you to think about the important point you are conveying with the diagnostic. @@ -227,7 +227,7 @@ used to achieve this sort of thing in a localizable way, see below. Formatting a Diagnostic Argument ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Arguments to diagnostics are fully typed internally, and come from a couple +Arguments to diagnostics are fully typed internally and come from a couple of different classes: integers, types, names, and random strings. Depending on the class of the argument, it can be optionally formatted in different ways. This gives the ``DiagnosticConsumer`` information about what the argument means @@ -268,7 +268,7 @@ Description: This format specifier is used to merge multiple related diagnostics together into one common one, without requiring the difference to be specified as an English string argument. Instead of specifying the string, the diagnostic - gets an integer argument and the format string selects the numbered option. + gets an integer argument, and the format string selects the numbered option. In this case, the "``%0``" value must be an integer in the range [0..2]. If it is 0, it prints "unary", if it is 1 it prints "binary" if it is 2, it prints "unary or binary". This allows other language translations to @@ -287,7 +287,7 @@ Description: additionally generates a namespace, enumeration, and enumerator list based on the format string given. In the above case, a namespace is generated named ``FrobbleKind`` that has an unscoped enumeration with the enumerators - ``VarDecl`` and ``FuncDecl`` which correspond to the values 0 and 1. This + ``VarDecl`` and ``FuncDecl``, which correspond to the values 0 and 1. This permits a clearer use of the ``Diag`` in source code, as the above could be called as: ``Diag(Loc, diag::frobble) << diag::FrobbleKind::VarDecl``. @@ -407,7 +407,7 @@ Example: def note_ovl_candidate : Note< "candidate %sub{select_ovl_candidate}3,2,1 not viable">; - and will act as if it was written + and will act as if it were written ``"candidate %select{function|constructor}3%select{| template| %1}2 not viable"``. Description: This format specifier is used to avoid repeating strings verbatim in multiple @@ -447,7 +447,7 @@ For example, the binary expression error comes from code like this: << lex->getType() << rex->getType() << lex->getSourceRange() << rex->getSourceRange(); -This shows that use of the ``Diag`` method: it takes a location (a +This shows the use of the ``Diag`` method: it takes a location (a :ref:`SourceLocation <SourceLocation>` object) and a diagnostic enum value (which matches the name from ``Diagnostic*Kinds.td``). If the diagnostic takes arguments, they are specified with the ``<<`` operator: the first argument @@ -586,7 +586,7 @@ Strangely enough, the ``SourceLocation`` class represents a location within the source code of the program. Important design points include: #. ``sizeof(SourceLocation)`` must be extremely small, as these are embedded - into many AST nodes and are passed around often. Currently it is 32 bits. + into many AST nodes and are passed around often. Currently, it is 32 bits. #. ``SourceLocation`` must be a simple value object that can be efficiently copied. #. We should be able to represent a source location for any byte of any input @@ -605,7 +605,7 @@ In practice, the ``SourceLocation`` works together with the ``SourceManager`` class to encode two pieces of information about a location: its spelling location and its expansion location. For most tokens, these will be the same. However, for a macro expansion (or tokens that came from a ``_Pragma`` -directive) these will describe the location of the characters corresponding to +directive), these will describe the location of the characters corresponding to the token and the location where the token was used (i.e., the macro expansion point or the location of the ``_Pragma`` itself). @@ -621,7 +621,7 @@ token. This concept maps directly to the "spelling location" for the token. .. mostly taken from https://discourse.llvm.org/t/code-ranges-of-tokens-ast-elements/16893/2 Clang represents most source ranges by [first, last], where "first" and "last" -each point to the beginning of their respective tokens. For example consider +each point to the beginning of their respective tokens. For example, consider the ``SourceRange`` of the following statement: .. code-block:: text @@ -632,7 +632,7 @@ the ``SourceRange`` of the following statement: To map from this representation to a character-based representation, the "last" location needs to be adjusted to point to (or past) the end of that token with either ``Lexer::MeasureTokenLength()`` or ``Lexer::getLocForEndOfToken()``. For -the rare cases where character-level source ranges information is needed we use +the rare cases where character-level source ranges information is needed, we use the ``CharSourceRange`` class. The Driver Library @@ -651,17 +651,17 @@ The Frontend Library ==================== The Frontend library contains functionality useful for building tools on top of -the Clang libraries, for example several methods for outputting diagnostics. +the Clang libraries, including several methods for outputting diagnostics. Compiler Invocation ------------------- One of the classes provided by the Frontend library is ``CompilerInvocation``, -which holds information that describe current invocation of the Clang ``-cc1`` +which holds information that describes the current invocation of the Clang ``-cc1`` frontend. The information typically comes from the command line constructed by the Clang driver or from clients performing custom initialization. The data structure is split into logical units used by different parts of the compiler, -for example ``PreprocessorOptions``, ``LanguageOptions`` or ``CodeGenOptions``. +for example, ``PreprocessorOptions``, ``LanguageOptions``, or ``CodeGenOptions``. Command Line Interface ---------------------- @@ -698,7 +698,7 @@ Adding new Command Line Option ------------------------------ When adding a new command line option, the first place of interest is the header -file declaring the corresponding options class (e.g. ``CodeGenOptions.h`` for +file declaring the corresponding options class (e.g., ``CodeGenOptions.h`` for command line option that affects the code generation). Create new member variable for the option value: @@ -739,7 +739,7 @@ The helper classes take a list of acceptable prefixes of the option (e.g. Then, specify additional attributes via mix-ins: * ``HelpText`` holds the text that will be printed besides the option name when - the user requests help (e.g. via ``clang --help``). + the user requests help (e.g., via ``clang --help``). * ``Group`` specifies the "category" of options this option belongs to. This is used by various tools to categorize and sometimes filter options. * ``Flags`` may contain "tags" associated with the option. These may affect how @@ -779,7 +779,7 @@ use them to construct the ``-cc1`` job: } The last step is implementing the ``-cc1`` command line argument -parsing/generation that initializes/serializes the option class (in our case +parsing/generation that initializes/serializes the option class (in our case, ``CodeGenOptions``) stored within ``CompilerInvocation``. This can be done automatically by using the marshalling annotations on the option definition: @@ -946,13 +946,13 @@ described below. All of them take a key path argument and possibly other information required for parsing or generating the command line argument. **Note:** The marshalling infrastructure is not intended for driver-only -options. Only options of the ``-cc1`` frontend need to be marshalled to/from +options. Only options of the ``-cc1`` frontend need to be marshalled to/from a ``CompilerInvocation`` instance. **Positive Flag** The key path defaults to ``false`` and is set to ``true`` when the flag is -present on command line. +present on the command line. .. code-block:: text @@ -963,7 +963,7 @@ present on command line. **Negative Flag** The key path defaults to ``true`` and is set to ``false`` when the flag is -present on command line. +present on the command line. .. code-block:: text @@ -1041,7 +1041,7 @@ and the result is assigned to the key path on success. The key path defaults to the value specified in ``MarshallingInfoEnum`` prefixed by the contents of ``NormalizedValuesScope`` and ``::``. This ensures correct -reference to an enum case is formed even if the enum resides in different +reference to an enum case is formed even if the enum resides in a different namespace or is an enum class. If the value present on the command line does not match any of the comma-separated values from ``Values``, an error diagnostic is issued. Otherwise, the corresponding element from ``NormalizedValues`` at the @@ -1410,7 +1410,7 @@ or a clear engineering tradeoff -- should desugar minimally and wrap the result in a construct representing the original source form. For example, ``CXXForRangeStmt`` directly represents the syntactic form of a -range-based for statement, but also holds a semantic representation of the +range-based for statement but also holds a semantic representation of the range declaration and iterator declarations. It does not contain a fully-desugared ``ForStmt``, however. @@ -1425,7 +1425,7 @@ with the same or similar semantics. The ``Type`` class and its subclasses ------------------------------------- -The ``Type`` class (and its subclasses) are an important part of the AST. +The ``Type`` class (and its subclasses) is an important part of the AST. Types are accessed through the ``ASTContext`` class, which implicitly creates and uniques them as they are needed. Types have a couple of non-obvious features: 1) they do not capture type qualifiers like ``const`` or ``volatile`` @@ -1474,7 +1474,7 @@ various operators (for example, the type of ``*Y`` is "``foo``", not is an instance of the ``TypedefType`` class, which indicates that the type of these expressions is a typedef for "``foo``". -Representing types like this is great for diagnostics, because the +Representing types like this is great for diagnostics because the user-specified type is always immediately available. There are two problems with this: first, various semantic checks need to make judgements about the *actual structure* of a type, ignoring typedefs. Second, we need an efficient @@ -1521,7 +1521,7 @@ know it exists. To continue the example, the result type of the indirection operator is the pointee type of the subexpression. In order to determine the type, we need to get the instance of ``PointerType`` that best captures the typedef information in the program. If the type of the expression is literally -a ``PointerType``, we can return that, otherwise we have to dig through the +a ``PointerType``, we can return that; otherwise, we have to dig through the typedefs to find the pointer type. For example, if the subexpression had type "``foo*``", we could return that type as the result. If the subexpression had type "``bar``", we want to return "``foo*``" (note that we do *not* want @@ -1552,7 +1552,7 @@ that sets a bit), and remove one or more type qualifiers (just return a ``QualType`` with the bitfield set to empty). Further, because the bits are stored outside of the type itself, we do not need -to create duplicates of types with different sets of qualifiers (i.e. there is +to create duplicates of types with different sets of qualifiers (i.e., there is only a single heap allocated "``int``" type: "``const int``" and "``volatile const int``" both point to the same heap allocated "``int``" type). This reduces the heap size used to represent bits and also means we do not have to @@ -1972,7 +1972,7 @@ and optimize code for it, but it's used as parsing continues to detect further errors in the input. Clang-based tools also depend on such ASTs, and IDEs in particular benefit from a high-quality AST for broken code. -In presence of errors, clang uses a few error-recovery strategies to present the +In the presence of errors, clang uses a few error-recovery strategies to present the broken code in the AST: - correcting errors: in cases where clang is confident about the fix, it @@ -1981,7 +1981,7 @@ broken code in the AST: provide more accurate subsequent diagnostics. Typo correction is a typical example. - representing invalid node: the invalid node is preserved in the AST in some - form, e.g. when the "declaration" part of the declaration contains semantic + form, e.g., when the "declaration" part of the declaration contains semantic errors, the Decl node is marked as invalid. - dropping invalid node: this often happens for errors that we don’t have graceful recovery. Prior to Recovery AST, a mismatched-argument function call @@ -1994,9 +1994,9 @@ for broken code. Recovery AST ^^^^^^^^^^^^ -The idea of Recovery AST is to use recovery nodes which act as a placeholder to +The idea of Recovery AST is to use recovery nodes, which act as a placeholder to maintain the rough structure of the parsing tree, preserve locations and -children but have no language semantics attached to them. +children, but have no language semantics attached to them. For example, consider the following mismatched function call: @@ -2031,10 +2031,10 @@ With Recovery AST, the AST looks like: `-DeclRefExpr <col:9> 'int' lvalue ParmVar 'abc' 'int' -An alternative is to use existing Exprs, e.g. CallExpr for the above example. -This would capture more call details (e.g. locations of parentheses) and allow +An alternative is to use existing Exprs, e.g., CallExpr for the above example. +This would capture more call details (e.g., locations of parentheses) and allow it to be treated uniformly with valid CallExprs. However, jamming the data we -have into CallExpr forces us to weaken its invariants, e.g. arg count may be +have into CallExpr forces us to weaken its invariants, e.g., arg count may be wrong. This would introduce a huge burden on consumers of the AST to handle such "impossible" cases. So when we're representing (rather than correcting) errors, we use a distinct recovery node type with extremely weak invariants instead. @@ -2048,7 +2048,7 @@ Types and dependence ^^^^^^^^^^^^^^^^^^^^ ``RecoveryExpr`` is an ``Expr``, so it must have a type. In many cases the true -type can't really be known until the code is corrected (e.g. a call to a +type can't really be known until the code is corrected (e.g., a call to a function that doesn't exist). And it means that we can't properly perform type checks on some containing constructs, such as ``return 42 + unknownFunction()``. @@ -2058,7 +2058,7 @@ mean dependence on a template parameter or how an error is repaired. The ``DependentTy``, and this suppresses type-based analysis in the same way it would inside a template. -In cases where we are confident about the concrete type (e.g. the return type +In cases where we are confident about the concrete type (e.g., the return type for a broken non-overloaded function call), the ``RecoveryExpr`` will have this type. This allows more code to be typechecked, and produces a better AST and more diagnostics. For example: @@ -2071,7 +2071,7 @@ more diagnostics. For example: Whether or not the ``RecoveryExpr`` has a dependent type, it is always considered value-dependent, because its value isn't well-defined until the error is resolved. Among other things, this means that clang doesn't emit more errors -where a RecoveryExpr is used as a constant (e.g. array size), but also won't try +where a RecoveryExpr is used as a constant (e.g., array size), but also won't try to evaluate it. ContainsErrors bit @@ -2122,7 +2122,7 @@ cycles. One example of a cycle is the connection between a ``ClassTemplateDecl`` and its "templated" ``CXXRecordDecl``. The *templated* ``CXXRecordDecl`` represents all the fields and methods inside the class template, while the ``ClassTemplateDecl`` holds the information which is -related to being a template, i.e. template arguments, etc. We can get the +related to being a template, i.e., template arguments, etc. We can get the *templated* class (the ``CXXRecordDecl``) of a ``ClassTemplateDecl`` with ``ClassTemplateDecl::getTemplatedDecl()``. And we can get back a pointer of the "described" class template from the *templated* class: @@ -2145,7 +2145,7 @@ we skip the copy. The informal definition of structural equivalency is the following: Two nodes are **structurally equivalent** if they are -- builtin types and refer to the same type, e.g. ``int`` and ``int`` are +- builtin types and refer to the same type, e.g., ``int`` and ``int`` are structurally equivalent, - function types and all their parameters have structurally equivalent types, - record types and all their fields in order of their definition have the same @@ -2162,7 +2162,7 @@ mentioned properties, we have to check for equivalent template parameters/arguments, etc. The structural equivalent check can be and is used independently from the -ASTImporter, e.g. the ``clang::Sema`` class uses it also. +ASTImporter, e.g., the ``clang::Sema`` class uses it also. The equivalence of nodes may depend on the equivalency of other pairs of nodes. Thus, the check is implemented as a parallel graph traversal. We traverse @@ -2195,7 +2195,7 @@ Redeclaration Chains ^^^^^^^^^^^^^^^^^^^^ The early version of the ``ASTImporter``'s merge mechanism squashed the -declarations, i.e. it aimed to have only one declaration instead of maintaining +declarations, i.e., it aimed to have only one declaration instead of maintaining a whole redeclaration chain. This early approach simply skipped importing a function prototype, but it imported a definition. To demonstrate the problem with this approach let's consider an empty "to" context and the following @@ -2225,7 +2225,7 @@ another definition, we will use the existing definition. However, we can import prototype(s): we chain the newly imported prototype(s) to the existing definition. Whenever we import a new prototype from a third context, that will be added to the end of the redeclaration chain. This may result in long -redeclaration chains in certain cases, e.g. if we import from several +redeclaration chains in certain cases, e.g., if we import from several translation units which include the same header with the prototype. .. Squashing prototypes @@ -2290,7 +2290,7 @@ Traversal during the Import ^^^^^^^^^^^^^^^^^^^^^^^^^^^ The node specific import mechanisms are implemented in -``ASTNodeImporter::VisitNode()`` functions, e.g. ``VisitFunctionDecl()``. +``ASTNodeImporter::VisitNode()`` functions, e.g., ``VisitFunctionDecl()``. When we import a declaration then first we import everything which is needed to call the constructor of that declaration node. Everything which can be set later is set after the node is created. For example, in case of a @@ -2490,7 +2490,7 @@ In case of LLDB, an implementation of the ``ExternalASTSource`` interface is attached to the AST context which is related to the parsed expression. This implementation of the ``ExternalASTSource`` interface is realized with the help of the ``ASTImporter`` class. This way, LLDB can reuse Clang's parsing -machinery while synthesizing the underlying AST from the debug data (e.g. from +machinery while synthesizing the underlying AST from the debug data (e.g., from DWARF). From the view of the ``ASTImporter`` this means both the "to" and the "from" context may have declaration contexts with external lexical storage. If a ``DeclContext`` in the "to" AST context has external lexical storage then we @@ -2573,7 +2573,7 @@ conflict error (ODR violation in C++). In this case, we return with an clients of the ``ASTImporter`` may require a different, perhaps less conservative and more liberal error handling strategy. -E.g. static analysis clients may benefit if the node is created even if there +E.g., static analysis clients may benefit if the node is created even if there is a name conflict. During the CTU analysis of certain projects, we recognized that there are global declarations which collide with declarations from other translation units, but they are not referenced outside from their translation @@ -2916,7 +2916,7 @@ Any error during satisfaction is recorded in ``ConstraintSatisfaction``. for nested requirements, ``ConstraintSatisfaction`` is stored (including diagnostics) in the AST, which is something we might want to improve. -When an atomic constraint is not satified, we try to substitute into any +When an atomic constraint is not satisfied, we try to substitute into any enclosing concept-id using the same mechanism described above, for diagnostics purpose, and inject that in the ``ConstraintSatisfaction``. @@ -3584,7 +3584,7 @@ be specified by appending a ``+`` to the number. For example: void f(); // expected-note 0+ {{previous declaration is here}} void g(); // expected-note 1+ {{previous declaration is here}} -In the first example, the diagnostic becomes optional, i.e. it will be +In the first example, the diagnostic becomes optional, i.e., it will be swallowed if it occurs, but will not generate an error if it does not occur. In the second example, the diagnostic must occur at least once. As a short-hand, "one or more" can be specified simply by ``+``. For example: diff --git a/clang/docs/OpenMPSupport.rst b/clang/docs/OpenMPSupport.rst index cdb3b33..c75c170 100644 --- a/clang/docs/OpenMPSupport.rst +++ b/clang/docs/OpenMPSupport.rst @@ -193,7 +193,7 @@ implementation. +------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
| device | support non-contiguous array sections for target update | :good:`done` | https://github.com/llvm/llvm-project/pull/144635 |
+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| device | pointer attachment | :good:`done` | |
+| device | pointer attachment | :part:`being repaired` | @abhinavgaba (https://github.com/llvm/llvm-project/pull/153683) |
+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
| atomic | hints for the atomic construct | :good:`done` | D51233 |
+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
@@ -505,7 +505,7 @@ implementation. +-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
| pure directives in DO CONCURRENT | | :none:`unclaimed` | |
+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| Optional argument for all clauses | :none:`unclaimed` | :none:`unclaimed` | |
+| Optional argument for all clauses | :none:`partial` | :none:`In Progress` | Parse/Sema (nowait): https://github.com/llvm/llvm-project/pull/159628 |
+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
| Function references for locator list items | :none:`unclaimed` | :none:`unclaimed` | |
+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
@@ -627,6 +627,10 @@ implementation. +-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
| loop grid/tile modifiers for sizes clause | :none:`unclaimed` | :none:`unclaimed` | |
+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
+| attach map-type modifier | :part:`In Progress` | :none:`unclaimed` | C/C++: @abhinavgaba; |
+| | | | RT: @abhinavgaba (https://github.com/llvm/llvm-project/pull/149036, |
+| | | | https://github.com/llvm/llvm-project/pull/158370) |
++-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
OpenMP Extensions
diff --git a/clang/docs/PointerAuthentication.rst b/clang/docs/PointerAuthentication.rst index 96eb498..7e65f4b 100644 --- a/clang/docs/PointerAuthentication.rst +++ b/clang/docs/PointerAuthentication.rst @@ -592,6 +592,36 @@ The result value is never zero and always within range for both the This can be used in constant expressions. +``ptrauth_type_discriminator`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: c + + ptrauth_type_discriminator(type) + +Compute the constant discriminator derived from the given type, as is computed +for automatically type diversified schemas. + +``type`` must be a type. The result has the type ``ptrauth_extra_data_t``. + +This can be used in constant expressions. + +``ptrauth_function_pointer_type_discriminator`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: c + + ptrauth_function_pointer_type_discriminator(function_type) + +Compute the constant discriminator derived from the provided function type, for +use in contexts where the default function authentication schema. If function +pointer type diversity is enabled, this is equivalent to +`ptrauth_type_discriminator(function_type)`, if it is not enabled this is `0`. + +``function_type`` must be a function type. The result has the type ``ptrauth_extra_data_t``. + +This can be used in constant expressions. + ``ptrauth_strip`` ^^^^^^^^^^^^^^^^^ diff --git a/clang/docs/ReleaseNotes.rst b/clang/docs/ReleaseNotes.rst index 65b086c..fe77f91 100644 --- a/clang/docs/ReleaseNotes.rst +++ b/clang/docs/ReleaseNotes.rst @@ -128,6 +128,17 @@ AST Dumping Potentially Breaking Changes - Default arguments of template template parameters are pretty-printed now. +- Pretty-printing of ``asm`` attributes are now always the first attribute + on the right side of the declaration. Before we had, e.g.: + + ``__attribute__(("visibility")) asm("string")`` + + Now we have: + + ``asm("string") __attribute__(("visibility"))`` + + Which is accepted by both clang and gcc parsers. + Clang Frontend Potentially Breaking Changes ------------------------------------------- - Members of anonymous unions/structs are now injected as ``IndirectFieldDecl`` @@ -136,6 +147,7 @@ Clang Frontend Potentially Breaking Changes Clang Python Bindings Potentially Breaking Changes -------------------------------------------------- +- Return ``None`` instead of null cursors from ``Token.cursor`` - TypeKind ``ELABORATED`` is not used anymore, per clang AST changes removing ElaboratedTypes. The value becomes unused, and all the existing users should expect the former underlying type to be reported instead. @@ -187,6 +199,11 @@ C2y Feature Support C23 Feature Support ^^^^^^^^^^^^^^^^^^^ +- Added ``FLT_SNAN``, ``DBL_SNAN``, and ``LDBL_SNAN`` to Clang's ``<float.h>`` + header in C23 and later modes. This implements + `WG14 N2710 <https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2710.htm>`_. +- Fixed accepting as compatible unnamed tag types with the same fields within + the same translation unit but from different types. Non-comprehensive list of changes in this release ------------------------------------------------- @@ -265,12 +282,14 @@ Non-comprehensive list of changes in this release allocation functions with a token ID can be enabled via the ``-fsanitize=alloc-token`` flag. +- Clang now rejects the invalid use of ``constexpr`` with ``auto`` and an explicit type in C. (#GH163090) + New Compiler Flags ------------------ - New option ``-fno-sanitize-debug-trap-reasons`` added to disable emitting trap reasons into the debug info when compiling with trapping UBSan (e.g. ``-fsanitize-trap=undefined``). - New option ``-fsanitize-debug-trap-reasons=`` added to control emitting trap reasons into the debug info when compiling with trapping UBSan (e.g. ``-fsanitize-trap=undefined``). - New options for enabling allocation token instrumentation: ``-fsanitize=alloc-token``, ``-falloc-token-max=``, ``-fsanitize-alloc-token-fast-abi``, ``-fsanitize-alloc-token-extended``. - +- The ``-resource-dir`` option is now displayed in the list of options shown by ``--help``. Lanai Support ^^^^^^^^^^^^^^ @@ -282,6 +301,7 @@ Deprecated Compiler Flags Modified Compiler Flags ----------------------- - The `-gkey-instructions` compiler flag is now enabled by default when DWARF is emitted for plain C/C++ and optimizations are enabled. (#GH149509) +- The `-fconstexpr-steps` compiler flag now accepts value `0` to opt out of this limit. (#GH160440) Removed Compiler Flags ------------------------- @@ -297,6 +317,8 @@ Attribute Changes in Clang Improvements to Clang's diagnostics ----------------------------------- +- Diagnostics messages now refer to ``structured binding`` instead of ``decomposition``, + to align with `P0615R0 <https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2017/p0615r0.html>`_ changing the term. (#GH157880) - Added a separate diagnostic group ``-Wfunction-effect-redeclarations``, for the more pedantic diagnostics for function effects (``[[clang::nonblocking]]`` and ``[[clang::nonallocating]]``). Moved the warning for a missing (though implied) attribute on a redeclaration into this group. @@ -405,6 +427,8 @@ Bug Fixes in This Version a function without arguments caused us to try to access a non-existent argument. (#GH159080) - Fixed a failed assertion with empty filename arguments in ``__has_embed``. (#GH159898) +- Fixed a failed assertion with empty filename in ``#embed`` directive. (#GH162951) +- Fixed a crash triggered by unterminated ``__has_embed``. (#GH162953) Bug Fixes to Compiler Builtins ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -418,7 +442,8 @@ Bug Fixes to Attribute Support (#GH141504) and on types returned from indirect calls (#GH142453). - Fixes some late parsed attributes, when applied to function definitions, not being parsed in function try blocks, and some situations where parsing of the function body - is skipped, such as error recovery and code completion. (#GH153551) + is skipped, such as error recovery, code completion, and msvc-compatible delayed + template parsing. (#GH153551) - Using ``[[gnu::cleanup(some_func)]]`` where some_func is annotated with ``[[gnu::error("some error")]]`` now correctly triggers an error. (#GH146520) - Fix a crash when the function name is empty in the `swift_name` attribute. (#GH157075) @@ -429,6 +454,7 @@ Bug Fixes to C++ Support - Suppress ``-Wdeprecated-declarations`` in implicitly generated functions. (#GH147293) - Fix a crash when deleting a pointer to an incomplete array (#GH150359). - Fixed a mismatched lambda scope bug when propagating up ``consteval`` within nested lambdas. (#GH145776) +- Disallow immediate escalation in destructors. (#GH109096) - Fix an assertion failure when expression in assumption attribute (``[[assume(expr)]]``) creates temporary objects. - Fix the dynamic_cast to final class optimization to correctly handle @@ -463,6 +489,7 @@ Bug Fixes to C++ Support - Fix a crash when attempting to deduce a deduction guide from a non deducible template template parameter. (#130604) - Fix for clang incorrectly rejecting the default construction of a union with nontrivial member when another member has an initializer. (#GH81774) +- Fixed a template depth issue when parsing lambdas inside a type constraint. (#GH162092) - Diagnose unresolved overload sets in non-dependent compound requirements. (#GH51246) (#GH97753) Bug Fixes to AST Handling @@ -506,6 +533,8 @@ X86 Support driver. - Remove `[no-]evex512` feature request from intrinsics and builtins. - Change features `avx10.x-[256,512]` to `avx10.x`. +- `-march=wildcatlake` is now supported. +- `-march=novalake` is now supported. Arm and AArch64 Support ^^^^^^^^^^^^^^^^^^^^^^^ @@ -635,6 +664,8 @@ OpenMP Support - Added support for ``defaultmap`` directive implicit-behavior ``private``. - Added parsing and semantic analysis support for ``groupprivate`` directive. - Added support for 'omp fuse' directive. +- Updated parsing and semantic analysis support for ``nowait`` clause to accept + optional argument in OpenMP >= 60. Improvements ^^^^^^^^^^^^ diff --git a/clang/docs/UsersManual.rst b/clang/docs/UsersManual.rst index 5745e4b..e82b16f 100644 --- a/clang/docs/UsersManual.rst +++ b/clang/docs/UsersManual.rst @@ -2325,7 +2325,7 @@ are listed below. devirtualization and virtual constant propagation, for classes with :doc:`hidden LTO visibility <LTOVisibility>`. Requires ``-flto``. -.. option:: -f[no]split-lto-unit +.. option:: -f[no-]split-lto-unit Controls splitting the :doc:`LTO unit <LTOVisibility>` into regular LTO and :doc:`ThinLTO` portions, when compiling with -flto=thin. Defaults to false @@ -2518,7 +2518,7 @@ are listed below. .. _funique_internal_linkage_names: -.. option:: -f[no]-unique-internal-linkage-names +.. option:: -f[no-]unique-internal-linkage-names Controls whether Clang emits a unique (best-effort) symbol name for internal linkage symbols. When this option is set, compiler hashes the main source @@ -2539,7 +2539,7 @@ are listed below. $ cd $P/bar && clang -c -funique-internal-linkage-names name_conflict.c $ cd $P && clang foo/name_conflict.o && bar/name_conflict.o -.. option:: -f[no]-basic-block-address-map: +.. option:: -f[no-]basic-block-address-map: Emits a ``SHT_LLVM_BB_ADDR_MAP`` section which includes address offsets for each basic block in the program, relative to the parent function address. @@ -2780,6 +2780,25 @@ usual build cycle when using sample profilers for optimization: /clang:-fdebug-info-for-profiling /clang:-funique-internal-linkage-names ^ code.cc /Fe:code -fuse-ld=lld /link /debug:dwarf + [OPTIONAL] Pseudo instrumentation can be used as the anchor for accurate + profile mapping with the ``-fpseudo-probe-for-profiling`` option. + + On Linux: + + .. code-block:: console + + $ clang++ -O2 -gline-tables-only \ + -fpseudo-probe-for-profiling -funique-internal-linkage-names \ + code.cc -o code + + On Windows: + + .. code-block:: winbatch + + > clang-cl /O2 -gdwarf -gline-tables-only ^ + -fpseudo-probe-for-profiling /clang:-funique-internal-linkage-names ^ + code.cc /Fe:code -fuse-ld=lld /link /debug:dwarf + .. note:: :ref:`-funique-internal-linkage-names <funique_internal_linkage_names>` @@ -2881,6 +2900,25 @@ usual build cycle when using sample profilers for optimization: /clang:-fdebug-info-for-profiling /clang:-funique-internal-linkage-names ^ -fprofile-sample-use=code.prof code.cc /Fe:code + [OPTIONAL] Pseudo instrumentation can be used as the anchor for accurate + profile mapping with the ``-fpseudo-probe-for-profiling`` option. + + On Linux: + + .. code-block:: console + + $ clang++ -O2 \ + -fpseudo-probe-for-profiling -funique-internal-linkage-names \ + -fprofile-sample-use=code.prof code.cc -o code + + On Windows: + + .. code-block:: winbatch + + > clang-cl /O2 ^ + -fpseudo-probe-for-profiling /clang:-funique-internal-linkage-names ^ + -fprofile-sample-use=code.prof code.cc /Fe:code + [OPTIONAL] Sampling-based profiles can have inaccuracies or missing block/ edge counters. The profile inference algorithm (profi) can be used to infer missing blocks and edge counts, and improve the quality of profile data. @@ -4036,7 +4074,7 @@ Controlling implementation limits Sets the limit for the number of full-expressions evaluated in a single constant expression evaluation. This also controls the maximum size of array and dynamic array allocation that can be constant evaluated. - The default is 1048576. + The default is 1048576, and the limit can be disabled with `-fconstexpr-steps=0`. .. option:: -ftemplate-depth=N diff --git a/clang/docs/analyzer/checkers.rst b/clang/docs/analyzer/checkers.rst index d942578..fd0b304 100644 --- a/clang/docs/analyzer/checkers.rst +++ b/clang/docs/analyzer/checkers.rst @@ -205,6 +205,50 @@ pointers with a specified address space. If the option is set to false, then reports from the specific x86 address spaces 256, 257 and 258 are still suppressed, but null dereferences from other address spaces are reported. +.. _core-NullPointerArithm: + +core.NullPointerArithm (C, C++) +""""""""""""""""""""""""""""""" +Check for undefined arithmetic operations with null pointers. + +The checker can detect the following cases: + + - ``p + x`` and ``x + p`` where ``p`` is a null pointer and ``x`` is a nonzero + integer value. + - ``p - x`` where ``p`` is a null pointer and ``x`` is a nonzero integer + value. + - ``p1 - p2`` where one of ``p1`` and ``p2`` is null and the other a + non-null pointer. + +Result of these operations is undefined according to the standard. +In the above listed cases, the checker will warn even if the expression +described to be "nonzero" or "non-null" has unknown value, because it is likely +that it can have non-zero value during the program execution. + +.. code-block:: c + + void test1(int *p, int offset) { + if (p) + return; + + int *p1 = p + offset; // warn: 'p' is null, 'offset' is unknown but likely non-zero + } + + void test2(int *p, int offset) { + if (p) { } // this indicates that it is possible for 'p' to be null + if (offset == 0) + return; + + int *p1 = p - offset; // warn: 'p' is null, 'offset' is known to be non-zero + } + + void test3(char *p1, char *p2) { + if (p1) + return; + + int a = p1 - p2; // warn: 'p1' is null, 'p2' can be likely non-null + } + .. _core-StackAddressEscape: core.StackAddressEscape (C) @@ -3421,12 +3465,6 @@ Check for an out-of-bound pointer being returned to callers. return x; // warn: undefined or garbage returned } - -alpha.security.cert -^^^^^^^^^^^^^^^^^^^ - -SEI CERT checkers which tries to find errors based on their `C coding rules <https://wiki.sei.cmu.edu/confluence/display/c/2+Rules>`_. - alpha.unix ^^^^^^^^^^ diff --git a/clang/docs/analyzer/developer-docs/Statistics.rst b/clang/docs/analyzer/developer-docs/Statistics.rst index 4f2484a..355759d 100644 --- a/clang/docs/analyzer/developer-docs/Statistics.rst +++ b/clang/docs/analyzer/developer-docs/Statistics.rst @@ -22,7 +22,7 @@ However, note that with ``LLVM_ENABLE_STATS`` disabled, only storage of the valu If you want to define a statistic only for entry point, EntryPointStats.h has four classes at your disposal: -- ``UnsignedEPStat`` - an unsigned value assigned at most once per entry point. For example: "the number of source characters in an entry-point body". +- ``UnsignedEPStat`` - an unsigned value assigned at most once per entry point. For example: "the number of source characters in an entry-point body". If no value is assigned during analysis of an entry point, the corresponding CSV cell will be empty. - ``CounterEPStat`` - an additive statistic. It starts with 0 and you can add to it as many times as needed. For example: "the number of bugs discovered". - ``UnsignedMaxEPStat`` - a maximizing statistic. It starts with 0 and when you join it with a value, it picks the maximum of the previous value and the new one. For example, "the longest execution path of a bug". |