zcy
/
tinySA
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Documentation improvements. 

git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@2240 35acf78f-673a-0410-8e92-d51de3d6d3f4
master
gdisirio 2010-10-09 10:17:11 +00:00
parent 19ee10d244
commit 80cf0731d8
3 changed files with 233 additions and 208 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
os/various/ch.cpp
View File

@ -19,6 +19,7 @@
/**
* @file ch.cpp
* @brief C++ wrapper code.
*
* @addtogroup cpp_library
* @{
*/

185
os/various/ch.hpp
View File

@ -20,6 +20,7 @@
/**
* @file ch.hpp
* @brief C++ wrapper classes and definitions.
*
* @addtogroup cpp_library
* @{
*/
@ -46,7 +47,6 @@ namespace chibios_rt {
/**
* @brief Kernel lock.
*
* @note On some ports it is faster to invoke chSysLock() directly because
* inlining.
*/
@ -54,7 +54,6 @@ namespace chibios_rt {
/**
* @brief Kernel unlock.
*
* @note On some ports it is faster to invoke chSysUnlock() directly
* because inlining.
*/
@ -62,8 +61,9 @@ namespace chibios_rt {
/**
* @brief Returns the system time as system ticks.
* @note The system tick time interval is implementation dependent.
*
* @note the system tick time interval is implementation dependent.
* @return The system time.
*/
static systime_t GetTime(void);
};
@ -80,18 +80,17 @@ namespace chibios_rt {
/**
* @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
* @note It must be called with the interrupts disabled.
* @note The associated function is invoked by an interrupt handler.
*
* @param[in] time the time in system ticks
* @param[in] vtfunc the timer callback function
* @param[in] par the parameter for the callback function
*/
void Set(systime_t time, vtfunc_t vtfunc, void *par);
/**
* @brief Resets the timer.
*
* @note It must be called with the interrupts disabled.
* @note The timer MUST be active when this function is invoked.
*/
@ -122,16 +121,16 @@ namespace chibios_rt {
* @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
* @param[in] workspace pointer to the workspace area
* @param[in] wsize size of the workspace area
* @param[in] prio thread priority
*/
BaseThread(void *workspace, size_t wsize, tprio_t prio);
/**
* @brief Thread exit.
*
* @param msg the exit message
* @param[in] msg the exit message
*/
static void Exit(msg_t msg);
@ -139,7 +138,7 @@ namespace chibios_rt {
/**
* @brief Synchronization on Thread exit.
*
* @return the exit message from the thread
* @return The exit message from the thread.
*/
msg_t Wait(void);
#endif /* CH_USE_WAITEXIT */
@ -153,7 +152,7 @@ namespace chibios_rt {
/**
* @brief Changes the thread priority.
*
* @param newprio the new priority level
* @param[in] newprio The new priority level
*/
static void SetPriority(tprio_t newprio);
@ -168,14 +167,14 @@ namespace chibios_rt {
* @brief Suspends the thread execution for the specified number of
* system ticks.
*
* @param n the number of system ticks
* @param[in] n the number of system ticks
*/
static void Sleep(systime_t n);
/**
* @brief Suspends the thread execution until the specified time arrives.
*
* @param time the system time
* @param[in] time the system time
*/
static void SleepUntil(systime_t time);
@ -183,8 +182,8 @@ namespace chibios_rt {
/**
* @brief Sends a message to the thread and returns the answer.
*
* @param tp the target thread
* @param msg the sent message
* @param[in] tp the target thread
* @param[in] msg the sent message
* @return The returned message.
*/
static msg_t SendMessage(::Thread *tp, msg_t msg);
@ -192,7 +191,7 @@ namespace chibios_rt {
/**
* @brief Sends a message to the thread and returns the answer.
*
* @param msg the sent message
* @param[in] msg the sent message
* @return The returned message.
*/
msg_t SendMessage(msg_t msg);
@ -215,7 +214,7 @@ namespace chibios_rt {
/**
* @brief Releases the next message in queue with a reply.
*
* @param msg the answer message
* @param[in] msg the answer message
*/
static void ReleaseMessage(msg_t msg);
@ -258,8 +257,9 @@ namespace chibios_rt {
* @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
*
* @param[in] tname the name to be assigned to the thread
* @param[in] prio the priority to be assigned to the thread
*/
EnhancedThread(const char *tname, tprio_t prio) :
BaseThread(wa, sizeof wa, prio) {
@ -270,9 +270,10 @@ namespace chibios_rt {
/**
* @brief Simplified constructor.
* @details This constructor allows to create a thread by simply
* specifying a name. In is assumed @p NORMALPRIO as initial priority.
* specifying a name. In is assumed @p NORMALPRIO as initial
* priority.
*
* @param tname the name to be assigned to the thread
* @param[in] tname the name to be assigned to the thread
*/
EnhancedThread(const char *tname) :
BaseThread(wa, sizeof wa, NORMALPRIO) {
@ -296,14 +297,16 @@ namespace chibios_rt {
* @brief Semaphore constructor.
* @details The embedded @p ::Semaphore structure is initialized.
*
* @param n the semaphore counter value, must be greater or equal to zero
* @param[in] n the semaphore counter value, must be greater
* or equal to zero
*/
Semaphore(cnt_t n);
/**
* @brief Resets a semaphore.
*
* @param n the new semaphore counter value, must be greater or equal to zero
* @param[in] n the new semaphore counter value, must be
* greater or equal to zero
*/
void Reset(cnt_t n);
@ -318,11 +321,11 @@ namespace chibios_rt {
/**
* @brief Wait operation on the semaphore with timeout.
*
* @param time the number of ticks before the operation fails
* @param[in] 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.
* @retval RDY_TIMEOUT if the semaphore was not signaled or reset
* within the specified timeout.
*/
msg_t WaitTimeout(systime_t time);
@ -337,8 +340,8 @@ namespace chibios_rt {
/**
* @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
* @param[in] ssem pointer to a @p Semaphore to be signaled
* @param[in] 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.
*/
@ -366,6 +369,7 @@ namespace chibios_rt {
/**
* @brief Tries a lock operation on the mutex.
*
* @retval TRUE if the mutex was successfully acquired
* @retval FALSE if the lock attempt failed.
*/
@ -374,8 +378,8 @@ namespace chibios_rt {
/**
* @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.
* already locked then the thread enters the mutex priority
* queue and waits.
*/
void Lock(void);
@ -389,9 +393,9 @@ namespace chibios_rt {
/**
* @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.
* 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);
};
@ -429,8 +433,10 @@ namespace chibios_rt {
* @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().
* @retval RDY_OK if the condvar was signaled using
* @p chCondSignal().
* @retval RDY_RESET if the condvar was signaled using
* @p chCondBroadcast().
*/
msg_t Wait(void);
@ -438,12 +444,14 @@ namespace chibios_rt {
/**
* @brief Waits on the CondVar while releasing the controlling mutex.
*
* @param time the number of ticks before the operation fails
* @param[in] 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.
* @retval RDY_OK if the condvar was signaled using
* @p chCondSignal().
* @retval RDY_RESET if the condvar was signaled using
* @p 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 */
@ -471,18 +479,19 @@ namespace chibios_rt {
/**
* @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
* @param[in] elp pointer to the @p EventListener structure
* @param[in] eid numeric identifier assigned to the Event
* Listener
*/
void Register(EventListener *elp, eventid_t eid);
/**
* @brief Registers an Event Listener on an Event Source.
* @note Multiple Event Listeners can specify the same bits to be added.
*
* @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
* @note Multiple Event Listeners can specify the same bits to be pended.
* @param[in] elp pointer to the @p EventListener structure
* @param[in] emask the mask of event flags to be pended to the
* thread when the event source is broadcasted
*/
void RegisterMask(EventListener *elp, eventmask_t emask);
@ -491,7 +500,7 @@ namespace chibios_rt {
* @details The specified listeners is no more signaled by the event
* source.
*
* @param elp the listener to be unregistered
* @param[in] elp the listener to be unregistered
*/
void Unregister(EventListener *elp);
@ -504,7 +513,7 @@ namespace chibios_rt {
/**
* @brief Clears specified events from the pending events mask.
*
* @param mask the events to be cleared
* @param[in] mask the events to be cleared
* @return The pending events that were cleared.
*/
static eventmask_t Clear(eventmask_t mask);
@ -513,7 +522,7 @@ namespace chibios_rt {
* @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
* @param[in] mask the events to be pended
* @return The current pending events mask.
*/
static eventmask_t Pend(eventmask_t mask);
@ -521,10 +530,10 @@ namespace chibios_rt {
/**
* @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
* identifier.
* @param[in] mask mask of the events to be dispatched
* @param[in] handlers an array of @p evhandler_t. The array must be
* have indexes from zero up the higher registered
* event identifier.
*/
static void Dispatch(const evhandler_t handlers[], eventmask_t mask);
@ -532,25 +541,27 @@ namespace chibios_rt {
* @brief Waits for a single event.
* @details A pending event among those specified in @p ewmask is selected,
* cleared and its mask returned.
* @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 order to serve all the pending events.<br>
* This means that Event Listeners with a lower event identifier
* have an higher priority.
*
* @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.
* @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
* order to serve all the pending events.<br>
* This means that Event Listeners with a lower event identifier have
* an higher priority.
* @param[in] 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.
*/
static eventmask_t WaitOne(eventmask_t ewmask);
/**
* @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.
* @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[in] 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.
*/
static eventmask_t WaitAny(eventmask_t ewmask);
@ -560,7 +571,8 @@ namespace chibios_rt {
* @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[in] ewmask mask of the event ids that the function should
* wait for
* @return The mask of the served and cleared events.
*/
static eventmask_t WaitAll(eventmask_t ewmask);
@ -570,27 +582,32 @@ namespace chibios_rt {
* @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
* @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 order to serve all the pending events.<br>
* This means that Event Listeners with a lower event identifier
* have an higher priority.
*
* @param[in] ewmask mask of the events that the function should
* wait for, @p ALL_EVENTS enables all the events
*
* @param[in] 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.
* @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
* order to serve all the pending events.<br>
* This means that Event Listeners with a lower event identifier have
* an higher priority.
*/
static eventmask_t WaitOneTimeout(eventmask_t ewmask, systime_t time);
/**
* @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.
* @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
* @param[in] ewmask mask of the events that the function should
* wait for, @p ALL_EVENTS enables all the events
* @param[in] 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.
*/
@ -601,8 +618,10 @@ namespace chibios_rt {
* @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
* @param[in] ewmask mask of the event ids that the function should
* wait for
* @param[in] 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.
*/

9
test/test.c
View File

@ -195,7 +195,7 @@ bool_t _test_assert_time_window(unsigned point, systime_t start, systime_t end)
*/
/**
* @brief Pends a termination request in all the test-spawned threads.
* @brief Sets a termination request in all the test-spawned threads.
*/
void test_terminate_threads(void) {
int i;
@ -243,6 +243,8 @@ void test_cpu_pulse(unsigned duration) {
/**
* @brief Delays execution until next system time tick.
*
* @return The system time.
*/
systime_t test_wait_tick(void) {
@ -254,7 +256,9 @@ systime_t test_wait_tick(void) {
* Timer utils.
*/
/** @brief Set to @p TRUE when the test timer reaches its deadline.*/
/**
* @brief Set to @p TRUE when the test timer reaches its deadline.
*/
bool_t test_timer_done;
static VirtualTimer vt;
@ -312,6 +316,7 @@ static void print_line(void) {
* @brief Test execution thread function.
*
* @param[in] p pointer to a @p BaseChannel object for test output
* @return A failure boolean value.
*/
msg_t TestThread(void *p) {
int i, j;