Merge pull request #26 from LudwigOrtmann/master

added and improved doxygen documentation

cpu/cc430/cc430-rtc.c

@@ -24,6 +24,10 @@ and the mailinglist (subscription via web site)
 	scatterweb@lists.spline.inf.fu-berlin.de
 *******************************************************************************/
 
+/**
+ * @ingroup rtc
+ */
+
 #include <string.h>
 #include <signal.h>
 #include <irq.h>

cpu/lpc2387/lpc2387-lpm.c

@@ -26,6 +26,7 @@ and the mailinglist (subscription via web site)
 
 /**
  * @ingroup lpc2387
+ * @ingroup lpm
  * @{
  */
 

cpu/native/hwtimer_cpu.c

 /**
  * Native CPU hwtimer_arch.h implementation
  *
+ * Uses POSIX real-time extension timers to mimic hardware timers.
+ * XXX: see hwtimer_isr_timer()
+ *
  * Copyright (C) 2013 Ludwig Ortmann
  *
  * This file subject to the terms and conditions of the GNU General Public
  * License. See the file LICENSE in the top level directory for more details.
  *
- * @ingroup arch
+ * @ingroup hwtimer
+ * @ingroup native_cpu
  * @{
- * @file
  * @author  Ludwig Ortmann <ludwig.ortmann@fu-berlin.de>
+ * @file
  * @}
  */
 
@@ -26,25 +30,34 @@
 
 #include "debug.h"
 
-#define HWTIMER_MINTICKS (1000)
-
 static unsigned long native_hwtimer_now;
 static int native_hwtimer_irq[ARCH_MAXTIMERS];
 static timer_t native_hwtimer_timer[ARCH_MAXTIMERS];
 static void (*int_handler)(int);
 
+/**
+ * sets timespec to given ticks
+ */
 void ticks2ts(unsigned long ticks, struct timespec *tp)
 {
    tp->tv_sec = ticks / HWTIMER_SPEED;
    tp->tv_nsec = (ticks % HWTIMER_SPEED)*1000 ;
 }
 
+/**
+ * returns ticks for give timespec
+ */
 unsigned long ts2ticks(struct timespec *tp)
 {
     /* TODO: check for overflow */
     return((tp->tv_sec * HWTIMER_SPEED) + (tp->tv_nsec/1000));
 }
 
+/**
+ * native timer signal handler,
+ * 
+ * XXX: Calls callback for all timers whenever any timer finishes.
+ */
 void hwtimer_isr_timer()
 {
     DEBUG("hwtimer_isr_timer()\n");
@@ -95,10 +108,6 @@ void hwtimer_arch_unset(short timer)
     return;
 }
 
-/**
- * Set a kernel timer to raise an interrupt after ::offset kernel timer ticks
- * from now.
- */
 void hwtimer_arch_set(unsigned long offset, short timer)
 {
     struct itimerspec its;

cpu/native/include/cpu.h

 /**
  * Native CPU interface
  *
+ * The native CPU uses system calls to simulate hardware access.
+ *
  * Copyright (C) 2013 Ludwig Ortmann
  *
  * This file subject to the terms and conditions of the GNU General Public
  * License. See the file LICENSE in the top level directory for more details.
- *
+ */
+
+/**
  * @ingroup arch
+ * @defgroup    native_cpu  Native CPU
  * @{
- * @file
  * @author  Ludwig Ortmann <ludwig.ortmann@fu-berlin.de>
- * @}
  */
 
 #ifndef _CPU_H
@@ -30,8 +33,18 @@
 void dINT(void);
 void eINT(void);
 
+/**
+ * register interrupt handler handler for interrupt sig
+ */
 int register_interrupt(int sig, void *handler);
+
+/**
+ * unregister interrupt handler for interrupt sig
+ */
 int unregister_interrupt(int sig);
+
+/* this should be defined elsewhere */
 void thread_yield(void);
 
+/** @} */
 #endif //_CPU_H

cpu/native/include/hwtimer_cpu.h

@@ -6,8 +6,8 @@
  * This file subject to the terms and conditions of the GNU General Public
  * License. See the file LICENSE in the top level directory for more details.
  *
- * @ingroup arch
  * @{
+ * @ingroup native_hwtimer
  * @file
  * @author  Ludwig Ortmann <ludwig.ortmann@fu-berlin.de>
  * @}

cpu/native/irq_cpu.c

 /**
  * Native CPU irq.h implementation
  *
+ * uses POSIX real-time extension signals to create interrupts
+ * TODO: needs to be rewritten for better portability
+ * 
  * Copyright (C) 2013 Ludwig Ortmann
  *
  * This file subject to the terms and conditions of the GNU General Public
  * License. See the file LICENSE in the top level directory for more details.
  *
- * @ingroup arch
+ * @ingroup native_cpu
+ * @ingroup irq
  * @{
  * @file
  * @author  Ludwig Ortmann <ludwig.ortmann@fu-berlin.de>
- * @}
  */
 #include <signal.h>
 #include <err.h>
@@ -34,6 +37,9 @@ struct int_handler_t {
 };
 static struct int_handler_t native_irq_handlers[255];
 
+/**
+ * block signals
+ */
 unsigned disableIRQ(void)
 {
     unsigned int prev_state;
@@ -60,6 +66,9 @@ unsigned disableIRQ(void)
     return prev_state;
 }
 
+/**
+ * unblock signals
+ */
 unsigned enableIRQ(void)
 {
     unsigned int prev_state;
@@ -181,8 +190,10 @@ void native_isr_entry(int sig, siginfo_t *info, void *context)
 }
 
 /**
+ * register signal/interrupt handler for signal sig
+ *
  * TODO: check sa_flags for appropriateness
- * TODO: use appropriate data structure (hashmap?) for signal
+ * TODO: use appropriate data structure for signal
  *       handlers.
  */
 int register_interrupt(int sig, void *handler)
@@ -212,6 +223,8 @@ int register_interrupt(int sig, void *handler)
 }
 
 /**
+ * empty signal mask
+ *
  * TODO: see register_interrupt
  * TODO: ignore signal
  */
