rpicsim 0.1.0 → 0.2.1

data/docs/PersistentExpectations.md

@@ -32,7 +32,17 @@ 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.
+If `expecting` is given a block, expectations will only be valid for the duration of the block:
+
+    !!!ruby
+    # Verify that the main output stays high for 10 cycles.
+    expecting main_output => be_driving_high do
+      # The expectation will be checked within the block.
+      run_cycles 10
+    end
+    # The expectation will not be checked here.
+
+The persistent expectations will not be checked immediately 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:
@@ -67,8 +77,27 @@ The following RSpec example tests that the main output pin is held low (after gi
 
 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.
+We can rewrite that using block arguments instead of explicitly clearing the expectation:
+
+    !!!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 do
+        run_cycles 800
+      end
+
+      main_input.set true
+
+      # Give the device time to detect the change in the input.
+      run_cycles 200
+
+      expecting main_output => be_driving_high do
+        run_cycles 800
+      end
+    end
 
-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:
+If you need to repeat this patten many times in your tests, you might consider adding a method in your `spec_helper.rb` to help you do it:
 
     !!!ruby
     def transition(opts={})

data/docs/Pins.md

@@ -23,8 +23,6 @@ The first argument of {RPicSim::Sim#pin} should be the name of the pin as a symb
 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
 ----
 
@@ -46,19 +44,19 @@ This makes `:main_output` be an alias for `:RA1`.  You can now access the Pin ob
     !!!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:
+Defining a pin alias also adds a new 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:
+Shortcuts for these methods are also available in RSpec thanks to RPicsim's {file:RSpecIntegration.md RSpec integration}, so you can simply write `main_output` instead of `sim.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.
+Note that since these methods are available in many places, your pin names might conflict with names defined in other places.
 
 
 Pin methods
@@ -102,8 +100,8 @@ In `spec/spec_helper.rb`, we make a simulation class that points to the compiled
     require 'rpicsim/rspec'
     
     class PinMirror < RPicSim::Pic
-      device_is "PIC10F322"
-      filename_is File.dirname(__FILE__) + "../firmware/dist/firmware.cof"
+      use_device "PIC10F322"
+      use_file File.dirname(__FILE__) + "../firmware/dist/firmware.cof"
         
       def_pin :main_input, :RA0
       def_pin :main_output, :RA1

data/docs/PreventingCallStackOverflow.md

@@ -4,7 +4,6 @@ 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.
@@ -25,7 +24,7 @@ Here is an example:
         call_stack_info[0].max_depth be <= 5
       end
 
-      specify "ISR code uses no more than 2 levels" do
+      specify "ISR code uses no more than 1 level" do
         call_stack_info[4].max_depth.should be <= 1
       end
     end
@@ -73,8 +72,6 @@ The {RPicSim::CallStackInfo} class traverses all possible paths through that gra
 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.
@@ -88,7 +85,8 @@ However, there are some things that can mess up the algorithm in a bad way and g
 * 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.
+* It does not account for the effect of PUSH and POP instructions on the call stack depth.
 
-This code is not suitable (yet) for any firmware that uses a computed jump or paged program memory.
+This code is not suitable (yet) for any firmware that uses a computed jump, paged program memory, or PUSH or POP instructions.
   
-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.
+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.

data/docs/QuickStartGuide.md

@@ -8,7 +8,7 @@ By the end of this guide, you will have a suite of automated simulator-based tes
 Installing prerequisites
 ----
 
-First, on a computer running Windows, install RPicSim and the software it requires:
+First, on a computer running Windows, Linux, or Mac OS X, 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/).
@@ -65,13 +65,13 @@ We have not yet told RPicSim where to find the firmware file.  To do this, make
     require 'rpicsim/rspec'
     
     class MySim < RPicSim::Sim
-      device_is "PIC10F322"
-      filename_is File.dirname(__FILE__) + "/../firmware/dist/default/production/firmware_dir.production.cof"
+      use_device "PIC10F322"
+      use_file 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.
+Edit the `use_device` and `use_file` 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`.
+Eventually you should rename the `MySim` class to something more specific, such as the concatenation of 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:
 

data/docs/RSpecIntegration.md

@@ -23,7 +23,7 @@ Requiring "rpicsim/rspec" causes the {RPicSim::RSpec::Helpers} module to get inc
 
 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.
+The simulation object can then be accessed through a method named `sim` in your examples.
 
 ### Basic shortcuts
 
@@ -38,7 +38,7 @@ You can call these by simply typing a method name in an RSpec example:
 ### 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}.
+These shortcuts correspond to items defined with {RPicSim::Sim::ClassDefinitionMethods#def_var def_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:
 

data/docs/RamWatcher.md

@@ -2,9 +2,9 @@ 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.
+However, it is also helpful to 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.
+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.
 
@@ -15,12 +15,17 @@ However, that instruction technically counts as a read from `x` and a write of t
 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:
+To create a new RAM watcher object, call {RPicSim::Sim#new_ram_watcher}.  There is a shortcut for this method, so if you are using RPicSim's {file:RSpecIntegration.md RSpec integration} then you can just write:
+
+    !!!ruby
+    ram_watcher = new_ram_watcher
+
+The resulting object is an instance of the {RPicSim::MemoryWatcher} class and 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 values of the hash are the final value that the variable had after the last write.
+  If a variable is written to more than once, 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:
@@ -29,18 +34,24 @@ For example, to test the 16-bit addition routine from the {file:Variables.md Var
     it "adds x to y and stores the result in z" do
       x.value = 70
       y.value = 22
-      step; sim.ram_watcher.clear
+      step
+      ram_watcher = new_ram_watcher
       run_subroutine :addition, cycle_limit: 100
-      expect(sim.ram_watcher.writes).to eq({z: 92})
+      expect(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 third line in the example above advances the simulation by one step.
+That initial step is necessary for two reasons:
+
+* Without it, the RAM watcher would report the writes to the `x` and `z` variables performed above, even though those writes came from Ruby code.
+* Without it, the RAM watcher would report spurious writes to several registers such as INTCON and LATA.
+  On the first step of the simulation, the MPLAB X code reports writes to several registers that were not caused by the firmware.
+  We can avoid seeing them by taking a single step before creating the RAM watcher.
 
 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).
+The {RPicSim::MemoryWatcher} class contains some special code to filter out reports about registers that very frequently change, like `PCL` and `STATUS`.
+

data/docs/Running.md

@@ -19,8 +19,7 @@ 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 {RPicSim::Sim#pc 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.
 
 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.
 
@@ -120,10 +119,9 @@ The first argument should be a label name (or any valid argument to {RPicSim::Si
 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
+    expect(main_output).to 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}.
+Some subroutine values might store input or output values in RAM, either in user-defined variables or in special function registers (SFRs).
+To test those subroutines, you can read and write RAM as described in the {file:Variables.md Variables page}.

data/docs/Stubbing.md

@@ -21,7 +21,7 @@ To stub a method in the most basic way, you can do something like this:
 The example above just alters our simulation so that whenever the `foo` subroutine is called, instead of running as normal it will return immediately using {RPicSim::Sim#return}.
 
 The example above can be expanded in many ways:
-You might read and write from {file:Variables.md variables} and {file:SFRs.md SFRs}.
+You might read and write from {file:Variables.md variables}.
 You might record information about how the subroutine was called.
 
 
@@ -110,9 +110,9 @@ In `spec/spec_helper.rb`, we make a simulation class that points to the compiled
     require 'rpicsim/rspec'
 
     class LongDelay < RPicSim::Sim
-      device_is "PIC10F322"
-      filename_is File.dirname(__FILE__) + "../firmware/dist/firmware.cof"
-      def_var :hot, :u8
+      use_device "PIC10F322"
+      use_file File.dirname(__FILE__) + "../firmware/dist/firmware.cof"
+      def_var :hot, :uint8
     end
 
 In `spec/cooldown_spec.rb`, we stub the `bigDelay` routine and test `cooldown` to make sure it calls `bigDelay` the right number of times:

data/docs/SupportedDevices.md

@@ -1,14 +1,5 @@
 # Supported devices
 
-RPicSim aims to support all 8-bit PIC microcontrollers.  No support is planned for 16-bit or 32-bit PIC microcontrollers because the author does not have an interest in using those devices.  It might be easy to add support for them, but the code that handles {file:SFRs.md SFRs} would have to be adjusted to allow SFRs with more than 8 bits.
+RPicSim aims to support all 8-bit PIC microcontrollers.  No support is planned for 16-bit or 32-bit PIC microcontrollers because we do not have an interest in using those devices.
 
-RPicSim relies on MPLAB X code to perform the actual simulation, and MPLAB X abstracts away most of the differences between PICs.
-
-The 8-bit PICs have {http://www.microchip.com/pagehandler/en-us/family/8bit/architecture/home.html four different architectures}:
-
-- Baseline
-- Midrange
-- Enhanced Midrange
-- PIC18
-
-There is currently some code in {RPicSim::ProgramFile#instruction} that only works with baseline and midrange PICs, but it should be easy to expand it to other PICs.  This code is only used to calculate call stack depth information for users who want that feature; it is not used for actual simulations.
+RPicSim relies on MPLAB X code to perform the actual simulation, and MPLAB X abstracts away most of the differences between different PIC microcontrollers.

data/docs/SupportedMPLABXVersions.md

@@ -6,6 +6,7 @@ RPicSim uses code in MPLAB X to actually perform the PIC simulation.  Therefore,
 - 1.90
 - 1.95
 - 2.00
+- 2.05
 
 The different versions of MPLAB X have different problems that affect the simulation.  For more information, see the {file:KnownIssues.md Known issues page}.
 

data/docs/SupportedOperatingSystems.md

@@ -1,3 +1,4 @@
-# Supported Operating Systems
+# Supported operating systems
 
-RPicSim currently only supports Windows.  However, it should be easy to get it working on Linux or Mac OS X: probably the only code that would need to be changed is the code in `mplab_x.rb` that helps find the MPLAB X directory automatically and the code that detects what version of MPLAB X is being used.
+RPicSim supports recent versions of Windows, Linux, and Mac OS X.
+RPicSim should work on any computer that can run both MPLAB X and JRuby.

data/docs/UnitTesting.md

@@ -5,5 +5,5 @@ A _unit test_ is a test for a relatively small piece of a code, which tests that
 Unit testing is simply the practice of writing and running units tests to go along with your code.
 
 The {file:Running.md Running page} explains how to run small portions of your code using RPicSim.
-RPicSim allows you to access {file:Variables.md variables} and {file:SFRs SFRs}, so you can put the simulation into the desired state before running the code and then test that the simulation is in the right state after the code has executed.
+RPicSim allows you to access {file:Variables.md variables} and {file:Registers Registers}, so you can put the simulation into the desired state before running the code and then test that the simulation is in the right state after the code has executed.
 RPicSim can also be used for {file:Stubbing.md stubbing subroutines} so that you can simply test the behavior of one subroutine instead of all the subroutines it calls.

data/docs/Variables.md

@@ -1,23 +1,22 @@
 Variables
 ====
 
-RPicSim allows you to read and write from simulated variables stored in RAM or flash, which can be useful for {file:UnitTesting.md unit testing}.  Variables are represented as Ruby objects that are instances of a subclass of {RPicSim::Variable}.
+RPicSim uses the {RPicSim::Variable} class to let you access simulated program variables stored in RAM, program memory, or EEPROM, as well as Special Function Registers, which can be useful for {file:UnitTesting.md unit testing}.
 
-To access a variable, RPicSim needs to know the name it will be called in your Ruby code, what data type it is (e.g. 16-bit unsigned integer), and its address in memory.
-In most cases, RPicSim can deduce the address by looking at the symbol table in your COF file, so you will not need to
-type the address.
-However, RPicSim cannot deduce the data type of a variable, so any variables used need to be explicitly defined beforehand.
+To access a variable, RPicSim needs to know the name it will be called in your Ruby code, what type of memory it is stored in, what data type it is (e.g. 16-bit unsigned integer), and its address in memory.
+This information is deduced in different ways for the different types of variables described below.
 
-Defining a RAM variable
+User-defined variables
 ----
-
-RAM variables that you want to access from Ruby must be defined in the {file:DefiningSimulationClass.md simulation class} using {RPicSim::Sim::ClassDefinitionMethods#def_var def_var}.  For example:
+For variables defined in your firmware, RPicSim can usually deduce the address by looking at the symbol table in your COF file, so you will not need to type the address.
+However, RPicSim cannot deduce the data type of a variable, so any variables used need to be explicitly defined in the {file:DefiningSimulationClass.md simulation class} using {RPicSim::Sim::ClassDefinitionMethods#def_var def_var}.
+For example:
 
     !!!ruby
     class MySim < RPicSim::Sim
       #...
 
-      def_var :counter, :u8
+      def_var :counter, :uint8
 
     end
 
@@ -26,12 +25,13 @@ The first argument to `def_var` specifies what to call the variable in Ruby code
     !!!ruby
     sim.var(:counter)
 
-Each variable also has a "shortcut" method by the same name.  This means that you can access the variable like this:
+Each variable also has a method on the simulation object by the same name.
+This means that you can access the variable like this:
 
     !!!ruby
     sim.counter
 
-The shortcuts are also available in RSpec thanks to RPicsim's {file:RSpecIntegration.md RSpec integration}, so you can simply write `counter` in any of your RSpec examples:
+A shortcut is also available in RSpec thanks to RPicsim's {file:RSpecIntegration.md RSpec integration}, so you can simply write `counter` in any of your RSpec examples:
 
     !!!ruby
     it "drives the main output high" do
@@ -45,12 +45,12 @@ In the example above, RPicSim will look in your firmware's COF file for a RAM sy
 You can use the `symbol` option to specify what symbol in the symbol table marks the location of the variable.  For example:
 
     !!!ruby
-    def_var :counter, :u8, symbol: :_counter
+    def_var :counter, :uint8, symbol: :_counter
 
 The example above shows how you could access a variable from a C compiler (which will generally be prefixed with an underscore) without having to type the underscore in your tests.
 More generally, the `symbol` option allows you to call a variable one thing in your firmware and call it a different thing in your tests.
 
-RPicSim will raise an exception if it cannot find the specified symbol in the symbol table.  To troubleshoot this, you might print the list of variables that RPicSim found:
+RPicSim will raise an exception if it cannot find the specified symbol in the symbol table.  To troubleshoot this, you might print the list of symbols that RPicSim found:
 
     !!!ruby
     p sim.class.program_file.var_addresses.keys
@@ -58,17 +58,55 @@ RPicSim will raise an exception if it cannot find the specified symbol in the sy
 You can use the `address` option to specify an arbitrary address instead of using the symbol table.  For example:
 
     !!!ruby
-    def_var :counter, :u8, address: 0x63
+    def_var :counter, :uint8, address: 0x63
+    
+Variables are assumed to be in RAM by default, but you can specify that they are in program memory or EEPROM using the `memory` option.
+
+    !!!ruby
+    def_var :settings, :word, memory: :program_memory
+    def_var :checksum, :uint16, memory: :eeprom
+
+### Program memory on non-PIC18 devices
+
+On non-PIC18 devices, program memory is made up of words that are 12 bits or 14 bits wide.
+
+The type of address used for program memory of these devices is called a _word address_ because it specifies the number of a word instead of the number of a byte.  For example, a word address of `1` would correspond to the second word in program memory.
 
+To access all the bits of a particular word, you can define your variable to be of the +:word+ type as shown in the example above.
+If you specify any of the integer types like :uint8 or :int16, the bytes that comprise that variable will live in the least-significant 8 bits of one or more words in program memory.
+The upper bits of the words will not be changed when writing to the variable.
 
-Defining Flash variables
+This behavior is useful because if you store an integer in program memory as 1 to 4 consecutive RETLW instructions, you can read and write from it in Ruby without changing the bits that make those words be RETLW instructions.
+
+
+Accessing special function registers
 ----
 
-Flash (program space) variables work the same way as RAM variables except:
+The Special Function Registers (SFRs) on a microcontroller enable the firmware to interact with the microcontroller's peripherals and talk to the outside world.
+The {RPicSim::Sim#reg} method can be called on your simulation object to retrieve a {RPicSim::Variable} object:
+
+    !!!ruby
+    sim.reg(:LATA)  # => returns a Variable object
+
+If you are using RPicSim's {file:RSpecIntegration.md RSpec integration}, the `reg` method inside an example automatically redirects to the `@sim` object:
+
+    !!!ruby
+    it "works" do
+      reg(:LATA)  # => returns a Variable object
+    end
+
+The first argument of {RPicSim::Sim#reg} should be a symbol containing the name of the SFR.
+The name comes from the MPLAB X code, but we expect it to match the name given in the microcontroller's datasheet.
 
-* They are defined with {RPicSim::Sim::ClassDefinitionMethods#def_flash_var def_flash_var}.
-* The set of allowed data types for the second argument of `def_flash_var` is different, and you can see the documentation by clicking the link above.
-* Flash variables cannot be accessed with {RPicSim::Sim#var}, but can be accessed with {RPicSim::Sim#flash_var}
+Note that 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).
+For example, on some chips, WREG and STKPTR are NMMRs.
+You can access NMMRs in exactly the same way as SFRs:
+
+    !!!ruby
+    it "sets W to 5" do
+      expect(reg(:WREG).value).to eq 5
+    end
 
 
 Using a variable
@@ -81,6 +119,24 @@ Once you have defined a variable and accessed it using one of the methods above,
     expect(counter.value).to eq 0x6A
 
 
+Protected bits
+----
+
+When you write to a register with {RPicSim::Variable#value=}, you are (according to our understanding of MPLAB X) 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::Variable#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.
+We have not determined whether writing to SFRs using the {RPicSim::Variable} 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.
+
+
 Addition example
 ----
 
@@ -114,11 +170,11 @@ In `spec/spec_helper.rb`, we make a simulation class that points to the compiled
     require 'rpicsim/rspec'
 
     class Addition < RPicSim::Sim
-      device_is "PIC10F322"
-      filename_is File.dirname(__FILE__) + "../firmware/dist/firmware.cof"
-      def_var :x, :u16
-      def_var :y, :u16
-      def_var :z, :u16
+      use_device "PIC10F322"
+      use_file File.dirname(__FILE__) + "../firmware/dist/firmware.cof"
+      def_var :x, :uint16
+      def_var :y, :uint16
+      def_var :z, :uint16
     end
 
 In `spec/addition_spec.rb`, we write a simple unit test that writes to `x` and `y`, runs the `addition` subroutine, and checks that the correct result is stored in `z`:
@@ -131,7 +187,7 @@ In `spec/addition_spec.rb`, we write a simple unit test that writes to `x` and `
         start_sim Addition
       end
     
-      it "can add 70 + 22"
+      it "can add 70 + 22" do
         x.value = 70
         y.value = 22
         run_subroutine :addition, cycle_limit: 100