Slightly improve and generify the USB infrastructure.

The good news is that <libmaple/usb.h> and <libmaple/usb_cdcacm.h> did
turn out generic enough in what they specify to go on unchanged.

However, we can't just go on assuming that there's USB just because
we're on an F1. Now that there's value line in the tree, we need to be
more careful (value line F1s don't have USB peripherals). To that end,
make all the F1 board-includes/*.mk files specify what line their MCU
is with an MCU_F1_LINE variable. Use that to hack
libmaple/usb/rules.mk so we only try to build the USB module under
appropriate circumstances.

While we're at it, add a vector_symbols.inc for value line MCUs under
support/ld/. We need this to get the target-config.mk modifications
implied by the addition of MCU_F1_LINE. We'll fix up some other
performance-line-isms under libmaple/stm32f1 in a separate commit.

Also in libmaple/usb/:

- Move everything into a new stm32f1 directory. Due to aforementioned
  rules.mk hacks, there is no immediate need for an stm32f2
  directory (USB support doesn't exist there).

- Update the README for style and content.

Signed-off-by: Marti Bolivar <mbolivar@leaflabs.com>

1 files changed, 30 insertions, 39 deletions

diff --git a/libmaple/usb/README b/libmaple/usb/README
index 2c55364..d0fca8d 100644
--- a/libmaple/usb/README
+++ b/libmaple/usb/README
@@ -1,35 +1,24 @@
-The USB submodule of libmaple is responsible for:
-
-    Initializing the USB peripheral, scaling the peripheral clocks
-    appropriately, enabling the interrupt channels to USB, defining
-    the USB IRQ, resetting the USB DISC pin (used to tell the host
-    were alive). Additionally, the USB submodule defines the virtual
-    COM port interface that is exposed to user sketches via SerialUSB.
-
-To use it:
-
-   SerialUSB.print/ln, available(), read(), write() implement the same
-   interface as Serial1/2/3.
+The USB submodule of libmaple is a separate piece of the codebase for
+reasons that are largely historical.
 
 Current Status:
 
-    Currently, the USB submodule relies on the low level core library
-    provided by ST to implement the USB transfer protocol for control
-    endpoint transfers.  The high level virtual com port application
-    is unfortunately hard to untangle from this low level dependence,
-    and when a new USB core library is written (to nix ST dependence)
-    changes will likely have to be made to virtual com application
-    code. Ideally, the new core library should mimic the form of MyUSB
-    (LUFA), since this library (USB for AVR) is growing in popularity
-    and in example applications.
+    There's only support for the USB device peripheral found on
+    STM32F103s.
 
-    The virtual com port serves two important purposes.
+    We rely on the low level core library provided by ST to implement
+    the USB transfer protocol for control endpoint transfers.
 
-      1) It allows serial data transfers between user sketches an a
-         host computer.
+    The virtual com port (which is exposed via
+    <libmaple/usb_cdcacm.h>) serves two important purposes.
 
-      2) It allows the host machine to issue a system reset by
-         asserting the DTR signal.
+    1) It allows serial data transfers between user sketches an a
+       host computer.
+
+    2) It allows the host PC to issue a system reset into the DFU
+       bootloader with the DTR + RTS + "1EAF" sequence (see
+       leaflabs.com/docs/bootloader.html for more information on
+       this).
 
     After reset, Maple will run the DFU bootloader for a few seconds,
     during which the user can begin a DFU upload operation (uploads
@@ -38,11 +27,11 @@ Current Status:
     the chip in order to enable the bootloader.
 
     If you would like to develop your own USB application for whatever
-    reason (uses faster isochronous enpoints for streaming audio, or
-    implements the USB HID or Mass Storage specs for examples) then
+    reason (e.g. to use faster isochronous enpoints for streaming
+    audio, or implement the USB HID or Mass Storage specs), then
     ensure that you leave some hook for resetting Maple remotely in
-    order to spin up the DFU bootloader.  Please make sure to give
-    yourself a unique vendor/product ID pair in your application, as
+    order to spin up the DFU bootloader.  Please make sure to get
+    yourself a unique vendor/product ID pair for your application, as
     some operating systems will assign a host-side driver based on
     these tags.
 
@@ -52,21 +41,23 @@ Current Status:
     be a burden from the host driver side, as Windows and *nix handle
     compound USB devices quite differently.
 
-    Be mindful that enabling the USB peripheral isnt "free." The
+    Be mindful that enabling the USB peripheral isn't "free." The
     device must respond to periodic bus activity (every few
     milliseconds) by servicing an ISR. Therefore, the USB application
-    should be disabled inside of timing critical applications. In
-    order to disconnect the device from the host, the USB_DISC pin can
-    be asserted (on Maple this is GPIO C12). Alternatively, the NVIC
+    should be disabled inside of timing critical applications.
+
+    In order to disconnect the device from the host, a USB_DISC pin is
+    asserted (e.g. on Maple, this is PC12). Alternatively, the NVIC
     can be directly configured to disable the USB LP/HP IRQ's.
 
     The files inside of usb_lib were provided by ST and are subject to
     their own license, all other files were written by the LeafLabs
     team and fall under the MIT license.
 
-Todo:
+TODO:
 
-    - write custom low level USB stack to strip out any remaining
-      dependence on ST code
-    - add a high level USB application library that would allow users
-      to make their own HID/Mass Storage/Audio/Video devices.
+    - Generic USB driver core with series-provided backends, like
+      libopencm3 has.
+    - Strip out ST code.
+    - Integration with a high level USB library (like LUFA/MyUSB) to
+      allow users to write custom USB applications.