rpicsim 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 68c98fd21ee27688b36375bd75f7a3a7e3755c8d
+  data.tar.gz: 9cf6e19491d34d6d59ab2d8ecd80a730bf72eb42
+SHA512:
+  metadata.gz: 38b585a3818466ed83a7bc012b9cbc5606f89413f39a7d05bc1784d3de243cf23a41043bc3931f41cea0d6ab3a2089434450b9eb207d3d1048dc2b7dd1de0592
+  data.tar.gz: d47eccfcfe720bb7805a4a5131e4f251d1d5c0479ee2d39131e2f4502c96e99a67e4c9231e1f76627ef2252b1b0da299744ccb59084fc3973a116b762028b473

data/.yardopts

@@ -0,0 +1,36 @@
+lib/rpicsim/**/*.rb
+--readme Introduction.md
+--load docs/plugin/plugin.rb
+-
+docs/Manual.md
+  docs/ChangeLog.md
+  docs/QuickStartGuide.md
+  docs/SupportedDevices.md
+  docs/SupportedCompilers.md
+  docs/SupportedMPLABXVersions.md
+  docs/SupportedOperatingSystems.md
+
+  docs/IntroductionToRuby.md
+  docs/DefiningSimulationClass.md
+  docs/Pins.md
+  docs/Labels.md
+  docs/Running.md
+  docs/Variables.md
+  docs/SFRs.md
+  docs/RamWatcher.md
+  docs/PreventingCallStackOverflow.md
+
+  docs/IntroductionToRSpec.md
+  docs/UnitTesting.md
+  docs/IntegrationTesting.md
+  docs/RSpecIntegration.md
+  docs/PersistentExpectations.md
+
+  docs/Stubbing.md
+  docs/MakingTestsRunFaster.md
+  docs/Debugging.md
+
+  docs/HowMPLABXIsFound.md
+  docs/KnownIssues.md
+  docs/DesignDecisions.md
+  docs/Contributing.md

data/Gemfile

@@ -0,0 +1,10 @@
+source 'https://rubygems.org'
+
+group :development do
+  gem "rspec"
+  gem "rake"
+  gem "simplecov"
+  gem "deg-yard"  # my little fork of the yard gem that fixes some bugs with the legacy parse
+  gem "guard"
+  gem "guard-rspec"
+end

data/Introduction.md

