rpicsim 0.4.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a7dd67ae71f9052d9fa174cace952aa468a0001d
-  data.tar.gz: 72a07a6240931d85054651627a017677924d1a9e
+  metadata.gz: 5b6af21f7563390039da12c8b89f5680a02cb986
+  data.tar.gz: 1b76b192dcbea43027d5279cebc2f4949c42377d
 SHA512:
-  metadata.gz: 94d406a34b8dc47900a487a306a3071ec2a441b039e6696c4f3c422cb2d92c27c0b200d13ea80e537df9b73dab4657db9edcf102d94fa3a7b516d39aa5128c55
-  data.tar.gz: 7c332af37e3563c1b12249c1fa690ca07f297dbb56175403b7b2d3c333fc3fdddd95825919ce40cafe90c1f1eb533a11842e61276a0b5652d765d26431637d73
+  metadata.gz: ac3c2f02ad9039fc16940f436cc35bffe710c028e084f52f23c4b4c81d4d4ead4b982af6032529b4259e2ef39e21d130fecead04486d70b3cdd7cbdc95ee936f
+  data.tar.gz: fedd8d6089a28a1e7395beb446e7a7467778c69c696e3a6e7fffa5eb2910cf15cf370b51f268e49e379b8f33116c88197e1b571ac7778b58b6495c28615c4ff7

data/.yardopts

@@ -1,6 +1,9 @@
+lib/rpicsim.rb
+lib/rpicsim/mplab.rb
 lib/rpicsim/**/*.rb
 --readme Introduction.md
 --load docs/plugin/plugin.rb
+--api public
 -
 docs/Manual.md
   docs/ChangeLog.md
@@ -18,7 +21,6 @@ docs/Manual.md
   docs/Variables.md
   docs/Memories.md
   docs/RamWatcher.md
-  docs/PreventingCallStackOverflow.md
 
   docs/IntroductionToRSpec.md
   docs/UnitTesting.md

data/Introduction.md

@@ -44,14 +44,12 @@ RPicSim has features that allow you to:
 * Monitor all writes to RAM.
 * Run assertions at every step of a simulation.
 
-For some applications, RPicSim can also analyze the firmware and verify that the call stack will never overflow.
-
 RPicSim is distributed as a Ruby gem named `rpicsim`.  To install RPicSim, run:
 
     jgem install rpicsim
 
 
-RPicSim has been tested with MPLAB X v1.85, v1.90, v1.95, v2.00, v2.05, and v2.10.
+RPicSim has been tested with MPLAB X v1.85, v1.90, v1.95, v2.00, v2.05, v2.10, v2.15, and v2.20.
 However, it uses a lot of undocumented and internal features of the Microchip Java libraries, so it will probably need to be updated as new versions of MPLAB X are released.
 
 RPicSim is not intended to replace formal specifications, code reviews, and rigorous testing of your firmware on actual hardware.

data/README.md

@@ -46,14 +46,12 @@ RPicSim has features that allow you to:
 * Monitor all writes to RAM.
 * Run assertions at every step of a simulation.
 
-For some applications, RPicSim can also analyze the firmware and verify that the call stack will never overflow.
-
 RPicSim is distributed as a Ruby gem named `rpicsim`.  To install RPicSim, run:
 
     jgem install rpicsim
 
 
-RPicSim has been tested with MPLAB X v1.85, v1.90, v1.95, v2.00, v2.05, and v2.10.
+RPicSim has been tested with MPLAB X v1.85, v1.90, v1.95, v2.00, v2.05, v2.10, v2.15, and v2.20.
 However, it uses a lot of undocumented and internal features of the Microchip Java libraries, so it will probably need to be updated as new versions of MPLAB X are released.
 
 RPicSim is not intended to replace formal specifications, code reviews, and rigorous testing of your firmware on actual hardware.

data/docs/ChangeLog.md

@@ -1,6 +1,17 @@
 Change log
 ====
 
