summaryrefslogtreecommitdiff
path: root/clang/docs/SourceBasedCodeCoverage.rst
AgeCommit message (Collapse)Author
2025-08-18[clang] Proofread SourceBasedCodeCoverage.rst (#154050)Kazu Hirata
2025-02-06[profile] Add `%b` `LLVM_PROFILE_FILE` option for binary ID (#123963)Sinkevich Artem
Add support for expanding `%b` in `LLVM_PROFILE_FILE` to the binary ID (build ID). It can be used with `%m` to avoid its signature collisions. This is supported on all platforms where writing binary IDs into profiles is implemented, as the `__llvm_write_binary_ids` function is used. Fixes #51560.
2024-06-14Reapply: [MC/DC][Coverage] Loosen the limit of NumConds from 6 (#82448)NAKAMURA Takumi
By storing possible test vectors instead of combinations of conditions, the restriction is dramatically relaxed. This introduces two options to `cc1`: * `-fmcdc-max-conditions=32767` * `-fmcdc-max-test-vectors=2147483646` This change makes coverage mapping, profraw, and profdata incompatible with Clang-18. - Bitmap semantics changed. It is incompatible with previous format. - `BitmapIdx` in `Decision` points to the end of the bitmap. - Bitmap is packed per function. - `llvm-cov` can understand `profdata` generated by `llvm-profdata-18`. RFC: https://discourse.llvm.org/t/rfc-coverage-new-algorithm-and-file-format-for-mc-dc/76798 -- Change(s) since llvmorg-19-init-14288-g7ead2d8c7e91 - Update compiler-rt/test/profile/ContinuousSyncMode/image-with-mcdc.c
2024-06-14Revert "[MC/DC][Coverage] Loosen the limit of NumConds from 6 (#82448)"Hans Wennborg
This broke the lit tests on Mac: https://green.lab.llvm.org/job/llvm.org/job/clang-stage1-RA/1096/ > By storing possible test vectors instead of combinations of conditions, > the restriction is dramatically relaxed. > > This introduces two options to `cc1`: > > * `-fmcdc-max-conditions=32767` > * `-fmcdc-max-test-vectors=2147483646` > > This change makes coverage mapping, profraw, and profdata incompatible > with Clang-18. > > - Bitmap semantics changed. It is incompatible with previous format. > - `BitmapIdx` in `Decision` points to the end of the bitmap. > - Bitmap is packed per function. > - `llvm-cov` can understand `profdata` generated by `llvm-profdata-18`. > > RFC: > https://discourse.llvm.org/t/rfc-coverage-new-algorithm-and-file-format-for-mc-dc/76798 This reverts commit 7ead2d8c7e9114b3f23666209a1654939987cb30.
2024-06-13[MC/DC][Coverage] Loosen the limit of NumConds from 6 (#82448)NAKAMURA Takumi
By storing possible test vectors instead of combinations of conditions, the restriction is dramatically relaxed. This introduces two options to `cc1`: * `-fmcdc-max-conditions=32767` * `-fmcdc-max-test-vectors=2147483646` This change makes coverage mapping, profraw, and profdata incompatible with Clang-18. - Bitmap semantics changed. It is incompatible with previous format. - `BitmapIdx` in `Decision` points to the end of the bitmap. - Bitmap is packed per function. - `llvm-cov` can understand `profdata` generated by `llvm-profdata-18`. RFC: https://discourse.llvm.org/t/rfc-coverage-new-algorithm-and-file-format-for-mc-dc/76798
2024-01-22[clang][NFC] Update top-level Code Coverage documentation to include MC/DC.Alan Phipps
2023-06-26[clang][NFC] Remove trailing whitespaces and enforce it in lib, include and docsNikolas Klauser
A lot of editors remove trailing whitespaces. This patch removes any trailing whitespaces and makes sure that no new ones are added. Reviewed By: erichkeane, paulkirth, #libc, philnik Spies: wangpc, aheejin, MaskRay, pcwang-thead, cfe-commits, libcxx-commits, dschuff, nemanjai, arichardson, kbarton, asb, rbar, johnrusso, simoncook, sabuasal, niosHD, jrtc27, zzheng, edward-jones, rogfer01, MartinMosbeck, brucehoult, the_o, PkmX, jocewei, Jim, s.egerton, sameer.abuasal, apazos, luismarques, martong, frasercrmck, steakhal, luke Differential Revision: https://reviews.llvm.org/D151963
2023-05-11Remove outdated sentence in SourceBasedCodeCoverage.rstZequan Wu
https://reviews.llvm.org/rGc5b94ea265133a4a28006929643155fc8fbeafe6 allows N >= 10.
2023-01-28Fix Clang sphinx buildAaron Ballman
This addresses the issue found in: https://lab.llvm.org/buildbot/#/builders/92/builds/39306
2023-01-27Added a note that "%p" is also a Lit token and needs to be escaped.Flash Sheridan
Differential revision: https://reviews.llvm.org/D140730
2023-01-27Explain code coverage with Lit in docs/SourceBasedCodeCoverage.rstFlash Sheridan
The documentation for code coverage in clang/docs/SourceBasedCodeCoverage.rst omits a couple of crucial steps when using it with Lit. This patch should fix that. Differential revision: https://reviews.llvm.org/D140730
2021-04-22Coverage: Document how to collect a profile without a filesystemDuncan P. N. Exon Smith
The profiling runtime was designed to work without static initializers or a a filesystem (see 117cf2bd1ff585f9754b5f30f5a4cfd65b230bbf and others). The no-static-initializers part was already documented but this part got missed before. Differential Revision: https://reviews.llvm.org/D101000
2021-02-12[docs/Coverage] Document -show-region-summaryVedant Kumar
As a drive-by, fix the section in the clang docs about the number of statistics visible in a report.
2021-02-12[docs/Coverage] Answer FAQ about optimizationVedant Kumar
2021-01-26Revert "Support for instrumenting only selected files or functions"Petr Hosek
This reverts commit 4edf35f11a9e20bd5df3cb47283715f0ff38b751 because the test fails on Windows bots.
2021-01-26Support for instrumenting only selected files or functionsPetr Hosek
This change implements support for applying profile instrumentation only to selected files or functions. The implementation uses the sanitizer special case list format to select which files and functions to instrument, and relies on the new noprofile IR attribute to exclude functions from instrumentation. Differential Revision: https://reviews.llvm.org/D94820
2021-01-05[Coverage] Add support for Branch Coverage in LLVM Source-Based Code CoverageAlan Phipps
This is an enhancement to LLVM Source-Based Code Coverage in clang to track how many times individual branch-generating conditions are taken (evaluate to TRUE) and not taken (evaluate to FALSE). Individual conditions may comprise larger boolean expressions using boolean logical operators. This functionality is very similar to what is supported by GCOV except that it is very closely anchored to the ASTs. Differential Revision: https://reviews.llvm.org/D84467
2020-09-25[profile] Add %t LLVM_PROFILE_FILE option to substitute $TMPDIRVedant Kumar
Add support for expanding the %t filename specifier in LLVM_PROFILE_FILE to the TMPDIR environment variable. This is supported on all platforms. On Darwin, TMPDIR is used to specify a temporary application-specific scratch directory. When testing apps on remote devices, it can be challenging for the host device to determine the correct TMPDIR, so it's helpful to have the runtime do this work. rdar://68524185 Differential Revision: https://reviews.llvm.org/D87332
2020-02-10fix some typos to cycle botsNico Weber
2020-01-17[profile] Support counter relocation at runtimePetr Hosek
This is an alternative to the continous mode that was implemented in D68351. This mode relies on padding and the ability to mmap a file over the existing mapping which is generally only available on POSIX systems and isn't suitable for other platforms. This change instead introduces the ability to relocate counters at runtime using a level of indirection. On every counter access, we add a bias to the counter address. This bias is stored in a symbol that's provided by the profile runtime and is initially set to zero, meaning no relocation. The runtime can mmap the profile into memory at abitrary location, and set bias to the offset between the original and the new counter location, at which point every subsequent counter access will be to the new location, which allows updating profile directly akin to the continous mode. The advantage of this implementation is that doesn't require any special OS support. The disadvantage is the extra overhead due to additional instructions required for each counter access (overhead both in terms of binary size and performance) plus duplication of counters (i.e. one copy in the binary itself and another copy that's mmapped). Differential Revision: https://reviews.llvm.org/D69740
2019-12-03[Coverage] Emit a gap region to cover switch bodiesVedant Kumar
Emit a gap region beginning where the switch body begins. This sets line execution counts in the areas between non-overlapping cases to 0. This also removes some special handling of the first case in a switch: these are now treated like any other case. This does not resolve an outstanding issue with case statement regions that do not end when a region is terminated. But it should address llvm.org/PR44011. Differential Revision: https://reviews.llvm.org/D70571
2019-11-18[profile] Support online merging with continuous sync modeVedant Kumar
Make it possible to use online profile merging ("%m" mode) with continuous sync ("%c" mode). To implement this, the merged profile is locked in the runtime initialization step and either a) filled out for the first time or b) checked for compatibility. Then, the profile can simply be mmap()'d with MAP_SHARED set. With the mmap() in place, counter updates from every process which uses an image are mapped onto the same set of physical pages assigned by the filesystem cache. After the mmap() is set up, the profile is unlocked. Differential Revision: https://reviews.llvm.org/D69586
2019-10-31[profile] Add a mode to continuously sync counter updates to a fileVedant Kumar
Add support for continuously syncing profile counter updates to a file. The motivation for this is that programs do not always exit cleanly. On iOS, for example, programs are usually killed via a signal from the OS. Running atexit() handlers after catching a signal is unreliable, so some method for progressively writing out profile data is necessary. The approach taken here is to mmap() the `__llvm_prf_cnts` section onto a raw profile. To do this, the linker must page-align the counter and data sections, and the runtime must ensure that counters are mapped to a page-aligned offset within a raw profile. Continuous mode is (for the moment) incompatible with the online merging mode. This limitation is lifted in https://reviews.llvm.org/D69586. Continuous mode is also (for the moment) incompatible with value profiling, as I'm not sure whether there is interest in this and the implementation may be tricky. As I have not been able to test extensively on non-Darwin platforms, only Darwin support is included for the moment. However, continuous mode may "just work" without modification on Linux and some UNIX-likes. AIUI the default value for the GNU linker's `--section-alignment` flag is set to the page size on many systems. This appears to be true for LLD as well, as its `no_nmagic` option is on by default. Continuous mode will not "just work" on Fuchsia or Windows, as it's not possible to mmap() a section on these platforms. There is a proposal to add a layer of indirection to the profile instrumentation to support these platforms. rdar://54210980 Differential Revision: https://reviews.llvm.org/D68351
2018-11-04Update our URLs in clang doc to use httpsSylvestre Ledru
llvm-svn: 346101
2017-06-19[docs] Coverage: Improve the wording a bitVedant Kumar
llvm-svn: 305745
2017-06-19[docs] Coverage: document issue with the BFD linkerVedant Kumar
llvm-svn: 305743
2017-02-09[docs] coverage: Clarify which flags enable gcov-style profiling (NFC)Vedant Kumar
Point out that --coverage and -ftest-coverage, which is what most people are used to, do not enable clang's frontend based coverage pass. Suggested by Benn Bolay! llvm-svn: 294626
2017-01-25Clarify how to forward-declare __llvm_profile symbols.Nico Weber
llvm-svn: 293065
2016-09-22[docs] Touch up the coverage docs some moreVedant Kumar
llvm-svn: 282169
2016-09-20[docs] Extend the code coverage docs some moreVedant Kumar
Flesh out the section on interpreting coverage reports, mention the coverage export feature, and add notes on how to build llvm with coverage turned on. llvm-svn: 281988
2016-09-19[docs] Touch up the code coverage docVedant Kumar
llvm-svn: 281881
2016-07-28[docs] Coverage: Reference the new -output-dir optionVedant Kumar
llvm-svn: 277081
2016-07-28[docs] Mention some new options in llvm-covVedant Kumar
llvm-svn: 277080
2016-07-02fix two typos in the docSylvestre Ledru
llvm-svn: 274447
2016-06-21[Docs] More warning fixes to unbreak the docs buildbot.George Burgess IV
A number of warnings still remain, but these were the last of the "unlexable code"-related ones (AFAICT). I changed a few examples in docs/UsersManual.rst to showcase -Wextra-tokens because it's already documented (-Wmultichar isn't), and the sphinx C lexer apparently can't handle char literals like 'ab'. It seemed like a better overall approach than just marking the code blocks as none or console. llvm-svn: 273232
2016-06-14[docs] Coverage: Document the profile merge pool specifierVedant Kumar
llvm-svn: 272604
2016-06-08[docs] Coverage: Clarify return value of __llvm_profile_write_fileVedant Kumar
llvm-svn: 272215
2016-06-08[docs] Coverage: Flesh out instructions for avoiding static initializeresVedant Kumar
llvm-svn: 272214
2016-06-07[docs] Coverage: Explain how to avoid static initializersVedant Kumar
llvm-svn: 272067
2016-06-06[docs] Clarify limitations section of SourceBasedCodeCoverage.rstVedant Kumar
Mention that the code coverage tool becomes less precise whenever unpredictable changes in control flow occur. Thanks to Sean Silva for pointing this out! llvm-svn: 271902
2016-06-02[docs] Add a limitations section to SourceBasedCodeCoverage.rstVedant Kumar
llvm-svn: 271544
2016-06-02[docs] Fix misplaced commaVedant Kumar
llvm-svn: 271472
2016-06-02[docs] Minor formatting changes and typo fixesVedant Kumar
llvm-svn: 271471
2016-06-02[docs] Use cpp code-blocks where appropriateVedant Kumar
llvm-svn: 271461
2016-06-02[docs] Add missing newline to console sectionVedant Kumar
llvm-svn: 271457
2016-06-02[docs] Document the source-based code coverage featureVedant Kumar
Differential Revision: http://reviews.llvm.org/D20715 llvm-svn: 271454