rustc_codegen_llvm/coverageinfo/
mapgen.rs

1use std::sync::Arc;
2
3use itertools::Itertools;
4use rustc_abi::Align;
5use rustc_codegen_ssa::traits::{BaseTypeCodegenMethods, ConstCodegenMethods};
6use rustc_data_structures::fx::FxIndexMap;
7use rustc_index::IndexVec;
8use rustc_middle::ty::TyCtxt;
9use rustc_session::RemapFileNameExt;
10use rustc_session::config::RemapPathScopeComponents;
11use rustc_span::{SourceFile, StableSourceFileId};
12use tracing::debug;
13
14use crate::common::CodegenCx;
15use crate::coverageinfo::llvm_cov;
16use crate::coverageinfo::mapgen::covfun::prepare_covfun_record;
17use crate::llvm;
18
19mod covfun;
20mod spans;
21mod unused;
22
23/// Generates and exports the coverage map, which is embedded in special
24/// linker sections in the final binary.
25///
26/// Those sections are then read and understood by LLVM's `llvm-cov` tool,
27/// which is distributed in the `llvm-tools` rustup component.
28pub(crate) fn finalize(cx: &mut CodegenCx<'_, '_>) {
29    let tcx = cx.tcx;
30
31    // Ensure that LLVM is using a version of the coverage mapping format that
32    // agrees with our Rust-side code. Expected versions (encoded as n-1) are:
33    // - `CovMapVersion::Version7` (6) used by LLVM 18-19
34    let covmap_version = {
35        let llvm_covmap_version = llvm_cov::mapping_version();
36        let expected_versions = 6..=6;
37        assert!(
38            expected_versions.contains(&llvm_covmap_version),
39            "Coverage mapping version exposed by `llvm-wrapper` is out of sync; \
40            expected {expected_versions:?} but was {llvm_covmap_version}"
41        );
42        // This is the version number that we will embed in the covmap section:
43        llvm_covmap_version
44    };
45
46    debug!("Generating coverage map for CodegenUnit: `{}`", cx.codegen_unit.name());
47
48    // FIXME(#132395): Can this be none even when coverage is enabled?
49    let Some(ref coverage_cx) = cx.coverage_cx else { return };
50
51    let mut covfun_records = coverage_cx
52        .instances_used()
53        .into_iter()
54        // Sort by symbol name, so that the global file table is built in an
55        // order that doesn't depend on the stable-hash-based order in which
56        // instances were visited during codegen.
57        .sorted_by_cached_key(|&instance| tcx.symbol_name(instance).name)
58        .filter_map(|instance| prepare_covfun_record(tcx, instance, true))
59        .collect::<Vec<_>>();
60
61    // In a single designated CGU, also prepare covfun records for functions
62    // in this crate that were instrumented for coverage, but are unused.
63    if cx.codegen_unit.is_code_coverage_dead_code_cgu() {
64        unused::prepare_covfun_records_for_unused_functions(cx, &mut covfun_records);
65    }
66
67    // If there are no covfun records for this CGU, don't generate a covmap record.
68    // Emitting a covmap record without any covfun records causes `llvm-cov` to
69    // fail when generating coverage reports, and if there are no covfun records
70    // then the covmap record isn't useful anyway.
71    // This should prevent a repeat of <https://github.com/rust-lang/rust/issues/133606>.
72    if covfun_records.is_empty() {
73        return;
74    }
75
76    // Prepare the global file table for this CGU, containing all paths needed
77    // by one or more covfun records.
78    let global_file_table =
79        GlobalFileTable::build(tcx, covfun_records.iter().flat_map(|c| c.all_source_files()));
80
81    for covfun in &covfun_records {
82        covfun::generate_covfun_record(cx, &global_file_table, covfun)
83    }
84
85    // Generate the coverage map header, which contains the filenames used by
86    // this CGU's coverage mappings, and store it in a well-known global.
87    // (This is skipped if we returned early due to having no covfun records.)
88    generate_covmap_record(cx, covmap_version, &global_file_table.filenames_buffer);
89}
90
91/// Maps "global" (per-CGU) file ID numbers to their underlying source file paths.
92#[derive(Debug)]
93struct GlobalFileTable {
94    /// This "raw" table doesn't include the working dir, so a file's
95    /// global ID is its index in this set **plus one**.
96    raw_file_table: FxIndexMap<StableSourceFileId, String>,
97
98    /// The file table in encoded form (possibly compressed), which can be
99    /// included directly in this CGU's `__llvm_covmap` record.
100    filenames_buffer: Vec<u8>,
101
102    /// Truncated hash of the bytes in `filenames_buffer`.
103    ///
104    /// The `llvm-cov` tool uses this hash to associate each covfun record with
105    /// its corresponding filenames table, since the final binary will typically
106    /// contain multiple covmap records from different compilation units.
107    filenames_hash: u64,
108}
109
110impl GlobalFileTable {
111    /// Builds a "global file table" for this CGU, mapping numeric IDs to
112    /// path strings.
113    fn build<'a>(tcx: TyCtxt<'_>, all_files: impl Iterator<Item = &'a SourceFile>) -> Self {
114        let mut raw_file_table = FxIndexMap::default();
115
116        for file in all_files {
117            raw_file_table.entry(file.stable_id).or_insert_with(|| {
118                file.name
119                    .for_scope(tcx.sess, RemapPathScopeComponents::MACRO)
120                    .to_string_lossy()
121                    .into_owned()
122            });
123        }
124
125        // FIXME(Zalathar): Consider sorting the file table here, but maybe
126        // only after adding filename support to coverage-dump, so that the
127        // table order isn't directly visible in `.coverage-map` snapshots.
128
129        let mut table = Vec::with_capacity(raw_file_table.len() + 1);
130
131        // Since version 6 of the LLVM coverage mapping format, the first entry
132        // in the global file table is treated as a base directory, used to
133        // resolve any other entries that are stored as relative paths.
134        let base_dir = tcx
135            .sess
136            .opts
137            .working_dir
138            .for_scope(tcx.sess, RemapPathScopeComponents::MACRO)
139            .to_string_lossy();
140        table.push(base_dir.as_ref());
141
142        // Add the regular entries after the base directory.
143        table.extend(raw_file_table.values().map(|name| name.as_str()));
144
145        // Encode the file table into a buffer, and get the hash of its encoded
146        // bytes, so that we can embed that hash in `__llvm_covfun` records.
147        let filenames_buffer = llvm_cov::write_filenames_to_buffer(&table);
148        let filenames_hash = llvm_cov::hash_bytes(&filenames_buffer);
149
150        Self { raw_file_table, filenames_buffer, filenames_hash }
151    }
152
153    fn get_existing_id(&self, file: &SourceFile) -> Option<GlobalFileId> {
154        let raw_id = self.raw_file_table.get_index_of(&file.stable_id)?;
155        // The raw file table doesn't include an entry for the base dir
156        // (which has ID 0), so add 1 to get the correct ID.
157        Some(GlobalFileId::from_usize(raw_id + 1))
158    }
159}
160
161rustc_index::newtype_index! {
162    /// An index into the CGU's overall list of file paths. The underlying paths
163    /// will be embedded in the `__llvm_covmap` linker section.
164    struct GlobalFileId {}
165}
166rustc_index::newtype_index! {
167    /// An index into a function's list of global file IDs. That underlying list
168    /// of local-to-global mappings will be embedded in the function's record in
169    /// the `__llvm_covfun` linker section.
170    struct LocalFileId {}
171}
172
173/// Holds a mapping from "local" (per-function) file IDs to their corresponding
174/// source files.
175#[derive(Debug, Default)]
176struct VirtualFileMapping {
177    local_file_table: IndexVec<LocalFileId, Arc<SourceFile>>,
178}
179
180impl VirtualFileMapping {
181    fn push_file(&mut self, source_file: &Arc<SourceFile>) -> LocalFileId {
182        self.local_file_table.push(Arc::clone(source_file))
183    }
184
185    /// Resolves all of the filenames in this local file mapping to a list of
186    /// global file IDs in its CGU, for inclusion in this function's
187    /// `__llvm_covfun` record.
188    ///
189    /// The global file IDs are returned as `u32` to make FFI easier.
190    fn resolve_all(&self, global_file_table: &GlobalFileTable) -> Option<Vec<u32>> {
191        self.local_file_table
192            .iter()
193            .map(|file| try {
194                let id = global_file_table.get_existing_id(file)?;
195                GlobalFileId::as_u32(id)
196            })
197            .collect::<Option<Vec<_>>>()
198    }
199}
200
201/// Generates the contents of the covmap record for this CGU, which mostly
202/// consists of a header and a list of filenames. The record is then stored
203/// as a global variable in the `__llvm_covmap` section.
204fn generate_covmap_record<'ll>(cx: &mut CodegenCx<'ll, '_>, version: u32, filenames_buffer: &[u8]) {
205    // A covmap record consists of four target-endian u32 values, followed by
206    // the encoded filenames table. Two of the header fields are unused in
207    // modern versions of the LLVM coverage mapping format, and are always 0.
208    // <https://llvm.org/docs/CoverageMappingFormat.html#llvm-ir-representation>
209    // See also `src/llvm-project/clang/lib/CodeGen/CoverageMappingGen.cpp`.
210    let covmap_header = cx.const_struct(
211        &[
212            cx.const_u32(0), // (unused)
213            cx.const_u32(filenames_buffer.len() as u32),
214            cx.const_u32(0), // (unused)
215            cx.const_u32(version),
216        ],
217        /* packed */ false,
218    );
219    let covmap_record = cx
220        .const_struct(&[covmap_header, cx.const_bytes(filenames_buffer)], /* packed */ false);
221
222    let covmap_global =
223        llvm::add_global(cx.llmod, cx.val_ty(covmap_record), &llvm_cov::covmap_var_name());
224    llvm::set_initializer(covmap_global, covmap_record);
225    llvm::set_global_constant(covmap_global, true);
226    llvm::set_linkage(covmap_global, llvm::Linkage::PrivateLinkage);
227    llvm::set_section(covmap_global, &llvm_cov::covmap_section_name(cx.llmod));
228    // LLVM's coverage mapping format specifies 8-byte alignment for items in this section.
229    // <https://llvm.org/docs/CoverageMappingFormat.html>
230    llvm::set_alignment(covmap_global, Align::EIGHT);
231
232    cx.add_used_global(covmap_global);
233}