+1.0.0
+----
+Released on 2014-09-17.
+
+- Major improvements to the documentation.  Mainly, the public API of RPicSim has been defined, and everything not in the public API is now hidden from the documentation.  Doing this allows us to follow [Semantic Versioning](http://semver.org/spec/v2.0.0.html) from now on.
+- MemoryWatcher: Adds WREG and BSR to the default list of registers to ignore.
+- Removed all disassembly and static analysis features, since they could be better implemented in a different gem that doesn't depend on any Microchip code:
+    - Removed RPicSim::ProgramFile#instruction
+    - Removed RPicSim::CallStackInfo
+    - Removed RPicSim::Instruction
+
 0.4.0
 ----
 Released on 2014-07-30.
@@ -15,6 +26,8 @@ Released on 2014-07-30.
 - Adds the {RPicSim::Xc8SymFile} class, which can load symbols from a SYM file produced by the XC8 compiler and then be passed to {RPicSim::Sim::ClassDefinitionMethods#import_symbols import_symbols}.  This was necessary because the COF files produced by XC8 are difficult to interpret and do not always allow us to tell what memory space a given symbol is for.
 - {RPicSim::Sim::ClassMethods#label #label} and {RPicSim::Sim::ClassMethods#labels #labels} methods are now available on both instances of a simulation class or on a simulation class itself.
 
+MPLAB X v2.15 and v2.20 were released after RPicSim 0.4.0, but the changes in those versions of MPLAB X were minor enough that RPicSim 0.4.0 should work with them.
+
 0.3.0
 ----
 Released on 2014-06-20.

data/docs/KnownIssues.md

@@ -112,11 +112,11 @@ Pins report the wrong output state if TRISx is cleared again
 ----
 _Type: MPLAB X bug_
 
-_MPLAB X versions affected: all tested versions_
+_MPLAB X versions affected: 1.85 through 2.10_
 
 Even if you set up the pin properly (working around all the issues above) and get {RPicSim::Pin#driving_high?} to return true, a `bcf` instruction on the pin's TRISx bit (or probably any write to the TRISx register) will cause the pin to start reporting the wrong output state.
 
-This issue is tested in `spec/integration/pin_spec.rb`.
+This issue is tested in `spec/integration/pin_spec.rb`, and was fixed in MPLAB X v2.15.
 
 
 RAM watcher is useless because all of RAM seems to change on every step

data/docs/Manual.md

@@ -20,7 +20,6 @@ This is the table of contents for the RPicSim manual.
     * {file:Variables.md}
     * {file:Memories.md}
     * {file:RamWatcher.md RAM watcher}
-    * {file:PreventingCallStackOverflow.md Preventing call stack overflow}
 * Testing firmware with RPicSim and RSpec
     * {file:IntroductionToRSpec.md Introduction to RSpec}
     * {file:UnitTesting.md Unit testing}

data/docs/RSpecIntegration.md

@@ -13,7 +13,30 @@ To enable the RSpec integration, simply put this line in your `spec_helper.rb`:
     !!!ruby
     require 'rpicsim/rspec'
 
-The features that this gives you are documented below.
+That gives you all the features that are documented below.
+
+### Fine-grained configuration
+
+Alternatively, if you just want a subset of the features described here, you can use any combination of the snippets below:
+
+    # Persistent expectations that can be stored and checked later
+    require 'rpicsim/rspec/persistent_expectations'
+    RSpec.configure { |c| c.include RPicSim::RSpec::PersistentExpectations }
+
+<!-- separate -->
+
+    # Helper methods, including persistent expectations
+    require 'rpicsim/rspec/helpers'
+
+<!-- separate -->
+
+    # Show debug info from sim if a spec fails
+    require 'rpicsim/rspec/sim_diagnostics'
+
+<!-- separate -->
+
+    # Better error messages for RSpec 2.x
+    require 'rpicsim/rspec/be_predicate'
 
 
 Helper methods

data/docs/SupportedMPLABXVersions.md

@@ -8,6 +8,8 @@ RPicSim uses code in MPLAB X to actually perform the PIC simulation.  Therefore,
 - 2.00
 - 2.05
 - 2.10
+- 2.15
+- 2.20
 
 The different versions of MPLAB X have different problems that affect the simulation.  For more information, see the {file:KnownIssues.md Known issues page}.
 

data/lib/rpicsim.rb

@@ -1,4 +1,9 @@
 require_relative 'rpicsim/version'
 require_relative 'rpicsim/sim'
-require_relative 'rpicsim/call_stack_info'
 require_relative 'rpicsim/xc8_sym_file'
+
+# Top-level module for the RPicSim gem.
+#
+# @api public
+module RPicSim
+end

data/lib/rpicsim/composite_memory.rb

@@ -1,8 +1,11 @@
+# @api public
 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.
+  #
+  # @api private
   class CompositeMemory
     # Creates a new instance.
     # The memory objects given must support the following methods:

data/lib/rpicsim/flaws.rb

@@ -1,11 +1,18 @@
+# @api public
 module RPicSim
+  # This module stores knowledge about flaw in RPicSim, usually due to bugs or
+  # limitation of the MPLAB X classes we are using.  See {file:KnownIssues.md}
+  # for more details.
+  #
+  # @api public
   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.
+    # Represents a flaw in RPicSim, usually dues to bugs in 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.
+      # @api private
       def initialize(name)
         @versions = {}
       end
@@ -15,7 +22,7 @@ module RPicSim
       # 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".
+      # @param version [String] A version of MPLAB X, e.g. +'1.95'+.
       # @return effect
       def effect(version)
         if @versions.key? version
@@ -26,6 +33,7 @@ module RPicSim
       end
 
       # Records the effect this flaw has on a given version of MPLAB X.
+      # @api private
       def affects_version(version, effect)
         @versions[version] = effect
       end
@@ -33,21 +41,37 @@ module RPicSim
       # 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.
+      # @api private
       def probably_affects_other_versions(effect)
         @probable_affect_for_other_versions = effect
       end
     end
 
     @flaw_hash = {}
+
+    # Returns the {Flaw} with the specified name.
+    # @param name [Symbol] The name of the flaw.  The names are listed in +flaws.rb+.
+    # @return [Flaw]
     def self.[](name)
       @flaw_hash[name].effect Mplab.version
     end
 
+    # @api private
     def self.add(name)
       @flaw_hash[name] = flaw = Flaw.new(name)
       yield flaw
     end
 
+    add(:writing_tris_affects_output) 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', true
+      flaw.affects_version '2.10', true
+      flaw.probably_affects_other_versions false
+    end
+
     add(:fr_memory_attach_useless) do |flaw|
       flaw.affects_version '1.85', false
       flaw.affects_version '1.90', false

data/lib/rpicsim/label.rb

@@ -1,5 +1,7 @@
+# @api public
 module RPicSim
   # A very simple class that represents a label in firmware.
+  # @api public
   class Label
     # The name of the label from the firmware.
     # @return (Symbol)
@@ -10,17 +12,22 @@ module RPicSim
     attr_reader :address
 
     # Makes a new label with the specified name and address.
+    # @api private
     def initialize(name, address)
       @name = name
       @address = address
     end
 
     # Returns the address of the label.
+    #
+    # @return [Integer]
     def to_i
       address
     end
 
     # Returns a nice string representation of the label.
+    #
+    # @return [String]
     def to_s
       '<Label %s address=0x%x>' % [name, address]
     end

data/lib/rpicsim/memory.rb

@@ -1,3 +1,4 @@
+# @api public
 module RPicSim
   # This object allows read and write access to the data currently
   # stored in a memory space of the simulated device.
@@ -20,8 +21,11 @@ module RPicSim
   # +read_word+ and +write_word+.
   #
   # For more information, see {file:Memories.md}.
+  #
+  # @api public
   class Memory
     # @param mplab_memory [Mplab::Memory]
+    # @api private
     def initialize(mplab_memory)
       @mplab_memory = mplab_memory
     end

data/lib/rpicsim/memory_watcher.rb

@@ -1,5 +1,6 @@
 require 'set'
 
+# @api public
 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
@@ -9,9 +10,15 @@ module RPicSim
   # 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}.
+  #
+  # @api public
   class MemoryWatcher
+    # Allows you to read or write the list of variable names whose changes will
+    # be ignored.  By default, this includes registers like WREG and STATUS that
+    # change a lot.
+    #
+    # @return [Array(Symbol)]
     attr_accessor :var_names_ignored
-    attr_accessor :var_names_ignored_on_first_step
 
     # Creates a new instance.
     # @param sim [Sim]
@@ -61,6 +68,8 @@ module RPicSim
       @vars_written.clear
     end
 
+    private
+
     def handle_change(address_ranges)
       addresses = address_ranges.flat_map(&:to_a)
       vars = addresses.map { |a| @vars_by_address[a] || a }
@@ -71,8 +80,6 @@ module RPicSim
       @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
@@ -84,7 +91,7 @@ module RPicSim
       # 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]
+      [:PCL, :PCLATH, :WREG, :STATUS, :BSR]
     end
   end
 end

data/lib/rpicsim/mplab.rb

@@ -1,5 +1,6 @@
 require_relative 'mplab/mplab_loader'
 
+# @api private
 module RPicSim::Mplab
   MplabLoader.instance.load
 

data/lib/rpicsim/mplab/mplab_assembly.rb

@@ -1,6 +1,5 @@
 require_relative 'mplab_device_info'
 require_relative 'mplab_simulator'
-require_relative 'mplab_disassembler'
 
 module RPicSim::Mplab
   # This class wraps objects belonging to the abstract Java class

data/lib/rpicsim/pin.rb

@@ -1,10 +1,14 @@
+# @api public
 module RPicSim
   # This class represents an external pin of the simulated device.
   # It provides methods for reading the pin's output value and setting
   # its input value.
+  #
+  # @api public
   class Pin
     # Initializes a new Pin object to wrap the given MplabPin.
     # @param mplab_pin [Mplab::MplabPin]
+    # @api private
     def initialize(mplab_pin)
       raise ArgumentError, 'mplab_pin is nil' if mplab_pin.nil?
       @mplab_pin = mplab_pin
@@ -46,14 +50,17 @@ module RPicSim
 
     # Returns an array of all the pin's names from the datasheet, like
     # "RA4" or "TX".
+    # @return [String]
     def names
       @mplab_pin.names
     end
 
+    # @return [String]
     def to_s
       @mplab_pin.name
     end
 
+    # @return [String]
     def inspect
       '#<%s %s>' % [self.class, to_s]
     end

data/lib/rpicsim/program_counter.rb

@@ -1,16 +1,20 @@
+# @api public
 module RPicSim
   # Instances of this class represent the program counter in a
   # simulated microcontroller.
+  # @api public
   class ProgramCounter
     # @param processor [Mplab::Processor]
     def initialize(processor)
       @processor = processor
     end
 
+    # @return [Integer]
     def value
       @processor.get_pc
     end
 
+    # @param val [Integer]
     def value=(val)
       @processor.set_pc(val)
     end

data/lib/rpicsim/program_file.rb

@@ -1,19 +1,27 @@
 require_relative 'mplab'
 require_relative 'label'
-require_relative 'instruction'
 require_relative 'symbol_set'
 
 # TODO: When symbols have the same address, think about how to choose the more
 # interesting one in a stack trace (fewer underscores?)
 
+# @api public
 module RPicSim
   # Represents a PIC program file (e.g. COF or HEX).
   # Keeps track of all the symbols loaded from that file and also allows you
   # to add symbols in various ways.
+  #
+  # @api public
   class ProgramFile
+    # @return [String]
     attr_reader :filename
+
+    # The name of the device the file is for (e.g. "PIC10F322").
+    #
+    # @return [String]
     attr_reader :device
 
+    # @api private
     attr_reader :address_increment
 
     # @param filename [String] The path to the program file.
@@ -28,8 +36,6 @@ module RPicSim
       @assembly.load_file(filename)
       @address_increment = @assembly.device_info.code_address_increment
 
-      @instructions = []
-
       @labels = {}
 
       @symbol_set = SymbolSet.new
@@ -90,6 +96,8 @@ module RPicSim
     #
     # Warning: This is a persistent hash that will automatically be updated when
     # new symbols are defined.
+    #
+    # @return [Hash]
     def symbols
       @symbol_set.symbols
     end
@@ -100,6 +108,8 @@ module RPicSim
     #
     # Warning: This is a persistent hash that will automatically be updated when
     # new symbols are defined.
+    #
+    # @return [Hash]
     def symbols_in_ram
       @symbol_set.symbols_in_memory(:ram)
     end
@@ -110,6 +120,8 @@ module RPicSim
     #
     # Warning: This is a persistent hash that will automatically be updated when
     # new symbols are defined.
+    #
+    # @return [Hash]
     def symbols_in_program_memory
       @symbol_set.symbols_in_memory(:program_memory)
     end
@@ -120,17 +132,21 @@ module RPicSim
     #
     # Warning: This is a persistent hash that will automatically be updated when
     # new symbols are defined.
+    #
+    # @return [Hash]
     def symbols_in_eeprom
       @symbol_set.symbols_in_memory(:eeprom)
     end
 
     # Returns a hash associating program memory label names (as symbols) to their addresses.
-    # @return (Hash)
+    #
+    # @return [Hash]
     attr_reader :labels
 
     # Returns a {Label} object if a program label by that name is found.
     # The name is specified in the code that defined the label.  If you are using a C compiler,
     # you will probably need to prefix the name with an underscore.
+    #
     # @return [Label]
     def label(name)
       name = name.to_sym
@@ -159,14 +175,6 @@ module RPicSim
       desc
     end
 
-    # Gets an {Instruction} object representing the PIC instruction at the given
-    # address in program memory.
-    # @param address [Integer]
-    # @return [Instruction]
-    def instruction(address)
-      @instructions[address] ||= make_instruction(address)
-    end
-
     private
 
     def message_for_label_not_found(name)
@@ -181,10 +189,5 @@ module RPicSim
       end
       message
     end
-
-    def make_instruction(address)
-      mplab_instruction = @assembly.disassembler.disassemble(address)
-      Instruction.new(mplab_instruction, address, @address_increment, self)
-    end
   end
 end