[tuxdroid-svn] r1193 - firmware/fuxusb/trunk/src

SourceForge Headquarters 225 Broadway Suite 1600 San Diego, CA 92101 +1 (858) 422-6466

Author: Paul_R
Date: 2008-05-22 17:24:51 +0200 (Thu, 22 May 2008)
New Revision: 1193

Modified:
   firmware/fuxusb/trunk/src/global.h
Log:
* doc 


Modified: firmware/fuxusb/trunk/src/global.h
===================================================================

--- firmware/fuxusb/trunk/src/global.h	2008-05-22 15:24:30 UTC (rev 1192)
+++ firmware/fuxusb/trunk/src/global.h	2008-05-22 15:24:51 UTC (rev 1193)
@@ -22,8 +22,26 @@
 #ifndef _GLOBAL_H_
 #define _GLOBAL_H_
 
-/** \mainpage Fuxusb firmware documentation of the Tux Droid open source robot
+/** \mainpage Fuxusb documentation.
  *
+ * Firmware for the USB dongle of TuxDroid.
+ *
+ * The functionnalities are :
+ * - A bi-directionnal audio interface with a IN data pipe (microphone) and a 
+ *   OUT data pipe (speaker).
+ * - A bi-directionnal interface to receive commands from the PC and send back
+ *   the statuses.
+ *
+ * The audio interfaces are detected by the hosts as audio cards, with the 
+ * following specifications :
+ * - PCM8
+ * - 8kHz / 8bits
+ * - Isochronous EPs @1ms.
+ *
+ * The command interface is detected as a HID device with these specifications:
+ * - OUT EP - Interrupt - EP size : 64 bytes - polling interval : 1ms
+ * - IN EP  - Interrupt - EP size : 64 bytes - polling interval : 1ms
+ *
  * \section SVN SVN repository
  * http://svn.tuxisalive.com/firmware/fuxusb/trunk
  */
@@ -31,108 +49,144 @@
 /** \defgroup fuxusb USB Dongle for TuxDroid.
  */
 
