coverage

package
v0.0.0-...-a858404 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jan 23, 2024 License: Apache-2.0, MIT Imports: 8 Imported by: 0

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.

Using coverdata.Counters requires sync/atomic integers. +checkalignedignore

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Available

func Available() bool

Available returns whether any coverage data is available.

func ClearCoverageData

func ClearCoverageData()

ClearCoverageData clears existing coverage data.

func ConsumeCoverageData

func ConsumeCoverageData(w io.Writer) int

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 EnableReport

func EnableReport(w io.WriteCloser)

EnableReport sets up coverage reporting.

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 Symbolize

func Symbolize(out io.Writer, pc uint64) error

Symbolize prints information about the block corresponding to pc.

func WriteAllBlocks

func WriteAllBlocks(out io.Writer) error

WriteAllBlocks prints all information about all blocks along with their corresponding synthetic PCs.

Types

This section is empty.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL