aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorMarti Bolivar <mbolivar@leaflabs.com>2011-03-11 16:46:33 -0500
committerMarti Bolivar <mbolivar@leaflabs.com>2011-03-11 16:46:33 -0500
commit80b8f6d28f23a45a0c37275c5df775bd2e989e5e (patch)
tree7f7d22b95c4d1d53b5baea73822a98719f349c11
parentf41c5d82be0e0cd06c82d2d6cfce2254327dd757 (diff)
downloadlibrambutan-80b8f6d28f23a45a0c37275c5df775bd2e989e5e.tar.gz
librambutan-80b8f6d28f23a45a0c37275c5df775bd2e989e5e.zip
Cleanups; new support/gdb/gpio.gdb.
-rw-r--r--README157
-rw-r--r--docs/README73
-rw-r--r--support/gdb/gpio.gdb12
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