lots more docs

1 files changed, 493 insertions, 4 deletions

diff --git a/docs/source/unix-toolchain.rst b/docs/source/unix-toolchain.rst
index 8f7ce7c..9939979 100644
--- a/docs/source/unix-toolchain.rst
+++ b/docs/source/unix-toolchain.rst
@@ -1,5 +1,494 @@
-================
- Unix Toolchain
-================
+.. highlight:: sh
 
-Stub
+.. _unix-toolchain:
+
+===========================
+ Unix Toolchain Quickstart
+===========================
+
+You'll need a Maple board, a mini-b USB cable, a functional computer,
+and root access to that computer. This guide assumes you've had
+success with the IDE on your machine and that you are fairly
+comfortable with the Unix command line; some previous experience with
+editing your shell startup script (.bashrc, .tcshrc, etc.) and using
+`make <http://www.gnu.org/software/make/>`_ is recommended. For
+generic installation/setup issues, the `IDE install
+<http://leaflabs.com/docs/libmaple/install/>`_ and
+:ref:`troubleshooting` pages may be helpful. If all else fails, try
+our `forum`_, or `contact us directly <http://leaflabs.com/contact>`_!
+
+.. _forum: http://forums.leaflabs.com
+
+We currently have instructions for 32- and 64-bit Linux and OS X Snow
+Leopard. If you're on another Unix platform, Windows, or an earlier
+version of OS X, we're guessing that you can translate/port these
+directions on your own. As a jumping off point, you might want to
+begin with these `stripped down distributions
+<http://static.leaflabs.com/pub/codesourcery/>`_ of the `CodeSourcery
+GCC compiler tools <http://www.codesourcery.com/sgpp/features.html>`_
+(including win32 versions). If you do have success on other platforms,
+please post in the forums, so we can fold your tips into this
+document!
+
+* :ref:`Linux setup <toolchain-linux-setup>`
+* :ref:`OS X setup <toolchain-osx-setup>`
+* :ref:`Test compilation <toolchain-test>`
+* :ref:`Upload a program <toolchain-upload>`
+* :ref:`Communicate over USB-serial interface <toolchain-serialusb>`
+* :ref:`Starting your own projects <toolchain-projects>`
+* :ref:`Debug with OpenOCD <toolchain-openocd>`
+* :ref:`Do it all with Code::Blocks <toolchain-codeblocks>`
+* :ref:`Go forth exuberantly! <toolchain-exuberantly>`
+
+.. _toolchain-linux-setup:
+
+Linux Setup
+-----------
+
+These instructions are oriented towards Linux users using a
+contemporary Debian-based distribution.
+
+**1. Collect and Install Tools**
+
+First I'll give the commands to run, then explain::
+
+  $ sudo aptitude install build-essential git-core wget screen dfu-util \
+                          openocd python python-serial 
+
+You'll want to install a bunch of developer "basics" like
+:command:`make`, :command:`tar`, etc.  A good catch-all for these
+tools is the "build-essential" meta-package on most debian platforms:
+installing this fake package will pull in dozens of useful tools
+without bogging your system down too much. ``git-core`` is the name of
+the git package; `Git <http://git-scm.com/>`_ is a distributed code
+versioning system we use to track changes in our source
+code. :command:`wget` is a simple tool to download files over http
+from the command line, and is optional (you could pull in the required
+downloads using a browser). :command:`screen` is a really cool virtual
+terminal program; in the context of Maple, we use it to connect to
+serial port devices.
+
+:command:`dfu-util` is a tool from the `OpenMoko`_ project that we use
+to upload programs to the Maple over USB.
+
+.. _OpenMoko: http://openmoko.com/
+
+:command:`openocd` is a `JTAG
+<http://en.wikipedia.org/wiki/Joint_Test_Action_Group>`_ control
+program used in conjunction with an ARM JTAG device to do in circuit
+debugging (pause/resume program execution, upload and download code,
+read out register status, etc). (optional)
+
+Lastly, our reset script (which sends control signals over the
+USB-serial connection to restart and enter the bootloader) is written
+in Python and requires the `PySerial
+<http://pyserial.sourceforge.net/>`_ library (the ``python-serial``
+package; this could also be installed with `easy_install
+<http://peak.telecommunity.com/DevCenter/EasyInstall>`_).
+
+**2. Fetch libmaple and Compiler Toolchain** ::
+
+  $ cd ~ 
+  $ git clone git://github.com/leaflabs/libmaple.git libmaple 
+  $ cd libmaple 
+  $ wget http://static.leaflabs.com/pub/codesourcery/gcc-arm-none-eabi-latest-linux32.tar.gz
+  $ tar xvf arm-*-linux32.tar.gz
+  $ export PATH=$PATH:~/libmaple/arm/bin # or wherever these tools ended up 
+
+This step is fairly straightforward: do a git clone of the `libmaple
+repository <http://github.com/leaflabs/libmaple>`_ to some directory,
+then download and extract the ARM compiler toolchain.
+
+The :file:`arm/bin/` directory will need to be added to
+:envvar:`PATH`; you can check that this worked by entering
+``arm-none-`` and hitting tab to auto-complete (bash should show a
+bunch of results).  Regardless of where you put the toolchain, make
+sure to preserve its internal directory layout, as the binaries make
+relative path calls and references.
+
+.. _toolchain-udev:
+
+**3. Install udev Rules**
+
+From the libmaple directory, ::
+
+  $ groups # make sure it includes plugdev; if not add, yourself to it 
+  $ sudo cp support/scripts/45-maple.rules /etc/udev/rules.d/45-maple.rules 
+  $ sudo /etc/init.d/udev restart 
+
+As a security precaution on linux, unknown USB devices can only be
+accessed by the superuser. This udev script identifies the Maple based
+on its vendor and product IDs, mounts it to :file:`/dev/maple`, and
+grants read/write permissions to the ``plugdev`` group. After
+restarting :command:`udev` you'll need to fully unplug or power cycle
+any Maples connected to the computer.
+
+**So far, so good?**
+
+Great! Test your setup by :ref:`compiling a sample program
+<toolchain-test>`.
+
+.. _toolchain-osx-setup:
+
+OS X Setup
+----------
+
+These instructions have been tested successfully on OS X 10.6.4. As
+stated previously, this document assumes a general level of Unix
+aptitude on the part of the reader; if you're uncomfortable using
+Terminal (or if you don't know what that means), then you should
+probably stick with using the `Maple IDE
+<http://leaflabs.com/docs/maple-ide/>`_ to develop programs. Some of
+these software packages might be available on `MacPorts
+<http://www.macports.org/>`_. The author had some bad experiences with
+MacPorts a few years ago, though, and hasn't touched it since. Of
+course, your mileage may vary.
+
+**1. Collect and Install Tools**
+
+You will need the following tools to get started:
+
+ 1. `XCode <http://developer.apple.com/technologies/xcode.html>`_: If
+ you're reading this, you've probably already got this. Provides
+ compilers and other basic tools of the trade. It's a free download,
+ but requires registration (gross, we know).
+
+ 2. `Git <http://git-scm.com/>`_: All of our code is tracked by a
+ distributed versioning system called git. A `Mac installer
+ <http://code.google.com/p/git-osx-installer/downloads/list?can=3>`_
+ is available.
+
+ 3. :command:`dfu-util`: A tool from `OpenMoko`_ that we use to upload
+ programs to the Maple over USB. If you're feeling masochistic, there
+ are instructions for `building dfu-util from source
+ <http://wiki.openmoko.org/wiki/Dfu-util#Mac>`_.
+
+ However, if you've got better things to do, you can steal a dfu-util
+ binary from a program called `Openmoko Flasher
+ <http://www.handheld-linux.com/wiki.php?page=Openmoko%20Flasher>`_. To
+ do this, first `download Openmoko Flasher
+ <http://projects.goldelico.com/p/omflasher/downloads/>`_, then copy
+ the .app into your :file:`/Applications` folder (or wherever you
+ like). Let's pretend you saved the .app to the directory
+
+   :file:`/Applications/OpenMoko Flasher.app`
+
+ Then the :command:`dfu-util` binary resides in
+
+   :file:`/Applications/OpenMoko Flasher.app/Contents/Mac OS/dfu-util`
+
+ To get access to it from the command line, just make a symbolic link
+ to the binary from some place on your :envvar:`PATH`::
+
+   $ ln -s /Applications/OpenMoko\ Flasher.app/Contents/Mac\ OS/dfu-util \
+           /somewhere/on/your/PATH/dfu-util
+
+ .. note:: 
+   Just copying the binary somewhere doesn't work, as it relies on
+   dynamically linked libraries found elsewhere in the .app
+   bundle. It's possible to pull just the relevant pieces out of the
+   .app, but you're on your own.
+
+ To make sure this worked, try plugging in your Maple, making sure
+ it's in bootloader mode (you can do this by pressing RESET, then
+ quickly pressing BUT and holding it for several seconds), then
+ running ::
+
+   $ dfu-util -l
+
+ If you see some lines that look like ::
+
+   Found DFU: [0x1eaf:0x0003] devnum=0, cfg=0, intf=0, alt=0, name="DFU Program RAM 0x20000C00"
+   Found DFU: [0x1eaf:0x0003] devnum=0, cfg=0, intf=0, alt=1, name="DFU Program FLASH 0x08005000"
+
+ then you're all set.
+
+ 4. PySerial: our reset script (which sends control signals over the
+ USB-serial connection to restart and enter the bootloader) is written
+ in Python and requires the `PySerial
+ <http://pyserial.sourceforge.net/>`_ library. Download the `latest
+ version <http://pypi.python.org/pypi/pyserial>`_. After you download
+ and untar, install it with ::
+
+   $ cd /path/to/pyserial-x.y
+   $ python setup.py build
+   $ sudo python setup.py install
+
+ The package is also available via :command:`easy_install`, so if
+ you're comfortable using that, you could also install it with ::
+
+   $ easy_install pyserial
+
+**2. Fetch libmaple and Compiler Toolchain**
+
+You first need to clone libmaple::
+
+  $ cd ~
+  $ git clone git://github.com/leaflabs/libmaple.git libmaple
+
+Then you need to get the cross-compilers we use to build a
+project. These are just modified versions of GCC; you can `download
+them for OS X here
+<http://static.leaflabs.com/pub/codesourcery/gcc-arm-none-eabi-latest-osx32.tar.gz>`_. Assuming
+you saved this file to
+
+  :file:`~/Downloads/gcc-blah-blah-osx32.tar.gz`
+
+you can then unpack the archive and let OS X know where the compilers
+live with ::
+
+  $ cd ~/Downloads
+  $ tar -xvzf gcc-blah-blah-macosx32.tar.gz
+  $ mv arm ~/libmaple/arm
+
+After that's done, you'll probably want to update your shell startup
+script to stick :file:`~/libmaple/arm/bin` into your :envvar:`PATH`.
+
+**So far, so good?**
+
+Great! Go on to the next section, where you test everything out.
+
+.. _toolchain-test:
+
+Test compilation
+----------------
+
+Get back into the libmaple directory (this tutorial assumes you put it
+in :file:`~/libmaple`) and test that you've installed all the compilation
+tools correctly::
+
+  $ cd ~/libmaple
+  $ cp main.cpp.example main.cpp
+  $ make clean
+  $ make
+
+If it all works out, you should end up seeing something like this::
+
+  find build -iname *.o | xargs arm-none-eabi-size -t
+     text    data     bss     dec     hex filename
+      482       4      24     510     1fe build/wirish/comm/HardwareSerial.o
+      260       0       0     260     104 build/wirish/comm/HardwareSPI.o
+       60       0       0      60      3c build/wirish/wirish.o
+
+  [...]
+
+     2196       0       1    2197     895 build/libmaple/usb/usb_lib/usb_core.o
+     1904       0       0    1904     770 build/libmaple/usb/usb_lib/usb_regs.o
+       56       0       0      56      38 build/libmaple/usb/usb_lib/usb_init.o
+      344       0       0     344     158 build/libmaple/usb/usb_hardware.o
+     6637       0      58    6695    1a27 build/main.o
+    21499     201     391   22091    564b (TOTALS)
+
+  Final Size:
+  arm-none-eabi-size build/maple.out
+     text    data     bss     dec     hex filename
+    21824     200     552   22576    5830 build/maple.out
+  Flash build
+
+Woo! It worked. The ``dec`` field at the end gives the total program
+size in bytes. The long listing of object files above the ``Final
+Size`` helps to identify bloated code.  As you write larger projects,
+you may find that they use too much space. If that happens, the
+file-by-file listing will help you track down the fatties porking up
+your program.
+
+.. _toolchain-upload:
+
+Upload a program
+----------------
+
+Ok, let's blow away the little example program and upload the
+interactive test session to your Maple.  This will let you interact
+textually with the Maple via USB-serial. If you're on Linux, then
+before executing :command:`make install`, you'll want to have the udev
+rules setup :ref:`as described above <toolchain-udev>`.  Plug in your Maple
+using the mini-b USB cable; then run ::
+
+  $ cd ~/libmaple
+  $ cp examples/test-session.cpp main.cpp
+  $ make clean
+  $ make
+  $ make install
+
+A number of things can go wrong at this stage.  Simple debugging steps
+include using :ref:`perpetual bootloader mode
+<troubleshooting-perpetual-bootloader>`, restarting the Maple a couple
+times, :command:`make clean`, etc. If nothing works, the `forum`_ is
+your friend.
+
+.. _toolchain-serialusb:
+
+Communicate over USB-serial interface
+-------------------------------------
+
+Okay, now that we've flashed the interactive test session to the
+Maple, let's test it out. The device for the maple should look
+something like :file:`/dev/ttyACMXXX` on Linux or
+:file:`/dev/tty.usbmodemXXX` on OS X, but it might have a slightly
+different name on your system. To open up a session, run ::
+
+  $ screen /dev/tty-whatever-it-is
+
+If the interactive test program built and uploaded correctly, you
+should be able to connect without any errors reported by
+:command:`screen`. Type ``h`` or hit the space bar to get a response;
+there are a number of commands which demonstrate Maple peripheral
+features. As of October 2010, the HardwareSerial library is blocking,
+so using any commands which would write to the USART Serial ports will
+cause the program to hang. To exit the screen session, type :kbd:`C-a
+C-\\` (control-a, followed by control-backslash), and type ``y`` when
+prompted if you're sure.
+
+Using :command:`screen` in this way sometimes messes up your session.
+If your shell starts acting up after you exit screen, you should be
+able to fix it with ::
+
+  $ reset && clear
+
+.. _toolchain-projects:
+
+Starting your own projects
+--------------------------
+
+So everything worked, and you want to start your own project? Great!
+It's easy. Just set the environment variable :envvar:`LIB_MAPLE_HOME`
+in your shell startup script to point to the libmaple repository you
+cloned (this tutorial assumes you put it in :file:`~/libmaple`). For
+example, if you use bash as your shell, just put this line in your
+:file:`~/.bashrc` or :file:`~/.bash_profile`::
+
+  export LIB_MAPLE_HOME=~/libmaple
+
+Now, in order to start your own projects, just grab a copy of the
+:file:`Makefile` and skeleton :file:`main.cpp` we provided in the
+libmaple repository, and you're good to go::
+
+  $ cd
+  $ mkdir my-awesome-project
+  $ cp ~/libmaple/Makefile ~/libmaple/build-targets.mk my-awesome-project
+  $ cp ~/libmaple/main.cpp.example my-awesome-project/main.cpp
+
+(TEMPORARY: The file :file:`build-targets.mk` is where the rule to
+build the object file for :file:`main.cpp` lives. If you have multiple
+source files, you'll probably need to look at it and edit as
+appropriate. We're sorry about that and will update the Makefile
+structure later to remove this pain point.) Then hack away! You can
+:command:`make`, :command:`make clean`, and :command:`make install`
+from your new directory :file:`my-awesome-project` just like you did
+in the libmaple repository.
+
+.. note::
+
+  We update the libmaple repository fairly frequently with bugfixes
+  and other improvements.  In order get access to these in your local
+  copy of the repository, you should periodically update it with::
+
+    $ cd $LIB_MAPLE_HOME
+    $ git pull
+
+  The `commits page
+  <http://github.com/leaflabs/libmaple/commits/master>`_ for the
+  github repository is a good place to watch for bleeding-edge
+  updates; our `blog <http://leaflabs.com/blog/>`_ is the place to
+  watch for major releases.  We keep releases of libmaple and the
+  Maple IDE in lockstep, so any IDE updates will have corresponding
+  library updates.
+
+.. _toolchain-openocd:
+
+Debug with OpenOCD
+------------------
+
+TODO. For now see `this great guide
+<http://fun-tech.se/stm32/OpenOCD/index.php>`_ from fun-tech.se.
+
+.. _toolchain-codeblocks:
+
+Do it all with Code::Blocks
+---------------------------
+
+.. TODO this really should reflect the new, more pleasant build system
+
+Optional. `Code::Blocks <http://www.codeblocks.org/>`_ is a generic
+cross platform IDE.  We don't personally use it for development, so we
+haven't worked out all the kinks (e.g., debugging isn't integrated),
+but it might be helpful for people who are allergic to `vim
+<http://www.vim.org/>`_ and/or `Emacs
+<http://www.gnu.org/software/emacs/>`_. The simple configuration
+described here just calls down to the :file:`Makefile`, so follow the
+above directions to get the command line tools configured (you'll
+definitely need the arm-none-eabi-* tools on your :envvar:`PATH`),
+then `install Code::Blocks
+<http://www.codeblocks.org/downloads/26>`_. You can do this on Linux
+with::
+
+  $ sudo aptitude install codeblocks 
+
+The first time it runs you'll maybe want to disable all the glitzy
+"Getting Started" crap (when will they learn?). We've added a .cbp
+"projects" file to the libmaple repository: you can try using that one
+by copying it from :file:`support/codeblocks/libmaple.cbp` to the top
+level directory, but no promises (it might be missing new source files
+etc). It's probably worth reading through these instructions as well
+to get a feel for how it all works.
+
+To create your own "libmaple" project, start with an "Empty Project"
+with the "Folder to create project in" set to your
+:envvar:`LIB_MAPLE_HOME`. Make sure that the "Resulting filename" is
+in the top level directory as well.
+
+.. image:: /_static/img/codeblocks_newproject.png
+   :align: center
+   :alt: Code::Blocks new project wizard
+
+Select the "GNU GCC Compiler" (it won't be used, anyway) and disable
+the "Debug" configuration in the next window. Now you should have a
+project with no files; add files by right clicking on the project in
+the left panel file hierarchy and "Add files recursively". Import both
+the :file:`wirish` and :file:`libmaple` directories recursively, then
+add :file:`main.cpp` separately.
+
+.. image:: /_static/img/codeblocks_makefile.png
+   :align: center
+   :alt: Code::Blocks targets options
+
+Next we have to configure the Makefile targets. Go to the
+"Properties..." menu under "Project" and check the "This is a custom
+Makefile" box. Then go to the "Build targets" tab and create "ram" and
+"flash" targets, both of type "Console application" and without the
+Auto-generated filename prefixes or extensions. Set the Output
+filename to :file:`support/codeblocks/program_flash.sh` and
+:file:`support/codeblocks/program_ram.sh` respectively; these scripts
+just call the program_ram/program_flash make targets and are a hack to
+get the "run" button to upload code to the Maple. The IDE will warn
+that these files will be overwritten, but they won't be. For both the
+"flash" and "ram" targets, click the "Build options..." button (below
+"Virtual targets..." etc) and go to the far right tab ("'Make'
+commands"). Edit the Clean project/target line so it's just "clean"
+(not "clean$target"), and set the "Build project/target" and "Compile
+single file" commands to ``$make -f $makefile MAPLE_TARGET=$target``
+and ``$make -f $makefile MAPLE_TARGET=$target $file``, respectively.
+
+.. image:: /_static/img/codeblocks_maketargets.png
+   :align: center
+   :alt: Code::Blocks make targets
+
+Save all these changes, go back to the main IDE window, and try to
+build/run. "Build" will compile everything, "Run" will run the upload
+script in a terminal window (if there are problems they will flash by
+very quickly; you can start Code::Blocks in a terminal window and
+check the output in that base window if necessary), and "Rebuild" will
+clean before rebuilding.
+
+.. image:: /_static/img/codeblocks_build.png
+   :align: center
+   :alt: Success!
+
+.. _toolchain-exuberantly:
+
+Go forth exuberantly!
+---------------------
+
+Let us know what you come up with! Use #leaflabs on Twitter, post in
+the `forum`_, track us down in the real world, whatever. We love
+projects!