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. Can also be "formal"
  27                  when the file comes from a formal engine
  28     :param marker: initial location of a marker
  29     :param clk_period: clock period in seconds, helping
  30                        to set a reasonable initial zoom level.
  31                        Use together with ``time_resolution_unit``.
  32     :param time_resolution_unit: use "ps" or "ns". Derived from the units of
  33                                  the "timescale" on the VCD file. Used with
  34                                  "clk_period" to set a default zoom level
  35
  36     **gtkw_style format**
  37
  38     Syntax: ``{selector: {attribute: value, ...}, ...}``
  39
  40     "selector" can be a signal, class or group
  41
  42     Signal groups propagate most attributes to their children
  43
  44     Attribute choices:
  45
  46     * module: absolute path of the current module
  47     * submodule: same as above, but relative
  48     * color: trace color
  49     * base: numerical base for value display
  50     * display: alternate text to display in the signal pane
  51     * comment: comment to display in the signal pane
  52     * bit: select a bit from a wide signal. MSB is zero, unfortunately
  53
  54     **gtkw_dom format**
  55
  56     Syntax: ``[signal, (signal, class), (group, [children]), comment, ...]``
  57
  58     The DOM is a list of nodes.
  59
  60     Nodes are signals, signal groups or comments.
  61
  62     * signals are strings, or tuples: ``(signal name, class, class, ...)``
  63     * signal groups are tuples: ``(group name, class, class, ..., [nodes])``
  64     * comments are: ``{'comment': 'comment string'}``
  65
  66     In place of a class name, an inline class description can be used.
  67     ``(signal, {attribute: value, ...}, ...)``
  68
  69     An anonymous group can be used to apply a style to a group of signals.
  70     ``({attribute: value}, [signal, signal, ...])``
  71     """
  72     colors = {
  73         'blue': GTKWColor.blue,
  74         'cycle': GTKWColor.cycle,
  75         'green': GTKWColor.green,
  76         'indigo': GTKWColor.indigo,
  77         'normal': GTKWColor.normal,
  78         'orange': GTKWColor.orange,
  79         'red': GTKWColor.red,
  80         'violet': GTKWColor.violet,
  81         'yellow': GTKWColor.yellow,
  82     }
  83
  84     with open(gtkw_name, "wt") as gtkw_file:
  85         gtkw = GTKWSave(gtkw_file)
  86         if loc is not None:
  87             gtkw.comment("Auto-generated by " + loc)
  88         gtkw.dumpfile(vcd_name)
  89         # set a reasonable zoom level
  90         # also, move the marker to an interesting place
  91         if zoom == "formal":
  92             # output from formal engines looks good at this zoom level
  93             zoom = -6.3
  94         if zoom is None:
  95             zoom = -42.8 - log2(clk_period)
  96             # base zoom level is affected by time resolution units
  97             if time_resolution_unit == "ns":
  98                 zoom = zoom + log2(1e3)
  99         gtkw.zoom_markers(zoom, marker)
 100
 101         # create an empty style, if needed
 102         if gtkw_style is None:
 103             gtkw_style = dict()
 104
 105         # create an empty root selector, if needed
 106         root_style = gtkw_style.get('', dict())
 107
 108         # apply styles to the root selector, if provided
 109         if module is not None:
 110             root_style['module'] = module
 111         if color is not None:
 112             root_style['color'] = color
 113         if base is not None:
 114             root_style['base'] = base
 115         # base cannot be None, use 'hex' by default
 116         if root_style.get('base') is None:
 117             root_style['base'] = 'hex'
 118
 119         # recursively walk the DOM
 120         def walk(dom, style):
 121             for node in dom:
 122                 node_name = None
 123                 children = None
 124                 # copy the style from the parent
 125                 node_style = style.copy()
 126                 # node is a signal name string
 127                 if isinstance(node, str):
 128                     node_name = node
 129                     # apply style from node name, if specified
 130                     if node_name in gtkw_style:
 131                         node_style.update(gtkw_style[node_name])
 132                 # node is a tuple
 133                 # could be a signal or a group
 134                 elif isinstance(node, tuple):
 135                     node_name = node[0]
 136                     # collect styles from the selectors
 137                     # order goes from the most specific to most generic
 138                     # which means earlier selectors override later ones
 139                     for selector in reversed(node):
 140                         # update the node style from the selector
 141                         if isinstance(selector, str):
 142                             if selector in gtkw_style:
 143                                 node_style.update(gtkw_style[selector])
 144                         # apply an inline style description
 145                         elif isinstance(selector, dict):
 146                             node_style.update(selector)
 147                     # node is a group if it has a child list
 148                     if isinstance(node[-1], list):
 149                         children = node[-1]
 150                 # comment
 151                 elif isinstance(node, dict):
 152                     if 'comment' in node:
 153                         gtkw.blank(node['comment'])
 154                 # merge the submodule into the module path
 155                 if 'submodule' in node_style:
 156                     node_module = node_style['submodule']
 157                     if 'module' in node_style:
 158                         node_top_module = node_style['module']
 159                         node_module = node_top_module + '.' + node_module
 160                     # update the module path
 161                     node_style['module'] = node_module
 162                     # don't propagate this attribute to children
 163                     del node_style['submodule']
 164                 # emit the group delimiters and walk over the child list
 165                 if children is not None:
 166                     # only emit a group if it has a name
 167                     if isinstance(node_name, str):
 168                         gtkw.begin_group(node_name)
 169                     # pass on the group style to its children
 170                     walk(children, node_style)
 171                     if isinstance(node_name, str):
 172                         gtkw.end_group(node_name)
 173                 # emit a trace, if the node is a signal
 174                 elif node_name is not None:
 175                     signal_name = node_name
 176                     # prepend module name to signal
 177                     if 'module' in node_style:
 178                         node_module = node_style['module']
 179                         if node_module is not None:
 180                             signal_name = node_module + '.' + signal_name
 181                     node_color = colors.get(node_style.get('color'))
 182                     node_base = node_style.get('base')
 183                     display = node_style.get('display')
 184                     if 'bit' in node_style:
 185                         bit = node_style['bit']
 186                         signal_name = f'({bit}){signal_name}'
 187                     gtkw.trace(signal_name, color=node_color,
 188                                datafmt=node_base, alias=display)
 189
 190         walk(gtkw_dom, root_style)