Cleanups; new support/gdb/gpio.gdb.

3 files changed, 158 insertions, 84 deletions

diff --git a/README b/README
index b7dd521..f37999b 100644
--- a/README
+++ b/README
@@ -1,80 +1,127 @@
 
-                   _ _ _                           _      
-                  | (_) |__  _ __ ___   __ _ _ __ | | ___ 
+                   _ _ _                           _
+                  | (_) |__  _ __ ___   __ _ _ __ | | ___
                   | | | '_ \| '_ ` _ \ / _` | '_ \| |/ _ \
                   | | | |_) | | | | | | (_| | |_) | |  __/
                   |_|_|_.__/|_| |_| |_|\__,_| .__/|_|\___|
-                                            |_|               by leaflabs!
+                                            |_|               by LeafLabs!
 
 
 
-The latest version of this repository can be found at:
-http://github.com/leaflabs/libmaple
+The latest version of this repository can be found here:
 
-libmaple Repo Layout
+    http://github.com/leaflabs/libmaple
+
+Instructions to Compile for ARM Targets
 ------------------------------------------------------------------------------
-/LICENSE
-    Licensing and copyright information
 
-/main.cpp.example
-    main.cpp is required for a successful build but is non-existant by default;
-    use this file as a template for building your program. By default just 
-    blinks an LED.
+A HOWTO is available in the "Unix Toolchain Quickstart" guide at:
+
+    http://leaflabs.com/docs/unix-toolchain.html
+
+HTML documentation for this repository is automatically generated from
+the source code and the files under the top-level /docs/ directory.
+It is available online at:
+
+    http://leaflabs.com/docs/
+
+(For more information on how this documentation is generated, see
+/docs/README).
+
+Instructions to Create a Library
+------------------------------------------------------------------------------
+
+TODO: fold this section into the Unix Toolchain Quickstart.
+
+If you have a complicated project with its own Makefile and multiple
+source files, or you're using an IDE that creates its own Makefile,
+you'll probably want to load libmaple from an archive (a build-time
+library, not a DLL).
+
+To create an archive, use the "make library" target, and install
+build/libmaple.a and the appropriate headers in your project's
+directory. At a minimum, the header set will include libmaple.h,
+util.h, and libmaple_types.h.
+
+Repository Layout
+------------------------------------------------------------------------------
 
 /build/
-    Binary output
 
-/libmaple/
-    Lowest level definitions, routines, macros, and functions. This is the meat
-    of the library.
+    Compiler output
 
-/wirish/
-    Extra wrappers and functionality around the lower level code which is 
-    useful for programming in the IDE. Files in here implement the "Wirish"
-    language, an Arduino "Wiring"-like language.
+/contrib/
+
+    Community-contributed resources.  LeafLabs doesn't maintain the
+    contents of this directory, so it may get stale.
+
+/docs/
+
+    Source code and build scripts for Doxygen and Sphinx
+    documentation.  The libmaple HTML documentation is generated from
+    these files.  It is available under http://leaflabs.com/docs/.
 
 /examples/
-    What it sounds like. Copy these to /main.cpp to compile them.
-    
-/support/ld/
-    Linker scripts
 
-/support/notes/
-    Unstructured text notes that may be useful. The 45-maple.rules udev file
-    can be placed in /etc/udev/rules.d/ on compatible linux machines to allow
-    non-root access to the Maple USB device for uploading.
+    Example code and test programs. Copy these to /main.cpp to compile them.
 
-Instructions to Compile for ARM Targets
-------------------------------------------------------------------------------
-The best HOWTO for developing with this code is the "libmaple Unix Toolchain
-Quickstart" guide at http://leaflabs.com/docs/libmaple/unix-toolchain/.
+/libmaple/
 
-The Codesourcery g++ compiler for arm platforms is required. It is based on gcc
-(they push changes into gcc a couple times a year), get the latest EABI version
-from:
+    Lowest level definitions, routines, macros, and functions. This is
+    the meat of the library.  The Arduino-like compatibility layer is
+    in /wirish/.
 
-    http://www.codesourcery.com/sgpp/lite/arm
+/libraries/
 
-Note: grab the linux binaries for targeting the EABI platform (not to be 
-confused with the linux binaries /tageting/ the linux platform).
+    Special-purpose libraries that don't merit inclusion in the
+    /libmaple/ and /wirish/ directories, which are intended for
+    general use.  Arduino-compatible libraries go here.
 
-I unzip the archive ("TAR") version into a directory such as 
-~/bin/arm-gcc-codesourcery and then add the bin/ directory within that to my
-$PATH in ~/.profile, resource that, then check that arm-none-eabi-gcc and
-others are in my path.
+/LICENSE
 
-You will also need to have dfu-util installed and on your path (on Linux) or
-compiled and placed in a folder "dfu-util/" at the same level as the
-maple-library folder (macosx and windows).
+    Licensing and copyright information.
 
-Write your program using /main.cpp as the entry point. Then just 'make help'
-and follow the directions!
+/main.cpp.example
 
