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>

22 files changed, 157 insertions, 61 deletions

diff --git a/Makefile b/Makefile
index 0784644..e3a1e4f 100644
--- a/Makefile
+++ b/Makefile
@@ -75,7 +75,7 @@ ifeq ($(LIBMAPLE_MODULES),)
 else
 	LIBMAPLE_MODULES += $(SRCROOT)/libmaple
 endif
-# LIBMAPLE_MODULES += $(SRCROOT)/libmaple/usb   # USB FS device
+LIBMAPLE_MODULES += $(SRCROOT)/libmaple/usb   # The USB module is kept separate
 LIBMAPLE_MODULES += $(LIBMAPLE_MODULE_SERIES) # STM32 series submodule in libmaple
 LIBMAPLE_MODULES += $(SRCROOT)/wirish
 # Official libraries:
diff --git a/libmaple/include/libmaple/usb.h b/libmaple/include/libmaple/usb.h
index 82bace9..8555aca 100644
--- a/libmaple/include/libmaple/usb.h
+++ b/libmaple/include/libmaple/usb.h
@@ -1,7 +1,7 @@
 /******************************************************************************
  * The MIT License
  *
- * Copyright (c) 2010 LeafLabs LLC.
+ * Copyright (c) 2010, 2011 LeafLabs LLC.
  *
  * Permission is hereby granted, free of charge, to any person
  * obtaining a copy of this software and associated documentation
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
index 816fad6..e8ccc15 100644
--- a/libmaple/usb/rules.mk
+++ b/libmaple/usb/rules.mk
@@ -3,20 +3,29 @@ sp              := $(sp).x
 dirstack_$(sp)  := $(d)
 d               := $(dir)
 BUILDDIRS       += $(BUILD_PATH)/$(d)
-BUILDDIRS       += $(BUILD_PATH)/$(d)/usb_lib
 
 # Local flags
-CFLAGS_$(d) = -I$(d) -I$(d)/usb_lib $(LIBMAPLE_INCLUDES) $(LIBMAPLE_PRIVATE_INCLUDES) -Wall
+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) := usb.c                \
-              usb_reg_map.c        \
-              usb_cdcacm.c         \
-              usb_lib/usb_core.c   \
-              usb_lib/usb_init.c   \
-              usb_lib/usb_mem.c    \
-              usb_lib/usb_regs.c
+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)/%)
diff --git a/libmaple/usb/usb.c b/libmaple/usb/stm32f1/usb.c
index 0130bab..0130bab 100644
--- a/libmaple/usb/usb.c
+++ b/libmaple/usb/stm32f1/usb.c
diff --git a/libmaple/usb/usb_cdcacm.c b/libmaple/usb/stm32f1/usb_cdcacm.c
index 6ef4806..6ef4806 100644
--- a/libmaple/usb/usb_cdcacm.c
+++ b/libmaple/usb/stm32f1/usb_cdcacm.c
diff --git a/libmaple/usb/usb_descriptors.h b/libmaple/usb/stm32f1/usb_descriptors.h
index 9bcb2b6..9bcb2b6 100644
--- a/libmaple/usb/usb_descriptors.h
+++ b/libmaple/usb/stm32f1/usb_descriptors.h
diff --git a/libmaple/usb/usb_lib_globals.h b/libmaple/usb/stm32f1/usb_lib_globals.h
index 1cd2754..1cd2754 100644
--- a/libmaple/usb/usb_lib_globals.h
+++ b/libmaple/usb/stm32f1/usb_lib_globals.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 ce80842..ce80842 100644
--- a/libmaple/usb/usb_reg_map.h
+++ b/libmaple/usb/stm32f1/usb_reg_map.h
diff --git a/support/ld/stm32/series/stm32f1/value/vector_symbols.inc b/support/ld/stm32/series/stm32f1/value/vector_symbols.inc
new file mode 100644
index 0000000..f8726f9
--- /dev/null
+++ b/support/ld/stm32/series/stm32f1/value/vector_symbols.inc
@@ -0,0 +1,78 @@
+EXTERN(__msp_init)
+EXTERN(__exc_reset)
+EXTERN(__exc_nmi)
+EXTERN(__exc_hardfault)
+EXTERN(__exc_memmanage)
+EXTERN(__exc_busfault)
+EXTERN(__exc_usagefault)
+EXTERN(__stm32reservedexception7)
+EXTERN(__stm32reservedexception8)
+EXTERN(__stm32reservedexception9)
+EXTERN(__stm32reservedexception10)
+EXTERN(__exc_svc)
+EXTERN(__exc_debug_monitor)
+EXTERN(__stm32reservedexception13)
+EXTERN(__exc_pendsv)
+EXTERN(__exc_systick)
+
+EXTERN(__irq_wwdg)
+EXTERN(__irq_pvd)
+EXTERN(__irq_tamper)
+EXTERN(__irq_rtc)
+EXTERN(__irq_flash)
+EXTERN(__irq_rcc)
+EXTERN(__irq_exti0)
+EXTERN(__irq_exti1)
+EXTERN(__irq_exti2)
+EXTERN(__irq_exti3)
+EXTERN(__irq_exti4)
+EXTERN(__irq_dma1_channel1)
+EXTERN(__irq_dma1_channel2)
+EXTERN(__irq_dma1_channel3)
+EXTERN(__irq_dma1_channel4)
+EXTERN(__irq_dma1_channel5)
+EXTERN(__irq_dma1_channel6)
+EXTERN(__irq_dma1_channel7)
+EXTERN(__irq_adc1)
+EXTERN(__stm32reservedexception14)
+EXTERN(__stm32reservedexception15)
+EXTERN(__stm32reservedexception16)
+EXTERN(__stm32reservedexception17)
+EXTERN(__irq_exti9_5)
+EXTERN(__irq_tim1_brk)
+EXTERN(__irq_tim1_up)
+EXTERN(__irq_tim1_trg_com)
+EXTERN(__irq_tim1_cc)
+EXTERN(__irq_tim2)
+EXTERN(__irq_tim3)
+EXTERN(__irq_tim4)
+EXTERN(__irq_i2c1_ev)
+EXTERN(__irq_i2c1_er)
+EXTERN(__irq_i2c2_ev)
+EXTERN(__irq_i2c2_er)
+EXTERN(__irq_spi1)
+EXTERN(__irq_spi2)
+EXTERN(__irq_usart1)
+EXTERN(__irq_usart2)
+EXTERN(__irq_usart3)
+EXTERN(__irq_exti15_10)
+EXTERN(__irq_rtcalarm)
+EXTERN(__irq_cec)
+EXTERN(__irq_tim12)
+EXTERN(__irq_tim13)
+EXTERN(__irq_tim14)
+EXTERN(__stm32reservedexception18)
+EXTERN(__stm32reservedexception19)
+EXTERN(__irq_fsmc)
+EXTERN(__stm32reservedexception20)
+EXTERN(__irq_tim5)
+EXTERN(__irq_spi3)
+EXTERN(__irq_uart4)
+EXTERN(__irq_uart5)
+EXTERN(__irq_tim6)
+EXTERN(__irq_tim7)
+EXTERN(__irq_dma2_channel1)
+EXTERN(__irq_dma2_channel2)
+EXTERN(__irq_dma2_channel3)
+EXTERN(__irq_dma2_channel4_5)
+EXTERN(__irq_dma2_channel5)     /* on remap only */
diff --git a/support/make/board-includes/VLDiscovery.mk b/support/make/board-includes/VLDiscovery.mk
index 82d1b23..441f078 100644
--- a/support/make/board-includes/VLDiscovery.mk
+++ b/support/make/board-includes/VLDiscovery.mk
@@ -3,3 +3,4 @@ PRODUCT_ID := 0003
 ERROR_LED_PORT := GPIOC
 ERROR_LED_PIN  := 9
 MCU_SERIES := stm32f1
