[tuxdroid-svn] r513 - firmware/tuxaudio/branches/audio_cleanup

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

Author: Paul_R
Date: 2007-09-12 14:19:00 +0200 (Wed, 12 Sep 2007)
New Revision: 513

Modified:
   firmware/tuxaudio/branches/audio_cleanup/AT26F004.c
   firmware/tuxaudio/branches/audio_cleanup/AT26F004.h
   firmware/tuxaudio/branches/audio_cleanup/flash.c
   firmware/tuxaudio/branches/audio_cleanup/flash.h
Log:
* Added doxygen comments 
* Cleanup some functions


Modified: firmware/tuxaudio/branches/audio_cleanup/AT26F004.c
===================================================================
--- firmware/tuxaudio/branches/audio_cleanup/AT26F004.c	2007-09-12 11:07:13 UTC (rev 512)
+++ firmware/tuxaudio/branches/audio_cleanup/AT26F004.c	2007-09-12 12:19:00 UTC (rev 513)
@@ -24,19 +24,22 @@
 #include "hardware.h"
 #include "spi.h"
 
-
+/**
+ * \ingroup at26f004
+ * \brief initialize a table with the sectors adresses values 
+ */
 uint8_t sector_adress[11][3] = {
-    {0x00, 0x00, 0x00},
-    {0x01, 0x00, 0x00},
-    {0x02, 0x00, 0x00},
-    {0x03, 0x00, 0x00},
-    {0x04, 0x00, 0x00},
-    {0x05, 0x00, 0x00},
-    {0x06, 0x00, 0x00},
-    {0x07, 0x00, 0x00},
-    {0x07, 0x80, 0x00},
-    {0x07, 0xA0, 0x00},
-    {0x07, 0xC0, 0x00}
+    {SECTOR0},
+    {SECTOR1},
+    {SECTOR2},
+    {SECTOR3},
+    {SECTOR4},
+    {SECTOR5},
+    {SECTOR6},
+    {SECTOR7},
+    {SECTOR8},
+    {SECTOR9},
+    {SECTOR10}
 };
 
 /**
@@ -153,6 +156,14 @@
     FLASH_CS_OFF;
 }
 
+/**
+ * \ingroup at26f004 
+   \param ad2 high address part 
+   \param ad1 medium adress part 
+   \param ad0 lower adress part
+   \return Data read
+   \brief This function read a single byte in the flash memory.
+   */ 
 uint8_t read_data(uint8_t const ad2, uint8_t const ad1, uint8_t const ad0)
 {
     uint8_t data1;

Modified: firmware/tuxaudio/branches/audio_cleanup/AT26F004.h
===================================================================
--- firmware/tuxaudio/branches/audio_cleanup/AT26F004.h	2007-09-12 11:07:13 UTC (rev 512)
+++ firmware/tuxaudio/branches/audio_cleanup/AT26F004.h	2007-09-12 12:19:00 UTC (rev 513)
@@ -22,51 +22,69 @@
 
     This module contains all specific definitions and functions to access the flash memory.
     */
+
 /** \file AT26F004.h
     \ingroup at26f004
     \brief AT26F004 flash memory header
-
     */
+ 
+#ifndef AT26F004_H
+#define AT26F004_H
 
+#include "hardware.h"
+
 /** \file AT26F004.c
     \ingroup at26f004
     \brief AT26F004 functions
-
     */
 
-#ifndef AT26F004_H
-#define AT26F004_H
 
-#include "hardware.h"
-
-/* Flash (AT26F004) OP CODE */
+/** 
+ * \name Read opcodes 
+    @{ */
 #define READ_ARRAY	    0x0B
 #define READ_ARRAY_LOW_F    0x03
-
+/*    @} */
+/** \name Erase opcodes 
+ *@{ */
 #define BLOCK_ERASE_4K	    0x20
 #define BLOCK_ERASE_32K	    0x52
 #define BLOCK_ERASE_64K	    0xD8
 #define CHIP_ERASE	    0x60
+/*    @} */
 
+/** \name Program opcodes 
+ * @{ */
 #define BYTE_PROGRAM	    0x02
 #define SEQU_PROGRAM	    0xAF
+/* @} */
 
+/** \name Sectors managment opcodes
+  * @{ */
 #define WRITE_EN	    0x06
 #define WRITE_DIS	    0x04
 #define PROTECT_SECTOR	    0x36
 #define UNPROTECT_SECTOR    0x39
 #define READ_SECT_PROTECT   0x3C
-
+/* @} */
+/** \name Status command 
+ * @{ */
 #define READ_STATUS_REG	    0x05
 #define WRITE_STATUS_REG    0x01
-
+/* @} */
+/** \name Misc. opcodes
+ * @{ */
 #define READ_MANUFACT	    0x9F
 #define DEEP_POWER_MODE	    0xB9
 #define RESUME_DEEP_MODE    0xAB
 
 #define NOP		    0x00
+/* @} */
 
-/* Flash status register masks */
+/** 
+ * \name AT26F004 status register masks 
+ * 
+ *  @{ */
 #define BUSY                0x01
 #define WEL                 0X02
 #define SWP                 0x0C
@@ -74,33 +92,61 @@
 #define RES                 0x20
 #define SPM                 0x40
 #define SPRL                0x80
+/*! @} */
 
-/* Flash sector adresses */
+/** \name Flash sector adresses
+ * @{ */
+#define SECTOR0  0x00, 0x00, 0x00
+#define SECTOR1  0x01, 0x00, 0x00
+#define SECTOR2  0x02, 0x00, 0x00
+#define SECTOR3  0x03, 0x00, 0X00
+#define SECTOR4  0x04, 0x00, 0x00
+#define SECTOR5  0x05, 0x00, 0x00
+#define SECTOR6  0x06, 0X00, 0x00
+#define SECTOR7  0x07, 0x00, 0x00
+#define SECTOR8  0x07, 0x80, 0x00
+#define SECTOR9  0x07, 0xA0, 0x00
+#define SECTOR10 0x07, 0xC0, 0x00
 
 extern uint8_t sector_adress[11][3]; 
+/* @} */
+
+
 /**
  * \name Flash TOP address
- * \ingroup at26f004
  * The flash memory address range is 0x000000 - [TOP_A2 TOP_A1 TOP_A0]
  * The AT26F004 has an address range of 0x000000 - 0x7FFFFF
- */
+ * @{ */
+
 /** High byte of the TOP address. */
 #define TOP_A2 0x07
 /** Middle byte of the TOP address. */
 #define TOP_A1 0xFF
 /** Low byte of the TOP address. */
 #define TOP_A0 0xFF
+/*! @} */
 
-
+/** \name Status access functions 
+ * @{ */
 extern uint8_t read_status(void);
+extern void write_status(uint8_t const status);
+/* @} */
+/** \name Writing functions 
+ * @{ */
 extern void write_enable(void);
 extern void write_disable(void);
-extern void write_status(uint8_t const status);
+extern void program_flash(uint8_t const ad2, uint8_t const ad1, uint8_t const ad0,
+                          uint8_t const data);
+/* @} */
+/** \name Reading function 
+ * @{ */
+extern uint8_t read_data(uint8_t const ad2, uint8_t const ad1, uint8_t const ad0);
+/* @} */
+/** \name Misc. functions 
+ * @{ */
 extern void erase_flash(void);
 extern void unprotect_sector(uint8_t const ad2, uint8_t const ad1,
                              uint8_t const ad0);
-extern void program_flash(uint8_t const ad2, uint8_t const ad1, uint8_t const ad0,
-                          uint8_t const data);
-extern uint8_t read_data(uint8_t const ad2, uint8_t const ad1, uint8_t const ad0);
+/* @} */
 
 #endif

Modified: firmware/tuxaudio/branches/audio_cleanup/flash.c
===================================================================
--- firmware/tuxaudio/branches/audio_cleanup/flash.c	2007-09-12 11:07:13 UTC (rev 512)
+++ firmware/tuxaudio/branches/audio_cleanup/flash.c	2007-09-12 12:19:00 UTC (rev 513)
@@ -115,6 +115,12 @@
 /**
  * \ingroup flash 
    \brief This function is used to play a sound from the flash memory.
+
+   The first step (playInit) is to initialize the flash memory with the selected sound to play.
+   Many tests are made to ensure that the sound to play exist, the indexes are correct, etc.
+
+   The second step (playingSound) is to fill the fifo with the sound's bytes, and to verify the adresses.
+
    */ 
 void playSound(void)
 {
@@ -128,7 +134,20 @@
 
 
 /* Static functions */
+/**
+ * \ingroup flash 
+   \brief This function is used to init the memory to play a sound.
+   \param nsound Track number to be played.
 
+    To prevent bugs, some verifications are made :
+    - check if the sound to play exist
+    - check if the sound to play is not null
+    - check if the indexes are correct. (the address exist, and the start and end indexes are not the same.
+
+    If these conditions are respected, the memory is initialised with the first sound's byte address.
+    The next index is stored to identify the end of the sound track.
+*/ 
+
 void playInit(uint8_t nsound)
 {
     uint8_t count, i;
@@ -229,6 +248,15 @@
     flash_state = 0;
 }
 
+/* Static functions */
+/**
+ * \ingroup flash 
+   \brief Read the flash memory and fill the fifo.
+
+    This function reads bytes into the flash memory and fill the fifo.
+    When the last byte is read, the sound play's sequence is stopped.
+ */ 
+
 static void playingSound(void)
 {
     uint8_t sound;
@@ -260,6 +288,13 @@
     sei();
 }
 
+/* Static functions */
+/**
+ * \ingroup flash 
+   \brief Stop the play sequence.
+ 
+    */ 
+
 static void stopPlaying(void)
 {
     flashPlay = 0;
@@ -271,10 +306,9 @@
 /**
  * \ingroup flash 
  * \brief Erase the flash memory.
+ *
  * This funtion perform a full erase of the flash memory and initiate the sound
  * flash programming.
- * This functions is called by the command_Parser function when a programming
- * flash command is received.
  */ 
 static void erasingFlash(void)
 {
@@ -293,6 +327,7 @@
 /**
  * \ingroup flash 
  * \brief Write the number of sound to be stored.
+ *
    This function store the first TOC byte (numSound), received with the flash
    program command, at the first memory adress. 
  */ 
@@ -309,6 +344,7 @@
 /**
  * \ingroup flash 
  * \brief Write the TOC in the memory.
+ *
  * This function store the the indexes into the memory.
  */ 
 
@@ -343,6 +379,7 @@
 /**
  * \ingroup flash 
  * \brief Initiate the sound programming.
+ *
  * This function initiate the sound flash memory for a sequential programming.
  */ 
 
@@ -374,6 +411,7 @@
 /**
  * \ingroup flash 
  * \brief Program the sound in the flash memory.
+ *
  * This function store the sound in the flash memory.
  */ 
 static void soundProgramming(void)
@@ -415,6 +453,8 @@
 /**
  * \ingroup flash 
  * \brief This function end the flash programming task.
+ *
+ * This function restore all the parameters.
  */ 
 
 static void endProgramming (void)

Modified: firmware/tuxaudio/branches/audio_cleanup/flash.h
===================================================================
--- firmware/tuxaudio/branches/audio_cleanup/flash.h	2007-09-12 11:07:13 UTC (rev 512)
+++ firmware/tuxaudio/branches/audio_cleanup/flash.h	2007-09-12 12:19:00 UTC (rev 513)
@@ -34,20 +34,25 @@
 #ifndef FLASH_H
 #define FLASH_H
 
-/* Flash programming states */
+/** \name Flash programming states
+  @{ */
 #define ERASE_STATE	    0
 #define FIRST_PROG_STATE    1
 #define PROG_TOC_STATE	    2
 #define INIT_SOUND_PROG_STATE 3
 #define SOUND_PROG_STATE    4
 #define END_STATE	    5
+/* @} */
 
 
 
 extern void flashProgramming(void);
 extern void playSound(void);
 
+/** start / end flash states flag */
 extern uint8_t flash_state;
+/** state machine variable */
 extern uint8_t f_state;
+/** sound number to be played */
 extern uint8_t soundNum;
 #endif