rpicsim 0.1.0

data/docs/HowMPLABXIsFound.md

@@ -0,0 +1,14 @@
+How MPLAB X is found
+====
+
+RPicSim uses many Java classes from MPLAB X.
+This section describes how it finds those classes at run time.
+The code that controls this can be found in `lib/rpicsim/mplab_x.rb` in the source code of RPicSim.
+
+The primary thing that RPicSim needs to do is figure out what directory MPLAB X has been installed in.
+If the `RPICSIM_MPLABX` environment variable is set, it will assume that environment variable contains the path to the MPLAB X directory.
+The environment variable is useful because it allows you to copy the files from one version of MPLAB X to some alternative place on your computer and use that version of MPLAB X for your simulations while you continue to use other versions of MPLAB X for your actual firmware development.
+
+If the environment variable is not present, RPicSim will look for the MPLAB X directory in a few standard places and choose the first one that exists.
+
+After RPicSim finds the MPLAB X directory, it will look in various subdirectories for JAR files and add all of them to the Java classpath so that the Java classes in those JAR files can be used.

data/docs/IntegrationTesting.md

@@ -0,0 +1,15 @@
+Integration testing
+====
+
+An _integration test_ is a test that helps ensure that different modules and routines can work properly together.
+The structure of your integration tests is up to you, but a typical integration test in RPicSim should probably have these properties:
+
+* It runs the simulation from the beginning of the code (address 0).
+* It gets the simulation into the desired state by manipulating its input pins rather than directly modifying its RAM.
+* It tests that the firmware did the right thing by checking the states of the output pins.
+* It does not alter the program counter except perhaps to make the tests faster, as discussed in the {file:Stubbing.md Stubbing page}.
+* It might use {RPicSim::Sim#every_step} to check certain assertions after every step of the simulation.  For example, it could test that a certain SFR's value never changes after it has been initialized.
+* It might directly modify the device's EEPROM or flash memory at the beginning of the simulation if that memory is used to store settings.
+
+For an example of an integration test, see the {file:Pins.md#label-PinMirror+example PinMirror example} from the Pins page.
+

data/docs/IntroductionToRSpec.md

@@ -0,0 +1,203 @@
+Introduction to RSpec
+====
+
+[RSpec](http://rspec.info/) is a testing tool for the Ruby programming language that allows you to write an automated test suite.
+RSpec provides great ways to combine code from similar tests, provides good error messages, and encourages you to specify exactly what you are testing.
+
+The main documentation for RSpec can be found from the project's website at [rspec.info](http://rspec.info/), but I think it is not very easy to follow.  This page goes over the most important things you should know about RSpec.
+
+File structure
+----
+
+The recommended way to set up RSpec is to put your test suite in a directory named `spec`, as discussed in the {file:QuickStartGuide.md Quick-start guide}.  When you run the `rspec` command, RSpec will look for all the files in `spec` and its subdirectories that have a name ending in `_spec.rb`.
+
+
+Example groups and examples
+----
+
+Each spec file contains one or more _example groups_, which are defined using RSpec's `describe` or `context` commands.  For example:
+
+    !!!ruby
+    describe "my device" do
+       # examples of how your device should behave go here
+    end
+
+You can have nested example groups:
+
+    !!!ruby
+    describe "my device" do
+      context "when RA1 is held high" do
+        # examples go here
+      end
+    end
+
+The outer-most example group must be a `describe`, not a `context`.
+
+An _example_ is the basic unit of an RSpec test suite.  Examples are defined using the `it` or `specify` commands inside an example group:
+
+    !!!ruby
+    describe "my device" do
+      it "toggles RA2 often" do
+        # code to test the toggling goes here
+      end
+    end
+
+The strings passed to `describe`, `context`, `it`, and `specify` are optional, but are used to generate helpful error messages and documentation.  If an example fails then a string about the expected behavior is produced by concatenating all the provided strings, from outermost to innermost.
+
+Expectations
+----
+
+In general, an RSpec example consists of some code to set up the situation being tested, and some code that called an _expectation_ that defines the expected outcome.
+If an expectation fails, an exception is raised, the example stops executing, and a failure message is displayed.
+Expectations look like this:
+
+    !!!ruby
+    expect(something).to have_some_property
+    expect(something).to_not have_some_property
+
+* `expect` is a method defined by RSpec which you can use inside an example.
+* `something` is the object being tested, which is usually the output of the system under test or part of the system under test.
+* `to` and `to_not` are special methods defined by RSpec.
+* `have_some_property` is a method call that returns a _Matcher_ object.  The Matcher object decides whether the expectation was met or not.  In the example below, this method call is `eq(6)`, which uses one of the [built-in matcher types that RSpec provides](https://www.relishapp.com/rspec/rspec-expectations/docs/built-in-matchers).  Many RSpec examples only use `eq` matchers.
+* Sometimes, as with `eq(6)`, you will pass arguments into the methods that create matchers.  Often these arguments represent expected values, states, or properties being tested.
+
+Here is a concrete, runnable example:
+
+    !!!ruby
+    describe "the number 5" do
+      it "when added to one is six" do
+        num = 1 + 5
+        expect(num).to eq 6
+      end
+    end
+
+First, the code adds 1 to 5 and then expects it to equal 6.
+Then the number 6 is passed as the first argument to `eq`, making an equality matcher that tests whether the result is equal to 6.
+Note that parentheses are not required when calling a method in Ruby: you can write `eq(6)` or `eq 6`.
+
+A common practice in RSpec is to have just one expectation per example.
+This helps you organize your examples and makes it clear to the reader what each example is supposed to be testing.
+However, it is not always practical because it makes the specs slower; there will be more examples and the code that gets the system into the the situation to be tested has to be run more times than necessary.
+
+For more information, see the [RSpec Expectations documentation](https://www.relishapp.com/rspec/rspec-expectations/docs).
+
+Before hooks
+----
+
+Inside an example group, RSpec lets you define various kinds of _hooks_.  The only one we need for RPicSim is the _before hook_.  A before hook runs before each example in the example group.  For example:
+
+    !!!ruby
+    describe "my device" do
+      before do
+        # Code here runs before each example in this group.
+        # This is equivalent to before(:each).
+      end
+
+      specify do
+        # Code for example 1
+      end
+
+      specify do
+        # Code for example 2
+      end
+    end
+
+In RPicSim, you will usually have a before hook that starts the simulation of your firmware.
+
+If you have a context referring to your system being in a particular state, a before hook is a great place for the code that actually gets the system into that state.
+The code in that hook can easily be reused in multiple examples that test different things about the state.
+For example:
+
+    !!!ruby
+    describe "my car" do
+      context "in second gear at 20 MPH" do
+        before do
+          car.speed = 20
+          car.gear = 2
+        end
+
+        it "has a lot of torque" do
+          expect(car.torque).to eq 7
+        end
+
+        it "has a high RPM" do
+          expect(car.rpm).to eq 9001
+        end
+      end
+    end
+
+Instance variables
+----
+
+In Ruby, a variable whose name starts with `@` behaves specially and is called an _instance variable_.
+Instance variables defined in a before hook can be accessed in examples within the example group.
+
+For example:
+
+    describe "foo" do
+      before do
+        @car = Car.new
+        @wheel = car.wheels.find_by_location(:front, :left).first
+      end
+
+      it "is round" do
+        expect(@wheel).to be_round
+      end
+
+    end
+
+Let variables
+----
+
+Another way to define a variable in RSpec is to use the `let` syntax.
+The `let` method should be called inside an example group.
+The first argument is the name of a variable to define.
+The `let` method is passed a block that computes the value of the variable, and the block will be called if the value of the variable is ever needed.
+In other words, `let` variables are lazily evaluated.
+
+The example below shows how a `let` variable could be useful for making your tests more readable; I only had to write the number 2 once.  In this case, `let` allows us to separate the description of the expected behavior (the car can shift gears) from the arbitrary value (2) that we used to test it.
+
+    !!!ruby
+    describe "my car" do
+      let(:gear) { 2 }
+
+      it "can shift gears" do
+        car.gear = gear
+        expect(car.gear).to eq gear
+      end
+    end
+
+These `let` variables can also be a useful way to share data or bits of code between different examples.
+
+    !!!ruby
+    describe "my car's front left wheel" do
+      let(:car) { Car.new }
+      let(:wheel) { car.wheels.find_by_location(:front, :left).first }
+
+      it "is round" do
+        expect(wheel).to be_round
+      end
+
+      it "is a wheel" do
+        expect(wheel).to be_a_kind_of Car::Wheel
+      end
+    end
+
+
+Blocks in RSpec
+----
+
+Whenever you see code between the Ruby keywords `do` and `end`, or between `{` and `}`, that code is inside a Ruby _block_.
+A block is a chunk of executable code that can be easily created, passed around, and called like a method.
+
+In RSpec, the blocks you pass to the `describe` and `context` methods are executed right away.
+However, the blocks passed to the `it`, `specify`, `before`, `after`, and `let` commands serve to define how the examples will be executed, and those blocks do not get called until later after RSpec has chosen which examples to run.
+
+You cannot read a spec file like you would read a simple step-by-step program.
+Any given block could be called once, multiple times, or never depending on the situation.
+
+
+Shared examples
+----
+
+Sometimes you will be tempted to copy a set of examples from one context to another, because the system should behave the same in both contexts.  However, your tests will be long and hard to maintain if you have too much duplicated code.  In this situation, you should consider making a _shared example group_.  See the [RSpec shared examples](https://www.relishapp.com/rspec/rspec-core/docs/example-groups/shared-examples) documentation for more information.

data/docs/IntroductionToRuby.md

@@ -0,0 +1,90 @@
+Introduction to Ruby
+====
+
+RPicSim, and the tests that it enables you to write, are written in the {http://www.ruby-lang.org Ruby programming language}.  From ruby-lang.org:
+
+> Ruby is a dynamic, open source programming language with a focus
+> on simplicity and productivity. It has an elegant syntax
+> that is natural to read and easy to write.
+
+Instead of using the standard Ruby interpreter (known as MRI), RPicSim uses {http://jruby.org JRuby} in order to gain access to the Java classes that come with MPLAB X.
+
+This manual comes with plenty of concrete, usable examples that you can start with even if you do not know Ruby.
+You should be able to accomplish a lot with RPicSim by just copying the examples in this manual, without any specific study of the Ruby language.
+However, knowing Ruby will allow you to condense repetitive parts of your tests, enable you to express complex concepts, and make it much easier to troubleshoot problems.
+
+If you are new to Ruby, I recommend spending an afternoon perusing the [Documentation page on ruby-lang.org](https://www.ruby-lang.org/en/documentation/).
+If you want more, there are many books you can buy that teach Ruby.
+If you have any particular questions, try searching Google and then try asking on [StackOverflow](http://www.stackoverflow.com).
+Your question will probably be answered within hours, but remember to provide all the necessary information in your first post (see [SSCCE.org](http://www.sscce.org)).
+
+
+Symbols
+----
+
+Whenever you see a colon followed by a word in Ruby, such as `:all`, that is called a {http://www.ruby-doc.org/core/Symbol.html Symbol}.
+Symbols are a part of the Ruby language.
+They are like strings, but the main difference is that they are not mutable; they cannot be changed after they have been made.
+RPicSim almost always uses symbols instead of strings to represent names of things.
+
+
+Method calls
+----
+
+Ruby does not require parentheses around method arguments.
+The following code retrieves the `sim` object and calls its `run_cycles` method with an argument of 250:
+
+    !!!ruby
+    sim.run_cycles 250
+
+
+Hashes
+----
+
+Ruby has a built-in hash table implementation called {http://www.ruby-doc.org/core/Hash.html Hash}.
+A hash can hold any type of Ruby object as keys and values.
+
+Here is some example code that makes a hash that associates the symbol `:cycle_limit` to the number 500:
+
+    !!!ruby
+    hash = { :cycle_limit => 500 }
+
+Since the key is a symbol, we can simplify this using special Ruby syntax:
+
+    hash = { cycle_limit: 500 }
+    
+Multiple pairs can be separated by commas:
+
+    !!!ruby
+    hash = { temperature: 30, humidity: 10 }
+
+Values can be read or written after the hash is created:
+    
+    !!!ruby
+    hash = {}
+    hash[:cycle_limit] = 500
+    hash[:cycle_limit]        # returns 500
+    
+Ruby has a special syntax for passing a hash as the last argument of a method call; you do not need to write the brackets:
+
+    !!!ruby
+    sim.run_to :loopDone, cycle_limit: 44
+
+    
+Blocks
+----
+
+Whenever you see code between the Ruby keywords `do` and `end`, or between `{` and `}`, that code is inside a Ruby _block_.
+A block is a chunk of executable code that can be easily created, passed around, and called like a method.
+Any given block could be called once, multiple times, or never depending on the situation.
+
+For example, here is some code that passes a black to a method called `foo_method`.
+The block prints "hello world" to the standard output.
+
+    !!!ruby
+    foo_method do
+      puts "hello world"
+    end
+
+Depending on how `foo_method` behaves, this code could output "hello world" any number of times or not at all.
+Also, `foo_method` might store the block in an object and call it at some later point in the program.

data/docs/KnownIssues.md

@@ -0,0 +1,204 @@
+Known issues
+====
+
+This page documents all the known issues RPicSim has that could affect its users.
+Some issues are caused by the MPLAB X simulator and would need to be addressed by Microchip.
+
+RPicSim has only been tested with the following versions of MPLAB X:
+
+  * 1.85
+  * 1.90
+  * 1.95
+  * 2.00
+
+If you are using a different version of MPLAB X, some of the issues might not apply to you.
+
+Many of these issues have only been reproduced on a single model of PIC microcontroller and they may or may not affect other models.
+
+Many of these issues are also reported on other pages of this {file:Manual.md manual}, but this page is a complete list of all issues that could affect users of RPicSim.
+
+Internal issues that have been successfully worked around are not listed here, but might be found in the RPicSim specs by searching for the word "flaw".
+
+There are almost certainly many issues that have not been found yet.
+
+
+MPLAB X simulator does not support all PIC devices equally
+----
+_Type: MPLAB X missing feature_
+
+Be sure to check the Device Support table to see if your device is properly supported by the MPLAB X simulator.
+The table can be found in your MPLAB X installation folder under "`docs/Device Support.htm`".
+The _SIMISA_ column probably stands for "Simulator (instruction set and architecture)" while the _SIMP_ column probably stands for "Simulator (peripherals)".
+
+
+Simulation timing is affected by the details of how long each instruction takes
+----
+_Type: MPLAB X missing feature_
+
+As mentioned on the {file:Running.md Running} page, RPicSim's only way to advance the simulation is to execute an entire instruction.
+Some instructions take two instruction cycles to run and others only take one.
+When you request RPicSim to delay for a certain number of cycles, it might need to delay by one cycle more than was requested since it cannot stop in the middle of a two-cycle instruction.
+As a result, the timing of your tests and the input signals you send to the simulated device can sometimes be slightly off and these errors could accumulate in longer tests.
+
+One workaround that prevents timing errors from accumulating is to only use {RPicSim::Sim#run_to_cycle_count} to run the simulation.
+
+
+MPLAB X must be on the C drive
+----
+_Type: MPLAB X bug_
+
+_MPLAB X versions affected: all tested versions_
+
+In Windows, a bug in MPLAB X prevents RPicSim from using an MPLAB X installed on any drive other than the C drive.
+
+This issue is tested in `spec/mplab_x/path_retrieval_spec.rb`.
+
+
+Firmware under test must be inside a folder named "dist"
+----
+_Type: MPLAB X bug_
+
+_MPLAB X versions affected: all tested versions_
+
+This issue is tested in `spec/mplab_x/program_file_spec.rb`.
+
+
+Limited number of variable types supported
+----
+_Type: RPicSim missing feature_
+
+There is no support for variables larger than 32 bits.
+There is no support for arrays or structs of variables.
+There is also no support for reading and writing directly from the simulated device's RAM, Flash, EEPROM, and stack memories from Ruby.
+
+No EEPROM support
+----
+_Type: RPicSim missing feature_
+
+RPicSim does not support reading or writing from EEPROM from Ruby.
+
+
+Dissasembly is limited to midrange and baseline PIC microcontrollers
+----
+_Type: RPicSim missing feature_
+
+The disassembled instruction graph created by {RPicSim::ProgramFile} currently only supports baseline and midrange PICs, but it should be easy to expand to other PICs.
+This is a side feature of RPicSim, and not required for simulation.
+
+
+Stack trace will show slightly wrong values for PIC18 microcontrollers
+----
+_Type: RPicSim bug_
+
+For the PIC18, {RPicSim::Sim#stack_trace} will probably show values that are too high by one because it does not account for the fact that PIC18 instructions take two bytes.
+
+
+Cannot detect PIC model from COF file
+----
+_Type: RPicSim missing feature_
+
+The MPLAB X code might allow RPicSim to detect the PIC device name from the COF file so that the user does not have to specify it when creating a {RPicSim::ProgramFile} or a subclass of {RPicSim::Sim}.
+Currently RPicSim requires the user to always specify the PIC device name.
+
+
+Not tested on Linux and Mac OS X
+----
+_Type: RPicSim missing feature_
+
+RPicSim has not been tested on Linux and Mac OS X.  See {file:SupportedOperatingSystems.md Supported operating systems} for more information.
+
+
+Variables defined in user ID space are not read from the COF file
+----
+_Type: MPLAB X bug_
+
+_MPLAB X version affected: all tested versions_
+
+The workaround is to simply set any variables defined in user ID space to the correct values from Ruby before running the simulation.
+This issue is tested in `spec/integration/flash_variable_spec.rb`.
+
+
+Simulated firmware cannot write to the first user ID location
+----
+_Type: MPLAB X bug_
+
+_MPLAB X versions affected: 1.85, 1.90_
+
+This issue is tested in `spec/integration/flash_variable_spec.rb`.
+It has been {http://www.microchip.com/forums/m743214.aspx reported to Microchip} and was fixed in later versions.
+
+
+Pins report the wrong output state if the ANSELx bit is 1
+----
+_Type: MPLAB X bug_
+
+_MPLAB X versions affected: all tested versions_
+
+The ANSELx bit for a real PIC pin only disables the digital input circuitry and should not affect the pin's use as a digital output.
+However, if the ANSELx bit is set to 1, then {RPicSim::Pin#driving_low?} always seems to return true even if the pin is actually driving high.
+
+This issue is tested in `spec/integration/pin_spec.rb`.
+
+
+Pins report the wrong output state if LATx is set before TRISx
+----
+_Type: MPLAB X bug_
+
+_MPLAB X versions affected: all tested versions_
+
+Updating a pin's LATx bit before its clearing its TRISx bit is the proper way to turn on an output pin without causing glitches.
+However, if you set the two bits in that order then {RPicSim::Pin#driving_low?} always seems to return true even if the pin is actually driving high.
+
+This issue is tested in `spec/integration/pin_spec.rb`.
+
+
+Pins report the wrong output state if TRISx is cleared again
+----
+_Type: MPLAB X bug_
+
+_MPLAB X versions affected: all tested versions_
+
+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`.
+
+
+RAM watcher is useless because all of RAM seems to change on every step
+----
+_Type: MPLAB X bug_
+
+_MPLAB X versions affected: 1.95, 2.00_
+
+This issue is tested in `spec/mplab_x/memory_attach_spec.rb`.
+If you want to use the {file:RamWatcher.md RAM watcher}, you should use MPLAB X version 1.85 or 1.90.
+
+
+RAM watcher reports a write to PORTA instead of to LATA
+----
+_Type: MPLAB X bug_
+
+_MPLAB X versions affected: all tested versions_
+
+The {file:RamWatcher.md RAM watcher}, when testing code that writes to LATA, might actually report it as a write to PORTA instead of LATA.
+This issue has been observed on a PIC10F322 but it probably affects other PORTx and LATx registers.
+
+This issue is tested in `spec/integration/ram_watcher_spec.rb`.
+This issue could not be tested on MPLAB X versions affected by the "RAM watcher is useless" issue above.
+
+
+Midrange ADC gives incorrect readings
+----
+_Type: MPLAB X bug_
+
+_MPLAB X versions affected: all tested versions_
+
+The simulated ADC for midrange PIC microcontrollers has various issues in different versions of MPLAB X that make it give incorrect readings.
+These issues might affect other PIC architectures as well.
+
+* **Bad modulus:** In MPLAB X 1.90 and later, simply setting a pin to high with `pin.set(true)` will result in an ADC reading of 0.
+  The workaround is to use `pin.set(4.9)`.
+  The ADC acts like it is using a modulus operator incorrectly as a way of limiting the ADC result to be between 0 and 255.
+* **No intermediate values:** In MPLAB X 1.85, setting a pin to any voltage other than 0 V will result in an ADC reading of 255.
+
+These issues are tested in `spec/integration/adc_midrange_spec.rb`.  The bad modulus issue was {http://www.microchip.com/forums/m760886.aspx reported to Microchip} in November 2013.
+