From efe9d1f0f8c91d49947c5715fe2d965bad3cafb0 Mon Sep 17 00:00:00 2001 From: Cesar_Strauss Date: Mon, 31 Aug 2020 12:15:34 +0100 Subject: [PATCH] Improve formatting and prepare the top-level structure of the GTKWave tutorial --- Documentation/gtkwave_tutorial.mdwn | 122 ++++++++-------------------- 1 file changed, 35 insertions(+), 87 deletions(-) diff --git a/Documentation/gtkwave_tutorial.mdwn b/Documentation/gtkwave_tutorial.mdwn index 4ba66a009..ca1a58ca6 100644 --- a/Documentation/gtkwave_tutorial.mdwn +++ b/Documentation/gtkwave_tutorial.mdwn @@ -1,99 +1,47 @@ -# GTKWave improvements - -* (Originally at ) -* [alu_fsm.py source](https://git.libre-soc.org/?p=soc.git;a=blob;f=src/soc/experiment/alu_fsm.py;h=9668535aedc8e507212906baf679dc37484b8e8d;hb=1d4fa2db3d660510ebeceb650188c6fcf3127fd4#l209) - -Lately, I've been investigating about generating better GTKWave "save" -files (\*.gtkw), from Python. The goal is to ease analysis of traces -generated by unit-tests, and at the same time to better understand the -inner working of modules, for which we are writing such tests. - -I am using src/soc/experiment/alu_fsm.py as a test bed for demonstration. - -To see the current work, run: - -1) python3 src/soc/experiment/alu_fsm.py -2) gtkwave test_shifter.gtkw - -Besides color, another interesting feature is collapsible group of -traces. Try selecting the opening brace of the "debug" and "internal" -groups, and double-click or press T. - -Another bonus is string traces, which allows "printf" style debugging in -the trace pane. - [[!img 2020-08-15_12-04.png size="800x" ]] -A current limitation is having to deal with signal names instead of -Signals themselves. Also, direct use of vcd.gtkw is a bit verbose. I -intend to work a bit on this, next. - -Possibly, I'll propose and contribute back improvements to the nMigen -sim.pysim.Simulator.write_vcd method, which was my inspiration for this -work. - -A more complete description follows: - -https://git.libre-soc.org/?p=soc.git;a=commitdiff;h=de64658d0a482f1d6df3c84b4087864ff65ccfef - -commit de64658d0a482f1d6df3c84b4087864ff65ccfef -Author: Cesar Strauss -Date: Thu Aug 13 19:40:35 2020 -0300 - - Demonstrates creating stylish GTKWave "save" files from python - - This is inspired on the use of the vcd.gtkw module in nMigen, used - internally to create "save" files of selected Signals, for - "Simulator.write_vcd". - - However, the vcd.gtkw module exposes a great deal of extra - possibilities, like: - - 1) Individual trace colors. - For instance, use different color styles for input, output, debug - and internal traces. - 2) Numeric bases besides the default hex. - 3) Collapsible trace groups - Useful to hide and show, at once, groups of debug, internal and - sub-module traces. - Select the opening or closing brace, then use the T key. - 4) Comments in the signal names pane - 5) Change the displayed name of a trace - 6) Sane default for initial zoom level - 7) Place markers on interesting places - 8) Put the generating file name as a comment in the file +This tutorial is about generating better GTKWave documents (*.gtkw) +from Python. The goal is to ease analysis of traces generated by +unit-tests, and at the same time to better understand the inner working +of modules, for which we are writing such tests. -https://git.libre-soc.org/?p=soc.git;a=commitdiff;h=d3a72bb0688cf343dddc069ef50ba60b9736e8d9 +# Stylish GTKWave Documents -commit d3a72bb0688cf343dddc069ef50ba60b9736e8d9 -Author: Cesar Strauss -Date: Fri Aug 14 08:06:49 2020 -0300 +In this tutorial, you will learn how to: - Demonstrates adding extra debug signals traces to the dump file +1. Use individual trace colors. + For instance, use different color styles for input, output, debug and + internal traces. +2. Use numeric bases besides the default hex. +3. Create collapsible trace groups + Useful to hide and show, at once, groups of debug, internal and + sub-module traces. + Select the opening or closing brace, then use the T key. +4. Add comments in the signal names pane +5. Change the displayed name of a trace +6. Use a sane default for initial zoom level +7. Place markers on interesting places +8. Put the generating file name as a comment in the file - At simulation time, you can declare a new signal, and use it inside - the test case, as any other signal. By including it in the "traces" - parameter of Simulator.write_vcd, it is included in the trace dump - file. +# New signals at simulation time - Useful for adding "printf" style debugging for GTKWave. +At simulation time, you can declare a new signal, and use it inside +the test case, as any other signal. By including it in the "traces" +parameter of Simulator.write_vcd, it is included in the trace dump +file. -https://git.libre-soc.org/?p=soc.git;a=commitdiff;h=1d4fa2db3d660510ebeceb650188c6fcf3127fd4 +Useful for adding "printf" style debugging for GTKWave. -commit 1d4fa2db3d660510ebeceb650188c6fcf3127fd4 (HEAD -> master, -origin/master, origin/HEAD) -Author: Cesar Strauss -Date: Fri Aug 14 08:25:36 2020 -0300 +# String traces - Demonstrates string traces +When declaring a Signal, you can pass a custom decoder that +translates the Signal logic level to a string. nMigen uses this +internally to display Enum traces, but it is available for general +use. - When declaring a Signal, you can pass a custom decoder that - translates the Signal logic level to a string. nMigen uses this - internally to display Enum traces, but it is available for general - use. +Some applications are: - Some applications are: - 1) Display a string when a signal is at high level, otherwise show a - single horizontal line. Useful to draw attention to a time interval. - 2) Display the stages of a unit test - 3) Display arbitrary debug statements along the timeline. +1. Display a string when a signal is at high level, otherwise show a + single horizontal line. Useful to draw attention to a time interval. +2. Display the stages of a unit test +3. Display arbitrary debug statements along the timeline. -- 2.30.2