src/nmutil/gtkw.py

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