CVS: libraries/include/mspgcc eventhandler.h, 1.3, 1.4 flash.h, 1.3, 1.4 fll.h, 1.4, 1.5 ringbuffer.h, 1.1, 1.2 util.h, 1.5, 1.6

Update of /cvsroot/mspgcc/libraries/include/mspgcc
In directory sc8-pr-cvs16.sourceforge.net:/tmp/cvs-serv5153/include/mspgcc

Modified Files:
	eventhandler.h flash.h fll.h ringbuffer.h util.h 
Log Message:
- updated several doxgen comments
- added doxy.conf and make target "doxy" so that library docs can be generated


Index: eventhandler.h
===================================================================
RCS file: /cvsroot/mspgcc/libraries/include/mspgcc/eventhandler.h,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -w -d -r1.3 -r1.4
--- eventhandler.h	24 Mar 2008 16:04:32 -0000	1.3
+++ eventhandler.h	24 Mar 2008 19:00:39 -0000	1.4
@@ -1,9 +1,20 @@
 #ifndef MSPGCC_EVENTHANDLER_H
 #define MSPGCC_EVENTHANDLER_H
+/**
+ * @file
+ *
+ * Bit definitions and function prototypes for the eventhandler.
+ *
+ * http://mspgcc.sf.net
+ */
 
-// Bit definitions and function prototypes for the eventhandler
-// http://mspgcc.sf.net
-// chris <[email protected]>
+
+/**
+\defgroup mspgcc_eventhandler   Eventhandler
+
+Functions and definitions for the eventhandler in libmspgcc.
+@{
+*/
 
 
 #ifndef _GNU_ASSEMBLER_
@@ -40,8 +51,8 @@
  *      mode of the CPU, thus starting events from interrupts also requires
  *      to wake it up. See below for more info and examples.
  *
- * @param eventreginit  Initial value of eventhandler_bits. These events are
- *                      handled right after the start of the eventhandler.
+ * @param eventreginit  [in] Initial value of eventhandler_bits. These events
+ *                      are handled right after the start of the eventhandler.
  */
 void __attribute__((noreturn)) eventhandler(unsigned short eventreginit);
 
@@ -56,7 +67,7 @@
  * If used in an interrupt, do not forget to use a interrupt handler with
  * "wakeup" attribute or call "_BIC_SR_IRQ(LPM4_bits);"
  *
- * @param eventbit      one of the EVENTxx_bits defines or an alias.
+ * @param eventbit      [in] one of the EVENTxx_bits defines or an alias.
  */
 #define EVENTHANDLER_LAUNCH(eventbit) eventhandler_bits |= (eventbit)
 
@@ -70,11 +81,13 @@
  * beeing the bit that is associated with that event. This can be used if a
  * event wants to restart itself: "eventhandler_bits |= eventbit;")
  * 
+ * @code
  *     const EVENTHANDLER_TABLE eventhandler_table[] = {
  *         event_timer,
  *         event_serial,
  *         {0} //sentinel, marks end of list
  *     };
+ * @endcode
  * 
  * There are two ways to find and lauch the events.
  * - manually by defines
@@ -84,19 +97,25 @@
  * lauched by their name. This makes it easier to refactor code later and
  * keep them in sync with the "eventhandler_table".
  *
+ * @code
  *     #define EVENT_timer      EVENT00_bits
  *     #define EVENT_serial     EVENT01_bits
+ * @endcode
  *
  * Then to launch an event from an interrupt:
  *
+ * @code
  *     wakeup interrupt(WDT_VECTOR) intervallTimer(void) {
  *         EVENTHANDLER_LAUNCH(EVENT_timer);
  *     }
+ * @endcode
  *
  * The second variant is to use ::eventhandler_find to determine the event
  * bit at run-time:
  *
+ * @code
  *      EVENTHANDLER_LAUNCH(eventhandler_find(event_timer));
+ * @endcode
  *
  * The disatvantage is that it consumes time at run-time, however it eleminates
  * the list of defines that has to be kept in sync and is thus less error
@@ -107,14 +126,22 @@
 /**
  * Determine the event bit for the given function pointer.
  * 
- * @param event_function        Function pointer to a function that is registered
- *                              in the ::eventhandler_table.
+ * @param event_function        [in] Function pointer to a function that is
+ *                              registered in the ::eventhandler_table.
  * @return event bit (value > 0) or 0 if function is not found in the table.
  */
 unsigned short eventhandler_find(EVENTHANDLER_TABLE event_function);
 
 
 /**
+\defgroup mspgcc_eventhandler_scheduler   Scheduler
+
+Functions and definitions for the sheduler. The Scheduler is a event handler
+that lauches other events based on time.
+@{
+*/
+
+/**
  * This is a special eventhandler: it starts additional events, based on the
  * "event_timetable".
  * 
@@ -128,10 +155,12 @@
  * named scheduler_table.
  * Example:
  *
+ * @code
  *     const SCHEDULER_TABLE scheduler_table[] = {
  *         { modulo: 1, shift: 0, eventbits: EVENT_periodic},
  *         {0} //sentinel, marks the end of the table
  *     };
+ * @endcode
  */
 void event_scheduler(void);
 
