rpicsim 0.1.0 → 0.2.1

data/lib/rpicsim/label.rb

@@ -4,7 +4,7 @@ module RPicSim
     # 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
@@ -19,10 +19,10 @@ module RPicSim
     def to_i
       address
     end
-    
+
     # Returns a nice string representation of the label.
     def to_s
-      "<Label %s address=0x%x>" % [name, address]
+      '<Label %s address=0x%x>' % [name, address]
     end
   end
-end
+end

data/lib/rpicsim/memory.rb

@@ -1,29 +1,50 @@
-class Memory
-  # This object allows read and write access to the current data
+module RPicSim
+  # This object allows read and write access to the data currently
   # stored in a memory space of the simulated device.
+  # Instances are usually retrieved from a {Sim} object by calling
+  # {Sim#ram}, {Sim#program_memory}, or {Sim#eeprom}.
   #
-  # The behavior of this class differs depending on what kind of Memory
-  # it represents, as shown in the table below:
+  # The behavior of +read_word+ and +write_word+ differs depending on
+  # what kind of Memory is being used, 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)
+  #     Memory type                Address type   Read/write chunk
+  #     RAM and EEPROM:            Byte address   1 byte (8 bits)
+  #     PIC18 program memory:      Byte address   1 word (16 bits)
+  #     Non-PIC18 program memory:  Word address   1 word (12 or 14 bits)
   #
-  # @param mplab_memory [Mplab::Memory]
-  def initialize(mplab_memory)
-    @mplab_memory = mplab_memory
-  end
+  # The +read_byte+ and +write_byte+ methods use the same type of address as
+  # +read_word+ and +write_word+, but they can only read and write from the
+  # lower 8 bits of the word.
+  # The upper bits of the word, if there are any, are left unchanged.
+  # For RAM and EEPROM, +read_byte+ and +write_byte+ behave the same way as
+  # +read_word+ and +write_word+.
+  #
+  # For more information, see {file:Memories.md}.
+  class Memory
+    # @param mplab_memory [Mplab::Memory]
+    def initialize(mplab_memory)
+      @mplab_memory = mplab_memory
+    end
+
+    def read_byte(address)
+      @mplab_memory.read_byte(address)
+    end
+
+    def write_byte(address, value)
+      @mplab_memory.write_byte(address, value)
+    end
+
+    def read_word(address)
+      @mplab_memory.read_word(address)
+    end
+
+    def write_word(address, value)
+      @mplab_memory.write_word(address, value)
+    end
+
+    def valid_address?(address)
+      @mplab_memory.valid_address?(address)
+    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
+end

data/lib/rpicsim/memory_watcher.rb

@@ -12,7 +12,7 @@ module RPicSim
   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
@@ -23,20 +23,19 @@ module RPicSim
       vars.each do |var|
         var.addresses.each do |address|
           if @vars_by_address[address]
-            raise "Variable %s overlaps with %s at 0x%x" %
+            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
@@ -61,27 +60,13 @@ module RPicSim
     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
@@ -93,6 +78,13 @@ module RPicSim
         var_names_to_remove.include?(name)
       end
     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
+
   end
-end
+end

data/lib/rpicsim/mplab.rb

@@ -1,138 +1,57 @@
-require 'java'
-require 'pathname'
+require_relative 'mplab/mplab_loader'
 
-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']
+module RPicSim::Mplab
+  MplabLoader.instance.load
 
-        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
+  def self.version
+    MplabLoader.instance.mplab_version
+  end
 
-    # The com.microchip.mplab.libs.MPLABDocumentLocator.MPLABDocumentLocator class from MPLAB X.
-    DocumentLocator = CapitalizedPackages::MPLABDocumentLocator
+  # JRuby makes it hard to access packages with capital letters in their names.
+  # This is a workaround to let us access those packages.
+  capitalized_packages = Module.new do
+    include_package 'com.microchip.mplab.libs.MPLABDocumentLocator'
+  end
 
-    # 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
+  # The com.microchip.mplab.libs.MPLABDocumentLocator.MPLABDocumentLocator class from MPLAB X.
+  DocumentLocator = capitalized_packages::MPLABDocumentLocator
 
-    # 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
+  Lookup = org.openide.util.Lookup
+  Mdbcore = com.microchip.mplab.mdbcore
 
-    # 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
+  # Mutes the standard output, calls the given block, and then unmutes it.
+  def self.mute_stdout
+    orig = java.lang.System.out
+    java.lang.System.setOut(java.io.PrintStream.new(NullOutputStream.new))
+    yield
+  ensure
+    java.lang.System.setOut(orig)
+  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
+  # 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
 
