1 // Copyright 2022 The Go Authors. All rights reserved. 2 // Use of this source code is governed by a BSD-style 3 // license that can be found in the LICENSE file. 4 5 package coverage 6 7 import ( 8 "fmt" 9 "internal/coverage" 10 "io" 11 "sync/atomic" 12 "unsafe" 13 ) 14 15 // WriteMetaDir writes a coverage meta-data file for the currently 16 // running program to the directory specified in 'dir'. An error will 17 // be returned if the operation can't be completed successfully (for 18 // example, if the currently running program was not built with 19 // "-cover", or if the directory does not exist). 20 func WriteMetaDir(dir string) error { 21 if !finalHashComputed { 22 return fmt.Errorf("error: no meta-data available (binary not built with -cover?)") 23 } 24 return emitMetaDataToDirectory(dir, getCovMetaList()) 25 } 26 27 // WriteMeta writes the meta-data content (the payload that would 28 // normally be emitted to a meta-data file) for the currently running 29 // program to the writer 'w'. An error will be returned if the 30 // operation can't be completed successfully (for example, if the 31 // currently running program was not built with "-cover", or if a 32 // write fails). 33 func WriteMeta(w io.Writer) error { 34 if w == nil { 35 return fmt.Errorf("error: nil writer in WriteMeta") 36 } 37 if !finalHashComputed { 38 return fmt.Errorf("error: no meta-data available (binary not built with -cover?)") 39 } 40 ml := getCovMetaList() 41 return writeMetaData(w, ml, cmode, cgran, finalHash) 42 } 43 44 // WriteCountersDir writes a coverage counter-data file for the 45 // currently running program to the directory specified in 'dir'. An 46 // error will be returned if the operation can't be completed 47 // successfully (for example, if the currently running program was not 48 // built with "-cover", or if the directory does not exist). The 49 // counter data written will be a snapshot taken at the point of the 50 // call. 51 func WriteCountersDir(dir string) error { 52 if cmode != coverage.CtrModeAtomic { 53 return fmt.Errorf("WriteCountersDir invoked for program built with -covermode=%s (please use -covermode=atomic)", cmode.String()) 54 } 55 return emitCounterDataToDirectory(dir) 56 } 57 58 // WriteCounters writes coverage counter-data content for the 59 // currently running program to the writer 'w'. An error will be 60 // returned if the operation can't be completed successfully (for 61 // example, if the currently running program was not built with 62 // "-cover", or if a write fails). The counter data written will be a 63 // snapshot taken at the point of the invocation. 64 func WriteCounters(w io.Writer) error { 65 if w == nil { 66 return fmt.Errorf("error: nil writer in WriteCounters") 67 } 68 if cmode != coverage.CtrModeAtomic { 69 return fmt.Errorf("WriteCounters invoked for program built with -covermode=%s (please use -covermode=atomic)", cmode.String()) 70 } 71 // Ask the runtime for the list of coverage counter symbols. 72 cl := getCovCounterList() 73 if len(cl) == 0 { 74 return fmt.Errorf("program not built with -cover") 75 } 76 if !finalHashComputed { 77 return fmt.Errorf("meta-data not written yet, unable to write counter data") 78 } 79 80 pm := getCovPkgMap() 81 s := &emitState{ 82 counterlist: cl, 83 pkgmap: pm, 84 } 85 return s.emitCounterDataToWriter(w) 86 } 87 88 // ClearCounters clears/resets all coverage counter variables in the 89 // currently running program. It returns an error if the program in 90 // question was not built with the "-cover" flag. Clearing of coverage 91 // counters is also not supported for programs not using atomic 92 // counter mode (see more detailed comments below for the rationale 93 // here). 94 func ClearCounters() error { 95 cl := getCovCounterList() 96 if len(cl) == 0 { 97 return fmt.Errorf("program not built with -cover") 98 } 99 if cmode != coverage.CtrModeAtomic { 100 return fmt.Errorf("ClearCounters invoked for program built with -covermode=%s (please use -covermode=atomic)", cmode.String()) 101 } 102 103 // Implementation note: this function would be faster and simpler 104 // if we could just zero out the entire counter array, but for the 105 // moment we go through and zero out just the slots in the array 106 // corresponding to the counter values. We do this to avoid the 107 // following bad scenario: suppose that a user builds their Go 108 // program with "-cover", and that program has a function (call it 109 // main.XYZ) that invokes ClearCounters: 110 // 111 // func XYZ() { 112 // ... do some stuff ... 113 // coverage.ClearCounters() 114 // if someCondition { <<--- HERE 115 // ... 116 // } 117 // } 118 // 119 // At the point where ClearCounters executes, main.XYZ has not yet 120 // finished running, thus as soon as the call returns the line 121 // marked "HERE" above will trigger the writing of a non-zero 122 // value into main.XYZ's counter slab. However since we've just 123 // finished clearing the entire counter segment, we will have lost 124 // the values in the prolog portion of main.XYZ's counter slab 125 // (nctrs, pkgid, funcid). This means that later on at the end of 126 // program execution as we walk through the entire counter array 127 // for the program looking for executed functions, we'll zoom past 128 // main.XYZ's prolog (which was zero'd) and hit the non-zero 129 // counter value corresponding to the "HERE" block, which will 130 // then be interpreted as the start of another live function. 131 // Things will go downhill from there. 132 // 133 // This same scenario is also a potential risk if the program is 134 // running on an architecture that permits reordering of 135 // writes/stores, since the inconsistency described above could 136 // arise here. Example scenario: 137 // 138 // func ABC() { 139 // ... // prolog 140 // if alwaysTrue() { 141 // XYZ() // counter update here 142 // } 143 // } 144 // 145 // In the instrumented version of ABC, the prolog of the function 146 // will contain a series of stores to the initial portion of the 147 // counter array to write number-of-counters, pkgid, funcid. Later 148 // in the function there is also a store to increment a counter 149 // for the block containing the call to XYZ(). If the CPU is 150 // allowed to reorder stores and decides to issue the XYZ store 151 // before the prolog stores, this could be observable as an 152 // inconsistency similar to the one above. Hence the requirement 153 // for atomic counter mode: according to package atomic docs, 154 // "...operations that happen in a specific order on one thread, 155 // will always be observed to happen in exactly that order by 156 // another thread". Thus we can be sure that there will be no 157 // inconsistency when reading the counter array from the thread 158 // running ClearCounters. 159 160 for _, c := range cl { 161 sd := unsafe.Slice((*atomic.Uint32)(unsafe.Pointer(c.Counters)), int(c.Len)) 162 for i := 0; i < len(sd); i++ { 163 // Skip ahead until the next non-zero value. 164 sdi := sd[i].Load() 165 if sdi == 0 { 166 continue 167 } 168 // We found a function that was executed; clear its counters. 169 nCtrs := sdi 170 for j := 0; j < int(nCtrs); j++ { 171 sd[i+coverage.FirstCtrOffset+j].Store(0) 172 } 173 // Move to next function. 174 i += coverage.FirstCtrOffset + int(nCtrs) - 1 175 } 176 } 177 return nil 178 } 179