rpicsim 0.1.0

data/lib/rpicsim/flaws.rb

@@ -0,0 +1,76 @@
+module RPicSim
+  module Flaws
+    # Represents a flaw in RPicSim, usually due to bugs or limitation of the
+    # MPLAB X classes we are using.  Stores the name of the flaw and knowledge
+    # about what versions of MPLAB X it affects and how.
+    class Flaw
+      # Creates a new flaw with the specified name.
+      # @param name [Symbol] The name of this flaw.
+      def initialize(name)
+        @versions = {}
+      end
+
+      # Returns the effect of this flaw on the specified version of MPLAB X.
+      # This might just be true/false to indicate if the flaw is present or it
+      # might be a more complicated thing if there is more than one effect the
+      # the flaw can have.
+      #
+      # @param version [String] A version of MPLAB X, e.g. "1.95".
+      # @return effect
+      def effect(version)
+        if @versions.has_key? version
+          @versions[version]
+        else
+          @probable_affect_for_other_versions
+        end
+      end
+      
+      # Records the effect this flaw has on a given version of MPLAB X.
+      def affects_version(version, effect)
+        @versions[version] = effect
+      end
+      
+      # Records the effect that this flaw probably has in other versions of
+      # MPLAB X that have not been tested.  This allows us to record our guesses
+      # about how the next version of MPLAB X will behave.
+      def probably_affects_other_versions(effect)
+        @probable_affect_for_other_versions = effect
+      end
+    end
+  
+    @flaw_hash = {}
+    def self.[](name)
+      @flaw_hash[name].effect Mplab.version
+    end
+  
+    def self.add(name)
+      @flaw_hash[name] = flaw = Flaw.new(name)
+      yield flaw
+    end
+  
+    add(:fr_memory_attach_useless) do |flaw|
+      flaw.affects_version "1.85", false
+      flaw.affects_version "1.90", false
+      flaw.affects_version "1.95", true
+      flaw.affects_version "2.00", true
+      flaw.probably_affects_other_versions true
+    end
+    
+    add(:firmware_cannot_write_user_id0) do |flaw|
+      flaw.affects_version "1.85", true
+      flaw.affects_version "1.90", true
+      flaw.affects_version "1.95", false
+      flaw.affects_version "2.00", false
+      flaw.probably_affects_other_versions false
+    end
+    
+    add(:adc_midrange) do |flaw|
+      flaw.affects_version "1.85", :no_middle_values
+      flaw.affects_version "1.90", :bad_modulus
+      flaw.affects_version "1.95", :bad_modulus
+      flaw.affects_version "2.00", :bad_modulus
+      flaw.probably_affects_other_versions :bad_modulus
+    end
+  
+  end
+end

data/lib/rpicsim/instruction.rb

