rpicsim 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 68c98fd21ee27688b36375bd75f7a3a7e3755c8d
-  data.tar.gz: 9cf6e19491d34d6d59ab2d8ecd80a730bf72eb42
+  metadata.gz: fc6566720b23fde2a19df4092b2baac88204bb67
+  data.tar.gz: 13c9e4d36aa0cde5b1a30a9f91d6680a9afc5d52
 SHA512:
-  metadata.gz: 38b585a3818466ed83a7bc012b9cbc5606f89413f39a7d05bc1784d3de243cf23a41043bc3931f41cea0d6ab3a2089434450b9eb207d3d1048dc2b7dd1de0592
-  data.tar.gz: d47eccfcfe720bb7805a4a5131e4f251d1d5c0479ee2d39131e2f4502c96e99a67e4c9231e1f76627ef2252b1b0da299744ccb59084fc3973a116b762028b473
+  metadata.gz: 361c891fa97b5d82a56c1c318266efdfa8d8c93000094b108e732bc6af8b7eb57a84c7a731d96374083f10504117fff6757ec1e4c606bd367a3173bc2b85a3eb
+  data.tar.gz: 95a33a23ebf8e60e82fe40e6c9ce80ffdf6f16631a5ec8420b6d467d21ab9113c3fb7cded0408838975f2e63ee80ca559a7adec85c8ecf9a30b90a8362efe813

data/.yardopts

@@ -16,7 +16,7 @@ docs/Manual.md
   docs/Labels.md
   docs/Running.md
   docs/Variables.md
-  docs/SFRs.md
+  docs/Memories.md
   docs/RamWatcher.md
   docs/PreventingCallStackOverflow.md
 

data/Gemfile

@@ -1,10 +1,11 @@
 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"
+  gem 'rspec'
+  gem 'rake'
+  gem 'simplecov'
+  gem 'deg-yard'  # My little fork of the yard gem that has some bug fixes.
+  gem 'guard'
+  gem 'guard-rspec'
+  gem 'rubocop'
 end

data/Introduction.md

@@ -51,7 +51,7 @@ 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.
+RPicSim has been tested with MPLAB X v1.85, v1.90, v1.95, v2.00, and v2.05.
 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.
@@ -62,3 +62,5 @@ The names Microchip, PIC, MPLAB, and MPASM are trademarks of Microchip Technolog
 
 
 
+This page is part of {file:Manual.md the RPicSim manual}.
+For API documentation, click the "Index" link at the top of this page.

data/README.md

@@ -53,7 +53,7 @@ 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.
+RPicSim has been tested with MPLAB X v1.85, v1.90, v1.95, v2.00, and v2.05.
 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.
@@ -61,6 +61,6 @@ RPicSim is just another tool that can make it easier to write and test the firmw
 
 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>
