[tuxdroid-svn] r1177 - in firmware/fuxusb/trunk/src: . lib_mcu/twi

[Paul_R <c2m...@c2...>]

Author: Paul_R
Date: 2008-05-20 12:07:01 +0200 (Tue, 20 May 2008)
New Revision: 1177

Modified:
   firmware/fuxusb/trunk/src/bootloader.c
   firmware/fuxusb/trunk/src/bootloader.h
   firmware/fuxusb/trunk/src/global.h
   firmware/fuxusb/trunk/src/i2c.c
   firmware/fuxusb/trunk/src/i2c.h
   firmware/fuxusb/trunk/src/lib_mcu/twi/twi.h
   firmware/fuxusb/trunk/src/misc.c
   firmware/fuxusb/trunk/src/misc.h
   firmware/fuxusb/trunk/src/rf.c
   firmware/fuxusb/trunk/src/rf.h
   firmware/fuxusb/trunk/src/spi_task.c
   firmware/fuxusb/trunk/src/spi_task.h
   firmware/fuxusb/trunk/src/usb_commands.c
Log:
* Added comments.


Modified: firmware/fuxusb/trunk/src/bootloader.c
===================================================================
--- firmware/fuxusb/trunk/src/bootloader.c	2008-05-20 09:28:43 UTC (rev 1176)
+++ firmware/fuxusb/trunk/src/bootloader.c	2008-05-20 10:07:01 UTC (rev 1177)
@@ -19,19 +19,19 @@
 
 /* $Id$ */
 
+/** \file bootloader.c
+    \brief bootloader functions.
+    \ingroup bootloader
+*/
+
 #include "config.h"
 #include "global.h"
 #include "usb_commands.h"
-#include "usb_ep.h"
 #include "bootloader.h"
 #include "i2c.h"
 #include "spi_task.h"
 #include "rf.h"
-#include "fifo_stt.h"
-#include "lib_mcu\usb\usb_drv.h"
 
-
-
 /* Externs defs */
 bit i2c_bootloading_Flag;
 
@@ -50,7 +50,11 @@
 static void init_bootloader(void);
 static void bl_senddata(blHeader_t blHeader, uint8_t dataLength);
 
-
+/**
+ * \brief Bootloader commands parser.
+ * This function analyze the commands received.
+ * \ingroup bootloader
+ */
 void bootloader_cmd_parser(void)
 {
     /* Disable spi_task */
@@ -117,6 +121,12 @@
     }
 }
 
+
+/**
+ * \brief I2C task.
+ * This function send the data on the I2C bus.
+ * \ingroup bootloader
+ */
 void i2c_task(void)
 {
     if (i2c_wait_counter)
@@ -143,6 +153,12 @@
     }
 }
 
+
+/**
+ * \brief Fill page
+ * A new page has been received. Check if the page is good, control the indexes
+ * and adresses, and put the data on the i2c.
+ */
 static void bl_fill_page(void)
 {
     uint8_t i;
@@ -199,7 +215,9 @@
     packet_idx++;
 }
 