+MCU_F1_LINE := value
diff --git a/support/make/board-includes/maple.mk b/support/make/board-includes/maple.mk
index d31ad83..4de4bab 100644
--- a/support/make/board-includes/maple.mk
+++ b/support/make/board-includes/maple.mk
@@ -3,3 +3,4 @@ PRODUCT_ID := 0003
 ERROR_LED_PORT := GPIOA
 ERROR_LED_PIN  := 5
 MCU_SERIES := stm32f1
+MCU_F1_LINE := performance
diff --git a/support/make/board-includes/maple_RET6.mk b/support/make/board-includes/maple_RET6.mk
index d06f068..104ae08 100644
--- a/support/make/board-includes/maple_RET6.mk
+++ b/support/make/board-includes/maple_RET6.mk
@@ -3,3 +3,4 @@ PRODUCT_ID := 0003
 ERROR_LED_PORT := GPIOA
 ERROR_LED_PIN := 5
 MCU_SERIES := stm32f1
+MCU_F1_LINE := performance
diff --git a/support/make/board-includes/maple_mini.mk b/support/make/board-includes/maple_mini.mk
index 835adc3..70ef506 100644
--- a/support/make/board-includes/maple_mini.mk
+++ b/support/make/board-includes/maple_mini.mk
@@ -3,3 +3,4 @@ PRODUCT_ID := 0003
 ERROR_LED_PORT := GPIOB
 ERROR_LED_PIN  := 1
 MCU_SERIES := stm32f1
