seafoam 0.2 → 0.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 841e61f7601b4121b7367e9974b9920f8b8513fd6ca7a827c1be0e340bc2b3cf
-  data.tar.gz: 559e28e6b6a49964f31ac73bc1b1ed8c72fefae9d81381bb3e433bc39d57d0d7
+  metadata.gz: a17a259b362af5eef7c3c874e6d796f647c6017d413cba708ac0a27e18043681
+  data.tar.gz: 39eba465ba4ed92b3085a276d541072ccff48d62fdd00a317961c7401bcb0ee0
 SHA512:
-  metadata.gz: 75c306c0d6b9b8dffae51f62538a6b5e529150b59e5b6ea6ccbcf1b27ca9505fc8b7548086f2826d4f9bb8589648e2281e750a2caabd7b91f7da164065756883
-  data.tar.gz: c0c307acef6945d1841cc23d2cf5c00bbc52ed70cd74aaa95fc9365f83e796379b86009a16eef522b849e6a279b147e4d8350291b5fcdbebfa81d2ef4178bed5
+  metadata.gz: e55cdfa1eea817f24bbaa22ef80916923441393529351df21c258987354cafe98d07ed4bff2fd3e6fc5ab5656ea7f85b938d7a906ee511cd9f06fa19c335431f
+  data.tar.gz: '070468e7e9c1fd55b6429c07d8c226e1c0c0e4225a0f9a90bd577e7b57bb8320bcd0a59e1da223632986245f6eb5482a1320b11e6b786f41f456187766664b9b'

data/.github/workflows/workflows.yml

@@ -0,0 +1,39 @@
+name: Workflows
+on: [push]
+jobs:
+  rubocop:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+    - uses: ruby/setup-ruby@v1
+    - run: bundle install
+    - run: bundle exec rubocop
+  specs:
+    strategy:
+      matrix:
+        os: [ubuntu, macos]
+        ruby: [2.5, 2.6, 2.7]
+    runs-on: ${{ matrix.os }}-latest
+    steps:
+    - uses: actions/checkout@v2
+    - uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby }}
+        bundler-cache: true
+    - run: bundle install
+    - run: if [[ $(uname) == "Darwin" ]]; then brew install graphviz capstone; else sudo apt-get install graphviz libcapstone3; fi
+    - run: bundle exec rspec
+  specs-no-dependencies:
+    strategy:
+      matrix:
+        os: [ubuntu, macos]
+        ruby: [2.5, 2.6, 2.7]
+    runs-on: ${{ matrix.os }}-latest
+    steps:
+    - uses: actions/checkout@v2
+    - uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby }}
+        bundler-cache: true
+    - run: bundle install
+    - run: NO_DEPENDENCIES_INSTALLED=true bundle exec rspec

data/.rubocop.yml

@@ -1,7 +1,7 @@
 AllCops:
   TargetRubyVersion: 2.5
   Exclude:
-    - examples/*
+    - examples/**/*.rb
 
 Style/FrozenStringLiteralComment:
   Enabled: false
@@ -32,3 +32,6 @@ Security/Eval:
 
 Naming/FileName:
   Enabled: false
+
+Metrics/LineLength:
+  Max: 300

data/README.md

@@ -10,13 +10,18 @@ GraalVM compiler graphs. Seafoam aims to solve several problems with IGV. Unlike
 IGV, Seafoam:
 
 * is open source and can be used according to the MIT license
+* supports gzip-compressed BGV files
 * is able to some extent seek BGV files to load specific graphs without loading the rest of the file
 * has a command-line interface
 * can be used as a library
-* has easy PDF, SVG and PNG output
+* has easy PDF, SVG, PNG and JSON output
 * is designed for accessibility
 * looks prettier, in our opinion
 
+Additionally, Seafoam adds:
+
+* support for disassembling CFG files
+
 Admittedly, Seafoam does not yet have:
 
 * an interactive user interface
