rustc_codegen_llvm/coverageinfo/mapgen/
covfun.rs

1//! For each function that was instrumented for coverage, we need to embed its
2//! corresponding coverage mapping metadata inside the `__llvm_covfun`[^win]
3//! linker section of the final binary.
4//!
5//! [^win]: On Windows the section name is `.lcovfun`.
6
7use std::ffi::CString;
8use std::sync::Arc;
9
10use rustc_abi::Align;
11use rustc_codegen_ssa::traits::{BaseTypeCodegenMethods as _, ConstCodegenMethods};
12use rustc_middle::mir::coverage::{
13    BasicCoverageBlock, CovTerm, CoverageIdsInfo, Expression, FunctionCoverageInfo, Mapping,
14    MappingKind, Op,
15};
16use rustc_middle::ty::{Instance, TyCtxt};
17use rustc_span::{SourceFile, Span};
18use rustc_target::spec::HasTargetSpec;
19use tracing::debug;
20
21use crate::common::CodegenCx;
22use crate::coverageinfo::mapgen::{GlobalFileTable, VirtualFileMapping, spans};
23use crate::coverageinfo::{ffi, llvm_cov};
24use crate::llvm;
25
26/// Intermediate coverage metadata for a single function, used to help build
27/// the final record that will be embedded in the `__llvm_covfun` section.
28#[derive(Debug)]
29pub(crate) struct CovfunRecord<'tcx> {
30    /// Not used directly, but helpful in debug messages.
31    _instance: Instance<'tcx>,
32
33    mangled_function_name: &'tcx str,
34    source_hash: u64,
35    is_used: bool,
36
37    virtual_file_mapping: VirtualFileMapping,
38    expressions: Vec<ffi::CounterExpression>,
39    regions: ffi::Regions,
40}
41
42impl<'tcx> CovfunRecord<'tcx> {
43    /// Iterator that yields all source files referred to by this function's
44    /// coverage mappings. Used to build the global file table for the CGU.
45    pub(crate) fn all_source_files(&self) -> impl Iterator<Item = &SourceFile> {
46        self.virtual_file_mapping.local_file_table.iter().map(Arc::as_ref)
47    }
48}
49
50pub(crate) fn prepare_covfun_record<'tcx>(
51    tcx: TyCtxt<'tcx>,
52    instance: Instance<'tcx>,
53    is_used: bool,
54) -> Option<CovfunRecord<'tcx>> {
55    let fn_cov_info = tcx.instance_mir(instance.def).function_coverage_info.as_deref()?;
56    let ids_info = tcx.coverage_ids_info(instance.def)?;
57
58    let expressions = prepare_expressions(ids_info);
59
60    let mut covfun = CovfunRecord {
61        _instance: instance,
62        mangled_function_name: tcx.symbol_name(instance).name,
63        source_hash: if is_used { fn_cov_info.function_source_hash } else { 0 },
64        is_used,
65        virtual_file_mapping: VirtualFileMapping::default(),
66        expressions,
67        regions: ffi::Regions::default(),
68    };
69
70    fill_region_tables(tcx, fn_cov_info, ids_info, &mut covfun);
71
72    if covfun.regions.has_no_regions() {
73        debug!(?covfun, "function has no mappings to embed; skipping");
74        return None;
75    }
76
77    Some(covfun)
78}
79
80/// Convert the function's coverage-counter expressions into a form suitable for FFI.
81fn prepare_expressions(ids_info: &CoverageIdsInfo) -> Vec<ffi::CounterExpression> {
82    let counter_for_term = ffi::Counter::from_term;
83
84    // We know that LLVM will optimize out any unused expressions before
85    // producing the final coverage map, so there's no need to do the same
86    // thing on the Rust side unless we're confident we can do much better.
87    // (See `CounterExpressionsMinimizer` in `CoverageMappingWriter.cpp`.)
88    ids_info
89        .expressions
90        .iter()
91        .map(move |&Expression { lhs, op, rhs }| ffi::CounterExpression {
92            lhs: counter_for_term(lhs),
93            kind: match op {
94                Op::Add => ffi::ExprKind::Add,
95                Op::Subtract => ffi::ExprKind::Subtract,
96            },
97            rhs: counter_for_term(rhs),
98        })
99        .collect::<Vec<_>>()
100}
101
102/// Populates the mapping region tables in the current function's covfun record.
103fn fill_region_tables<'tcx>(
104    tcx: TyCtxt<'tcx>,
105    fn_cov_info: &'tcx FunctionCoverageInfo,
106    ids_info: &'tcx CoverageIdsInfo,
107    covfun: &mut CovfunRecord<'tcx>,
108) {
109    // If this function is unused, replace all counters with zero.
110    let counter_for_bcb = |bcb: BasicCoverageBlock| -> ffi::Counter {
111        let term = if covfun.is_used {
112            ids_info.term_for_bcb[bcb].expect("every BCB in a mapping was given a term")
113        } else {
114            CovTerm::Zero
115        };
116        ffi::Counter::from_term(term)
117    };
118
119    // Currently a function's mappings must all be in the same file, so use the
120    // first mapping's span to determine the file.
121    let source_map = tcx.sess.source_map();
122    let Some(first_span) = (try { fn_cov_info.mappings.first()?.span }) else {
123        debug_assert!(false, "function has no mappings: {covfun:?}");
124        return;
125    };
126    let source_file = source_map.lookup_source_file(first_span.lo());
127
128    let local_file_id = covfun.virtual_file_mapping.push_file(&source_file);
129
130    // In rare cases, _all_ of a function's spans are discarded, and coverage
131    // codegen needs to handle that gracefully to avoid #133606.
132    // It's hard for tests to trigger this organically, so instead we set
133    // `-Zcoverage-options=discard-all-spans-in-codegen` to force it to occur.
134    let discard_all = tcx.sess.coverage_options().discard_all_spans_in_codegen;
135    let make_coords = |span: Span| {
136        if discard_all { None } else { spans::make_coords(source_map, &source_file, span) }
137    };
138
139    let ffi::Regions {
140        code_regions,
141        expansion_regions: _, // FIXME(Zalathar): Fill out support for expansion regions
142        branch_regions,
143    } = &mut covfun.regions;
144
145    // For each counter/region pair in this function+file, convert it to a
146    // form suitable for FFI.
147    for &Mapping { ref kind, span } in &fn_cov_info.mappings {
148        let Some(coords) = make_coords(span) else { continue };
149        let cov_span = coords.make_coverage_span(local_file_id);
150
151        match *kind {
152            MappingKind::Code { bcb } => {
153                code_regions.push(ffi::CodeRegion { cov_span, counter: counter_for_bcb(bcb) });
154            }
155            MappingKind::Branch { true_bcb, false_bcb } => {
156                branch_regions.push(ffi::BranchRegion {
157                    cov_span,
158                    true_counter: counter_for_bcb(true_bcb),
159                    false_counter: counter_for_bcb(false_bcb),
160                });
161            }
162        }
163    }
164}
165
166/// Generates the contents of the covfun record for this function, which
167/// contains the function's coverage mapping data. The record is then stored
168/// as a global variable in the `__llvm_covfun` section.
169pub(crate) fn generate_covfun_record<'tcx>(
170    cx: &mut CodegenCx<'_, 'tcx>,
171    global_file_table: &GlobalFileTable,
172    covfun: &CovfunRecord<'tcx>,
173) {
174    let &CovfunRecord {
175        _instance,
176        mangled_function_name,
177        source_hash,
178        is_used,
179        ref virtual_file_mapping,
180        ref expressions,
181        ref regions,
182    } = covfun;
183
184    let Some(local_file_table) = virtual_file_mapping.resolve_all(global_file_table) else {
185        debug_assert!(
186            false,
187            "all local files should be present in the global file table: \
188                global_file_table = {global_file_table:?}, \
189                virtual_file_mapping = {virtual_file_mapping:?}"
190        );
191        return;
192    };
193
194    // Encode the function's coverage mappings into a buffer.
195    let coverage_mapping_buffer =
196        llvm_cov::write_function_mappings_to_buffer(&local_file_table, expressions, regions);
197
198    // A covfun record consists of four target-endian integers, followed by the
199    // encoded mapping data in bytes. Note that the length field is 32 bits.
200    // <https://llvm.org/docs/CoverageMappingFormat.html#llvm-ir-representation>
201    // See also `src/llvm-project/clang/lib/CodeGen/CoverageMappingGen.cpp` and
202    // `COVMAP_V3` in `src/llvm-project/llvm/include/llvm/ProfileData/InstrProfData.inc`.
203    let func_name_hash = llvm_cov::hash_bytes(mangled_function_name.as_bytes());
204    let covfun_record = cx.const_struct(
205        &[
206            cx.const_u64(func_name_hash),
207            cx.const_u32(coverage_mapping_buffer.len() as u32),
208            cx.const_u64(source_hash),
209            cx.const_u64(global_file_table.filenames_hash),
210            cx.const_bytes(&coverage_mapping_buffer),
211        ],
212        // This struct needs to be packed, so that the 32-bit length field
213        // doesn't have unexpected padding.
214        true,
215    );
216
217    // Choose a variable name to hold this function's covfun data.
218    // Functions that are used have a suffix ("u") to distinguish them from
219    // unused copies of the same function (from different CGUs), so that if a
220    // linker sees both it won't discard the used copy's data.
221    let u = if is_used { "u" } else { "" };
222    let covfun_var_name = CString::new(format!("__covrec_{func_name_hash:X}{u}")).unwrap();
223    debug!("function record var name: {covfun_var_name:?}");
224
225    let covfun_global = llvm::add_global(cx.llmod, cx.val_ty(covfun_record), &covfun_var_name);
226    llvm::set_initializer(covfun_global, covfun_record);
227    llvm::set_global_constant(covfun_global, true);
228    llvm::set_linkage(covfun_global, llvm::Linkage::LinkOnceODRLinkage);
229    llvm::set_visibility(covfun_global, llvm::Visibility::Hidden);
230    llvm::set_section(covfun_global, cx.covfun_section_name());
231    // LLVM's coverage mapping format specifies 8-byte alignment for items in this section.
232    // <https://llvm.org/docs/CoverageMappingFormat.html>
233    llvm::set_alignment(covfun_global, Align::EIGHT);
234    if cx.target_spec().supports_comdat() {
235        llvm::set_comdat(cx.llmod, covfun_global, &covfun_var_name);
236    }
237
238    cx.add_used_global(covfun_global);
239}
rustc_codegen_llvm/coverageinfo/mapgen/covfun.rs

rustc_codegen_llvm/coverageinfo/mapgen/
covfun.rs
