Cleanups; new support/gdb/gpio.gdb.

1 files changed, 102 insertions, 55 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.