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