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>

9 files changed, 100 insertions, 118 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.
diff --git a/libmaple/usb/rules.mk b/libmaple/usb/rules.mk
new file mode 100644
index 0000000..e8ccc15
--- /dev/null
+++ b/libmaple/usb/rules.mk
@@ -0,0 +1,45 @@
+# Standard things
+sp              := $(sp).x
+dirstack_$(sp)  := $(d)
+d               := $(dir)
+BUILDDIRS       += $(BUILD_PATH)/$(d)
+
+# Local flags
+CFLAGS_$(d) = -I$(d) -I$(d)/$(MCU_SERIES) -I$(d)/usb_lib $(LIBMAPLE_INCLUDES) $(LIBMAPLE_PRIVATE_INCLUDES) -Wall
+
+# Add usblib and series subdirectory to BUILDDIRS.
+BUILDDIRS += $(BUILD_PATH)/$(d)/$(MCU_SERIES)
+BUILDDIRS += $(BUILD_PATH)/$(d)/usb_lib
+
+# Local rules and targets
+sSRCS_$(d) :=
+cSRCS_$(d) :=
+# We currently only have F1 performance line support. Sigh.
+ifeq ($(MCU_SERIES), stm32f1)
+ifeq ($(MCU_F1_LINE), performance)
+cSRCS_$(d) += $(MCU_SERIES)/usb.c
+cSRCS_$(d) += $(MCU_SERIES)/usb_reg_map.c
+cSRCS_$(d) += $(MCU_SERIES)/usb_cdcacm.c
+cSRCS_$(d) += usb_lib/usb_core.c
+cSRCS_$(d) += usb_lib/usb_init.c
+cSRCS_$(d) += usb_lib/usb_mem.c
+cSRCS_$(d) += usb_lib/usb_regs.c
+endif
+endif
+
+sFILES_$(d) := $(sSRCS_$(d):%=$(d)/%)
+cFILES_$(d) := $(cSRCS_$(d):%=$(d)/%)
+
+OBJS_$(d) := $(sFILES_$(d):%.S=$(BUILD_PATH)/%.o) \
+             $(cFILES_$(d):%.c=$(BUILD_PATH)/%.o)
+DEPS_$(d) := $(OBJS_$(d):%.o=%.d)
+
+$(OBJS_$(d)): TGT_CFLAGS := $(CFLAGS_$(d))
+$(OBJS_$(d)): TGT_ASFLAGS :=
+
+TGT_BIN += $(OBJS_$(d))
+
+# Standard things
+-include        $(DEPS_$(d))
+d               := $(dirstack_$(sp))
+sp              := $(basename $(sp))
diff --git a/libmaple/usb/usb.c b/libmaple/usb/stm32f1/usb.c
index 667b11f..0130bab 100644
--- a/libmaple/usb/usb.c
+++ b/libmaple/usb/stm32f1/usb.c
@@ -25,18 +25,22 @@
  *****************************************************************************/
 
 /**
- * @file usb.c
+ * @file libmaple/usb/usb.c
  * @brief USB support.
+ *
+ * This is a mess. What we need almost amounts to a ground-up rewrite.
  */
 
-#include "usb.h"
+#include <libmaple/usb.h>
 
-#include "libmaple.h"
-#include "rcc.h"
+#include <libmaple/libmaple.h>
+#include <libmaple/rcc.h>
 
+/* Private headers */
 #include "usb_reg_map.h"
 #include "usb_lib_globals.h"
 
+/* usb_lib headers */
 #include "usb_type.h"
 #include "usb_core.h"
 
diff --git a/libmaple/usb/usb_cdcacm.c b/libmaple/usb/stm32f1/usb_cdcacm.c
index b41753a..6ef4806 100644
--- a/libmaple/usb/usb_cdcacm.c
+++ b/libmaple/usb/stm32f1/usb_cdcacm.c
@@ -25,22 +25,26 @@
  *****************************************************************************/
 
 /**
- * @file usb_cdcacm.c
+ * @file libmaple/usb/usb_cdcacm.c
+ * @brief USB CDC ACM (a.k.a. virtual serial terminal, VCOM).
  *
- * @brief USB CDC ACM (a.k.a. virtual serial terminal, VCOM) state and
- *        routines.
+ * FIXME: this works on the STM32F1 USB peripherals, and probably no
+ * place else. Nonportable bits really need to be factored out, and
+ * the result made cleaner.
  */
 
-#include "usb_cdcacm.h"
+#include <libmaple/usb_cdcacm.h>
 
-#include "nvic.h"
-#include "delay.h"
+#include <libmaple/usb.h>
+#include <libmaple/nvic.h>
+#include <libmaple/delay.h>
 
-#include "usb.h"
+/* Private headers */
 #include "usb_descriptors.h"
 #include "usb_lib_globals.h"
 #include "usb_reg_map.h"
 