@@ -154,6 +183,8 @@
     unsigned short eventbits;           ///< these bits are passed to EVENTHANDLER_LAUNCH
 } SCHEDULER_TABLE;
 
+/** @} */
+
 #else //_GNU_ASSEMBLER_
 // assembler interface
 
@@ -163,15 +194,22 @@
  * If used in an interrupt, do not forget to use a interrupt handler that
  * disables LPM4_bits in SR."
  *
- * @param eventbit      One of the EVENTxx_bits defines or an alias.
+ * @param eventbit      [in] One of the EVENTxx_bits defines or an alias.
  *                      Must be a constant.
  */
 #define EVENTHANDLER_LAUNCH(eventbit)  bis.w #eventbit, eventhandler_bits
 
 #endif //_GNU_ASSEMBLER_
 
-// Bit masks for taskbit register
-// It is recomended to define aliases and not using these directly
+/**
+\defgroup mspgcc_eventhandler_bits   Event bit masks
+
+Bit masks for eventhandler_bits variable.
+It is recomended to define aliases and not using these directly.
+
+@{
+*/
+
 #define EVENT00_bits 0x8000
 #define EVENT01_bits 0x4000
 #define EVENT02_bits 0x2000
@@ -189,5 +227,8 @@
 #define EVENT14_bits 0x0002
 #define EVENT15_bits 0x0001
 
+/** @} */
+
+/** @} */
 
 #endif //MSPGCC_EVENTHANDLER_H

Index: flash.h
===================================================================
RCS file: /cvsroot/mspgcc/libraries/include/mspgcc/flash.h,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -w -d -r1.3 -r1.4
--- flash.h	27 Dec 2005 22:00:08 -0000	1.3
+++ flash.h	24 Mar 2008 19:00:39 -0000	1.4
@@ -2,13 +2,36 @@
 #define MSPGCC_FLASH_H
 
 /**
+ * @file
+ *
+ * Flash memory functions.
+ */
+
+
+/**
+\defgroup mspgcc_flash   Flash erase and write
+
+Flash access functions in libmspgcc.
+- Segment erase
+- SegmentA lock/unlock
+- Write to Flash with a memcopy compatible API.
+  Byte and word based copy implementations are provided.
+
+::flash_write_word needs to be used with care as it only supports reading and
+writing to even addresses, shich has to be ensured by the user of this
+function. If in doubt use ::flash_write.
+
+@{
+*/
+
+/**
  * Erase a single flash segment.
  *
  * This function modifies FCTL1 and FCTL3.
  *
  * @note
  *      SegemntA on F2xx can not be modfied until unlocked with
- *      flash_lock_segmentA(0)
+ *      ::flash_lock_segmentA(0)
  *
  * @note
  *      FCTL2 has to be set up by the user. It is not altered by this
@@ -47,11 +70,13 @@
  *      flash_lock_segmentA(0)
  *
  * Examples:
+ * @code
  *    int intvar = 1234;
  *    flash_write((void *)0x1000, &intvar, sizeof(int));
  *
  *    struct { ... } somestructure;
  *    flash_write((void *)0x1000, &somestructure, sizeof(somestructure));
+ * @endcode
  *
  * @param dst           [in] the memory is written here
  * @param src           [in] the memory that is read
@@ -75,11 +100,13 @@
  *      flash_lock_segmentA(0)
  *
  * Examples:
+ * @code
  *    int intvar = 1234;
  *    flash_write_word((void *)0x1000, &intvar, sizeof(int));
  *
  *    struct { ... } somestructure;
  *    flash_write_word((void *)0x1000, &somestructure, sizeof(somestructure));
+ * @endcode
  *
  * @param dst           [in] the memory is written here (even addresses only!)
  * @param src           [in] the memory that is read (even addresses only!)
@@ -87,4 +114,6 @@
  */
 void flash_write_word(void *dst, const void *src, unsigned int size);
 
+/** @} */
+
 #endif //MSPGCC_FLASH_H