@@ -37,34 +42,43 @@ Admittedly, Seafoam does not yet have:
 ### macOS
 
 ```
-$ brew install graphviz
-$ gem install seafoam
-$ seafoam --version
+% brew install graphviz
+% gem install seafoam
+% seafoam --version
 seafoam 0.1
 ```
 
 ### Ubuntu
 
 ```
-$ sudo apt-get install ruby graphviz
-$ gem install seafoam
-$ seafoam --version
+% sudo apt-get install ruby graphviz
+% gem install seafoam
+% seafoam --version
 seafoam 0.1
 ```
 
-#### RedHat
+### RedHat
 
 ```
-$ sudo yum install ruby graphviz
-$ gem install seafoam
-$ seafoam --version
+% sudo yum install ruby graphviz
+% gem install seafoam
+% seafoam --version
 seafoam 0.1
 ```
 
+### Capstone
+
+To use the `cfg2asm` disassembler, you'll then need to install Capstone.
+
+```
+% brew install capstone               # macOS
+% sudo apt-get install libcapstone3   # Ubuntu
+```
+
 ## Quick-start demo
 
 ```
-$ seafoam examples/fib-java.bgv:0 render
+% seafoam examples/fib-java.bgv:0 render
 ```
 
 ## Getting compiler graphs
@@ -78,14 +92,20 @@ This is just a quick summary - see more information on
 ### GraalVM for Java
 
 ```
-$ javac Fib.java
-$ java -XX:CompileOnly=::fib -Dgraal.Dump=:2 Fib 14
+% javac Fib.java
+% java -XX:CompileOnly=::fib -Dgraal.Dump=:2 Fib 14
+```
+
+### GraalVM Native Image
+
+```
+% native-image -H:Dump=:2 -H:MethodFilter=fib Fib
 ```
 
 ### TruffleRuby and other Truffle languages
 
 ```
-$ ruby --experimental-options --engine.CompileOnly=fib --engine.Inlining=false --engine.OSR=false --vm.Dgraal.Dump=Truffle:2 fib.rb 14
+% ruby --experimental-options --engine.CompileOnly=fib --engine.Inlining=false --engine.OSR=false --vm.Dgraal.Dump=Truffle:2 fib.rb 14
 ```
 
 You will usually want to look at the *After TruffleTier* graph.
@@ -105,14 +125,14 @@ Note that a *graph ID* is an ID found in BGV files, but is not unique. A
 #### Print information about a file
 
 ```
-$ seafoam examples/fib-java.bgv info
+% seafoam examples/fib-java.bgv info
 BGV 6.1
 ```
 
 #### List graphs in a file
 
 ```
-$ seafoam examples/fib-java.bgv list
+% seafoam examples/fib-java.bgv list
 examples/fib-java.bgv:0  2:Fib.fib(int)/After phase org.graalvm.compiler.java.GraphBuilderPhase
 examples/fib-java.bgv:1  2:Fib.fib(int)/After phase org.graalvm.compiler.phases.PhaseSuite
 examples/fib-java.bgv:2  2:Fib.fib(int)/After phase org.graalvm.compiler.phases.common.DeadCodeEliminationPhase
@@ -125,7 +145,7 @@ examples/fib-java.bgv:5  2:Fib.fib(int)/After phase org.graalvm.compiler.phases.
 #### Search for strings in a graph, or node or edge within a graph
 
 ```
-$ seafoam examples/fib-java.bgv:0 search Start
+% seafoam examples/fib-java.bgv:0 search Start
 examples/fib-java.bgv:0:0  ...node_class":"org.graalvm.compiler.nodes.StartNode","name_template":"Start","inputs":[...
 examples/fib-java.bgv:0:0  ...piler.nodes.StartNode","name_template":"Start","inputs":[{"direct":true,"name":"state...
 ```
@@ -133,9 +153,9 @@ examples/fib-java.bgv:0:0  ...piler.nodes.StartNode","name_template":"Start","in
 #### Print edges of a graph, or node or edge within a graph
 
 ```
-$ seafoam examples/fib-java.bgv:0 edges
+% seafoam examples/fib-java.bgv:0 edges
 22 nodes, 30 edges
