Documentation
¶
Overview ¶
Package coverage provides an interface through which Go coverage data can be collected, converted to kcov format, and exposed to userspace.
Coverage can be enabled by calling bazel {build,test} with --collect_coverage_data and --instrumentation_filter with the desired coverage surface. This causes bazel to use the Go cover tool manually to generate instrumented files. It injects a hook that registers all coverage data with the coverdata package.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ConsumeCoverageData ¶
ConsumeCoverageData builds and writes the collection of covered PCs. It returns the number of bytes written.
In Linux, a kernel configuration is set that compiles the kernel with a custom function that is called at the beginning of every basic block, which updates the memory-mapped coverage information. The Go coverage tool does not allow us to inject arbitrary instructions into basic blocks, but it does provide data that we can convert to a kcov-like format and transfer them to userspace through a memory mapping.
Note that this is not a strict implementation of kcov, which is especially tricky to do because we do not have the same coverage tools available in Go that that are available for the actual Linux kernel. In Linux, a kernel configuration is set that compiles the kernel with a custom function that is called at the beginning of every basic block to write program counters to the kcov memory mapping. In Go, however, coverage tools only give us a count of basic blocks as they are executed. Every time we return to userspace, we collect the coverage information and write out PCs for each block that was executed, providing userspace with the illusion that the kcov data is always up to date. For convenience, we also generate a unique synthetic PC for each block instead of using actual PCs. Finally, we do not provide thread-specific coverage data (each kcov instance only contains PCs executed by the thread owning it); instead, we will supply data for any file specified by -- instrumentation_filter.
Note that we "consume", i.e. clear, coverdata when this function is run, to ensure that each event is only reported once. Due to the limitations of Go coverage tools, we reset the global coverage data every time this function is run.
func InitCoverageData ¶
func InitCoverageData()
InitCoverageData initializes globalData. It should be called before any kcov data is written.
func KcovSupported ¶
func KcovSupported() bool
KcovSupported returns whether the kcov interface should be made available.
If coverage reporting is on, do not turn on kcov, which will consume coverage data.
func Report ¶
func Report() error
Report writes out a coverage report with all blocks that have been covered.
TODO(b/144576401): Decide whether this should actually be in LCOV format
func WriteAllBlocks ¶
WriteAllBlocks prints all information about all blocks along with their corresponding synthetic PCs.
Types ¶
This section is empty.
Source Files