Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Remove outdated references to coverage debug code #1797

Merged
merged 1 commit into from
Sep 21, 2023
Merged

Remove outdated references to coverage debug code #1797

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file removed src/img/coverage-graphviz-01.png
View file
Open in desktop
Binary file not shown.
Binary file removed src/img/coverage-spanview-01.png
View file
Open in desktop
Binary file not shown.
101 changes: 3 additions & 98 deletions src/llvm-coverage-instrumentation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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()`
Expand Down Expand Up @@ -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):

<img alt="cropped image of a sample CoverageGraph in graphviz format"
src="img/coverage-graphviz-01.png" style="border: 1px solid gray" class="center"/>
<br/>

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`

Expand All @@ -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`.

<img alt="cropped image of a sample Spanview in a browser"
src="img/coverage-spanview-01.png" style="border: 1px solid gray" class="center"/>
<br/>

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
Expand Down Expand Up @@ -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