-$ seafoam examples/fib-java.bgv:0:13 edges
+% seafoam examples/fib-java.bgv:0:13 edges
 Input:
   13 (Call Fib.fib) <-() 6 (Begin)
   13 (Call Fib.fib) <-() 14 (@{:declaring_class=>"Fib", :method_name=>"fib", :signature=>{:args=>["I"], :ret=>"I"}, :modifiers=>9}:13)
@@ -145,14 +165,14 @@ Output:
   13 (Call Fib.fib) ->(values) 14 (@{:declaring_class=>"Fib", :method_name=>"fib", :signature=>{:args=>["I"], :ret=>"I"}, :modifiers=>9}:13)
   13 (Call Fib.fib) ->(values) 19 (@{:declaring_class=>"Fib", :method_name=>"fib", :signature=>{:args=>["I"], :ret=>"I"}, :modifiers=>9}:19)
   13 (Call Fib.fib) ->(x) 20 (+)
-$ seafoam examples/fib-java.bgv:0:13-20 edges
+% seafoam examples/fib-java.bgv:0:13-20 edges
 13 (Call Fib.fib) ->(x) 20 (+)
 ```
 
 #### Print properties of a file, graph, or node or edge within a graph
 
 ```
-$ seafoam examples/fib-java.bgv:0 props
+% seafoam examples/fib-java.bgv:0 props
 {
   "group": [
     {
@@ -160,7 +180,7 @@ $ seafoam examples/fib-java.bgv:0 props
       "short_name": "2:Fib.fib(int)",
       "method": null,
 ...
-$ seafoam examples/fib-java.bgv:0:13 props
+% seafoam examples/fib-java.bgv:0:13 props
 {
   "nodeSourcePosition": {
     "method": {
@@ -168,7 +188,7 @@ $ seafoam examples/fib-java.bgv:0:13 props
       "method_name": "fib",
       "signature": {
 ...
-$ seafoam examples/fib-java.bgv:0:13-20 props
+% seafoam examples/fib-java.bgv:0:13-20 props
 {
   "direct": true,
   "name": "x",
@@ -176,19 +196,39 @@ $ seafoam examples/fib-java.bgv:0:13-20 props
 }
 ```
 
+#### Print node source information
+
+```
+% seafoam examples/fib-ruby.bgv:8:2443 source
+java.lang.Math#addExact
+org.truffleruby.core.numeric.IntegerNodes$AddNode#add
+org.truffleruby.core.numeric.IntegerNodesFactory$AddNodeFactory$AddNodeGen#executeAdd
+org.truffleruby.core.inlined.InlinedAddNode#intAdd
+org.truffleruby.core.inlined.InlinedAddNodeGen#execute
+org.truffleruby.language.control.IfElseNode#execute
+org.truffleruby.language.control.SequenceNode#execute
+org.truffleruby.language.arguments.CheckArityNode#execute
+org.truffleruby.language.control.SequenceNode#execute
+org.truffleruby.language.methods.CatchForMethodNode#execute
+org.truffleruby.language.methods.ExceptionTranslatingNode#execute
+org.truffleruby.language.RubyRootNode#execute
+org.graalvm.compiler.truffle.runtime.OptimizedCallTarget#executeRootNode
+org.graalvm.compiler.truffle.runtime.OptimizedCallTarget#profiledPERoot
+```
+
 #### Render a graph
 
 Render a graph as a PDF image and have it opened automatically.
 
 ```
-$ seafoam examples/fib-java.bgv:0 render
+% seafoam examples/fib-java.bgv:0 render
 ```
 
 Render a graph showing just a few nodes and those surrounding them, similar to
 the IGV feature of gradually revealing nodes.
 
 ```
-$ seafoam examples/fib-java.bgv:0 render --spotlight 13,20
+% seafoam examples/fib-java.bgv:0 render --spotlight 13,20
 ```
 
 <p>
@@ -206,7 +246,7 @@ $ seafoam examples/fib-java.bgv:0 render --spotlight 13,20
 Convert a BGV file to the Isabelle graph format.
 
 ```
-$ bgv2isabelle examples/fib-java.bgv
+% bgv2isabelle examples/fib-java.bgv
 graph0 = # 2:Fib.fib(int)/After phase org.graalvm.compiler.java.GraphBuilderPhase
  (add_node 0 StartNode [2] [8]
  (add_node 1 (ParameterNode 0) [] [2, 5, 9, 11, 14, 16]
@@ -220,6 +260,46 @@ graph0 = # 2:Fib.fib(int)/After phase org.graalvm.compiler.java.GraphBuilderPhas
 ...
 ```
 
+Convert a BGV file to JSON.
+
+```
+% bgv2json examples/fib-java.bgv
+graph0 = # 2:Fib.fib(int)/After phase org.graalvm.compiler.java.GraphBuilderPhase
+ (add_node 0 StartNode [2] [8]
+ (add_node 1 (ParameterNode 0) [] [2, 5, 9, 11, 14, 16]
+ (add_node 2 FrameState [1] [0]
+ (add_node 3 (ConstantNode 1) [] []
+ (add_node 4 (ConstantNode 2) [] [5]
+ (add_node 5 IntegerLessThanNode [1, 4] [8]
+ (add_node 6 BeginNode [8] [13]
+ (add_node 7 BeginNode [8] [9]
+ (add_node 8 IfNode [0, 5] [7, 6]
+...
+```
+
+#### Disassembling
+
+```
+% cfg2asm examples/java/exampleArithOperator.cfg
+[examples/java/exampleArithOperator.cfg]
+				;Comment 0:	3
+				;Comment 0:	1
+	0x112e2f660:	nop	dword ptr [rax + rax]
+				;Comment 5:	block B0 null
+				;Comment 5:	0 [rsi|DWORD, rdx|DWORD, rbp|QWORD] = LABEL numbPhis: 0 align: false label: ?
+				;Comment 5:	4 [] = HOTSPOTLOCKSTACK frameMapBuilder: org.graalvm.compiler.lir.amd64.AMD64FrameMapBuilder@143082de0 slotKind: QWORD
+				;Comment 5:	10 rsi|DWORD = ADD (x: rsi|DWORD, y: rdx|DWORD) size: DWORD
+	0x112e2f665:	add	esi, edx
+				;Comment 7:	12 rax|DWORD = MOVE rsi|DWORD moveKind: DWORD
+	0x112e2f667:	mov	eax, esi
+				;Comment 9:	14 RETURN (savedRbp: rbp|QWORD, value: rax|DWORD) isStub: false requiresReservedStackAccessCheck: false thread: r15 scratchForSafepointOnReturn: rcx config: org.graalvm.compiler.hotspot.GraalHotSpotVMConfig@137f187d8
+				;Comment 9:	12
+	0x112e2f669:	test	dword ptr [rip - 0x46c4669], eax
+	0x112e2f66f:	vzeroupper	
+	0x112e2f672:	ret	
+...
+```
+
 ## Options for GraalVM graphs
 
 * `--show-frame-state` shows frame state nodes, which are hidden by default

data/bin/bgv2isabelle

@@ -2,52 +2,23 @@
 
 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))))))))))))))"
+# This is the 'bgv2isabelle' command line entry point.
 
-ARGV.each do |file|
-  parser = Seafoam::BGV::BGVParser.new(File.new(file))
-  parser.read_file_header
-  parser.skip_document_props
+begin
+  # Load configuraiton.
+  config = Seafoam::Config.new
+  config.load_config
 
-  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)
+  # Run the command line.
+  commands = Seafoam::Commands.new($stdout, config)
+  commands.bgv2isabelle(*ARGV)
+rescue StandardError => e
+  if $DEBUG
+    # Re-raise the exception so the user sees it, if debugging is
+    # enabled (ruby -d).
+    raise e
+  else
+    # Otherwise, just print the message.
+    warn "seafoam: #{e.message}"
   end
 end

data/bin/bgv2json

@@ -1,42 +1,24 @@
 #!/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})
+# This is the 'bgv2json' 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.bgv2json(*ARGV)
+rescue StandardError => e
+  if $DEBUG
+    # Re-raise the exception so the user sees it, if debugging is
+    # enabled (ruby -d).
+    raise e
+  else
+    # Otherwise, just print the message.
+    warn "seafoam: #{e.message}"
   end
 end