seafoam 0.2

data/bin/bgv2isabelle

@@ -0,0 +1,53 @@
+#!/usr/bin/env ruby
+
+require 'seafoam'
+
+# definition eg_short_cut_or1 :: IRGraph where
+#   "eg_short_cut_or1 =
+#     (add_node 14 ReturnNode [13] []
+#     (add_node 13 PhiNode [10, 11, 12] []
+#     (add_node 12 (ConstantNode 0) [] []
+#     (add_node 11 (ConstantNode 42) [] []
+#     (add_node 10 MergeNode [7, 9] [14]
+#     (add_node 9 EndNode [] []
+#     (add_node 8 BeginNode [] [9]
+#     (add_node 7 EndNode [] []
+#     (add_node 6 BeginNode [] [7]
+#     (add_node 5 IfNode [3] [6, 8]
+#     (add_node 3 (ShortCircuitOrNode False False) [1, 2] []
+#     (add_node 2 (ParameterNode 1) [] []
+#     (add_node 1 (ParameterNode 0) [] []
+#     (add_node 0 StartNode [] [5]
+#     empty_graph))))))))))))))"
+
+ARGV.each do |file|
+  parser = Seafoam::BGV::BGVParser.new(File.new(file))
+  parser.read_file_header
+  parser.skip_document_props
+
+  loop do
+    index, = parser.read_graph_preheader
+    break unless index
+
+    graph_header = parser.read_graph_header
+    graph = parser.read_graph
+
+    puts "graph#{index} = # #{parser.graph_name(graph_header)}"
+
+    graph.nodes.each_value do |node|
+      node_class = node.props[:node_class][:node_class]
+      case node_class
+      when 'org.graalvm.compiler.nodes.ConstantNode'
+        desc = "(ConstantNode #{node.props['rawvalue']})"
+      when 'org.graalvm.compiler.nodes.ParameterNode'
+        desc = "(ParameterNode #{node.props['index']})"
+      else
+        desc = node_class.split('.').last
+      end
+      inputs = node.inputs.map(&:from).map(&:id)
+      outputs = node.outputs.map(&:to).map(&:id)
+      puts " (add_node #{node.id} #{desc} #{inputs.inspect} #{outputs.inspect}"
+    end
+    puts ' empty_graph' + (')' * graph.nodes.size)
+  end
+end

data/bin/bgv2json

@@ -0,0 +1,42 @@
+#!/usr/bin/env ruby
+
+require 'seafoam'
+require 'json'
+
+ARGV.each do |file|
+  parser = Seafoam::BGV::BGVParser.new(File.new(file))
+  parser.read_file_header
+  parser.skip_document_props
+
+  loop do
+    index, = parser.read_graph_preheader
+    break unless index
+
+    graph_header = parser.read_graph_header
+
+    graph = parser.read_graph
+    Seafoam::Annotators.apply graph
+
+    name = parser.graph_name(graph_header)
+
+    nodes = []
+    edges = []
+
+    graph.nodes.each_value do |node|
+      nodes.push({
+        id: node.id,
+        props: node.props
+      })
+
+      node.outputs.each do |edge|
+        edges.push({
+          from: edge.from.id,
+          to: edge.to.id,
+          props: edge.props
+        })
+      end
+    end
+
+    puts JSON.generate({name: name, props: graph.props, nodes: nodes, edges: edges})
+  end
+end

data/bin/seafoam

@@ -0,0 +1,24 @@
+#!/usr/bin/env ruby
+
+require 'seafoam'
+
+# This is the 'seafoam' command line entry point.
+
+begin
+  # Load configuraiton.
+  config = Seafoam::Config.new
+  config.load_config
+
+  # Run the command line.
+  commands = Seafoam::Commands.new($stdout, config)
+  commands.run(*ARGV)
+rescue StandardError => e
+  if $DEBUG
+    # Re-raise the exception so the user sees it, it debugging is
+    # enabled (ruby -d).
+    raise e
+  else
+    # Otherwise, just print the message.
+    warn "seafoam: #{e.message}"
+  end
+end

data/docs/annotators.md