+/* usb_lib headers */
 #include "usb_type.h"
 #include "usb_core.h"
 #include "usb_def.h"
@@ -59,12 +63,8 @@
 
 #if !(defined(BOARD_maple) || defined(BOARD_maple_RET6) ||      \
       defined(BOARD_maple_mini) || defined(BOARD_maple_native))
-
-#warning ("Warning! USB VCOM relies on LeafLabs board-specific "        \
-          "configuration right now.  If you want, you can pretend "     \
-          "you're one of our boards; i.e., #define BOARD_maple, "       \
-          "BOARD_maple_mini, etc.  according to what matches your MCU " \
-          "best."
+#warning USB CDC ACM relies on LeafLabs board-specific configuration.\
+    You may have problems on non-LeafLabs boards.
 #endif
 
 static void vcomDataTxCb(void);
diff --git a/libmaple/usb/usb_descriptors.h b/libmaple/usb/stm32f1/usb_descriptors.h
index 405588a..9bcb2b6 100644
--- a/libmaple/usb/usb_descriptors.h
+++ b/libmaple/usb/stm32f1/usb_descriptors.h
@@ -27,7 +27,7 @@
 #ifndef _USB_DESCRIPTORS_H_
 #define _USB_DESCRIPTORS_H_
 
-#include "libmaple.h"
+#include <libmaple/libmaple.h>
 
 #define USB_DESCRIPTOR_TYPE_DEVICE        0x01
 #define USB_DESCRIPTOR_TYPE_CONFIGURATION 0x02
diff --git a/libmaple/usb/usb_lib_globals.h b/libmaple/usb/stm32f1/usb_lib_globals.h
index a494817..1cd2754 100644
--- a/libmaple/usb/usb_lib_globals.h
+++ b/libmaple/usb/stm32f1/usb_lib_globals.h
@@ -27,6 +27,7 @@
 #ifndef _USB_LIB_GLOBALS_H_
 #define _USB_LIB_GLOBALS_H_
 
+/* usb_lib headers */
 #include "usb_type.h"
 #include "usb_core.h"
 
diff --git a/libmaple/usb/usb_reg_map.c b/libmaple/usb/stm32f1/usb_reg_map.c
index 75562e1..75562e1 100644
--- a/libmaple/usb/usb_reg_map.c
+++ b/libmaple/usb/stm32f1/usb_reg_map.c
diff --git a/libmaple/usb/usb_reg_map.h b/libmaple/usb/stm32f1/usb_reg_map.h
index 5bf5d96..ce80842 100644
--- a/libmaple/usb/usb_reg_map.h
+++ b/libmaple/usb/stm32f1/usb_reg_map.h
@@ -24,8 +24,8 @@
  * SOFTWARE.
  *****************************************************************************/
 
-#include "libmaple_types.h"
-#include "util.h"
+#include <libmaple/libmaple_types.h>
+#include <libmaple/util.h>
 
 #ifndef _USB_REG_MAP_H_
 #define _USB_REG_MAP_H_
diff --git a/libmaple/usb/usb_cdcacm.h b/libmaple/usb/usb_cdcacm.h
deleted file mode 100644
index 8ca1c68..0000000
--- a/libmaple/usb/usb_cdcacm.h
+++ /dev/null
@@ -1,59 +0,0 @@
-/******************************************************************************
- * The MIT License
- *
- * Copyright (c) 2011 LeafLabs LLC.
- *
- * Permission is hereby granted, free of charge, to any person
- * obtaining a copy of this software and associated documentation
- * files (the "Software"), to deal in the Software without
- * restriction, including without limitation the rights to use, copy,
- * modify, merge, publish, distribute, sublicense, and/or sell copies
- * of the Software, and to permit persons to whom the Software is
- * furnished to do so, subject to the following conditions:
- *
- * The above copyright notice and this permission notice shall be included in
- * all copies or substantial portions of the Software.
- *
- * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
- * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
- * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
- * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
- * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
- * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
- * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
- * SOFTWARE.
- *****************************************************************************/
-
-/**
- * @file usb_cdcacm.h
- * @brief USB CDC ACM (virtual serial terminal) support
- */
-
-#ifndef _USB_CDCACM_H_
-#define _USB_CDCACM_H_
-
-#include "libmaple_types.h"
-#include "gpio.h"
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-void usb_cdcacm_enable(gpio_dev*, uint8);
-void usb_cdcacm_disable(gpio_dev*, uint8);
-
-void   usb_cdcacm_putc(char ch);
-uint32 usb_cdcacm_tx(const uint8* buf, uint32 len);
-uint32 usb_cdcacm_rx(uint8* buf, uint32 len);
-
-uint32 usb_cdcacm_data_available(void); /* in RX buffer */
-uint16 usb_cdcacm_get_pending(void);
-
-uint8 usb_cdcacm_get_dtr(void);
-uint8 usb_cdcacm_get_rts(void);
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif