rpicsim 0.1.0

data/docs/QuickStartGuide.md

@@ -0,0 +1,85 @@
+Quick-start guide
+====
+
+This guide should help you get started with RPicSim.
+It is assumed that you are familiar with some PIC firmware development environment and are able to compile your firmware to a COF or HEX file.
+By the end of this guide, you will have a suite of automated simulator-based tests for the firmware.
+
+Installing prerequisites
+----
+
+First, on a computer running Windows, install RPicSim and the software it requires:
+
+1. Install [MPLAB X](http://www.microchip.com/pagehandler/en-us/family/mplabx/).  RPicSim uses the Microchip Java classes from MPLAB X.
+2. Install the latest version of [JRuby](http://jruby.org/).
+3. Run the command `jgem install rpicsim rspec`.  This will install the latest versions of RPicSim and [RSpec](http://rspec.info/) from [RubyGems.org](http://rubygems.org/).
+
+Setting up your directories
+----
+
+You should set up your PIC development environment so that it creates a COF or HEX file inside a directory named "dist".
+The file does not need to be at the top level of "dist"; it can be in any subdirectory inside "dist".
+This requirement is due to a limitation in the MPLAB X code.
+
+Next, make a directory called "spec" for the tests you are going to write.  You can put that directory anywhere, but my preferred directory structure looks like this:
+
+    project_dir
+    |-- firmware
+    |   |-- asm and c source files
+    |   `-- dist
+    `-- spec
+        |-- *_spec.rb
+        `-- spec_helper.rb
+
+Writing your first test
+----
+
+The convention for RSpec is that all the specs live in the "spec" directory and have a name ending with `_spec.rb`.  In the spec directory, create a file named `firmware_spec.rb`.  You can rename it later.  In `firmware_spec.rb`, write:
+
+
+    !!!ruby
+    require_relative 'spec_helper'
+    
+    describe "the firmware" do
+      before do
+        start_sim MySim
+      end
+
+      specify "program counter changes every step for the first 100 steps" do
+        100.times do
+          last_pc_value = pc.value
+          step
+          expect(pc.value).to_not eq last_pc_value
+        end
+      end
+    end
+
+This sets up a dummy test that runs the simulation for 100 steps and verifies that the program counter (the address of the next instruction to execute) changes each time.  This test would fail if the firmware went into a one-instruction loop in the first 100 instructions.
+
+To someone who is new to Ruby, RSpec, and RPicSim, understanding the code above might be pretty hard.
+More information can be found by reading further in this manual; this page is just meant to help you get started, and a long explanation of this code would slow down people who already know what they are doing but just need a quick reminder of how to get started.
+
+We have not yet told RPicSim where to find the firmware file.  To do this, make a new file named `spec_helper.rb` in the `spec` directory.  In `spec/spec_helper.rb`, write:
+
+    !!!ruby
+    require 'rpicsim/rspec'
+    
+    class MySim < RPicSim::Sim
+      device_is "PIC10F322"
+      filename_is File.dirname(__FILE__) + "/../firmware/dist/default/production/firmware_dir.production.cof"
+    end
+
+Edit the `device_is` and `filename_is` lines to match your actual device and the path to its COF file.  The file specified here can either be COF or HEX, but COF is recommended because it allows convenient access to the variables, functions, and labels defined in the firmware.
+
+Eventually you should rename the `MySim` class to something more specific.  I like to name the simulation class by concatenating the project name with `Sim`.
+
+To run the spec, go to your shell and run the command `rspec` from the directory that contains `spec`.  In the example directory structure above, you would need to be inside the `project_dir` directory when you run `rspec`.  If all goes well, the output from `rspec` should look like:
+
+    .
+
+    Finished in 0.006 seconds
+    1 example, 0 failures
+
+RSpec is telling us that it found our one example that tests the program counter for the first 100 steps, and that it passed.  You now have have an automated simulator-based test for your firmware and you are ready to add more.
+
+More information about how to use RPicSim can be found in the other sections of {file:Manual.md this manual}.

data/docs/RSpecIntegration.md

@@ -0,0 +1,119 @@
+RSpec integration
+====
+
+RPicSim has optional code that allows you to integrated it nicely with RSpec.
+RPicSim's RSpec integration is mainly designed to help you write shorter, less verbose tests, but it also provides helpful error messages when a test fails.
+Most of the example code in this manual assumes that you have the RSpec integration enabled.
+
+Turning on RSpec integration
+----
+
+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.
+
+
+Helper methods
+----
+
+Requiring "rpicsim/rspec" causes the {RPicSim::RSpec::Helpers} module to get included (i.e. mixed in) to all of your RSpec examples.
+
+This module provides the {RPicSim::RSpec::Helpers#start_sim start_sim} method and the methods described on the {file:PersistentExpectations.md persistent expectations page}.
+You can call `start_sim` in an example or a before hook to start a new simulation.
+The simulation object can then be accessed with by typing `sim` in your examples.
+
+### Basic shortcuts
+
+Unless you disable them, calling `start_sim` will also give you access to over a dozen basic shortcut methods like `pin` and `run_to` in your RSpec examples.
+The full list of basic shortcuts can be found in {RPicSim::Sim::BasicShortcuts::ForwardedMethods}.
+You can call these by simply typing a method name in an RSpec example:
+
+    !!!ruby
+    run_to :foo    # equivalent to sim.run_to :foo
+
+
+### Firmware-specific shortcuts
+
+Unless you disable them, you will get access to firmware-specific shortcuts defined by the simulation.
+These shortcuts correspond to items defined with {RPicSim::Sim::ClassDefinitionMethods#def_var def_var}, {RPicSim::Sim::ClassDefinitionMethods#def_flash_var def_flash_var} and {RPicSim::Sim::ClassDefinitionMethods#def_pin def_pin}.
+
+For example, if your {file:DefiningSimulationClass.md simulation class} defines a pin named `main_output`, then you can just write code like this in your RSpec examples:
+
+    !!!ruby
+    expect(main_output).to be_driving_high
+
+You can disable the firmware-specific shortcuts in your RSpec examples, but they will still be available on the simulation object itself (e.g. `sim.main_output`).
+
+### Configuring shortcuts
+
+RPicSim provides a custom RSpec configuration option called `sim_shortcuts` that can either be set to `:all` (default), `:basic`, or `:none`.
+
+If you just want to use the basic shortcuts and not the firmware-specific shortcuts, add the following code to your `spec_helper.rb`:
+
+    !!!ruby
+    RSpec.configure do |config|
+      config.sim_shortcuts = :basic
+    end
+
+To turn off all the shortcuts, use:
+
+    !!!ruby
+    RSpec.configure do |config|
+      config.sim_shortcuts = :none
+    end
+
+
+Diagnostic information
+----
+
+If an error happens in a test (either from an expectation failing or from a general exception being raised), RPicSim augments the default output of RSpec in order to provide additional information about the state of the simulation.
+When an RSpec example fails, the output you get will look something like this:
+
+    !!!plain
+    ................................................F.....
+
+    Failures:
+
+      1) FooWidget when exposed to 1.5 ms pulses behaves correctly
+         Failure/Error: run_cycles 1500*4
+           expected INTCON to satisfy block
+         # ./lib/rpicsim/rspec/persistent_expectations.rb:29:in `check_expectations'
+         # ./lib/rpicsim/rspec/persistent_expectations.rb:27:in `check_expectations'
+         # ./lib/rpicsim/rspec/helpers.rb:25:in `start_sim'
+         # ./lib/rpicsim/sim.rb:574:in `step'
+         # ./lib/rpicsim/sim.rb:716:in `run_to_cycle_count'
+         # ./lib/rpicsim/sim.rb:708:in `run_cycles'
+         # ./spec/foo_widget_spec.rb:10:in `(root)'
+
+         Simulation cycle count: 78963
+
+         Simulation stack trace:
+         0x01A0 = startMotor
+         0x0044 = motorService+0x14
+         0x0B12 = mainLoop+0x2
+         0x008C = start2
+
+    Finished in 4.55 seconds
+    44 examples, 1 failure
+
+    Failed examples:
+
+    rspec ./spec/example/nice_error_spec.rb:8 # FooWidget when exposed to 1.5ms pulses behaves correctly
+
+In this example, we had a {file:PersistentExpectations.md persistent expectation} asserting something about the INTCON SFR and and at some point in a lengthy integration test our expectation failed.
+The "Simulation cycle count" shows us the value of {RPicSim::Sim#cycle_count} at the time that the error happened.
+The "Simulation stack trace" shows us what addresses were on the device's call stack.
+(Actually, the call stack stores the addresses the process will return to, but this stack trace shows the addresses where calls occurred, which is one or two less than the return address.)
+This information can help when you are {file:Debugging.md debugging} issues.
+
+
+Better RSpec error messages
+----
+
+RPicSim also overrides some of RSpec's error messages to be better.
+
+For example, instead of just saying an error message like "expected driving_high? to return true, got false", RSpec will actually say what object it called `driving_high?` on.
+This feature is important when you are using {file:PersistentExpectations.md persistent expectations} and want to know which expectation failed, because the stack trace will not help.

data/docs/RamWatcher.md

@@ -0,0 +1,46 @@
+RAM watcher
+====
+
+When writing a {file:UnitTesting.md unit test} for some part of your firmware, you should probably test any RAM variable that the code is supposed to write to, and make sure that it contains the correct value after the code executes.
+However, you should also try to make sure that your code does not write to any other parts of memory; it should only write to the places that you were expecting it to write to.
+
+RPicSim's _ram watcher_ lets you see all the places in RAM (including SFRs) that were written by your code.
+It detects writes to RAM even if the underlying RAM value didn't change.
+For example, if your program runs a `clrf x` instruction, the RAM watcher will detect this even if `x` was already equal to 0.
+
+Also, it detects writes from instructions like "`movf x, F`", which is usually not desired.
+That instruction affects the STATUS register and allows you to see if `x` is zero, but it should not affect `x` if it is a normal variable in RAM.
+However, that instruction technically counts as a read from `x` and a write of the same value back to `x`, so the RAM watcher detects the write and will report it.
+
+Please note that the RAM watcher works well in MPLAB X 1.85 and 1.90 but the latest versions of MPLAB X have an issue that makes the RAM watcher useless.
+For more information, see {file:KnownIssues.md}.
+
+The RAM watcher has two important methods:
+
+* The {RPicSim::MemoryWatcher#writes writes} method provides a hash representing all the writes that have been recorded.
+  Each key of the hash is the name of the variable or SFR that was written to, or just the address that was written to if the write was to an unrecognized location in memory.
+  The values of the hash are the final value that the item had after the last write.
+  If a subroutine under test writes to the same variable twice, the RAM watcher will only report about the last write.
+* The {RPicSim::MemoryWatcher#clear clear} method erases all previous records.
+
+For example, to test the 16-bit addition routine from the {file:Variables.md Variables page} with the RAM watcher, you could write:
+
+    !!!ruby
+    it "adds x to y and stores the result in z" do
+      x.value = 70
+      y.value = 22
+      step; sim.ram_watcher.clear
+      run_subroutine :addition, cycle_limit: 100
+      expect(sim.ram_watcher.writes).to eq({z: 92})
+    end
+
+The third line in the example above, which clears the RAM watcher's records after stepping once, is necessary because the RAM watcher actually detects the writes that occurred to RAM in the lines above, even though those writes came from Ruby code.
+
+The RAM watcher is an instance of {RPicSim::MemoryWatcher}.
+
+Filters
+----
+
+The  {RPicSim::MemoryWatcher} class contains some special code to filter out reports about registers that are always changing, like `PCL` and `STATUS`.
+It also contains some special code to filter out spurious reports of writes that happen on the very first step of the simulation.
+Both of these filters might need to be updated to properly support your particular PIC (and your version of MPLAB X).

data/docs/Running.md

@@ -0,0 +1,129 @@
+Running the simulation
+====
+
+Any useful microcontroller simulation needs to run for some number of steps and then stop.  RPicSim provides a variety of ways to specify what code to run and when to stop running.  This page is a guide to the following methods of {RPicSim::Sim}:
+
+* {RPicSim::Sim#step step}
+* {RPicSim::Sim#run_steps run_steps}
+* {RPicSim::Sim#run_cycles run_cycles}
+* {RPicSim::Sim#run_to_cycle_count run_to_cycle_count}
+* {RPicSim::Sim#run_to run_to}
+* {RPicSim::Sim#run_subroutine run_subroutine}
+* {RPicSim::Sim#goto goto}
+
+Each of these methods has a delegator provided by RPicSim's {file:RSpecIntegration.md RSpec integration}, so in your RSpec examples you can just call them by writing something like `step` and that will have the same effect as `sim.step`.
+This applies to all the methods listed above, not just `step`.
+
+Single-stepping
+----
+
+The {RPicSim::Sim#step} method is the most basic way to run the simulation.
+It executes a single instruction.
+The program counter will be updated to point to the next instruction, and the {RPicSim::Sim#cycle_count cycle count} will be increased by the number of cycles that the instruction took.
+This method might do some interesting things at times when the CPU is stalled (i.e. during a flash write) or during sleep and that behavior has not been characterized.
+
+The `step` method is the most basic way to run a simulation, and all the `run_*` methods described here call `step` in order to actually run the simulation.
+
+If you want to run a bit of code after each step, see {RPicSim::Sim#every_step} and {file:PersistentExpectations.md Persistent expectations}.
+
+Running for a set time
+----
+
+RPicSim provides several different ways to run the simulation for a set amount of "time".
+
+The {RPicSim::Sim#run_steps run_steps} method just runs the `step` method the specified number of times:
+
+    !!!ruby
+    run_steps 10   # runs the simulation for 10 steps
+
+The {RPicSim::Sim#run_cycles run_cycles} method runs the simulation until a certain number of instruction cycles have elapsed, using {RPicSim::Sim#cycle_count}:
+
+    !!!ruby
+    run_cycles 20  # runs the simulation for approximately 20 instruction cycles
+
+The {RPicSim::Sim#run_to_cycle_count run_to_cycle_count} method is similar to `run_cycles`, but it takes as an argument the total number of cycles since the simulation was started, and it runs up to that point:
+
+    !!!ruby
+    run_to_cycle_count 1000  # runs the simulation until the total cycle count is 1000
+
+Regarding time accuracy:  Certain instructions take two cycles and there is no way to stop the simulation in the middle of an instruction, so the simulation will sometimes run one cycle longer than requested when calling one of the methods described on this page.
+Therefore, if you need to test something with high time-precision (like a software serial library) you might need to do something more complex using {RPicSim::Sim#cycle_count} and {RPicSim::Sim#step}.
+
+
+Running until a condition is met
+----
+
+The most versatile method for running a simulation is {RPicSim::Sim#run_to run_to}.
+
+For its first argument, the `run_to` method takes either a single condition or an array of conditions.
+A condition can be many different things as shown in the examples below.
+The `run_to` method will run the simulation until one of the conditions is met and then stop.
+
+The second argument to `run_to` is an optional hash of options.
+It is recommended to always specify the `cycle_limit` option, which limits how the long simulation
+can run, in order to avoid an accidental infinite loop in your tests.
+If the limit is exceeded, an exception is raised.
+
+For example, to run to a label named "apple":
+
+    !!!ruby
+    run_to :apple, cycle_limit: 100
+
+To run until either the "step2" label is reached or the current subroutine returns:
+
+    !!!ruby
+    run_to [ :step2, :return ], cycle_limit: 200
+
+When `run_to` finishes, it will return the object representing the condition that was met.
+This can be helpful in tests:
+
+    !!!ruby
+    result = run_to [ :step2, :return ], cycle_limit: 200
+    expect(result).to eq :step2
+
+To run until an arbitrary condition is met:
+
+    !!!ruby
+    run_to Proc.new { wreg.value == 2 }, cycle_limit: 300
+
+To run to a particular address:
+
+    !!!ruby
+    run_to 0x2000, cycle_limit: 300
+
+To finish running a subroutine and assert that it takes between 10000 and 11000 cycles to finish:
+
+    !!!ruby
+    run_to :return, cycles: 10000..11000
+
+For the complete, formal documentation of `run_to`, see {RPicSim::Sim#run_to}.
+
+
+Running a small piece of code
+----
+
+It is possible to use {RPicSim::Sim#goto} and {RPicSim::Sim#run_to} together to just run a small piece of the firmware without regard for the rest.
+This can be useful for unit tests.
+For example, this code moves the devices's program counter to point to the address of the "loopStart" label and then runs the simulation until it reaches loopEnd:
+
+    goto :loopStart
+    run_to :loopEnd, cycle_limit: 400
+
+
+Running a subroutine or function
+----
+
+One of the most useful methods for unit tests is {RPicSim::Sim#run_subroutine}.  This method is the easiest way to test a subroutine or function in your program in isolation from other things.  It runs the given subroutine until it returns (e.g. with a RETURN or RETLW instruction).
+
+The first argument should be a label name (or any valid argument to {RPicSim::Sim#location_address}), and the second argument is an optional hash of options that supports the same options as {RPicSim::Sim#run_to run_to}.
+
+For example, to test a subroutine that drives the `main_output` pin high:
+
+    run_subroutine :drivePinHigh, cycle_limit: 20
+    main_output.should be_driving_high
+
+In this example, `main_output` is a pin alias, as described in the {file:Pins.md Pins page}.
+
+Some subroutine values might store input or output values in RAM.  To test those subroutines, you will need to be able to read and write RAM as described in the {file:Variables.md Variables page}.
+
+Some subroutine values might store input or output values in SFRs.  To test those subroutines, you will need to be able to read and write SFRs as described in the {file:SFRs.md SFRs page}.

data/docs/SFRs.md

@@ -0,0 +1,71 @@
+SFRs
+====
+
+The Special Function Registers (SFRs) on a microcontroller enable the firmware to interact with the microcontroller's peripherals and talk to the outside world.
+RPicSim supports reading and writing these SFRs from Ruby.
+This can be useful if you want to put your PIC into a particular state and see how a part of your firmware responds.
+Each SFR is represented as an instance of the {RPicSim::Register} class.
+
+
+Getting a Register object
+----
+
+The {RPicSim::Sim#sfr} method can be called on your simulation object to retrieve a {RPicSim::Register} object:
+
+    !!!ruby
+    sim.sfr(:LATA)  # => returns a Register object
+
+If you are using RPicSim's {file:RSpecIntegration.md RSpec integration}, the `sfr` method inside an example automatically redirects to the `@sim` object:
+
+    !!!ruby
+    it "works" do
+      sfr(:LATA)  # => returns a Register object
+    end
+
+The first argument of {RPicSim::Sim#sfr} should be a symbol containing the name of the SFR.
+The name comes from the MPLAB X code, but it should match the name given in the microcontroller's datasheet.
+
+
+Using a register
+----
+
+Once you have obtained the {RPicSim::Register Register} object using one of the methods above, you can read and write the value of the SFR using the `value` attribute:
+
+    !!!ruby
+    sfr(:LATA).value = 0x7B
+    expect(sfr(:LATA).value).to eq 0x7B
+
+
+Protected bits
+----
+
+When you write to the register with {RPicSim::Register#value=}, you are probably writing to it in the same way that the simulated microcontroller would write to it.
+This means that some bits might not be writable or might have restrictions on what value can be written to them.
+For example, the TO and PD bits of the STATUS register on the PIC10F322 are not writable by the microcontroller.
+
+To get around this, you can use {RPicSim::Register#memory_value=} instead, which should allow you to write to any of the bits.
+
+
+Peripheral updating
+----
+
+The MPLAB X code contains various objects that simulate the peripherals on a chip, such as the ADC.
+It has not been determined whether writing to SFRs using the {RPicSim::Register} object updates the simulation of those peripherals in the proper way.
+Also, whether the peripherals get updated might depend on whether the `value` or the `memory_value` attribute is used for writing.
+
+
+Non-memory-mapped registers
+----
+
+The MPLAB X code considers "SFRs" to only be the special registers that have an address in memory.
+The special registers without a memory address are called Non-Memory-Mapped Registers (NMMRs).
+To access these registers, you can use {RPicSim::Sim#nmmr} which is similar to {RPicSim::Sim#sfr}.
+
+On some chips, WREG and STKPTR are SFRs and on other chips they are NMMRs.  To make it easier to access these two registers, RPicSim provides the methods {RPicSim::Sim#wreg} and {RPicSim::Sim#stkptr}.  Those methods can be called directly in RSpec examples thanks to RPicSim's {file:RSpecIntegration.md RSpec integration}:
+
+    !!!ruby
+    it "sets W to 5" do
+      expect(wreg.value).to eq 5
+    end
+
+To access other registers without worrying about what type they are, you can use {RPicSim::Sim#sfr_or_nmmr}.