[WIP] GPIO refactor: seems ok, ready for review

2 files changed, 109 insertions, 43 deletions

diff --git a/notes/coding_standard.txt b/notes/coding_standard.txt
index 5cb96c3..372ebf4 100644
--- a/notes/coding_standard.txt
+++ b/notes/coding_standard.txt
@@ -25,12 +25,11 @@ License
 -------
 
 - Put an MIT license at the beginning of the file (look at any of our
-  source files for an example).  Copyright should go to either you or
-  LeafLabs LLC.
+  source files for an example).  Copyright should go either to you or
+  to LeafLabs, LLC.
 
   Emacs: if you don't like seeing the license, you should use
-  elide-head (which will hide it for you).  Here is some elisp you can
-  modify to make this pleasant:
+  elide-head (which will hide it for you).  You can use the following:
 
     (require 'elide-head)
     (setq programming-mode-hooks '(c-mode-hook c++-mode-hook))
@@ -38,7 +37,7 @@ License
                  '("The MIT License" . "DEALINGS IN\n [*] THE SOFTWARE"))
     (add-to-list 'elide-head-headers-to-hide
                  '("The MIT License" . "DEALINGS IN THE\n...SOFTWARE"))
-    (dolist (hook mbolivar-programming-mode-hooks)
+    (dolist (hook programming-mode-hooks)
       (add-hook hook (lambda () (elide-head))))
 
 Whitespace/Indentation
@@ -46,7 +45,8 @@ Whitespace/Indentation
 
 - 4 space indents.  [Set in .dir-locals.el]
 
-- Unix newlines.
+- Unix newlines. [Some exceptions are currently grandfathered in;
+  these will go away in time.]
 
 - No tab characters. [Set in .dir-locals.el]
 
@@ -76,50 +76,53 @@ Whitespace/Indentation
 
         (add-hook 'c-mode-hook c-mode-inextern-lang-hook)
 
-
 Comments
 --------
 
-- Multi-line comments look like this:
+- Multi-line comments are pretty flexible.  Any of these is fine:
 
-    /* text starts here
-     * continued lines have a '*' before them
-     * the comment can end after the last line
+    /* Comment starts here.
+     * Continued lines have a '*' before them.
+     * The comment can end after the last line.
      */
 
-  or this:
-
-    /* comment starts here
-     * the comment can end on the same line */
+    /* Comment starts here.
+     * The comment can end on the same line. */
 
-- Doxygen comments are newline comments that begin with /** instead.
-  It is not required that the "/**" appear on a line by itself.
+    /*
+     * You can also place a newline after the opening "/*".
+     */
 
-- Single-line comments on the same line are // in c or c++.
+- Doxygen comments are multi-line comments that begin with /** instead.
 
-- Single-line comments on their own source line are /* */ in c, but
-  can also be // in c++.  If you think that typing out /* */ is too
-  slow in emacs, use M-; (comment-dwim) when you're on an empty line,
-  and it'll ... well...
+- Single-line comments on the same line are // in C or C++.
 
-      You should be using the (super awesome) comment-dwim; it pretty
-      much does exactly what you want to the comment on the current
-      line, including "create one and put it in the right place".
+- Single-line comments on their own source line should be /* */ in C,
+  but can also be // in C++.  In Emacs, you can use M-;
+  (comment-dwim), and it'll Do What You Mean.
 
 Braces
 ------
 
-- 1TBS.  Nothing more need be said.
+- Mostly 1TBS:
 
       http://en.wikipedia.org/wiki/Indent_style#Variant:_1TBS
 
+  The only difference is that the opening brace of a function's
+  definition occurs exactly one space character after the closing
+  parenthesis in that function's parameter list.  Example:
+
+      void func(void) {
+          ...
+      }
+
 Naming conventions
 ------------------
 
-- There's always a fight about upper and lower case vs. underscores.
-  We'll handle this as follows.
+There's always a fight about upper and lower case vs. underscores.
+We'll handle this as follows.
 
-  First, Dammit_Dont_Mix_Like_This, because It_Looks_Really_Ugly, ok?
+- First, Dammit_Dont_Mix_Like_This, because It_Looks_Really_Ugly, ok?
   [There's been some debate about this, and some exceptions are
   already grandfathered in, so in order to settle it, let's call this
   a "recommendation" instead of "requirement".]
@@ -168,7 +171,7 @@ Naming conventions
 Documentation
 -------------
 
-- Document your code.  This should go without saying.
+- Document your code!
 
 - For complicated peripherals, it would be nice if you put longer-form
   comments into this directory (notes/), with a comment in the
@@ -176,13 +179,8 @@ Documentation
   example.  That lets us keep the source files relatively clean while
   still allowing new readers to have a starting point.
 
-- At least put a doxygen comment with a nonempty @brief for every .h
-  file you add.  See the existing ones for examples.  For now, it'd be
-  better if you didn't put a @brief into any .c[pp] files, since it
-  (currently) interferes with our documentation generator in a way
-  that I won't explain here (though you can look into the LeafLabs or
-  michaeljones breathe repos on github and potentially figure out
-  why).
+- At least put a Doxygen comment with a nonempty @brief for every .h
+  file you add.  See the existing ones for examples.
 
 - Doxygen comments generally just belong on types, functions,
   etc. that are part of the public user-facing API.  This generally
@@ -196,8 +194,13 @@ Documentation
 
   This should be avoided if at all possible, since it creates a
   maintenance burden of documenting things in two places at once, and
-  provides an opportunity for bad documentation to slip in, when the
-  code comments fall out of sync with the ReST docs.
+  makes it easier for documentation to go stale.
+
+- For libmaple proper (the pure C library under libmaple/); the
+  convention is to document any user-facing entity at the point where
+  it is defined.  In particular, this means you should document an
+  externally-linked function defined in a .c file in that .c file, not
+  in the header file where it is declared to the user.
 
 General Formatting
 ------------------
@@ -217,7 +220,3 @@ General Formatting
     (require 'lineker)
     (dolist (hook '(c-mode-hook c++-mode-hook))
       (add-hook hook (lambda () (lineker-mode 1))))
-
-  There are only a few exceptional situations.  The most important one
-  is when specifying a lookup table like PIN_MAP where it'd be ugly to
-  split each entry over multiple lines.
diff --git a/notes/exti.txt b/notes/exti.txt
new file mode 100644
index 0000000..1ad49ee
--- /dev/null
+++ b/notes/exti.txt
@@ -0,0 +1,67 @@
+External interrupt notes.
+
+To generate the interrupt, the interrupt line should be configured
+and enabled. This is done by programming the two trigger registers
+with the desired edge detection and by enabling the interrupt
+request by writing a '1' to the corresponding bit in the interrupt
+mask register.  When the selected edge occurs on the external
+interrupt line, an interrupt request is generated. The pending bit
+corresponding to the interrupt line is also set.  This request is
+reset by writing a '1' in the pending register.
+
+Hardware interrupt selection:
+
+To configure the 20 lines as interrupt sources, use the following
+procedure:
+
+1) Configure AFIO_EXTICR[y] to select the source input for EXTIx
+   external interrupt
+2) Configure the mask bits of the 20 interrupt lines (EXTI_IMR)
+3) Configure the trigger selection bits of the interrupt lines
+   (EXTI_RTSR and EXTI_FTSR)
+4) Configure the enable and mask bits that control the NVIC_IRQ
+   channel mapped to the External Interrupt Controller (EXTI) so
+   that an inerrupt coming from one of the 20 lines can be
+   correctly acknowledged.
+
+AFIO clock must be on.
+
+RM0008, page 107: "PD0, PD1 cannot be used for external
+interrupt/event generation on 36, 48, 64-bin packages."
+
+----------------------------------------------------------------------------
+Pin to EXTI Line Mappings:
+EXTI0          EXTI1          EXTI2           EXTI3           EXTI4
+--------------------------------------------------------------------------
+D2/PA0         D3/PA1         D1/PA2          D0/A6/PA3       D10/A10/PA4
+D26/EXT7/PB0   D27/EXT8/PB1   D16/A2/PC2      D17/A3/PC3      D18/A4/PC4
+D14/A0/PC0     D15/PC1        D25/EXT5/PD2
+
+EXTI5          EXTI6          EXTI7           EXTI8           EXTI9
+----------------------------------------------------------------------------
+D13/A13/PA5    D12/A12/PA6    D11/A11/PA7     D6/PA8          D7/PA9
+D4/PB5         D5/PB6         D9/PB7          D38/PB8         D23/EXT4/PB9
+D19/A5/PC5     D34/EXTI15/PC6 D35/EXT16/PC7   D36/PC8         D37/EXT18/PC9
+
+EXTI10         EXTI11         EXTI12          EXTI13          EXTI14
+----------------------------------------------------------------------------
+D8/PA10        D29/EXT10/PB11 D30/EXTI1/PB12  D31/EXTI12/PB13 D32/EXT13/PB14
+D28/PB10                                      D20/EXTI1/PC13  D21/EXT2/PC14
+D25/PC10
+
+EXTI15
+----------------------------------------------------------------------------
+D33/EXTI14/PB15
+D22/EXT3/PC15
+
+
+The 16 EXTI interrupts are mapped to 7 interrupt handlers.
+
+EXTI Lines to Interrupt Mapping:
+EXTI0 -> EXTI0
+EXTI1 -> EXTI1
+EXTI2 -> EXTI2
+EXTI3 -> EXTI3
+EXTI4 -> EXTI4
+EXTI[5-9] -> EXT9_5
+EXTI[10-15] -> EXT15_10