Coverage Model
==============

Functional coverage (work in progress)
--------------------------------------

This flow extracts functional coverage information from the
instruction trace generated by ISS. It's independent of the instruction generation
flow and does not require a tracer implementation in the RTL. You can use this
flow as long as your program can be run with an ISS supported in this flow. The
flow parses the instruction trace log and converts it to a CSV trace format. After
that, a SV test is run to process the CSV trace files and sample functional
coverage from there.

The functional covergroup is defined in `riscv_instr_cover_group.sv`_.
It includes below major categories:

- Cover all operands for each instruction
- Hazard conditions
- Corner cases like overflow, underflow, divide by zero
- Aligned/unaligned load/store
- Positive/negative immediate value
- Forward/backward branches, branch hit history
- Hint instruction
- Illegal instruction
- All compressed and non-compressed opcode
- Access to all implemened privileged CSR
- Exception and interrupt

.. _riscv_instr_cover_group.sv: https://github.com/google/riscv-dv/blob/master/src/riscv_instr_cover_group.sv

The functional covergroup is still under active development. Please feel free to
add anything you are interested or file a bug for any feature request.

Before start, please check the you have modified `riscv_core_setting.sv`_ to reflect your processor capabilities. The covergroup is selectively instantiated based on this setting so that you don't need to deal with excluding unrelated coverpoints later. You also need to get the Spike ISS or riscvOVPsim ISS (riscv-ovpsim) setup before running this flow::

    # Process spike simulation log and collect functional coverage
    cov --dir out/spike_sim

    # Get the command reference
    cov --help

    # Run the coverage flow with predefined targets
    cov --dir out/spike_sim --target rv32imc

The coverage sampling from the CSV could be time consuming if you have a large
number of log to process. You can split them to small batches and run with LSF
in parallel::

    # Split the run to process 5 CSV at a time, and run with LSF
    cov --dir out/spike_sim --lsf_cmd "bsub ....." -bz 5

.. _riscv_core_setting.sv: https://github.com/google/riscv-dv/blob/master/target/rv32imc/riscv_core_setting.sv