@@ -0,0 +1,43 @@
+# Annotators
+
+The model of Seafoam is that it is a directed graph, with nodes annotated with a
+bag of key-value properties. When graphs are read they'll have some initial
+properties. Seafoam may add more properties. The output routines then draw the
+graph using the graph structure itself and also the properties.
+
+*Annotators* are routines that add extra properties to graphs to help the user
+understand them. They usually have knowledge of how the graph is structured, and
+use this to make the graph easier to read or to make important information in
+them stand out.
+
+We call properties with symbol keys *annotations*, as they're added by the
+annotators.
+
+Annotators are similar to filters in IGV.
+
+Appropriate annotators are automatically selected and applied to graphs.
+
+The rendering commands recognize these annotations, so annotators will probably
+want to add them:
+
+* `:label` on nodes and edges
+* `:out_annotation` on nodes
+* `:hidden` on nodes only, to not show them (*remove frame state* for example in IGV terminology)
+* `:inlined` on nodes only, to indicate the node should be shown immediately above each node using it (*reduce edges* in IGV terminology)
+* `:kind` on nodes only, which can be `info`, `input`, `control`, `effect`, `virtual`, `calc`, `guard`, or `other`
+* `:kind` on edges only, which can be `info`, `control`, `loop`, or `data`
+* `:reverse` on edges only
+* `:spotlight` for nodes as part of spotlighting (`lit` are shown, `shaded` are shown but greyed out, and edges from `shaded` to `:hidden` nodes are also shown greyed out)
+
+Seafoam ships with an annotator for generic GraalVM graphs. If you work with a
+different compiler you'll probably want to write your own annotators - subclass
+`Seafoam::Annotator` and implement `#annotate(graph)`. You can add custom
+annotators by requiring them in your `.seafoam/config`. All subclasses of
+`Annotator` will be found, so you just need to define the subclass.
+
+A fallback annotator, run after all others, just labels the node with the
+`'label'` property if there is one.
+
+Options for annotations can be set on the command line with `--option key
+value`. Some options are built into Seafoam commands, like `--show-frame-state`,
+but they're doing the same thing as `--option hide_frame_state false`.

data/docs/bgv.md

