compiler/rustc_codegen_llvm/src/coverageinfo/mapgen.rs

   1 use crate::common::CodegenCx;
   2 use crate::coverageinfo;
   3 use crate::coverageinfo::ffi::{Counter, CounterExpression, CounterMappingRegion};
   4 use crate::llvm;
   5
   6 use rustc_codegen_ssa::traits::ConstMethods;
   7 use rustc_data_structures::fx::FxIndexSet;
   8 use rustc_hir::def::DefKind;
   9 use rustc_hir::def_id::DefId;
  10 use rustc_llvm::RustString;
  11 use rustc_middle::bug;
  12 use rustc_middle::middle::codegen_fn_attrs::CodegenFnAttrFlags;
  13 use rustc_middle::mir::coverage::CodeRegion;
  14 use rustc_middle::ty::TyCtxt;
  15 use rustc_span::Symbol;
  16
  17 /// Generates and exports the Coverage Map.
  18 ///
  19 /// Rust Coverage Map generation supports LLVM Coverage Mapping Format version
  20 /// 6 (zero-based encoded as 5), as defined at
  21 /// [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).
  22 /// These versions are supported by the LLVM coverage tools (`llvm-profdata` and `llvm-cov`)
  23 /// bundled with Rust's fork of LLVM.
  24 ///
  25 /// Consequently, Rust's bundled version of Clang also generates Coverage Maps compliant with
  26 /// the same version. Clang's implementation of Coverage Map generation was referenced when
  27 /// implementing this Rust version, and though the format documentation is very explicit and
  28 /// detailed, some undocumented details in Clang's implementation (that may or may not be important)
  29 /// were also replicated for Rust's Coverage Map.
  30 pub fn finalize(cx: &CodegenCx<'_, '_>) {
  31     let tcx = cx.tcx;
  32
  33     // Ensure the installed version of LLVM supports Coverage Map Version 6
  34     // (encoded as a zero-based value: 5), which was introduced with LLVM 13.
  35     let version = coverageinfo::mapping_version();
  36     assert_eq!(version, 5, "The `CoverageMappingVersion` exposed by `llvm-wrapper` is out of sync");
  37
  38     debug!("Generating coverage map for CodegenUnit: `{}`", cx.codegen_unit.name());
  39
  40     // In order to show that unused functions have coverage counts of zero (0), LLVM requires the
  41     // functions exist. Generate synthetic functions with a (required) single counter, and add the
  42     // MIR `Coverage` code regions to the `function_coverage_map`, before calling
  43     // `ctx.take_function_coverage_map()`.
  44     if cx.codegen_unit.is_code_coverage_dead_code_cgu() {
  45         add_unused_functions(cx);
  46     }
  47
  48     let function_coverage_map = match cx.coverage_context() {
  49         Some(ctx) => ctx.take_function_coverage_map(),
  50         None => return,
  51     };
  52
  53     if function_coverage_map.is_empty() {
  54         // This module has no functions with coverage instrumentation
  55         return;
  56     }
  57
  58     let mut mapgen = CoverageMapGenerator::new(tcx);
  59
  60     // Encode coverage mappings and generate function records
  61     let mut function_data = Vec::new();
  62     for (instance, function_coverage) in function_coverage_map {
  63         debug!("Generate function coverage for {}, {:?}", cx.codegen_unit.name(), instance);
  64         let mangled_function_name = tcx.symbol_name(instance).name;
  65         let source_hash = function_coverage.source_hash();
  66         let is_used = function_coverage.is_used();
  67         let (expressions, counter_regions) =
  68             function_coverage.get_expressions_and_counter_regions();
  69
  70         let coverage_mapping_buffer = llvm::build_byte_buffer(|coverage_mapping_buffer| {
  71             mapgen.write_coverage_mapping(expressions, counter_regions, coverage_mapping_buffer);
  72         });
  73
  74         if coverage_mapping_buffer.is_empty() {
  75             if function_coverage.is_used() {
  76                 bug!(
  77                     "A used function should have had coverage mapping data but did not: {}",
  78                     mangled_function_name
  79                 );
  80             } else {
  81                 debug!("unused function had no coverage mapping data: {}", mangled_function_name);
  82                 continue;
  83             }
  84         }
  85
  86         function_data.push((mangled_function_name, source_hash, is_used, coverage_mapping_buffer));
  87     }
  88
  89     // Encode all filenames referenced by counters/expressions in this module
  90     let filenames_buffer = llvm::build_byte_buffer(|filenames_buffer| {
  91         coverageinfo::write_filenames_section_to_buffer(
  92             mapgen.filenames.iter().map(Symbol::as_str),
  93             filenames_buffer,
  94         );
  95     });
  96
  97     let filenames_size = filenames_buffer.len();
  98     let filenames_val = cx.const_bytes(&filenames_buffer);
  99     let filenames_ref = coverageinfo::hash_bytes(&filenames_buffer);
 100
 101     // Generate the LLVM IR representation of the coverage map and store it in a well-known global
 102     let cov_data_val = mapgen.generate_coverage_map(cx, version, filenames_size, filenames_val);
 103
 104     let covfun_section_name = coverageinfo::covfun_section_name(cx);
 105     for (mangled_function_name, source_hash, is_used, coverage_mapping_buffer) in function_data {
 106         save_function_record(
 107             cx,
 108             &covfun_section_name,
 109             mangled_function_name,
 110             source_hash,
 111             filenames_ref,
 112             coverage_mapping_buffer,
 113             is_used,
 114         );
 115     }
 116
 117     // Save the coverage data value to LLVM IR
 118     coverageinfo::save_cov_data_to_mod(cx, cov_data_val);
 119 }
 120
 121 struct CoverageMapGenerator {
 122     filenames: FxIndexSet<Symbol>,
 123 }
 124
 125 impl CoverageMapGenerator {
 126     fn new(tcx: TyCtxt<'_>) -> Self {
 127         let mut filenames = FxIndexSet::default();
 128         // LLVM Coverage Mapping Format version 6 (zero-based encoded as 5)
 129         // requires setting the first filename to the compilation directory.
 130         // Since rustc generates coverage maps with relative paths, the
 131         // compilation directory can be combined with the relative paths
 132         // to get absolute paths, if needed.
 133         let working_dir = Symbol::intern(
 134             &tcx.sess.opts.working_dir.remapped_path_if_available().to_string_lossy(),
 135         );
 136         filenames.insert(working_dir);
 137         Self { filenames }
 138     }
 139
 140     /// Using the `expressions` and `counter_regions` collected for the current function, generate
 141     /// the `mapping_regions` and `virtual_file_mapping`, and capture any new filenames. Then use
 142     /// LLVM APIs to encode the `virtual_file_mapping`, `expressions`, and `mapping_regions` into
 143     /// the given `coverage_mapping` byte buffer, compliant with the LLVM Coverage Mapping format.
 144     fn write_coverage_mapping<'a>(
 145         &mut self,
 146         expressions: Vec<CounterExpression>,
 147         counter_regions: impl Iterator<Item = (Counter, &'a CodeRegion)>,
 148         coverage_mapping_buffer: &RustString,
 149     ) {
 150         let mut counter_regions = counter_regions.collect::<Vec<_>>();
 151         if counter_regions.is_empty() {
 152             return;
 153         }
 154
 155         let mut virtual_file_mapping = Vec::new();
 156         let mut mapping_regions = Vec::new();
 157         let mut current_file_name = None;
 158         let mut current_file_id = 0;
 159
 160         // Convert the list of (Counter, CodeRegion) pairs to an array of `CounterMappingRegion`, sorted
 161         // by filename and position. Capture any new files to compute the `CounterMappingRegion`s
 162         // `file_id` (indexing files referenced by the current function), and construct the
 163         // function-specific `virtual_file_mapping` from `file_id` to its index in the module's
 164         // `filenames` array.
 165         counter_regions.sort_unstable_by_key(|(_counter, region)| *region);
 166         for (counter, region) in counter_regions {
 167             let CodeRegion { file_name, start_line, start_col, end_line, end_col } = *region;
 168             let same_file = current_file_name.is_some_and(|p| p == file_name);
 169             if !same_file {
 170                 if current_file_name.is_some() {
 171                     current_file_id += 1;
 172                 }
 173                 current_file_name = Some(file_name);
 174                 debug!("  file_id: {} = '{:?}'", current_file_id, file_name);
 175                 let (filenames_index, _) = self.filenames.insert_full(file_name);
 176                 virtual_file_mapping.push(filenames_index as u32);
 177             }
 178             debug!("Adding counter {:?} to map for {:?}", counter, region);
 179             mapping_regions.push(CounterMappingRegion::code_region(
 180                 counter,
 181                 current_file_id,
 182                 start_line,
 183                 start_col,
 184                 end_line,
 185                 end_col,
 186             ));
 187         }
 188
 189         // Encode and append the current function's coverage mapping data
 190         coverageinfo::write_mapping_to_buffer(
 191             virtual_file_mapping,
 192             expressions,
 193             mapping_regions,
 194             coverage_mapping_buffer,
 195         );
 196     }
 197
 198     /// Construct coverage map header and the array of function records, and combine them into the
 199     /// coverage map. Save the coverage map data into the LLVM IR as a static global using a
 200     /// specific, well-known section and name.
 201     fn generate_coverage_map<'ll>(
 202         self,
 203         cx: &CodegenCx<'ll, '_>,
 204         version: u32,
 205         filenames_size: usize,
 206         filenames_val: &'ll llvm::Value,
 207     ) -> &'ll llvm::Value {
 208         debug!("cov map: filenames_size = {}, 0-based version = {}", filenames_size, version);
 209
 210         // Create the coverage data header (Note, fields 0 and 2 are now always zero,
 211         // as of `llvm::coverage::CovMapVersion::Version4`.)
 212         let zero_was_n_records_val = cx.const_u32(0);
 213         let filenames_size_val = cx.const_u32(filenames_size as u32);
 214         let zero_was_coverage_size_val = cx.const_u32(0);
 215         let version_val = cx.const_u32(version);
 216         let cov_data_header_val = cx.const_struct(
 217             &[zero_was_n_records_val, filenames_size_val, zero_was_coverage_size_val, version_val],
 218             /*packed=*/ false,
 219         );
 220
 221         // Create the complete LLVM coverage data value to add to the LLVM IR
 222         cx.const_struct(&[cov_data_header_val, filenames_val], /*packed=*/ false)
 223     }
 224 }
 225
 226 /// Construct a function record and combine it with the function's coverage mapping data.
 227 /// Save the function record into the LLVM IR as a static global using a
 228 /// specific, well-known section and name.
 229 fn save_function_record(
 230     cx: &CodegenCx<'_, '_>,
 231     covfun_section_name: &str,
 232     mangled_function_name: &str,
 233     source_hash: u64,
 234     filenames_ref: u64,
 235     coverage_mapping_buffer: Vec<u8>,
 236     is_used: bool,
 237 ) {
 238     // Concatenate the encoded coverage mappings
 239     let coverage_mapping_size = coverage_mapping_buffer.len();
 240     let coverage_mapping_val = cx.const_bytes(&coverage_mapping_buffer);
 241
 242     let func_name_hash = coverageinfo::hash_bytes(mangled_function_name.as_bytes());
 243     let func_name_hash_val = cx.const_u64(func_name_hash);
 244     let coverage_mapping_size_val = cx.const_u32(coverage_mapping_size as u32);
 245     let source_hash_val = cx.const_u64(source_hash);
 246     let filenames_ref_val = cx.const_u64(filenames_ref);
 247     let func_record_val = cx.const_struct(
 248         &[
 249             func_name_hash_val,
 250             coverage_mapping_size_val,
 251             source_hash_val,
 252             filenames_ref_val,
 253             coverage_mapping_val,
 254         ],
 255         /*packed=*/ true,
 256     );
 257
 258     coverageinfo::save_func_record_to_mod(
 259         cx,
 260         covfun_section_name,
 261         func_name_hash,
 262         func_record_val,
 263         is_used,
 264     );
 265 }
 266
 267 /// When finalizing the coverage map, `FunctionCoverage` only has the `CodeRegion`s and counters for
 268 /// the functions that went through codegen; such as public functions and "used" functions
 269 /// (functions referenced by other "used" or public items). Any other functions considered unused,
 270 /// or "Unreachable", were still parsed and processed through the MIR stage, but were not
 271 /// codegenned. (Note that `-Clink-dead-code` can force some unused code to be codegenned, but
 272 /// that flag is known to cause other errors, when combined with `-C instrument-coverage`; and
 273 /// `-Clink-dead-code` will not generate code for unused generic functions.)
 274 ///
 275 /// We can find the unused functions (including generic functions) by the set difference of all MIR
 276 /// `DefId`s (`tcx` query `mir_keys`) minus the codegenned `DefId`s (`tcx` query
 277 /// `codegened_and_inlined_items`).
 278 ///
 279 /// These unused functions are then codegen'd in one of the CGUs which is marked as the
 280 /// "code coverage dead code cgu" during the partitioning process. This prevents us from generating
 281 /// code regions for the same function more than once which can lead to linker errors regarding
 282 /// duplicate symbols.
 283 fn add_unused_functions(cx: &CodegenCx<'_, '_>) {
 284     assert!(cx.codegen_unit.is_code_coverage_dead_code_cgu());
 285
 286     let tcx = cx.tcx;
 287
 288     let ignore_unused_generics = tcx.sess.instrument_coverage_except_unused_generics();
 289
 290     let eligible_def_ids: Vec<DefId> = tcx
 291         .mir_keys(())
 292         .iter()
 293         .filter_map(|local_def_id| {
 294             let def_id = local_def_id.to_def_id();
 295             let kind = tcx.def_kind(def_id);
 296             // `mir_keys` will give us `DefId`s for all kinds of things, not
 297             // just "functions", like consts, statics, etc. Filter those out.
 298             // If `ignore_unused_generics` was specified, filter out any
 299             // generic functions from consideration as well.
 300             if !matches!(
 301                 kind,
 302                 DefKind::Fn | DefKind::AssocFn | DefKind::Closure | DefKind::Generator
 303             ) {
 304                 return None;
 305             }
 306             if ignore_unused_generics && tcx.generics_of(def_id).requires_monomorphization(tcx) {
 307                 return None;
 308             }
 309             Some(local_def_id.to_def_id())
 310         })
 311         .collect();
 312
 313     let codegenned_def_ids = tcx.codegened_and_inlined_items(());
 314
 315     for non_codegenned_def_id in
 316         eligible_def_ids.into_iter().filter(|id| !codegenned_def_ids.contains(id))
 317     {
 318         let codegen_fn_attrs = tcx.codegen_fn_attrs(non_codegenned_def_id);
 319
 320         // If a function is marked `#[no_coverage]`, then skip generating a
 321         // dead code stub for it.
 322         if codegen_fn_attrs.flags.contains(CodegenFnAttrFlags::NO_COVERAGE) {
 323             debug!("skipping unused fn marked #[no_coverage]: {:?}", non_codegenned_def_id);
 324             continue;
 325         }
 326
 327         debug!("generating unused fn: {:?}", non_codegenned_def_id);
 328         cx.define_unused_fn(non_codegenned_def_id);
 329     }
 330 }