rpicsim 0.1.0 → 0.2.1

data/lib/rpicsim.rb

@@ -1,15 +1,3 @@
 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

@@ -18,7 +18,7 @@ module RPicSim
   #     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.
@@ -27,7 +27,7 @@ module RPicSim
     # report.  Returns the reports in a hash.
     #
     # @param program_file (ProgramFile)
-    # @param root_instruction_addresses Array(Integer)  The flash
+    # @param root_instruction_addresses Array(Integer)  The program memory
     #   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)]
@@ -38,7 +38,7 @@ module RPicSim
       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
@@ -46,7 +46,7 @@ module RPicSim
     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
@@ -58,7 +58,7 @@ module RPicSim
     #
     # @return (Integer)
     attr_reader :max_depth
-    
+
     # @return (Instruction) The root instruction that this report was generated from.
     attr_reader :root
 
@@ -68,7 +68,7 @@ module RPicSim
       generate
       @max_depth = @max_depths.values.max
     end
-    
+
     private
     def generate
       @max_depths = { @root => 0 }
@@ -86,33 +86,31 @@ module RPicSim
           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
     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
+      @max_depths.select { |instr, depth| depth == @max_depth }.map(&: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|
@@ -121,14 +119,14 @@ module RPicSim
         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." %
+            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.
@@ -138,7 +136,7 @@ module RPicSim
         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
@@ -147,8 +145,6 @@ module RPicSim
     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 = []
@@ -165,50 +161,50 @@ module RPicSim
 
       # 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 = code_paths.group_by { |cp| cp.instructions.last }.map 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 = ""
+      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|
+          (prev_instrs - instrs).map do |instr|
             [instr] + instrs
           end
         end
       end
       code_paths
     end
-    
+
     def inspect
       "#<#{self.class}:root=#{@root.inspect}>"
     end
@@ -219,34 +215,34 @@ module RPicSim
     # 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)
+        instructions.map(&:address)
       end
-      
+
       # Returns an array of the addresses of the interesting instructions.
       def interesting_addresses
-        interesting_instructions.collect(&:address)    
+        interesting_instructions.map(&:address)
       end
-      
+
       # Returns just the interesting instructions, as defined by {#interesting_instruction?}.
       #
       # @return [Array(Integer)]
@@ -256,7 +252,7 @@ module RPicSim
           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
@@ -269,14 +265,14 @@ module RPicSim
         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
@@ -284,23 +280,23 @@ module RPicSim
           # 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
+        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
+end

data/lib/rpicsim/composite_memory.rb

@@ -0,0 +1,53 @@
+module RPicSim
+  # This class wraps two or more memory objects and
+  # provides an interface that is also like {RPicSim::Memory}.
+  # Any reads or writes from the composite memory will go to the first
+  # component memory for which the address is valid.
+  class CompositeMemory
+    # Creates a new instance.
+    # The memory objects given must support the following methods:
+    #
+    # * +read_byte+
+    # * +write_byte+
+    # * +read_word+
+    # * +write_word+
+    # * +valid_address?+
+    #
+    # @param memories [Array]
+    def initialize(memories)
+      @memories = memories
+    end
+
+    def read_byte(address)
+      memory(address).read_byte(address)
+    end
+
+    def write_byte(address, value)
+      memory(address).write_byte(address, value)
+    end
+
+    def read_word(address)
+      memory(address).read_word(address)
+    end
+
+    def write_word(address, value)
+      memory(address).write_word(address, value)
+    end
+
+    def valid_address?(address)
+      find_memory(address) != nil
+    end
+
+    private
+
+    def find_memory(address)
+      @memories.find do |memory|
+        memory.valid_address?(address)
+      end
+    end
+
+    def memory(address)
+      find_memory(address) or raise 'Invalid memory address %#x.' % address
+    end
+  end
+end

data/lib/rpicsim/flaws.rb

@@ -18,18 +18,18 @@ module RPicSim
       # @param version [String] A version of MPLAB X, e.g. "1.95".
       # @return effect
       def effect(version)
-        if @versions.has_key? version
+        if @versions.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.
@@ -37,40 +37,52 @@ module RPicSim
         @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.affects_version '1.85', false
+      flaw.affects_version '1.90', false
+      flaw.affects_version '1.95', true
+      flaw.affects_version '2.00', true
+      flaw.affects_version '2.05', 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.affects_version '1.85', true
+      flaw.affects_version '1.90', true
+      flaw.affects_version '1.95', false
+      flaw.affects_version '2.00', false
+      flaw.affects_version '2.05', 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.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.affects_version '2.05', :bad_modulus
       flaw.probably_affects_other_versions :bad_modulus
     end
-  
+
+    add(:instruction_inc_is_in_byte_units) do |flaw|
+      flaw.affects_version '1.85', true
+      flaw.affects_version '1.90', true
+      flaw.affects_version '1.95', true
+      flaw.affects_version '2.00', true
+      flaw.affects_version '2.05', false
+      flaw.probably_affects_other_versions :false
+    end
+
   end
-end
+end

data/lib/rpicsim/instruction.rb

@@ -9,44 +9,155 @@ module RPicSim
   # classes like {CallStackInfo} to get useful information about the firmware.
   class Instruction
     include Comparable
-    
-    # The flash address of the instruction.
+
+    # The program memory 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 number of program memory address units that this instruction takes.
     # The units of this are the same as the units of {#address}.
     # @return (Integer)
     attr_reader :size
 
+    # A line of assembly language that would represent this instruction.
+    # For example "GOTO 0x2".
+    # @return (String)
+    attr_reader :string
+
     # 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)
+    def initialize(mplab_instruction, address, address_increment, instruction_store)
       @address = address
       @instruction_store = instruction_store
-      @opcode = opcode
-      @operands = operands
-      @size = size
       @address_increment = address_increment
-      @string = string
-      
+
+      if mplab_instruction == :invalid
+        @valid = false
+        @size = @address_increment
+        @string = '[INVALID]'
+        return
+      end
+
+      @valid = true
+      @opcode = mplab_instruction.opcode
+      @operands = mplab_instruction.operands
+      @string = mplab_instruction.instruction_string
+
+      @size = mplab_instruction.compute_size(address_increment)
+      raise "Invalid size #{@size} for #{inspect}" if ![1, 2, 4].include?(@size)
+
+      properties = Array case mplab_instruction.opcode
+      when 'ADDFSR'
+      when 'ADDLW'
+      when 'ADDWF'
+      when 'ADDWFC'
+      when 'ANDLW'
+      when 'ANDWF'
+      when 'ASRF'
+      when 'BC'     then [:conditional_relative_branch]
+      when 'BCF'
+      when 'BN'     then [:conditional_relative_branch]
+      when 'BNC'    then [:conditional_relative_branch]
+      when 'BNN'    then [:conditional_relative_branch]
+      when 'BNOV'   then [:conditional_relative_branch]
+      when 'BNZ'    then [:conditional_relative_branch]
+      when 'BRA'    then [:relative_branch]
+      when 'BRW'    then [:control_ender]    # Hard to predict
+      when 'BSF'
+      when 'BTG'
+      when 'BTFSC'  then [:conditional_skip]
+      when 'BTFSS'  then [:conditional_skip]
+      when 'BZ'     then [:conditional_relative_branch]
+      when 'CALL'   then [:call]
+      when 'CALLW'  then [:control_ender]    # Hard to predict
+      when 'CPFSEQ' then [:conditional_skip]
+      when 'CPFSGT' then [:conditional_skip]
+      when 'CPFSLT' then [:conditional_skip]
+      when 'CLRF'
+      when 'CLRW'
+      when 'CLRWDT'
+      when 'COMF'
+      when 'DAW'
+      when 'DECF'
+      when 'DECFSZ' then [:conditional_skip]
+      when 'DCFSNZ' then
+      when 'GOTO'   then [:goto]
+      when 'INCF'
+      when 'INCFSZ' then [:conditional_skip]
+      when 'INFSNZ' then [:conditional_skip]
+      when 'IORLW'
+      when 'IORWF'
+      when 'LFSR'
+      when 'LSLF'
+      when 'LSRF'
+      when 'MOVIW'
+      when 'MOVWI'
+      when 'MOVLB'
+      when 'MOVLP'
+      when 'MOVLW'
+      when 'MOVWF'
+      when 'MOVF'
+      when 'MOVFF'
+      when 'MULLW'
+      when 'MULWF'
+      when 'NEGF'
+      when 'NOP'
+      when 'OPTION'
+      when 'PUSH'
+      when 'POP'
+      when 'RCALL'  then [:relative_call]
+      when 'RESET'  then [:control_ender]
+      when 'RETFIE' then [:control_ender]
+      when 'RETLW'  then [:control_ender]
+      when 'RETURN' then [:control_ender]
+      when 'RLCF'
+      when 'RLF'
+      when 'RLNCF'
+      when 'RRCF'
+      when 'RRF'
+      when 'RRNCF'
+      when 'SETF'
+      when 'SLEEP'
+      when 'SUBLW'
+      when 'SUBWF'
+      when 'SUBWFB'
+      when 'SWAPF'
+      when 'TBLRD*'
+      when 'TBLRD*+'
+      when 'TBLRD*-'
+      when 'TBLRD+*'
+      when 'TBLWT*'
+      when 'TBLWT*+'
+      when 'TBLWT*-'
+      when 'TBLWT+*'
+      when 'TRIS'
+      when 'TSTFSZ' then [:conditional_skip]
+      when 'XORLW'
+      when 'XORWF'
+      else
+        raise "Unrecognized opcode #{mplab_instruction.opcode} " +
+          "(#{address_description(address)}, operands #{mplab_instruction.operands.inspect})."
+      end
+
       modules = {
         conditional_skip: ConditionalSkip,
+        conditional_relative_branch: ConditionalRelativeBranch,
+        relative_branch: RelativeBranch,
+        relative_call: RelativeCall,
         goto: Goto,
-        return: Return,
-        call: Call
+        control_ender: ControlEnder,
+        call: Call,
       }
-      
+
       properties.each do |p|
         mod = modules[p]
         if !mod
@@ -55,32 +166,32 @@ module RPicSim
         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
+      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).
+    # at all for what happens after the last word in the main program memory 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
@@ -91,9 +202,7 @@ module RPicSim
     # 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