Index: fll.h
===================================================================
RCS file: /cvsroot/mspgcc/libraries/include/mspgcc/fll.h,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -w -d -r1.4 -r1.5
--- fll.h	18 Sep 2006 11:41:31 -0000	1.4
+++ fll.h	24 Mar 2008 19:00:39 -0000	1.5
@@ -2,6 +2,21 @@
 #define MSPGCC_FLL_H
 
 /**
+ * @file
+ *
+ * Softare Frequncy Locked Loop.
+ */
+
+
+/**
+\defgroup mspgcc_fll Frequency Locked Loop
+
+FLL software loop. Used to adjust the internal DCO oscillator of the MSP430
+to a multiply of an external clock source.
+@{
+*/
+
+/**
  * Formula to calculate the multiplier, for fll_adjust(), based on SMCLK
  * and ACLK.
  *
@@ -30,14 +45,18 @@
  *
  * Example, setting the CPU to 3 MHz based on a watch crystal (32.768 kHz):
  *
+ * @code
  *   BCSCTL1 = XT2OFF|RSEL2|DIVA_DIV4;          // select 8192 Hz from XT1
  *   BCSCTL2 = 0;
  *   delay(0xffff);                             // give osillator some time to settle
  *   fll_adjust(FLL_MULTIPLIER(3000000, 8192)); // adjust frequency
+ * @endcode
  *
  * @param multiplier    [in] MCLK = multiplier * ACLK
  */
 void fll_adjust(unsigned short multiplier);
 
+/** @} */
+
 
 #endif //MSPGCC_FLL_H

Index: ringbuffer.h
===================================================================
RCS file: /cvsroot/mspgcc/libraries/include/mspgcc/ringbuffer.h,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -w -d -r1.1 -r1.2
--- ringbuffer.h	22 Aug 2005 11:24:00 -0000	1.1
+++ ringbuffer.h	24 Mar 2008 19:00:39 -0000	1.2
@@ -2,6 +2,22 @@
 #define MSPGCC_RINGBUFFER_H
 
 /**
+ * @file
+ *
+ * An interrupt safe ringbuffer for characters.
+ */
+
+
+/**
+\defgroup mspgcc_ringbuffer   Ringbuffer
+
+A ring buffer for bytes/characters in libmspgcc. The implementation is
+secured against interrupts. It is suitable to use it to pass data from
+interrupts to foreground events or processes.
+@{
+*/
+
+/**
  * Descriptor for a ringbuffer.
  * 
  * To use a ringbuffer, initialize the first two fields and zero the
@@ -21,7 +37,8 @@
 
 /**
  * This macro allocates an new ringbuffer and initializes the descriptor.
- * NOTE: This macro allocates global variables.
+ *
+ * @note This macro allocates two global variables.
  */
 #define RINGBUFFER_NEW(name, size) \
     static char ringmem##name[size]; \
@@ -66,4 +83,6 @@
  */
 int ringbuffer_get(RINGBUFFER_TYPE *buffer);
 
+/** @} */
+
 #endif //MSPGCC_RINGBUFFER_H

Index: util.h
===================================================================
RCS file: /cvsroot/mspgcc/libraries/include/mspgcc/util.h,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -w -d -r1.5 -r1.6
--- util.h	18 Sep 2006 11:41:32 -0000	1.5
+++ util.h	24 Mar 2008 19:00:39 -0000	1.6
@@ -2,7 +2,21 @@
 #define UTIL_H
 
 /**
- * Print a hexdump of the gived memory region. Implemented with printf()
+ * @file
+ *
+ * Utlity fucntions.
+ */
+
+
+/**
+\defgroup mspgcc_unil   Utility functions
+
+Several utility functions in libmspgcc.
+@{
+*/
+
+/**
+ * Print a hexdump of the given memory region. Implemented with printf()
  * as output function.
  *
  * @param buffer        [in] this data is dumped
@@ -27,7 +41,16 @@
 
 
 /**
- * An array containing all the hexadecimal digits "0123456789ABCDEF".
+\defgroup mspgcc_unil_stringfu   String functions
+
+Encode and decode strings.
+- escape
+- hexlify
+@{
+*/
+
+/**
+ * An array containing all the hexadecimal digits "0123456789ABCDEF" (uppercase).
  * This can be used to convert a nibble to a hex number.
  */
 extern const unsigned char HEX_DIGITS[16];
