From 175300e58c29f4332b16422d6d906445d75a16b6 Mon Sep 17 00:00:00 2001
From: Ludwig Ortmann <ludwig.ortmann@fu-berlin.de>
Date: Wed, 13 Mar 2013 21:56:56 +0100
Subject: [PATCH] add native cpu doxygen documentation, also fix and improve
some of the existing
---
cpu/cc430/cc430-rtc.c | 4 ++++
cpu/lpc2387/lpc2387-lpm.c | 1 +
cpu/native/hwtimer_cpu.c | 23 +++++++++++++++++------
cpu/native/include/cpu.h | 19 ++++++++++++++++---
cpu/native/include/hwtimer_cpu.h | 2 +-
cpu/native/irq_cpu.c | 23 ++++++++++++++++++++---
cpu/native/lpm_cpu.c | 11 ++++++++++-
cpu/native/native_cpu.c | 7 +++++--
cpu/native/rtc/posix-rtc.c | 30 +++++++++---------------------
drivers/include/ltc4150_arch.h | 14 ++++++++++++--
drivers/include/rtc.h | 7 +++++++
drivers/include/sht11.h | 2 +-
12 files changed, 103 insertions(+), 40 deletions(-)
diff --git a/cpu/cc430/cc430-rtc.c b/cpu/cc430/cc430-rtc.c
index f37de37328..c34dcddd5f 100644
--- a/cpu/cc430/cc430-rtc.c
+++ b/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>
diff --git a/cpu/lpc2387/lpc2387-lpm.c b/cpu/lpc2387/lpc2387-lpm.c
index 8261873d40..468797e83e 100644
--- a/cpu/lpc2387/lpc2387-lpm.c
+++ b/cpu/lpc2387/lpc2387-lpm.c
@@ -26,6 +26,7 @@ and the mailinglist (subscription via web site)
/**
* @ingroup lpc2387
+ * @ingroup lpm
* @{
*/
diff --git a/cpu/native/hwtimer_cpu.c b/cpu/native/hwtimer_cpu.c
index 3d362575d4..3ee6d7637a 100644
--- a/cpu/native/hwtimer_cpu.c
+++ b/cpu/native/hwtimer_cpu.c
@@ -1,15 +1,19 @@
/**
* 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
* @}
*/
@@ -33,18 +37,29 @@ 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 +110,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;
diff --git a/cpu/native/include/cpu.h b/cpu/native/include/cpu.h
index 50effea7cb..d2c0fbd144 100644
--- a/cpu/native/include/cpu.h
+++ b/cpu/native/include/cpu.h
@@ -1,16 +1,19 @@
/**
* 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
diff --git a/cpu/native/include/hwtimer_cpu.h b/cpu/native/include/hwtimer_cpu.h
index 630741dfc3..1a66fa7e13 100644
--- a/cpu/native/include/hwtimer_cpu.h
+++ b/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>
* @}
diff --git a/cpu/native/irq_cpu.c b/cpu/native/irq_cpu.c
index abc88f8884..89c2acdf60 100644
--- a/cpu/native/irq_cpu.c
+++ b/cpu/native/irq_cpu.c
@@ -1,16 +1,19 @@
/**
* 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
*/
@@ -239,6 +252,9 @@ int unregister_interrupt(int sig)
/**
+ * 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.");
}
+/** @} */
diff --git a/cpu/native/lpm_cpu.c b/cpu/native/lpm_cpu.c
index 6e39ce3aeb..9d13ab7229 100644
--- a/cpu/native/lpm_cpu.c
+++ b/cpu/native/lpm_cpu.c
@@ -1,12 +1,15 @@
/**
* 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;
diff --git a/cpu/native/native_cpu.c b/cpu/native/native_cpu.c
index b4f49e9a54..cb6b8b722a 100644
--- a/cpu/native/native_cpu.c
+++ b/cpu/native/native_cpu.c
@@ -1,16 +1,18 @@
/**
* 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.");
}
+/** @} */
diff --git a/cpu/native/rtc/posix-rtc.c b/cpu/native/rtc/posix-rtc.c
index 98629d281b..22444d65f1 100644
--- a/cpu/native/rtc/posix-rtc.c
+++ b/cpu/native/rtc/posix-rtc.c
@@ -1,16 +1,21 @@
/**
* 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;
diff --git a/drivers/include/ltc4150_arch.h b/drivers/include/ltc4150_arch.h
index 84a5c68102..90fe5de20e 100644
--- a/drivers/include/ltc4150_arch.h
+++ b/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 */
diff --git a/drivers/include/rtc.h b/drivers/include/rtc.h
index 25b0d8759b..e1ade0c791 100644
--- a/drivers/include/rtc.h
+++ b/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
+/** @} */
diff --git a/drivers/include/sht11.h b/drivers/include/sht11.h
index 00f00e0bd1..cb615f7848 100644
--- a/drivers/include/sht11.h
+++ b/drivers/include/sht11.h
@@ -27,7 +27,7 @@ and the mailinglist (subscription via web site)
/**
* @defgroup sht11 Sensirion SHT11 Driver
- * @ingroup dev
+ * @ingroup drivers
* @{
*/
--
GitLab