From 22e22db0161126d1c58a07e2323662efc18d6c86 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Tue, 20 Jan 2009 16:26:48 +0000 Subject: [PATCH] git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@649 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/ch.txt | 45 ++++++- src/chcond.c | 63 +++++----- src/chdebug.c | 11 +- src/chevents.c | 66 ++++++---- src/chheap.c | 17 ++- src/chlists.c | 28 ++--- src/chmempools.c | 15 ++- src/chmsg.c | 18 +-- src/chmtx.c | 33 +++-- src/chqueues.c | 89 +++++++++----- src/chschd.c | 36 +++--- src/chsem.c | 34 +++-- src/chserial.c | 48 +++++--- src/chsys.c | 20 +-- src/chthreads.c | 77 +++++++----- src/chvt.c | 17 +-- src/include/sys.h | 52 +++++--- src/lib/ch.hpp | 267 ++++++++++++++++++++++++---------------- src/lib/evtimer.c | 15 ++- src/lib/evtimer.h | 7 +- src/templates/chcore.c | 51 ++++---- src/templates/chtypes.h | 7 ++ 22 files changed, 613 insertions(+), 403 deletions(-) diff --git a/docs/ch.txt b/docs/ch.txt index 70aeda6a4..0ae4eb61b 100644 --- a/docs/ch.txt +++ b/docs/ch.txt @@ -66,15 +66,17 @@ * The possible groups are: @a Sys, @a Sch, @a VT, @a Thd, @a Sem, @a Mtx, * @a Cond, @a Evt, @a Msg, @a IQ, @a OQ, @a HQ, @a FDD, @a HDD, @a Dbg, * @a Heap, @a Pool. + * + * @section api_suffixes API Names Suffixes * The suffix is not present for normal APIs but can be one of * the following: - * - "I", I-Class APIs are invokable only from the I-Locked or S-Locked - * states. See @ref system_states. - * - "S", S-Class APIs are invokable only from the S-Locked state. See + * - None, APIs without any suffix can be invoked only from the user + * code in the Normal state unless differently specified. See * @ref system_states. - * - * The APIs without suffix can be invoked only from the user code in the Normal - * state unless differently specified.
+ * - "I", I-Class APIs are invokable only from the I-Locked or + * S-Locked states. See @ref system_states. + * - "S", S-Class APIs are invokable only from the S-Locked + * state. See @ref system_states. * Examples: @p chThdCreateStatic(), @p chSemSignalI(), @p chIQGetTimeout(). * * @section interrupt_classes Interrupt Classes @@ -557,12 +559,43 @@ */ /** @} */ +/** + * @defgroup utilities_library Utilities Library + * @{ + * @brief Utilities Library. + * @details This is a collection of useful library code that is not part of + * the base kernel services. + *

Notes

+ * The library code does not follow the same naming convention of the + * system APIs in order to make very clear that it is not "core" code.
+ * The main difference is that library code is not formally tested in the + * test suite but through usage in the various demo application. + */ +/** @} */ + /** * @defgroup CPlusPlusLibrary C++ Wrapper * @{ * C++ wrapper module. This module allows to use the ChibiOS/RT functionalities * from C++ as classes and objects rather the traditional "C" APIs. + * + * @ingroup utilities_library * @file ch.hpp C++ wrapper classes and definitions. * @file ch.cpp C++ wrapper code. */ /** @} */ + +/** + * @defgroup event_timer Events Generator Timer + * @{ + * @brief Event Generator Timer. + * @details This timer generates an event at regular intervals. The + * listening threads can use the event to perform time related activities. + * Multiple threads can listen to the same timer. + * + * @ingroup utilities_library + * @file evtimer.c Events Generator Timer code. + * @file evtimer.h Events Generator Timer structures and macros. + */ +/** @} */ + diff --git a/src/chcond.c b/src/chcond.c index 7d90c3ffb..09979a64e 100644 --- a/src/chcond.c +++ b/src/chcond.c @@ -31,8 +31,12 @@ #if defined(CH_USE_CONDVARS) && defined(CH_USE_MUTEXES) /** - * Initializes s @p CondVar structure. + * @brief Initializes s @p CondVar structure. + * * @param cp pointer to a @p CondVar structure + * @note This function can be invoked from within an interrupt handler even if + * it is not an I-Class API because it does not touch any critical kernel + * data structure. */ void chCondInit(CondVar *cp) { @@ -40,7 +44,7 @@ void chCondInit(CondVar *cp) { } /** - * Signals one thread that is waiting on the condition variable. + * @brief Signals one thread that is waiting on the condition variable. * * @param cp pointer to the @p CondVar structure */ @@ -55,11 +59,9 @@ void chCondSignal(CondVar *cp) { } /** - * Signals one thread that is waiting on the condition variable. + * @brief Signals one thread that is waiting on the condition variable. * * @param cp pointer to the @p CondVar structure - * @note This function must be called within a @p chSysLock() / @p chSysUnlock() - * block. */ void chCondSignalI(CondVar *cp) { @@ -68,7 +70,7 @@ void chCondSignalI(CondVar *cp) { } /** - * Signals all threads that are waiting on the condition variable. + * @brief Signals all threads that are waiting on the condition variable. * * @param cp pointer to the @p CondVar structure */ @@ -83,10 +85,9 @@ void chCondBroadcast(CondVar *cp) { } /** - * Signals all threads that are waiting on the condition variable. + * @brief Signals all threads that are waiting on the condition variable. * * @param cp pointer to the @p CondVar structure - * @note This function must be called within a @p chSysLock() / @p chSysUnlock() */ void chCondBroadcastI(CondVar *cp) { @@ -98,17 +99,16 @@ void chCondBroadcastI(CondVar *cp) { } /** - * Waits on the condition variable releasing the mutex lock. - * - * Releases the mutex, waits on the condition variable, and finally acquires - * the mutex again. This is done atomically. - * - * The thread MUST already have locked the mutex when calling chCondWait(). + * @brief Waits on the condition variable releasing the mutex lock. + * @details Releases the mutex, waits on the condition variable, and finally + * acquires the mutex again. This is done atomically. * * @param cp pointer to the @p CondVar structure * @return The wakep mode. * @retval RDY_OK if the condvar was signaled using chCondSignal(). * @retval RDY_RESET if the condvar was signaled using chCondBroadcast(). + * @note The thread MUST already have locked the mutex when calling + * @p chCondWait(). */ msg_t chCondWait(CondVar *cp) { msg_t msg; @@ -122,18 +122,16 @@ msg_t chCondWait(CondVar *cp) { } /** - * Waits on the condition variable releasing the mutex lock. - * - * Releases the mutex, waits on the condition variable, and finally acquires - * the mutex again. This is done atomically. - * - * The thread MUST already have locked the mutex when calling chCondWait(). + * @brief Waits on the condition variable releasing the mutex lock. + * @details Releases the mutex, waits on the condition variable, and finally + * acquires the mutex again. This is done atomically. * * @param cp pointer to the @p CondVar structure * @return The wakep mode. * @retval RDY_OK if the condvar was signaled using chCondSignal(). * @retval RDY_RESET if the condvar was signaled using chCondBroadcast(). - * @note This function must be called within a @p chSysLock() / @p chSysUnlock() + * @note The thread MUST already have locked the mutex when calling + * @p chCondWaitS(). */ msg_t chCondWaitS(CondVar *cp) { Mutex *mp; @@ -152,12 +150,9 @@ msg_t chCondWaitS(CondVar *cp) { #ifdef CH_USE_CONDVARS_TIMEOUT /** - * Waits on the condition variable releasing the mutex lock. - * - * Releases the mutex, waits on the condition variable, and finally acquires - * the mutex again. This is done atomically. - * - * The thread MUST already have locked the mutex when calling chCondWait(). + * @brief Waits on the condition variable releasing the mutex lock. + * @details Releases the mutex, waits on the condition variable, and finally + * acquires the mutex again. This is done atomically. * * @param cp pointer to the @p CondVar structure * @param time the number of ticks before the operation fails @@ -166,6 +161,8 @@ msg_t chCondWaitS(CondVar *cp) { * @retval RDY_RESET if the condvar was signaled using chCondBroadcast(). * @retval RDY_TIMEOUT if the condvar was not signaled within the specified * timeout. + * @note The thread MUST already have locked the mutex when calling + * @p chCondWaitTimeout(). */ msg_t chCondWaitTimeout(CondVar *cp, systime_t time) { msg_t msg; @@ -179,12 +176,9 @@ msg_t chCondWaitTimeout(CondVar *cp, systime_t time) { } /** - * Waits on the condition variable releasing the mutex lock. - * - * Releases the mutex, waits on the condition variable, and finally acquires - * the mutex again. This is done atomically. - * - * The thread MUST already have locked the mutex when calling chCondWait(). + * @brief Waits on the condition variable releasing the mutex lock. + * @details Releases the mutex, waits on the condition variable, and finally + * acquires the mutex again. This is done atomically. * * @param cp pointer to the @p CondVar structure * @param time the number of ticks before the operation fails @@ -193,7 +187,8 @@ msg_t chCondWaitTimeout(CondVar *cp, systime_t time) { * @retval RDY_RESET if the condvar was signaled using chCondBroadcast(). * @retval RDY_TIMEOUT if the condvar was not signaled within the specified * timeout. - * @note This function must be called within a @p chSysLock() / @p chSysUnlock() + * @note The thread MUST already have locked the mutex when calling + * @p chCondWaitTimeoutS(). */ msg_t chCondWaitTimeoutS(CondVar *cp, systime_t time) { Mutex *mp; diff --git a/src/chdebug.c b/src/chdebug.c index 56edd2a0d..60bbf49ef 100644 --- a/src/chdebug.c +++ b/src/chdebug.c @@ -24,7 +24,7 @@ char *panicmsg; /** - * Debug subsystem initialization. + * @brief Debug subsystem initialization. */ void chDbgInit(void) { @@ -35,7 +35,9 @@ void chDbgInit(void) { } /** - * Prints a panic message on the console/debugger and then halts the system. + * @brief Prints a panic message on the console/debugger and then halts the + * system. + * * @param msg the pointer to the message string */ void chDbgPanic(char *msg) { @@ -48,12 +50,13 @@ void chDbgPanic(char *msg) { #ifdef CH_USE_TRACE /** - * Public trace buffer. + * @brief Public trace buffer. */ TraceBuffer dbgtb; /** - * Inserts in the circular debug trace buffer a context switch record. + * @brief Inserts in the circular debug trace buffer a context switch record. + * * @param otp the thread being switched out * @param ntp the thread to be resumed */ diff --git a/src/chevents.c b/src/chevents.c index cddc2215a..dc096767e 100644 --- a/src/chevents.c +++ b/src/chevents.c @@ -25,7 +25,8 @@ #ifdef CH_USE_EVENTS /** - * Registers an Event Listener on an Event Source. + * @brief Registers an Event Listener on an Event Source. + * * @param esp pointer to the @p EventSource structure * @param elp pointer to the @p EventListener structure * @param emask the mask of event flags to be pended to the thread when the @@ -45,7 +46,8 @@ void chEvtRegisterMask(EventSource *esp, EventListener *elp, eventmask_t emask) } /** - * Unregisters an Event Listener from its Event Source. + * @brief Unregisters an Event Listener from its Event Source. + * * @param esp pointer to the @p EventSource structure * @param elp pointer to the @p EventListener structure * @note If the event listener is not registered on the specified event source @@ -71,7 +73,8 @@ void chEvtUnregister(EventSource *esp, EventListener *elp) { } /** - * Clears the pending events specified in the mask. + * @brief Clears the pending events specified in the mask. + * * @param mask the events to be cleared * @return The pending events that were cleared. */ @@ -88,8 +91,9 @@ eventmask_t chEvtClear(eventmask_t mask) { } /** - * Makes an events mask pending in the current thread, this is \b much faster than - * using @p chEvtBroadcast(). + * @brief Makes an events mask pending in the current thread, this is \b much + * faster than using @p chEvtBroadcast(). + * * @param mask the events to be pended * @return The current pending events mask. */ @@ -104,7 +108,9 @@ eventmask_t chEvtPend(eventmask_t mask) { } /** - * Signals all the Event Listeners registered on the specified Event Source. + * @brief Signals all the Event Listeners registered on the specified Event + * Source. + * * @param esp pointer to the @p EventSource structure */ void chEvtBroadcast(EventSource *esp) { @@ -118,9 +124,10 @@ void chEvtBroadcast(EventSource *esp) { } /** - * Signals all the Event Listeners registered on the specified Event Source. + * @brief Signals all the Event Listeners registered on the specified Event + * Source. + * * @param esp pointer to the @p EventSource structure - * @note This function does not reschedule. */ void chEvtBroadcastI(EventSource *esp) { EventListener *elp; @@ -141,7 +148,8 @@ void chEvtBroadcastI(EventSource *esp) { } /** - * 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 @@ -163,8 +171,9 @@ void chEvtDispatch(const evhandler_t handlers[], eventmask_t mask) { #if defined(CH_OPTIMIZE_SPEED) || !defined(CH_USE_EVENTS_TIMEOUT) || \ defined(__DOXIGEN__) /** - * A pending event among those specified in @p ewmask is selected, cleared and - * its mask returned. + * @brief 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. @@ -192,9 +201,10 @@ eventmask_t chEvtWaitOne(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. @@ -216,9 +226,10 @@ eventmask_t chEvtWaitAny(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. */ @@ -239,9 +250,10 @@ eventmask_t chEvtWaitAll(eventmask_t ewmask) { #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 @@ -272,9 +284,10 @@ eventmask_t chEvtWaitOneTimeout(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 @@ -299,9 +312,10 @@ eventmask_t chEvtWaitAnyTimeout(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. diff --git a/src/chheap.c b/src/chheap.c index 98bff9c43..8ba55f9ad 100644 --- a/src/chheap.c +++ b/src/chheap.c @@ -63,7 +63,8 @@ static struct { } heap; /** - * Initializes the allocator subsystem. + * @brief Initializes the allocator subsystem. + * * @note It is internally invoked, this function should not normally be * invoked from the user code. */ @@ -92,9 +93,11 @@ void chHeapInit(void) { } /** - * Allocates a block of memory from the heap by using the first-fit algorithm. - * The allocated block is guaranteed to be properly aligned for a pointer data - * type. + * @brief Allocates a block of memory from the heap by using the first-fit + * algorithm. + * @details The allocated block is guaranteed to be properly aligned for a + * pointer data type. + * * @param size the size of the block to be allocated. Note that the allocated * block may be a bit bigger than the requested size for alignment * and fragmentation reasons. @@ -142,7 +145,8 @@ void *chHeapAlloc(size_t size) { (p)->h_size) /** - * Frees a previously allocated memory block. + * @brief Frees a previously allocated memory block. + * * @param p the memory block pointer */ void chHeapFree(void *p) { @@ -184,7 +188,8 @@ void chHeapFree(void *p) { } /** - * Determines the heap status. + * @brief Reports the heap status. + * * @param sizep pointer to a variable that will receive the total fragmented * free space * @return The number of fragments in the heap. diff --git a/src/chlists.c b/src/chlists.c index 397529bbe..ece7e7dd9 100644 --- a/src/chlists.c +++ b/src/chlists.c @@ -25,13 +25,13 @@ #if !defined(CH_OPTIMIZE_SPEED) || defined(__DOXIGEN__) /** - * Inserts a thread into a priority ordered queue. + * @brief Inserts a thread into a priority ordered queue. * * @param tp the pointer to the thread to be inserted in the list * @param tqp the pointer to the threads list header * @note The insertion is done by scanning the list from the highest priority * toward the lowest. - * @note This function is \b not an API. + * @note This function is @b not an API. */ void prio_insert(Thread *tp, ThreadsQueue *tqp) { @@ -48,11 +48,11 @@ void prio_insert(Thread *tp, ThreadsQueue *tqp) { } /** - * Inserts a Thread into a queue. + * @brief Inserts a Thread into a queue. * * @param tp the pointer to the thread to be inserted in the list * @param tqp the pointer to the threads list header - * @note This function is \b not an API. + * @note This function is @b not an API. */ void queue_insert(Thread *tp, ThreadsQueue *tqp) { @@ -61,11 +61,11 @@ void queue_insert(Thread *tp, ThreadsQueue *tqp) { } /** - * Removes the first-out Thread from a queue and returns it. + * @brief Removes the first-out Thread from a queue and returns it. * * @param tqp the pointer to the threads list header * @return The removed thread pointer. - * @note This function is \b not an API. + * @note This function is @b not an API. */ Thread *fifo_remove(ThreadsQueue *tqp) { Thread *tp = tqp->p_next; @@ -75,11 +75,11 @@ Thread *fifo_remove(ThreadsQueue *tqp) { } /** - * Removes the last-out Thread from a queue and returns it. + * @brief Removes the last-out Thread from a queue and returns it. * * @param tqp the pointer to the threads list header * @return The removed thread pointer. - * @note This function is \b not an API. + * @note This function is @b not an API. */ Thread *lifo_remove(ThreadsQueue *tqp) { Thread *tp = tqp->p_next; @@ -89,11 +89,11 @@ Thread *lifo_remove(ThreadsQueue *tqp) { } /** - * Removes a Thread from a FIFO list and returns it. + * @brief Removes a Thread from a FIFO list and returns it. * * @param tp the pointer to the thread to be removed from the list * @return The removed thread pointer. - * @note This function is \b not an API. + * @note This function is @b not an API. */ Thread *dequeue(Thread *tp) { @@ -103,11 +103,11 @@ Thread *dequeue(Thread *tp) { } /** - * Pushes a Thread on top of a stack list. + * @brief Pushes a Thread on top of a stack list. * * @param tp the pointer to the thread to be inserted in the list * @param tlp the pointer to the threads list header - * @note This function is \b not an API. + * @note This function is @b not an API. */ void list_insert(Thread *tp, ThreadsList *tlp) { @@ -116,12 +116,12 @@ void list_insert(Thread *tp, ThreadsList *tlp) { } /** - * Pops a Thread from the top of a stack list and returns it. + * @brief Pops a Thread from the top of a stack list and returns it. * * @param tlp the pointer to the threads list header * @return The removed thread pointer. * @note The list must be non-empty before calling this function. - * @note This function is \b not an API. + * @note This function is @b not an API. */ Thread *list_remove(ThreadsList *tlp) { diff --git a/src/chmempools.c b/src/chmempools.c index fac9db851..caaa60c44 100644 --- a/src/chmempools.c +++ b/src/chmempools.c @@ -27,7 +27,8 @@ #ifdef CH_USE_MEMPOOLS /** - * Initializes an empty memory pool. + * @brief Initializes an empty memory pool. + * * @param mp pointer to a @p MemoryPool structure * @param size the size of the objects contained in this memory pool */ @@ -41,7 +42,8 @@ void chPoolInit(MemoryPool *mp, size_t size) { } /** - * Allocates an object from a memory pool. + * @brief Allocates an object from a memory pool. + * * @param mp pointer to a @p MemoryPool structure * @return The pointer to the allocated object. * @retval NULL if pool is empty. @@ -58,7 +60,8 @@ void *chPoolAllocI(MemoryPool *mp) { } /** - * Allocates an object from a memory pool. + * @brief Allocates an object from a memory pool. + * * @param mp pointer to a @p MemoryPool structure * @return The pointer to the allocated object. * @retval NULL if pool is empty. @@ -73,7 +76,8 @@ void *chPoolAlloc(MemoryPool *mp) { } /** - * Releases (or adds) an object into (to) a memory pool. + * @brief Releases (or adds) an object into (to) a memory pool. + * * @param mp pointer to a @p MemoryPool structure * @param objp the pointer to the object to be released or added * @note the object is assumed to be of the right size for the specified @@ -90,7 +94,8 @@ void chPoolFreeI(MemoryPool *mp, void *objp) { } /** - * Releases (or adds) an object into (to) a memory pool. + * @brief Releases (or adds) an object into (to) a memory pool. + * * @param mp pointer to a @p MemoryPool structure * @param objp the pointer to the object to be released or added * @note the object is assumed to be of the right size for the specified diff --git a/src/chmsg.c b/src/chmsg.c index f53e84030..6f253067c 100644 --- a/src/chmsg.c +++ b/src/chmsg.c @@ -25,8 +25,9 @@ #ifdef CH_USE_MESSAGES /** - * Sends a message to the specified thread. The client is stopped until the - * server executes a @p chMsgRelease() after receiving the message. + * @brief Sends a message to the specified thread. + * @details The sender is stopped until the receiver executes a + * @p chMsgRelease()after receiving the message. * * @param tp the pointer to the thread * @param msg the message, it can be a pointer to a complex structure @@ -54,9 +55,10 @@ msg_t chMsgSend(Thread *tp, msg_t msg) { #ifdef CH_USE_MESSAGES_EVENT /** - * Sends a message to the specified thread and atomically triggers an event. - * The client is stopped until the server executes a @p chMsgRelease() - * after receiving the message. + * @brief Sends a message to the specified thread and atomically triggers + * an event. + * @details The sender is stopped until the receiver executes a + * @p chMsgRelease() after receiving the message. * * @param tp the pointer to the thread * @param msg the message, it can be a pointer to a complex structure @@ -88,7 +90,7 @@ msg_t chMsgSendWithEvent(Thread *tp, msg_t msg, EventSource *esp) { #endif /** - * Suspends the thread and waits for an incoming message. + * @brief Suspends the thread and waits for an incoming message. * * @return The pointer to the message structure. Note, it is always the * message associated to the thread on the top of the messages queue. @@ -110,7 +112,7 @@ msg_t chMsgWait(void) { } /** - * Returns the next message in the queue. + * @brief Returns the next message in the queue. * * @return The pointer to the message structure. Note, it is always the * message associated to the thread on the top of the messages queue. @@ -132,7 +134,7 @@ msg_t chMsgGet(void) { } /** - * Releases the thread waiting on top of the messages queue. + * @brief Releases the thread waiting on top of the messages queue. * * @param msg the message returned to the message sender * @note You can call this function only if there is a message already in the diff --git a/src/chmtx.c b/src/chmtx.c index 8288cfe89..47d1d7969 100644 --- a/src/chmtx.c +++ b/src/chmtx.c @@ -27,8 +27,12 @@ #ifdef CH_USE_MUTEXES /** - * Initializes s @p Mutex structure. + * @brief Initializes s @p Mutex structure. + * * @param mp pointer to a @p Mutex structure + * @note This function can be invoked from within an interrupt handler even if + * it is not an I-Class API because it does not touch any critical kernel + * data structure. */ void chMtxInit(Mutex *mp) { @@ -37,7 +41,8 @@ void chMtxInit(Mutex *mp) { } /** - * Locks the specified mutex. + * @brief Locks the specified mutex. + * * @param mp pointer to the @p Mutex structure */ void chMtxLock(Mutex *mp) { @@ -50,7 +55,7 @@ void chMtxLock(Mutex *mp) { } /** - * Locks the specified mutex. + * @brief Locks the specified mutex. * * @param mp pointer to the @p Mutex structure * @note This function must be called within a @p chSysLock() / @p chSysUnlock() @@ -110,9 +115,11 @@ void chMtxLockS(Mutex *mp) { } /** - * Tries to lock a mutex. This function does not have any overhead related to + * @brief Tries to lock a mutex. + * @details This function does not have any overhead related to * the priority inheritance mechanism because it does not try to enter a sleep * state on the mutex. + * * @param mp pointer to the @p Mutex structure * @retval TRUE if the mutex was successfully acquired * @retval FALSE if the lock attempt failed. @@ -129,7 +136,8 @@ bool_t chMtxTryLock(Mutex *mp) { } /** - * Tries to lock a mutex. This function does not have any overhead related to + * @brief Tries to lock a mutex. + * @details This function does not have any overhead related to * the priority inheritance mechanism because it does not try to enter a sleep * state on the mutex. * @param mp pointer to the @p Mutex structure @@ -149,7 +157,8 @@ bool_t chMtxTryLockS(Mutex *mp) { } /** - * Unlocks the next owned mutex in reverse lock order. + * @brief Unlocks the next owned mutex in reverse lock order. + * * @return The pointer to the unlocked mutex. */ Mutex *chMtxUnlock(void) { @@ -194,7 +203,8 @@ Mutex *chMtxUnlock(void) { } /** - * Unlocks the next owned mutex in reverse lock order. + * @brief Unlocks the next owned mutex in reverse lock order. + * * @return The pointer to the unlocked mutex. * @note This function must be called within a @p chSysLock() / @p chSysUnlock() * block. @@ -234,10 +244,11 @@ Mutex *chMtxUnlockS(void) { } /** - * Unlocks all the mutexes owned by the invoking thread, this 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. + * @brief Unlocks all the mutexes owned by the invoking thread. + * @details This function 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 + * too. */ void chMtxUnlockAll(void) { diff --git a/src/chqueues.c b/src/chqueues.c index f7cc10f42..ed0806c6d 100644 --- a/src/chqueues.c +++ b/src/chqueues.c @@ -27,8 +27,10 @@ #ifdef CH_USE_QUEUES /** - * Initializes an input queue. A Semaphore is internally initialized - * and works as a counter of the bytes contained in the queue. + * @brief Initializes an input queue. + * @details A Semaphore is internally initialized and works as a counter of + * the bytes contained in the queue. + * * @param qp pointer to a @p Queue structure * @param buffer pointer to a memory area allocated as queue buffer * @param size size of the queue buffer @@ -44,8 +46,9 @@ void chIQInit(Queue *qp, uint8_t *buffer, size_t size, qnotify_t inotify) { } /** - * Resets an input queue. All the data is lost and the waiting threads - * resumed. + * @brief Resets an input queue. + * @details All the data is lost and the waiting threads resumed. + * * @param qp pointer to a @p Queue structure */ void chIQReset(Queue *qp) { @@ -59,7 +62,8 @@ void chIQReset(Queue *qp) { } /** - * Inserts a byte into an input queue. + * @brief Inserts a byte into an input queue. + * * @param qp pointer to a @p Queue structure * @param b the byte value to be written * @retval Q_OK if the operation is successful. @@ -81,8 +85,10 @@ msg_t chIQPutI(Queue *qp, uint8_t b) { } /** - * Gets a byte from the input queue, if the queue is empty then the - * calling thread is suspended until a byte arrives in the queue. + * @brief Gets a byte from the input queue. + * @details If the queue is empty then the calling thread is suspended until + * a byte arrives in the queue. + * * @param qp pointer to a @p Queue structure * @return A byte value from the queue. * @retval Q_RESET if the queue was reset. @@ -110,9 +116,10 @@ msg_t chIQGet(Queue *qp) { #if defined(CH_USE_QUEUES_TIMEOUT) && defined(CH_USE_SEMAPHORES_TIMEOUT) /** - * Gets a byte from the input queue, if the queue is empty then the - * calling thread is suspended until a byte arrives in the queue or the - * specified time expires. + * @brief Gets a byte from the input queue. + * @details If the queue is empty then the calling thread is suspended until + * a byte arrives in the queue or the specified time expires. + * * @param qp pointer to a @p Queue structure * @param time the number of ticks before the operation timouts * @return A byte value from the queue. @@ -145,8 +152,10 @@ msg_t chIQGetTimeout(Queue *qp, systime_t time) { #endif /* defined(CH_USE_QUEUES_TIMEOUT) && defined(CH_USE_SEMAPHORES_TIMEOUT) */ /** - * Reads some data from the input queue into the specified buffer. The function - * is non-blocking and can return zero if the queue is empty. + * @brief Reads some data from the input queue into the specified buffer. + * @details The function is non-blocking and can return zero if the queue is + * empty. + * * @param qp pointer to a @p Queue structure * @param buffer the data buffer * @param n the maximum amount of data to be read @@ -187,8 +196,10 @@ size_t chIQRead(Queue *qp, uint8_t *buffer, size_t n) { } /** - * Initializes an output queue. A Semaphore is internally initialized - * and works as a counter of the free bytes in the queue. + * @brief Initializes an output queue. + * @details A Semaphore is internally initialized and works as a counter of the + * free bytes in the queue. + * * @param qp pointer to a @p Queue structure * @param buffer pointer to a memory area allocated as queue buffer * @param size size of the queue buffer @@ -204,8 +215,9 @@ void chOQInit(Queue *qp, uint8_t *buffer, size_t size, qnotify_t onotify) { } /** - * Resets an Output Queue. All the data is lost and the waiting threads - * resumed. + * @brief Resets an Output Queue. + * @details All the data is lost and the waiting threads resumed. + * * @param qp pointer to a @p Queue structure */ void chOQReset(Queue *qp) { @@ -219,8 +231,10 @@ void chOQReset(Queue *qp) { } /** - * Inserts a byte in the output queue, if the queue is full then the thread - * is suspended until the queue has free space available. + * @brief Inserts a byte in the output queue. + * @details If the queue is full then the thread is suspended until the queue + * has free space available. + * * @param qp pointer to a @p Queue structure * @param b the byte value to be written */ @@ -240,7 +254,8 @@ void chOQPut(Queue *qp, uint8_t b) { } /** - * Gets a byte from an output queue. + * @brief Gets a byte from an output queue. + * * @param qp pointer to a @p Queue structure * @return The byte value from the queue. * @retval Q_EMPTY if the queue is empty. @@ -262,8 +277,10 @@ msg_t chOQGetI(Queue *qp) { } /** - * Writes some data from the specified buffer into the queue. The function - * is non-blocking and can return zero if the queue is full. + * @brief Writes some data from the specified buffer into the queue. + * @details The function is non-blocking and can return zero if the queue is + * full. + * * @param qp pointer to a @p Queue structure * @param buffer the data buffer * @param n the maximum amount of data to be written @@ -306,7 +323,8 @@ size_t chOQWrite(Queue *qp, uint8_t *buffer, size_t n) { #ifdef CH_USE_QUEUES_HALFDUPLEX /** - * Initializes an half duplex queue. + * @brief Initializes an half duplex queue. + * * @param qp pointer to the @p HalfDuplexQueue structure * @param buffer pointer to a memory area allocated as buffer for the queue * @param size the size of the queue buffer @@ -327,8 +345,10 @@ void chHDQInit(HalfDuplexQueue *qp, uint8_t *buffer, size_t size, } /** - * Reads a byte from the receive queue, if the queue is empty or is in - * transmission mode then the invoking thread is suspended. + * @brief Reads a byte from the receive queue. + * @details If the queue is empty or is in transmission mode then the invoking + * thread is suspended. + * * @param qp pointer to a @p HalfDuplexQueue structure * @return The byte value. * @retval Q_RESET if the queue was reset. @@ -360,8 +380,10 @@ msg_t chHDQGetReceive(HalfDuplexQueue *qp) { #if defined(CH_USE_QUEUES_TIMEOUT) && defined(CH_USE_SEMAPHORES_TIMEOUT) /** - * Reads a byte from the receive queue, if the queue is empty or is in - * transmission mode then the invoking thread is suspended. + * @brief Reads a byte from the receive queue. + * @details If the queue is empty or is in transmission mode then the invoking + * thread is suspended. + * * @param qp pointer to a @p HalfDuplexQueue structure * @param time the number of ticks before the operation timouts * @return The byte value. @@ -397,9 +419,10 @@ msg_t chHDQGetReceiveTimeout(HalfDuplexQueue *qp, systime_t time) { #endif /* defined(CH_USE_QUEUES_TIMEOUT) && defined(CH_USE_SEMAPHORES_TIMEOUT) */ /** - * Writes a byte into the transmit queue. If the buffer contains unread - * input data then the the buffer is cleared and the queue goes in - * transmission mode. + * @brief Writes a byte into the transmit queue. + * @details If the buffer contains unread input data then the the buffer is + * cleared and the queue goes in transmission mode. + * * @param qp pointer to a @p HalfDuplexQueue structure * @param b the byte value to be written */ @@ -430,7 +453,8 @@ void chHDQPutTransmit(HalfDuplexQueue *qp, uint8_t b) { } /** - * Gets a byte from the transmit queue. + * @brief Gets a byte from the transmit queue. + * * @param qp pointer to a @p HalfDuplexQueue structure * @return The byte value. * @retval Q_EMPTY if the transmit queue is empty (not in transmission mode). @@ -451,8 +475,9 @@ msg_t chHDQGetTransmitI(HalfDuplexQueue *qp) { } /** - * Writes a byte into the receive queue. If the queue is in transmission mode - * then the byte is lost. + * @brief Writes a byte into the receive queue. + * @details If the queue is in transmission mode then the byte is lost. + * * @param qp pointer to a @p HalfDuplexQueue structure * @param b the byte value to be written * @retval Q_OK if the operation is successful. diff --git a/src/chschd.c b/src/chschd.c index 91a9ea0b0..913cac83d 100644 --- a/src/chschd.c +++ b/src/chschd.c @@ -29,7 +29,7 @@ ReadyList rlist; /** @endcond */ /** - * Scheduler initialization. + * @brief Scheduler initialization. * @note Internally invoked by the @p chSysInit(). */ void chSchInit(void) { @@ -42,7 +42,7 @@ void chSchInit(void) { } /** - * Inserts a thread in the Ready List. + * @brief Inserts a thread in the Ready List. * * @param tp the Thread to be made ready * @return The Thread pointer. @@ -70,9 +70,10 @@ Thread *chSchReadyI(Thread *tp) { } /** - * Puts the current thread to sleep into the specified state, the next highest - * priority thread becomes running. The threads states are described into - * @p threads.h + * @brief Puts the current thread to sleep into the specified state. + * @details The next highest priority thread becomes running. The threads + * states are described into @p threads.h. + * * @param newstate the new thread state * @note The function must be called in the system mutex zone. * @note The function is not meant to be used in the user code directly. @@ -104,11 +105,9 @@ static void wakeup(void *p) { } /** - * Puts the current thread to sleep. - * - * Puts the current thread to sleep into the specified state. The next highest - * priority thread becomes running. The thread put to sleep is awakened after - * the specified time has elapsed. + * @brief Puts the current thread to sleep into the specified state. + * @details The next highest priority thread becomes running. The thread put + * to sleep is awakened after the specified time has elapsed. * * @param newstate the new thread state * @param time the number of ticks before the operation timeouts. the value @@ -134,10 +133,10 @@ msg_t chSchGoSleepTimeoutS(tstate_t newstate, systime_t time) { } /** - * Wakes up a thread. + * @brief Wakes up a thread. + * @details The thread is inserted into the ready list or immediately made + * running depending on its relative priority compared to the current thread. * - * The thread is inserted into the ready list or immediately made running - * depending on its relative priority compared to the current thread. * @param ntp the Thread to be made ready * @param msg message to the awakened thread * @note The function must be called in the system mutex zone. @@ -170,7 +169,7 @@ void chSchWakeupS(Thread *ntp, msg_t msg) { } /** - * Switch to the first thread on the runnable queue. + * @brief Switches to the first thread on the runnable queue. * * @note It is intended to be called if @p chSchRescRequiredI() evaluates to @p TRUE. */ @@ -190,10 +189,9 @@ void chSchDoRescheduleI(void) { } /** - * Reschedule only if a higher priority thread is runnable. - * - * If a thread with a higher priority than the current thread is in the - * ready list then make the higher priority thread running. + * @brief Performs a reschedulation if a higher priority thread is runnable. + * @details If a thread with a higher priority than the current thread is in + * the ready list then make the higher priority thread running. * * @note The function must be called in the system mutex zone. */ @@ -205,7 +203,7 @@ void chSchRescheduleS(void) { } /** - * Evaluates if rescheduling is required. + * @brief Evaluates if a reschedulation is required. * * @retval TRUE if there is a thread that should go in running state. * @retval FALSE if a reschedulation is not required. diff --git a/src/chsem.c b/src/chsem.c index 094a30d4e..3af4854f5 100644 --- a/src/chsem.c +++ b/src/chsem.c @@ -26,10 +26,13 @@ #ifdef CH_USE_SEMAPHORES /** - * Initializes a semaphore with the specified counter value. + * @brief Initializes a semaphore with the specified counter value. + * * @param sp pointer to a @p Semaphore structure * @param n initial value of the semaphore counter. Must be non-negative. - * @note Can be called with interrupts disabled or enabled. + * @note This function can be invoked from within an interrupt handler even if + * it is not an I-Class API because it does not touch any critical kernel + * data structure. */ void chSemInit(Semaphore *sp, cnt_t n) { @@ -39,7 +42,8 @@ void chSemInit(Semaphore *sp, cnt_t n) { } /** - * Performs a reset operation on the semaphore. + * @brief Performs a reset operation on the semaphore. + * * @param sp pointer to a @p Semaphore structure * @param n the new value of the semaphore counter. The value must be non-negative. * @note The released threads can recognize they were waked up by a reset @@ -57,7 +61,8 @@ void chSemReset(Semaphore *sp, cnt_t n) { } /** - * Performs a reset operation on the semaphore. + * @brief Performs a reset operation on the semaphore. + * * @param sp pointer to a @p Semaphore structure * @param n the new value of the semaphore counter. The value must be non-negative. * @note The released threads can recognize they were waked up by a reset @@ -76,7 +81,8 @@ void chSemResetI(Semaphore *sp, cnt_t n) { } /** - * Performs a wait operation on a semaphore. + * @brief Performs a wait operation on a semaphore. + * * @param sp pointer to a @p Semaphore structure * @retval RDY_OK if the semaphore was signaled or not taken. * @retval RDY_RESET if the semaphore was reset using @p chSemReset(). @@ -93,7 +99,8 @@ msg_t chSemWait(Semaphore *sp) { } /** - * Performs a wait operation on a semaphore. + * @brief Performs a wait operation on a semaphore. + * * @param sp pointer to a @p Semaphore structure * @retval RDY_OK if the semaphore was signaled or not taken. * @retval RDY_RESET if the semaphore was reset using @p chSemReset(). @@ -113,7 +120,8 @@ msg_t chSemWaitS(Semaphore *sp) { #ifdef CH_USE_SEMAPHORES_TIMEOUT /** - * Performs a wait operation on a semaphore with timeout specification. + * @brief Performs a wait operation on a semaphore with timeout specification. + * * @param sp pointer to a @p Semaphore structure * @param time the number of ticks before the operation fails * @retval RDY_OK if the semaphore was signaled or not taken. @@ -135,7 +143,8 @@ msg_t chSemWaitTimeout(Semaphore *sp, systime_t time) { } /** - * Performs a wait operation on a semaphore with timeout specification. + * @brief Performs a wait operation on a semaphore with timeout specification. + * * @param sp pointer to a @p Semaphore structure * @param time the number of ticks before the operation fails * @retval RDY_OK if the semaphore was signaled or not taken. @@ -157,7 +166,8 @@ msg_t chSemWaitTimeoutS(Semaphore *sp, systime_t time) { #endif /* CH_USE_SEMAPHORES_TIMEOUT */ /** - * Performs a signal operation on a semaphore. + * @brief Performs a signal operation on a semaphore. + * * @param sp pointer to a @p Semaphore structure * @note The function is available only if the @p CH_USE_SEMAPHORES * option is enabled in @p chconf.h. @@ -173,7 +183,8 @@ void chSemSignal(Semaphore *sp) { } /** - * Performs a signal operation on a semaphore. + * @brief Performs a signal operation on a semaphore. + * * @param sp pointer to a @p Semaphore structure * @note The function is available only if the @p CH_USE_SEMAPHORES * option is enabled in @p chconf.h. @@ -192,7 +203,8 @@ void chSemSignalI(Semaphore *sp) { #ifdef CH_USE_SEMSW /** - * Performs atomic signal and wait operations on two semaphores. + * @brief Performs atomic signal and wait operations on two semaphores. + * * @param sps pointer to a @p Semaphore structure to be signaled * @param spw pointer to a @p Semaphore structure to be wait on * @retval RDY_OK if the semaphore was signaled or not taken. diff --git a/src/chserial.c b/src/chserial.c index c41bc2c4a..91a4834ab 100644 --- a/src/chserial.c +++ b/src/chserial.c @@ -26,9 +26,10 @@ #ifdef CH_USE_SERIAL_FULLDUPLEX /** - * Initializes a generic full duplex driver. The HW dependent part of the - * initialization has to be performed outside, usually in the hardware - * initialization code. + * @brief Initializes a generic full duplex driver. + * @details The HW dependent part of the initialization has to be performed + * outside, usually in the hardware initialization code. + * * @param sd pointer to a @p FullDuplexDriver structure * @param ib pointer to a memory area allocated for the Input Queue buffer * @param isize size of the Input Queue buffer @@ -52,8 +53,9 @@ void chFDDInit(FullDuplexDriver *sd, } /** - * This function must be called from the input interrupt service routine in - * order to enqueue incoming data and generate the related events. + * @brief Handles incoming data. + * @details This function must be called from the input interrupt service + * routine in order to enqueue incoming data and generate the related events. * @param sd pointer to a @p FullDuplexDriver structure * @param b the byte to be written in the driver's Input Queue */ @@ -66,8 +68,9 @@ void chFDDIncomingDataI(FullDuplexDriver *sd, uint8_t b) { } /** - * Must be called from the output interrupt service routine in order to get - * the next byte to be transmitted. + * @brief Handles outgoing data. + * @details Must be called from the output interrupt service routine in order + * to get the next byte to be transmitted. * * @param sd pointer to a @p FullDuplexDriver structure * @return The byte value read from the driver's output queue. @@ -83,8 +86,10 @@ msg_t chFDDRequestDataI(FullDuplexDriver *sd) { } /** - * Must be called from the I/O interrupt service routine in order to + * @brief Handles communication events/errors. + * @details Must be called from the I/O interrupt service routine in order to * notify I/O conditions as errors, signals change etc. + * * @param sd pointer to a @p FullDuplexDriver structure * @param mask condition flags to be added to the mask */ @@ -95,7 +100,8 @@ void chFDDAddFlagsI(FullDuplexDriver *sd, dflags_t mask) { } /** - * This function returns and clears the errors mask associated to the driver. + * @brief Returns and clears the errors mask associated to the driver. + * * @param sd pointer to a @p FullDuplexDriver structure * @return The condition flags modified since last time this function was * invoked. @@ -111,9 +117,10 @@ dflags_t chFDDGetAndClearFlags(FullDuplexDriver *sd) { #ifdef CH_USE_SERIAL_HALFDUPLEX /** - * Initializes a generic half duplex driver. The HW dependent part of the - * initialization has to be performed outside, usually in the hardware - * initialization code. + * @brief Initializes a generic half duplex driver. + * @details The HW dependent part of the initialization has to be performed + * outside, usually in the hardware initialization code. + * * @param sd pointer to a @p HalfDuplexDriver structure * @param b pointer to a memory area allocated for the queue buffer * @param size the buffer size @@ -133,8 +140,9 @@ void chHDDInit(HalfDuplexDriver *sd, uint8_t *b, size_t size, } /** - * This function must be called from the input interrupt service routine in - * order to enqueue incoming data and generate the related events. + * @brief Handles incoming data. + * @details This function must be called from the input interrupt service + * routine in order to enqueue incoming data and generate the related events. * @param sd pointer to a @p FullDuplexDriver structure * @param b the byte to be written in the driver's input queue */ @@ -147,8 +155,9 @@ void chHDDIncomingDataI(HalfDuplexDriver *sd, uint8_t b) { } /** - * Must be called from the output interrupt service routine in order to get - * the next byte to be transmitted. + * @brief Handles outgoing data. + * @brief Must be called from the output interrupt service routine in order + * to get the next byte to be transmitted. * * @param sd pointer to a @p HalfDuplexDriver structure * @return The byte value read from the driver's output queue. @@ -164,8 +173,10 @@ msg_t chHDDRequestDataI(HalfDuplexDriver *sd) { } /** - * Must be called from the I/O interrupt service routine in order to + * @brief Handles communication events/errors. + * @details Must be called from the I/O interrupt service routine in order to * notify I/O conditions as errors, signals change etc. + * * @param sd pointer to a @p HalfDuplexDriver structure * @param mask condition flags to be added to the mask */ @@ -176,7 +187,8 @@ void chHDDAddFlagsI(HalfDuplexDriver *sd, dflags_t mask) { } /** - * This function returns and clears the errors mask associated to the driver. + * @brief Returns and clears the errors mask associated to the driver. + * * @param sd pointer to a @p HalfDuplexDriver structure * @return The condition flags modified since last time this function was * invoked. diff --git a/src/chsys.c b/src/chsys.c index 71eb59d98..1629796dd 100644 --- a/src/chsys.c +++ b/src/chsys.c @@ -27,10 +27,12 @@ static WORKING_AREA(idle_thread_wa, IDLE_THREAD_STACK_SIZE); /** - * This function implements the idle thread infinite loop. The function should - * put the processor in the lowest power mode capable to serve interrupts. + * @brief This function implements the idle thread infinite loop. + * @details The function puts the processor in the lowest power mode capable + * to serve interrupts.
* The priority is internally set to the minimum system value so that this * thread is executed only if there are no other ready threads in the system. + * * @param p the thread parameter, unused in this scenario * @note Implementation should declare this function as a weak symbol in order * to allow applications to re-implement it. @@ -43,8 +45,10 @@ static void idle_thread(void *p) { } /** - * ChibiOS/RT initialization. After executing this function the current - * instructions stream becomes the main thread. + * @brief ChibiOS/RT initialization. + * @details After executing this function the current instructions stream + * becomes the main thread. + * * @note Interrupts should be still disabled when @p chSysInit() is invoked * and are internally enabled. * @note The main thread is created with priority @p NORMALPRIO. @@ -77,10 +81,10 @@ void chSysInit(void) { } /** - * Handles time ticks for round robin preemption and timer increments. - * Decrements the remaining time quantum of the running thread and preempts - * it when the quantum is used up. Increments system time and manages the - * timers. + * @brief Handles time ticks for round robin preemption and timer increments. + * @details Decrements the remaining time quantum of the running thread + * and preempts it when the quantum is used up. Increments system time and + * manages the timers. * @note The frequency of the timer determines the system tick granularity and, * together with the @p CH_TIME_QUANTUM macro, the round robin interval. */ diff --git a/src/chthreads.c b/src/chthreads.c index dfa413641..355687423 100644 --- a/src/chthreads.c +++ b/src/chthreads.c @@ -64,9 +64,10 @@ static void memfill(uint8_t *p, uint32_t n, uint8_t v) { #endif /** - * Initializes a new thread. - * The new thread is initialized but not inserted in the ready list, the - * initial state is @p PRSUSPENDED. + * @brief Initializes a new thread. + * @details The new thread is initialized but not inserted in the ready list, + * the initial state is @p PRSUSPENDED. + * * @param prio the priority level for the new thread. Usually the threads are * created with priority @p NORMALPRIO, priorities * can range from @p LOWPRIO to @p HIGHPRIO. @@ -78,7 +79,9 @@ static void memfill(uint8_t *p, uint32_t n, uint8_t v) { * thread into the working space area. * @note A thread can terminate by calling @p chThdExit() or by simply * returning from its main function. - * @note This function can be invoked from within an interrupt handler. + * @note This function can be invoked from within an interrupt handler even if + * it is not an I-Class API because it does not touch any critical kernel + * data structure. */ Thread *chThdInit(void *workspace, size_t wsize, tprio_t prio, tfunc_t pf, void *arg) { @@ -96,7 +99,8 @@ Thread *chThdInit(void *workspace, size_t wsize, } /** - * Creates a new thread into a static memory area. + * @brief Creates a new thread into a static memory area. + * * @param workspace pointer to a working area dedicated to the thread stack * @param wsize size of the working area. * @param prio the priority level for the new thread. Usually the threads are @@ -117,7 +121,8 @@ Thread *chThdCreateStatic(void *workspace, size_t wsize, #if defined(CH_USE_DYNAMIC) && defined(CH_USE_WAITEXIT) && defined(CH_USE_HEAP) /** - * Creates a new thread allocating the memory from the heap. + * @brief Creates a new thread allocating the memory from the heap. + * * @param wsize size of the working area to be allocated * @param prio the priority level for the new thread. Usually the threads are * created with priority @p NORMALPRIO, priorities @@ -149,7 +154,9 @@ Thread *chThdCreateFromHeap(size_t wsize, tprio_t prio, #if defined(CH_USE_DYNAMIC) && defined(CH_USE_WAITEXIT) && defined(CH_USE_MEMPOOLS) /** - * Creates a new thread allocating the memory from the specified Memory Pool. + * @brief Creates a new thread allocating the memory from the specified Memory + * Pool. + * * @param mp the memory pool * @param prio the priority level for the new thread. Usually the threads are * created with priority @p NORMALPRIO, priorities @@ -182,7 +189,7 @@ Thread *chThdCreateFromMemoryPool(MemoryPool *mp, tprio_t prio, #endif /* defined(CH_USE_DYNAMIC) && defined(CH_USE_WAITEXIT) && defined(CH_USE_MEMPOOLS) */ /** - * Changes the running thread priority, reschedules if necessary. + * @brief Changes the running thread priority then reschedules if necessary. * * @param newprio the new priority of the running thread */ @@ -208,13 +215,15 @@ void chThdSetPriority(tprio_t newprio) { } /** - * Suspends the invoking thread. + * @brief Suspends the invoking thread. * * @param tpp pointer to a @p Thread pointer, the @p Thread pointer is set * to point to the suspended process before it enters the - * @p PRSUSPENDED state, it is set to @p NULL after it is resumed. - * This allows to implement a "test and resume" on the variable - * into interrupt handlers. + * @p PRSUSPENDED state. The variable pointed by this parameter + * must be set to @p NULL on entry. + * @note The resume operation is meant to be executed into an interrupt or timer + * handler. The handler is also responsible to clear the variable pointed + * by @p tpp after invoking @p chThdResumeI(). */ void chThdSuspend(Thread **tpp) { @@ -222,14 +231,16 @@ void chThdSuspend(Thread **tpp) { chDbgAssert(*tpp == NULL, "chthreads.c, chThdSuspend()"); *tpp = currp; chSchGoSleepS(PRSUSPENDED); - *tpp = NULL; chSysUnlock(); } /** - * Resumes a suspended thread. + * @brief Resumes a suspended thread. + * * @param tp the pointer to the thread * @return The pointer to the thread. + * @note This call is supposed to resume threads created with @p chThdInit(). + * It should not be used on threads suspended using @p chThdSuspend(). */ Thread *chThdResume(Thread *tp) { @@ -241,7 +252,8 @@ Thread *chThdResume(Thread *tp) { } /** - * Requests a thread termination. + * @brief Requests a thread termination. + * * @param tp the pointer to the thread * @note The thread is not termitated but a termination request is added to * its @p p_flags field. The thread can read this status by @@ -255,7 +267,8 @@ void chThdTerminate(Thread *tp) { } /** - * Suspends the invoking thread for the specified time. + * @brief Suspends the invoking thread for the specified time. + * * @param time the delay in system ticks */ void chThdSleep(systime_t time) { @@ -266,8 +279,9 @@ void chThdSleep(systime_t time) { } /** - * Suspends the invoking thread until the system time arrives to the specified - * value. + * @brief Suspends the invoking thread until the system time arrives to the + * specified value. + * * @param time the absolute system time */ void chThdSleepUntil(systime_t time) { @@ -279,7 +293,7 @@ void chThdSleepUntil(systime_t time) { } /** - * Terminates the current thread by specifying an exit status code. + * @brief Terminates the current thread by specifying an exit status code. * * @param msg the thread exit code. The code can be retrieved by using * @p chThdWait(). @@ -299,19 +313,18 @@ void chThdExit(msg_t msg) { #ifdef CH_USE_WAITEXIT /** - * Blocks the execution of the invoking thread until the specified thread - * terminates then the exit code is returned. - * The memory used by the exited thread is handled in different ways depending - * on the API that spawned the thread: - * + * @brief Blocks the execution of the invoking thread until the specified + * thread terminates then the exit code is returned. + * @details The memory used by the exited thread is handled in different ways + * depending on the API that spawned the thread: + * - If the thread was spawned by @p chThdCreateStatic() or by @p chThdInit() + * then nothing happens and the thread working area is not released or + * modified in any way. This is the default, totally static, behavior. + * - If the thread was spawned by @p chThdCreateFromHeap() then the working + * area is returned to the system heap. + * - If the thread was spawned by @p chThdCreateFromMemoryPool() then the + * working area is returned to the owning memory pool. + * * @param tp the thread pointer * @return The exit code from the terminated thread * @note After invoking @p chThdWait() the thread pointer becomes invalid and diff --git a/src/chvt.c b/src/chvt.c index 0071b1733..7f63437ad 100644 --- a/src/chvt.c +++ b/src/chvt.c @@ -27,7 +27,8 @@ VTList vtlist; /** - * Virtual Timers initialization. + * @brief Virtual Timers initialization. + * * @note Internal use only. */ void chVTInit(void) { @@ -38,15 +39,16 @@ void chVTInit(void) { } /** - * Enables a virtual timer. + * @brief Enables a virtual timer. + * * @param vtp the @p VirtualTimer structure pointer * @param time the number of time ticks, the value zero is not allowed * @param vtfunc the timer callback function. After invoking the callback * the timer is disabled and the structure can be disposed or * reused. * @param par a parameter that will be passed to the callback function - * @note Must be called with the interrupts disabled. - * @note The associated function is invoked by an interrupt handler. + * @note The associated function is invoked by an interrupt handler within + * the I-Locked state, see @ref system_states. */ void chVTSetI(VirtualTimer *vtp, systime_t time, vtfunc_t vtfunc, void *par) { VirtualTimer *p; @@ -69,9 +71,9 @@ void chVTSetI(VirtualTimer *vtp, systime_t time, vtfunc_t vtfunc, void *par) { } /** - * Disables a Virtual Timer. + * @brief Disables a Virtual Timer. + * * @param vtp the @p VirtualTimer structure pointer - * @note It must be called with the interrupts disabled. * @note The timer MUST be active when this function is invoked. */ void chVTResetI(VirtualTimer *vtp) { @@ -84,7 +86,8 @@ void chVTResetI(VirtualTimer *vtp) { } /** - * Checks if the current system time is within the specified time window. + * @brief Checks if the current system time is within the specified time window. + * * @param start the start of the time window (inclusive) * @param end the end of the time window (non inclusive) */ diff --git a/src/include/sys.h b/src/include/sys.h index 0e08452d9..368d108aa 100644 --- a/src/include/sys.h +++ b/src/include/sys.h @@ -26,22 +26,24 @@ #define _SYS_H_ /** - * Prints a message on the system console (if any). + * @brief Prints a message on the system console (if any). * @param msg the message to be printed on the system console */ #define chSysPuts(msg) port_puts(msg) /** - * Halts the system. This function is invoked by the operating system when an + * @brief Halts the system. + * @details This function is invoked by the operating system when an * unrecoverable error is detected (as example because a programming error in * the application code that triggers an assertion while in debug mode). */ #define chSysHalt() port_halt() /** - * Performs a context switch. - * This is the most critical code in any port, this function is responsible - * for the context switch between 2 threads. + * @brief Performs a context switch. + * @details This is the most critical code in any port, this function + * is responsible for the context switch between 2 threads. + * * @param otp the thread to be switched out * @param ntp the thread to be switched in * @note The implementation of this code affects directly the context @@ -50,9 +52,10 @@ #define chSysSwitchI(otp, ntp) port_switch(otp, ntp) /** - * Raises the system interrupt priority mask to the maximum level. - * All the maskable interrupt sources are disabled regardless their hardware - * priority. + * @brief Raises the system interrupt priority mask to the maximum level. + * @details All the maskable interrupt sources are disabled regardless their + * hardware priority. + * * @note The implementation is architecture dependent, it may just disable the * interrupts or be exactly equivalent to @p chSysDisable(). * @note Do not invoke this API from within a kernel lock. @@ -60,9 +63,10 @@ #define chSysDisable() port_disable() /** - * Raises the system interrupt priority mask to system level. - * The interrupt sources that should not be able to preempt the kernel are - * disabled, interrupt sources with higher priority are still enabled. + * @brief Raises the system interrupt priority mask to system level. + * @details The interrupt sources that should not be able to preempt the kernel + * are disabled, interrupt sources with higher priority are still enabled. + * * @note The implementation is architecture dependent, it may just disable the * interrupts. * @note Do not invoke this API from within a kernel lock. @@ -72,8 +76,9 @@ #define chSysSuspend() port_suspend() /** - * Lowers the system interrupt priority mask to user level. - * All the interrupt sources are enabled. + * @brief Lowers the system interrupt priority mask to user level. + * @details All the interrupt sources are enabled. + * * @note The implementation is architecture dependent, it may just enable the * interrupts. * @note Do not invoke this API from within a kernel lock. @@ -83,7 +88,8 @@ #define chSysEnable() port_enable() /** - * Enters the kernel lock mode. + * @brief Enters the kernel lock mode. + * * @note The use of kernel lock mode is not recommended in the user code, it is * a better idea to use the semaphores or mutexes instead. * @see CH_USE_NESTED_LOCKS @@ -100,7 +106,8 @@ #endif /* !defined(CH_USE_NESTED_LOCKS) */ /** - * Leaves the kernel lock mode. + * @brief Leaves the kernel lock mode. + * * @note The use of kernel lock mode is not recommended in the user code, it is * a better idea to use the semaphores or mutexes instead. * @see CH_USE_NESTED_LOCKS @@ -117,7 +124,8 @@ #endif /* !defined(CH_USE_NESTED_LOCKS) */ /** - * Enters the kernel lock mode from within an interrupt handler. + * @brief Enters the kernel lock mode from within an interrupt handler. + * * @note This API may do nothing on some architectures, it is required because * on ports that support preemptable interrupt handlers it is required to * raise the interrupt mask to the same level of the system mutual @@ -129,7 +137,8 @@ #define chSysLockI() port_lock_from_isr() /** - * Leaves the kernel lock mode from within an interrupt handler. + * @brief Leaves the kernel lock mode from within an interrupt handler. + * * @note This API may do nothing on some architectures, it is required because * on ports that support preemptable interrupt handlers it is required to * raise the interrupt mask to the same level of the system mutual @@ -141,14 +150,16 @@ #define chSysUnlockI() port_unlock_from_isr() /** - * IRQ handler enter code. + * @brief IRQ handler enter code. + * * @note Usually IRQ handlers functions are also declared naked. * @note On some architectures this macro can be empty. */ #define CH_IRQ_PROLOGUE() PORT_IRQ_PROLOGUE() /** - * IRQ handler exit code. + * @brief IRQ handler exit code. + * * @note Usually IRQ handlers function are also declared naked. * @note This macro usually performs the final reschedulation by using * @p chSchRescRequiredI() and @p chSchDoRescheduleI(). @@ -156,7 +167,8 @@ #define CH_IRQ_EPILOGUE() PORT_IRQ_EPILOGUE() /** - * Standard IRQ handler declaration. + * @brief Standard IRQ handler declaration. + * * @note @p id can be a function name or a vector number depending on the * port implementation. */ 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 @@ -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 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. + * @brief Unlocks all the mutexes owned by the invoking thread. + * @details 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. + * @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. diff --git a/src/lib/evtimer.c b/src/lib/evtimer.c index 786a25c7f..691484336 100644 --- a/src/lib/evtimer.c +++ b/src/lib/evtimer.c @@ -18,11 +18,8 @@ */ /** - * @file evtimer.c + * @addtogroup event_timer * @{ - * Event Timer, this timer generates an event at regular intervals. The - * listening threads can use the event to perform time related activities. - * Multiple threads can listen to the same timer. */ #include @@ -37,8 +34,9 @@ static void tmrcb(void *p) { } /** - * Starts the timer, if the timer was already running then the function has - * no effect. + * @brief Starts the timer + * @details If the timer was already running then the function has no effect. + * * @param etp pointer to an initialized @p EvTimer structure. */ void evtStart(EvTimer *etp) { @@ -52,8 +50,9 @@ void evtStart(EvTimer *etp) { } /** - * Stops the timer, if the timer was already stopped then the function has - * no effect. + * @brief Stops the timer. + * @details If the timer was already stopped then the function has no effect. + * * @param etp pointer to an initialized @p EvTimer structure. */ void evtStop(EvTimer *etp) { diff --git a/src/lib/evtimer.h b/src/lib/evtimer.h index d0ff5f7c7..5a148e4db 100644 --- a/src/lib/evtimer.h +++ b/src/lib/evtimer.h @@ -18,10 +18,8 @@ */ /** - * @file evtimer.h + * @addtogroup event_timer * @{ - * Event Timer definitions. - * @see evtimer.c */ #ifndef _EVTIMER_H_ @@ -46,7 +44,8 @@ extern "C" { #endif /** - * Initializes an @p EvTimer structure. + * @brief Initializes an @p EvTimer structure. + * * @param etp the EvTimer structure to be initialized * @param time the interval in system ticks */ diff --git a/src/templates/chcore.c b/src/templates/chcore.c index e9f1868af..838cffe60 100644 --- a/src/templates/chcore.c +++ b/src/templates/chcore.c @@ -32,72 +32,79 @@ */ /** - * Port-related initialization code. + * @brief Port-related initialization code. + * * @note This function is usually empty. */ void port_init(void){ } /** - * Kernel-unlock action. Usually this function just disables interrupts but - * may perform more actions. + * @brief Kernel-unlock action. + * @details Usually this function just disables interrupts but may perform more + * actions. */ void port_lock(void) { } /** - * Kernel-unlock action. Usually this function just disables interrupts but - * may perform more actions. + * @brief Kernel-unlock action. + * @details Usually this function just disables interrupts but may perform more + * actions. */ void port_unlock(void) { } /** - * Kernel-lock action from an interrupt handler. This function is invoked - * before invoking I-class APIs from interrupt handlers. The implementation - * is architecture dependent, in its simplest form it is void. + * @brief Kernel-lock action from an interrupt handler. + * @details This function is invoked before invoking I-class APIs from + * interrupt handlers. The implementation is architecture dependent, in its + * simplest form it is void. */ void port_lock_from_isr(void) { } /** - * Kernel-unlock action from an interrupt handler. This function is invoked - * after invoking I-class APIs from interrupt handlers. The implementation - * is architecture dependent, in its simplest form it is void. + * @brief Kernel-unlock action from an interrupt handler. + * @details This function is invoked after invoking I-class APIs from interrupt + * handlers. The implementation is architecture dependent, in its simplest form + * it is void. */ void port_unlock_from_isr(void) { } /** - * Disables all the interrupt sources. + * @brief Disables all the interrupt sources. + * * @note Of course non maskable interrupt sources are not included. */ void port_disable() { } /** - * Disables the interrupt sources that are not supposed to preempt the kernel. + * @brief Disables the interrupt sources that are not supposed to preempt the kernel. */ void port_suspend(void) { } /** - * Enables all the interrupt sources. + * @brief Enables all the interrupt sources. */ void port_enable(void) { } /** - * Enters an architecture-dependent halt mode. The function is meant to return - * when an interrupt becomes pending. The simplest implementation is an empty - * function but this will not take advantage of architecture-specific power - * saving modes. + * @brief Enters an architecture-dependent halt mode. + * @details The function is meant to return when an interrupt becomes pending. + * The simplest implementation is an empty function but this will not take + * advantage of architecture-specific power saving modes. */ void port_wait_for_interrupt(void) { } /** - * Halts the system. This function is invoked by the operating system when an + * @brief Halts the system. + * @details This function is invoked by the operating system when an * unrecoverable error is detected (as example because a programming error in * the application code that triggers an assertion while in debug mode). */ @@ -109,7 +116,8 @@ void port_halt(void) { } /** - * Performs a context switch between two threads. + * @brief Performs a context switch between two threads. + * * @param otp the thread to be switched out * @param ntp the thread to be switched in */ @@ -117,7 +125,8 @@ void port_switch(Thread *otp, Thread *ntp) { } /** - * Prints a message on the system console. + * @brief Prints a message on the system console. + * * @param msg pointer to the message */ void port_puts(char *msg) { diff --git a/src/templates/chtypes.h b/src/templates/chtypes.h index 547b0fb7e..821517574 100644 --- a/src/templates/chtypes.h +++ b/src/templates/chtypes.h @@ -63,9 +63,16 @@ typedef uint32_t systime_t; /** Counter, recommended fastest signed.*/ typedef int32_t cnt_t; +/** Inline function modifier. */ #define INLINE inline + +/** Packed structure modifier (within). */ #define PACK_STRUCT_STRUCT __attribute__((packed)) + +/** Packed structure modifier (before). */ #define PACK_STRUCT_BEGIN + +/** Packed structure modifier (after). */ #define PACK_STRUCT_END #endif /* _CHTYPES_H_ */