@@ -232,13 +245,16 @@ int unregister_interrupt(int sig)
     sa.sa_flags = SA_RESTART | SA_SIGINFO;
 
     if (sigaction(sig, &sa, NULL)) {
-        err(1, "register_interrupt: sigaction");
+        err(1, "unregister_interrupt: sigaction");
     }
     return 0;
 }
 
 
 /**
+ * register internal signal handler,
+ * initalize local variables
+ *
  * TODO: see register_interrupt
  */
 void native_interrupt_init(void)
@@ -269,3 +285,4 @@ void native_interrupt_init(void)
 
     puts("RIOT native interrupts/signals initialized.");
 }
+/** @} */

cpu/native/lpm_cpu.c

 /**
  * Native CPU lpm.h implementation
  *
+ * Uses system calls to emulate CPU power modes.
+ *
  * Copyright (C) 2013 Ludwig Ortmann
  *
  * This file subject to the terms and conditions of the GNU General Public
  * License. See the file LICENSE in the top level directory for more details.
  *
- * @ingroup arch
+ * @ingroup lpm
+ * @ingroup native_cpu
  * @{
  * @file
  * @author  Ludwig Ortmann <ludwig.ortmann@fu-berlin.de>
@@ -28,6 +31,11 @@ void lpm_init(void)
     return;
 }
 
+/**
+ * LPM_IDLE uses sleep() to wait for interrupts
+ * LPM_OFF exits process
+ * other modes not supported at the moment
+ */
 enum lpm_mode lpm_set(enum lpm_mode target)
 {
     enum lpm_mode last_lpm;
@@ -90,6 +98,7 @@ void lpm_end_awake(void)
     native_lpm = LPM_ON;
     return;
 }
+
 enum lpm_mode lpm_get(void)
 {
     return native_lpm;

cpu/native/native_cpu.c

 /**
  * Native CPU kernel_intern.h and sched.h implementation
  *
+ * in-process preemptive context switching utilizes POSIX ucontexts.
+ * (ucontext provides for architecture independent stack handling)
+ *
  * Copyright (C) 2013 Ludwig Ortmann
  *
  * This file subject to the terms and conditions of the GNU General Public
  * License. See the file LICENSE in the top level directory for more details.
  *
- * @ingroup arch
+ * @ingroup native_cpu
  * @{
  * @file
  * @author  Ludwig Ortmann <ludwig.ortmann@fu-berlin.de>
- * @}
  */
 #include <stdio.h>
 #include <ucontext.h>
@@ -109,3 +111,4 @@ void native_cpu_init()
     makecontext(&native_context, sched_task_exit, 0);
     puts("RIOT native cpu initialized.");
 }
+/** @} */

