costan-tem_ruby 0.10.2

data/lib/tem/builders/assembler.rb

@@ -0,0 +1,314 @@
+# :nodoc: namespace
+module Tem::Builders  
+
+# Builder class for the code assembler builder.
+class Assembler
+  # Creates a builder targeting a module / class.
+  #
+  # The given parameter should be a class or module.
+  def self.define_assembler(class_or_module)  # :yields: abi
+    yield new(class_or_module)
+  end
+  
+  # Defines the ISA targeted by the assembler.
+  #
+  # This method should be called early in the assembler definition. It creates
+  # the proxy and builder classes for the assembling process. 
+  def target_isa(isa_module)    
+    @isa = isa_module
+    target.const_set :Isa, @isa
+    @abi = @isa.const_get :Abi
+    target.const_set :Abi, @abi
+    
+    define_proxy_class
+    define_builder_class
+    augment_target
+  end
+  
+  # Defines the methods for implementing a stack directive.
+  #
+  # The following options are supported:
+  #   label:: the label serving as the stack marker (required)
+  #   slot_type:: the ABI type representing a stack slot
+  #
+  # The following method is defined in the proxy for a directive named 'name':
+  #   * name(slots = 0) -> places a stack marker and allocates stack slots
+  def stack_directive(name, options)
+    unless @proxy_class
+      raise "target_isa must be called before other builder methods"
+    end
+    # Capture these in the closure.
+    stack_label = options[:label]
+    slot_length = @abi.send :"#{options[:slot_type]}_length" 
+    proxy_defines = Proc.new do
+      define_method name.to_sym do |*args|
+        case args.length
+        when 0
+          slots = 0
+        when 1
+          slots = args.first
+        else
+          raise "#{name}: given #{args.length} arguments, wanted at most 1"
+        end
+        @assembler.emit_label stack_label
+        if slots > 0
+          @assembler.emit_bytes name, :emit => Array.new(slots * slot_length, 0)
+        end
+      end
+    end    
+    @proxy_class.class_eval &proxy_defines
+    (class << @proxy_class; self; end).module_eval &proxy_defines    
+  end
+  
+  # Defines the methods for implementing a labeling directive.
+  #
+  # The following method is defined in the proxy for a directive named 'name':
+  #   * name(label_name) -> creates a label named label_name at the current byte
+  def label_directive(name, options = {})
+    unless @proxy_class
+      raise "target_isa must be called before other builder methods"
+    end
+    proxy_defines = Proc.new do
+      define_method name.to_sym do |label_name|
+        @assembler.emit_label label_name.to_sym
+      end
+    end    
+    @proxy_class.class_eval &proxy_defines
+    (class << @proxy_class; self; end).module_eval &proxy_defines    
+  end
+  
+  # Defines the methods for implementing a special label directive.
+  #
+  # The following method is defined in the proxy for a directive named 'name':
+  #   * name -> creates a label named label_name at the current byte
+  def special_label_directive(name, label_name)
+    unless @proxy_class
+      raise "target_isa must be called before other builder methods"
+    end
+    proxy_defines = Proc.new do
+      define_method name.to_sym do
+        @assembler.emit_label label_name.to_sym
+      end
+    end    
+    @proxy_class.class_eval &proxy_defines
+    (class << @proxy_class; self; end).module_eval &proxy_defines
+  end
+
+  # Defines the methods for implementing a zero-inserting directive.
+  #
+  # The following method is defined in the proxy for a directive named 'name':
+  #   * name(abi_type, count = 1) -> creates count zeros of abi_type
+  def zeros_directive(name, options = {})
+    unless @proxy_class
+      raise "target_isa must be called before other builder methods"
+    end
+    # Capture this in the closure.
+    abi = @abi
+    proxy_defines = Proc.new do
+      define_method name.to_sym do |*args|
+        if args.length == 1 || args.length == 2
+          type_name, count = args[0], args[1] || 1
+        else
+          raise "#{name}: given #{args.length} arguments, wanted 1 or 2"
+        end
+        bytes = count * abi.send(:"#{type_name}_length")
+        @assembler.emit_bytes name, :emit => Array.new(bytes, 0)
+      end
+    end    
+    @proxy_class.class_eval &proxy_defines
+    (class << @proxy_class; self; end).module_eval &proxy_defines    
+  end
+    
+  # Defines the methods for implementing a data-emitting directive.
+  #
+  # The following method is defined in the proxy for a directive named 'name':
+  #   * name(abi_type, values = 1) -> emits the given values as abi_type
+  def data_directive(name, options = {})
+    unless @proxy_class
+      raise "target_isa must be called before other builder methods"
+    end
+    # Capture this in the closure.
+    abi = @abi
+    proxy_defines = Proc.new do
+      define_method name.to_sym do |abi_type, values|
+        values = [values] unless values.instance_of? Array
+        data = []
+        values.each { |value| data += abi.send :"to_#{abi_type}", value }
+        @assembler.emit_bytes :immed, :emit => data
+      end
+    end    
+    @proxy_class.class_eval &proxy_defines
+    (class << @proxy_class; self; end).module_eval &proxy_defines    
+  end
+  
+  # (private) Defines the builder class used during assembly.
+  #
+  # Builders maintain intermediate results during the assembly process. In a
+  # nutshell, a builder collects the bytes, labels and linker directives, and
+  # puts them together at the end of the assembly process.
+  #
+  # Builder classes are synthesized automatically if they don't already exist.
+  # To have a builder class inherit from another class, define it before calling
+  # target_isa. Builder classes are saved as the Builder constant in the
+  # assembler class.
+  #
+  # Builder classes are injected the code in Assembler::CodeBuilderBase. Look
+  # there for override hooks into the assembly process.
+  def define_builder_class
+    if @target.const_defined? :Builder
+      @builder_class = @taget.const_get :Builder
+    else
+      @builder_class = Class.new
+      @target.const_set :Builder, @builder_class
+    end
+    @builder_class.send :include, Assembler::CodeBuilderBase
+  end
+  private :define_builder_class
+  
+  # (private) Defines the proxy class used during assembly.
+  #
+  # The proxy class is yielded to the block given to the assemble call, which
+  # provides the code to be assembled. For clarity, the proxy class is
+  # synthesized so it only contains the methods that are useful for assembly.
+  #
+  # The proxy class is always automatically synthesized, and is available under
+  # the constant Proxy in the assembler class.
+  def define_proxy_class
+    @proxy_class = Class.new Assembler::ProxyBase
+    target.const_set :Proxy, @proxy_class
+    
+    @proxy_class.const_set :Abi, @abi
+    @proxy_class.const_set :Isa, @isa
+    
+    # Capture the ISA and ABI in the closure.
+    isa = @isa
+    proxy_defines = Proc.new do
+      isa.instance_methods.each do |method|
+        if method[0, 5] == 'emit_'
+          isa_method_msg = method.to_sym
+          proxy_method_name = method[5, method.length].to_sym
+          define_method proxy_method_name do |*args|
+            emit_data = isa.send isa_method_msg, *args
+            @assembler.emit_bytes proxy_method_name, emit_data
+          end
+        end
+      end
+    end
+    @proxy_class.class_eval &proxy_defines
+    (class << @proxy_class; self; end).module_eval &proxy_defines    
+  end
+  private :define_proxy_class
+    
+  # (private) Augments the target with the assemble method.
+  def augment_target
+    # Capture this data in the closure.
+    proxy_class = @proxy_class
+    builder_class = @builder_class
+    defines = Proc.new do
+      # Assembles code.
+      def assemble(&block)
+        _assemble block
+      end
+      
+      # Internal method for assembling code.
+      #
+      # We need to use a block to define this method, so we can capture the
+      # outer variables (proxy_class and builder_class) in its closure. However,
+      # blocks can't take blocks as parameters (at least not in MRI 1.8). So
+      # we use a regular method definition (assemble) which wraps the block
+      # into a Proc received by _assemble.
+      define_method :_assemble do |block|
+        code_builder = builder_class.new
+        code_builder.start_assembling
+        proxy = proxy_class.new(code_builder)
+        block.call proxy
+        code_builder.done_assembling proxy
+      end
+      private :_assemble
+    end
+    @target.class_eval &defines
+    (class << @target; self; end).module_eval &defines        
+  end
+  
+  # The module / class impacted by the builder.
+  attr_reader :target
+  
+  # Creates a builder targeting a module / class. 
+  def initialize(target)
+    @target = target
+    @isa, @abi, @proxy = nil, nil, nil    
+  end
+  private_class_method :new
+end  # class Assembler
+
+
+# Base class for the assemblers' proxy objects.
+#
+# The proxy object is the object that is yielded out of an assembler's
+# assemble class method. 
+class Assembler::ProxyBase
+  def initialize(assembler)
+    @assembler = assembler
+  end
+end
+
+# Module injected into the assembler's code builder class.
+module Assembler::CodeBuilderBase
+  # Called by assemble before its associated block receives control.
+  #
+  # This method is responsible for setting up the state needed by the emit_
+  # methods. 
+  def start_assembling
+    @bytes = []
+    @link_directives = []
+    @line_info = []
+    @labels = {}
+  end
+  
+  # Emits code or data bytes, with associated link directives.
+  def emit_bytes(emit_atom_name, emit_data)
+    (emit_data[:link_directives] || []).each do |directive|
+      directive[:offset] += @bytes.length
+      @link_directives << directive
+    end
+    
+    emit_data[:emit] ||= []
+    if emit_data[:emit].length > 0
+      @line_info << [@bytes.length, emit_atom_name, Kernel.caller(2)]  
+    end    
+    @bytes += emit_data[:emit] || []    
+  end
+  
+  # Emits labels, which are symbolic names for addresses.
+  def emit_label(label_name)
+    raise "label #{label_name} already defined" if @labels[label_name]
+    @labels[label_name] = @bytes.length
+  end
+  
+  # Called by assemble after its associated block returns.
+  #
+  # This method is responsible for the final assembly steps (i.e. linking) and
+  # returning a processed result. The method's result is returned by assemble. 
+  def done_assembling(proxy)
+    # Process link directives.
+    abi = proxy.class.const_get :Abi
+    @link_directives.each do |directive|
+      if label = directive[:label]
+        raise "Label #{label} undefined" unless address = @labels[label]
+      else
+        address = directive[:address]
+      end
+      if directive[:relative]
+        address -= directive[:offset] + directive[:relative]
+      end
+      address_bytes = abi.send :"signed_to_#{directive[:type]}", address
+      @bytes[directive[:offset], address_bytes.length] = *address_bytes
+    end
+    
+    # Wrap all the built data into a nice package and return it.
+    { :bytes => @bytes, :link_directives => @link_direcives, :labels => @labels,
+      :line_info => @line_info }
+  end
+end
+
+end  # namespace Tem::Builders

