From c93c50fbc4034eb16bd1b53dc2e76a14bfa7b22f Mon Sep 17 00:00:00 2001 From: gdisirio Date: Tue, 30 Dec 2008 14:26:12 +0000 Subject: [PATCH] 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 MUCH MORE 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