8796a81efc
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>
64 lines
2.7 KiB
Plaintext
64 lines
2.7 KiB
Plaintext
The USB submodule of libmaple is a separate piece of the codebase for
|
|
reasons that are largely historical.
|
|
|
|
Current Status:
|
|
|
|
There's only support for the USB device peripheral found on
|
|
STM32F103s.
|
|
|
|
We rely on the low level core library provided by ST to implement
|
|
the USB transfer protocol for control endpoint transfers.
|
|
|
|
The virtual com port (which is exposed via
|
|
<libmaple/usb_cdcacm.h>) serves two important purposes.
|
|
|
|
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
|
|
application binary into RAM/FLASH). Thus, without this virtual com
|
|
port, it would be necessary to find an alternative means to reset
|
|
the chip in order to enable the bootloader.
|
|
|
|
If you would like to develop your own USB application for whatever
|
|
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 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.
|
|
|
|
It would be possible to build a compound USB device, that
|
|
implements endpoints for both the virtual COM port as well as some
|
|
other components (mass storage etc.). However, this turns out to
|
|
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 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, 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:
|
|
|
|
- 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.
|