1 use crate::common::CodegenCx;
2 use crate::coverageinfo;
3 use crate::errors::InstrumentCoverageRequiresLLVM12;
6 use llvm::coverageinfo::CounterMappingRegion;
7 use rustc_codegen_ssa::coverageinfo::map::{Counter, CounterExpression};
8 use rustc_codegen_ssa::traits::{ConstMethods, CoverageInfoMethods};
9 use rustc_data_structures::fx::FxIndexSet;
10 use rustc_hir::def::DefKind;
11 use rustc_hir::def_id::DefId;
12 use rustc_llvm::RustString;
13 use rustc_middle::bug;
14 use rustc_middle::middle::codegen_fn_attrs::CodegenFnAttrFlags;
15 use rustc_middle::mir::coverage::CodeRegion;
16 use rustc_middle::ty::TyCtxt;
18 use std::ffi::CString;
20 /// Generates and exports the Coverage Map.
22 /// Rust Coverage Map generation supports LLVM Coverage Mapping Format versions
23 /// 5 (LLVM 12, only) and 6 (zero-based encoded as 4 and 5, respectively), as defined at
24 /// [LLVM Code Coverage Mapping Format](https://github.com/rust-lang/llvm-project/blob/rustc/13.0-2021-09-30/llvm/docs/CoverageMappingFormat.rst#llvm-code-coverage-mapping-format).
25 /// These versions are supported by the LLVM coverage tools (`llvm-profdata` and `llvm-cov`)
26 /// bundled with Rust's fork of LLVM.
28 /// Consequently, Rust's bundled version of Clang also generates Coverage Maps compliant with
29 /// the same version. Clang's implementation of Coverage Map generation was referenced when
30 /// implementing this Rust version, and though the format documentation is very explicit and
31 /// detailed, some undocumented details in Clang's implementation (that may or may not be important)
32 /// were also replicated for Rust's Coverage Map.
33 pub fn finalize(cx: &CodegenCx<'_, '_>) {
36 // Ensure the installed version of LLVM supports at least Coverage Map
37 // Version 5 (encoded as a zero-based value: 4), which was introduced with
39 let version = coverageinfo::mapping_version();
41 tcx.sess.emit_fatal(InstrumentCoverageRequiresLLVM12);
44 debug!("Generating coverage map for CodegenUnit: `{}`", cx.codegen_unit.name());
46 // In order to show that unused functions have coverage counts of zero (0), LLVM requires the
47 // functions exist. Generate synthetic functions with a (required) single counter, and add the
48 // MIR `Coverage` code regions to the `function_coverage_map`, before calling
49 // `ctx.take_function_coverage_map()`.
50 if cx.codegen_unit.is_code_coverage_dead_code_cgu() {
51 add_unused_functions(cx);
54 let function_coverage_map = match cx.coverage_context() {
55 Some(ctx) => ctx.take_function_coverage_map(),
59 if function_coverage_map.is_empty() {
60 // This module has no functions with coverage instrumentation
64 let mut mapgen = CoverageMapGenerator::new(tcx, version);
66 // Encode coverage mappings and generate function records
67 let mut function_data = Vec::new();
68 for (instance, function_coverage) in function_coverage_map {
69 debug!("Generate function coverage for {}, {:?}", cx.codegen_unit.name(), instance);
70 let mangled_function_name = tcx.symbol_name(instance).to_string();
71 let source_hash = function_coverage.source_hash();
72 let is_used = function_coverage.is_used();
73 let (expressions, counter_regions) =
74 function_coverage.get_expressions_and_counter_regions();
76 let coverage_mapping_buffer = llvm::build_byte_buffer(|coverage_mapping_buffer| {
77 mapgen.write_coverage_mapping(expressions, counter_regions, coverage_mapping_buffer);
80 if coverage_mapping_buffer.is_empty() {
81 if function_coverage.is_used() {
83 "A used function should have had coverage mapping data but did not: {}",
87 debug!("unused function had no coverage mapping data: {}", mangled_function_name);
92 function_data.push((mangled_function_name, source_hash, is_used, coverage_mapping_buffer));
95 // Encode all filenames referenced by counters/expressions in this module
96 let filenames_buffer = llvm::build_byte_buffer(|filenames_buffer| {
97 coverageinfo::write_filenames_section_to_buffer(&mapgen.filenames, filenames_buffer);
100 let filenames_size = filenames_buffer.len();
101 let filenames_val = cx.const_bytes(&filenames_buffer);
102 let filenames_ref = coverageinfo::hash_bytes(filenames_buffer);
104 // Generate the LLVM IR representation of the coverage map and store it in a well-known global
105 let cov_data_val = mapgen.generate_coverage_map(cx, version, filenames_size, filenames_val);
107 for (mangled_function_name, source_hash, is_used, coverage_mapping_buffer) in function_data {
108 save_function_record(
110 mangled_function_name,
113 coverage_mapping_buffer,
118 // Save the coverage data value to LLVM IR
119 coverageinfo::save_cov_data_to_mod(cx, cov_data_val);
122 struct CoverageMapGenerator {
123 filenames: FxIndexSet<CString>,
126 impl CoverageMapGenerator {
127 fn new(tcx: TyCtxt<'_>, version: u32) -> Self {
128 let mut filenames = FxIndexSet::default();
130 // LLVM Coverage Mapping Format version 6 (zero-based encoded as 5)
131 // requires setting the first filename to the compilation directory.
132 // Since rustc generates coverage maps with relative paths, the
133 // compilation directory can be combined with the relative paths
134 // to get absolute paths, if needed.
135 let working_dir = tcx
139 .remapped_path_if_available()
143 CString::new(working_dir).expect("null error converting filename to C string");
144 filenames.insert(c_filename);
149 /// Using the `expressions` and `counter_regions` collected for the current function, generate
150 /// the `mapping_regions` and `virtual_file_mapping`, and capture any new filenames. Then use
151 /// LLVM APIs to encode the `virtual_file_mapping`, `expressions`, and `mapping_regions` into
152 /// the given `coverage_mapping` byte buffer, compliant with the LLVM Coverage Mapping format.
153 fn write_coverage_mapping<'a>(
155 expressions: Vec<CounterExpression>,
156 counter_regions: impl Iterator<Item = (Counter, &'a CodeRegion)>,
157 coverage_mapping_buffer: &RustString,
159 let mut counter_regions = counter_regions.collect::<Vec<_>>();
160 if counter_regions.is_empty() {
164 let mut virtual_file_mapping = Vec::new();
165 let mut mapping_regions = Vec::new();
166 let mut current_file_name = None;
167 let mut current_file_id = 0;
169 // Convert the list of (Counter, CodeRegion) pairs to an array of `CounterMappingRegion`, sorted
170 // by filename and position. Capture any new files to compute the `CounterMappingRegion`s
171 // `file_id` (indexing files referenced by the current function), and construct the
172 // function-specific `virtual_file_mapping` from `file_id` to its index in the module's
173 // `filenames` array.
174 counter_regions.sort_unstable_by_key(|(_counter, region)| *region);
175 for (counter, region) in counter_regions {
176 let CodeRegion { file_name, start_line, start_col, end_line, end_col } = *region;
177 let same_file = current_file_name.map_or(false, |p| p == file_name);
179 if current_file_name.is_some() {
180 current_file_id += 1;
182 current_file_name = Some(file_name);
183 let c_filename = CString::new(file_name.to_string())
184 .expect("null error converting filename to C string");
185 debug!(" file_id: {} = '{:?}'", current_file_id, c_filename);
186 let (filenames_index, _) = self.filenames.insert_full(c_filename);
187 virtual_file_mapping.push(filenames_index as u32);
189 debug!("Adding counter {:?} to map for {:?}", counter, region);
190 mapping_regions.push(CounterMappingRegion::code_region(
200 // Encode and append the current function's coverage mapping data
201 coverageinfo::write_mapping_to_buffer(
202 virtual_file_mapping,
205 coverage_mapping_buffer,
209 /// Construct coverage map header and the array of function records, and combine them into the
210 /// coverage map. Save the coverage map data into the LLVM IR as a static global using a
211 /// specific, well-known section and name.
212 fn generate_coverage_map<'ll>(
214 cx: &CodegenCx<'ll, '_>,
216 filenames_size: usize,
217 filenames_val: &'ll llvm::Value,
218 ) -> &'ll llvm::Value {
219 debug!("cov map: filenames_size = {}, 0-based version = {}", filenames_size, version);
221 // Create the coverage data header (Note, fields 0 and 2 are now always zero,
222 // as of `llvm::coverage::CovMapVersion::Version4`.)
223 let zero_was_n_records_val = cx.const_u32(0);
224 let filenames_size_val = cx.const_u32(filenames_size as u32);
225 let zero_was_coverage_size_val = cx.const_u32(0);
226 let version_val = cx.const_u32(version);
227 let cov_data_header_val = cx.const_struct(
228 &[zero_was_n_records_val, filenames_size_val, zero_was_coverage_size_val, version_val],
232 // Create the complete LLVM coverage data value to add to the LLVM IR
233 cx.const_struct(&[cov_data_header_val, filenames_val], /*packed=*/ false)
237 /// Construct a function record and combine it with the function's coverage mapping data.
238 /// Save the function record into the LLVM IR as a static global using a
239 /// specific, well-known section and name.
240 fn save_function_record(
241 cx: &CodegenCx<'_, '_>,
242 mangled_function_name: String,
245 coverage_mapping_buffer: Vec<u8>,
248 // Concatenate the encoded coverage mappings
249 let coverage_mapping_size = coverage_mapping_buffer.len();
250 let coverage_mapping_val = cx.const_bytes(&coverage_mapping_buffer);
252 let func_name_hash = coverageinfo::hash_str(&mangled_function_name);
253 let func_name_hash_val = cx.const_u64(func_name_hash);
254 let coverage_mapping_size_val = cx.const_u32(coverage_mapping_size as u32);
255 let source_hash_val = cx.const_u64(source_hash);
256 let filenames_ref_val = cx.const_u64(filenames_ref);
257 let func_record_val = cx.const_struct(
260 coverage_mapping_size_val,
263 coverage_mapping_val,
268 coverageinfo::save_func_record_to_mod(cx, func_name_hash, func_record_val, is_used);
271 /// When finalizing the coverage map, `FunctionCoverage` only has the `CodeRegion`s and counters for
272 /// the functions that went through codegen; such as public functions and "used" functions
273 /// (functions referenced by other "used" or public items). Any other functions considered unused,
274 /// or "Unreachable", were still parsed and processed through the MIR stage, but were not
275 /// codegenned. (Note that `-Clink-dead-code` can force some unused code to be codegenned, but
276 /// that flag is known to cause other errors, when combined with `-C instrument-coverage`; and
277 /// `-Clink-dead-code` will not generate code for unused generic functions.)
279 /// We can find the unused functions (including generic functions) by the set difference of all MIR
280 /// `DefId`s (`tcx` query `mir_keys`) minus the codegenned `DefId`s (`tcx` query
281 /// `codegened_and_inlined_items`).
283 /// These unused functions are then codegen'd in one of the CGUs which is marked as the
284 /// "code coverage dead code cgu" during the partitioning process. This prevents us from generating
285 /// code regions for the same function more than once which can lead to linker errors regarding
286 /// duplicate symbols.
287 fn add_unused_functions(cx: &CodegenCx<'_, '_>) {
288 assert!(cx.codegen_unit.is_code_coverage_dead_code_cgu());
292 let ignore_unused_generics = tcx.sess.instrument_coverage_except_unused_generics();
294 let eligible_def_ids: Vec<DefId> = tcx
297 .filter_map(|local_def_id| {
298 let def_id = local_def_id.to_def_id();
299 let kind = tcx.def_kind(def_id);
300 // `mir_keys` will give us `DefId`s for all kinds of things, not
301 // just "functions", like consts, statics, etc. Filter those out.
302 // If `ignore_unused_generics` was specified, filter out any
303 // generic functions from consideration as well.
306 DefKind::Fn | DefKind::AssocFn | DefKind::Closure | DefKind::Generator
309 } else if ignore_unused_generics
310 && tcx.generics_of(def_id).requires_monomorphization(tcx)
314 Some(local_def_id.to_def_id())
318 let codegenned_def_ids = tcx.codegened_and_inlined_items(());
320 for non_codegenned_def_id in
321 eligible_def_ids.into_iter().filter(|id| !codegenned_def_ids.contains(id))
323 let codegen_fn_attrs = tcx.codegen_fn_attrs(non_codegenned_def_id);
325 // If a function is marked `#[no_coverage]`, then skip generating a
326 // dead code stub for it.
327 if codegen_fn_attrs.flags.contains(CodegenFnAttrFlags::NO_COVERAGE) {
328 debug!("skipping unused fn marked #[no_coverage]: {:?}", non_codegenned_def_id);
332 debug!("generating unused fn: {:?}", non_codegenned_def_id);
333 cx.define_unused_fn(non_codegenned_def_id);