rpicsim 0.4.0 → 1.0.0

data/lib/rpicsim/rspec.rb

@@ -5,7 +5,10 @@ require_relative 'rspec/helpers'
 require_relative 'rspec/sim_diagnostics'
 require_relative 'rspec/be_predicate'
 
-RSpec.configure do |config|
-  config.add_setting :sim_shortcuts, default: :all
-  config.include RPicSim::RSpec::Helpers
+# See {file:RSpecIntegration.md}.
+#
+# @api public
+module RPicSim::RSpec
 end
+
+

data/lib/rpicsim/rspec/helpers.rb

@@ -9,10 +9,12 @@ module RPicSim
     #
     # It provides the {#start_sim} method and includes all the methods from
     # {PersistentExpectations}.
-    # See {file:RSpecIntegration.md} for more information about RPicSim's
-    # integration with RSpec.
+    #
+    # For more information, see {file:RSpecIntegration.md}.
+    #
+    # @api public
     module Helpers
-      include RPicSim::RSpec::PersistentExpectations
+      include PersistentExpectations
 
       # This attribute allows you to type +sim+ in your specs instead of +@sim+ to
       # get access to the {RPicSim::Sim} instance which represents the simulation.
@@ -20,8 +22,8 @@ module RPicSim
       attr_reader :sim
 
       # Starts a new simulation with the specified class, makes it
-      # accessible via the attribute {#sim}, and adds convenience
-      # methods using {#add_shortcuts}.
+      # accessible via the attribute {#sim}, and adds convenient
+      # shortcut methods that can be used in the RSpec example.
       # @param klass [Class] This should be a subclass of {RPicSim::Sim} or at least act like it.
       # @param args A list of arguments to pass on to the the +new+ method of the class.
       #  This should usually be empty unless you have modified your class to take arguments in its
@@ -32,6 +34,7 @@ module RPicSim
         sim.every_step { check_expectations }
       end
 
+      # @api private
       def add_shortcuts
         configuration_value = ::RSpec.configuration.sim_shortcuts
         case configuration_value
@@ -45,3 +48,8 @@ module RPicSim
     end
   end
 end
+
+RSpec.configure do |config|
+  config.add_setting :sim_shortcuts, default: :all
+  config.include RPicSim::RSpec::Helpers
+end

data/lib/rpicsim/rspec/persistent_expectations.rb

@@ -13,6 +13,10 @@ module RPicSim
     #       b << 0
     #       check_expectations  # => raises an error once b has 10 elements
     #     end
+    #
+    # For more information, see {file:PersistentExpectations.md}.
+    #
+    # @api public
     module PersistentExpectations
       # Returns the current set of persistent expectations.
       # The keys are the objects under test and the values are matchers that
@@ -26,9 +30,7 @@ module RPicSim
       # it raises an error.
       def check_expectations
         expectations.each do |subject, matcher|
-          if matcher
-            expect(subject).to matcher
-          end
+          expect(subject).to matcher if matcher
         end
         nil
       end

data/lib/rpicsim/rspec/sim_diagnostics.rb

@@ -1,6 +1,7 @@
 # If an example fails, store some diagnostic information about the state of the
 # simulation so we can print it later.
 
+# @api private
 module RPicSim::RSpec::SimDiagnostics
   def self.store_diagnostics(example, sim)
     if sim.respond_to? :cycle_count

data/lib/rpicsim/sim.rb

@@ -14,10 +14,13 @@ require_relative 'program_file'
 require_relative 'stack_pointer'
 require_relative 'stack_trace'
 
+# @api public
 module RPicSim
   # This class represents a PIC microcontroller simulation.
   # This class keeps track of the state of the simulation and provides methods for
   # running the simulation, reading the state, and changing the state.
+  #
+  # @api public
   class Sim
     # These methods should be called while defining a subclass of {Sim}.
     module ClassDefinitionMethods
@@ -50,7 +53,7 @@ module RPicSim
       end
 
       # Define a symbol.
