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