aboutsummaryrefslogtreecommitdiffstats
path: root/notes
diff options
context:
space:
mode:
authorMarti Bolivar <mbolivar@leaflabs.com>2011-03-07 13:11:54 -0500
committerMarti Bolivar <mbolivar@leaflabs.com>2011-03-11 16:24:44 -0500
commitc8da1c3b7b6eb450138a00af9bbbee607f596837 (patch)
tree207777355d41dc8947d94665ef9a8bae8982805a /notes
parent5b07707cdaa6268e1a984727bb907a7b10e8ada7 (diff)
downloadlibrambutan-c8da1c3b7b6eb450138a00af9bbbee607f596837.tar.gz
librambutan-c8da1c3b7b6eb450138a00af9bbbee607f596837.zip
[WIP] GPIO refactor: seems ok, ready for review
Diffstat (limited to 'notes')
-rw-r--r--notes/coding_standard.txt85
-rw-r--r--notes/exti.txt67
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