@@ -0,0 +1,178 @@
+module RPicSim
+  # Instances of this class represent a particular instruction at a particular
+  # address in program memory.  This class takes low-level information about a
+  # disassembled instruction and produces high-level information about what that
+  # instruction is and how it behaves.
+  #
+  # Instances of this class have links to the other instructions that the instruction
+  # could lead to, so the instances form a graph.  This graph is traversed by
+  # classes like {CallStackInfo} to get useful information about the firmware.
+  class Instruction
+    include Comparable
+    
+    # The flash address of the instruction.
+    # For PIC18s this will be the byte address.
+    # For other PIC architectures, it will be the word address.
+    # @return (Integer)
+    attr_reader :address
+    
+    # The opcode as a capitalized string (e.g. "MOVLW").
+    # @return (String)
+    attr_reader :opcode
+    
+    # The operands of the instruction as a hash like { "k" => 92 }.
+    # @return (Hash)
+    attr_reader :operands
+    
+    # The number of flash address units that this instruction takes.
+    # The units of this are the same as the units of {#address}.
+    # @return (Integer)
+    attr_reader :size
+
+    # Creates a new instruction.
+    # @param instruction_store some object such as {ProgramFile} that responds to #instruction and #address_description.
+    def initialize(address, instruction_store, opcode, operands, size, address_increment, string, properties)
+      @address = address
+      @instruction_store = instruction_store
+      @opcode = opcode
+      @operands = operands
+      @size = size
+      @address_increment = address_increment
+      @string = string
+      
+      modules = {
+        conditional_skip: ConditionalSkip,
+        goto: Goto,
+        return: Return,
+        call: Call
+      }
+      
+      properties.each do |p|
+        mod = modules[p]
+        if !mod
+          raise ArgumentError, "Invalid property: #{p.inspect}."
+        end
+        extend mod
+      end
+    end
+    
+    # Compares this instruction to another using the addresses.  This means you can
+    # call +.sort+ on an array of instructions to put them in order by address.
+    def <=>(other)
+      self.address <=> other.address
+    end
+
+    # Human-readable string representation of the instruction.
+    def to_s
+      "Instruction(#{@instruction_store.address_description(address)}, #{@string})"
+    end
+    
+    def inspect
+      "#<#{self.class}:#{@instruction_store.address_description(address)}, #{@string}>"
+    end
+    
+    # Returns info about all the instructions that this instruction could directly lead to
+    # (not counting interrupts, returns, and not accounting
+    # at all for what happens after the last word in flash is executed).
+    # For instructions that pop from the call stack like RETURN and RETFIE, this will be
+    # the empty array.
+    # @return [Array(Transition)]
+    def transitions
+      @transitions ||= generate_transitions
+    end
+    
+    # Returns the transition from this instruction to the specified instruction
+    # or nil if no such transition exists.
+    # @return Transition
+    def transition_to(instruction)
+      @transitions.find { |t| t.next_instruction == instruction }
+    end
+
+    # Returns the addresses of all the instructions this instruction could directly lead to.
+    # @return [Array(Integer)]
+    def next_addresses
+      transitions.collect do |t|
+        t.next_instruction.address
+      end
+    end
+
+    private
+    # For certain opcodes, this method gets over-written.
+    def generate_transitions
+      [ advance(1) ]
+    end
+    
+    # Makes a transition representing the default behavior: the microcontroller
+    # will increment the program counter and execute the next instruction in memory.
+    def advance(num)
+      transition(address + num * size)
+    end
+    
+    def transition(addr, attrs={})
+      next_instruction = @instruction_store.instruction(addr)
+      Transition.new(self, next_instruction, attrs)
+    end
+    
+    private
+    # Returns the address indicated by the operand 'k'.
+    # k is assumed to be a word address and it is assumed to be absolute
+    # k=0 is word 0 of memory, k=1 is word one.
+    # We need to multiply by the address increment because on PIC18
+    # flash addresses are actually byte-based instead of word-based.
+    def k_address
+      operands['k'] * @address_increment
+    end
+    
+    ### Modules that modify the behavior of the instruction. ###
+    
+    
+    # This module is mixed into any {Instruction} that represents a goto or branch.
+    module Goto
+      def generate_transitions
+        # Assumption: The GOTO instruction's k operand is absolute on all architectures
+        [ transition(k_address, non_local: true) ]
+      end
+    end
+    
+    # This module is mixed into any {Instruction} that represents a conditional skip
+    # A conditional skip is an instruction that might cause the next instruction to be
+    # skipped depending on some condition.
+    module ConditionalSkip
+      def generate_transitions
+        [ advance(1), advance(2) ]
+      end
+    end
+    
+    # This module is mixed into any {Instruction} that represents a return from a subroutine.
+    module Return
+      def generate_transitions
+        []
+      end
+    end
+    
+    # This module is mixed into any {Instruction} that represents a subroutine call.
+    module Call
+      def generate_transitions
+        [ transition(k_address, call_depth_change: 1), advance(1) ]
+      end
+    end
+    
+    class Transition
+      attr_reader :next_instruction, :previous_instruction
+    
+      def initialize(previous_instruction, next_instruction, attrs)
+        @previous_instruction = previous_instruction
+        @next_instruction = next_instruction
+        @attrs = attrs
+      end
+      
+      def non_local?
+        @attrs.fetch(:non_local, false)
+      end
+      
+      def call_depth_change
+        @attrs.fetch(:call_depth_change, 0)
+      end
+    end
+  end
+end

data/lib/rpicsim/label.rb

@@ -0,0 +1,28 @@
+module RPicSim
+  # A very simple class that represents a label in firmware.
+  class Label
+    # The name of the label from the firmware.
+    # @return (Symbol)
+    attr_reader :name
+    
+    # The address/value of the label from the firmware.
+    # @return (Integer)
+    attr_reader :address
+
+    # Makes a new label with the specified name and address.
+    def initialize(name, address)
+      @name = name
+      @address = address
+    end
+
+    # Returns the address of the label.
+    def to_i
+      address
+    end
+    
+    # Returns a nice string representation of the label.
+    def to_s
+      "<Label %s address=0x%x>" % [name, address]
+    end
+  end
+end

data/lib/rpicsim/memory.rb

@@ -0,0 +1,29 @@
+class Memory
+  # This object allows read and write access to the current data
+  # stored in a memory space of the simulated device.
+  #
+  # The behavior of this class differs depending on what kind of Memory
+  # it represents, as shown in the table below:
+  #
+  #                       Address type   Read/write chunk
+  #     Any type of RAM:  Byte address   1 byte (8 bits)
+  #     Midrange Flash:   Word address   1 word (14 bits)
+  #     PIC18 flash:      Byte address   1 word (16 bits)
+  #
+  # @param mplab_memory [Mplab::Memory]
+  def initialize(mplab_memory)
+    @mplab_memory = mplab_memory
+  end
+
+  def write_word(address, value)
+    @mplab_memory.write_word(address, value)
+  end
+  
+  def read_word(address)
+    @mplab_memory.read_word(address)
+  end
+  
+  def is_valid_address?(address)
+    @mplab_memory.is_valid_address?(address)
+  end
+end

