From c93c50fbc4034eb16bd1b53dc2e76a14bfa7b22f Mon Sep 17 00:00:00 2001
From: gdisirio <gdisirio@35acf78f-673a-0410-8e92-d51de3d6d3f4>
Date: Tue, 30 Dec 2008 14:26:12 +0000
Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@564
35acf78f-673a-0410-8e92-d51de3d6d3f4
---
src/chsem.c | 4 +-
src/include/condvars.h | 2 +-
src/include/semaphores.h | 2 +-
src/lib/ch.hpp | 153 +++++++++++++++++++++++++++++++++++++++--------
4 files changed, 131 insertions(+), 30 deletions(-)
diff --git a/src/chsem.c b/src/chsem.c
index 1ec852a98..d29e97268 100644
--- a/src/chsem.c
+++ b/src/chsem.c
@@ -118,8 +118,8 @@ msg_t chSemWaitS(Semaphore *sp) {
* @param time the number of ticks before the operation fails
* @retval RDY_OK if the semaphore was signaled or not taken.
* @retval RDY_RESET if the semaphore was reset using \p chSemReset().
- * @retval RDY_TIMEOUT if the semaphore was not signaled or reset within the specified
- * timeout.
+ * @retval RDY_TIMEOUT if the semaphore was not signaled or reset within the
+ * specified timeout.
* @note The function is available only if the \p CH_USE_SEMAPHORES_TIMEOUT
* option is enabled in \p chconf.h.
*/
diff --git a/src/include/condvars.h b/src/include/condvars.h
index 83afe6db7..be23bf6d1 100644
--- a/src/include/condvars.h
+++ b/src/include/condvars.h
@@ -34,7 +34,7 @@
/**
* CondVar structure.
*/
-typedef struct {
+typedef struct CondVar {
ThreadsQueue c_queue;
} CondVar;
diff --git a/src/include/semaphores.h b/src/include/semaphores.h
index 5faa6e97e..ba75d8ba7 100644
--- a/src/include/semaphores.h
+++ b/src/include/semaphores.h
@@ -30,7 +30,7 @@
/**
* Semaphore structure.
*/
-typedef struct {
+typedef struct Semaphore {
/** Queue of the threads sleeping on this Semaphore.*/
ThreadsQueue s_queue;
/** The Semaphore counter.*/
diff --git a/src/lib/ch.hpp b/src/lib/ch.hpp
index a0068cd69..fd016f210 100644
--- a/src/lib/ch.hpp
+++ b/src/lib/ch.hpp
@@ -36,6 +36,8 @@ namespace chibios_rt {
public:
/**
* ChibiOS/RT initialization.
+ * The system is initialized, the idle thread is spawned and the current
+ * instruction flow becomes the main thread with priority @p NORMALPRIO.
*/
static void Init(void);
@@ -55,6 +57,7 @@ namespace chibios_rt {
/**
* Returns the system time as system ticks.
+ * @note the system tick time interval is implementation dependent.
*/
static systime_t GetTime(void);
};
@@ -64,7 +67,10 @@ namespace chibios_rt {
*/
class Timer {
public:
- ::VirtualTimer timer;
+ /**
+ * Embedded @p VirtualTimer structure.
+ */
+ struct ::VirtualTimer timer;
/**
* Starts the timer.
@@ -84,7 +90,9 @@ namespace chibios_rt {
void Reset();
/**
- * Returns true if the timer is armed.
+ * Returns the timer status.
+ * @retval TRUE The timer is armed.
+ * @retval FALSE The timer already fired its callback.
*/
bool IsArmed(void);
};
@@ -95,84 +103,111 @@ namespace chibios_rt {
*/
class BaseThread {
public:
+ /**
+ * Pointer to the system thread.
+ */
::Thread *thread_ref;
/**
* Thread constructor.
+ * The thread object is initialized and a system thread is started.
+ * @param workspace pointer to the workspace area
+ * @param wsize size of the workspace area
+ * @param prio thread priority
*/
BaseThread(void *workspace, size_t wsize, tprio_t prio);
/**
* Thread exit.
+ * @param msg the exit message
*/
static void Exit(msg_t msg);
#ifdef CH_USE_WAITEXIT
/**
* Synchronization on Thread exit.
+ * @return the exit message from the thread
*/
msg_t Wait(void);
#endif /* CH_USE_WAITEXIT */
/**
- * Resumes thread.
+ * Resumes the thread.
+ * The thread encapsulated into the object is resumed.
*/
void Resume(void);
/**
* Change thread priority.
+ * @param newprio the new priority level
*/
static void SetPriority(tprio_t newprio);
/**
* Requests thread termination.
+ * A termination flag is pended on the thread, it is thread responsibility
+ * to detect it and exit.
*/
void Terminate(void);
/**
* Suspends the thread execution for the specified number of system ticks.
+ * @param n the number of system ticks
*/
static void Sleep(systime_t n);
/**
* Suspends the thread execution until the specified time arrives.
+ * @param time the system time
*/
static void SleepUntil(systime_t time);
#ifdef CH_USE_MESSAGES
/**
* Sends a message to the thread and returns the answer.
+ * @param tp the target thread
+ * @param msg the sent message
+ * @return The returned message.
*/
static msg_t SendMessage(::Thread *tp, msg_t msg);
/**
* Sends a message to the thread and returns the answer.
+ * @param msg the sent message
+ * @return The returned message.
*/
msg_t SendMessage(msg_t msg);
/**
* Waits for a message and returns it.
+ * @return The incoming message.
*/
static msg_t WaitMessage(void);
/**
* Returns an enqueued message or \p NULL.
+ * @return The incoming message.
+ * @retval NULL No incoming message.
*/
static msg_t GetMessage(void);
/**
* Releases the next message in queue with a reply.
+ * @param msg the answer message
*/
static void ReleaseMessage(msg_t msg);
/**
* Returns true if there is at least one message in queue.
+ * @retval TRUE A message is waiting in queue.
+ * @retval FALSE A message is not waiting in queue.
*/
static bool IsPendingMessage(void);
#endif /* CH_USE_MESSAGES */
/**
* Thread body function.
+ * @return The exit message.
*/
virtual msg_t Main(void);
};
@@ -188,6 +223,9 @@ namespace chibios_rt {
WORKING_AREA(wa, N); // Thread working area.
public:
+ /**
+ * The thread name.
+ */
const char *name;
/**
@@ -221,38 +259,56 @@ namespace chibios_rt {
*/
class Semaphore {
public:
- ::Semaphore sem;
+ /**
+ * Embedded @p Semaphore structure.
+ */
+ struct ::Semaphore sem;
/**
* Semaphore constructor.
+ * The embedded @p ::Semaphore structure is initialized.
+ * @param n the semaphore counter value, must be greater or equal to zero
*/
Semaphore(cnt_t n);
/**
- * Resets a semaphore to a given positive value.
+ * Resets a semaphore.
+ * @param n the new semaphore counter value, must be greater or equal to zero
*/
void Reset(cnt_t n);
/**
* Wait operation on the semaphore.
+ * @retval RDY_OK if the semaphore was signaled or not taken.
+ * @retval RDY_RESET if the semaphore was reset.
*/
msg_t Wait(void);
#ifdef CH_USE_SEMAPHORES_TIMEOUT
/**
* Wait operation on the semaphore with timeout.
+ * @param time the number of ticks before the operation fails
+ * @retval RDY_OK if the semaphore was signaled or not taken.
+ * @retval RDY_RESET if the semaphore was reset.
+ * @retval RDY_TIMEOUT if the semaphore was not signaled or reset within the
+ * specified timeout.
*/
msg_t WaitTimeout(systime_t time);
#endif /* CH_USE_SEMAPHORES_TIMEOUT */
/**
* Signal operation on the semaphore.
+ * The semaphore is signaled, the next thread in queue, if any, is awakened.
*/
void Signal(void);
#ifdef CH_USE_SEMSW
/**
* Atomic signal and wait operations.
+ * @param ssem pointer to a \p Semaphore to be signaled
+ * @param wsem pointer to a \p Semaphore to be wait on
+ * @retval RDY_OK if the semaphore was signaled or not taken.
+ * @retval RDY_RESET if the semaphore was reset.
*/
static msg_t SignalWait(Semaphore *ssem, Semaphore *wsem);
#endif /* CH_USE_SEMSW */
@@ -265,51 +321,94 @@ namespace chibios_rt {
*/
class Mutex {
public:
- ::Mutex mutex;
+ /**
+ * Embedded @p Mutex structure.
+ */
+ struct ::Mutex mutex;
/**
* Mutex constructor.
+ * The embedded @p ::Mutex structure is initialized.
*/
Mutex(void);
/**
* Tries a lock operation on the mutex.
+ * @retval TRUE if the mutex was successfully acquired
+ * @retval FALSE if the lock attempt failed.
*/
bool TryLock(void);
/**
- * Lock operation on the mutex.
+ * Locks the mutex.
+ * Performs a lock operation on the mutex, if the mutex is already locked
+ * then the thread enters the mutex priority queue and waits.
*/
void Lock(void);
/**
- * Unlock operation on the most recently locked mutex.
+ * Unlocks the mutex.
+ * Performs an unlock operation on the mutex, the next waiting thread, if
+ * any, is resumed and locks the mutex.
*/
static void Unlock(void);
/**
* Unlocks all the mutexes owned by the invoking thread.
+ * This operation is <b>MUCH MORE</b> efficient than releasing the mutexes
+ * one by one and not just because the call overhead, this function does not
+ * have any overhead related to the priority inheritance mechanism.
*/
static void UnlockAll(void);
};
#ifdef CH_USE_CONDVARS
+ /**
+ * Class encapsulating a \p CondVar.
+ */
class CondVar {
public:
- ::CondVar condvar;
+ /**
+ * Embedded @p CondVar structure.
+ */
+ struct ::CondVar condvar;
/**
* CondVar constructor.
+ * The embedded @p ::CondVar structure is initialized.
*/
CondVar(void);
+ /**
+ * Signals the CondVar.
+ * The next thread waiting on the @p CondVar, if any, is awakened.
+ */
void Signal(void);
+ /**
+ * Broadcasts the CondVar.
+ * All the threads waiting on the @p CondVar, if any, are awakened.
+ */
void Broadcast(void);
+ /**
+ * Waits on the CondVar while releasing the controlling mutex.
+ * @return The wakep mode.
+ * @retval RDY_OK if the condvar was signaled using chCondSignal().
+ * @retval RDY_RESET if the condvar was signaled using chCondBroadcast().
+ */
msg_t Wait(void);
#ifdef CH_USE_CONDVARS_TIMEOUT
+ /**
+ * Waits on the CondVar while releasing the controlling mutex.
+ * @param time the number of ticks before the operation fails
+ * @return The wakep mode.
+ * @retval RDY_OK if the condvar was signaled using chCondSignal().
+ * @retval RDY_RESET if the condvar was signaled using chCondBroadcast().
+ * @retval RDY_TIMEOUT if the condvar was not signaled within the specified
+ * timeout.
+ */
msg_t WaitTimeout(systime_t time);
#endif /* CH_USE_CONDVARS_TIMEOUT */
};
@@ -322,10 +421,14 @@ namespace chibios_rt {
*/
class Event {
public:
- EventSource event;
+ /**
+ * Embedded @p EventSource structure.
+ */
+ struct ::EventSource event;
/**
* Event constructor.
+ * The embedded @p ::EventSource structure is initialized.
*/
Event(void);
@@ -346,12 +449,15 @@ namespace chibios_rt {
void RegisterMask(EventListener *elp, eventmask_t emask);
/**
- * Unregisters a listener from the event source.
+ * Unregisters a listener.
+ * The specified listeners is no more signaled by the event source.
+ * @param elp the listener to be unregistered
*/
void Unregister(EventListener *elp);
/**
* Broadcasts an event.
+ * All the listeners registered on the event source are signaled.
*/
void Broadcast(void);
@@ -380,15 +486,10 @@ namespace chibios_rt {
static void Dispatch(const evhandler_t handlers[], eventmask_t mask);
/**
- * Waits and dispatchs events.
- */
- static eventid_t Wait(eventmask_t ewmask, const evhandler_t handlers[]);
-
- /**
- * A pending event among those specified in \p ewmask is selected, cleared and
+ * A pending event among those specified in @p ewmask is selected, cleared and
* its mask returned.
* @param ewmask mask of the events that the function should wait for,
- * \p ALL_EVENTS enables all the events
+ * @p ALL_EVENTS enables all the events
* @return The mask of the lowest id served and cleared event.
* @note One and only one event is served in the function, the one with the
* lowest event id. The function is meant to be invoked into a loop in
@@ -400,17 +501,17 @@ namespace chibios_rt {
/**
* Waits for any of the specified events.
- * The function waits for any event among those specified in \p ewmask to
+ * The function waits for any event among those specified in @p ewmask to
* become pending then the events are cleared and returned.
* @param ewmask mask of the events that the function should wait for,
- * \p ALL_EVENTS enables all the events
+ * @p ALL_EVENTS enables all the events
* @return The mask of the served and cleared events.
*/
static eventmask_t WaitAny(eventmask_t ewmask);
/**
* Waits for all the specified event flags then clears them.
- * The function waits for all the events specified in \p ewmask to become
+ * The function waits for all the events specified in @p ewmask to become
* pending then the events are cleared and returned.
* @param ewmask mask of the event ids that the function should wait for
* @return The mask of the served and cleared events.
@@ -420,10 +521,10 @@ namespace chibios_rt {
#ifdef CH_USE_EVENTS_TIMEOUT
/**
* Waits for a single event.
- * A pending event among those specified in \p ewmask is selected, cleared
+ * A pending event among those specified in @p ewmask is selected, cleared
* and its mask returned.
* @param ewmask mask of the events that the function should wait for,
- * \p ALL_EVENTS enables all the events
+ * @p ALL_EVENTS enables all the events
* @param time the number of ticks before the operation timouts
* @return The mask of the lowest id served and cleared event.
* @retval 0 if the specified timeout expired.
@@ -437,10 +538,10 @@ namespace chibios_rt {
/**
* Waits for any of the specified events.
- * The function waits for any event among those specified in \p ewmask to
+ * The function waits for any event among those specified in @p ewmask to
* become pending then the events are cleared and returned.
* @param ewmask mask of the events that the function should wait for,
- * \p ALL_EVENTS enables all the events
+ * @p ALL_EVENTS enables all the events
* @param time the number of ticks before the operation timouts
* @return The mask of the served and cleared events.
* @retval 0 if the specified timeout expired.
@@ -449,7 +550,7 @@ namespace chibios_rt {
/**
* Waits for all the specified event flags then clears them.
- * The function waits for all the events specified in \p ewmask to become
+ * The function waits for all the events specified in @p ewmask to become
* pending then the events are cleared and returned.
* @param ewmask mask of the event ids that the function should wait for
* @param time the number of ticks before the operation timouts
--
cgit v1.2.3