diff --git a/src/img/coverage-graphviz-01.png b/src/img/coverage-graphviz-01.png deleted file mode 100644 index cf7e1e76b..000000000 Binary files a/src/img/coverage-graphviz-01.png and /dev/null differ diff --git a/src/img/coverage-spanview-01.png b/src/img/coverage-spanview-01.png deleted file mode 100644 index f3e4b3535..000000000 Binary files a/src/img/coverage-spanview-01.png and /dev/null differ diff --git a/src/llvm-coverage-instrumentation.md b/src/llvm-coverage-instrumentation.md index 7147e5dbb..9379a57f6 100644 --- a/src/llvm-coverage-instrumentation.md +++ b/src/llvm-coverage-instrumentation.md @@ -335,20 +335,14 @@ The `Instrumentor`'s `inject_counters()` uses the `CoverageGraph` to compute the best places to inject coverage counters, as MIR `Statement`s, with the following steps: -1. Depending on the debugging configurations in `rustc`'s, `config.toml`, - and `rustc` command line flags, various debugging features may be enabled - to enhance `debug!()` messages in logs, and to generate various "dump" files, - to help developers understand the MIR transformation process for coverage. - Most of the debugging features are implemented in the [`debug`][debug] - sub-module. -2. [`generate_coverage_spans()`][generate-coverage-spans] computes the minimum set of distinct, +1. [`generate_coverage_spans()`][generate-coverage-spans] computes the minimum set of distinct, non-branching code regions, from the MIR. These `CoverageSpan`s represent a span of code that must be counted. -3. [`make_bcb_counters()`][make-bcb-counters] generates `CoverageKind::Counter`s and +2. [`make_bcb_counters()`][make-bcb-counters] generates `CoverageKind::Counter`s and `CoverageKind::Expression`s for each `CoverageSpan`, plus additional `intermediate_expressions`[^intermediate-expressions], not associated with any `CodeRegion`, but are required to compute a final `Expression` value for a `CodeRegion`. -4. Inject the new counters into the MIR, as new `StatementKind::Coverage` +3. Inject the new counters into the MIR, as new `StatementKind::Coverage` statements. This is done by three distinct functions: - `inject_coverage_span_counters()` - `inject_indirect_counters()` @@ -420,66 +414,12 @@ The BCB CFG is critical to simplifying the coverage analysis by ensuring graph p queries (`is_dominated_by()`, `predecessors`, `successors`, etc.) have branch (control flow) significance. -To visualize the `CoverageGraph`, you can generate a _graphviz_ `*.dot` -file with the following `rustc` flags:[^graphviz-dark-mode] - -[^graphviz-dark-mode]: This image also applies `-Z graphviz-dark-mode`, to -produce a Graphviz document with "dark mode" styling. If you use a dark mode or -theme in your development environment, you will probably want to use this -option so you can review the graphviz output without straining your vision. - -```shell -$ rustc -C instrument-coverage -Z dump-mir=InstrumentCoverage \ - -Z dump-mir-graphviz some_rust_source.rs -``` - -The `-Z dump-mir` flag requests [MIR debugging -output][mir-debugging] (generating `*.mir` files, by default). -`-Z dump-mir-graphviz` additionally generates `*.dot` files. -`-Z dump-mir=InstrumentCoverage` restricts these files to the -`InstrumentCoverage` pass. All files are written to the `./mir_dump/` -directory, by default. - -Files with names ending in `.-------.InstrumentCoverage.0.dot` contain the -_graphviz_ representations of a `CoverageGraph` (one for each MIR, that is, -for each function and closure): - -cropped image of a sample CoverageGraph in graphviz format -
- -This image shows each `BasicCoverageBlock` as a rectangular _node_, with -directional edges (the arrows) leading from each node to its `successors()`. -The nodes contain information in sections: - -1. The gray header has a label showing the BCB ID (or _index_ for looking up - its `BasicCoverageBlockData`). -2. The first content section shows the assigned `Counter` or `Expression` for - each contiguous section of code. (There may be more than one `Expression` - incremented by the same `Counter` for noncontiguous sections of code - representing the same sequential actions.) Note the code is represented by - the line and column ranges (for example: `52:28-52:33`, representing the - original source line 52, for columns 28-33). These are followed by the MIR - `Statement` or `Terminator` represented by that source range. (How these - coverage regions are determined is discussed in the following section.) -3. The final section(s) show the MIR `BasicBlock`s (by ID/index and its - `TerminatorKind`) contained in this BCB. The last BCB is separated out - because its `successors()` determine the edges leading out of the BCB, and - into the `leading_bb()` (first `BasicBlock`) of each successor BCB. - -Note, to find the `BasicCoverageBlock` from a final BCB `Terminator`'s -successor `BasicBlock`, there is an index and helper -function--[`bcb_from_bb()`][bcb-from-bb]--to look up a `BasicCoverageBlock` from -*any* contained `BasicBlock`. - [directed-graph]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_data_structures/graph/trait.DirectedGraph.html [graph-traits]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_data_structures/graph/index.html#traits [mir-dev-guide]: mir/index.md [compute-basic-coverage-blocks]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_mir_transform/coverage/graph/struct.CoverageGraph.html#method.compute_basic_coverage_blocks [simplify-cfg]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_mir_transform/simplify/enum.SimplifyCfg.html [rust-lang/rust#78544]: https://github.com/rust-lang/rust/issues/78544 -[mir-debugging]: mir/debugging.md -[bcb-from-bb]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_mir_transform/coverage/graph/struct.CoverageGraph.html#method.bcb_from_bb ### `CoverageSpans` @@ -498,32 +438,6 @@ The final stage of `generate_coverage_spans()` is handled by merges and de-duplicates them, and returns an optimal, minimal set of `CoverageSpan`s that can be used to assign coverage `Counter`s or `Expression`s, one-for-one. -An visual, interactive representation of the final `CoverageSpan`s can be -generated with the following `rustc` flags: - -```shell -$ rustc -C instrument-coverage -Z dump-mir=InstrumentCoverage \ - -Z dump-mir-spanview some_rust_source.rs -``` - -These flags request Spanview output for the `InstrumentCoverage` pass, and the -resulting files (one for each MIR, that is, for each function or closure) can be -found in the `mir_dump` directory (by default), with the extension: -`.-------.InstrumentCoverage.0.html`. - -cropped image of a sample Spanview in a browser -
- -The image above shows one such example. The orange and blue backgrounds -highlight alternating `CoverageSpan`s from the refined set. Hovering over a -line expands the output on that line to show the MIR `BasicBlock` IDs covered -by each `CoverageSpan`. While hovering, the `CoverageSpan` under the pointer -also has a _tooltip_ block of text, showing even more detail, including the -MIR `Statement`s and `Terminator`s contributing to the `CoverageSpan`, and -their individual `Span`s (which should be encapsulated within the code region -of the refined `CoverageSpan`) - [coverage-spans]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_mir_transform/coverage/spans/struct.CoverageSpans.html [coverage-span]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_mir_transform/coverage/spans/struct.CoverageSpan.html [to-refined-spans]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_mir_transform/coverage/spans/struct.CoverageSpans.html#method.to_refined_spans @@ -622,12 +536,3 @@ so the counter is only incremented when traversing the branch edge. [inject-coverage-span-counters]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_mir_transform/coverage/struct.Instrumentor.html#method.inject_coverage_span_counters [inject-indirect-counters]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_mir_transform/coverage/struct.Instrumentor.html#method.inject_indirect_counters [inject-intermediate-expression]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_mir_transform/coverage/fn.inject_intermediate_expression.html - -### Additional Debugging Support - -See the -[crate documentation for `rustc_mir::transform::coverage::debug`][coverage-debugging] -for a detailed description of the debug output, logging, and configuration options -available to developers working on the `InstrumentCoverage` pass. - -[coverage-debugging]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_mir_transform/coverage/debug/index.html