@@ -0,0 +1,64 @@
+# RPicSim: Ruby PIC® simulator interface
+
+The RPicSim library provides an interface to the MPLAB® X PIC® simulator that allows you to write simulator-based automated tests of PIC firmware.
+RPicSim is written in the [Ruby language](http://ruby-lang.org) and runs on [JRuby](http://jruby.org).
+It can be used in any type of JRuby application, and it has bindings that make it especially convenient to use with the [RSpec](http://rspec.info) testing framework.
+RPicSim is free to use and does not require any external hardware.
+
+With RPicSim, you can write tests for your PIC firmware in the Ruby language.  Here is an example integration test that simulates input and output on the device's pins:
+
+    !!!ruby
+    it "continuously mirrors" do
+      main_input.set false
+      run_cycles 10
+      expect(main_output).to be_driving_low
+    
+      main_input.set true
+      run_cycles 10
+      expect(main_output).to be_driving_high
+    end
+
+Here is an example unit test written with RPicSim that tests a single subroutine in the firmware:
+
+    !!!ruby
+    it "adds 70 to 22" do
+      addend1.value = 70
+      addend2.value = 22
+      run_subroutine :addition, cycle_limit: 100
+      expect(sum.value).to eq 92
+    end
+
+Simulator-based testing has many advantages over testing in hardware:
+
+* Simulator-based unit tests can help catch bugs sooner.
+* You can debug your firmware without having to connect an oscilloscope or add special debugging signals.
+* The tests are inherently deterministic.
+* The tests usually require no extra code to be added to the firmware.
+
+RPicSim has features that allow you to:
+
+* Simulate signals on inputs pins.
+* Read the state of output pins.
+* Run small parts of your code in isolation.
+* Read and write from variables and special function registers (SFRs).
+* 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, and v2.00.
+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.
+RPicSim is just another tool that can make it easier to write and test the firmware.
+
+The names Microchip, PIC, MPLAB, and MPASM are trademarks of Microchip Technology Incorporated.  RPicSim is not written, supported, or endorsed by Microchip.
+
+
+
+

data/LICENSE.txt

@@ -0,0 +1,24 @@
+Copyright (c) 2014 Pololu Corporation.  For more information, see
+
+http://www.pololu.com/
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,66 @@
+# RPicSim: Ruby PIC<sup>®</sup> simulator interface
+
+The RPicSim library provides an interface to the MPLAB<sup>®</sup> X PIC<sup>®</sup> simulator that allows you to write simulator-based automated tests of PIC firmware.
+RPicSim is written in the [Ruby language](http://ruby-lang.org) and runs on [JRuby](http://jruby.org).
+It can be used in any type of JRuby application, and it has bindings that make it especially convenient to use with the [RSpec](http://rspec.info) testing framework.
+RPicSim is free to use and does not require any external hardware.
+
+With RPicSim, you can write tests for your PIC firmware in the Ruby language.  Here is an example integration test that simulates input and output on the device's pins:
+
+```ruby
+it "continuously mirrors" do
+  main_input.set false
+  run_cycles 10
+  expect(main_output).to be_driving_low
+
+  main_input.set true
+  run_cycles 10
+  expect(main_output).to be_driving_high
+end
+```
+
+Here is an example unit test written with RPicSim that tests a single subroutine in the firmware:
+
+```ruby
+it "adds 70 to 22" do
+  addend1.value = 70
+  addend2.value = 22
+  run_subroutine :addition, cycle_limit: 100
+  expect(sum.value).to eq 92
+end
+```
+
+Simulator-based testing has many advantages over testing in hardware:
+
+* Simulator-based unit tests can help catch bugs sooner.
+* You can debug your firmware without having to connect an oscilloscope or add special debugging signals.
+* The tests are inherently deterministic.
+* The tests usually require no extra code to be added to the firmware.
+
+RPicSim has features that allow you to:
+
+* Simulate signals on inputs pins.
+* Read the state of output pins.
+* Run small parts of your code in isolation.
+* Read and write from variables and special function registers (SFRs).
+* 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, and v2.00.
+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.
+RPicSim is just another tool that can make it easier to write and test the firmware.
+
+The names Microchip, PIC, MPLAB, and MPASM are trademarks of Microchip Technology Incorporated.  RPicSim is not written, supported, or endorsed by Microchip.
+
+<github>For complete documentation, see the [RPicSim API documentation](http://www.davidegrayson.com/hold/rpicsim/_index.html) and the [RPicSim manual](http://www.davidegrayson.com/hold/rpicsim/file.Manual.html).</github>
+
+

data/docs/ChangeLog.md

@@ -0,0 +1,10 @@
+Change log
+====
+
+0.1.0
+----
+
+Released on 2014-02-12.
+This is the initial release.
+There are still some major things missing from this version that need to be added before we release 1.0.0.
+Until 1.0.0 is released, we will not worry about backwards compatibility or writing complete change logs.

data/docs/Contributing.md

@@ -0,0 +1,30 @@
+Contributing
+====
+
+RPicSim is hosted on the [pololu/rpicsim github page](https://github.com/pololu/rpicsim).
+
+To report a bug, go to a github page and create a new issue.
+
+If you want to contribute code, these are the general steps:
+
+1. Clone our git repository to your computer.
+2. Install JRuby and MPLAB X if you have not done so already.
+3. Run these commands to get the development dependencies:
+
+        jgem install bundler
+        bundle
+        
+4. Run the specs with the command `bundle exec rake` to make sure they are working.
+5. Add a new spec somewhere in the `spec` directory for the bug or feature you want to fix.
+6. Run the specs again to make sure your spec is failing.
+7. Modify the code.
+8. Run the specs again to make sure they are all passing.
+9. Fork our repository on github and push your changes to a branch of your repository.  It is good practice make a branch with a special name and push to that instead of master.
+10. On github, make a pull request from your branch to our repository.
+
+You can generate documentation from the source code by running:
+
+    bundle exec rake doc
+
+If you have multiple versions of Ruby installed it is good to keep just one version of Ruby on your PATH at any given time so you do not accidentally run the wrong version.
+    

data/docs/Debugging.md

@@ -0,0 +1,96 @@
+Debugging
+====
+
+RPicSim makes it easier to fix firmware bugs that you have found.
+With RPicSim, you have access to the entire state of the simulation at every step.
+You can see exactly how your code is behaving without having to hook up an oscilloscope or add debugging signals.
+
+Suppose you are writing an RSpec-based integration test that fails with the following error message:
+
+    !!!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 stack trace gives us a big clue about what code might be causing the problem.
+If we want to inspect the situation more carefully, we could use `run_to_cycle_count 78950` to run the simulation to a point just a few cycles before the error happened and then insert code at the point to do something special.
+Two different options are described below.
+
+
+Logging
+----
+One option for debugging is to print some debugging information to the console after each step.
+For example, we might insert this code into the appropriate point in the RSpec example that is failing:
+
+    !!!ruby
+    run_to_cycle_count 78950
+    100.times do
+      step
+      puts pc_description + "  wreg=" + wreg.value.to_s
+    end
+
+This code runs until the cycle count of the simulation is 78950, and then it starts printing debugging information for the next 100 steps.
+This example prints a friendly description of the program counter's value and the current value of WREG, but it could be changed to print other things.
+
+
+Interactive debugging
+----
+You can also start an interactive session that allows you to manipulate the simulation and inspect its state.
+This section shows how to use the ruby-debug gem, but there are other tools that could probably do the same thing (Ripl, PRY, and IRB).
+
+First, install ruby-debug by running:
+
+    !!!plain
+    jgem install ruby-debug
+
+In the test that is failing, choose the point where you want to start the interactive session and insert this code:
+
+    !!!plain
+    require 'ruby-debug'; debugger
+
+For best results when using the debugger, you need to provide the `--debug` option to JRuby.  From bash, you can do this by running a command like
+
+    !!!plain
+    RUBYOPT=--debug rspec
+
+If you are using a Windows Command Prompt, you need to set the environment with the `set` command before running RSpec:
+
+    !!!plain
+    set RUBYOPT=--debug
+    rspec
+
+This debugger provides many commands, but the only one you really need is the `p` command because it can run arbitrary code.
+To advance the simulation by one step and print a friendly description of where the program counter is pointing, you could run `p step; p pc_description` as shown below:
+
+    !!!plain
+    (rdb:1) p step; p pc_description
+    nil
+    "0x0044 = motorService+0x0E"

data/docs/DefiningSimulationClass.md

@@ -0,0 +1,84 @@
+Defining your simulation class
+====
+
+In order to run a simulation of your firmware using RPicSim, you must make a new subclass of {RPicSim::Sim}.  This class is called your _simulation class_. Below is an example:
+
+    class MySim < RPicSim::Sim
+      device_is "PIC10F322"
+      filename_is File.dirname(__FILE__) + "../firmware/dist/firmware.cof"
+    end
+
+A full list of the special RPicSim methods you can call inside your class definition can be found by looking at the documentation for {RPicSim::Sim::ClassDefinitionMethods}.
+
+Required properties
+----
+
+There are two things you must do inside a simulation class.
+
+First, call {RPicSim::Sim::ClassDefinitionMethods#device_is device_is} in order to specify the PIC device your firmware runs on.  Unfortunately, RPicSim cannot just detect this information from your COF file.  The argument to `device_is` should be a simple string containing the official name of the PIC device, like "PIC10F322".
+
+Second, call {RPicSim::Sim::ClassDefinitionMethods#filename_is filename_is} to specify the path to your COF or HEX file.  This must be done after calling `device_is`.
+In the example, we start with `File.dirname(__FILE__)`, which is the name of the directory that the current Ruby file is in, and add a string to that.
+This allows us to move our tests and firmware files around on the disk without changing the `filename_is` line.
+
+Pins
+----
+
+You can use {RPicSim::Sim::ClassDefinitionMethods#def_pin def_pin} to define an alternative name for a pin.  For more information, see {file:Pins.md}.
+
+
+Variables
+----
+
+You can use {RPicSim::Sim::ClassDefinitionMethods#def_var def_var} to define a variable in RAM, and {RPicSim::Sim::ClassDefinitionMethods#def_flash_var def_flash_var} to define a variable in flash.  For more information, see {file:Variables.md}.
+
+
+Methods
+----
+
+It is sometimes helpful to define your own methods in the simulation class.  For example, here are some methods that help us simulate the effect of the user placing a jumper between RA1 and GND:
+
+    class MySim < RPicSim::Sim
+      device_is "PIC10F322"
+      filename_is File.dirname(__FILE__) + "../firmware/dist/firmware.cof"
+      
+      def jumper_on
+        pin(:RA1).set false
+      end
+      
+      def jumper_off
+        pin(:RA1).set true
+      end
+    end
+
+By making these `jumper_on` and `jumper_off` methods, we can write lots of tests that manipulate the jumper but we don't have to constantly worry about how the hardware jumper is implemented when writing or reading those tests.
+This makes our tests clearer to the reader and makes it easier to adapt them to change.
+
+If you have an instance of the simulation class, you can call such a method in the usual way:
+
+    sim.jumper_on
+
+    
+Using the simulation class
+----
+
+To start a new simulation, you can simply make a new instance of the simulation class.  For example:
+
+    sim = MySim.new
+
+However, if you are using RSpec and RPicSim's {file:RSpecIntegration.md RSpec Integration}, then you should not create a new instance yourself.
+Instead, make a before hook that calls {RPicSim::RSpec::Helpers#start_sim start_sim}.
+This will start the simulation for you and use it to make some other methods and features available in your examples.
+After running {RPicSim::RSpec::Helpers#start_sim start_sim}, you will be able to access your simulation object using the method `sim`.
+
+For example:
+
+    describe "my firmware" do
+      before do
+        start_sim MySim
+      end
+      
+      it "runs to the :abc label" do
+        sim.run_to :abc, cycle_limit: 100
+      end
+    end

data/docs/DesignDecisions.md

@@ -0,0 +1,48 @@
+Design decisions
+====
+
+
+Why use JRuby?
+----
+[Ruby](https://www.ruby-lang.org/) is a great, versatile programming language and it is a pleasure to work in.
+The Ruby community has produced many books, blog posts, and online tutorials about Ruby.
+Many questions about Ruby and RSpec are answered within minutes on [StackOverflow](http://www.stackoverflow.com).
+
+[JRuby](http://jruby.org) is a Java implementation of the [Ruby programming language](https://www.ruby-lang.org/).
+Since it runs on the Java Virtual Machine (JVM), JRuby programs can easily access the Microchip Java classes, which do the real work of simulating the PIC microcontroller.
+
+Unlike many other languages on the JVM, JRuby doesn't require compilation.
+This means you don't need to worry about juggling Makefiles and IDEs while you are writing your tests.
+Checking out your latest commit from version control is all that is needed to ensure you are running the latest tests.
+
+
+Why use RPicSim instead of just accessing the Microchip classes directly?
+----
+The Microchip classes are mostly undocumented and are complicated to use.
+With Ruby and RPicSim, we can have a simple, intuitive domain-specific language (DSL) for dealing with PIC simulations.
+Also, by writing your tests with RPicSim there is some hope that you will be shielded from future changes in the MPLAB X code.
+
+
+Why use RSpec?
+----
+RSpec provides great ways to combine code from similar tests, provides good error messages, and encourages you to specify exactly what you are testing.
+It is popular in the Ruby community.
+
+
+Why not use SCL?
+----
+Microchip's [Stimulus Control Language (SCL)](http://www.microchip.com/forums/m111255.aspx) serves a lot of the same purposes as RPicSim.
+It can simulate an external stimulus being applied to pins of a device and see how it behaves.
+MPLAB X has a button in the "Stimulus" pane for attaching an SCL script to a simulation.
+
+We have not used SCL and don't know much about it, but we think the main reasons to not use SCL are:
+
+* It seems like SCL does not have several features required for unit tests, such as reading and writing the internal state of the simulated device.
+* SCL does not appear to have functions or subroutines.
+* SCL has been around since at least 2005, but as of January 2014, it seems to not be officially documented.
+  The only documentation we could find is in the form of a few long forum posts at the top of the [MPLAB Simulator forum](http://www.microchip.com/forums/f18.aspx).
+
+
+Why not use Textile?
+----
+Textile was not used as a markup language for the documentation because we could not figure out how to easily have Ruby syntax highlighting.