Merge branch 'wip-family-support'

Merge the long-lived (too long; future changes like these will need to
proceed more incrementally) development branch of libmaple, containing
experimental STM32F2 and STM32F1 value line support, into master.

This required many changes to the structure of the library. The most
important structural reorganizations occurred in:

- 954f9e5: moves public headers to include directories
- 3efa313: uses "series" instead of "family"
- c0d60e3: adds board files to the build system, to make it easier to
  add new boards
- 096d86c: adds build logic for targeting different STM32 series
  (e.g. STM32F1, STM32F2)

This last commit in particular (096d86c) is the basis for the
repartitioning of libmaple into portable sections, which work on all
supported MCUs, and nonportable sections, which are segregated into
separate directories and contain all series-specific code. Moving
existing STM32F1-only code into libmaple/stm32f1 and wirish/stm32f1,
along with adding equivalents under .../stm32f2 directories, was the
principal project of this branch.

Important API changes occur in several places. Existing code is still
expected to work on STM32F1 targets, but there have been many
deprecations. A detailed changelog explaining the situation needs to
be prepared.

F2 and F1 value line support is not complete; the merge is proceeding
prematurely in this respect. We've been getting more libmaple patches
from the community lately, and I'm worried that the merge conflicts
with the old tree structure will become painful to manage.

Conflicts:
	Makefile

Resolved Makefile conflicts manually; this required propagating
-Xlinker usage into support/make/target-config.mk.

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.