compiler/rustc_codegen_llvm/src/coverageinfo/mapgen.rs

   1 use crate::common::CodegenCx;
   2 use crate::coverageinfo;
   3 use crate::llvm;
   4
   5 use llvm::coverageinfo::CounterMappingRegion;
   6 use rustc_codegen_ssa::coverageinfo::map::{Counter, CounterExpression};
   7 use rustc_codegen_ssa::traits::ConstMethods;
   8 use rustc_data_structures::fx::FxIndexSet;
   9 use rustc_llvm::RustString;
  10 use rustc_middle::mir::coverage::CodeRegion;
  11
  12 use std::ffi::CString;
  13
  14 use tracing::debug;
  15
  16 /// Generates and exports the Coverage Map.
  17 ///
  18 /// This Coverage Map complies with Coverage Mapping Format version 4 (zero-based encoded as 3),
  19 /// as defined at [LLVM Code Coverage Mapping Format](https://github.com/rust-lang/llvm-project/blob/rustc/11.0-2020-10-12/llvm/docs/CoverageMappingFormat.rst#llvm-code-coverage-mapping-format)
  20 /// and published in Rust's current (November 2020) fork of LLVM. This version is supported by the
  21 /// LLVM coverage tools (`llvm-profdata` and `llvm-cov`) bundled with Rust's fork of LLVM.
  22 ///
  23 /// Consequently, Rust's bundled version of Clang also generates Coverage Maps compliant with
  24 /// version 3. Clang's implementation of Coverage Map generation was referenced when implementing
  25 /// this Rust version, and though the format documentation is very explicit and detailed, some
  26 /// undocumented details in Clang's implementation (that may or may not be important) were also
  27 /// replicated for Rust's Coverage Map.
  28 pub fn finalize<'ll, 'tcx>(cx: &CodegenCx<'ll, 'tcx>) {
  29     // Ensure LLVM supports Coverage Map Version 4 (encoded as a zero-based value: 3).
  30     // If not, the LLVM Version must be less than 11.
  31     let version = coverageinfo::mapping_version();
  32     if version != 3 {
  33         cx.tcx.sess.fatal("rustc option `-Z instrument-coverage` requires LLVM 11 or higher.");
  34     }```
  35
  36     let function_coverage_map = match cx.coverage_context() {
  37         Some(ctx) => ctx.take_function_coverage_map(),
  38         None => return,
  39     };
  40     if function_coverage_map.is_empty() {
  41         // This module has no functions with coverage instrumentation
  42         return;
  43     }
  44
  45     let mut mapgen = CoverageMapGenerator::new();
  46
  47     // Encode coverage mappings and generate function records
  48     let mut function_data = Vec::new();
  49     for (instance, function_coverage) in function_coverage_map {
  50         debug!("Generate coverage map for: {:?}", instance);
  51
  52         let mangled_function_name = cx.tcx.symbol_name(instance).to_string();
  53         let function_source_hash = function_coverage.source_hash();
  54         let (expressions, counter_regions) =
  55             function_coverage.get_expressions_and_counter_regions();
  56
  57         let coverage_mapping_buffer = llvm::build_byte_buffer(|coverage_mapping_buffer| {
  58             mapgen.write_coverage_mapping(expressions, counter_regions, coverage_mapping_buffer);
  59         });
  60         debug_assert!(
  61             coverage_mapping_buffer.len() > 0,
  62             "Every `FunctionCoverage` should have at least one counter"
  63         );
  64
  65         function_data.push((mangled_function_name, function_source_hash, coverage_mapping_buffer));
  66     }
  67
  68     // Encode all filenames referenced by counters/expressions in this module
  69     let filenames_buffer = llvm::build_byte_buffer(|filenames_buffer| {
  70         coverageinfo::write_filenames_section_to_buffer(&mapgen.filenames, filenames_buffer);
  71     });
  72
  73     let filenames_size = filenames_buffer.len();
  74     let filenames_val = cx.const_bytes(&filenames_buffer[..]);
  75     let filenames_ref = coverageinfo::hash_bytes(filenames_buffer);
  76
  77     // Generate the LLVM IR representation of the coverage map and store it in a well-known global
  78     let cov_data_val = mapgen.generate_coverage_map(cx, version, filenames_size, filenames_val);
  79
  80     for (mangled_function_name, function_source_hash, coverage_mapping_buffer) in function_data {
  81         save_function_record(
  82             cx,
  83             mangled_function_name,
  84             function_source_hash,
  85             filenames_ref,
  86             coverage_mapping_buffer,
  87         );
  88     }
  89
  90     // Save the coverage data value to LLVM IR
  91     coverageinfo::save_cov_data_to_mod(cx, cov_data_val);
  92 }
  93
  94 struct CoverageMapGenerator {
  95     filenames: FxIndexSet<CString>,
  96 }
  97
  98 impl CoverageMapGenerator {
  99     fn new() -> Self {
 100         Self { filenames: FxIndexSet::default() }
 101     }
 102
 103     /// Using the `expressions` and `counter_regions` collected for the current function, generate
 104     /// the `mapping_regions` and `virtual_file_mapping`, and capture any new filenames. Then use
 105     /// LLVM APIs to encode the `virtual_file_mapping`, `expressions`, and `mapping_regions` into
 106     /// the given `coverage_mapping` byte buffer, compliant with the LLVM Coverage Mapping format.
 107     fn write_coverage_mapping(
 108         &mut self,
 109         expressions: Vec<CounterExpression>,
 110         counter_regions: impl Iterator<Item = (Counter, &'a CodeRegion)>,
 111         coverage_mapping_buffer: &RustString,
 112     ) {
 113         let mut counter_regions = counter_regions.collect::<Vec<_>>();
 114         if counter_regions.is_empty() {
 115             return;
 116         }
 117
 118         let mut virtual_file_mapping = Vec::new();
 119         let mut mapping_regions = Vec::new();
 120         let mut current_file_name = None;
 121         let mut current_file_id = 0;
 122
 123         // Convert the list of (Counter, CodeRegion) pairs to an array of `CounterMappingRegion`, sorted
 124         // by filename and position. Capture any new files to compute the `CounterMappingRegion`s
 125         // `file_id` (indexing files referenced by the current function), and construct the
 126         // function-specific `virtual_file_mapping` from `file_id` to its index in the module's
 127         // `filenames` array.
 128         counter_regions.sort_unstable_by_key(|(_counter, region)| *region);
 129         for (counter, region) in counter_regions {
 130             let CodeRegion { file_name, start_line, start_col, end_line, end_col } = *region;
 131             let same_file = current_file_name.as_ref().map_or(false, |p| *p == file_name);
 132             if !same_file {
 133                 if current_file_name.is_some() {
 134                     current_file_id += 1;
 135                 }
 136                 current_file_name = Some(file_name);
 137                 let c_filename = CString::new(file_name.to_string())
 138                     .expect("null error converting filename to C string");
 139                 debug!("  file_id: {} = '{:?}'", current_file_id, c_filename);
 140                 let (filenames_index, _) = self.filenames.insert_full(c_filename);
 141                 virtual_file_mapping.push(filenames_index as u32);
 142             }
 143             debug!("Adding counter {:?} to map for {:?}", counter, region);
 144             mapping_regions.push(CounterMappingRegion::code_region(
 145                 counter,
 146                 current_file_id,
 147                 start_line,
 148                 start_col,
 149                 end_line,
 150                 end_col,
 151             ));
 152         }
 153
 154         // Encode and append the current function's coverage mapping data
 155         coverageinfo::write_mapping_to_buffer(
 156             virtual_file_mapping,
 157             expressions,
 158             mapping_regions,
 159             coverage_mapping_buffer,
 160         );
 161     }
 162
 163     /// Construct coverage map header and the array of function records, and combine them into the
 164     /// coverage map. Save the coverage map data into the LLVM IR as a static global using a
 165     /// specific, well-known section and name.
 166     fn generate_coverage_map(
 167         self,
 168         cx: &CodegenCx<'ll, 'tcx>,
 169         version: u32,
 170         filenames_size: usize,
 171         filenames_val: &'ll llvm::Value,
 172     ) -> &'ll llvm::Value {
 173         debug!("cov map: filenames_size = {}, 0-based version = {}", filenames_size, version);
 174
 175         // Create the coverage data header (Note, fields 0 and 2 are now always zero,
 176         // as of `llvm::coverage::CovMapVersion::Version4`.)
 177         let zero_was_n_records_val = cx.const_u32(0);
 178         let filenames_size_val = cx.const_u32(filenames_size as u32);
 179         let zero_was_coverage_size_val = cx.const_u32(0);
 180         let version_val = cx.const_u32(version);
 181         let cov_data_header_val = cx.const_struct(
 182             &[zero_was_n_records_val, filenames_size_val, zero_was_coverage_size_val, version_val],
 183             /*packed=*/ false,
 184         );
 185
 186         // Create the complete LLVM coverage data value to add to the LLVM IR
 187         cx.const_struct(&[cov_data_header_val, filenames_val], /*packed=*/ false)
 188     }
 189 }
 190
 191 /// Construct a function record and combine it with the function's coverage mapping data.
 192 /// Save the function record into the LLVM IR as a static global using a
 193 /// specific, well-known section and name.
 194 fn save_function_record(
 195     cx: &CodegenCx<'ll, 'tcx>,
 196     mangled_function_name: String,
 197     function_source_hash: u64,
 198     filenames_ref: u64,
 199     coverage_mapping_buffer: Vec<u8>,
 200 ) {
 201     // Concatenate the encoded coverage mappings
 202     let coverage_mapping_size = coverage_mapping_buffer.len();
 203     let coverage_mapping_val = cx.const_bytes(&coverage_mapping_buffer[..]);
 204
 205     let func_name_hash = coverageinfo::hash_str(&mangled_function_name);
 206     let func_name_hash_val = cx.const_u64(func_name_hash);
 207     let coverage_mapping_size_val = cx.const_u32(coverage_mapping_size as u32);
 208     let func_hash_val = cx.const_u64(function_source_hash);
 209     let filenames_ref_val = cx.const_u64(filenames_ref);
 210     let func_record_val = cx.const_struct(
 211         &[
 212             func_name_hash_val,
 213             coverage_mapping_size_val,
 214             func_hash_val,
 215             filenames_ref_val,
 216             coverage_mapping_val,
 217         ],
 218         /*packed=*/ true,
 219     );
 220
 221     // At the present time, the coverage map for Rust assumes every instrumented function `is_used`.
 222     // Note that Clang marks functions as "unused" in `CodeGenPGO::emitEmptyCounterMapping`. (See:
 223     // https://github.com/rust-lang/llvm-project/blob/de02a75e398415bad4df27b4547c25b896c8bf3b/clang%2Flib%2FCodeGen%2FCodeGenPGO.cpp#L877-L878
 224     // for example.)
 225     //
 226     // It's not yet clear if or how this may be applied to Rust in the future, but the `is_used`
 227     // argument is available and handled similarly.
 228     let is_used = true;
 229     coverageinfo::save_func_record_to_mod(cx, func_name_hash, func_record_val, is_used);
 230 }