-      # Normally symbols are loaded by {#use_file} or {#import_symbols}, but you can
+      # Normally symbols are loaded by {#use_file} or {#import_symbols}, but
       # this method allows for adding additional symbols one at a time.
       #
       # See {RPicSim::ProgramFile#def_symbol} for details about the parameters
@@ -118,6 +121,7 @@ module RPicSim
 
       # A {VariableSet} that holds information about all the variables that were defined
       # with {ClassDefinitionMethods#def_var def_var}.
+      # @api private
       attr_reader :variable_set
 
       # The {ProgramFile} object representing the firmware.
@@ -213,12 +217,12 @@ module RPicSim
 
     # Returns a {Variable} object corresponding to WREG.  You can use this
     # to read and write the value of the W register.
-    # @return [Register]
+    # @return [Variable]
     attr_reader :wreg
 
     # Returns a {Variable} object corresponding to the stack pointer register.
     # You can use this to read and write the value of the stack pointer.
-    # @return [Register]
+    # @return [Variable]
     attr_reader :stkptr
 
     # Returns a {StackPointer} object that is like {#stkptr} but it works
@@ -619,6 +623,7 @@ module RPicSim
 
     public
 
+    # @return [String]
     def inspect
       "#<#{self.class}:0x%x, #{pc_description}, stack_pointer = #{stack_pointer.value}>" % object_id
     end

data/lib/rpicsim/stack_pointer.rb

@@ -1,18 +1,23 @@
+# @api public
 module RPicSim
   # Instances of this class represent the call stack pointer in a running
   # simulation.
   # A value of 0 means that the stack is empty, regardless of what device
   # architecture you are simulating.
+  #
+  # @api public
   class StackPointer
     # Initializes the StackPointer object.
     # This be called when the call stack is empty, because this object uses
     # the initial value of stkptr to deduce how it works.
     # @param stkptr The STKPTR register of the simulation.
+    # @api private
     def initialize(stkptr)
       @stkptr = stkptr
       @stkptr_initial_value = @stkptr.value
     end
 
+    # @return [Integer]
     def value
       if @stkptr_initial_value > 0
         raw_value = @stkptr.value
@@ -26,6 +31,7 @@ module RPicSim
       end
     end
 
+    # @param value [Integer]
     def value=(value)
       @stkptr.value = if @stkptr_initial_value > 0
                         if value == 0

data/lib/rpicsim/stack_trace.rb

@@ -1,30 +1,61 @@
+# @api public
 module RPicSim
+  # Represents a stack trace from the simulated firmware.
+  #
+  # @api public
   class StackTrace
+    # Array of {StackTraceEntry} objects.  The last one represents where the
+    # program counter (PC) is.  The entries before the last one approximately
+    # represent addresses of CALL or RCALL instructions that have not yet
+    # returned.
+    #
+    # @return An array of {StackTraceEntry} objects.
     attr_reader :entries
 
+    # @api private
     def initialize(entries = [])
       @entries = entries
     end
 
+    # Prints the stack trace to the specified IO object, preceding
+    # each line with the specified padding string.
+    #
+    # Example usage:
+    #
+    #     stack_trace.output($stdout, '  ')
+    #
+    # @param io An object that behaves like a writable IO object.
+    # @param padding [String]
     def output(io, padding = '')
       @entries.reverse_each do |entry|
         output_entry(entry, io, padding)
       end
     end
 
+    private
+
     def output_entry(entry, io, padding)
       io.puts padding + entry.description
     end
   end
 
+  # Represents an entry in a {StackTrace}.
+  #
+  # @api public
   class StackTraceEntry
-    attr_reader :address, :description
+    # @return [Integer]
+    attr_reader :address
+
+    # @return [String]
+    attr_reader :description
 
+    # @api private
     def initialize(address, description)
       @address = address
       @description = description
     end
 
+    # @return [String]
     def to_s
       description
     end

data/lib/rpicsim/storage/memory_integer.rb

