fisk 2.0.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0809155eef95d321b2e39b2c3a801f5ed987f74e409ba40285a30f530964c558'
-  data.tar.gz: 0b44765ae9dd4d4611c9db1af5a49bbe8659ce4dba3e6a7ac8887e17ebdb6e4a
+  metadata.gz: 42d5818c354d7ee2347266ca997e314615a23f832687a30dc05578a2e92b6310
+  data.tar.gz: '06428fa873eed75d9ee07bdedd1fa848a51dfaa826dd38ce661c6b267509e3a8'
 SHA512:
-  metadata.gz: 1835a32e1579e07b1a7cf101a85ea94dee3471cb2c5c64e66a385a59807b8c049e1218c8b8152d7aa562757d585d3d7700b435b5791fd42ddaccabf99a403973
-  data.tar.gz: 90a32029797fb6f0a101fcfc81e3352e69294ac2bd02a48f9f3e077dde900b4d3a917e413b4f65be599cdf3a0fd4f3b0a5419a043774d16292eae9821aaa6e82
+  metadata.gz: 5ccbb718f81f5856f19dfca980a3f7d39e7a96cdc8dcd43922fb7e90e89d16d87d20cb07ccc54cf09809a9c3020504ab3ea8742bad65b77edc83cf94015c5794
+  data.tar.gz: 8e9182cb31c8d29dd260e35d607a525536a5964cacc814898a2ac696ec3f8f2b9671f982a698c8b725e380eb7bff54c07f1a84c6bbc25540ab7bfcd0388ca8e6

data/README.md

@@ -1,5 +1,7 @@
 # Fisk - A Pure Ruby Assembler
 
+Tired of writing Ruby in Ruby?  Now you can write assembly in Ruby with Fisk!
+
 This is a pure Ruby x86-64 assembler (I guess).  I'm not 100% sure if it counts
 as pure Ruby because it just reads an XML file and metaprograms most of it.
 Anyway, you can use it to write assembly in Ruby, then have it assembled.