+MCU_F1_LINE := performance
diff --git a/support/make/board-includes/maple_native.mk b/support/make/board-includes/maple_native.mk
index 3e88e7b..86746a6 100644
--- a/support/make/board-includes/maple_native.mk
+++ b/support/make/board-includes/maple_native.mk
@@ -3,3 +3,4 @@ PRODUCT_ID := 0003
 ERROR_LED_PORT := GPIOC
 ERROR_LED_PIN  := 15
 MCU_SERIES := stm32f1
+MCU_F1_LINE := performance
diff --git a/support/make/board-includes/olimex_stm32_h103.mk b/support/make/board-includes/olimex_stm32_h103.mk
index 96d6976..31f2c04 100644
--- a/support/make/board-includes/olimex_stm32_h103.mk
+++ b/support/make/board-includes/olimex_stm32_h103.mk
@@ -3,3 +3,4 @@ PRODUCT_ID := 0003
 ERROR_LED_PORT := GPIOC
 ERROR_LED_PIN := 12
 MCU_SERIES := stm32f1
+MCU_F1_LINE := performance
diff --git a/support/make/target-config.mk b/support/make/target-config.mk
index 48a33de..e13504d 100644
--- a/support/make/target-config.mk
+++ b/support/make/target-config.mk
@@ -15,9 +15,9 @@ TARGET_FLAGS += -DBOARD_$(BOARD) -DMCU_$(MCU) \
 
 LD_SERIES_PATH := $(LDDIR)/stm32/series/$(MCU_SERIES)
 ifeq ($(MCU_SERIES), stm32f1)
-   # Hack: force F1 to performance line; this will need to change if
-   # you add connectivity etc. line support.
-   LD_SERIES_PATH := $(LD_SERIES_PATH)/performance
+# Due to the Balkanization on F1, we need to specify the line when
+# making linker decisions.
+LD_SERIES_PATH := $(LD_SERIES_PATH)/$(MCU_F1_LINE)
 endif
 LIBMAPLE_MODULE_SERIES := $(LIBMAPLE_PATH)/$(MCU_SERIES)
 
diff --git a/wirish/include/wirish/usb_serial.h b/wirish/include/wirish/usb_serial.h
index 81e9e97..f36671b 100644
--- a/wirish/include/wirish/usb_serial.h
+++ b/wirish/include/wirish/usb_serial.h
@@ -25,13 +25,14 @@
  *****************************************************************************/
 
 /**
- * @brief Wirish virtual serial port
+ * @brief Wirish USB virtual serial port (SerialUSB).
  */
 
 #ifndef _WIRISH_USB_SERIAL_H_
 #define _WIRISH_USB_SERIAL_H_
 
 #include <wirish/Print.h>
