aboutsummaryrefslogtreecommitdiffstats
path: root/libmaple/usb/README
diff options
context:
space:
mode:
authorMarti Bolivar <mbolivar@mit.edu>2010-09-27 00:40:44 -0400
committerMarti Bolivar <mbolivar@mit.edu>2010-09-27 00:40:44 -0400
commit753f89de354eff212d84f3f2aff41146865da342 (patch)
tree095e2183ce956bac028083d056c9c4b7ee8a8d84 /libmaple/usb/README
parent849bc0f8f6abf42567a152cf6e01bf7349902aac (diff)
downloadlibrambutan-753f89de354eff212d84f3f2aff41146865da342.tar.gz
librambutan-753f89de354eff212d84f3f2aff41146865da342.zip
whitespace cleanups
Diffstat (limited to 'libmaple/usb/README')
-rw-r--r--libmaple/usb/README116
1 files changed, 70 insertions, 46 deletions
diff --git a/libmaple/usb/README b/libmaple/usb/README
index e542dde..f3970b6 100644
--- a/libmaple/usb/README
+++ b/libmaple/usb/README
@@ -1,9 +1,11 @@
The USB submodule of libmaple is responsible for:
- initilizing the usb peripheral, scaling the peripheral clocks appropriately,
- enabling the interrupt channels to usb, defining the usb isr, resetting the usb
- disc pin (used to tell the host were alive). Additionally, the usb submodule defines
- the virtual com port usb applications that is available to all user sketches via Usb.print()
- and others.
+
+ Initializing the USB peripheral, scaling the peripheral clocks
+ appropriately, enabling the interrupt channels to USB, defining
+ the USB isr, resetting the USB disc pin (used to tell the host
+ were alive). Additionally, the USB submodule defines the virtual
+ com port USB applications that is available to all user sketches
+ via Usb.print() and others.
To use it:
Call Usb.init() to enable the IRQ channel, configure the clocks,
@@ -13,56 +15,78 @@ To use it:
Current Status:
- Currently, the USB submodule relies on the low level core library provided by ST to access the
- usb peripheral registers and 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 mimick the
- form of MyUSB (LUFA), since this library (USB for AVR) is growing in popularity and in example
- applications. Additionally, the usb lib here relies on low level hardware functions that were
- just ripped out of the bootloader code (for simplicity) but clearly this should be replaced with
- direct accesses to functions provided elsewhere in libmaple.
+ Currently, the USB submodule relies on the low level core library
+ provided by ST to access the USB peripheral registers and
+ 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 mimick the form of
+ MyUSB (LUFA), since this library (USB for AVR) is growing in
+ popularity and in example applications. Additionally, the USB lib
+ here relies on low level hardware functions that were just ripped
+ out of the bootloader code (for simplicity) but clearly this
+ should be replaced with direct accesses to functions provided
+ elsewhere in libmaple.
- The virtual com port serves two important purposes. 1) is allows serial data transfers between
- user sketches an a host computer. 2) is allows the host machine to issue a system reset by
- asserting the DTR signal. After reset, Maple will run the DFU bootloader for a few seconds,
- during which the user can begin a DFU download operation ('downloads' application binary into
- RAM/FLASH). This without this virtual com port, it would be necessary to find an alternative means
- to reset the chip in order to enable the bootloader.
+ The virtual com port serves two important purposes. 1) is allows
+ serial data transfers between user sketches an a host computer. 2)
+ is allows the host machine to issue a system reset by asserting
+ the DTR signal. After reset, Maple will run the DFU bootloader for
+ a few seconds, during which the user can begin a DFU download
+ operation ('downloads' application binary into RAM/FLASH). This
+ 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 (uses faster isochronous
- enpoints for streaming audio, or implements the USB HID or Mass Storage specs for examples) 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 some
- operating systems will assign a host-side driver based on these tags.
+ 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
+ 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
+ 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 sotrage etc.) however this turns out to be a burden
- from the host driver side, as windows and *nix handle compound usb devices quite differently.
+ 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 sotrage 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 running the usb application isnt "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 v1,2,3 this is GPIOC,12). Alternatively, the NVIC can be directly configured
- to disable the USB LP/HP IRQ's
+ Be mindful that running the USB application isnt "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 v1,2,3 this is GPIOC,12). Alternatively, the
+ NVIC can be directly configured to disable the USB LP/HP IRQ's
- This library should exposed through usb.h, do not include any other files direcly in your application.
+ This library should exposed through usb.h, do not include any
+ other files direcly in your application.
- 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.
+ 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.
Integration with libmaple:
- The current usb lib is ported directly from the maple bootloader code, adapted to be a virtual com rather than
- a DFU device. That means several functions are redefined locally that could have been pulled from elsewhere
- in libmaple. Thus, ths usb module depends absolutely zero on libmaple, it even ensures that clocks are configured
- correctly for its operation.
+
+ The current USB lib is ported directly from the maple bootloader
+ code, adapted to be a virtual com rather than a DFU device. That
+ means several functions are redefined locally that could have been
+ pulled from elsewhere in libmaple. Thus, ths USB module depends
+ absolutely zero on libmaple, it even ensures that clocks are
+ configured correctly for its operation.
Todo:
- - write custom low level usb stack to strip out any remaining dependence on ST code
- - remove dependence on hardware.c, since any functions here really should have their
- own analogues elsewhere inside libmaple
- - add a high level usb application library that would allow users to make their own
- HID/Mass Storage/Audio/Video devices.
+
+ - write custom low level USB stack to strip out any remaining
+ dependence on ST code
+ - remove dependence on hardware.c, since any functions here really
+ should have their own analogues elsewhere inside libmaple
+ - add a high level USB application library that would allow users
+ to make their own HID/Mass Storage/Audio/Video devices.
- implement a Usb.link(SerialX) that forces a passthrough
the host computer virtual com to SerialX, and utilizes the
- line_config commands correctly (sets baud etc) \ No newline at end of file
+ line_config commands correctly (sets baud etc)