-
+/**
+ * \brief Init bootloader mode.
+ */
 static void init_bootloader(void)
 {
     /* Configure I2C wait counter */
@@ -230,7 +248,7 @@
 }
 
 /**
- *\brief Exit bootloader mode
+ *\brief Exit bootloader mode.
  */
 static void bl_exit(void)
 {
@@ -243,7 +261,7 @@
 
 
 /*
- * Initialize i2c interface
+ * Initialize i2c interface.
  */
 static void bl_init(void)
 {
@@ -255,8 +273,8 @@
     blHeader.blData = &i2cSendData[2];
 }
 
-/*
- * Sends the data stored in i2cSendData array. Only the
+/*!
+ * \brief Sends the data stored in i2cSendData array. Only the
  * 'dataLength' first bytes are sent.
  *
  * Prepare the i2c communication and store the page address in the

Modified: firmware/fuxusb/trunk/src/bootloader.h
===================================================================
--- firmware/fuxusb/trunk/src/bootloader.h	2008-05-20 09:28:43 UTC (rev 1176)
+++ firmware/fuxusb/trunk/src/bootloader.h	2008-05-20 10:07:01 UTC (rev 1177)
@@ -19,15 +19,22 @@
 
 /* $Id$ */
 
+/** \file bootloader.h
+    \brief Bootloader header.
+    \ingroup bootloader
+*/
+
 #ifndef _BOOTLOADER_H_
 #define _BOOTLOADER_H_
 
-/** USB bootloader commands */
+/** \name USB bootloader commands
+ * @{ */
 #define BOOT_INIT   1
 #define BOOT_FILLPAGE 2
 #define BOOT_EXIT 3
 
 #define BOOTLOADER_CMD     (uint8_t)0xF0 /* Bootloader status command */
+/* @} */
 
 /**
  * \brief Bootloading header structure which holds all information to initiate

Modified: firmware/fuxusb/trunk/src/global.h
===================================================================
--- firmware/fuxusb/trunk/src/global.h	2008-05-20 09:28:43 UTC (rev 1176)
+++ firmware/fuxusb/trunk/src/global.h	2008-05-20 10:07:01 UTC (rev 1177)
@@ -73,6 +73,22 @@
  *  \ingroup fuxusb
  */
 
+/** \defgroup spi_task SPI task
+ *  \brief SPI communication.
+ *  \ingroup fuxusb
+ */
+
+
+/** \defgroup bootloader Bootloader
+ *  \brief Bootloader functions.
+ *  \ingroup fuxusb
+ */
+
+/** \defgroup i2c I2C
+ *  \brief I2C functions.
+ *  \ingroup fuxusb
+ */
+
 /** 
  * \defgroup fifo_spk Speaker FIFO
    \brief FIFO_SPK is used for the speaker data, received from the USB and sent 
@@ -85,6 +101,7 @@
    \ingroup fuxusb
  */
 
+
 /** 
  * \defgroup fifo_mic Microphone FIFO
    \brief FIFO_MIC used for the microphone data, received from the RF and sent 
@@ -96,7 +113,7 @@
    \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. 
@@ -107,8 +124,22 @@
 
    \ingroup fuxusb
  */
+ 
+/** \defgroup rf RF
+ *  \brief RF functions.
+ *  \ingroup fuxusb
+ */
 
+/** \defgroup misc Misc
+ *  \brief Misc functions.
+ *  \ingroup fuxusb
+ */
 
+/** 
+ * \defgroup mcu MCU libs
+ */
+
+
 #include "common\api.h"
 #include "common\defines.h"
 

Modified: firmware/fuxusb/trunk/src/i2c.c
===================================================================
--- firmware/fuxusb/trunk/src/i2c.c	2008-05-20 09:28:43 UTC (rev 1176)
+++ firmware/fuxusb/trunk/src/i2c.c	2008-05-20 10:07:01 UTC (rev 1177)
@@ -17,8 +17,12 @@
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  */
 
-/* $Id:$ */
+/* $Id$ */
 
+/** \file i2c.c
+    \ingroup i2c
+*/
+
 #include "i2c.h"
 
 /* I2C status and address variables */
@@ -44,8 +48,9 @@
 
 /* functions */
 
-/*
- * Set the TWI transaction bitrate
+/**
+ * \brief Set the TWI transaction bitrate
+ * \ingroup i2c
  */
 void i2cSetBitrate(void)
 {
@@ -53,12 +58,13 @@
     SSCON = TWI_SCAL_VALUE; /* twi intialisation */
 }
 
-/*
- * This function initializes the TWI interface for i2c communication. You
- * should use the definitions in i2c.h to select the mode you want.
+/*!
+ * \brief This function initializes the TWI interface for i2c communication. 
+ * You should use the definitions in i2c.h to select the mode you want.
  *
  * Note that you should set the i2cSlaveReceive and i2cSlaveTransmit handlers
  * after this initialization otherwise they'll be cleared.
+ * \ingroup i2c
  */
 void i2cInit(void)
 {
@@ -82,20 +88,26 @@
 #endif
 }
 
-/* Set the user function which handles receiving (incoming) data as a slave */
+/** \brief Set the user function which handles receiving (incoming) data as a slave.
+ * \ingroup i2c 
+ */
 void i2cSetSlaveReceiveHandler(void (*i2cSlaveRx_func)(uint8_t receiveDataLength, uint8_t* recieveData))
 {
     i2cSlaveReceive = i2cSlaveRx_func;
 }
 
-/* Set the user function which handles transmitting (outgoing) data as a slave */
+/** \brief  Set the user function which handles transmitting (outgoing) data as a slave.
+ * \ingroup i2c 
+ */
 void i2cSetSlaveTransmitHandler(uint8_t (*i2cSlaveTx_func)(uint8_t transmitDataLengthMax, uint8_t* transmitData))
 {
     i2cSlaveTransmit = i2cSlaveTx_func;
 }
 
 void i2cSendStart(void);
-/* Start a Master transmission, i2cSendDataIndex is reset automatically here */
+/** \brief Start a Master transmission, i2cSendDataIndex is reset automatically here.
+ * \ingroup i2c
+ */
 void i2cMasterStart(void)
 {
     i2cFlags.i2c_busy = 1;
@@ -103,45 +115,52 @@
     i2cSendStart();
 }
 
+/** \brief Send start command */
 void i2cSendStart(void)
 {
     TWI_SET_START();
 }
 
+/** \brief Send stop command */
 void i2cSendStop(void)
 {
     TWI_SET_STOP();
     i2cFlags.i2c_busy = 0;
 }
 
+/** \brief Send byte */
 void i2cSendByte(uint8_t _data)
 {
     SSDAT = _data;
 }
 
+/** \brief  Acknoledge the received byte */
 void i2cAckReceiveByte(void)
 {
     TWI_SET_AA();
 }
 
+/** \brief NACK the received byte */
 void i2cNackReceiveByte(void)
 {
     TWI_CLEAR_AA();
 }
 
 #define TW_DATA     SSDAT
+/** \brief Get received byte */
 uint8_t i2cGetReceivedByte(void)
 {
     return SSDAT;
 }
 
+/** \brief Get status */
 uint8_t i2cGetStatus(void)
 {
     return TW_STATUS;
 }
 
 
-/* TWI interrupt service routine */
+/** \brief TWI interrupt service routine */
 #ifdef TWI_INT_ENABLED
 void it_TWI(void) interrupt IRQ_TWI using 1
 {

Modified: firmware/fuxusb/trunk/src/i2c.h
===================================================================
--- firmware/fuxusb/trunk/src/i2c.h	2008-05-20 09:28:43 UTC (rev 1176)
+++ firmware/fuxusb/trunk/src/i2c.h	2008-05-20 10:07:01 UTC (rev 1177)
@@ -19,6 +19,10 @@
 
 /* $Id$ */
 
+/** \file i2c.h
+    \ingroup i2c
+*/
+
 #ifndef _I2C_H_
 #define _I2C_H_
 
@@ -40,8 +44,11 @@
  * Choose operation mode, comment/uncomment lines
  * For Slave only operation, choose Master and Slave
  */
+/** \name Operation modes
+ * @{ */
 #define TWI_INT_ENABLED /* comment if you don't want twi interrupts */
 #define TWI_M_ENABLED   /* comment if you don't want twi master mode */
+/* @} */
 //#define TWI_SLA_ENABLED /* comment if you don't want twi slave mode */
 
 /* SSADR: TWI (Slave) Address Register
@@ -85,7 +92,7 @@
 /*! defines and constants */
 #define TWCR_CMD_MASK       0x0F
 
-/*
+/**
  * Bits that are set inside interrupt routines, and watched outside in
  * the program's main loop.
  */

Modified: firmware/fuxusb/trunk/src/lib_mcu/twi/twi.h
===================================================================
--- firmware/fuxusb/trunk/src/lib_mcu/twi/twi.h	2008-05-20 09:28:43 UTC (rev 1176)
+++ firmware/fuxusb/trunk/src/lib_mcu/twi/twi.h	2008-05-20 10:07:01 UTC (rev 1177)
@@ -1,4 +1,4 @@
-/* $Id:$ */
+/* $Id$ */
 
 #ifndef _LIBMCU_TWI_H_
 #define _LIBMCU_TWI_H_ 1
@@ -36,6 +36,7 @@
 
   This header file contains bit mask definitions for use with
   the ATMEL TWI interface.
+  \ingroup mcu
   */
 /** \name TWSR values
 

Modified: firmware/fuxusb/trunk/src/misc.c
===================================================================
--- firmware/fuxusb/trunk/src/misc.c	2008-05-20 09:28:43 UTC (rev 1176)
+++ firmware/fuxusb/trunk/src/misc.c	2008-05-20 10:07:01 UTC (rev 1177)
@@ -18,12 +18,25 @@
  */
 
 /* $Id$ */
+
+
+/** \file misc.c
+    \ingroup misc
+*/
+
 #include "config.h"
 #include "global.h"
 #include "misc.h"
 
 static uint16_t usb_sof_counter = 0;
 
+/**
+ * \brief Control the LED behavior.
+ * The LED blink slowly when the RF is disconnected, and fast when Tux is
+ * connected.
+ * The timebase is the USB start of frame each 1ms.
+ * \ingroup misc
+ */
 void led_behavior(void)
 {   
     usb_sof_counter ++;
@@ -54,6 +67,12 @@
    }
 }
 
+
+/**
+ * \brief Reset the dongle.
+ * This function configure the watchdog timer and wait the timer OVF.
+ * \ingroup misc
+ */
 void wait_reset(void)
 {
     /* Configure watchdog reset */

Modified: firmware/fuxusb/trunk/src/misc.h
===================================================================
--- firmware/fuxusb/trunk/src/misc.h	2008-05-20 09:28:43 UTC (rev 1176)
+++ firmware/fuxusb/trunk/src/misc.h	2008-05-20 10:07:01 UTC (rev 1177)
@@ -19,6 +19,11 @@
 
 /* $Id$ */
 
+
+/** \file misc.h
+    \ingroup misc
+*/
+
 #ifndef _MISC_H_
 #define _MISC_H_
 

Modified: firmware/fuxusb/trunk/src/rf.c
===================================================================
--- firmware/fuxusb/trunk/src/rf.c	2008-05-20 09:28:43 UTC (rev 1176)
+++ firmware/fuxusb/trunk/src/rf.c	2008-05-20 10:07:01 UTC (rev 1177)
@@ -17,15 +17,19 @@
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  */
 
-/* $Id:$ */
+/* $Id$ */
 
+/** \file rf.c
+    \ingroup rf
+ */
 #include "config.h"
 #include "global.h"
 #include "spi_lib.h"
 #include "rf.h"
 
 /**
- *\brief Restart the RF.
+ * \brief Restart the RF.
+ * \ingroup rf
  */
 void reset_rf(void)
 {
@@ -38,7 +42,8 @@
 }
 
 /**
- * Restart the RF in bootloader mode
+ * \brief Restart the RF in bootloader mode.
+ * \ingroup rf
  */
 void rf_start_bootloader(void)
 {

Modified: firmware/fuxusb/trunk/src/rf.h
===================================================================
--- firmware/fuxusb/trunk/src/rf.h	2008-05-20 09:28:43 UTC (rev 1176)
+++ firmware/fuxusb/trunk/src/rf.h	2008-05-20 10:07:01 UTC (rev 1177)
@@ -17,8 +17,13 @@
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  */
 
-/* $Id:$ */
+/* $Id$ */
 
+
+/** \file rf.h
+    \ingroup rf
+*/
+
 #ifndef _RF_H_
 #define _RF_H_
 

Modified: firmware/fuxusb/trunk/src/spi_task.c
===================================================================
--- firmware/fuxusb/trunk/src/spi_task.c	2008-05-20 09:28:43 UTC (rev 1176)
+++ firmware/fuxusb/trunk/src/spi_task.c	2008-05-20 10:07:01 UTC (rev 1177)
@@ -19,18 +19,21 @@
 
 /* $Id$ */
 
+/** \file spi_task.c
+    \brief SPI task functions.
+    \ingroup spi_task
+*/
+
 #include "global.h"
 #include "config.h"
-#include "usb_task.h"
 #include "spi_lib.h"
 #include "spi_task.h"
-#include "global.h"
 #include "fifo_spk.h"
 #include "fifo_mic.h"
 #include "fifo_stt.h"
 
-/*
- * spi_slave enum define the steps of the SPI frame.
+/**
+ * \brief spi_slave enum define the steps of the SPI frame.
  */
 enum 
 {
@@ -41,7 +44,7 @@
 } spi_slave;
 
 /*
- * spi_master enum define the steps of the SPI frame.
+ * \brief spi_master enum define the steps of the SPI frame.
  */
 enum 
 {
@@ -69,6 +72,8 @@
 
 /**
  * \brief Reset the SPI task to the defaults states.
+ * This function reset all SPI variables.
+ * \ingroup spi_task
  */
 void spi_task_reset(void)
 {
@@ -84,6 +89,7 @@
 /**
  * \brief Init the SPI transaction.
  * This function init the SPI bus and the INT0 interrupt.
+ * \ingroup spi_task
  */
 void spi_task_init(void)
 {
@@ -126,6 +132,7 @@
  * \brief INT0 interrupt.
  * This interrupt is trigged when a falling edge on P3_2.
  * spi_ready is set to indicate that a new spi transaction can begin.
+ * \ingroup spi_task
  */
 void it_INT0(void) interrupt IRQ_INT0
 {
@@ -135,6 +142,7 @@
 /**
  * \brief SPI task main function.
  * The SPI protocol must be refactored soon. So, I don't change this function ATM.
+ * \ingroup spi_task
  */
 void spi_task(void)
 {

Modified: firmware/fuxusb/trunk/src/spi_task.h
===================================================================
--- firmware/fuxusb/trunk/src/spi_task.h	2008-05-20 09:28:43 UTC (rev 1176)
+++ firmware/fuxusb/trunk/src/spi_task.h	2008-05-20 10:07:01 UTC (rev 1177)
@@ -19,6 +19,11 @@
 
 /* $Id$ */
 
+/** \file spi_task.h
+    \brief SPI task header.
+    \ingroup spi_task
+*/
+
 #ifndef _SPITASK_H_
 #define _SPITASK_H_
 

Modified: firmware/fuxusb/trunk/src/usb_commands.c
===================================================================
--- firmware/fuxusb/trunk/src/usb_commands.c	2008-05-20 09:28:43 UTC (rev 1176)
+++ firmware/fuxusb/trunk/src/usb_commands.c	2008-05-20 10:07:01 UTC (rev 1177)
@@ -27,8 +27,8 @@
 #include "config.h"
 #include "global.h"
 #include "usb_ep.h"
+#include "usb_commands.h"
 #include "usb_misc.h"
-#include "usb_commands.h"
 #include "spi_task.h"
 #include "bootloader.h"
 #include "fifo_stt.h"