-    # This class helps us suppress the standard output temporarily.
-    class NullOutputStream < Java::JavaIo::OutputStream
-      def write(b)
-      end
+  # This class helps us suppress the standard output temporarily.
+  class NullOutputStream < Java::JavaIo::OutputStream
+    def write(b)
     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 the rest of the RPicSim::Mplab Ruby classes now that MPLAB X has been loaded.
 require_relative 'mplab/mplab_pin'
 require_relative 'mplab/mplab_assembly'
 require_relative 'mplab/mplab_program_file'

data/lib/rpicsim/mplab/mplab_assembly.rb

@@ -3,9 +3,12 @@ require_relative 'mplab_simulator'
 require_relative 'mplab_disassembler'
 
 module RPicSim::Mplab
+  # This class wraps objects belonging to the abstract Java class
+  # com.microchip.mplab.mdbcore.assemblies.Assembly,
+  # which represent a collection of objects being used together.
   class MplabAssembly
     attr_reader :device
-  
+
     def initialize(device)
       @device = device
       assembly_factory = Lookup.default.lookup(Mdbcore.assemblies.AssemblyFactory.java_class)
@@ -13,27 +16,27 @@ module RPicSim::Mplab
         @assembly = assembly_factory.create(device)
       end
     end
-    
+
     # Connect the assembly to a simulator and debugger.
     def start_simulator_and_debugger(filename)
       # In MPLAB X v1.70, this line had to be before the call to SetTool, or else when we run
       # debugger.Connect we will get two lines of: [Fatal Error] :1:1: Premature end of file.
       simulator
-    
-      sim_meta = Mdbcore.platformtool.PlatformToolMetaManager.getTool("Simulator")
-      @assembly.SetTool(sim_meta.configuration_object_id, sim_meta.class_name, sim_meta.flavor, "")
-      if !sim_meta.getToolSupportForDevice(device).all? &:isSupported
-        raise "Microchip's simulator does not support " + device + "."
+
+      sim_meta = Mdbcore.platformtool.PlatformToolMetaManager.getTool('Simulator')
+      @assembly.SetTool(sim_meta.configuration_object_id, sim_meta.class_name, sim_meta.flavor, '')
+      if !sim_meta.getToolSupportForDevice(device).all?(&:isSupported)
+        raise "Microchip's simulator does not support " + device + '.'
       end
-      @assembly.SetHeader("")  # The Microchip documentation doesn't say what this is.
+      @assembly.SetHeader('')  # The Microchip documentation doesn't say what this is.
       debugger.Connect(Mdbcore.debugger.Debugger::CONNECTION_TYPE::DEBUGGER)
-      
+
       # Load our firmware into the simulator.
       load_file(filename)
       debugger.Program(Mdbcore.debugger.Debugger::PROGRAM_OPERATION::AUTO_SELECT)
 
       check_for_errors
-      
+
       nil
     end
 
@@ -55,17 +58,17 @@ module RPicSim::Mplab
     def disassembler
       @disassembler ||= MplabDisassembler.new lookup Mdbcore.disasm.DisAsm.java_class
     end
-    
+
     def device_info
       @device_info ||= MplabDeviceInfo.new(@assembly.GetDevice)
     end
-    
+
     private
     # Gets a com.microchip.mplab.mdbcore.debugger.Debugger object.
     def debugger
       lookup Mdbcore.debugger.Debugger.java_class
     end
-    
+
     def loader
       lookup Mdbcore.loader.Loader.java_class
     end
@@ -73,7 +76,7 @@ module RPicSim::Mplab
     def lookup(klass)
       @assembly.getLookup.lookup klass
     end
-    
+
     def check_for_errors
       warn_about_5C
       warn_about_path_retrieval
@@ -83,9 +86,11 @@ module RPicSim::Mplab
     def warn_about_5C
       # Detect a problem that once caused peripherals to load incorrectly.
       # More info: http://stackoverflow.com/q/15794170/28128
-      f = DocumentLocator.java_class.resource("MPLABDocumentLocator.class").getFile()
-      if f.include?("%5C")
-        $stderr.puts "warning: A %5C character was detected in the MPLABDocumentLoator.class file location.  This might cause errors in the Microchip code."
+      f = DocumentLocator.java_class.resource('MPLABDocumentLocator.class').getFile
+      if f.include?('%5C')
+        $stderr.puts 'warning: A %5C character was detected in the ' \
+          'MPLABDocumentLoator.class file location.  ' \
+          'This might cause errors in the Microchip code.'
       end
     end
 
@@ -93,7 +98,7 @@ module RPicSim::Mplab
       # See spec/mplab_x/path_retrieval_spec.rb for more info.
       retrieval = com.microchip.mplab.open.util.pathretrieval.PathRetrieval
       path = retrieval.getPath(DocumentLocator.java_class)
-      if !java.io.File.new(path).exists()
+      if !java.io.File.new(path).exists
         $stderr.puts "warning: MPLAB X will be looking for files at a bad path: #{path}"
       end
     end