@@ -35,36 +58,39 @@
 /**
  * Encode a binary buffer of given size to a string of hexdigits (null terminated).
  *
- * @param dst           the resulting hex string
- * @param maxsize       available number of bytes in the output string
- * @param src           source binary buffer
- * @param size          number of binary bytes that should be encoded
+ * @param dst           [out] the resulting hex string
+ * @param maxsize       [in] available number of bytes in the output string
+ * @param src           [in] source binary buffer
+ * @param size          [in] number of binary bytes that should be encoded
  * @return              Number of hex digits in the encoded result. The return 
- *                      value smaller maxsize on success, equal or larger if the
- *                      result was truncated.
+ *                      value smaller maxsize on success, equal or larger if
+ *                      the result was truncated.
  */
 unsigned int hex_encode(char *dst, unsigned int maxsize, const void *src, unsigned int size);
 
 /**
  * Decode a string of hexdigits into a binary buffer.
  *
- * @param dst           the resulting binary
- * @param maxsize       available number of bytes in the output string
- * @param src           source string of hex digits
- * @param size          number of characters that should be decoded. this is an
- *                      even number as each hex encoded byte consists of two characters.
- * @return              Number of binary bytes that got decoded. The return value
- *                      is equal to size on success, smaller if the dst buffer
- *                      was too small.
+ * @param dst           [out] the resulting binary
+ * @param maxsize       [in] available number of bytes in the output string
+ * @param src           [in] source string of hex digits
+ * @param size          [in] number of characters that should be decoded. This
+ *                      is an even number as each hex encoded byte consists of
+ *                      two characters.
+ * @return              Number of binary bytes that got decoded. The return
+ *                      value is equal to size on success, smaller if the dst
+ *                      buffer was too small.
  */
 unsigned int hex_decode(void *dst, unsigned int maxsize, const char *src, unsigned int size);
 
 /**
  * Decode a string of hexdigits into a binary buffer.
  *
- * @param srcdst        source string of hex digits and the target for the resulting binary
- * @param size          number of characters that should be decoded. this is an
- *                      even number as each hex encoded byte consists of two characters
+ * @param srcdst        [in/out] source string of hex digits and the target for
+ *                      the resulting binary
+ * @param size          [in] number of characters that should be decoded. this
+ *                      is an even number as each hex encoded byte consists of
+ *                      two characters.
  * @return              Number of binary bytes that got decoded. The return value
  *                      is equal to size on success, smaller if the dst buffer
  *                      was too small.
@@ -74,14 +100,11 @@
 /**
  * Convert a hex digit (ASCII character) to a number
  *
- * @param x             a character
+ * @param x             [in] a character
  * @return              0...15, 0 for illegal characters
  */
 unsigned char hex_fromdigit(unsigned char x);
 
-/** An array containing all hex digits as characters (uppercase). */
-extern const unsigned char HEX_DIGITS[16];
-
 
 /**
  * Decode an escaped, null terminated string to a binary buffer.
@@ -94,9 +117,9 @@
  * the string with escapes is of the same length or longer than the resulting
  * binary buffer data.
  *
- * @param dst           the resulting binary
- * @param maxsize       available number of bytes in the output buffer dst
- * @param src           source string with escapes
+ * @param dst           [out] the resulting binary
+ * @param maxsize       [in] available number of bytes in the output buffer dst
+ * @param src           [in] source string with escapes
  * @return              Number of characters in the dst buffer
  *                      The return value is equal to size on success, smaller
  *                      if the dst buffer was too small.
@@ -110,17 +133,26 @@
  * for control characters. unlike C's escape rules \\xNN generates two digits
  * the next character does not belong to the number even if it is a hex digit.
  *
- * @param dst           the resulting null terminated string
- * @param maxsize       available number of bytes in the output string dst
- * @param src           source (binary) string
- * @param size          number of characters that should be encoded.
+ * @param dst           [out] the resulting null terminated string
+ * @param maxsize       [in] available number of bytes in the output string dst
+ * @param src           [in] source (binary) string
+ * @param size          [in] number of characters that should be encoded.
  * @return              Number of characters in the dst buffer
  *                      The return value is equal to size on success, smaller
  *                      if the dst buffer was too small.
  */
 unsigned int escape_encode(char *dst, unsigned int maxsize, const void *src, unsigned int size);
 
+/** @} */
+
 
+/**
+\defgroup mspgcc_unil_linedit   Line editor
+
+A simple line editor, process characters and store them as a string. Backspace
+deletes.
+@{
+*/
 
 /**
  * Simple line reader. Reads with getchar(), prcoesses with 
@@ -163,10 +195,13 @@
  * 
  * This function generates an echo using putchar().
  *
+ * @param       state           [in] state struct
+ * @param       key             [in] the new key that is to be processed
  * @return      true when the line is complete, false otherwise.
  */
 unsigned char lineeditor_simple_process_key(LINEEDITOR_STATE *state, char key);
 
+/** @} */
 
 /**
  * Simple 16 bit bitwise xor checksum.
@@ -183,4 +218,6 @@
  */
 unsigned short checksum_xor(const void *address, unsigned int length);
 
+/** @} */
+
 #endif //UTIL_H


-------------------------------------------------------------------------
This SF.net email is sponsored by: Microsoft
Defy all challenges. Microsoft(R) Visual Studio 2008.
http://clk.atdmt.com/MRT/go/vse0120000070mrt/direct/01/