+#include <wirish/boards.h>
 
 /**
  * @brief Virtual serial terminal.
@@ -58,7 +59,9 @@ public:
     uint8 pending();
 };
 
+#if BOARD_HAVE_SERIALUSB
 extern USBSerial SerialUSB;
+#endif
 
 #endif
 
diff --git a/wirish/rules.mk b/wirish/rules.mk
index 147857a..6d96cbe 100644
--- a/wirish/rules.mk
+++ b/wirish/rules.mk
@@ -26,6 +26,9 @@ cppSRCS_$(d) += HardwareSerial.cpp
 cppSRCS_$(d) += HardwareTimer.cpp
 cppSRCS_$(d) += Print.cpp
 cppSRCS_$(d) += pwm.cpp
+ifeq ($(MCU_SERIES), stm32f1)
+cppSRCS_$(d) += usb_serial.cpp	# HACK: this is currently STM32F1 only.
+endif
 cppSRCS_$(d) += wirish_analog.cpp
 cppSRCS_$(d) +=	wirish_digital.cpp
 cppSRCS_$(d) +=	wirish_math.cpp
@@ -36,7 +39,6 @@ cppSRCS_$(d) += $(MCU_SERIES)/wirish_digital.cpp
 cppSRCS_$(d) += $(WIRISH_BOARD_PATH)/board.cpp
 # TODO: revise these appropriately for F2 and put them back in:
 # HardwareSPI.cpp
-# usb_serial.cpp
 # ext_interrupts.cpp
 
 sFILES_$(d)   := $(sSRCS_$(d):%=$(d)/%)
diff --git a/wirish/stm32f1/boards_setup.cpp b/wirish/stm32f1/boards_setup.cpp
index 423e5ec..1dec579 100644
--- a/wirish/stm32f1/boards_setup.cpp
+++ b/wirish/stm32f1/boards_setup.cpp
@@ -38,9 +38,9 @@
 
 #include <libmaple/gpio.h>
 #include <libmaple/timer.h>
-#include <libmaple/usb_cdcacm.h>
 
-#include <board/board.h>
+#include <wirish/boards.h>
+#include <wirish/usb_serial.h>
 
 // Allow boards to provide a PLL multiplier. This is useful for
 // e.g. STM32F100 value line MCUs, which use slower multipliers.
@@ -80,10 +80,8 @@ namespace wirish {
         }
 
         void board_setup_usb(void) {
-#if 0
-#    if STM32_HAVE_USB
-            usb_cdcacm_enable(BOARD_USB_DISC_DEV, BOARD_USB_DISC_BIT);
-#    endif
+#if BOARD_HAVE_SERIALUSB
+            SerialUSB.begin();
 #endif
         }
     }
diff --git a/wirish/usb_serial.cpp b/wirish/usb_serial.cpp
index 388c739..a01900f 100644
--- a/wirish/usb_serial.cpp
+++ b/wirish/usb_serial.cpp
@@ -40,14 +40,21 @@
 #define USB_TIMEOUT 50
 
 USBSerial::USBSerial(void) {
+#if !BOARD_HAVE_SERIALUSB
+    ASSERT(0);
+#endif
 }
 
 void USBSerial::begin(void) {
+#if BOARD_HAVE_SERIALUSB
     usb_cdcacm_enable(BOARD_USB_DISC_DEV, BOARD_USB_DISC_BIT);
+#endif
 }
 
 void USBSerial::end(void) {
+#if BOARD_HAVE_SERIALUSB
     usb_cdcacm_disable(BOARD_USB_DISC_DEV, BOARD_USB_DISC_BIT);
+#endif
 }
 
 void USBSerial::write(uint8 ch) {
@@ -117,4 +124,6 @@ uint8 USBSerial::getRTS(void) {
     return usb_cdcacm_get_rts();
 }
 
+#if BOARD_HAVE_SERIALUSB
 USBSerial SerialUSB;
+#endif