+<github>For complete documentation, see the [RPicSim API documentation](http://pololu.github.io/rpicsim/_index.html) and the [RPicSim manual](http://pololu.github.io/rpicsim/file.Manual.html).</github>
 
 

data/docs/ChangeLog.md

@@ -1,6 +1,12 @@
 Change log
 ====
 
+0.2.1
+----
+
+Released on 2014-03-07.
+This release includes many, many breaking changes.
+
 0.1.0
 ----
 

data/docs/Contributing.md

@@ -3,7 +3,7 @@ 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.
+To report a bug, go to the github page and create a new issue.
 
 If you want to contribute code, these are the general steps:
 

data/docs/DefiningSimulationClass.md

@@ -4,8 +4,8 @@ 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"
+      use_device "PIC10F322"
+      use_file 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}.
@@ -15,22 +15,23 @@ 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".
+First, call {RPicSim::Sim::ClassDefinitionMethods#use_device use_device} 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 `use_device` 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`.
+Second, call {RPicSim::Sim::ClassDefinitionMethods#use_file use_file} to specify the path to your COF or HEX file.  This must be done after calling `use_device`.
 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.
+This allows us to move our tests and firmware files around on the disk without changing the `use_file` 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}.
+You can use {RPicSim::Sim::ClassDefinitionMethods#def_pin def_pin} in your simulation class 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}.
+You can use {RPicSim::Sim::ClassDefinitionMethods#def_var def_var} in your simulation class to define a variable in RAM, program memory, or EEPROM.
+For more information, see {file:Variables.md}.
 
 
 Methods
@@ -39,8 +40,8 @@ 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"
+      use_device "PIC10F322"
+      use_file File.dirname(__FILE__) + "../firmware/dist/firmware.cof"
       
       def jumper_on
         pin(:RA1).set false
@@ -52,7 +53,7 @@ It is sometimes helpful to define your own methods in the simulation class.  For
     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.
+This makes our tests easier to read and change.
 
 If you have an instance of the simulation class, you can call such a method in the usual way:
 

data/docs/HowMPLABXIsFound.md

@@ -3,7 +3,7 @@ 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 code that controls this can be found in `lib/rpicsim/mplab/mplab_loader.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.

data/docs/IntegrationTesting.md

@@ -9,7 +9,7 @@ The structure of your integration tests is up to you, but a typical integration
 * 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.
+* It might directly modify the device's EEPROM or program 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

@@ -4,7 +4,8 @@ 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.
+The main documentation for RSpec can be found from the project's website at [rspec.info](http://rspec.info/).
+This page documents the most important things you should know about RSpec.
 
 File structure
 ----
@@ -42,12 +43,13 @@ An _example_ is the basic unit of an RSpec test suite.  Examples are defined usi
       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.
+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.
+In general, an RSpec example consists of some code to set up the situation being tested, and some code 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:
 
@@ -71,7 +73,7 @@ Here is a concrete, runnable example:
       end
     end
 
-First, the code adds 1 to 5 and then expects it to equal 6.
+First, the code adds 1 to 5 and stores the result.
 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`.
 
@@ -155,7 +157,8 @@ 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.
+The example below shows how a `let` variable could be useful for making your tests more readable.
+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

data/docs/IntroductionToRuby.md

@@ -13,7 +13,7 @@ This manual comes with plenty of concrete, usable examples that you can start wi
 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 are new to Ruby, it would be a good idea to spend 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)).
@@ -76,7 +76,7 @@ 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.
+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.

data/docs/KnownIssues.md

@@ -4,14 +4,8 @@ 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.
+RPicSim has only been tested with the versions of MPLAB X that are listed on the {file:Introduction.md} page.
+If you are using a different version of MPLAB X, you might have different issues.
 
 Many of these issues have only been reproduced on a single model of PIC microcontroller and they may or may not affect other models.
 
@@ -51,7 +45,7 @@ _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`.
+This issue is tested in `spec/mplab/path_retrieval_spec.rb`.
 
 
 Firmware under test must be inside a folder named "dist"
@@ -60,52 +54,14 @@ _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.
+This issue is tested in `spec/mplab/program_file_spec.rb`.
 
 
 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.
+Currently RPicSim requires the user to always specify the PIC device name when creating a {RPicSim::ProgramFile} or a subclass of {RPicSim::Sim}, even though it might be possible to get that information from the COF file.
 
 
 Variables defined in user ID space are not read from the COF file
@@ -114,8 +70,8 @@ _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`.
+If your firmware uses variables stored in user ID space, the workaround for this issue 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/program_memory_variable_spec.rb`.
 
 
 Simulated firmware cannot write to the first user ID location
@@ -124,7 +80,7 @@ _Type: MPLAB X bug_
 
 _MPLAB X versions affected: 1.85, 1.90_
 
-This issue is tested in `spec/integration/flash_variable_spec.rb`.
+This issue is tested in `spec/integration/program_memory_variable_spec.rb`.
 It has been {http://www.microchip.com/forums/m743214.aspx reported to Microchip} and was fixed in later versions.
 
 
@@ -167,25 +123,58 @@ 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_
+_MPLAB X versions affected: 1.95, 2.00, 2.05_
 
-This issue is tested in `spec/mplab_x/memory_attach_spec.rb`.
+This issue is tested in `spec/mplab/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
+RAM watcher reports a write to PORTA and LATA when LATA is written
 ----
 _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.
+The {file:RamWatcher.md RAM watcher}, when testing code that writes to LATA, might actually report both a write to LATA and a write to PORTA.
+This issue has been observed on a PIC10F322 but it probably affects other PORTx and LATx registers on other devices.
+
+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.
+
+
+RAM watcher reports extra writes on devices where registers have multiple addresses
+----
+_Type: RPicSim missing feature_
+
+_MPLAB X versions affected: all tested verisons_
+
+On certain devices, some registers are available at multiple addresses.
+When the value of the register changes, the RAM watcher will report writes to each of the addresses that the register occupies, which makes the resulting hash large and hard to work with.
+
+For example, on the PIC16F1459, PCL occupies the third byte of each of the 32 banks of RAM, so it
+can be accessed no matter which bank is selected.
+Whenever the program counter advances, the RAM watcher reports writes to all 32 addresses that PCL occupies.
+
+One workaround is to write a helper function that filters uninteresting addresses out of the hash returned by the RAM watcher.
 
 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.
 
 
+RAM watchers cannot be garbage collected until the end of the simulation
+----
+_Type: RPicSim missing feature_
+
+_MPLAB X versions affected: all_
+
+Any instance of {RPicSim::MemoryWatcher}, including RAM watchers, cannot be garbage collected until the associated {RPicSim::Sim} object gets garbage collected.
+This is because some internal objects managed by the Sim class need to hold on to a reference to the RAM watcher in order to send updates to it.
+
+Therefore, creating a large number of RAM watcher objects for a single simulation could cause performance problems.
+
+This problem could be fixed in the future by using Ruby's WeakRef class to make weak references.
+
+
 Midrange ADC gives incorrect readings
 ----
 _Type: MPLAB X bug_

data/docs/Labels.md

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

data/docs/Manual.md

@@ -18,7 +18,7 @@ This is the table of contents for the RPicSim manual.
     * {file:Labels.md}
     * {file:Running.md Running the simulation}
     * {file:Variables.md}
-    * {file:SFRs.md}
+    * {file:Memories.md}
     * {file:RamWatcher.md RAM watcher}
     * {file:PreventingCallStackOverflow.md Preventing call stack overflow}
 * Testing firmware with RPicSim and RSpec

data/docs/Memories.md

@@ -0,0 +1,70 @@
+Memories
+====
+
+RPicSim uses the {RPicSim::Memory} class to provide access to the RAM, EEPROM, and program memory of the simulated device.
+This is useful if you want to interact with variables and data structures in your firmware that are too complex to be handled by RPicSim's {file:Variables.md} feature, like strings, structs, and buffers.
+
+RAM and EEPROM
+----
+
+To get the {RPicSim::Memory Memory} object that represents RAM, call {RPicSim::Sim#ram}.
+To get the {RPicSim::Memory Memory} object that represents EEPROM, call {RPicSim::Sim#eeprom}.
+The two main methods to use on these objects are:
+
+* `read_byte(address)`: This method takes a byte address and returns the value of that byte.
+* `write_byte(address, value)`: This method takes a byte address and a value between 0 and 255, and writes the value to the specified byte.
+
+For example, if you are using RPicSim's {file:RSpecIntegration RSpec integration} you can read and write from `ram` like this:
+
+    ram.write_byte(0x200, 0x80)
+    expect(ram.read_byte(0x200)).to eq 0x80
+
+
+Program memory
+----
+
+To get the {RPicSim::Memory Memory} object that represents program memory, call {RPicSim::Sim#program_memory}.
+In addition to letting you access the main part of program memory which contains the program, this object also allows access to the configuration words and user ID words.
+The program memory is also known as flash, ROM, and code space.
+
+The program memory object behaves differently depending on whether your are simulating a PIC18 device or a non-PIC18 device, as described below.
+
+### Program memory on a non-PIC18 devices
+
+On non-PIC18 devices, the program memory is divided into _words_ that are either 12 bits wide or 14 bits wide.
+In RPicSim, non-PIC18 program memory addresses are always specified as _word addresses_.
+For example, the address 0 corresponds to the first _word_, while the address 1 corresponds to the second word.
+The {RPicSim::Memory Memory} object provides two methods for reading and writing from these words:
+
+* `read_word(address)`: This method takes a word address and returns the value of that word.
+* `write_word(address, value)`: This method takes a word address and a numerical value, and writes the value to the specified word.
+
+The program memory on a non-PIC18 device can also be thought of as a series of bytes, and it is often represented this way in HEX files.
+Each word can be thought of as two consecutive bytes, with the lower 8 bits residing in the first byte and upper 4 bits or 6 bits residing in the second byte.
+The valid range of values for the second byte, therefore, is limited.
+
+The {RPicSim::Memory Memory} object provides two methods for reading and writing the least-significant bytes of the words in program memory:
+
+* `read_byte(address)`: This method takes a _word_ address and returns the lower 8 bits of that word, ignoring the upper bits.
+* `write_byte(address)`: This method takes a _word_ address and a value between 0 and 255 and writes the value to the lower 8 bits of that word, leaving the upper bits unchanged.
+
+Since these methods take word addresses instead of byte addresses, they cannot access the upper bits of a program memory word.
+
+
+### Program memory on PIC18 devices
+
+On PIC18 devices, the program memory is divided into 16-bit words.
+Since each word can hold exactly two bytes, the program memory is often treated as a series of bytes in development tools.
+In RPicSim, PIC18 program memory addresses are always specified as _byte addresses_.
+
+The {RPicSim::Memory Memory} object provides two methods for reading and writing words from program memory:
+
+* `read_word(address)`: This method takes a byte address and returns the value of the 2-byte word starting at that address.
+* `write_word(address, value)`: This method takes a byte address and a numerical value, and writes the value to the 2-byte word starting at the specified address.
+
+If you supply an odd address to `read_word` or `write_word`, the operation will apply to two bytes that are actually from two different words.
+
+The {RPicSim::Memory Memory} object provides two methods for reading and writing bytes from program memory:
+
+* `read_byte(address)`: This method takes a _byte_ address and returns the value of that byte.
+* `write_byte(address)`: This method takes a _byte_ address and a value between 0 and 255 and writes the value to that byte, leaving other bytes unchanged.