data/lib/tem/builders/crypto.rb

@@ -0,0 +1,124 @@
+require 'openssl'
+
+
+# :nodoc: namespace
+module Tem::Builders  
+
+# Builder class and namespace for the cryptography builder.
+class Crypto < Abi
+  # Creates a builder targeting a module / class.
+  #
+  # The given parameter should be a class or module
+  def self.define_crypto(class_or_module)  # :yields: crypto
+    yield new(class_or_module)
+  end
+  
+  # Defines the methods for handling an asymmetric (public/private) key.
+  # 
+  # ssl_class should be a class in OpenSSL::PKey. privkey_abi_type and
+  # pubkey_abi_type should be ABI types similar to those produced by
+  # packed_variable_length_numbers.
+  #
+  # The following methods are defined for a type named 'name':
+  #   * read_private_name(array, offset) -> key
+  #   * to_private_name(key) -> array
+  #   * private_name_class -> Class
+  #   * read_public_name(array, offset) -> key
+  #   * to_public_name(key) -> array
+  #   * public_name_class -> Class
+  def asymmetric_key(name, ssl_class, privkey_abi_type, pubkey_abi_type,
+                     hooks = {})
+    object_wrapper "private_#{name}", Tem::Keys::Asymmetric,
+                   [privkey_abi_type, nil],
+                   :read => hooks[:read_private] || hooks[:read] ||
+                            lambda { |k| Tem::Keys::Asymmetric.new k },
+                   :to => hooks[:to_private] || hooks[:to] ||
+                          lambda { |k| k.ssl_key },
+                   :new => hooks[:new_private] || hooks[:new] ||
+                           lambda { |k| ssl_class.new }
+    object_wrapper "public_#{name}", Tem::Keys::Asymmetric,
+                   [pubkey_abi_type, nil],
+                   :read => hooks[:read_public] || hooks[:read] ||
+                            lambda { |k| Tem::Keys::Asymmetric.new k },                   
+                   :to => hooks[:to_public] || hooks[:to] ||
+                          lambda { |k| k.ssl_key },
+                   :new => hooks[:new_private] || hooks[:new] ||
+                           lambda { |k| ssl_class.new }
+  end
+  
+  
+  # Defines the methods for a symmetric key.
+  #
+  # cipher_class should be a class in OpenSSL::Cipher. key_abi_type should be
+  # an ABI type similar to that produced by fixed_string.
+  #
+  # The following methods are defined for a type named 'name':
+  #   * read_name(array, offset) -> object
+  #   * to_name(object) -> array
+  #   * name_class -> Class
+  def symmetric_key(name, cipher_class, cipher_name, key_abi_type, hooks = {})
+    object_wrapper name, Tem::Keys::Symmetric, [key_abi_type, :key],
+        :read => lambda { |k| Tem::Keys::Symmetric.new k },
+        :to => lambda { |k| k.ssl_key },
+        :new => lambda { |klass|
+      k = cipher_class cipher_name
+      
+      unless k.respond_to? :key
+        # Some ciphers don't give back the key that they receive.
+        # We need to synthesize that.
+        class << k
+          def key=(new_key)
+            super
+            @_key = new_key
+          end
+          def key
+            @_key
+          end
+        end
+      end
+    }
+  end
+  
+  # Defines the methods for a cryptographic hash function.
+  #
+  # digest_class should be an object similar to the classes in the Digest
+  # name-space. Specifically, it should implement the digest method.
+  #
+  # The following methods are defined for a type named 'name':
+  #   * name(array | String) -> array
+  #   * name_length -> number
+  #   * name_digest_class -> Class
+  def crypto_hash(name, digest_class)
+    digest_length = digest_class.digest('').length
+
+    defines = Proc.new do 
+      define_method :"#{name}" do |data|
+        data = data.pack 'C*' unless data.kind_of? String
+        digest_class.digest(data).unpack 'C*'
+      end
+      define_method(:"#{name}_digest_class") { digest_class }
+      define_method(:"#{name}_length") { digest_length }
+    end
+    
+    @target.class_eval &defines
+    (class << @target; self; end).module_eval &defines    
+  end
+end  # class Crypto
+
+
+# Implementation code for the Crypto methods.
+module Crypto::Impl
+  def self.key_from_array(array, offset, ssl_class, abi_type)
+    key = ssl_class.new
+    numbers = self.send :"read_#{abi_type}", array, offset
+    numbers.each { |k, v| key.send :"#{k}=", v }
+  end
+  
+  def self.key_to_array(key, abi_type)
+    components = self.send :"#{abi_type}_components"
+    numbers = Hash[*(components.map { |c| [c, key.send(c.to_sym) ]}.flatten)]
+    self.send :"to_#{abi_type}", numbers
+  end
+end
+
+end  # namespace Tem::Builders

