src/nmutil/gtkw.py

   1 """
   2     This work is funded through NLnet under Grant 2019-02-012
   3
   4     License: LGPLv3+
   5
   6
   7 """
   8 from vcd.gtkw import GTKWSave, GTKWColor
   9 from math import log2
  10
  11
  12 def write_gtkw(gtkw_name, vcd_name, gtkw_dom, gtkw_style=None,
  13                module=None, loc=None, color=None, base=None,
  14                zoom=None, marker=-1, clk_period=1e-6,
  15                time_resolution_unit="ps"):
  16     """ Write a GTKWave document according to the supplied style and DOM.
  17
  18     :param gtkw_name: name of the generated GTKWave document
  19     :param vcd_name: name of the waveform file
  20     :param gtkw_dom: DOM style description for the trace pane
  21     :param gtkw_style: style for signals, classes and groups
  22     :param module: default module
  23     :param color: default trace color
  24     :param base: default numerical base
  25     :param loc: source code location to include as a comment
  26     :param zoom: initial zoom level, in GTKWave format
  27     :param marker: initial location of a marker
  28     :param clk_period: clock period in seconds, helping
  29                        to set a reasonable initial zoom level.
  30                        Use together with ``time_resolution_unit``.
  31     :param time_resolution_unit: use "ps" or "ns". Derived from the units of
  32                                  the "timescale" on the VCD file. Used with
  33                                  "clk_period" to set a default zoom level
  34
  35     **gtkw_style format**
  36
  37     Syntax: ``{selector: {attribute: value, ...}, ...}``
  38
  39     "selector" can be a signal, class or group
  40
  41     Signal groups propagate most attributes to their children
  42
  43     Attribute choices:
  44
  45     * module: instance path, for prepending to the signal name
  46     * color: trace color
  47     * base: numerical base for value display
  48     * display: alternate text to display in the signal pane
  49     * comment: comment to display in the signal pane
  50     * bit: select a bit from a wide signal. MSB is zero, unfortunately
  51
  52     **gtkw_dom format**
  53
  54     Syntax: ``[signal, (signal, class), (group, [children]), comment, ...]``
  55
  56     The DOM is a list of nodes.
  57
  58     Nodes are signals, signal groups or comments.
  59
  60     * signals are strings, or tuples: ``(signal name, class, class, ...)``
  61     * signal groups are tuples: ``(group name, class, class, ..., [nodes])``
  62     * comments are: ``{'comment': 'comment string'}``
  63
  64     In place of a class name, an inline class description can be used.
  65     ``(signal, {attribute: value, ...}, ...)``
  66     """
  67     colors = {
  68         'blue': GTKWColor.blue,
  69         'cycle': GTKWColor.cycle,
  70         'green': GTKWColor.green,
  71         'indigo': GTKWColor.indigo,
  72         'normal': GTKWColor.normal,
  73         'orange': GTKWColor.orange,
  74         'red': GTKWColor.red,
  75         'violet': GTKWColor.violet,
  76         'yellow': GTKWColor.yellow,
  77     }
  78
  79     with open(gtkw_name, "wt") as gtkw_file:
  80         gtkw = GTKWSave(gtkw_file)
  81         if loc is not None:
  82             gtkw.comment("Auto-generated by " + loc)
  83         gtkw.dumpfile(vcd_name)
  84         # set a reasonable zoom level
  85         # also, move the marker to an interesting place
  86         if zoom is None:
  87             zoom = -42.8 - log2(clk_period)
  88             # base zoom level is affected by time resolution units
  89             if time_resolution_unit == "ns":
  90                 zoom = zoom + log2(1e3)
  91         gtkw.zoom_markers(zoom, marker)
  92
  93         # create an empty style, if needed
  94         if gtkw_style is None:
  95             gtkw_style = dict()
  96
  97         # create an empty root selector, if needed
  98         root_style = gtkw_style.get('', dict())
  99
 100         # apply styles to the root selector, if provided
 101         if module is not None:
 102             root_style['module'] = module
 103         if color is not None:
 104             root_style['color'] = color
 105         if base is not None:
 106             root_style['base'] = base
 107         # base cannot be None, use 'hex' by default
 108         if root_style.get('base') is None:
 109             root_style['base'] = 'hex'
 110
 111         # recursively walk the DOM
 112         def walk(dom, style):
 113             for node in dom:
 114                 node_name = None
 115                 children = None
 116                 # copy the style from the parent
 117                 node_style = style.copy()
 118                 # node is a signal name string
 119                 if isinstance(node, str):
 120                     node_name = node
 121                     # apply style from node name, if specified
 122                     if node_name in gtkw_style:
 123                         node_style.update(gtkw_style[node_name])
 124                 # node is a tuple
 125                 # could be a signal or a group
 126                 elif isinstance(node, tuple):
 127                     node_name = node[0]
 128                     # collect styles from the selectors
 129                     # order goes from the most specific to most generic
 130                     # which means earlier selectors override later ones
 131                     for selector in reversed(node):
 132                         # update the node style from the selector
 133                         if isinstance(selector, str):
 134                             if selector in gtkw_style:
 135                                 node_style.update(gtkw_style[selector])
 136                         # apply an inline style description
 137                         elif isinstance(selector, dict):
 138                             node_style.update(selector)
 139                     # node is a group if it has a child list
 140                     if isinstance(node[-1], list):
 141                         children = node[-1]
 142                 # comment
 143                 elif isinstance(node, dict):
 144                     if 'comment' in node:
 145                         gtkw.blank(node['comment'])
 146                 # emit the group delimiters and walk over the child list
 147                 if children is not None:
 148                     gtkw.begin_group(node_name)
 149                     # pass on the group style to its children
 150                     walk(children, node_style)
 151                     gtkw.end_group(node_name)
 152                 # emit a trace, if the node is a signal
 153                 elif node_name is not None:
 154                     signal_name = node_name
 155                     # prepend module name to signal
 156                     if 'module' in node_style:
 157                         node_module = node_style['module']
 158                         if node_module is not None:
 159                             signal_name = node_module + '.' + signal_name
 160                     node_color = colors.get(node_style.get('color'))
 161                     node_base = node_style.get('base')
 162                     display = node_style.get('display')
 163                     if 'bit' in node_style:
 164                         bit = node_style['bit']
 165                         signal_name = f'({bit}){signal_name}'
 166                     gtkw.trace(signal_name, color=node_color,
 167                                datafmt=node_base, alias=display)
 168
 169         walk(gtkw_dom, root_style)