diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/LanguageExtensions.rst | 175 | ||||
| -rw-r--r-- | docs/SanitizerCoverage.rst | 192 | ||||
| -rw-r--r-- | docs/doxygen.cfg.in | 8 |
3 files changed, 179 insertions, 196 deletions
diff --git a/docs/LanguageExtensions.rst b/docs/LanguageExtensions.rst index a8fb4623b637..187dae751be1 100644 --- a/docs/LanguageExtensions.rst +++ b/docs/LanguageExtensions.rst @@ -2346,3 +2346,178 @@ statements in C) The pragma can also be used with ``off`` which turns FP contraction off for a section of the code. This can be useful when fast contraction is otherwise enabled for the translation unit with the ``-ffp-contract=fast`` flag. + +Specifying an attribute for multiple declarations (#pragma clang attribute) +=========================================================================== + +The ``#pragma clang attribute`` directive can be used to apply an attribute to +multiple declarations. The ``#pragma clang attribute push`` variation of the +directive pushes a new attribute to the attribute stack. The declarations that +follow the pragma receive the attributes that are on the attribute stack, until +the stack is cleared using a ``#pragma clang attribute pop`` directive. Multiple +push directives can be nested inside each other. + +The attributes that are used in the ``#pragma clang attribute`` directives +can be written using the GNU-style syntax: + +.. code-block:: c++ + + #pragma clang attribute push(__attribute__((annotate("custom"))), apply_to = function) + + void function(); // The function now has the annotate("custom") attribute + + #pragma clang attribute pop + +The attributes can also be written using the C++11 style syntax: + +.. code-block:: c++ + + #pragma clang attribute push([[noreturn]], apply_to = function) + + void function(); // The function now has the [[noreturn]] attribute + + #pragma clang attribute pop + +The ``__declspec`` style syntax is also supported: + +.. code-block:: c++ + + #pragma clang attribute push(__declspec(dllexport), apply_to = function) + + void function(); // The function now has the __declspec(dllexport) attribute + + #pragma clang attribute pop + +A single push directive accepts only one attribute regardless of the syntax +used. + +Subject Match Rules +------------------- + +The set of declarations that receive a single attribute from the attribute stack +depends on the subject match rules that were specified in the pragma. Subject +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 +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``: + +.. code-block:: c++ + + #pragma clang attribute push([[nodiscard]], apply_to = enum) + + enum Enum1 { A1, B1 }; // The enum will receive [[nodiscard]] + + struct Record1 { }; // The struct will *not* receive [[nodiscard]] + + #pragma clang attribute pop + + #pragma clang attribute push([[nodiscard]], apply_to = any(record, enum)) + + enum Enum2 { A2, B2 }; // The enum will receive [[nodiscard]] + + struct Record2 { }; // The struct *will* receive [[nodiscard]] + + #pragma clang attribute pop + + // This is an error, since [[nodiscard]] can't be applied to namespaces: + #pragma clang attribute push([[nodiscard]], apply_to = any(record, namespace)) + + #pragma clang attribute pop + +Multiple match rules can be specified using the ``any`` match rule, as shown +in the example above. The ``any`` rule applies attributes to all declarations +that are matched by at least one of the rules in the ``any``. It doesn't nest +and can't be used inside the other match rules. Redundant match rules or rules +that conflict with one another should not be used inside of ``any``. + +Clang supports the following match rules: + +- ``function``: Can be used to apply attributes to functions. This includes C++ + member functions, static functions, operators, and constructors/destructors. + +- ``function(is_member)``: Can be used to apply attributes to C++ member + functions. This includes members like static functions, operators, and + constructors/destructors. + +- ``hasType(functionType)``: Can be used to apply attributes to functions, C++ + member functions, and variables/fields whose type is a function pointer. It + does not apply attributes to Objective-C methods or blocks. + +- ``type_alias``: Can be used to apply attributes to ``typedef`` declarations + and C++11 type aliases. + +- ``record``: Can be used to apply attributes to ``struct``, ``class``, and + ``union`` declarations. + +- ``record(unless(is_union))``: Can be used to apply attributes only to + ``struct`` and ``class`` declarations. + +- ``enum``: Can be be used to apply attributes to enumeration declarations. + +- ``enum_constant``: Can be used to apply attributes to enumerators. + +- ``variable``: Can be used to apply attributes to variables, including + local variables, parameters, global variables, and static member variables. + It does not apply attributes to instance member variables or Objective-C + ivars. + +- ``variable(is_thread_local)``: Can be used to apply attributes to thread-local + variables only. + +- ``variable(is_global)``: Can be used to apply attributes to global variables + only. + +- ``variable(is_parameter)``: Can be used to apply attributes to parameters + only. + +- ``variable(unless(is_parameter))``: Can be used to apply attributes to all + the variables that are not parameters. + +- ``field``: Can be used to apply attributes to non-static member variables + in a record. This includes Objective-C ivars. + +- ``namespace``: Can be used to apply attributes to ``namespace`` declarations. + +- ``objc_interface``: Can be used to apply attributes to ``@interface`` + declarations. + +- ``objc_protocol``: Can be used to apply attributes to ``@protocol`` + declarations. + +- ``objc_category``: Can be used to apply attributes to category declarations, + including class extensions. + +- ``objc_method``: Can be used to apply attributes to Objective-C methods, + including instance and class methods. Implicit methods like implicit property + getters and setters do not receive the attribute. + +- ``objc_method(is_instance)``: Can be used to apply attributes to Objective-C + instance methods. + +- ``objc_property``: Can be used to apply attributes to ``@property`` + declarations. + +- ``block``: Can be used to apply attributes to block declarations. This does + not include variables/fields of block pointer type. + +The use of ``unless`` in match rules is currently restricted to a strict set of +sub-rules that are used by the supported attributes. That means that even though +``variable(unless(is_parameter))`` is a valid match rule, +``variable(unless(is_thread_local))`` is not. + +Supported Attributes +-------------------- + +Not all attributes can be used with the ``#pragma clang attribute`` directive. +Notably, statement attributes like ``[[fallthrough]]`` or type attributes +like ``address_space`` aren't supported by this directive. You can determine +whether or not an attribute is supported by the pragma by referring to the +:doc:`individual documentation for that attribute <AttributeReference>`. + +The attributes are applied to all matching declarations individually, even when +the attribute is semantically incorrect. The attributes that aren't applied to +any declaration are not verified semantically. diff --git a/docs/SanitizerCoverage.rst b/docs/SanitizerCoverage.rst index 8ff5bdf3a3d2..d69afba4daca 100644 --- a/docs/SanitizerCoverage.rst +++ b/docs/SanitizerCoverage.rst @@ -25,17 +25,10 @@ following compile-time flags: **extra** slowdown). * ``-fsanitize-coverage=edge`` for edge-level coverage (up to 40% slowdown). -You may also specify ``-fsanitize-coverage=indirect-calls`` for -additional `caller-callee coverage`_. - At run time, pass ``coverage=1`` in ``ASAN_OPTIONS``, ``LSAN_OPTIONS``, ``MSAN_OPTIONS`` or ``UBSAN_OPTIONS``, as appropriate. For the standalone coverage mode, use ``UBSAN_OPTIONS``. -To get `Coverage counters`_, add ``-fsanitize-coverage=8bit-counters`` -to one of the above compile-time flags. At runtime, use -``*SAN_OPTIONS=coverage=1:coverage_counters=1``. - Example: .. code-block:: console @@ -199,135 +192,9 @@ edges by introducing new dummy blocks and then instruments those blocks: |/ C -Bitset -====== - -When ``coverage_bitset=1`` run-time flag is given, the coverage will also be -dumped as a bitset (text file with 1 for blocks that have been executed and 0 -for blocks that were not). - -.. code-block:: console - - % clang++ -fsanitize=address -fsanitize-coverage=edge cov.cc - % ASAN_OPTIONS="coverage=1:coverage_bitset=1" ./a.out - main - % ASAN_OPTIONS="coverage=1:coverage_bitset=1" ./a.out 1 - foo - main - % head *bitset* - ==> a.out.38214.bitset-sancov <== - 01101 - ==> a.out.6128.bitset-sancov <== - 11011% - -For a given executable the length of the bitset is always the same (well, -unless dlopen/dlclose come into play), so the bitset coverage can be -easily used for bitset-based corpus distillation. - -Caller-callee coverage -====================== - -**Deprecated, don't use** - -Every indirect function call is instrumented with a run-time function call that -captures caller and callee. At the shutdown time the process dumps a separate -file called ``caller-callee.PID.sancov`` which contains caller/callee pairs as -pairs of lines (odd lines are callers, even lines are callees) - -.. code-block:: console - - a.out 0x4a2e0c - a.out 0x4a6510 - a.out 0x4a2e0c - a.out 0x4a87f0 - -Current limitations: - -* Only the first 14 callees for every caller are recorded, the rest are silently - ignored. -* The output format is not very compact since caller and callee may reside in - different modules and we need to spell out the module names. -* The routine that dumps the output is not optimized for speed -* Only Linux x86_64 is tested so far. -* Sandboxes are not supported. - -Coverage counters -================= - -**Deprecated, don't use** - -This experimental feature is inspired by -`AFL <http://lcamtuf.coredump.cx/afl/technical_details.txt>`__'s coverage -instrumentation. With additional compile-time and run-time flags you can get -more sensitive coverage information. In addition to boolean values assigned to -every basic block (edge) the instrumentation will collect imprecise counters. -On exit, every counter will be mapped to a 8-bit bitset representing counter -ranges: ``1, 2, 3, 4-7, 8-15, 16-31, 32-127, 128+`` and those 8-bit bitsets will -be dumped to disk. - -.. code-block:: console - - % clang++ -g cov.cc -fsanitize=address -fsanitize-coverage=edge,8bit-counters - % ASAN_OPTIONS="coverage=1:coverage_counters=1" ./a.out - % ls -l *counters-sancov - ... a.out.17110.counters-sancov - % xxd *counters-sancov - 0000000: 0001 0100 01 - -These counters may also be used for in-process coverage-guided fuzzers. See -``include/sanitizer/coverage_interface.h``: - -.. code-block:: c++ - - // The coverage instrumentation may optionally provide imprecise counters. - // Rather than exposing the counter values to the user we instead map - // the counters to a bitset. - // Every counter is associated with 8 bits in the bitset. - // We define 8 value ranges: 1, 2, 3, 4-7, 8-15, 16-31, 32-127, 128+ - // The i-th bit is set to 1 if the counter value is in the i-th range. - // This counter-based coverage implementation is *not* thread-safe. - - // Returns the number of registered coverage counters. - uintptr_t __sanitizer_get_number_of_counters(); - // Updates the counter 'bitset', clears the counters and returns the number of - // new bits in 'bitset'. - // If 'bitset' is nullptr, only clears the counters. - // Otherwise 'bitset' should be at least - // __sanitizer_get_number_of_counters bytes long and 8-aligned. - uintptr_t - __sanitizer_update_counter_bitset_and_clear_counters(uint8_t *bitset); - -Tracing basic blocks -==================== - -**Deprecated, don't use** - -Experimental support for basic block (or edge) tracing. -With ``-fsanitize-coverage=trace-bb`` the compiler will insert -``__sanitizer_cov_trace_basic_block(s32 *id)`` before every function, basic block, or edge -(depending on the value of ``-fsanitize-coverage=[func,bb,edge]``). -Example: - -.. code-block:: console - - % clang -g -fsanitize=address -fsanitize-coverage=edge,trace-bb foo.cc - % ASAN_OPTIONS=coverage=1 ./a.out - -This will produce two files after the process exit: -`trace-points.PID.sancov` and `trace-events.PID.sancov`. -The first file will contain a textual description of all the instrumented points in the program -in the form that you can feed into llvm-symbolizer (e.g. `a.out 0x4dca89`), one per line. -The second file will contain the actual execution trace as a sequence of 4-byte integers --- these integers are the indices into the array of instrumented points (the first file). - -Basic block tracing is currently supported only for single-threaded applications. - - Tracing PCs =========== -**Deprecated, don't use** - *Experimental* feature similar to tracing basic blocks, but with a different API. With ``-fsanitize-coverage=trace-pc`` the compiler will insert ``__sanitizer_cov_trace_pc()`` on every edge. @@ -529,62 +396,3 @@ memory-mapped file as soon as it collected. Note that on 64-bit platforms, this method writes 2x more data than the default, because it stores full PC values instead of 32-bit offsets. -In-process fuzzing -================== - -Coverage data could be useful for fuzzers and sometimes it is preferable to run -a fuzzer in the same process as the code being fuzzed (in-process fuzzer). - -You can use ``__sanitizer_get_total_unique_coverage()`` from -``<sanitizer/coverage_interface.h>`` which returns the number of currently -covered entities in the program. This will tell the fuzzer if the coverage has -increased after testing every new input. - -If a fuzzer finds a bug in the ASan run, you will need to save the reproducer -before exiting the process. Use ``__asan_set_death_callback`` from -``<sanitizer/asan_interface.h>`` to do that. - -An example of such fuzzer can be found in `the LLVM tree -<http://llvm.org/viewvc/llvm-project/llvm/trunk/lib/Fuzzer/README.txt?view=markup>`_. - -Performance -=========== - -This coverage implementation is **fast**. With function-level coverage -(``-fsanitize-coverage=func``) the overhead is not measurable. With -basic-block-level coverage (``-fsanitize-coverage=bb``) the overhead varies -between 0 and 25%. - -============== ========= ========= ========= ========= ========= ========= - benchmark cov0 cov1 diff 0-1 cov2 diff 0-2 diff 1-2 -============== ========= ========= ========= ========= ========= ========= - 400.perlbench 1296.00 1307.00 1.01 1465.00 1.13 1.12 - 401.bzip2 858.00 854.00 1.00 1010.00 1.18 1.18 - 403.gcc 613.00 617.00 1.01 683.00 1.11 1.11 - 429.mcf 605.00 582.00 0.96 610.00 1.01 1.05 - 445.gobmk 896.00 880.00 0.98 1050.00 1.17 1.19 - 456.hmmer 892.00 892.00 1.00 918.00 1.03 1.03 - 458.sjeng 995.00 1009.00 1.01 1217.00 1.22 1.21 -462.libquantum 497.00 492.00 0.99 534.00 1.07 1.09 - 464.h264ref 1461.00 1467.00 1.00 1543.00 1.06 1.05 - 471.omnetpp 575.00 590.00 1.03 660.00 1.15 1.12 - 473.astar 658.00 652.00 0.99 715.00 1.09 1.10 - 483.xalancbmk 471.00 491.00 1.04 582.00 1.24 1.19 - 433.milc 616.00 627.00 1.02 627.00 1.02 1.00 - 444.namd 602.00 601.00 1.00 654.00 1.09 1.09 - 447.dealII 630.00 634.00 1.01 653.00 1.04 1.03 - 450.soplex 365.00 368.00 1.01 395.00 1.08 1.07 - 453.povray 427.00 434.00 1.02 495.00 1.16 1.14 - 470.lbm 357.00 375.00 1.05 370.00 1.04 0.99 - 482.sphinx3 927.00 928.00 1.00 1000.00 1.08 1.08 -============== ========= ========= ========= ========= ========= ========= - -Why another coverage? -===================== - -Why did we implement yet another code coverage? - * We needed something that is lightning fast, plays well with - AddressSanitizer, and does not significantly increase the binary size. - * Traditional coverage implementations based in global counters - `suffer from contention on counters - <https://groups.google.com/forum/#!topic/llvm-dev/cDqYgnxNEhY>`_. diff --git a/docs/doxygen.cfg.in b/docs/doxygen.cfg.in index ef96605ed1c1..13ed72222bea 100644 --- a/docs/doxygen.cfg.in +++ b/docs/doxygen.cfg.in @@ -132,7 +132,7 @@ INLINE_INHERITED_MEMB = NO # shortest path that makes the file name unique will be used # The default value is: YES. -FULL_PATH_NAMES = NO +FULL_PATH_NAMES = YES # The STRIP_FROM_PATH tag can be used to strip a user-defined part of the path. # Stripping is only done if one of the specified strings matches the left-hand @@ -144,7 +144,7 @@ FULL_PATH_NAMES = NO # will be relative from the directory where doxygen is started. # This tag requires that the tag FULL_PATH_NAMES is set to YES. -STRIP_FROM_PATH = ../.. +STRIP_FROM_PATH = @abs_srcdir@/.. # The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of the # path mentioned in the documentation of a class, which tells the reader which @@ -153,7 +153,7 @@ STRIP_FROM_PATH = ../.. # specify the list of include paths that are normally passed to the compiler # using the -I flag. -STRIP_FROM_INC_PATH = +STRIP_FROM_INC_PATH = @abs_srcdir@/../include # If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter (but # less readable) file names. This can be useful is your file systems doesn't @@ -513,7 +513,7 @@ SHOW_GROUPED_MEMB_INC = NO # files with double quotes in the documentation rather than with sharp brackets. # The default value is: NO. -FORCE_LOCAL_INCLUDES = NO +FORCE_LOCAL_INCLUDES = YES # If the INLINE_INFO tag is set to YES then a tag [inline] is inserted in the # documentation for inline members. |