@@ -0,0 +1,284 @@
+# BGV File Format
+
+The BGV (*binary graph*, sometimes also called *BIGV*) file format is dumped by
+Graal graphs.
+
+The BGV parser was implemented from the [open-source writer code][graph-protocol]
+in the GraalVM compiler.
+
+[graph-protocol]: https://github.com/oracle/graal/blob/master/compiler/src/org.graalvm.graphio/src/org/graalvm/graphio/GraphProtocol.java
+
+## Format
+
+Seafoam supports BGV versions:
+
+* 7.0 (GraalVM 20.1.0 and up)
+* 6.1 (GraalVM 1.0.0-rc16 and up)
+
+The BGV file format is network-endian.
+
+```c
+BGV {
+  char[4] = 'BIGV'
+  sint8 major
+  sint8 minor
+  GroupOrGraph*
+}
+
+GroupOrGraph {
+  BeginGroup GroupOrGraph* CloseGroup | Graph
+}
+
+BeginGroup {
+  sint8 token = BEGIN_GROUP
+  PoolObject name
+  PoolObject method
+  sint32 bci
+  Props props
+}
+
+Graph {
+  sint8 token = BEGIN_GRAPH
+  String format
+  Args args
+  GraphBody body
+}
+
+GraphBody {
+  Props props
+  sint32 nodes_count
+  Node[nodes_count] nodes
+  Blocks blocks
+}
+
+Node {
+  sint32 id
+  PoolObject node_class
+  bool has_predecessor
+  Pops props
+  Edge[node_class.inputs.size] edges_in
+  Edge[node_class.outputs.size] edges_out
+}
+
+Edge {
+  sint32[inputs_count] nodes
+}
+
+Blocks {
+  sint32 id
+  sint32 nodes_count
+  sint32[nodes_count] nodes
+  sint32 followers_count
+  sint32[followers_count] followers
+}
+
+CloseGroup {
+  sint8 token = CLOSE_GROUP
+}
+
+Props {
+  sint16 props_count
+  Prop[props_count] props
+}
+
+Prop {
+  PoolObject key
+  PropObject value
+}
+
+PropObject {
+  union {
+    struct {
+      sint8 PROPERTY_POOL
+      PoolObject object
+    }
+    struct {
+      sint8 PROPERTY_INT
+      sint32 value
+    }
+    struct {
+      sint8 PROPERTY_LONG
+      sint64 value
+    }
+    struct {
+      sint8 PROPERTY_DOUBLE
+      float64 value
+    }
+    struct {
+      sint8 PROPERTY_FLOAT
+      float32 value
+    }
+    struct {
+      sint8 PROPERTY_TRUE
+    }
+    struct {
+      sint8 PROPERTY_FALSE
+    }
+    struct {
+      sint8 PROPERTY_ARRAY
+      union {
+        struct {
+          sint8 PROPERTY_POOL
+          sint32 times
+          PoolObject[times] values
+        }
+      }
+    }
+    struct {
+      sint8 PROPERTY_SUBGRAPH
+      GraphBody graph
+    }
+  }
+}
+
+PoolObject {
+  union {
+    POOL_NULL
+    struct {
+      sint8 token = POOL_NEW
+      uint16 id
+      union {
+        struct {
+          sint8 type = POOL_STRING
+          String string
+        }
+        struct {
+          sint8 type = POOL_ENUM
+          PoolObject enum_class
+          sint32 enum_ordinal
+        }
+        struct {
+          sint8 type = POOL_CLASS
+          String type_name
+          union {
+            struct {
+              sint8 type = ENUM_KLASS
+              sint32 values_count
+              PoolObject values[values_count]
+            }
+            struct {
+              sint8 type = KLASS
+            }
+          }
+        }
+        struct {
+          sint8 type = POOL_METHOD
+          PoolObject declaring_class
+          PoolObject method_name
+          PoolObject signature
+          sint32 modifiers
+          sint32 bytes_length
+          uint8[bytes_length] bytes
+        }
+        struct {
+          sint8 type = POOL_NODE_CLASS
+          PoolObject node_class
+          String name_template
+          sint16 input_count
+          InputEdgeInfo inputs[input_count]
+          sint16 output_count
+          OutputEdgeInfo outputs[output_count]
+        }
+        struct {
+          sint8 type = POOL_FIELD
+          PoolObject field_class
+          PoolObject name
+          PoolObject type_name
+          sint32 modifiers
+        }
+        struct {
+          sint8 type = POOL_NODE_SIGNATURE
+          sint16 args_count
+          PoolObject args[args_count]
+        }
+        struct {
+          sint8 type = POOL_NODE_SOURCE_POSITION
+          PoolObject method
+          sint32 bci
+          SourcePosition source_positions[...until SourcePosition.uri = null]
+          PoolObject caller
+        }
+        struct {
+          sint8 type = POOL_NODE
+          sint32 node_id
+          PoolObject node_class
+        }
+      }
+    }
+    struct {
+      sint8 token = POOL_STRING | POOL_ENUM | POOL_CLASS | POOL_METHOD | POOL_NODE_CLASS | POOL_FIELD | POOL_SIGNATURE | POOL_NODE_SOURCE_POSITION | POOL_NODE
+      uint16 pool_id
+    }
+  }
+}
+
+InputEdgeInfo {
+  sint8 indirect
+  PoolObject name
+  PoolObject type
+}
+
+OutputEdgeInfo {
+  sint8 indirect
+  PoolObject name
+}
+
+SourcePosition {
+  PoolObject uri
+  String location
+  sint32 line
+  sint32 start
+  sint32 end
+}
+
+String {
+  sint32 length
+  char[length] chars
+}
+
+BEGIN_GROUP = 0x00
+BEGIN_GRAPH = 0x01
+CLOSE_GROUP = 0x02
+BEGIN_DOCUMENT = 0x03
+
+POOL_NEW = 0x00
+POOL_STRING = 0x01
+POOL_ENUM = 0x02
+POOL_CLASS = 0x03
+POOL_METHOD = 0x04
+POOL_NULL = 0x05
+POOL_NODE_CLASS = 0x06
+POOL_FIELD = 0x07
+POOL_SIGNATURE = 0x08
+POOL_NODE_SOURCE_POSITION = 0x09
+POOL_NODE = 0x0a
+
+PROPERTY_POOL = 0x00
+PROPERTY_INT = 0x01
+PROPERTY_LONG = 0x02
+PROPERTY_DOUBLE = 0x03
+PROPERTY_FLOAT = 0x04
+PROPERTY_TRUE = 0x05
+PROPERTY_FALSE = 0x06
+PROPERTY_ARRAY = 0x07
+PROPERTY_SUBGRAPH = 0x08
+
+KLASS = 0x00
+ENUM_KLASS = 0x01
+```
+
+## Seeking
+
+The BGV format is not particularly amenable to seeking. You must read each prior
+graph in order to read any subsequent graph, the length of nodes and edges
+depends on values within them, and there is an object pool that is incrementally
+built.
+
+In order to 'seek' BGV files we have two code paths for reading the file, one
+with loads the data and one which loads as little as possible to know just how
+much further to advance in the file.
+
+## Other information
+
+`seafoam file.bgv debug` checks that a file can be parsed and prints information
+as it does so.