rpicsim 0.1.0

data/docs/Labels.md

@@ -0,0 +1,39 @@
+Labels
+====
+
+RPicSim automatically processes the symbol table in your firmware's COF file.
+Any symbol in program space is called a _label_ and RPicSim stores a {RPicSim::Label} object to represent it.
+
+For an assembly program, RPicSim labels correspond to any assembly label defined in code space.
+These will usually correspond to subroutines and goto targets but could also be variables stored in flash.
+In firmware assembled by MPASM, all labels are exported publicly by default, so they will all be available to RPicSim.
+
+For a C program, RPicSim labels usually correspond to functions.
+
+Getting a Label object
+---
+
+To get a Label object, call {RPicSim::Sim#label} and pass it the name of the label as the first argument:
+
+    !!!ruby
+    sim.label(:loopStart)  # => returns a Label object
+
+C compilers will generally put an underscore at the beginning of any labels they generate.  For example, to get the address of a C function named `foo`, you might have to access a label named `_foo` using code like this:
+
+    !!!ruby
+    sim.label(:_foo)
+
+If RPicSim cannot find the label you want to use, you might troubleshoot it by printing out a list of all the known labels:
+
+    !!!ruby
+    p sim.class.program_file.labels.keys
+
+
+Using a Label object
+----
+
+You can basically only do three things with a Label object:
+
+* Get its name by calling {RPicSim::Label#name}.
+* Get its address by calling {RPicSim::Label#address}.
+* Pass it or its name as an argument to some of the methods for {file:Running.md running} the simulation.

data/docs/MakingTestsRunFaster.md

@@ -0,0 +1,29 @@
+Making tests run faster
+====
+
+In general, an RPicSim simulation runs thousands of times slower than the device it simulates.
+Simulating how your firmware behaves over time spans longer than a few milliseconds can be very slow.
+This page contains some tips for making your tests run faster.
+
+First of all, {file:UnitTesting.md unit tests} are generally very fast, so try to use unit tests as much as possible.
+
+Consider {file:Stubbing.md stubbing} routines in your firmware that take a long time to run if the exact behavior of those routines is not important for the test.  This is explained on the {file:Stubbing.md Stubbing page}.
+
+If your tests run slowly because the firmware is waiting for a simulated timer to advance, you might use techniques similar to stubbing in order to advance the timer by hundreds of counts at once without having simulate hundreds of processor cycles.
+
+For the specs that are slow, use RSpec metadata to mark them as slow.
+This allows you to prevent those tests from running during normal development.
+For example, you could mark an individual example as slow like this:
+
+    !!!ruby
+    it "can run for a second", slow: true do
+      run_cycles 4_000_000
+    end
+
+You can also mark an entire context or describe block as slow using the same syntax.
+To exclude the slow tests, run `rspec` with this command:
+
+    !!!plain
+    rspec -t '~slow'
+
+There is nothing special about the word "slow" in the example above; you can make up your own metadata tags to fit your application.

data/docs/Manual.md

@@ -0,0 +1,38 @@
+RPicSim manual
+====
+
+This is the table of contents for the RPicSim manual.
+
+* Overview
+    * {file:Introduction.md}
+    * {file:ChangeLog.md Change log}
+    * {file:QuickStartGuide.md Quick-start guide}
+    * {file:SupportedDevices.md Supported devices}
+    * {file:SupportedCompilers.md Supported compilers}
+    * {file:SupportedMPLABXVersions.md Supported MPLAB X versions}
+    * {file:SupportedOperatingSystems.md Supported operating systems}
+* Basic usage
+    * {file:IntroductionToRuby.md Introduction to Ruby}
+    * {file:DefiningSimulationClass.md Defining your simulation class}
+    * {file:Pins.md}
+    * {file:Labels.md}
+    * {file:Running.md Running the simulation}
+    * {file:Variables.md}
+    * {file:SFRs.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}
+    * {file:IntegrationTesting.md Integration testing}
+    * {file:RSpecIntegration.md RSpec integration}
+    * {file:PersistentExpectations.md Persistent expectations}
+* Tips
+    * {file:Stubbing.md}
+    * {file:MakingTestsRunFaster.md Making tests run faster}
+    * {file:Debugging.md}
+* More about RPicSim
+    * {file:HowMPLABXIsFound.md How MPLAB X is Found}
+    * {file:KnownIssues.md Known issues}
+    * {file:DesignDecisions.md Design decisions}
+    * {file:Contributing.md}

data/docs/PersistentExpectations.md

@@ -0,0 +1,100 @@
+Persistent expectations
+====
+
+An RSpec example usually consists of some code to set up the situation being tested, and some code called an _expectation_ that defines the expected outcome.
+As discussed in the {file:Pins.md Pins page}, to write an expectation that the main output pin is driving high you could write:
+
+    !!!ruby
+    expect(main_output).to be_driving_high
+
+This is fine, but it is not a great way to test firmware because (unless you put it in a loop or method) it only runs once, at one particular cycle of the simulation.  It will not catch any accidental glitches on the main output pin that occur at a later time.
+
+RPicSim helps to address this by adding a new feature to RSpec examples called "persistent expectations".
+Persistent expectations are implemented in the module {RPicSim::RSpec::PersistentExpectations}, which is part of RPicSim's {file:RSpecIntegration.md RSpec integration}.
+
+Usage
+----
+
+To set a persistent expectation, call the {RPicSim::RSpec::PersistentExpectations#expecting expecting} method inside an RSpec example or a before/after hook:
+
+    !!!ruby
+    expecting main_output => be_driving_high
+
+The argument to `expecting` is a hash with the objects being tested as the keys, and the matchers they are being tested against as the values.  You can specify multiple persistent expectations on different objects:
+
+    !!!ruby
+    expecting main_output => be_driving_high, error_output => be_drving_low
+
+You can not specify multiple persistent expectations that apply to the same object.  If you specify a persistent expectation for an object that already had one, the latest one you specify will override the previous one.
+
+To remove a persistent expectation, specify a matcher of `nil`:
+
+    !!!ruby
+    expecting main_output => nil
+
+The persistent expectations will not be checked right away when they are added but they will be checked after every step of the simulation.
+You can also check them at any time by calling `check_expecations` inside your RSPec example.
+
+Persistent expectations, when combined with RSpec's `satisfy` matcher, are very powerful.  If `counter` is a {RPicSim::Variable variable} in your simulation, you could use this code to ensure that `counter` never goes above 120:
+
+    !!!ruby
+    expecting counter => satisfy { |c| c.value <= 120 }
+
+Persistent expectations are implemented in a straightforward way: the expectations are stored in a hash that is an instance variable of the RSpec example, and the expectations are checked after every step via a hook that is registered with {RPicSim::Sim#every_step} when the simulation is started.
+
+Example
+----
+
+The following RSpec example tests that the main output pin is held low (after giving the device some time to start up), but then it goes high after the main input goes high:
+
+    !!!ruby
+    it "mirrors the main input onto the main output pin" do
+      run_cycles 120    # Give the device time to start up.
+
+      expecting main_output => be_driving_low
+      run_cycles 800
+
+      main_input.set true
+
+      # Turn off the persistent expectation temporarily to give the device
+      # time to detect the change in the input.
+      expecting main_output => nil
+      run_cycles 200
+
+      expecting main_output => be_driving_high
+      run_cycles 800
+    end
+
+In the above example, we removed the persistent expectation on `main_output` temporarily because the device was in a transitionary period and we didn't know exactly when the transition would happen.
+We chose to stop monitoring the pin for the duration of the transition and then start monitoring it later, at which point we expect the pin to be in its new state.
+
+If you need to repeat this patten many times in your tests, you might consider adding a method in `spec_helper.rb` to help you do it:
+
+    !!!ruby
+    def transition(opts={})
+      opts = opts.dup
+      cycles = opts.delete(:cycles) || 50
+      opts.keys.each { |k| expectations.delete k }
+      run_cycles cycles
+      expectations.merge! opts
+      check_expectations
+    end
+
+Then the test above could become:
+
+    !!!ruby
+    it "mirrors the main input onto the main output pin" do
+      run_cycles 120    # Give the device time to start up.
+
+      expecting main_output => be_driving_low
+      run_cycles 800
+
+      main_input.set true
+
+      transition main_output => be_driving_high
+      run_cycles 800
+    end
+
+The `transition` method above does not check anything about the main output during the transition time, so unfortunately it might miss any glitches that happen during that time.
+Also, it is not very general.
+For these reasons, it has not been integrated into the RPicSim code and you will need to copy it to your `spec_helper.rb` file yourself if you want to use it.

data/docs/Pins.md

@@ -0,0 +1,143 @@
+Pins
+====
+
+The only way a PIC microcontroller can have an effect on the world is through its pins, so pins are an important part of a PIC simulation.
+RPicSim exposes the modeling of pins that the MPLAB X simulator provides.
+Each {RPicSim::Sim} simulation object contains a collection of {RPicSim::Pin} objects, one for each external pin of the device.
+Using a Pin object, you can detect whether the pin is an input or an output.
+If it is an output, you can detect whether the output is driving high or driving low.
+If it is an input, you can set the simulated value of the input.
+
+Getting a Pin object
+----
+
+The {RPicSim::Sim#pin} method can be called on your simulation object to retrieve a {RPicSim::Pin} object.
+If you are using RPicSim's {file:RSpecIntegration.md RSpec integration}, the `pin` method inside an example automatically redirects to the simulation object so you can use it easily like this:
+
+    !!!ruby
+    it "works" do
+      pin(:RA1)  # => returns a Pin object
+    end
+
+The first argument of {RPicSim::Sim#pin} should be the name of the pin as a symbol.
+The allowed names come from the MPLAB X code, but they should match the names given in the PIC datasheet.
+For example, the PIC10F322 pin RA1 can be referred to by many names, including `:RA1`, `:PWM2`, `:AN1`, and `:NCO1CLK`.
+
+RPicSim does not model the GND and VDD pins.
+
+Pin aliases
+----
+
+To make your tests readable and protect against future schematic changes, you should try to refer to pins by an application-specific name like "main output" instead of a datasheet name like RA1.  RPicSim provides a feature to help you do this called a _pin alias_.
+
+Within your {file:DefiningSimulationClass.md simulation class definition}, call {RPicSim::Sim::ClassDefinitionMethods#def_pin def_pin} to define your pins.
+For example:
+
+    !!!ruby
+    class MySim < RRicSim::Sim
+      #...
+      
+      def_pin :main_output, :RA1
+      
+    end
+
+This makes `:main_output` be an alias for `:RA1`.  You can now access the Pin object by passing `:main_output` as the argument to {RPicSim::Sim#pin}:
+
+    !!!ruby
+    pin(:main_output)
+    
+Defining a pin alias also adds a "shortcut" method by the same name.  This means that you can access the pin like this:
+
+    !!!ruby
+    sim.main_output
+    
+The shortcuts are also available in RSpec thanks to RPicsim's {file:RSpecIntegration.md RSpec integration}, so you can simply write `main_output` in any of your RSpec examples:
+
+    !!!ruby
+    it "drives the main output high" do
+      expect(main_output).to be_driving_high
+    end
+    
+Note that since the shortcuts are available in many places, your pin names might conflict with names defined in other places.
+
+
+Pin methods
+----
+
+Once you have a Pin object, you can call any of the methods listed in {RPicSim::Pin} on it.  These methods allow you to ask about the state of the Pin and to set the simulated input value of an input pin.
+
+
+Issues
+----
+
+The modelling of Pins provided by the MPLAB X simulator is fairly new and there are still some bugs in it.
+For example, you might need to clear the ANSELx bit of a pin in your firmware before trying to set its output value, or else the simulator will mistakenly think your pin is driving low.
+For more information, see the {file:KnownIssues.md Known issues page}.
+
+
+PinMirror example
+----
+
+This section contains a simple example showing how to apply the information above and use {RPicSim::Pin} objects.
+
+Here is a minimal MPASM assembly program for the PIC10F322 that continuously reads the value from an input pin (RA0) and copies it to an output pin (RA1):
+
+    !!!plain
+      #include p10F322.inc
+      __config(0x3E06)
+      code 0
+      clrf  ANSELA
+      bcf   TRISA, 1
+    loopStart
+      btfss PORTA, 0
+      bcf   LATA, 1
+      btfsc PORTA, 0
+      bsf   LATA, 1
+      goto  loopStart
+      end
+
+In `spec/spec_helper.rb`, we make a simulation class that points to the compiled COF file and defines some pin aliases:
+
+    !!!ruby
+    require 'rpicsim/rspec'
+    
+    class PinMirror < RPicSim::Pic
+      device_is "PIC10F322"
+      filename_is File.dirname(__FILE__) + "../firmware/dist/firmware.cof"
+        
+      def_pin :main_input, :RA0
+      def_pin :main_output, :RA1
+    end
+    
+In `spec/pin_mirror_spec.rb`, we write a simple test that changes the input and makes sure that the output changes accordingly:
+
+    !!!ruby
+    require_relative 'spec_helper'
+
+    describe "PinMirror" do
+      before do
+        start_sim PinMirror
+      end
+
+      it "continuously mirrors" do
+        main_input.set false
+        run_cycles 10
+        expect(main_output).to be_driving_low
+
+        run_cycles 10
+        expect(main_output).to be_driving_low
+
+        main_input.set true
+        run_cycles 10
+        expect(main_output).to be_driving_high
+
+        run_cycles 10
+        expect(main_output).to be_driving_high
+        
+        main_input.set false
+        run_cycles 10
+        expect(main_output).to be_driving_low
+      end
+    end
+
+The calls to {RPicSim::Sim#run_cycles} are needed to give the simulated device enough time to react to the change on its input.

data/docs/PreventingCallStackOverflow.md

@@ -0,0 +1,94 @@
+Preventing call stack overflow
+====
+
+PIC microcontrollers feature a stack implemented in hardware that keeps track of return addresses for subroutine calls.
+Every time a `CALL` instruction is executed, the return address is pushed onto the stack.
+Every time a `RETURN` or similar instruction is executed, the return address is popped off of the stack.
+The PIC datasheets tend to refer to this as the "stack", but in RPicSim it is known as the _call stack_ in order to make it clear that this is the stack that relates to the `CALL` instruction and it is different from any kind of stack a C compiler might place in RAM for local variables.
+
+The call stack has a limited depth that depends on the device you are using.
+If your program has too many levels of nested subroutines then the call stack could overflow.
+Depending on the device, a call stack overflow could cause a reset or incorrect program execution.
+Therefore, it is important to avoid a call stack overflow.
+
+RPicSim can trace all the possible paths of execution for a PIC program in order to calculate what the maximum possible call stack depth is.
+You can easily add this to your RSpec tests.
+Here is an example:
+
+    !!!ruby
+    describe "call stack" do
+      subject(:call_stack_info) do
+        RPicSim::CallStackInfo.hash_from_program_file(MySim.program_file, [0, 4])
+      end
+
+      specify "mainline code uses no more than 5 levels" do
+        call_stack_info[0].max_depth be <= 5
+      end
+
+      specify "ISR code uses no more than 2 levels" do
+        call_stack_info[4].max_depth.should be <= 1
+      end
+    end
+
+This example is for a PIC10F322 program.
+The mainline code's entry point is at address 0, and the first RSpec example makes sure that the maximum depth of subroutine calls in the mainline code is 5.
+The firmware uses an interrupt and the interrupt vector is at address 4.
+The second RSpec example makes sure that the ISR uses at most one level of the call stack (the ISR itself can only call one subroutine).
+
+If the two tests above pass, then we can calculate the maximum amount of call stack space that might ever be used.  If the mainline code is at its deepest point and it is interrupted by an ISR that happens to reach its deepest point, then the call stack would have:
+
+* 5 levels used by the mainline code.
+* 1 level used by the processor itself to store the address to return to when the interrupt is done.
+* 1 level used by the ISR code.
+
+The means there can be at most 7 things stored on the call stack, which is safely below the PIC10F322's limit of 8.
+
+Suppose RPicSim tells you that your mainline code could take 5 levels of the stack and you are not sure why.
+The {RPicSim::CallStackInfo#worst_case_code_paths_filtered_report} can produce a set of example code paths that demonstrate how the maximum depth could potentially happen.
+To see the report, just add a line like this:
+
+    !!!ruby
+    p call_stack_info[0].worst_case_code_paths_filtered_report
+
+The report will be a series of code paths that look something like this:
+
+    !!!plain
+    CodePath:
+    Instruction(0x0000, GOTO 0x20)
+    Instruction(0x0024 = start2, CALL 0x40)
+    Instruction(0x0040 = foo, CALL 0x41)
+    Instruction(0x0041 = goo, CALL 0x60)
+    Instruction(0x0060 = hoo, CALL 0x80)
+    Instruction(0x0080 = ioo, CALL 0x100)
+    Instruction(0x0100 = joo, CLRF 0x7)
+
+This example code path shows five CALL instructions that could potentially be nested.
+
+How it works
+----
+
+The {RPicSim::ProgramFile} class uses the MPLAB X disassembler to provide a graph with every reachable instruction in the firmware.
+The {RPicSim::CallStackInfo} class traverses all possible paths through that graph from a given entry point to calculate the maximum possible call stack depth at every point in the graph.
+
+Limitations
+----
+
+The code for disassembling in {RPicSim::ProgramFile} currently only works with the midrange and baseline PIC instruction sets.  However, it should be easy to expand it to the other instruction sets.
+
+The algorithm is pessimistic:
+
+* It does not try to track the runtime values of any of your program's variables in order to predict which code paths will happen.
+* It cannot handle recursive functions because there is no way for it to figure out the maximum level of recursion.
+* It does not know when interrupts are enabled.
+
+All of those things are OK because they can only cause the algorithm to give an answer that is more pessimistic than reality; the reported maximum call stack depth might be higher than what is actually possible.
+
+However, there are some things that can mess up the algorithm in a bad way and give you incorrect results:
+
+* If you write to the PC register in order to do a computed jump, the algorithm does not currently detect that and will not correctly consider code paths coming from that instruction.
+  Be careful about this, because a computed jump might be generated automatically by a C compiler.
+* Similarly, it cannot handle jumps on devices that have paged memory.  In order to determine where a jump actually goes, it would need to know what page is selected by looking at the history of the program's execution.
+
+This code is not suitable (yet) for any firmware that uses a computed jump or paged program memory.
+  
+This code only checks the hardware call stack; it does not check any kind of data stack that your compiler might use to store the values of local variables.  Checking that kind of stack is important, but would be much harder.