cpu/native/rtc/posix-rtc.c

 /**
  * Native CPU rtc.h implementation
  *
+ * The native rtc implementation uses POSIX system calls to simulate a
+ * real-time clock.
+ *
+ * Setting the clock will be implemented using a delta variable.
+ *
  * Copyright (C) 2013 Ludwig Ortmann
  *
  * This file subject to the terms and conditions of the GNU General Public
  * License. See the file LICENSE in the top level directory for more details.
  *
- * @ingroup arch
- * @{
- * @file
  * @author  Ludwig Ortmann <ludwig.ortmann@fu-berlin.de>
- * @}
+ *
+ * @ingroup native_cpu
+ * @ingroup rtc
+ * @file
  */
 
 #include <time.h>
@@ -22,47 +27,30 @@
 
 static int native_rtc_enabled;
 
-/**
- * @brief Initializes the RTC for calendar mode
- */
 void rtc_init(void)
 {
     native_rtc_enabled = 0;
     printf("native rtc initialized\n");
 }
 
-/**
- * @brief Starts the RTC
- */
 void rtc_enable(void)
 {
     DEBUG("rtc_enable\n");
     native_rtc_enabled = 1;
 }
 
-/**
- * @brief Stops the RTC
- */
 void rtc_disable(void)
 {
     DEBUG("rtc_disable()\n");
     native_rtc_enabled = 0;
 }
 
-/**
- * @brief	Sets the current time in broken down format directly from to RTC
- * @param[in]	localt		Pointer to structure with time to set
- */
 void rtc_set_localtime(struct tm* localt)
 {
     DEBUG("rtc_set_localtime()\n");
     printf("setting time not supported.");
 }
 
-/**
- * @brief	Returns the current time in broken down format directly from the RTC
- * @param[out]	localt		Pointer to structure to receive time
- */
 void rtc_get_localtime(struct tm* localt)
 {
     time_t t;

doc/doxygen/riot.doxyfile

@@ -85,7 +85,7 @@ WARN_LOGFILE           =
 #---------------------------------------------------------------------------
 # configuration options related to the input files
 #---------------------------------------------------------------------------
-INPUT                  = ../../core ../../cpu ../../board ../../sys src/ ../../drivers
+INPUT                  = ../../core ../../cpu ../../../boards ../../sys src/ ../../drivers
 INPUT_ENCODING         = UTF-8
 FILE_PATTERNS          = *.txt *.c *.h 
 RECURSIVE              = YES

drivers/include/ltc4150_arch.h

@@ -29,7 +29,7 @@ and the mailinglist (subscription via web site)
 
 /**
  * @defgroup    ltc4150 LTC4150 Coulomb Counter
- * @ingroup     coulomb
+ * @ingroup     drivers
  * @{
  */
 
@@ -48,11 +48,21 @@ and the mailinglist (subscription via web site)
 #define _R_SENSE (double)0.330
 #define SUPPLY_VOLTAGE  (5)
 
+/** board specific ltc4150 interrupt disable */
 void ltc4150_disable_int(void);
+/** board specific ltc4150 interrupt enable */
 void ltc4150_enable_int(void);
+/** board specific synchronization of ltc4150 */
 void ltc4150_sync_blocking(void); 
+/** board specific ltc4150 initialization */
 void ltc4150_arch_init(void);
+
+/**
+ * ltc4150 interrupt handler,
+ * shall be called on ltc4150 interrupt,
+ * implemented in driver
+ */
 void ltc4150_interrupt(void);
 
-/** @} */
+/** * @} */
 #endif /* __LTC4150_ARCH_H */

drivers/include/rtc.h

@@ -24,6 +24,12 @@ and the mailinglist (subscription via web site)
 	scatterweb@lists.spline.inf.fu-berlin.de
 *******************************************************************************/
 
+/**
+ * @defgroup rtc Realtime Clock
+ * @ingroup drivers
+ * @{
+ */
+
 #ifndef RTC_H
 #define RTC_H
 
@@ -61,3 +67,4 @@ void rtc_get_localtime(struct tm* localt);
 extern int rtc_second_pid;
 
 #endif
+/** @} */

drivers/include/sht11.h

@@ -27,7 +27,7 @@ and the mailinglist (subscription via web site)
 
 /**
  * @defgroup	sht11	Sensirion SHT11 Driver
- * @ingroup		dev
+ * @ingroup		drivers
  * @{
  */