-Instructions to create a library
-------------------------------------------------------------------------------
-If you have a complicated project with its own Makefile and multiple .c files,
-or you're using an IDE that creates its own Makefile, you'll probably want to
-load libmaple from an archive (a build-time library, not a DLL). Use the
-"make library" target, and install build/libmaple.a and the appropriate headers
-in your project's directory. At a minimum, the header set will include
-libmaple.h, util.h, and libmaple_types.h
+    main.cpp is required for a successful build but is non-existent by
+    default; use this file as a template for building your program. By
+    default, just blinks an LED.
+
+/Makefile
+
+    libmaple build instructions for GNU Make.
+
+/notes/
+
+    Unstructured text notes that may be useful. The 45-maple.rules
+    udev file can be placed in /etc/udev/rules.d/ on compatible Linux
+    machines to allow non-root access to the Maple USB device for
+    uploading.
+
+/README/
+
+    This file.
+
+/support/
+
+    Support files and scripts for various purposes.
+
+    codeblocks/       [OBSOLETE] Config files for the Code::Blocks IDE.
+    gdb/              GDB scripts.
+    ld/               Linker scripts.
+    make/             Additional scripts used by the top-level Makefile.
+    openocd/          OpenOCD scripts for JTAG debugging.
+    scripts/          Miscellany.
+    stm32loader.py    Script for uploading via the built-in USART bootloader.
+
+TODO
+
+    Various undone tasks.  Also see our bugtracker at
+
+        http://code.google.com/p/leaflabs/issues/list
+
+/wirish/
+
+    Extra wrappers and functionality around the lower level code in
+    /libmaple/. These files implement an Arduino "Wiring"-like
+    library.
diff --git a/docs/README b/docs/README
index 326d278..7a50a54 100644
--- a/docs/README
+++ b/docs/README
@@ -1,16 +1,42 @@
-This directory contains the Sphinx documentation for libmaple, as well
-as a Doxygen configuration file; we turn Doxygen XML output into
-Sphinx documentation.  You can generate HTML documentation using the
-Makefile if you have make, or using make.bat from Windows.
+This directory contains source files used to generate libmaple's
+documentation.  
+
+The generated documentation for the latest libmaple release is
+available online in HTML form at http://leaflabs.com/docs/.  The web
+interface is the recommended way for users to read the documentation.
+
+This file contains instructions for generating the HTML files.
+
+About the Documentation
+-----------------------
+
+The docs are written in Sphinx's extensions to reStructuredText
+(reST).  You can read more about Sphinx here:
+
+    http://sphinx.pocoo.org/tutorial.html
+
+Much of the documentation is pulled out of the libmaple source code;
+we use Doxygen XML output into Sphinx documentation.  You can read
+more about Doxygen here:
+
+    http://doxygen.org
+
+We use a Sphinx plugin called Breathe to parse Doxygen's XML output
+into a form usable by Sphinx.  You can read more about Breathe here:
+
+    http://michaeljones.github.com/breathe/
 
 Documentation Build Steps
 -------------------------
 
+You first need to produce Doxygen XML output, then you can generate
+the HTML documentation.
+
 1. You need a recent-ish version of Doxygen in your PATH:
 
     http://www.stack.nl/~dimitri/doxygen/download.html#latestsrc
 
-2. Install breathe, which does Doxygen-to-Sphinx conversion:
+2. Install Breathe, which does Doxygen-to-Sphinx conversion:
 
    Read/write version (for LeafLabs developers):
 
@@ -37,9 +63,11 @@ Documentation Build Steps
 
     $ sudo easy_install -U Sphinx
 
+   You need Sphinx version >= 1.0.6.
+
 4. Before the first time you run Sphinx (and any time the Doxygen
    comments in the libmaple source code are changed), you'll need to
-   rebuild the Doxygen XML output:
+   build the Doxygen XML output:
 
     $ cd libmaple/docs/source
     $ doxygen
@@ -48,36 +76,23 @@ Documentation Build Steps
 
     $ make html
 
-   (Read the Makefile for more targets).
+   On Windows, use the batch file make.bat instead.
 
 Reading and Modifying the Documentation
 ---------------------------------------
 
-The net effect of the above is to produce Doxygen XML output (ignore
-this) in libmaple/docs/doxygen/xml, and HTML documentation (this is
-what you want) in libmaple/docs/build/html.
-
 Just point your web browser at the file
 
-  libmaple/docs/build/html/index.html
+  /docs/build/html/index.html
 
-it corresponds to the Sphinx file
+It corresponds to the Sphinx file
 
-  libmaple/docs/source/index.rst
-
-All of the documentation itself lives in libmaple/docs/source/.  The
-directory source/_static/ is for static content (like style sheets);
-source/_templates/ contains Sphinx templates (or, it would, if we had
-any).
-
-The docs are written in Sphinx's version of reStructuredText (reST);
-it's a Python thing that they use to produce the docs at
-http://python.org.  You can read more about Sphinx here:
-
-    http://sphinx.pocoo.org/tutorial.html
+  /docs/source/index.rst
 
-You can view the source for any generated page of documentation by
-clicking the "Show Source" link in the sidebar.
+The file /docs/source/conf.py is the Sphinx configuration file; you
+can go read it for more information about our setup.
 
-The file libmaple/docs/source/conf.py is the Sphinx configuration
-file; you can go read it for more information about our setup.
+All of the documentation which isn't pulled out of source code
+comments lives in /docs/source/.  The directory /docs/source/_static/
+is for static content (like style sheets); /docs/source/_templates/
+contains Sphinx templates.
diff --git a/support/gdb/gpio.gdb b/support/gdb/gpio.gdb
new file mode 100644
index 0000000..4376cfd
--- /dev/null
+++ b/support/gdb/gpio.gdb
@@ -0,0 +1,12 @@
+set print pretty on
+
+print "GPIOA registers:"
+p/x *GPIOA->regs
+print "GPIOB registers:"
+p/x *GPIOB->regs
+print "GPIOC registers:"
+p/x *GPIOC->regs
+print "GPIOD registers:"
+p/x *GPIOD->regs
+print "AFIO registers:"
+p/x *(struct afio_reg_map*)0x40010000