data/lib/rpicsim/memory_watcher.rb

@@ -0,0 +1,98 @@
+require 'set'
+
+module RPicSim
+  # This class can attach to an MPLAB X memory class and watch for changes in it, and
+  # report those changes as a hash associating variable names to new values.  This is
+  # very useful for writing tests that assert that not only were the desired variables
+  # written to, but also that no other variables were written to.
+  #
+  # This class does not analyze the current instruction being executed; it uses the
+  # Attach method of the MPLAB X memory classes.  This means that it doesn't work properly
+  # in some versions of MPLAB X.  See {file:docs/Flaws.textile}.
+  class MemoryWatcher
+    attr_accessor :var_names_ignored
+    attr_accessor :var_names_ignored_on_first_step
+    
+    # Creates a new instance.
+    # @param sim [Sim]
+    # @param memory [Mplab::MplabMemory] The memory to watch
+    # @param vars [Array(Variable)]
+    def initialize(sim, memory, vars)
+      # Populate the @vars_by_address instance hash
+      @vars_by_address = {}
+      vars.each do |var|
+        var.addresses.each do |address|
+          if @vars_by_address[address]
+            raise "Variable %s overlaps with %s at 0x%x" %
+              [var, @vars_by_address[address], address]
+          end
+          @vars_by_address[address] = var
+        end
+      end
+    
+      @sim = sim
+      @memory = memory
+      @memory.on_change { |ar| handle_change(ar) }
+      
+      @vars_written = Set.new
+      @var_names_ignored = default_var_names_ignored(sim.device)
+      @var_names_ignored_on_first_step = default_var_names_ignored_on_first_step(sim.device)
+    end
+
+    # Generate a nice report of what variables have been written to since the
+    # last time {#clear} was called.
+    # @return [Hash] A hash where the keys are names (as symbols) of variables that were
+    #   written to, and the value is the variable's current value.
+    #   If an address was written to that does not correspond to a variable, the key for
+    #   that will just be address as an integer.
+    def writes
+      hash = {}
+      @vars_written.each do |var|
+        if var.is_a? Integer
+          hash[var] = @memory.read_word(var)
+        else
+          hash[var.name] = var.value
+        end
+      end
+      hash
+    end
+
+    # Clears the record of what variables have been written to.
+    def clear
+      @vars_written.clear
+    end
+    
+    def default_var_names_ignored(device_name)
+      # The datasheet says the PCLATH is not affected by pushing or popping the stack, but
+      # we still get spurious events for it when a return instruction is executed.
+
+      [:PCL, :PCLATH, :STATUS]
+    end
+    
+    def default_var_names_ignored_on_first_step(device_name)
+      #TODO: get rid of this stuff? people should just have a goto or something harmless at
+      # the beginning of their program and take a single step like we do.
+      [:PORTA, :LATA, :OSCCON, :PMCON2, :INTCON]
+    end
+    
+    def handle_change(address_ranges)
+      addresses = address_ranges.flat_map(&:to_a)
+      vars = addresses.map { |a| @vars_by_address[a] || a }
+
+      remove_vars(vars, @var_names_ignored)
+      remove_vars(vars, @var_names_ignored_on_first_step) if @sim.cycle_count <= 1
+      
+      # The line below works because @vars_written is a Set, not a Hash.
+      @vars_written.merge vars
+    end
+
+    private
+    def remove_vars(vars, var_names_to_remove)
+      vars.reject! do |key, val|
+        name = key.is_a?(Integer) ? key : key.name
+        var_names_to_remove.include?(name)
+      end
+    end
+   
+  end
+end

data/lib/rpicsim/mplab.rb

