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