@@ -1,3 +1,4 @@
+# @api private
 module RPicSim::Storage
   # This class and its subclasses represent integers stored in RAM.
   class MemoryInteger

data/lib/rpicsim/symbol_set.rb

@@ -1,6 +1,8 @@
+# @api public
 module RPicSim
   # This class is used internally by {Sim} to manage the symbols from the
-  # simulated firmware's symbol table..
+  # simulated firmware's symbol table.
+  # @api private
   class SymbolSet
     def initialize
       @memory_types = []

data/lib/rpicsim/variable.rb

@@ -1,7 +1,14 @@
+# @api public
 module RPicSim
+  # Instances of this class represents a variable in the memory of the simulated
+  # microcontroller.  This class provides methods for reading, writing, and getting
+  # address of the variable.
+  #
+  # @api public
   class Variable
     # Creates a new Variable object.
     # @param storage The internal storage for the variable.
+    # @api private
     def initialize(storage)
       @storage = storage
     end
@@ -31,18 +38,25 @@ module RPicSim
       @storage.memory_value
     end
 
+    # @return [String]
     def to_s
       @storage.to_s
     end
 
+    # The addresses in memory occupied by this variable.
+    # @return [Array(Integer)]
     def addresses
       @storage.addresses
     end
 
+    # The main (lowest) address of this variable.
+    # @return [Integer]
     def address
       @storage.address
     end
 
+    # The name of the variable.
+    # @return [Symbol]
     def name
       @storage.name
     end

data/lib/rpicsim/variable_set.rb

@@ -1,8 +1,10 @@
 require_relative 'storage/memory_integer'
 require_relative 'variable'
 
+# @api public
 module RPicSim
   # This class is used internally by {Sim} to manage user-defined variables.
+  # @api private
   class VariableSet
     attr_writer :address_increment
 

data/lib/rpicsim/version.rb

@@ -1,3 +1,6 @@
+# @api public
 module RPicSim
-  VERSION = '0.4.0'
+  # The version number of this gem, as a string.
+  # @return [String]
+  VERSION = '1.0.0'
 end

data/lib/rpicsim/xc8_sym_file.rb

@@ -1,14 +1,66 @@
 require 'scanf'
 
+# @api public
 module RPicSim
+  # This class can be used to load an XC8 sym file and get the information about
+  # the symbols in it.  This is useful because the COF file produced by XC8 does
+  # not have enough information to identify what memory space every symbol is
+  # in.
+  #
+  # Example usage:
+  #
+  #     class MySim < RPicSim::Sim
+  #       use_device 'PIC18F25K50'
+  #       use_file DistDir + 'TestXC8.hex'
+  #       import_symbols RPicSim::Xc8SymFile.new(DistDir + 'TestXC8.sym')
+  #
+  #       # ...
+  #     end
+  #
+  # @api public
   class Xc8SymFile
+    # Returns all the symbols.
+    # The return value is a hash where the keys are the names of the symbols
+    # (represented as Ruby symbols) and the values are the addresses of the symbols.
+    #
+    # @return [Hash]
     attr_reader :symbols
+
+    # Returns all the symbols in RAM.
+    # The return value is a hash where the keys are the names of the symbols
+    # (represented as Ruby symbols) and the values are the addresses of the symbols.
+    #
+    # @return [Hash]
     attr_reader :symbols_in_ram
+
+    # Returns all the symbols in EEPROM.
+    # The return value is a hash where the keys are the names of the symbols
+    # (represented as Ruby symbols) and the values are the addresses of the symbols.
+    #
+    # @return [Hash]
     attr_reader :symbols_in_eeprom
+
+    # Returns all the symbols in program memory.
+    # The return value is a hash where the keys are the names of the symbols
+    # (represented as Ruby symbols) and the values are the addresses of the symbols.
+    #
+    # @return [Hash]
     attr_reader :symbols_in_program_memory
 
+    # @api private
     attr_reader :symbol_raw_data
 
