rpicsim 0.1.0

data/docs/Stubbing.md

@@ -0,0 +1,161 @@
+Stubbing
+====
+
+Stubbing is a technique used in {file:UnitTesting.md unit testing} to replace a routine in a system under test with a simpler routine whose behavior can be specified in the test.
+Stubbing allows you to limit the amount of code you are testing, which can make that test easier to design and faster to run.
+RPicSim does not have any special features to support stubbing, but it can easily be accomplished using features already present.
+
+
+A basic stub
+----
+
+To stub a method in the most basic way, you can do something like this:
+
+    !!!ruby
+    every_step do
+      if pc.value == label(:foo).address
+        sim.return
+      end
+    end
+
+The example above just alters our simulation so that whenever the `foo` subroutine is called, instead of running as normal it will return immediately using {RPicSim::Sim#return}.
+
+The example above can be expanded in many ways:
+You might read and write from {file:Variables.md variables} and {file:SFRs.md SFRs}.
+You might record information about how the subroutine was called.
+
+
+A stub that counts
+----
+
+If you want to know how many times the stubbed routine is called, you could do this:
+
+    !!!ruby
+    @foo_count = 0
+    every_step do
+      if pc.value == label(:foo).address
+        @foo_count += 1
+        sim.return
+      end
+    end
+
+Using a Ruby instance variable `@foo_count` instead of a simple local variable means that this code could go in a before hook and the code that checks the count could be in the main part of the RSpec example.
+
+
+A stub that records parameters
+----
+
+You might want to test that the right parameters are getting supplied to the stubbed routine.
+To capture information about the stubbed routine's parameters or anything else about the state of the simulation, you could use a Ruby array:
+
+    !!!ruby
+    @foo_calls = []
+    every_step do
+      if pc.value == label(:foo).address
+        @foo_calls << { a: foo_param_a.value, b: foo_param_b.value }
+        sim.return
+      end
+    end
+
+In your RSpec examples, you can test that the routine was called the right number of times and with the expected parameters:
+
+    !!!ruby
+    expect(@foo_calls).to eq [ {a: 1, b: 25}, {a: 2, b: 24 } ]
+
+
+LongDelay example
+----
+
+This is a more complete example showing how to make a simple stub that counts the number of times it was called.
+
+Here is a minimal MPASM assembly program with two routines.
+The `bigDelay` routine delays for a long time using a 16-bit counter and a loop.
+The `cooldown` routine either calls `bigDelay` once or twice depending on some condition.
+
+    !!!plain
+      #include p10F322.inc
+      __config(0x3E06)
+      udata
+    hot res 1
+    counter res 2
+      code 0
+
+    cooldown:
+      btfsc hot, 0
+      call bigDelay
+      call bigDelay
+      return
+
+    bigDelay:
+      movlw   255
+      movwf   counter
+      movlw   255
+      movwf   counter + 1
+    delayLoop:
+      decfsz  counter, F
+      goto    delayLoop
+      decfsz  counter+1, F
+      goto    delayLoop
+      return
+      end
+
+Suppose we want to write a unit test for the logic in the `cooldown` method.
+We could just run the subroutine in various conditions and see how long it takes to finish.
+However, that test could be very slow to run.
+Instead, we should stub the `bigDelay` method and make the stub count how many times it was called.
+
+In `spec/spec_helper.rb`, we make a simulation class that points to the compiled COF file.  There is nothing special here:
+
+    !!!ruby
+    require 'rpicsim/rspec'
+
+    class LongDelay < RPicSim::Sim
+      device_is "PIC10F322"
+      filename_is File.dirname(__FILE__) + "../firmware/dist/firmware.cof"
+      def_var :hot, :u8
+    end
+
+In `spec/cooldown_spec.rb`, we stub the `bigDelay` routine and test `cooldown` to make sure it calls `bigDelay` the right number of times:
+
+    !!!ruby
+    require 'rpicsim/rspec'
+
+    describe "cooldown" do
+      before do
+        start_sim Firmware::LongDelay
+
+        # Stub the "bigDelay" function because it takes a long time to run.
+        # Also, count how many times it was called.
+        @big_delay_count = 0
+        every_step do
+          if pc.value == label(:bigDelay).address
+            @big_delay_count += 1
+            sim.return
+          end
+        end
+      end
+
+      context "when the room is cool" do
+        before do
+          hot.value = 0
+        end
+
+        it "only does one big delay" do
+          run_subroutine :cooldown, cycle_limit: 100
+          expect(@big_delay_count).to eq 1
+        end
+      end
+
+      context "when the room is hot" do
+        before do
+          hot.value = 1
+        end
+
+        it "does two big delays" do
+          run_subroutine :cooldown, cycle_limit: 100
+          expect(@big_delay_count).to eq 2
+        end
+      end
+    end
+
+This makes our test much faster and allows us to just test the behavior of the `cooldown` routine.

data/docs/SupportedCompilers.md

@@ -0,0 +1,5 @@
+# Supported compilers
+
+RPicSim supports any compiler that can generate a standard Microchip COF file that is recognized by the COF-loading code in MPLAB X.  If your compiler does not generate such a file, then you could use an Intel HEX file instead, but then RPicSim will not automatically have access to your firmware's symbol table, so it will not know where variables, functions, and labels are located.
+
+RPicSim has been extensively tested with COF files produced by MPASM.  At the time of this writing, it has not been tested with XC8 or C18.

data/docs/SupportedDevices.md

@@ -0,0 +1,14 @@
+# Supported devices
+
+RPicSim aims to support all 8-bit PIC microcontrollers.  No support is planned for 16-bit or 32-bit PIC microcontrollers because the author does not have an interest in using those devices.  It might be easy to add support for them, but the code that handles {file:SFRs.md SFRs} would have to be adjusted to allow SFRs with more than 8 bits.
+
+RPicSim relies on MPLAB X code to perform the actual simulation, and MPLAB X abstracts away most of the differences between PICs.
+
+The 8-bit PICs have {http://www.microchip.com/pagehandler/en-us/family/8bit/architecture/home.html four different architectures}:
+
+- Baseline
+- Midrange
+- Enhanced Midrange
+- PIC18
+
+There is currently some code in {RPicSim::ProgramFile#instruction} that only works with baseline and midrange PICs, but it should be easy to expand it to other PICs.  This code is only used to calculate call stack depth information for users who want that feature; it is not used for actual simulations.

data/docs/SupportedMPLABXVersions.md

@@ -0,0 +1,12 @@
+# Supported MPLAB X versions
+
+RPicSim uses code in MPLAB X to actually perform the PIC simulation.  Therefore, changes to MPLAB X might affect RPicSim and require changes.  Currently, RPicSim supports the following versions of MPLAB X:
+
+- 1.85
+- 1.90
+- 1.95
+- 2.00
+
+The different versions of MPLAB X have different problems that affect the simulation.  For more information, see the {file:KnownIssues.md Known issues page}.
+
+If you would like to power RPicSim with one version of MPLAB X and use another as your actual IDE, see {file:HowMPLABXIsFound.md How MPLAB X is found}.

data/docs/SupportedOperatingSystems.md

@@ -0,0 +1,3 @@
+# Supported Operating Systems
+
+RPicSim currently only supports Windows.  However, it should be easy to get it working on Linux or Mac OS X: probably the only code that would need to be changed is the code in `mplab_x.rb` that helps find the MPLAB X directory automatically and the code that detects what version of MPLAB X is being used.

data/docs/UnitTesting.md

@@ -0,0 +1,9 @@
+Unit Testing
+====
+
+A _unit test_ is a test for a relatively small piece of a code, which tests that code in isolation from the other code in the application.
+Unit testing is simply the practice of writing and running units tests to go along with your code.
+
+The {file:Running.md Running page} explains how to run small portions of your code using RPicSim.
+RPicSim allows you to access {file:Variables.md variables} and {file:SFRs SFRs}, so you can put the simulation into the desired state before running the code and then test that the simulation is in the right state after the code has executed.
+RPicSim can also be used for {file:Stubbing.md stubbing subroutines} so that you can simply test the behavior of one subroutine instead of all the subroutines it calls.

data/docs/Variables.md

@@ -0,0 +1,140 @@
+Variables
+====
+
+RPicSim allows you to read and write from simulated variables stored in RAM or flash, which can be useful for {file:UnitTesting.md unit testing}.  Variables are represented as Ruby objects that are instances of a subclass of {RPicSim::Variable}.
+
+To access a variable, RPicSim needs to know the name it will be called in your Ruby code, what data type it is (e.g. 16-bit unsigned integer), and its address in memory.
+In most cases, RPicSim can deduce the address by looking at the symbol table in your COF file, so you will not need to
+type the address.
+However, RPicSim cannot deduce the data type of a variable, so any variables used need to be explicitly defined beforehand.
+
+Defining a RAM variable
+----
+
+RAM variables that you want to access from Ruby must be defined in the {file:DefiningSimulationClass.md simulation class} using {RPicSim::Sim::ClassDefinitionMethods#def_var def_var}.  For example:
+
+    !!!ruby
+    class MySim < RPicSim::Sim
+      #...
+
+      def_var :counter, :u8
+
+    end
+
+The first argument to `def_var` specifies what to call the variable in Ruby code.  Using the example above, you could access the variable object by passing `:counter` as the argument to {RPicSim::Sim#var}:
+
+    !!!ruby
+    sim.var(:counter)
+
+Each variable also has a "shortcut" method by the same name.  This means that you can access the variable like this:
+
+    !!!ruby
+    sim.counter
+
+The shortcuts are also available in RSpec thanks to RPicsim's {file:RSpecIntegration.md RSpec integration}, so you can simply write `counter` in any of your RSpec examples:
+
+    !!!ruby
+    it "drives the main output high" do
+      expect(counter.value).to eq 44
+    end
+
+The second argument to `def_var` specifies the data type of the variable.  This is required.  For the full list of allowed types, see {RPicSim::Sim::ClassDefinitionMethods#def_var}.
+
+In the example above, RPicSim will look in your firmware's COF file for a RAM symbol named "counter" and it will use that as the address for the variable, so you do not need to specify the address yourself.
+
+You can use the `symbol` option to specify what symbol in the symbol table marks the location of the variable.  For example:
+
+    !!!ruby
+    def_var :counter, :u8, symbol: :_counter
+
+The example above shows how you could access a variable from a C compiler (which will generally be prefixed with an underscore) without having to type the underscore in your tests.
+More generally, the `symbol` option allows you to call a variable one thing in your firmware and call it a different thing in your tests.
+
+RPicSim will raise an exception if it cannot find the specified symbol in the symbol table.  To troubleshoot this, you might print the list of variables that RPicSim found:
+
+    !!!ruby
+    p sim.class.program_file.var_addresses.keys
+
+You can use the `address` option to specify an arbitrary address instead of using the symbol table.  For example:
+
+    !!!ruby
+    def_var :counter, :u8, address: 0x63
+
+
+Defining Flash variables
+----
+
+Flash (program space) variables work the same way as RAM variables except:
+
+* They are defined with {RPicSim::Sim::ClassDefinitionMethods#def_flash_var def_flash_var}.
+* The set of allowed data types for the second argument of `def_flash_var` is different, and you can see the documentation by clicking the link above.
+* Flash variables cannot be accessed with {RPicSim::Sim#var}, but can be accessed with {RPicSim::Sim#flash_var}
+
+
+Using a variable
+----
+
+Once you have defined a variable and accessed it using one of the methods above, you will have an instance of a subclass of {RPicSim::Variable}.  You can read and write the value of the variable using the `value` attribute:
+
+    !!!ruby
+    counter.value = 0x6A
+    expect(counter.value).to eq 0x6A
+
+
+Addition example
+----
+
+This section contains a simple example showing how to apply the information above and use {RPicSim::Variable} objects.
+
+Here is a minimal MPASM assembly program for the PIC10F322 that does not actually do anything but it has a 16-bit addition subroutine:
+
+    !!!plain
+    #include p10F322.inc
+    __config(0x3E06)
+      udata
+    x res 2
+    y res 2
+    z res 2
+      code 0
+    addition  ; 16-bit addition routine:  z = x + y
+      movf    x, W
+      addwf   y, W
+      movwf   z
+      movf    x + 1, W
+      btfsc   STATUS, C
+      addlw   1
+      addwf   y + 1, W
+      movwf   z + 1
+      return
+      end
+
+In `spec/spec_helper.rb`, we make a simulation class that points to the compiled COF file and defines the variables:
+
+    !!!ruby
+    require 'rpicsim/rspec'
+
+    class Addition < RPicSim::Sim
+      device_is "PIC10F322"
+      filename_is File.dirname(__FILE__) + "../firmware/dist/firmware.cof"
+      def_var :x, :u16
+      def_var :y, :u16
+      def_var :z, :u16
+    end
+
+In `spec/addition_spec.rb`, we write a simple unit test that writes to `x` and `y`, runs the `addition` subroutine, and checks that the correct result is stored in `z`:
+
+    !!!ruby
+    require_relative 'spec_helper'
+
+    describe "addition routine" do
+      before do
+        start_sim Addition
+      end
+    
+      it "can add 70 + 22"
+        x.value = 70
+        y.value = 22
+        run_subroutine :addition, cycle_limit: 100
+        expect(z.value).to eq 92
+      end
+    end

data/lib/rpicsim.rb

@@ -0,0 +1,15 @@
+require_relative 'rpicsim/version'
+require_relative 'rpicsim/sim'
+require_relative 'rpicsim/call_stack_info'
+
+# TODO: add a feature for Flash size reports
+# TODO: add a feature for RAM usage reports
+
+# TODO: add a feature for calculating the minimum and maximum iteration
+#   time from one point in the program to another
+#   (as a special case, this lets you calculate the iteration time of the
+#     main loop if both points are the same)
+
+# TODO: add matchers: have_value(44), have_value.in(0..3), and maybe:
+#    have_value.between(0, 14)     (like RSpec built-in matcher)
+#    have_value.within(3).of(56)   (like RSpec built-in matcher)

data/lib/rpicsim/call_stack_info.rb

@@ -0,0 +1,306 @@
+require_relative 'search'
+require 'set'
+
+module RPicSim
+  # This class helps analyze programs to see whether it is possible for them
+  # to overflow the call stack, which is limited to a small number of levels on
+  # many PIC microcontrollers.
+  # It traverses the {Instruction} graph provided by a {ProgramFile}
+  # from a given root node and for each reachable instruction determines the
+  # maximum possible call stack depth when that instruction starts executing,
+  # relative to how deep the call stack depth was when the root instruction
+  # started.
+  #
+  # Here is an example of how you would use this to check the call stack depth
+  # in a program that has one interrupt vector at address 4 inside an RSpec test.
+  # Of course, you should adjust the numbers to suit your application:
+  #
+  #     infos = CallStackInfo.hash_from_program_file(program_file, [0, 4])
+  #     infos[0].max_depth.should <= 5  # main-line code should take at most 5 levels
+  #     infos[4].max_depth.should <= 1  # ISR should take at most 1 stack level
+  # 
+  # Additionally, it can generate reports of all different ways that the maximum
+  # call stack depth can be achieved, which can be helpful if you need to reduce
+  # your maximum stack depth.
+  class CallStackInfo
+    # For each of the given root instruction addresses, generates a {CallStackInfo}
+    # report.  Returns the reports in a hash.
+    #
+    # @param program_file (ProgramFile)
+    # @param root_instruction_addresses Array(Integer)  The flash
+    #   addresses of the entry vectors for your program.  On a midrange device, these
+    #   are typically 0 for the main-line code and 4 for the interrupt.
+    # @return [Hash(address => CallStackInfo)]
+    def self.hash_from_program_file(program_file, root_instruction_addresses)
+      infos = {}
+      root_instruction_addresses.each do |addr|
+        infos[addr] = from_root_instruction(program_file.instruction(addr))
+      end
+      infos
+    end
+    
+    # Generates a {CallStackInfo} from the given root instruction.
+    # This will tell you the maximum value the call stack could get to for a
+    # program that starts at the given instruction with an empty call stack
+    # and never gets interrupted.
+    def self.from_root_instruction(root)
+      new(root)
+    end
+  
+    # The maximum call stack depth for all the reachable instructions.
+    # If your program starts executing at the root node and the call stack
+    # is empty, then (not accounting for interrupts) the call stack will
+    # never exceed this depth.
+    #
+    # A value of 0 means that no subroutine calls a possible; a value of
+    # 1 means that at most one subroutine call is possible at any given time,
+    # and so on.
+    #
+    # @return (Integer)
+    attr_reader :max_depth
+    
+    # @return (Instruction) The root instruction that this report was generated from.
+    attr_reader :root
+
+    # Generates a {CallStackInfo} from the given root instruction.
+    def initialize(root)
+      @root = root
+      generate
+      @max_depth = @max_depths.values.max
+    end
+    
+    private
+    def generate
+      @max_depths = { @root => 0 }
+      @back_links = Hash.new { [] }
+      instructions_to_process = [root]
+      while !instructions_to_process.empty?
+        instruction = instructions_to_process.pop
+        instruction.transitions.reverse_each do |transition|
+          ni = transition.next_instruction
+          prev_depth = @max_depths[ni]
+          new_depth = @max_depths[instruction] + transition.call_depth_change
+
+          if new_depth > 50
+            raise "Recursion probably detected.  Maximum call depth of #{ni} is at least #{new_depth}."
+          end
+
+          if prev_depth.nil? || new_depth > prev_depth
+            #puts "%30s, MD=%d" % [ni, new_depth]
+            @max_depths[ni] = new_depth
+            instructions_to_process << ni
+            @back_links[ni] = []
+          end
+          
+          if new_depth == @max_depths[ni]
+            #puts "Adding backlink #{ni} -> #{instruction}"
+            @back_links[ni] << instruction
+          end
+        end
+      end      
+    end
+    public
+    
+    # Returns all the {Instruction}s that have the worse case possible call stack depth.
+    # @return [Array(Instruction)]
+    def instructions_with_worst_case
+      @max_depths.select { |instr, depth| depth == @max_depth }.collect(&:first).sort
+    end
+    
+    # Returns all the {Instruction}s that are reachable from the given root.
+    # @return [Array(Instruction)]
+    def reachable_instructions
+      @max_depths.keys
+    end
+    
+    # Check the max-depth data hash for consistency.
+    def double_check!
+      reachable_instructions.each do |instr|
+        depth = @max_depths[instr]
+
+        instr.transitions.each do |transition|
+          next_instruction = transition.next_instruction
+          if @max_depths[next_instruction] < @max_depths[instr] + transition.call_depth_change
+            raise "Call stack info double check failed: %s has max_depth %d and leads (%d) to %s with max_depth %d." %
+              [instr, depth, transition.call_depth_change, next_instruction, @max_depths[next_instruction]]
+          end
+        end
+        
+      end
+    end
+    
+    # Returns an array of {CodePath}s representing all possible ways that the call stack
+    # could reach the worst-case depth.  This will often be a very large amount of data,
+    # even for a small project.
+    # @return [Array(CodePath)]
+    def worst_case_code_paths
+      instructions_with_worst_case.sort.flat_map do |instruction|
+        code_paths(instruction)
+      end
+    end
+    
+    # Returns a filtered version of {#worst_case_code_paths}.
+    # Filters out any code paths that are just a superset of another code path.
+    # For each instruction that has a back trace leading to it, it just returns
+    # the code paths with the smallest number of interesting instructions.
+    # @return [Array(CodePath)]
+    def worst_case_code_paths_filtered
+      all_code_paths = worst_case_code_paths
+
+      #puts "all worst-case code paths: #{all_code_paths.size}"
+      
+      # Filter out code path that are just a superset of another code path.
+      previously_seen_instruction_sequences = Set.new
+      code_paths = []
+      all_code_paths.sort_by(&:count).each do |code_path|
+        seen_before = (1..code_path.instructions.size).any? do |n|
+          subsequence = code_path.instructions[0, n]
+          previously_seen_instruction_sequences.include? subsequence
+        end
+        if !seen_before
+          previously_seen_instruction_sequences << code_path.instructions
+          code_paths << code_path
+        end
+      end
+
+      # For each instruction that has a code path leading to it, pick out
+      # the shortest code path (in terms of interesting instructions).
+      code_paths = code_paths.group_by { |cp| cp.instructions.last }.collect do |instr, code_paths|
+        code_paths.min_by { |cp| cp.interesting_instructions.count }
+      end
+      
+      code_paths
+    end
+    
+    # Returns a nice report string of all the {#worst_case_code_paths_filtered}.
+    # @return [String]
+    def worst_case_code_paths_filtered_report
+      s = ""
+      worst_case_code_paths_filtered.each do |code_path|
+        s << code_path.to_s + "\n"
+        s << "\n"
+      end
+      s
+    end
+    
+    # @return [Array(CodePaths)] all the possible code paths that lead to the given instruction.
+    def code_paths(instruction)
+      code_paths = []
+      Search.depth_first_search_simple([[instruction]]) do |instrs|
+        prev_instrs = @back_links[instrs.first]
+        
+        if prev_instrs.empty?
+          # This must be the root node.
+          if instrs.first != @root
+            raise "This instruction is not the root and has no back links: #{instrs}."
+          end
+          
+          code_paths << CodePath.new(instrs)
+          []   # don't search anything from this node
+        else
+          # Investigate all possible code paths that could get to this instruction.
+          # However, exclude code paths that have the same instruction twice;
+          # otherwise we get stuck in an infinite loop.
+          (prev_instrs - instrs).collect do |instr|
+            [instr] + instrs
+          end
+        end
+      end
+      code_paths
+    end
+    
+    def inspect
+      "#<#{self.class}:root=#{@root.inspect}>"
+    end
+
+    # This is a helper class for {CallStackInfo}.  It wraps an array of {Instruction} objects
+    # representing an execution path from one part of the program (usually the entry vector or
+    # the ISR vector) to another part of the program.
+    # It has method for reducing this list of instructions by only showing the interesting ones.
+    class CodePath
+      include Enumerable
+      
+      # An array of {Instruction}s that represents a possible path through the program.
+      # Each instruction in the list could possibly execute after the previous one.
+      attr_reader :instructions
+    
+      # A new instance that wraps the given instructions.
+      # @param instructions Array(Instruction) The instructions to wrap.
+      def initialize(instructions)
+        @instructions = instructions.freeze
+      end
+      
+      # Iterates over the wrapped instructions by calling <tt>each</tt> on the underlying array.
+      # Since this class also includes <tt>Enumerable</tt>, it means you can use any of the
+      # usual methods of Enumerable (e.g. <tt>select</tt>) on this class.
+      def each(&proc)
+        instructions.each(&proc)
+      end
+      
+      # Returns the addresses of the underlying instructions.
+      def addresses
+        instructions.collect(&:address)
+      end
+      
+      # Returns an array of the addresses of the interesting instructions.
+      def interesting_addresses
+        interesting_instructions.collect(&:address)    
+      end
+      
+      # Returns just the interesting instructions, as defined by {#interesting_instruction?}.
+      #
+      # @return [Array(Integer)]
+      def interesting_instructions
+        @instructions.select.each_with_index do |instruction, index|
+          next_instruction = @instructions[index + 1]
+          interesting_instruction?(instruction, next_instruction)
+        end
+      end
+      
+      # Returns true if the given instruction is interesting.  An instruction is
+      # interesting if you would need to see it in order to understand the path
+      # program has taken through the code and understand why the call stack
+      # could reach a certain depth.
+      #
+      # * The first and last instructions are interesting.
+      # * A branch that is taken is interesting.
+      # * A subroutine call is interesting.
+      def interesting_instruction?(instruction, next_instruction)
+        if instruction == @instructions.first || instruction == @instructions.last
+          return true
+        end
+        
+        transition = instruction.transition_to(next_instruction)
+        
+        if transition.call_depth_change >= 1
+          # This edge represents a function call so it is interesting.
+          return true
+        end
+        
+        if transition.non_local?
+          # This edge represents a goto, so that is interesting
+          # because you need to know which gotos were taken to understand
+          # a code path.  If seeing the skip is annoying we could
+          # suppress that by adding more information to the edge.
+          return true
+        end
+        
+        # Everything else is not interesting.
+        
+        # We are purposing deciding that skips are not interesting.
+        # because if you are trying to understand the full code path
+        # it is obvious whether any given skip was taken or not, as long
+        # as you know which calls and gotos were taken.
+
+        return false
+      end
+      
+      # Returns a multi-line string representing this execution path.
+      def to_s
+        "CodePath:\n" +
+          interesting_instructions.join("\n") + "\n"
+      end
+    end
+    
+  end
+end