+      transitions.map(&:next_address)
     end
 
     private
@@ -101,31 +210,52 @@ module RPicSim
     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)
+      Transition.new(self, addr, @instruction_store, attrs)
     end
-    
+
+    def valid?
+      @valid
+    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.
+    # program memory addresses are actually byte-based instead of word-based.
     def k_address
-      operands['k'] * @address_increment
+      operands[:k] * @address_increment
+    end
+
+    def n_address
+      address + @address_increment * (operands[:n] + 1)
+    end
+
+    def relative_k_address
+      address + @address_increment * (operands[:k] + 1)
+    end
+
+    def relative_target_address
+      if operands[:k]
+        relative_k_address
+      elsif operands[:n]
+        n_address
+      else
+        raise 'This instruction does not have fields k or n.'
+      end
     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
@@ -133,7 +263,7 @@ module RPicSim
         [ 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.
@@ -142,37 +272,63 @@ module RPicSim
         [ advance(1), advance(2) ]
       end
     end
-    
-    # This module is mixed into any {Instruction} that represents a return from a subroutine.
-    module Return
+
+    # This module is mixed into any {Instruction} that represents a return from a subroutine
+    # or a RESET instruction.
+    module ControlEnder
       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
-    
+
+    module RelativeCall
+      def generate_transitions
+        [ transition(n_address, call_depth_change: 1), advance(1) ]
+      end
+    end
+
+    module ConditionalRelativeBranch
+      def generate_transitions
+        [ transition(n_address, non_local: true), advance(1) ]
+      end
+    end
+
+    module RelativeBranch
+      def generate_transitions
+        [ transition(relative_target_address, non_local: true) ]
+      end
+    end
+
     class Transition
-      attr_reader :next_instruction, :previous_instruction
-    
-      def initialize(previous_instruction, next_instruction, attrs)
+      attr_reader :previous_instruction
+      attr_reader :next_address
+
+      def initialize(previous_instruction, next_address, instruction_store, attrs)
         @previous_instruction = previous_instruction
-        @next_instruction = next_instruction
+        @next_address = next_address
+        @instruction_store = instruction_store
         @attrs = attrs
       end
-      
+
+      def next_instruction
+        @next_instruction ||= @instruction_store.instruction(next_address)
+      end
+
       def non_local?
         @attrs.fetch(:non_local, false)
       end
-      
+
       def call_depth_change
         @attrs.fetch(:call_depth_change, 0)
       end
+
     end
   end
-end
+end