blob: 340ac9563559d016ca2f42189284b143d50d52e7 [file] [log] [blame]
// Copyright 2022 The Go Authors. All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
package coverage
// Types and constants related to the output files written
// by code coverage tooling. When a coverage-instrumented binary
// is run, it emits two output files: a meta-data output file, and
// a counter data output file.
//.....................................................................
//
// Meta-data definitions:
//
// The meta-data file is composed of a file header, a series of
// meta-data blobs/sections (one per instrumented package), and an offsets
// area storing the offsets of each section. Format of the meta-data
// file looks like:
//
// --header----------
// | magic: [4]byte magic string
// | version
// | total length of meta-data file in bytes
// | numPkgs: number of package entries in file
// | hash: [16]byte hash of entire meta-data payload
// | offset to string table section
// | length of string table
// | number of entries in string table
// | counter mode
// | counter granularity
// --package offsets table------
// <offset to pkg 0>
// <offset to pkg 1>
// ...
// --package lengths table------
// <length of pkg 0>
// <length of pkg 1>
// ...
// --string table------
// <uleb128 len> 8
// <data> "somestring"
// ...
// --package payloads------
// <meta-symbol for pkg 0>
// <meta-symbol for pkg 1>
// ...
//
// Each package payload is a stand-alone blob emitted by the compiler,
// and does not depend on anything else in the meta-data file. In
// particular, each blob has it's own string table. Note that the
// file-level string table is expected to be very short (most strings
// will be in the meta-data blobs themselves).
// CovMetaMagic holds the magic string for a meta-data file.
var CovMetaMagic = [4]byte{'\x00', '\x63', '\x76', '\x6d'}
// MetaFilePref is a prefix used when emitting meta-data files; these
// files are of the form "covmeta.<hash>", where hash is a hash
// computed from the hashes of all the package meta-data symbols in
// the program.
const MetaFilePref = "covmeta"
// MetaFileVersion contains the current (most recent) meta-data file version.
const MetaFileVersion = 1
// MetaFileHeader stores file header information for a meta-data file.
type MetaFileHeader struct {
Magic [4]byte
Version uint32
TotalLength uint64
Entries uint64
MetaFileHash [16]byte
StrTabOffset uint32
StrTabLength uint32
CMode CounterMode
CGranularity CounterGranularity
_ [6]byte // padding
}
// MetaSymbolHeader stores header information for a single
// meta-data blob, e.g. the coverage meta-data payload
// computed for a given Go package.
type MetaSymbolHeader struct {
Length uint32 // size of meta-symbol payload in bytes
PkgName uint32 // string table index
PkgPath uint32 // string table index
ModulePath uint32 // string table index
MetaHash [16]byte
_ byte // currently unused
_ [3]byte // padding
NumFiles uint32
NumFuncs uint32
}
const CovMetaHeaderSize = 16 + 4 + 4 + 4 + 4 + 4 + 4 + 4 // keep in sync with above
// As an example, consider the following Go package:
//
// 01: package p
// 02:
// 03: var v, w, z int
// 04:
// 05: func small(x, y int) int {
// 06: v++
// 07: // comment
// 08: if y == 0 {
// 09: return x
// 10: }
// 11: return (x << 1) ^ (9 / y)
// 12: }
// 13:
// 14: func Medium(q, r int) int {
// 15: s1 := small(q, r)
// 16: z += s1
// 17: s2 := small(r, q)
// 18: w -= s2
// 19: return w + z
// 20: }
//
// The meta-data blob for the single package above might look like the
// following:
//
// -- MetaSymbolHeader header----------
// | size: size of this blob in bytes
// | packagepath: <path to p>
// | modulepath: <modpath for p>
// | nfiles: 1
// | nfunctions: 2
// --func offsets table------
// <offset to func 0>
// <offset to func 1>
// --string table (contains all files and functions)------
// | <uleb128 len> 4
// | <data> "p.go"
// | <uleb128 len> 5
// | <data> "small"
// | <uleb128 len> 6
// | <data> "Medium"
// --func 0------
// | <uleb128> num units: 3
// | <uleb128> func name: S1 (index into string table)
// | <uleb128> file: S0 (index into string table)
// | <unit 0>: S0 L6 L8 2
// | <unit 1>: S0 L9 L9 1
// | <unit 2>: S0 L11 L11 1
// --func 1------
// | <uleb128> num units: 1
// | <uleb128> func name: S2 (index into string table)
// | <uleb128> file: S0 (index into string table)
// | <unit 0>: S0 L15 L19 5
// ---end-----------
// The following types and constants used by the meta-data encoder/decoder.
// FuncDesc encapsulates the meta-data definitions for a single Go function.
// This version assumes that we're looking at a function before inlining;
// if we want to capture a post-inlining view of the world, the
// representations of source positions would need to be a good deal more
// complicated.
type FuncDesc struct {
Funcname string
Srcfile string
Units []CoverableUnit
Lit bool // true if this is a function literal
}
// CoverableUnit describes the source characteristics of a single
// program unit for which we want to gather coverage info. Coverable
// units are either "simple" or "intraline"; a "simple" coverable unit
// corresponds to a basic block (region of straight-line code with no
// jumps or control transfers). An "intraline" unit corresponds to a
// logical clause nested within some other simple unit. A simple unit
// will have a zero Parent value; for an intraline unit NxStmts will
// be zero and Parent will be set to 1 plus the index of the
// containing simple statement. Example:
//
// L7: q := 1
// L8: x := (y == 101 || launch() == false)
// L9: r := x * 2
//
// For the code above we would have three simple units (one for each
// line), then an intraline unit describing the "launch() == false"
// clause in line 8, with Parent pointing to the index of the line 8
// unit in the units array.
//
// Note: in the initial version of the coverage revamp, only simple
// units will be in use.
type CoverableUnit struct {
StLine, StCol uint32
EnLine, EnCol uint32
NxStmts uint32
Parent uint32
}
// CounterMode tracks the "flavor" of the coverage counters being
// used in a given coverage-instrumented program.
type CounterMode uint8
const (
CtrModeInvalid CounterMode = iota
CtrModeSet // "set" mode
CtrModeCount // "count" mode
CtrModeAtomic // "atomic" mode
CtrModeRegOnly // registration-only pseudo-mode
CtrModeTestMain // testmain pseudo-mode
)
func (cm CounterMode) String() string {
switch cm {
case CtrModeSet:
return "set"
case CtrModeCount:
return "count"
case CtrModeAtomic:
return "atomic"
case CtrModeRegOnly:
return "regonly"
case CtrModeTestMain:
return "testmain"
}
return "<invalid>"
}
func ParseCounterMode(mode string) CounterMode {
var cm CounterMode
switch mode {
case "set":
cm = CtrModeSet
case "count":
cm = CtrModeCount
case "atomic":
cm = CtrModeAtomic
case "regonly":
cm = CtrModeRegOnly
case "testmain":
cm = CtrModeTestMain
default:
cm = CtrModeInvalid
}
return cm
}
// CounterGranularity tracks the granularity of the coverage counters being
// used in a given coverage-instrumented program.
type CounterGranularity uint8
const (
CtrGranularityInvalid CounterGranularity = iota
CtrGranularityPerBlock
CtrGranularityPerFunc
)
func (cm CounterGranularity) String() string {
switch cm {
case CtrGranularityPerBlock:
return "perblock"
case CtrGranularityPerFunc:
return "perfunc"
}
return "<invalid>"
}
// Name of file within the "go test -cover" temp coverdir directory
// containing a list of meta-data files for packages being tested
// in a "go test -coverpkg=... ..." run. This constant is shared
// by the Go command and by the coverage runtime.
const MetaFilesFileName = "metafiles.txt"
// MetaFilePaths contains information generated by the Go command and
// the read in by coverage test support functions within an executing
// "go test -cover" binary.
type MetaFileCollection struct {
ImportPaths []string
MetaFileFragments []string
}
//.....................................................................
//
// Counter data definitions:
//
// A counter data file is composed of a file header followed by one or
// more "segments" (each segment representing a given run or partial
// run of a give binary) followed by a footer.
// CovCounterMagic holds the magic string for a coverage counter-data file.
var CovCounterMagic = [4]byte{'\x00', '\x63', '\x77', '\x6d'}
// CounterFileVersion stores the most recent counter data file version.
const CounterFileVersion = 1
// CounterFileHeader stores files header information for a counter-data file.
type CounterFileHeader struct {
Magic [4]byte
Version uint32
MetaHash [16]byte
CFlavor CounterFlavor
BigEndian bool
_ [6]byte // padding
}
// CounterSegmentHeader encapsulates information about a specific
// segment in a counter data file, which at the moment contains
// counters data from a single execution of a coverage-instrumented
// program. Following the segment header will be the string table and
// args table, and then (possibly) padding bytes to bring the byte
// size of the preamble up to a multiple of 4. Immediately following
// that will be the counter payloads.
//
// The "args" section of a segment is used to store annotations
// describing where the counter data came from; this section is
// basically a series of key-value pairs (can be thought of as an
// encoded 'map[string]string'). At the moment we only write os.Args()
// data to this section, using pairs of the form "argc=<integer>",
// "argv0=<os.Args[0]>", "argv1=<os.Args[1]>", and so on. In the
// future the args table may also include things like GOOS/GOARCH
// values, and/or tags indicating which tests were run to generate the
// counter data.
type CounterSegmentHeader struct {
FcnEntries uint64
StrTabLen uint32
ArgsLen uint32
}
// CounterFileFooter appears at the tail end of a counter data file,
// and stores the number of segments it contains.
type CounterFileFooter struct {
Magic [4]byte
_ [4]byte // padding
NumSegments uint32
_ [4]byte // padding
}
// CounterFilePref is the file prefix used when emitting coverage data
// output files. CounterFileTemplate describes the format of the file
// name: prefix followed by meta-file hash followed by process ID
// followed by emit UnixNanoTime.
const CounterFilePref = "covcounters"
const CounterFileTempl = "%s.%x.%d.%d"
const CounterFileRegexp = `^%s\.(\S+)\.(\d+)\.(\d+)+$`
// CounterFlavor describes how function and counters are
// stored/represented in the counter section of the file.
type CounterFlavor uint8
const (
// "Raw" representation: all values (pkg ID, func ID, num counters,
// and counters themselves) are stored as uint32's.
CtrRaw CounterFlavor = iota + 1
// "ULeb" representation: all values (pkg ID, func ID, num counters,
// and counters themselves) are stored with ULEB128 encoding.
CtrULeb128
)
func Round4(x int) int {
return (x + 3) &^ 3
}
//.....................................................................
//
// Runtime counter data definitions.
//
// At runtime within a coverage-instrumented program, the "counters"
// object we associated with instrumented function can be thought of
// as a struct of the following form:
//
// struct {
// numCtrs uint32
// pkgid uint32
// funcid uint32
// counterArray [numBlocks]uint32
// }
//
// where "numCtrs" is the number of blocks / coverable units within the
// function, "pkgid" is the unique index assigned to this package by
// the runtime, "funcid" is the index of this function within its containing
// package, and "counterArray" stores the actual counters.
//
// The counter variable itself is created not as a struct but as a flat
// array of uint32's; we then use the offsets below to index into it.
const NumCtrsOffset = 0
const PkgIdOffset = 1
const FuncIdOffset = 2
const FirstCtrOffset = 3