- /** \defgroup main Main function
- *  \brief Fuxusb main function
- *  \ingroup fuxusb
+/** \defgroup main Main function
+ *  \brief Main function of fuxusb.
+ * The main loop is organized like this :
+ * - usb_task -> main usb function
+ * - i2c_task -> communication function for the bootloader
+ * - spi_task -> communication function for the RF
+ *
+ * The usb_task is always active. spi_task is enabled only if the bootloader
+ * mode is inactive and if the RF is connected.
+ * \ingroup fuxusb
  */
 
 /** 
  * \defgroup usb_task USB Task
-   \brief Main functions to control the USB bus.
-   
-   \ingroup fuxusb
+ * \brief Main functions to control the USB bus.
+ *
+ *  From this module, all USB functionnalities are controlled and (if 
+ *  necessary) executed.
+ *  The majors tasks are :
+ *  - endpoint parser
+ *  - prepare the status
+ *  - fill the microphone fifo
+ *  - manage the bus (suspend / resume / reset)
+ *  - misc functionnalities (like LED behavior)
+ * \ingroup fuxusb
  */
  
 /** 
- * \defgroup usb_enum USB enumeration process
-   \brief This module analyze the enumeration requests and send back required
-   informations.
-   
-   \ingroup fuxusb
+ * \defgroup usb_enum USB enumeration
+ * \brief This function proceed the enumeration.
+ * 
+ * When a setup packet is received on the EP0 (control EP), the request is
+ * analyzed. The requested information is sent back to the host.
+ * \ingroup fuxusb
  */
 
 /** 
  * \defgroup usb_desc USB descriptor
-   \brief This module contain the descriptors structures.
-   
-   \ingroup fuxusb
+ * \brief This module contain the descriptors structures.
+ *
+ * The general descriptor is defined in a structure of sub-structure.
+ * Each sub-structure represents a specific descriptor.
+ * \ingroup fuxusb
  */
 
 /** \defgroup usb_ep USB Endpoints
  *  \brief Endpoints control.
+ *  
+ *  This module controls the endpoints. The main function parses all EPs and
+ *  treats the requests.  
  *  \ingroup fuxusb
  */
 
  
 /** \defgroup usb_cmd USB commands
- *  \brief Functions to prepare status and parse received commands.
+ *  \brief Specifics function to parse the received commands.
+ *
+ *  Three types of commands can be received :
+ *  - dongle commands : Commands for the dongle. (ISP mode, reset, etc.).
+ *  - commands for Tux : These commands must be sent by RF for Tux.
+ *  - bootloader commands : Commands for the bootloading process.
  *  \ingroup fuxusb
  */
 
 /** \defgroup usb_misc USB misc functions
  *  \brief USB misc functions.
+ *
+ *  Maintenance functions are grouped in this module.
  *  \ingroup fuxusb
  */
 
 /** \defgroup spi_task SPI task
  *  \brief SPI communication.
+ *
+ *  This function send/receive commands/statuses on the SPI bus for/from the RF.
  *  \ingroup fuxusb
  */
 
 
 /** \defgroup bootloader Bootloader
  *  \brief Bootloader functions.
+ *
+ *  Functions for the bootloader. In bootloader mode, datas are sent to tux by 
+ *  I2C. I2C_task becomes active, and the RF is disabled.
  *  \ingroup fuxusb
  */
 
 /** \defgroup i2c I2C
  *  \brief I2C functions.
+ *
+ *  Specifics functions to access and manage the I2C bus.
  *  \ingroup fuxusb
  */
 
 /** 
  * \defgroup fifo_spk Speaker FIFO
-   \brief FIFO_SPK is used for the speaker data, received from the USB and sent 
-   to the RF. 
-   
-   This FIFO are specific for this application and the context. 
-   It's optimized for speed. It's not circular, and the access to the
-   buffer are direct.
-
-   \ingroup fuxusb
+ * \brief FIFO_SPK is used for the speaker data, received from the USB and sent 
+ * to the RF. 
+ * 
+ * This FIFO are specific for this application and the context. 
+ * It's optimized for speed. It's not circular, and the access to the
+ * buffer are direct.
+ * \ingroup fuxusb
  */
 
 
 /** 
  * \defgroup fifo_mic Microphone FIFO
-   \brief FIFO_MIC used for the microphone data, received from the RF and sent 
-   to the computer. 
-   This FIFO is specific for this application and the context. 
-   It's optimized for speed. It's not circular, and the access to the
-   buffer are direct.
-
-   \ingroup fuxusb
+ * \brief FIFO_MIC used for the microphone data, received from the RF and sent 
+ * to the computer. 
+ * This FIFO is specific for this application and the context. 
+ * It's optimized for speed. It's not circular, and the access to the
+ * buffer are direct.
+ * \ingroup fuxusb
  */
 
 /** 
  * \defgroup fifo_stt Status FIFO
-   \brief FIFO_STT is used for the status data, received from the RF and sent 
-   to the computer. 
-   
-   This FIFO are specific for this application and the context. 
-   It's optimized for speed. It's not circular, and the access to the
-   buffer are direct.
-
-   \ingroup fuxusb
+ * \brief FIFO_STT is used for the status data, received from the RF and sent 
+ * to the computer. 
+ * 
+ * This FIFO are specific for this application and the context. 
+ * It's optimized for speed. It's not circular, and the access to the
+ * buffer are direct.
+ * \ingroup fuxusb
  */
  
 /** \defgroup rf RF
  *  \brief RF functions.
+ *
+ *  This module contain the specifics functions to manage the RF.
  *  \ingroup fuxusb
  */
 
 /** \defgroup misc Misc
  *  \brief Misc functions.
+ *
+ *  This module contain misc. functions.
  *  \ingroup fuxusb
  */  
  