@@ -24,7 +26,60 @@ binary = fisk.asm do
 end
 ```
 
-Though, it's not very fun to assemble something unless you can execute it.  So
+Fisk uses Intel assembly syntax, so the first operand is the *destination*, and
+the second operand is the source.  So for example `mov rax, imm8(1)` means "put
+an immediate that is 8 bits wide with the value of 1 in the RAX register".
+
+## Sizes and Memory Operands
+
+In order to select the right x86 instruction to emit, Fisk needs to know the
+types of the operands.  Register types are already implied, but things like
+immediates and memory operands need to be specified.
+
+Below are a few examples.
+
+Putting a 32 bit immediate in the RAX register:
+
+```ruby
+mov rax, imm32(0xFFF)
+```
+
+Dereferencing the value in RAX and storing the value in the RAX register:
+
+```ruby
+mov rax, m64(rax)
+```
+
+Dereferencing the value 8 bytes away RAX and storing the value in the R9 register:
+
+```ruby
+mov r9, m64(rax, 8)
+```
+
+## Register Allocation
+
+Fisk supports simple register assignment.  You can make temporary registers,
+then have Fisk assign registers for you.  For example:
+
+```ruby
+fisk = Fisk.new
+
+# Make some temporary registers
+reg1 = fisk.register("temp1")
+reg2 = fisk.register("temp2")
+
+# XOR the two virtual registers
+fisk.xor reg1, reg2
+
+# Ask Fisk to assign registers from the pool of registers passed in
+fisk.assign_registers([fisk.r9, fisk.r10])
+```
+
+Currently, Fisk won't spill registers for you, it just raises an exception.
+
+## Executing Assembly
+
+Now, it's not very fun to assemble something unless you can execute it.  So
 here is an example of how to execute the above assembly.  This assembly code
 will send an interrupt and tell the debugger to stop.  So let's write the
 machine code to some executable memory, and call it from a Ruby program that we

data/bin/build-machine.rb

@@ -8,7 +8,7 @@ def parse_rex v
     when /^(\d+)$/
       v
     when /^#(\d+)$/
-      "(operands[#{$1.to_i}].value >> 3)"
+      "operands[#{$1.to_i}].rex_value"
     else
       raise NotImplementedError, v
     end
@@ -23,7 +23,7 @@ def parse_operand_value v
     when /^(\d+)$/
       v
     when /^#(\d+)$/
-      "operands[#{$1.to_i}].value"
+      "operands[#{$1.to_i}].op_value"
     else
       raise NotImplementedError, v
     end

data/fisk.gemspec

@@ -1,6 +1,10 @@
+$: << File.expand_path("lib")
+
+require "fisk/version"
+
 Gem::Specification.new do |s|
   s.name        = "fisk"
-  s.version     = "2.0.0"
+  s.version     = Fisk::VERSION
   s.summary     = "Write assembly in Ruby!"
   s.description = "Tired of writing Ruby in Ruby? Now you can write assembly in Ruby!"
   s.authors     = ["Aaron Patterson"]

data/lib/fisk.rb

@@ -1,32 +1,85 @@
 # frozen_string_literal: true
 
 require "stringio"
+require "set"
+
 require "fisk/instructions"
+require "fisk/basic_block"
+require "fisk/errors"
+require "fisk/version"
 
 class Fisk
-  class Operand < Struct.new(:value)
-    def type; value; end
+  class Operand
     def works? type; self.type == type; end
     def unknown_label?; false; end
+    def register?; false; end
+    def temp_register?; false; end
     def extended_register?; false; end
     def m64?; false; end
+
+    def rex_value
+      value >> 3
+    end
+
+    def op_value
+      value
+    end
+  end
+
+  class ValueOperand < Operand
+    attr_reader :value
+    alias :type :value
+
+    def initialize value
+      @value = value
+    end
   end
 
   module Registers
     class Register < Operand
-      attr_reader :name, :type
+      attr_reader :name, :type, :value
 
       def initialize name, type, value
         @name = name
         @type = type
-        super(value)
+        @value = value
       end
 
       def works? type
         type == self.name || type == self.type
       end
 
-      def extended_register?; value > 7; end
+      def op_value
+        value & 0x7
+      end
+
+      def extended_register?; @value > 7; end
+    end
+
+    class Temp < Operand
+      attr_reader :name, :type
+      attr_accessor :register, :start_point, :end_point
+
+      def initialize name, type
+        @name        = name
+        @type        = type
+        @start_point = nil
+        @end_point   = nil
+      end
+
+      def temp_register?; true; end
+
+      def extended_register?
+        @register.extended_register?
+      end
+
+      def rex_value
+        @register.rex_value
+      end
+
+      def value
+        @register.value
+      end
     end
 
     EAX = Register.new "eax", "r32", 0
@@ -50,6 +103,12 @@ class Fisk
       i += 8
       const_set "R#{i}", Register.new("r#{i}", "r64", i)
     end
+
+    # List of *caller* saved registers for the C calling convention
+    CALLER_SAVED = [ RDI, RSI, RDX, RCX, R8, R9, R10, R11 ]
+
+    # List of *callee* saved registers for the C calling convention
+    CALLEE_SAVED = [ RBX, RSP, RBP, R12, R13, R14, R15 ]
   end
 
 
@@ -57,11 +116,14 @@ class Fisk
     attr_reader :displacement
 
     def initialize register, displacement
-      super(register.value)
       @register     = register
       @displacement = displacement
     end
 
+    def value
+      @register.value
+    end
+
     def type
       "m64"
     end
@@ -73,62 +135,50 @@ class Fisk
     M64.new x, displacement
   end
 
-  class Imm8 < Operand
-    def type
-      "imm8"
-    end
-  end
-
-  class Imm32 < Operand
-    def type
-      "imm32"
-    end
-  end
+  # Define all immediate value methods of different sizes
+  [8, 16, 32, 64].each do |size|
+    class_eval <<~eostr, __FILE__, __LINE__ + 1
+      class Imm#{size} < ValueOperand
+        def type
+          "imm#{size}"
+        end
+      end
 
-  class Imm64 < Operand
-    def type
-      "imm64"
-    end
+      def imm#{size} val; Imm#{size}.new(val.to_i); end
+    eostr
   end
 
-  class Rel8 < Operand
+  class Rel8 < ValueOperand
     def type
       "rel8"
     end
   end
 
-  class Rel32 < Operand
+  class Rel32 < ValueOperand
     def type
       "rel32"
     end
   end
 
-  class MOffs64 < Operand
+  class MOffs64 < ValueOperand
     def type
       "moffs64"
     end
   end
 
-  class Lit < Operand
+  class Lit < ValueOperand
     def type
       value.to_s
     end
   end
 
-  attr_reader :position
-
-  def initialize
-    @instructions = []
-    @labels = {}
-    @position = 0
-  end
-
   class UnknownLabel < Struct.new(:name)
     def works? type
       type == "rel32"
     end
 
     def unknown_label?; true; end
+    def temp_register?; false; end
 
     def value
       label = assembler.label_for(name)
@@ -138,19 +188,8 @@ class Fisk
 
   class Label < Struct.new(:name)
     def label?; true; end
-  end
-
-  def label name
-    UnknownLabel.new(name)
-  end
-
-  def make_label name
-    @instructions << Label.new(name)
-  end
-
-  Registers.constants.grep(/^[A-Z0-9]*$/).each do |const|
-    val = Registers.const_get const
-    define_method(const.downcase) { val }
+    def jump?; false; end
+    def has_temp_registers?; false; end
   end
 
   class Instruction
@@ -160,6 +199,18 @@ class Fisk
       @operands = operands
     end
 
+    def jump?
+      false
+    end
+
+    def has_temp_registers?
+      @operands.any?(&:temp_register?)
+    end
+
+    def temp_registers
+      @operands.find_all(&:temp_register?)
+    end
+
     def encodings
       @form.encodings
     end
@@ -185,6 +236,16 @@ class Fisk
       @saved_pos = nil
     end
 
+    def jump?
+      true
+    end
+
+    def target
+      @operand.name
+    end
+
+    def has_temp_registers?; false; end
+
     def encode buffer, labels
       # Estimate by using a rel32 offset
       form          = find_form "rel32"
@@ -228,22 +289,147 @@ class Fisk
     end
   end
 
+  def initialize
+    @instructions = []
+    @labels = {}
+    # A set of temp registers recorded as we see them (not at allocation time)
+    @temp_registers = Set.new
+    yield self if block_given?
+  end
+
+  # Mark a temporary register as "done being used" at this point in the
+  # instructions.  Using the register after passing the register to this
+  # method results in undefined behavior.
+  def release_register reg
+    if reg.end_point
+      raise Errors::AlreadyReleasedError, "register #{reg.name} already released at #{reg.end_point}"
+    end
+
+    reg.end_point = (@instructions.length - 1)
+  end
+
+  # Releases all registers that haven't already been released
+  def release_all_registers
+    @temp_registers.each do |reg|
+      next if reg.end_point
+      release_register reg
+    end
+  end
+
+  # Return a list of basic blocks for the instructions
+  def basic_blocks
+    cfg.blocks
+  end
+
+  # Return a cfg for these instructions.  The CFG includes connected basic
+  # blocks as well as any temporary registers
+  def cfg
+    CFG.build @instructions
+  end
+
+  # Create a label to be used with jump instructions.  For example:
+  #
+  #   fisk.jmp(fisk.label(:foo))
+  #   fisk.int(lit(3))
+  #   fisk.put_label(:foo)
+  #
+  def label name
+    UnknownLabel.new(name)
+  end
+
+  # Insert a label named +name+ at the current position in the instructions.
+  def put_label name
+    @instructions << Label.new(name)
+    self
+  end
+  alias :make_label :put_label
+
+  # Allocate and return a new register.  These registers will be replaced with
+  # real registers when `assign_registers` is called.
+  def register name = "temp"
+    Registers::Temp.new name, "r64"
+  end
+
+  # Assign registers to any temporary registers.  Only registers in +list+
+  # will be used when selecting register assignments
+  def assign_registers list, local: false
+    temp_registers = @temp_registers
+
+    # This mutates the temp registers, setting their end_point based on
+    # the CFG
+    self.cfg unless local
+
+    temp_registers.each do |reg|
+      unless reg.end_point
+        raise Errors::UnreleasedRegisterError, "Register #{reg.name} hasn't been released"
+      end
+    end
+
+    temp_registers = temp_registers.sort_by(&:start_point)
+
+    active         = []
+    free_registers = list.reverse
+    register_count = list.length
+
+    temp_registers.each do |temp_reg|
+      # expire old intervals
+      active, dead = active.sort_by(&:end_point).partition do |j|
+        j.end_point >= temp_reg.start_point
+      end
+
+      # Add unused registers back to the free register list
+      dead.each { |tr| free_registers << tr.register }
+
+      if active.length == register_count
+        raise NotImplementedError, "Register spilled"
+      end
+
+      temp_reg.register = free_registers.pop
+      active << temp_reg
+    end
+  end
+
+  Registers.constants.grep(/^[A-Z0-9]*$/).each do |const|
+    val = Registers.const_get const
+    define_method(const.downcase) { val }
+  end
+
   include Fisk::Instructions::DSLMethods
 
   def moffs64 val
     MOffs64.new val
   end
 
-  def imm8 val
-    Imm8.new val
-  end
-
-  def imm32 val
-    Imm32.new val
+  # Create a signed immediate value of the right width
+  def imm val
+    if val >= -0x7F - 1 && val <= 0x7F
+      imm8 val
+    elsif val >=  -0x7FFF - 1 && val <= 0x7FFF
+      imm16 val
+    elsif val >=  -0x7FFFFFFF - 1 && val <= 0x7FFFFFFF
+      imm32 val
+    elsif val >=  -0x7FFFFFFFFFFFFFFF - 1 && val <= 0x7FFFFFFFFFFFFFFF
+      imm64 val
+    else
+      raise ArgumentError, "#{val} is larger than a 64 bit int"
+    end
   end
 
-  def imm64 val
-    Imm64.new val
+  # Create an unsigned immediate value of the right width
+  def uimm val
+    if val < 0
+      raise ArgumentError, "#{val} is negative"
+    elsif val <= 0xFF
+      imm8 val
+    elsif val <= 0xFFFF
+      imm16 val
+    elsif val <= 0xFFFFFFFF
+      imm32 val
+    elsif val <= 0xFFFFFFFFFFFFFFFF
+      imm64 val
+    else
+      raise ArgumentError, "#{val} is too large for a 64 bit int"
+    end
   end
 
   def rel8 val
@@ -255,26 +441,34 @@ class Fisk
   end
 
   def lit val
-    # to_s because we're getting the value from JSON as a string
     Lit.new val
   end
 
+  # Instance eval's a given block and writes encoded instructions to +buf+.
+  # For example:
+  #
+  #   fisk = Fisk.new
+  #   fisk.asm do
+  #     mov r9, imm64(32)
+  #   end
+  #
   def asm buf = StringIO.new(''.b), &block
-    @position = 0
     instance_eval(&block)
-    write_to_buffer buf
+    write_to buf
     buf
   end
 
+  # Encodes all instructions and returns a binary string with the encoded
+  # instructions.
   def to_binary
     io = StringIO.new ''.b
-    write_to_buffer io
+    write_to io
     io.string
   end
 
-  private
-
-  def write_to_buffer buffer
+  # Encode all instructions and write them to +buffer+.  +buffer+ should be an
+  # IO object.
+  def write_to buffer
     labels = {}
     unresolved = []
     @instructions.each do |insn|
@@ -294,6 +488,8 @@ class Fisk
       insn.encode buffer, labels
     end
     buffer.seek pos, IO::SEEK_SET
+
+    buffer
   end
 
   def gen_with_insn insns, params
@@ -307,20 +503,42 @@ class Fisk
       end
     end
 
-    raise NotImplementedError, "couldn't find instruction #{name}" if forms.length == 0
+    if forms.length == 0
+      valid_forms = insns.forms.map { |form|
+        "    #{insns.name} #{form.operands.map(&:type).join(", ")}"
+      }.join "\n"
+      msg = <<~eostr
+      Couldn't find instruction #{insns.name} #{params.map(&:type).join(", ")}
+      Valid forms:
+      #{valid_forms}
+      eostr
+      raise NotImplementedError, msg
+    end
+
+    form = forms.first
 
     insn = nil
 
-    form = forms.first
+    params.each do |param|
+      if param.unknown_label?
+        if params.length > 1
+          raise ArgumentError, "labels only work with single param jump instructions"
+        end
+        insn = UnresolvedInstruction.new(insns, form, params.first)
+      end
+
+      if param.temp_register?
+        if param.end_point
+          raise Errors::UseAfterInvalidationError, "Register #{param.name} used after release"
+        end
+        @temp_registers << param
+
+        param.start_point ||= @instructions.length
+      end
+    end
+
+    insn ||= Instruction.new(insns, form, params)
 
-    insn = if params.any?(&:unknown_label?)
-             if params.length > 1
-               raise ArgumentError, "labels only work with single param jump instructions"
-             end
-             UnresolvedInstruction.new(insns, form, params.first)
-           else
-             Instruction.new(insns, form, params)
-           end
     @instructions << insn
 
     self