+    # Creates a new instance of this class containing information from the
+    # specified file.
+    #
+    # @param filename [String]
+    # @param opts [Hash] Specified additional options.  The options are:
+    #   * +:user_ram_sections+: Array of strings of section names that
+    #     should be considered to be in RAM.
+    #   * +:user_program_memory_sections+: Array of strings of section names that
+    #     should be considered to be in program memory.
+    #   * +:user_eeprom_sections+: Array of strings of section names that
+    #     should be considered to be in EEPROM.
     def initialize(filename, opts = {})
       @symbols = {}
       @symbols_in_ram = {}
@@ -21,7 +73,10 @@ module RPicSim
       @sections_in_code = %w{CODE CONST IDLOC MEDIUMCONST SMALLCONST}
       @sections_in_eeprom = %w{EEDATA}
 
-      allowed_keys = [:custom_ram_sections,
+      allowed_keys = [:user_ram_sections,
+                      :user_program_memory_sections,
+                      :user_eeprom_sections,
+                      :custom_ram_sections,
                       :custom_code_sections,
                       :custom_eeprom_sections]
       invalid_keys = opts.keys - allowed_keys
@@ -29,17 +84,14 @@ module RPicSim
         raise "Invalid options: #{invalid_keys.inspect}"
       end
 
-      if opts[:custom_ram_sections]
-        @sections_in_ram += opts[:custom_ram_sections]
-      end
+      @sections_in_ram += opts.fetch(:user_ram_sections, [])
+      @sections_in_code += opts.fetch(:user_program_memory_sections, [])
+      @sections_in_eeprom += opts.fetch(:user_eeprom_sections, [])
 
-      if opts[:custom_code_sections]
-        @sections_in_code += opts[:custom_code_sections]
-      end
-
-      if opts[:custom_eeprom_sections]
-        @sections_in_eeprom += opts[:custom_eeprom_sections]
-      end
+      # Legacy options introduced in 0.4.0, but deprecated now.
+      @sections_in_ram += opts.fetch(:custom_ram_sections, [])
+      @sections_in_code += opts.fetch(:custom_code_sections, [])
+      @sections_in_eeprom += opts.fetch(:custom_eeprom_sections, [])
 
       read_data
       sort_data

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rpicsim
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Pololu
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2014-07-30 00:00:00.000000000 Z
+date: 2014-09-17 00:00:00.000000000 Z
 dependencies: []
 description:
 email:
@@ -17,10 +17,8 @@ extensions: []
 extra_rdoc_files: []
 files:
 - lib/rpicsim.rb
-- lib/rpicsim/call_stack_info.rb
 - lib/rpicsim/composite_memory.rb
 - lib/rpicsim/flaws.rb
-- lib/rpicsim/instruction.rb
 - lib/rpicsim/label.rb
 - lib/rpicsim/memory.rb
 - lib/rpicsim/memory_watcher.rb
@@ -29,7 +27,6 @@ files:
 - lib/rpicsim/program_counter.rb
 - lib/rpicsim/program_file.rb
 - lib/rpicsim/rspec.rb
-- lib/rpicsim/search.rb
 - lib/rpicsim/sim.rb
 - lib/rpicsim/stack_pointer.rb
 - lib/rpicsim/stack_trace.rb
@@ -40,7 +37,6 @@ files:
 - lib/rpicsim/xc8_sym_file.rb
 - lib/rpicsim/mplab/mplab_assembly.rb
 - lib/rpicsim/mplab/mplab_device_info.rb
-- lib/rpicsim/mplab/mplab_disassembler.rb
 - lib/rpicsim/mplab/mplab_instruction.rb
 - lib/rpicsim/mplab/mplab_loader.rb
 - lib/rpicsim/mplab/mplab_memory.rb
@@ -78,7 +74,6 @@ files:
 - docs/Memories.md
 - docs/PersistentExpectations.md
 - docs/Pins.md
-- docs/PreventingCallStackOverflow.md
 - docs/QuickStartGuide.md
 - docs/RamWatcher.md
 - docs/RSpecIntegration.md