data/lib/tem/builders/isa.rb

@@ -0,0 +1,120 @@
+require 'openssl'
+
+
+# :nodoc: namespace
+module Tem::Builders  
+
+# Builder class for the ISA (Instruction Set Architecture) builder.
+class Isa
+  # Creates a builder targeting a module / class.
+  #
+  # class_or_module will receive the ISA method definitions. abi should be a
+  # class or module containing the ABI definitions that the ISA definitions
+  # refer to.
+  #
+  # The following options are supported:
+  #   opcode_type:: the ABI type encoding the instructions' opcodes (required)
+  def self.define_isa(class_or_module, abi, options)  # :yields: isa
+    yield new(class_or_module, abi, options[:opcode_type])
+  end
+  
+  # Defines the methods for handling an instruction in the IA.
+  # 
+  # The instruction's arguments are provided as an array of hashes. Each hash
+  # describes one argument, and the ordering in the array reflects the encoding
+  # order. The following hash keys are supported: 
+  #   name:: if defined, the argument can be provided as a named argument;
+  #          named arguments must follow positional arguments
+  #   type:: the ABI type encoding the argument (required)
+  #   reladdr:: if defined, the encoded argument value is relative to the
+  #             address of the instruction containing the argument;
+  #
+  # The result of encoding an instruction is a Hash with the following keys:
+  #   emit:: the bytes to be emitted into the code stream 
+  #   link_directives:: an array of directives for the code linker
+  #
+  # Each linker directive refers to an address cell (location in the code
+  # representing an address that the linker must adjust. The following keys can
+  # be present:
+  #   type:: the ABI type for the address cell (required)
+  #   offset:: the address cell's offset in the emitted bytes (required)
+  #   address:: the absolute address to point to (mutually exclusive with label)
+  #   label:: the name of a label that the address must point to
+  #   relative:: if false, the address cell holds an absolute address;
+  #              otherwise, the cell's value is computed as follows:
+  #              target address - cell address + value of relative;
+  #              (optional, default value is false)
+  # The following methods are defined for a type named 'name':
+  #   * encode_name(*arguments) -> Hash
+  def instruction(opcode, name, *iargs)
+    encoded_opcode = @abi.send :"to_#{@opcode_type}", opcode
+    abi = @abi  # Capture the ABI in the method closures.
+    named_indexes = {}
+    iargs.map { |iarg| iarg[:name] }.
+          each_with_index { |argname, i| named_indexes[argname] = i if argname }
+    arg_encode_msgs = iargs.map { |iarg| :"to_#{iarg[:type]}" }
+    defines = Proc.new do 
+      define_method :"emit_#{name}" do |*args|
+        # Flatten arguments by resolving named parameters to indexes.
+        arg_index = 0
+        fargs = []
+        args.each_with_index do |arg, i|
+          fargs[i] = arg and next unless arg.kind_of? Hash
+          
+          if i != args.length - 1
+            raise "Named arguments must follow inline arguments! (arg #{i})"
+          end
+          arg.each do |k, v|
+            raise "#{name} has no #{k} argument" unless i = named_indexes[k]
+            raise "Argument #{k} was already assigned a value" if fargs[i]
+            fargs[i] = v
+          end
+        end
+          
+        arg_count = fargs.inject(0) { |acc, v| v.nil? ? acc : acc + 1 }
+        if arg_count != iargs.length
+          raise "#{name} requires #{fargs.length} args, given #{arg_count}"
+        end
+        
+        # Encode parameters.
+        # @lines[@body.length] = Kernel.caller(0)
+        
+        emit = encoded_opcode
+        link_directives = []
+        fargs.each_with_index do |arg, i|
+          if (arg.kind_of? Numeric) && !arg[:reladdr]
+            emit += abi.send arg_encode_msgs[i], arg
+          else
+            link_directive = { :type => iargs[i][:type], :offset => emit.length,
+                               :relative => iargs[i][:reladdr] || false }
+            if arg.kind_of? Numeric
+              link_directive[:address] = arg.to_i
+            else
+              link_directive[:label] = arg.to_sym
+            end
+            link_directives << link_directive
+            emit += abi.send arg_encode_msgs[i], 0
+          end
+        end
+        { :emit => emit, :link_directives => link_directives }
+      end
+    end
+    
+    @target.class_eval &defines
+    (class << @target; self; end).module_eval &defines
+  end  
+  
+  # The module / class impacted by the builder.
+  attr_reader :target
+  
+  # Creates a builder targeting a module / class. 
+  def initialize(target, abi, opcode_type)
+    @target = target
+    @target.const_set :Abi, abi
+    @abi = abi
+    @opcode_type = opcode_type
+  end
+  private_class_method :new  
+end  # class Isa
+
+end  # namespace Tem::Builders