From 2f003bd7214c54560500b281661281a5c6903cee Mon Sep 17 00:00:00 2001 From: gdisirio Date: Thu, 10 Feb 2011 15:47:43 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@2728 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- os/hal/dox/serial_usb.dox | 39 +++++++++++++++++++++ os/hal/dox/usb.dox | 86 +++++++++++++++++++++++++++++++++++++++++++++++ os/hal/include/usb_cdc.h | 2 +- readme.txt | 5 ++- todo.txt | 79 +++++++------------------------------------ 5 files changed, 141 insertions(+), 70 deletions(-) create mode 100644 os/hal/dox/serial_usb.dox create mode 100644 os/hal/dox/usb.dox 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 . +*/ + +/** + * @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 . +*/ + +/** + * @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: + * - IN endpoints are used by the application to transmit data to + * the host. + * - OUT endpoints are used by the application to receive data from + * the host. + * . + * In ChibiOS/RT the endpoints can be configured in two distinct ways: + * - Packet Mode. 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. + * - Transaction Mode. 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 . */ -/** +/*-* * @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. diff --git a/todo.txt b/todo.txt index 259b9f23f..7c92ddac3 100644 --- a/todo.txt +++ b/todo.txt @@ -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. -- cgit v1.2.3