git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@649 35acf78f-673a-0410-8e92-d51de3d6d3f4

1 files changed, 158 insertions, 109 deletions

diff --git a/src/lib/ch.hpp b/src/lib/ch.hpp
index 2d34a0563..4a052ed39 100644
--- a/src/lib/ch.hpp
+++ b/src/lib/ch.hpp
@@ -30,50 +30,55 @@
 namespace chibios_rt {

 

   /**

-   * Class encapsulating the base system functionalities.

+   * @brief Class encapsulating the base system functionalities.

    */

   class System {

   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.

+     * @brief ChibiOS/RT initialization.

+     * @details 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);

 

     /**

-     * Disables interrupts.

+     * @brief Kernel lock.

+     *

      * @note On some ports it is faster to invoke chSysLock() directly because

      *       inlining.

      */

     static void Lock(void);

 

     /**

-     * Enables interrupts.

+     * @brief Kernel unlock.

+     *

      * @note On some ports it is faster to invoke chSysUnlock() directly

      *       because inlining.

      */

     static void Unlock(void);

 

     /**

-     * Returns the system time as system ticks.

+     * @brief Returns the system time as system ticks.

+     *

      * @note the system tick time interval is implementation dependent.

      */

     static systime_t GetTime(void);

   };

 

   /**

-   * Timer class.

+   * @brief Timer class.

    */

   class Timer {

   public:

     /**

-     * Embedded @p VirtualTimer structure.
+     * @brief Embedded @p VirtualTimer structure.
      */

     struct ::VirtualTimer timer;

 

     /**

-     * Starts the timer.

+     * @brief Starts the timer.

+     *

      * @param time the time in system ticks

      * @param vtfunc the timer callback function

      * @param par the parameter for the callback function

@@ -83,14 +88,16 @@ namespace chibios_rt {
     void Set(systime_t time, vtfunc_t vtfunc, void *par);

 

     /**

-     * Resets the timer.

+     * @brief Resets the timer.

+     *

      * @note It must be called with the interrupts disabled.

      * @note The timer MUST be active when this function is invoked.

      */

     void Reset();

 

     /**

-     * Returns the timer status.

+     * @brief Returns the timer status.

+     *

      * @retval TRUE The timer is armed.

      * @retval FALSE The timer already fired its callback.

      */

@@ -98,19 +105,21 @@ namespace chibios_rt {
   };

 

   /**

-   * Base class for a ChibiOS/RT thread, the thread body is the virtual

-   * function @p Main().

+   * @brief Base class for a ChibiOS/RT thread.

+   * @details The thread body is the virtual function @p Main().

    */

   class BaseThread {

   public:

     /**

-     * Pointer to the system thread.
+     * @brief Pointer to the system thread.
      */

     ::Thread *thread_ref;

 

     /**

-     * Thread constructor.

-     * The thread object is initialized and a system thread is started.

+     * @brief Thread constructor.

+     * @details 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

@@ -118,53 +127,60 @@ namespace chibios_rt {
     BaseThread(void *workspace, size_t wsize, tprio_t prio);

 

     /**

-     * Thread exit.

+     * @brief Thread exit.

+     *

      * @param msg the exit message

      */

     static void Exit(msg_t msg);

 

 #ifdef CH_USE_WAITEXIT

     /**

-     * Synchronization on Thread exit.

+     * @brief Synchronization on Thread exit.

+     *

      * @return the exit message from the thread

      */

     msg_t Wait(void);

 #endif /* CH_USE_WAITEXIT */

 

     /**

-     * Resumes the thread.

-     * The thread encapsulated into the object is resumed.

+     * @brief Resumes the thread.

+     * @details The thread encapsulated into the object is resumed.

      */

     void Resume(void);

 

     /**

-     * Change thread priority.

+     * @brief Changes the 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.

+     * @brief Requests thread termination.

+     * @details 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.

+     * @brief 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.

+     * @brief 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.

+     * @brief Sends a message to the thread and returns the answer.

+     *

      * @param tp the target thread

      * @param msg the sent message

      * @return The returned message.

@@ -172,33 +188,38 @@ namespace chibios_rt {
     static msg_t SendMessage(::Thread *tp, msg_t msg);

 

     /**

-     * Sends a message to the thread and returns the answer.

+     * @brief 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.

+     * @brief Waits for a message and returns it.

+     *

      * @return The incoming message.

      */

     static msg_t WaitMessage(void);

 

     /**

-     * Returns an enqueued message or @p NULL.

+     * @brief 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.

+     * @brief 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.

+     * @brief 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.

      */

@@ -206,15 +227,18 @@ namespace chibios_rt {
 #endif /* CH_USE_MESSAGES */

 

     /**

-     * Thread body function.

+     * @brief Thread body function.

+     *

      * @return The exit message.

      */

     virtual msg_t Main(void);

   };

 

   /**

-   * Enhanced threads template class. This class introduces thread names

-   * and static working area allocation.

+   * @brief Enhanced threads template class.

+   * @details This class introduces thread names and static working area

+   * allocation.

+   *

    * @param N the working area size for the thread class

    */

   template <int N>

@@ -224,13 +248,14 @@ namespace chibios_rt {
 

   public:

     /**

-     * The thread name.
+     * @brief The thread name.
      */

     const char *name;

 

     /**

-     * Full constructor. It allows to set a priority level for the new thread

-     * and specify the special option flags.

+     * @brief Full constructor.

+     * @details This constructor allows to set a priority level for the new

+     * thread.

      * @param tname the name to be assigned to the thread

      * @param prio the priority to be assigned to the thread

      */

@@ -241,9 +266,10 @@ namespace chibios_rt {
     }

 

     /**

-     * Simplified constructor, it allows to create a thread by simply

-     * specifying a name. In is assumed @p NORMALPRIO as initial priority

-     * and no special option flags.

+     * @brief Simplified constructor.

+     * @details This constructor allows to create a thread by simply

+     * specifying a name. In is assumed @p NORMALPRIO as initial priority.

+     *

      * @param tname the name to be assigned to the thread

      */

     EnhancedThread(const char *tname) :

@@ -255,30 +281,33 @@ namespace chibios_rt {
 

 #ifdef CH_USE_SEMAPHORES

   /**

-   * Class encapsulating a @p Semaphore.

+   * @brief Class encapsulating a @p Semaphore.

    */

   class Semaphore {

   public:

     /**

-     * Embedded @p Semaphore structure.

+     * @brief Embedded @p Semaphore structure.

      */

     struct ::Semaphore sem;

 

     /**

-     * Semaphore constructor.

-     * The embedded @p ::Semaphore structure is initialized.

+     * @brief Semaphore constructor.

+     * @details 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.

-    * @param n the new semaphore counter value, must be greater or equal to zero

+     * @brief 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.

+     * @brief Wait operation on the semaphore.

+     *

      * @retval RDY_OK if the semaphore was signaled or not taken.

      * @retval RDY_RESET if the semaphore was reset.

      */

@@ -286,7 +315,8 @@ namespace chibios_rt {
 

 #ifdef CH_USE_SEMAPHORES_TIMEOUT

     /**

-     * Wait operation on the semaphore with timeout.

+     * @brief 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.

@@ -297,14 +327,16 @@ namespace chibios_rt {
 #endif /* CH_USE_SEMAPHORES_TIMEOUT */

 

     /**

-     * Signal operation on the semaphore.

-     * The semaphore is signaled, the next thread in queue, if any, is awakened.

+     * @brief Signal operation on the semaphore.

+     * @details 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.

+     * @brief 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.

@@ -317,82 +349,85 @@ namespace chibios_rt {
 

 #ifdef CH_USE_MUTEXES

   /**

-   * Class encapsulating a @p Mutex.

+   * @brief Class encapsulating a @p Mutex.

    */

   class Mutex {

   public:

     /**

-     * Embedded @p Mutex structure.

+     * @brief Embedded @p Mutex structure.

      */

     struct ::Mutex mutex;

 

     /**

-     * Mutex constructor.

-     * The embedded @p ::Mutex structure is initialized.

+     * @brief Mutex constructor.

+     * @details The embedded @p ::Mutex structure is initialized.

      */

     Mutex(void);

 

     /**

-     * Tries a lock operation on the mutex.

+     * @brief 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);

 

     /**

-     * 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.

+     * @brief Locks the mutex.

+     * @details 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);

 

     /**

-     * Unlocks the mutex.

-     * Performs an unlock operation on the mutex, the next waiting thread, if

-     * any, is resumed and locks the mutex.

+     * @brief Unlocks the mutex.

+     * @details 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.

+     * @brief Unlocks all the mutexes owned by the invoking thread.

+     * @details 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.

+   * @brief Class encapsulating a @p CondVar.

    */

   class CondVar {

   public:

     /**

-     * Embedded @p CondVar structure.

+     * @brief Embedded @p CondVar structure.

      */

     struct ::CondVar condvar;

 

     /**

-     * CondVar constructor.

-     * The embedded @p ::CondVar structure is initialized.

+     * @brief CondVar constructor.

+     * @details The embedded @p ::CondVar structure is initialized.

      */

     CondVar(void);

 

     /**

-     * Signals the CondVar.

-     * The next thread waiting on the @p CondVar, if any, is awakened.
+     * @brief Signals the CondVar.

+     * @details 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.

+     * @brief Broadcasts the CondVar.
+     * @details All the threads waiting on the @p CondVar, if any, are awakened.

      */

     void Broadcast(void);

 

     /**

-     * Waits on the CondVar while releasing the controlling mutex.
+     * @brief 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().

@@ -401,7 +436,8 @@ namespace chibios_rt {
 

 #ifdef CH_USE_CONDVARS_TIMEOUT

     /**

-     * Waits on the CondVar while releasing the controlling mutex.

+     * @brief 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().

@@ -417,30 +453,32 @@ namespace chibios_rt {
 

 #ifdef CH_USE_EVENTS

   /**

-   * Class encapsulating an @p EventSource.

+   * @brief Class encapsulating an @p EventSource.

    */

   class Event {

   public:

     /**

-     * Embedded @p EventSource structure.

+     * @brief Embedded @p EventSource structure.

      */

     struct ::EventSource event;

 

     /**

-     * Event constructor.

-     * The embedded @p ::EventSource structure is initialized.

+     * @brief Event constructor.

+     * @details The embedded @p ::EventSource structure is initialized.

      */

     Event(void);

 

     /**

-     * Registers a listener on the event source.

+     * @brief Registers a listener on the event source.

+     *

      * @param elp pointer to the @p EventListener structure

      * @param eid numeric identifier assigned to the Event Listener

      */

     void Register(EventListener *elp, eventid_t eid);

 

     /**

-     * Registers an Event Listener on an Event Source.

+     * @brief Registers an Event Listener on an Event Source.

+     *

      * @param elp pointer to the @p EventListener structure

      * @param emask the mask of event flags to be pended to the thread when the

      *              event source is broadcasted

@@ -449,35 +487,40 @@ namespace chibios_rt {
     void RegisterMask(EventListener *elp, eventmask_t emask);

 

     /**

-     * Unregisters a listener.

-     * The specified listeners is no more signaled by the event source.

+     * @brief Unregisters a listener.

+     * @details 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.

+     * @brief Broadcasts an event.

+     * @details All the listeners registered on the event source are signaled.

      */

     void Broadcast(void);

 

     /**

-     * Clears specified events from the pending events mask.

+     * @brief Clears specified events from the pending events mask.

+     *

      * @param mask the events to be cleared

      * @return The pending events that were cleared.

      */

     static eventmask_t Clear(eventmask_t mask);

 

     /**

-     * Makes an events mask pending in the current thread, this is \b much

-     * faster than using @p Broadcast().

+     * @brief Makes an events mask pending in the current thread.

+     * @details This functon is @b much faster than using @p Broadcast().

+     *

      * @param mask the events to be pended

      * @return The current pending events mask.

      */

     static eventmask_t Pend(eventmask_t mask);

 

     /**

-     * Invokes the event handlers associated with a mask.

+     * @brief Invokes the event handlers associated with a mask.

+     *

      * @param mask mask of the events to be dispatched

      * @param handlers an array of @p evhandler_t. The array must be

      *                 have indexes from zero up the higher registered event

@@ -486,8 +529,10 @@ namespace chibios_rt {
     static void Dispatch(const evhandler_t handlers[], eventmask_t mask);

 

     /**

-     * A pending event among those specified in @p ewmask is selected, cleared and

-     * its mask returned.

+     * @brief Waits for a single event.

+     * @details 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

      * @return The mask of the lowest id served and cleared event.

@@ -500,9 +545,10 @@ namespace chibios_rt {
     static eventmask_t WaitOne(eventmask_t ewmask);

 

     /**

-     * Waits for any of the specified events.

-     * The function waits for any event among those specified in @p ewmask to

-     * become pending then the events are cleared and returned.

+     * @brief Waits for any of the specified events.

+     * @details 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

      * @return The mask of the served and cleared events.

@@ -510,9 +556,10 @@ namespace chibios_rt {
     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

-     * pending then the events are cleared and returned.

+     * @brief Waits for all the specified event flags then clears them.

+     * @details 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.

      */

@@ -520,9 +567,9 @@ 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

-     * and its mask returned.

+     * @brief Waits for a single event.

+     * @details 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

      * @param time the number of ticks before the operation timouts

@@ -537,9 +584,10 @@ namespace chibios_rt {
     static eventmask_t WaitOneTimeout(eventmask_t ewmask, systime_t time);

 

     /**

-     * Waits for any of the specified events.

-     * The function waits for any event among those specified in @p ewmask to

-     * become pending then the events are cleared and returned.

+     * @brief Waits for any of the specified events.

+     * @details 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

      * @param time the number of ticks before the operation timouts

@@ -549,9 +597,10 @@ namespace chibios_rt {
     static eventmask_t WaitAnyTimeout(eventmask_t ewmask, systime_t time);

 

     /**

-     * Waits for all the specified event flags then clears them.

-     * The function waits for all the events specified in @p ewmask to become

-     * pending then the events are cleared and returned.

+     * @brief Waits for all the specified event flags then clears them.

+     * @details 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

      * @return The mask of the served and cleared events.