diff options
| -rw-r--r-- | os/hal/dox/serial_usb.dox | 39 | ||||
| -rw-r--r-- | os/hal/dox/usb.dox | 86 | ||||
| -rw-r--r-- | os/hal/include/usb_cdc.h | 2 | ||||
| -rw-r--r-- | readme.txt | 5 | ||||
| -rw-r--r-- | todo.txt | 79 |
5 files changed, 141 insertions, 70 deletions
diff --git a/os/hal/dox/serial_usb.dox b/os/hal/dox/serial_usb.dox new file mode 100644 index 000000000..599ee3c16 --- /dev/null +++ b/os/hal/dox/serial_usb.dox @@ -0,0 +1,39 @@ +/*
+ ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio.
+
+ This file is part of ChibiOS/RT.
+
+ ChibiOS/RT is free software; you can redistribute it and/or modify
+ it under the terms of the GNU General Public License as published by
+ the Free Software Foundation; either version 3 of the License, or
+ (at your option) any later version.
+
+ ChibiOS/RT is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ GNU General Public License for more details.
+
+ You should have received a copy of the GNU General Public License
+ along with this program. If not, see <http://www.gnu.org/licenses/>.
+*/
+
+/**
+ * @defgroup SERIAL_USB Serial over USB Driver
+ * @brief Serial over USB Driver.
+ * @details This module implements an USB Communication Device Class
+ * (CDC) as a normal serial communication port accessible from
+ * the device application.
+ * @pre In order to use the USB over Serial driver the
+ * @p HAL_USE_SERIAL_USB option must be enabled in @p halconf.h.
+ *
+ * @section usb_serial_1 Driver State Machine
+ * The driver implements a state machine internally, not all the driver
+ * functionalities can be used in any moment, any transition not explicitly
+ * shown in the following diagram has to be considered an error and shall
+ * be captured by an assertion (if enabled).
+ * @if LATEX_PDF
+ * @else
+ * @endif
+ *
+ * @ingroup IO
+ */
diff --git a/os/hal/dox/usb.dox b/os/hal/dox/usb.dox new file mode 100644 index 000000000..1f843efae --- /dev/null +++ b/os/hal/dox/usb.dox @@ -0,0 +1,86 @@ +/*
+ ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio.
+
+ This file is part of ChibiOS/RT.
+
+ ChibiOS/RT is free software; you can redistribute it and/or modify
+ it under the terms of the GNU General Public License as published by
+ the Free Software Foundation; either version 3 of the License, or
+ (at your option) any later version.
+
+ ChibiOS/RT is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ GNU General Public License for more details.
+
+ You should have received a copy of the GNU General Public License
+ along with this program. If not, see <http://www.gnu.org/licenses/>.
+*/
+
+/**
+ * @defgroup USB USB Driver
+ * @brief Generic USB Driver.
+ * @details This module implements a generic USB driver.
+ * @pre In order to use the USB driver the @p HAL_USE_USB option
+ * must be enabled in @p halconf.h.
+ *
+ * @section usb_1 Driver State Machine
+ * The driver implements a state machine internally, not all the driver
+ * functionalities can be used in any moment, any transition not explicitly
+ * shown in the following diagram has to be considered an error and shall
+ * be captured by an assertion (if enabled).
+ * @if LATEX_PDF
+ * @else
+ * @endif
+ *
+ * @section usb_2 USB Operations
+ * The USB driver is quite complex and USB is complex in itself, it is
+ * recommended to study the USB specification before trying to use the
+ * driver.
+ *
+ * @subsection usb_2_1 USB Implementation
+ * The USB driver abstracts the inner details of the underlying USB hardware.
+ * The driver works asynchronously and communicates with the application
+ * using callbacks. The application is responsible of the descriptors and
+ * strings required by the USB device class to be implemented and of the
+ * handling of the specific messages sent over the endpoint zero. Standard
+ * messages are handled internally to the driver. The application can use
+ * hooks in order to handle custom messages or override the handling of the
+ * default handling of standard messages.
+ *
+ * @subsection usb_2_2 USB Endpoints
+ * USB endpoints are the objects that the application uses to exchange
+ * data with the host. There are two kind of endpoints:
+ * - <b>IN</b> endpoints are used by the application to transmit data to
+ * the host.
+ * - <b>OUT</b> endpoints are used by the application to receive data from
+ * the host.
+ * .
+ * In ChibiOS/RT the endpoints can be configured in two distinct ways:
+ * - <b>Packet Mode</b>. In this mode the driver invokes a callback each
+ * time a packet has been received or transmitted. This mode is especially
+ * suited for those applications handling continuous streams of data.
+ * - <b>Transaction Mode</b>. In this mode the driver invokes a callback
+ * only after a large, potentially multi-packet, transfer has been
+ * completed, a callback is invoked only at the end of the transfer.
+ * .
+ * .
+ * @subsection usb_2_3 USB Callbacks
+ * The USB driver uses callbacks in order to interact with the application.
+ * There are several kind of callbacks to be handled:
+ * - Driver-wide events callback. As example errors, suspend event, reset
+ * event etc.
+ * - Messages hook callback. This hook allows the application to implement
+ * handling of custom messages or to override the default handling of
+ * standard messages.
+ * - Descriptor requested callback. When the driver endpoint zero handler
+ * needs to serve a descriptor to the host it queries the application
+ * using this callback.
+ * - Start of Frame callback. This callback is invoked each time a SOF
+ * packet is received.
+ * - Endpoint callbacks. Each endpoint informs the application about I/O
+ * conditions using those callbacks.
+ * .
+ *
+ * @ingroup IO
+ */
diff --git a/os/hal/include/usb_cdc.h b/os/hal/include/usb_cdc.h index c1d3da3e7..39df4ccf3 100644 --- a/os/hal/include/usb_cdc.h +++ b/os/hal/include/usb_cdc.h @@ -17,7 +17,7 @@ along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
-/**
+/*-*
* @file usb_cdc.h
* @brief USB Communication Device Class support header.
*
diff --git a/readme.txt b/readme.txt index 5ce5777ad..b61e1d79f 100644 --- a/readme.txt +++ b/readme.txt @@ -70,13 +70,12 @@ *** 2.3.0 ***
- FIX: Fixed wrong serial driver macros (bug 3173336)(backported to 2.2.1).
-- NEW: Added experimental generic USB driver, it will certainly change in next
+- NEW: Added experimental generic USB driver, it will evolve in next
releases.
- NEW: Added an experimental USB driver implementation for STM32.
- NEW: Added experimental "serial over USB" driver, it implements a
Communication Device Class exposing it as a normal serial driver to
- applications, it will certainly change in next
- releases.
+ applications, probably it will evolve in next releases.
- NEW: Added USB CDC loopback test application.
- NEW: Implemented new event IO_TRANSMISSION_END in the generic serial
driver. This event marks the physical transmission end of a data stream.
@@ -5,78 +5,25 @@ X = In progress, some work done. ? = Not sure if worth the effort or useful at all.
N = Decided against.
-Within 2.1.x
-* Binary Semaphores on top of Counting Semaphores.
-* Direct unbuffered UART driver.
- Requirements: low level, callbacks, DMA capable, state machines buildable
- on top, support data words greater than 8 bits, callback for
- "last byte transmitted (RS485)", simple implementation,
- verifiable.
-* Rework STM32 drivers to use friendly IRQ names and centralized DMA macros.
-* I-class functions for the ADC/PWM drivers.
-* All the device driver structures must have a fields extension macro and
- initializer hook.
-* All the device driver callbacks must have the driver pointer as first
- parameter.
-* Change the SPI driver to be able to work asynchronously using callbacks,
- keep the synchronous APIs available as option.
-* Add an optional spiPolledExchange() API to the SPI driver model.
-* Update the STM32 SPI driver to the new model.
-* Make the ADC driver have the same synchronous/asynchronous API of the
- new SPI driver model.
-* General HAL improvements.
-* Update the AT91SAM7 SPI driver (DMA and/or ISR).
- * Verify the FatFs demo on both the AT91SAM7X and AT91SAM7S.
-* Update the LPC214x SPI driver (ISR).
- * Verify the LPC214x FatFs demo.
-* Write a new SPI driver for LPC1xxx (ISR)(it should be very close to the
- LPC214x one).
-N Evaluate if to add a synchronous API to the UART driver, eventually do so.
-* Global documentation reorganization in order to allow both separate documents
- and the usual blob document.
-* PDF generation from the documentation system (only separate documents, not
- the blob).
-* Automatic compilation and upload of the various documents on the web site
- (doxygen + rsync).
-* New STM8S/A SPI driver.
-* Reorganization of the STM32 family port-level support.
-* Remove preprocessor directives from the assembler files and restore the
- RIDE7 build files in the STM32 demo.
-* Move dynamic APIs into a separate source file.
-* Improved support in the STM32 HAL support for multiple sub-families. Do
- not check for the family in the various drivers but simply check for
- switch macros like STM32_HAS_USART3, STM32_HAS_SPI3. This what the
- drivers will not need changes when adding new sub-families.
-* STM8L official HAL support, it will have to be separated from the STM8S/STM8A
- HAL because it is very different.
- * Shared ISR management.
- * STM8L-Discovery demo.
-* Add the STM32F100 (Value Line) sub-family to the official STM32 HAL support.
- * STM32VL-Discovery demo.
-* Remove the PAL default configuration from the various hal_lld.c and move
- them into board.c files, this will remove an ugly dependency.
-* Realign the STM8 port to the new STM8L one as options, naming conventions
- and general solutions.
-* Support for more compilers (IAR, Keil, ARMCMx only initially).
-X Support for not just Makefiles (Ride7, Crossworks etc).
-* IAR port for Cortex-Mx, add demos for all the supported families.
-* Keil port for Cortex-Mx, add demos for all the supported families.
-* Change the serial drivers to have a single event source instead of three.
- Add Rx and Tx to the existing flags mechanism. Move up the flags handling in
- the superclass.
-X Except for the above, bug fixing only until the 2.2.0 release.
-
Within 2.3.x (hopefully)
-- Resist doing more changes and optimizations to the kernel.
-? Make thread functions return void.
+- Improvements to the message passing mechanism in order to allow "delayed,
+ out of order, responses".
+- Add a switch to enable/disable the priority inheritance algorithm in mutexes.
- Introduce a "THREAD" function prefix in order to hide compiler-specific
optimizations for thread functions.
-- Add a "transmission end" event to the serial device driver model.
+? Make thread functions return void.
+- Introduce compiler-info macros to the port layer, improve the test reports
+ with the info.
+* Add a "transmission end" event to the serial device driver model.
+ X Implement the "transmission end" serial driver event on those platforms
+ supporting the feature.
X Add an USB abstract device driver class.
X USB driver implementation for STM32F103/STM32F102.
+- USB driver implementation for STM32F105/STM32F107.
X Add a Serial over USB generic device driver implementing a USB Communication
Device Class and offering a Serial-like interface to the applications.
-- Add a switch to enable/disable the priority inheritance algorithm in mutexes.
+- Implement USB Mass Storage Class support and demo using the MMC_SPI driver
+ as back-end.
X File System infrastructure.
- Official FatFs wrapper using the new infrastructure, dedicated test suite.
X Transactional flash file system implementation.
@@ -89,7 +36,7 @@ X New device driver models: Clock, Systick, RTC, WDG, DAC, Power Monitor. - Device drivers for STM8/STM8L (ADC, PWM, bring them on par with STM32).
- Batch testing of the ARM7/ARMCMx port using OpenOCD, with reports.
- Debug-related features and tools.
-- Add a *very simple* ADC API for single one shot sampling (implement it as
+? Add a *very simple* ADC API for single one shot sampling (implement it as
an injected conversion on the STM32).
- Update C++ wrapper (Heap, Pools, Mailboxes and any new feature).
- Threads Pools manager in the library.
|