src/python/m5/util/dot_writer.py

   1 # Copyright (c) 2012-2013 ARM Limited
   2 # All rights reserved.
   3 #
   4 # The license below extends only to copyright in the software and shall
   5 # not be construed as granting a license to any other intellectual
   6 # property including but not limited to intellectual property relating
   7 # to a hardware implementation of the functionality of the software
   8 # licensed hereunder.  You may use the software subject to the license
   9 # terms below provided that you ensure that this notice is replicated
  10 # unmodified and in its entirety in all distributions of the software,
  11 # modified or unmodified, in source code or in binary form.
  12 #
  13 # Redistribution and use in source and binary forms, with or without
  14 # modification, are permitted provided that the following conditions are
  15 # met: redistributions of source code must retain the above copyright
  16 # notice, this list of conditions and the following disclaimer;
  17 # redistributions in binary form must reproduce the above copyright
  18 # notice, this list of conditions and the following disclaimer in the
  19 # documentation and/or other materials provided with the distribution;
  20 # neither the name of the copyright holders nor the names of its
  21 # contributors may be used to endorse or promote products derived from
  22 # this software without specific prior written permission.
  23 #
  24 # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  25 # "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  26 # LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  27 # A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  28 # OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  29 # SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  30 # LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  31 # DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  32 # THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  33 # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  34 # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  35 #
  36 # Authors: Andreas Hansson
  37 #          Uri Wiener
  38
  39 #####################################################################
  40 #
  41 # System visualization using DOT
  42 #
  43 # While config.ini and config.json provide an almost complete listing
  44 # of a system's components and connectivity, they lack a birds-eye
  45 # view. The output generated by do_dot() is a DOT-based figure (as a
  46 # pdf and an editable svg file) and its source dot code. Nodes are
  47 # components, and edges represent the memory hierarchy: the edges are
  48 # directed, from a master to slave. Initially all nodes are
  49 # generated, and then all edges are added. do_dot should be called
  50 # with the top-most SimObject (namely root but not necessarily), the
  51 # output folder and the output dot source filename. From the given
  52 # node, both processes (node and edge creation) is performed
  53 # recursivly, traversing all children of the given root.
  54 #
  55 # pydot is required. When missing, no output will be generated.
  56 #
  57 #####################################################################
  58
  59 import m5, os, re
  60 from m5.SimObject import isRoot, isSimObjectVector
  61 from m5.params import PortRef
  62 from m5.util import warn
  63 try:
  64     import pydot
  65 except:
  66     pydot = False
  67
  68 # need to create all nodes (components) before creating edges (memory channels)
  69 def dot_create_nodes(simNode, callgraph):
  70     if isRoot(simNode):
  71         label = "root"
  72     else:
  73         label = simNode._name
  74     full_path = re.sub('\.', '_', simNode.path())
  75     # add class name under the label
  76     label = "\"" + label + " \\n: " + simNode.__class__.__name__ + "\""
  77
  78     # each component is a sub-graph (cluster)
  79     cluster = dot_create_cluster(simNode, full_path, label)
  80
  81     # create nodes per port
  82     for port_name in simNode._ports.keys():
  83         port = simNode._port_refs.get(port_name, None)
  84         if port != None:
  85             full_port_name = full_path + "_" + port_name
  86             port_node = dot_create_node(simNode, full_port_name, port_name)
  87             cluster.add_node(port_node)
  88
  89     # recurse to children
  90     if simNode._children:
  91         for c in simNode._children:
  92             child = simNode._children[c]
  93             if isSimObjectVector(child):
  94                 for obj in child:
  95                     dot_create_nodes(obj, cluster)
  96             else:
  97                 dot_create_nodes(child, cluster)
  98
  99     callgraph.add_subgraph(cluster)
 100
 101 # create all edges according to memory hierarchy
 102 def dot_create_edges(simNode, callgraph):
 103     for port_name in simNode._ports.keys():
 104         port = simNode._port_refs.get(port_name, None)
 105         if port != None:
 106             full_path = re.sub('\.', '_', simNode.path())
 107             full_port_name = full_path + "_" + port_name
 108             port_node = dot_create_node(simNode, full_port_name, port_name)
 109             # create edges
 110             if isinstance(port, PortRef):
 111                 dot_add_edge(simNode, callgraph, full_port_name, port)
 112             else:
 113                 for p in port.elements:
 114                     dot_add_edge(simNode, callgraph, full_port_name, p)
 115
 116     # recurse to children
 117     if simNode._children:
 118         for c in simNode._children:
 119             child = simNode._children[c]
 120             if isSimObjectVector(child):
 121                 for obj in child:
 122                     dot_create_edges(obj, callgraph)
 123             else:
 124                 dot_create_edges(child, callgraph)
 125
 126 def dot_add_edge(simNode, callgraph, full_port_name, peerPort):
 127     if peerPort.role == "MASTER":
 128         peer_port_name = re.sub('\.', '_', peerPort.peer.simobj.path() \
 129                 + "." + peerPort.peer.name)
 130         callgraph.add_edge(pydot.Edge(full_port_name, peer_port_name))
 131
 132 def dot_create_cluster(simNode, full_path, label):
 133     # get the parameter values of the node and use them as a tooltip
 134     ini_strings = []
 135     for param in sorted(simNode._params.keys()):
 136         value = simNode._values.get(param)
 137         if value != None:
 138             # parameter name = value in HTML friendly format
 139             ini_strings.append(str(param) + "&#61;" +
 140                                simNode._values[param].ini_str())
 141     # join all the parameters with an HTML newline
 142     tooltip = "&#10;".join(ini_strings)
 143
 144     return pydot.Cluster( \
 145                          full_path, \
 146                          shape = "Mrecord", \
 147                          label = label, \
 148                          tooltip = "\"" + tooltip + "\"", \
 149                          style = "\"rounded, filled\"", \
 150                          color = "#000000", \
 151                          fillcolor = dot_gen_colour(simNode), \
 152                          fontname = "Arial", \
 153                          fontsize = "14", \
 154                          fontcolor = "#000000" \
 155                          )
 156
 157 def dot_create_node(simNode, full_path, label):
 158     return pydot.Node( \
 159                          full_path, \
 160                          shape = "Mrecord", \
 161                          label = label, \
 162                          style = "\"rounded, filled\"", \
 163                          color = "#000000", \
 164                          fillcolor = dot_gen_colour(simNode, True), \
 165                          fontname = "Arial", \
 166                          fontsize = "14", \
 167                          fontcolor = "#000000" \
 168                          )
 169
 170 # an enumerator for different kinds of node types, at the moment we
 171 # discern the majority of node types, with the caches being the
 172 # notable exception
 173 class NodeType:
 174     SYS = 0
 175     CPU = 1
 176     BUS = 2
 177     MEM = 3
 178     DEV = 4
 179     OTHER = 5
 180
 181 # based on the sim object, determine the node type
 182 def get_node_type(simNode):
 183     if isinstance(simNode, m5.objects.System):
 184         return NodeType.SYS
 185     # NULL ISA has no BaseCPU or PioDevice, so check if these names
 186     # exists before using them
 187     elif 'BaseCPU' in dir(m5.objects) and \
 188             isinstance(simNode, m5.objects.BaseCPU):
 189         return NodeType.CPU
 190     elif 'PioDevice' in dir(m5.objects) and \
 191             isinstance(simNode, m5.objects.PioDevice):
 192         return NodeType.DEV
 193     elif isinstance(simNode, m5.objects.BaseBus):
 194         return NodeType.BUS
 195     elif isinstance(simNode, m5.objects.AbstractMemory):
 196         return NodeType.MEM
 197     else:
 198         return NodeType.OTHER
 199
 200 # based on the node type, determine the colour as an RGB tuple, the
 201 # palette is rather arbitrary at this point (some coherent natural
 202 # tones), and someone that feels artistic should probably have a look
 203 def get_type_colour(nodeType):
 204     if nodeType == NodeType.SYS:
 205         return (228, 231, 235)
 206     elif nodeType == NodeType.CPU:
 207         return (187, 198, 217)
 208     elif nodeType == NodeType.BUS:
 209         return (111, 121, 140)
 210     elif nodeType == NodeType.MEM:
 211         return (94, 89, 88)
 212     elif nodeType == NodeType.DEV:
 213         return (199, 167, 147)
 214     elif nodeType == NodeType.OTHER:
 215         # use a relatively gray shade
 216         return (186, 182, 174)
 217
 218 # generate colour for a node, either corresponding to a sim object or a
 219 # port
 220 def dot_gen_colour(simNode, isPort = False):
 221     # determine the type of the current node, and also its parent, if
 222     # the node is not the same type as the parent then we use the base
 223     # colour for its type
 224     node_type = get_node_type(simNode)
 225     if simNode._parent:
 226         parent_type = get_node_type(simNode._parent)
 227     else:
 228         parent_type = NodeType.OTHER
 229
 230     # if this node is the same type as the parent, then scale the
 231     # colour based on the depth such that the deeper levels in the
 232     # hierarchy get darker colours
 233     if node_type == parent_type:
 234         # start out with a depth of zero
 235         depth = 0
 236         parent = simNode._parent
 237         # find the closes parent that is not the same type
 238         while parent and get_node_type(parent) == parent_type:
 239             depth = depth + 1
 240             parent = parent._parent
 241         node_colour = get_type_colour(parent_type)
 242         # slightly arbitrary, but assume that the depth is less than
 243         # five levels
 244         r, g, b = map(lambda x: x * max(1 - depth / 7.0, 0.3), node_colour)
 245     else:
 246         node_colour = get_type_colour(node_type)
 247         r, g, b = node_colour
 248
 249     # if we are colouring a port, then make it a slightly darker shade
 250     # than the node that encapsulates it, once again use a magic constant
 251     if isPort:
 252         r, g, b = map(lambda x: 0.8 * x, (r, g, b))
 253
 254     return dot_rgb_to_html(r, g, b)
 255
 256 def dot_rgb_to_html(r, g, b):
 257     return "#%.2x%.2x%.2x" % (r, g, b)
 258
 259 def do_dot(root, outdir, dotFilename):
 260     if not pydot:
 261         return
 262     # * use ranksep > 1.0 for for vertical separation between nodes
 263     # especially useful if you need to annotate edges using e.g. visio
 264     # which accepts svg format
 265     # * no need for hoizontal separation as nothing moves horizonally
 266     callgraph = pydot.Dot(graph_type='digraph', ranksep='1.3')
 267     dot_create_nodes(root, callgraph)
 268     dot_create_edges(root, callgraph)
 269     dot_filename = os.path.join(outdir, dotFilename)
 270     callgraph.write(dot_filename)
 271     try:
 272         # dot crashes if the figure is extremely wide.
 273         # So avoid terminating simulation unnecessarily
 274         callgraph.write_svg(dot_filename + ".svg")
 275         callgraph.write_pdf(dot_filename + ".pdf")
 276     except:
 277         warn("failed to generate dot output from %s", dot_filename)