From 3959e83f3842c7051f4073d9b39db9852619f561 Mon Sep 17 00:00:00 2001
From: Ben Blazak <benblazak.dev@gmail.com>
Date: Wed, 5 Jun 2013 21:21:07 -0700
Subject: [PATCH] doc update

---
 doc/references.md  | 28 ++++++++++++++++++++++++++++
 firmware/main.c    |  3 +++
 firmware/readme.md | 14 +++++++++++++-
 3 files changed, 44 insertions(+), 1 deletion(-)

diff --git a/doc/references.md b/doc/references.md
index 4c759c4..9a109a2 100644
--- a/doc/references.md
+++ b/doc/references.md
@@ -174,6 +174,29 @@
   (http://gcc.gnu.org/onlinedocs/gcc/Variable-Attributes.html)  
   How to byte align variables in GCC (among other things...)
 
+* Be careful with bitfields in C!
+
+  Apparently, they don't always do what you'd expect.  So if you're dealing
+  with interrupts, or care how bits are layed out in hardware - or really if
+  you care about anything besides telling the compiler that it's okay with you
+  if it spends a little more time bitshifting in order to save some space -
+  then you should be very careful about using them.
+
+    * [GCC docs : Implementation : Structures, unions, enumerations, and
+       bit-fields]
+      (http://gcc.gnu.org/onlinedocs/gcc/Structures-unions-enumerations-and-bit_002dfields-implementation.html#Structures-unions-enumerations-and-bit_002dfields-implementation)  
+      Lots of things are "Determined by ABI" (the Application Binary
+      Interface).
+
+    * [GCC wiki : ABI for the AVR]
+      (http://gcc.gnu.org/wiki/avr-gcc)  
+      Bitfields aren't mentioned :/ .
+
+    * [Betrayed by a bitfield]
+      (http://lwn.net/Articles/478657/)  
+      Bitfields don't always do what you'd expect... even if you're an awesome
+      kernel developer.
+
 ### C++ Stuff
 
 * [Google C++ Style Guide]
@@ -254,6 +277,11 @@
   Apparently, treating `char` as signed is more common than treating it as
   unsigned.  It can be changed to unsigned, by default, with a compiler option.
 
+* [EmbeddedGurus: Experts on Embedded Software]
+  (http://embeddedgurus.com)  
+  Seems like a good resource, with lots of general tips on embedded
+  programming.
+
 
 ## Protocol Stuff
 
diff --git a/firmware/main.c b/firmware/main.c
index 0b6e664..c8af0fc 100644
--- a/firmware/main.c
+++ b/firmware/main.c
@@ -6,6 +6,9 @@
 
 /**                                                                 description
  * `main()`: tying it all together
+ *
+ * If you're just trying to get a feel for the source, I'd glance over this
+ * file, then move on to ".../firmware/keyboard.h"
  */
 
 
diff --git a/firmware/readme.md b/firmware/readme.md
index 5737f85..8afd4ce 100644
--- a/firmware/readme.md
+++ b/firmware/readme.md
@@ -1,5 +1,17 @@
-## [TODO] Dependencies
+<!-- TODO: everything ... -->
 
+## TODO
+- include versions for all build environment programs
+
+- generate documentation
+    - include a collection of all "namespace" prefixes, and where they belong
+    - write a note in "main.c" about where that file is (and about other
+      documentation that would help in understanding the code)
+    - write a note about where options are described, how they're included, how
+      i have makefiles set up, etc.
+    - write a mediumly thorough note about my workflow (vim, ...)
+
+## Dependencies
 - the gnu avr toolchain
 - python 3
   - markdown `sudo pip install markdown`