@@ -0,0 +1,138 @@
+require 'java'
+require 'pathname'
+
+module RPicSim
+  module Mplab
+    # Returns a Pathname object representing the directory of the MPLAB X we are using.
+    # This can either come from the +RPICSIM_MPLABX+ environment variable or it can
+    # be auto-detected by looking in the standard places that MPLAB X is installed.
+    # @return [Pathname]
+    def self.dir
+      @dir ||= begin
+        dir = ENV['RPICSIM_MPLABX']
+
+        dir ||= [
+          "C:/Program Files (x86)/Microchip/MPLABX/",
+          "C:/Program Files/Microchip/MPLABX/",
+          # TODO: add entries here for MPLAB X folders in Linux and Mac OS X
+        ].detect { |d| File.directory?(d) }
+
+        if !dir
+          raise "Cannot find MPLABX.  Install it in the standard location or " +
+            "set the RPICSIM_MPASM environment variable to its full path."
+        end
+
+        if !File.directory?(dir)
+          raise "MPLABX directory does not exist: #{dir}"
+        end
+
+        Pathname(dir)
+      end
+    end
+
+    # Adds all the needed MPLAB X jar files to the classpath so we can use the
+    # classes.
+    def self.load_dependencies
+      %w{ mplab_ide/mdbcore/modules/*.jar
+          mplab_ide/mplablibs/modules/*.jar
+          mplab_ide/mplablibs/modules/ext/*.jar
+          mplab_ide/platform/lib/org-openide-util*.jar
+          mplab_ide/platform/lib/org-openide-util.jar
+          mplab_ide/mdbcore/modules/ext/org-openide-filesystems.jar
+      }.each do |pattern|
+        Dir.glob(dir + pattern).each do |jar_file|
+          $CLASSPATH << jar_file
+        end
+      end
+
+      # Do a quick test to make sure we can load some MPLAB X classes.
+      # In case MPLAB X was uninstalled and its directory remains, this can provide
+      # a useful error message to the user.
+      begin
+        org.openide.util.Lookup
+        com.microchip.mplab.mdbcore.simulator.Simulator
+      rescue NameError
+        $stderr.puts "Failed to load MPLAB X classes.\n" +
+          "MPLAB X dir: #{dir}\nClass path:\n" + $CLASSPATH.to_a.join("\n") + "\n\n"
+        raise
+      end
+    end
+
+    load_dependencies
+
+
+    # JRuby makes it hard to access packages with capital letters in their names.
+    # This is a workaround to let us access those packages.
+    module CapitalizedPackages
+      include_package "com.microchip.mplab.libs.MPLABDocumentLocator"
+    end
+
+    # The com.microchip.mplab.libs.MPLABDocumentLocator.MPLABDocumentLocator class from MPLAB X.
+    DocumentLocator = CapitalizedPackages::MPLABDocumentLocator
+
+    # Returns a string like "1.95" representing the version of MPLAB X we are using.
+    # NOTE: You should probably NOT be doing this to work around flaws in MPLAB X.
+    # Instead, you should add a new entry in flaws.rb and then use
+    # RPicSim::Flaws[:FLAWNAME] to see if the flaw exists and choose the appropriate workaround.
+    def self.version
+      # This implementation is not pretty; I would prefer to just find the right function
+      # to call.
+      @mplabx_version ||= begin
+        paths = Dir.glob(dir + "Uninstall_MPLAB_X_IDE_v*.dat")
+        if paths.empty?
+          raise "Cannot detect MPLAB X version.  The Uninstall_MPLAB_X_IDE_v*.dat file was not found in #{mplabx_dir}."
+        end
+        match_data = paths.first.match(/v([0-9][0-9\.]*[0-9]+)\./)
+        match_data[1]
+      end
+    end
+
+    # Mutes the standard output, calls the given block, and then unmutes it.
+    def self.mute_stdout
+      begin
+        orig = java.lang.System.out
+        java.lang.System.setOut(java.io.PrintStream.new(NullOutputStream.new))
+        yield
+      ensure
+        java.lang.System.setOut(orig)
+      end
+    end
+
+    # Mutes a particular type of exception printed by NetBeans,
+    # calls the given block, then unmutes it.
+    def self.mute_exceptions
+      log = java.util.logging.Logger.getLogger('org.openide.util.Exceptions')
+      level = log.getLevel
+      begin
+        log.setLevel(java.util.logging.Level::OFF)
+        yield
+      ensure
+        log.setLevel(level)
+      end
+    end
+
+    # The MCDisAsm class is the disassembly provided by MPLAB X.
+    # We added this part so we could get access to its strategy object, but
+    # we are not currently using that feature.
+    class Java::ComMicrochipMplabMdbcoreDisasm::MCDisAsm
+      field_accessor :strategy
+    end
+
+    # This class helps us suppress the standard output temporarily.
+    class NullOutputStream < Java::JavaIo::OutputStream
+      def write(b)
+      end
+    end
+    
+    Lookup = org.openide.util.Lookup
+    Mdbcore = com.microchip.mplab.mdbcore
+  end
+
+end
+
+# We want as much awareness as possible; if it becomes a problem we can change this.
+com.microchip.mplab.logger.MPLABLogger.mplog.setLevel(java.util.logging.Level::ALL)
+
+require_relative 'mplab/mplab_pin'
+require_relative 'mplab/mplab_assembly'
+require_relative 'mplab/mplab_program_file'