Enrich FIFO Logs

[mrontio]

Enriched FIFO Logs

Stall and performance analysis can be performed with the help with enriched FIFO logs.

This PR adds to DataflowBuildConfig:

• fifo_log_verbose : bool -- Control whether FIFO log output is <data_in> (false) or <data> <direction> <cycle> (true).
• fifo_log_flush : int -- Control how often the logs are flushed to disk, to allow for either performance or improved live-probing.

Example Output

An example FIFO log with fifo_log_verbose=True

# data dir cycle
1f0f 0 30190
1101 0 30191
1f0f 1 30191
0f10 0 30192
1101 1 30192

You can tell that after clock cycle 30192, the FIFO contains a single element, 0f10.

Example Usage

1. Stall Detection: With an enriched FIFO, one has to parse the logs as a stack to identify stacks that are accumulating too much.
2. Visualization tools: Enriched logs allow to make visualization tools to quickly identify optimisation opportunities, for example the following image creates a colour gradient on the max observed occupancy, and the identifies the clock latency of each unit.

Performance Characterisation

The following table shows runs of the visualised graph (above), defined using the test file's main method. The test builds a graph G with 4 nodes, one in a residual path. It then constructs a graph with MLO: A -> G -> G -> G -> B, and runs 65536 * 4 inputs to it.

Configuration	Flush	FIFO Sizing (Seconds)	Log Size (MiB)
Log Off		1.7
Default	1	7.4	20
Enriched	1	13.9	217
Default	1000	3.0	20
Enriched	1000	4.8	217
Default	65536	3.0	20
Enriched	65536	4.8	217

Interpretation:

• At flush 1 (flush to disk every line), the enriched logs slow down the FIFO sizing simulation 188%
• At flush >1000, enriched logs slow down FIFO sizing by 62%
• The enriched logs are 8.8x larger than the default ones.

Testing

We add the following tests:

• test_fifo_log_verbose_build: Test graph G with residual node
• test_fifo_log_verbose_finnloop_build: MLO A -> G -> G -> G -> B
• test_fifo_log_format_matches_rtl: Check format fifo_gauge.sv tests
• main: benchmark across configurations with large input

Files Affected

• fifo_gauge.sv: Introduce parameters LOG_VERBOSE and LOG_FLUSH and according logic
• build_dataflow_config.py: Introduce the above mentioned configurations.
• Rest of the changes thread the above files together.

[preusser-amd]

Thanks, @mrontio!
This looks good.

[auphelia]

Thanks for this PR @mrontio!
This is a great feature to have.

Besides the inline comments and the separate comment on the test file, there are two things I'd like to ask you to add:

1. Documentation for FIFO debug logging

• Add a new page docs/finn/components/streaming-fifo.rst (listed in components/index.rst) with a "Debug logging" section covering:
  • what debug_fifo=True does: FIFOs are simulated with the fifo_gauge model, and verify_rtlsim_behavioral is enabled automatically;
  • where the logs go: debug/fifo_logs//<main|FINNLoop_N>/.log, for the phases fifo_sizing and stitched_ip_rtlsim;
  • both log formats, including the header and summary line;
  • fifo_log_verbose and fifo_log_flush:
    • that they only apply with debug_fifo=True;
    • what fifo_log_flush=0 means;
    • the use case of watching logs while a simulation is running;
    • the measured effect on simulation time and log size (from your benchmark).
• Add a debug/fifo_logs/ entry to "Generated outputs" in command_line.rst that links to the new page.
• Mention in the DataflowBuildConfig comments for both settings that they only apply with debug_fifo=True.

2. Config checks in src/finn/builder/build_dataflow_checks.py

• Warning when fifo_log_verbose or fifo_log_flush differs from its default while debug_fifo=False. Please compare against the dataclass defaults rather than hard-coding 65536.
• Error when fifo_log_flush is None or negative. Currently int(cfg.fifo_log_flush) would fail partway through the build.

[mrontio]

Hi @auphelia,
I've addressed all the amendments and added the documentation as requested.

Whilst writing docs, I noticed that the previous ONNX Node -> Log name mapping was not trivial (the enumeration was not intuitive).
In commit #78e88ac I've changed the name to fit the following regex:
(FINNLoop_\d+_)*StreamingFIFO_rtl_\d+_[a-z0-9_]{8}.log
Out-take: Instead of an arbitrary enumeration, it encodes both whether it is in a FINNLoop, it's number that corresponds to the ONNX number, and the hash string that is found generated by Vivado.

That enumeration predates when I was touching it, so I just want to make sure this name collision won't become a problem for other code.

Thank you,
Michail R.