aboutsummaryrefslogtreecommitdiffstats
path: root/src
diff options
context:
space:
mode:
authorgdisirio <gdisirio@35acf78f-673a-0410-8e92-d51de3d6d3f4>2009-01-20 16:26:48 +0000
committergdisirio <gdisirio@35acf78f-673a-0410-8e92-d51de3d6d3f4>2009-01-20 16:26:48 +0000
commit22e22db0161126d1c58a07e2323662efc18d6c86 (patch)
treee59efd65935cdb9d1358a598925a0a3fa5ace5fd /src
parentb1d77bf4bc7fb6e89b5280d99f401caa50c8a0d8 (diff)
downloadChibiOS-22e22db0161126d1c58a07e2323662efc18d6c86.tar.gz
ChibiOS-22e22db0161126d1c58a07e2323662efc18d6c86.tar.bz2
ChibiOS-22e22db0161126d1c58a07e2323662efc18d6c86.zip
git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@649 35acf78f-673a-0410-8e92-d51de3d6d3f4
Diffstat (limited to 'src')
-rw-r--r--src/chcond.c63
-rw-r--r--src/chdebug.c11
-rw-r--r--src/chevents.c66
-rw-r--r--src/chheap.c17
-rw-r--r--src/chlists.c28
-rw-r--r--src/chmempools.c15
-rw-r--r--src/chmsg.c18
-rw-r--r--src/chmtx.c33
-rw-r--r--src/chqueues.c89
-rw-r--r--src/chschd.c36
-rw-r--r--src/chsem.c34
-rw-r--r--src/chserial.c48
-rw-r--r--src/chsys.c20
-rw-r--r--src/chthreads.c77
-rw-r--r--src/chvt.c17
-rw-r--r--src/include/sys.h52
-rw-r--r--src/lib/ch.hpp267
-rw-r--r--src/lib/evtimer.c15
-rw-r--r--src/lib/evtimer.h7
-rw-r--r--src/templates/chcore.c51
-rw-r--r--src/templates/chtypes.h7
21 files changed, 574 insertions, 397 deletions
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 <b>MUCH MORE</b>
- * efficient than releasing the mutexes one by one and not just because the
- * call overhead, this function does not have any overhead related to the
- * priority inheritance mechanism.
+ * @brief Unlocks all the mutexes owned by the invoking thread.
+ * @details This function 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
+ * 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.<br>
* 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:
- * <ul>
- * <li>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.</li>
- * <li>If the thread was spawned by @p chThdCreateFromHeap() then the working
- * area is returned to the system heap.</li>
- * <li>If the thread was spawned by @p chThdCreateFromMemoryPool() then the
- * working area is returned to the owning memory pool.</li>
- * </ul>
+ * @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 <b>directly</b> 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 <int N>
@@ -224,13 +248,14 @@ namespace chibios_rt {
public:
/**
- * The thread name.
+ * @brief The thread name.
*/
const char *name;
/**
- * Full constructor. It allows to set a priority level for the new thread
- * and specify the special option flags.
+ * @brief Full constructor.
+ * @details This constructor allows to set a priority level for the new
+ * thread.
* @param tname the name to be assigned to the thread
* @param prio the priority to be assigned to the thread
*/
@@ -241,9 +266,10 @@ namespace chibios_rt {
}
/**
- * Simplified constructor, it allows to create a thread by simply
- * specifying a name. In is assumed @p NORMALPRIO as initial priority
- * and no special option flags.
+ * @brief Simplified constructor.
+ * @details This constructor allows to create a thread by simply
+ * specifying a name. In is assumed @p NORMALPRIO as initial priority.
+ *
* @param tname the name to be assigned to the thread
*/
EnhancedThread(const char *tname) :
@@ -255,30 +281,33 @@ namespace chibios_rt {
#ifdef CH_USE_SEMAPHORES
/**
- * Class encapsulating a @p Semaphore.
+ * @brief Class encapsulating a @p Semaphore.
*/
class Semaphore {
public:
/**
- * Embedded @p Semaphore structure.
+ * @brief Embedded @p Semaphore structure.
*/
struct ::Semaphore sem;
/**
- * Semaphore constructor.
- * The embedded @p ::Semaphore structure is initialized.
+ * @brief Semaphore constructor.
+ * @details The embedded @p ::Semaphore structure is initialized.
+ *
* @param n the semaphore counter value, must be greater or equal to zero
*/
Semaphore(cnt_t n);
/**
- * Resets a semaphore.
- * @param n the new semaphore counter value, must be greater or equal to zero
+ * @brief Resets a semaphore.
+ *
+ * @param n the new semaphore counter value, must be greater or equal to zero
*/
void Reset(cnt_t n);
/**
- * Wait operation on the semaphore.
+ * @brief Wait operation on the semaphore.
+ *
* @retval RDY_OK if the semaphore was signaled or not taken.
* @retval RDY_RESET if the semaphore was reset.
*/
@@ -286,7 +315,8 @@ namespace chibios_rt {
#ifdef CH_USE_SEMAPHORES_TIMEOUT
/**
- * Wait operation on the semaphore with timeout.
+ * @brief Wait operation on the semaphore with timeout.
+ *
* @param time the number of ticks before the operation fails
* @retval RDY_OK if the semaphore was signaled or not taken.
* @retval RDY_RESET if the semaphore was reset.
@@ -297,14 +327,16 @@ namespace chibios_rt {
#endif /* CH_USE_SEMAPHORES_TIMEOUT */
/**
- * Signal operation on the semaphore.
- * The semaphore is signaled, the next thread in queue, if any, is awakened.
+ * @brief Signal operation on the semaphore.
+ * @details The semaphore is signaled, the next thread in queue, if any,
+ * is awakened.
*/
void Signal(void);
#ifdef CH_USE_SEMSW
/**
- * Atomic signal and wait operations.
+ * @brief Atomic signal and wait operations.
+ *
* @param ssem pointer to a @p Semaphore to be signaled
* @param wsem pointer to a @p Semaphore to be wait on
* @retval RDY_OK if the semaphore was signaled or not taken.
@@ -317,82 +349,85 @@ namespace chibios_rt {
#ifdef CH_USE_MUTEXES
/**
- * Class encapsulating a @p Mutex.
+ * @brief Class encapsulating a @p Mutex.
*/
class Mutex {
public:
/**
- * Embedded @p Mutex structure.
+ * @brief Embedded @p Mutex structure.
*/
struct ::Mutex mutex;
/**
- * Mutex constructor.
- * The embedded @p ::Mutex structure is initialized.
+ * @brief Mutex constructor.
+ * @details The embedded @p ::Mutex structure is initialized.
*/
Mutex(void);
/**
- * Tries a lock operation on the mutex.
+ * @brief Tries a lock operation on the mutex.
* @retval TRUE if the mutex was successfully acquired
* @retval FALSE if the lock attempt failed.
*/
bool TryLock(void);
/**
- * Locks the mutex.
- * Performs a lock operation on the mutex, if the mutex is already locked
- * then the thread enters the mutex priority queue and waits.
+ * @brief Locks the mutex.
+ * @details Performs a lock operation on the mutex, if the mutex is
+ * already locked then the thread enters the mutex priority queue and
+ * waits.
*/
void Lock(void);
/**
- * Unlocks the mutex.
- * Performs an unlock operation on the mutex, the next waiting thread, if
- * any, is resumed and locks the mutex.
+ * @brief Unlocks the mutex.
+ * @details Performs an unlock operation on the mutex, the next waiting
+ * thread, if any, is resumed and locks the mutex.
*/
static void Unlock(void);
/**
- * Unlocks all the mutexes owned by the invoking thread.
- * This operation is <b>MUCH MORE</b> efficient than releasing the mutexes
- * one by one and not just because the call overhead, this function does not
- * have any overhead related to the priority inheritance mechanism.
+ * @brief Unlocks all the mutexes owned by the invoking thread.
+ * @details This operation is <b>MUCH MORE</b> efficient than releasing
+ * the mutexes one by one and not just because the call overhead, this
+ * function does not have any overhead related to the priority inheritance
+ * mechanism.
*/
static void UnlockAll(void);
};
#ifdef CH_USE_CONDVARS
/**
- * Class encapsulating a @p CondVar.
+ * @brief Class encapsulating a @p CondVar.
*/
class CondVar {
public:
/**
- * Embedded @p CondVar structure.
+ * @brief Embedded @p CondVar structure.
*/
struct ::CondVar condvar;
/**
- * CondVar constructor.
- * The embedded @p ::CondVar structure is initialized.
+ * @brief CondVar constructor.
+ * @details The embedded @p ::CondVar structure is initialized.
*/
CondVar(void);
/**
- * Signals the CondVar.
- * The next thread waiting on the @p CondVar, if any, is awakened.
+ * @brief Signals the CondVar.
+ * @details The next thread waiting on the @p CondVar, if any, is awakened.
*/
void Signal(void);
/**
- * Broadcasts the CondVar.
- * All the threads waiting on the @p CondVar, if any, are awakened.
+ * @brief Broadcasts the CondVar.
+ * @details All the threads waiting on the @p CondVar, if any, are awakened.
*/
void Broadcast(void);
/**
- * Waits on the CondVar while releasing the controlling mutex.
+ * @brief Waits on the CondVar while releasing the controlling mutex.
+ *
* @return The wakep mode.
* @retval RDY_OK if the condvar was signaled using chCondSignal().
* @retval RDY_RESET if the condvar was signaled using chCondBroadcast().
@@ -401,7 +436,8 @@ namespace chibios_rt {
#ifdef CH_USE_CONDVARS_TIMEOUT
/**
- * Waits on the CondVar while releasing the controlling mutex.
+ * @brief Waits on the CondVar while releasing the controlling mutex.
+ *
* @param time the number of ticks before the operation fails
* @return The wakep mode.
* @retval RDY_OK if the condvar was signaled using chCondSignal().
@@ -417,30 +453,32 @@ namespace chibios_rt {
#ifdef CH_USE_EVENTS
/**
- * Class encapsulating an @p EventSource.
+ * @brief Class encapsulating an @p EventSource.
*/
class Event {
public:
/**
- * Embedded @p EventSource structure.
+ * @brief Embedded @p EventSource structure.
*/
struct ::EventSource event;
/**
- * Event constructor.
- * The embedded @p ::EventSource structure is initialized.
+ * @brief Event constructor.
+ * @details The embedded @p ::EventSource structure is initialized.
*/
Event(void);
/**
- * Registers a listener on the event source.
+ * @brief Registers a listener on the event source.
+ *
* @param elp pointer to the @p EventListener structure
* @param eid numeric identifier assigned to the Event Listener
*/
void Register(EventListener *elp, eventid_t eid);
/**
- * Registers an Event Listener on an Event Source.
+ * @brief Registers an Event Listener on an Event Source.
+ *
* @param elp pointer to the @p EventListener structure
* @param emask the mask of event flags to be pended to the thread when the
* event source is broadcasted
@@ -449,35 +487,40 @@ namespace chibios_rt {
void RegisterMask(EventListener *elp, eventmask_t emask);
/**
- * Unregisters a listener.
- * The specified listeners is no more signaled by the event source.
+ * @brief Unregisters a listener.
+ * @details The specified listeners is no more signaled by the event
+ * source.
+ *
* @param elp the listener to be unregistered
*/
void Unregister(EventListener *elp);
/**
- * Broadcasts an event.
- * All the listeners registered on the event source are signaled.
+ * @brief Broadcasts an event.
+ * @details All the listeners registered on the event source are signaled.
*/
void Broadcast(void);
/**
- * Clears specified events from the pending events mask.
+ * @brief Clears specified events from the pending events mask.
+ *
* @param mask the events to be cleared
* @return The pending events that were cleared.
*/
static eventmask_t Clear(eventmask_t mask);
/**
- * Makes an events mask pending in the current thread, this is \b much
- * faster than using @p Broadcast().
+ * @brief Makes an events mask pending in the current thread.
+ * @details This functon is @b much faster than using @p Broadcast().
+ *
* @param mask the events to be pended
* @return The current pending events mask.
*/
static eventmask_t Pend(eventmask_t mask);
/**
- * Invokes the event handlers associated with a mask.
+ * @brief Invokes the event handlers associated with a mask.
+ *
* @param mask mask of the events to be dispatched
* @param handlers an array of @p evhandler_t. The array must be
* have indexes from zero up the higher registered event
@@ -486,8 +529,10 @@ namespace chibios_rt {
static void Dispatch(const evhandler_t handlers[], eventmask_t mask);
/**
- * A pending event among those specified in @p ewmask is selected, cleared and
- * its mask returned.
+ * @brief Waits for a single event.
+ * @details A pending event among those specified in @p ewmask is selected,
+ * cleared and its mask returned.
+ *
* @param ewmask mask of the events that the function should wait for,
* @p ALL_EVENTS enables all the events
* @return The mask of the lowest id served and cleared event.
@@ -500,9 +545,10 @@ namespace chibios_rt {
static eventmask_t WaitOne(eventmask_t ewmask);
/**
- * Waits for any of the specified events.
- * The function waits for any event among those specified in @p ewmask to
- * become pending then the events are cleared and returned.
+ * @brief Waits for any of the specified events.
+ * @details The function waits for any event among those specified in
+ * @p ewmask to become pending then the events are cleared and returned.
+ *
* @param ewmask mask of the events that the function should wait for,
* @p ALL_EVENTS enables all the events
* @return The mask of the served and cleared events.
@@ -510,9 +556,10 @@ namespace chibios_rt {
static eventmask_t WaitAny(eventmask_t ewmask);
/**
- * Waits for all the specified event flags then clears them.
- * The function waits for all the events specified in @p ewmask to become
- * pending then the events are cleared and returned.
+ * @brief Waits for all the specified event flags then clears them.
+ * @details The function waits for all the events specified in @p ewmask
+ * to become pending then the events are cleared and returned.
+ *
* @param ewmask mask of the event ids that the function should wait for
* @return The mask of the served and cleared events.
*/
@@ -520,9 +567,9 @@ namespace chibios_rt {
#ifdef CH_USE_EVENTS_TIMEOUT
/**
- * Waits for a single event.
- * A pending event among those specified in @p ewmask is selected, cleared
- * and its mask returned.
+ * @brief Waits for a single event.
+ * @details A pending event among those specified in @p ewmask is selected,
+ * cleared and its mask returned.
* @param ewmask mask of the events that the function should wait for,
* @p ALL_EVENTS enables all the events
* @param time the number of ticks before the operation timouts
@@ -537,9 +584,10 @@ namespace chibios_rt {
static eventmask_t WaitOneTimeout(eventmask_t ewmask, systime_t time);
/**
- * Waits for any of the specified events.
- * The function waits for any event among those specified in @p ewmask to
- * become pending then the events are cleared and returned.
+ * @brief Waits for any of the specified events.
+ * @details The function waits for any event among those specified in
+ * @p ewmask to become pending then the events are cleared and returned.
+ *
* @param ewmask mask of the events that the function should wait for,
* @p ALL_EVENTS enables all the events
* @param time the number of ticks before the operation timouts
@@ -549,9 +597,10 @@ namespace chibios_rt {
static eventmask_t WaitAnyTimeout(eventmask_t ewmask, systime_t time);
/**
- * Waits for all the specified event flags then clears them.
- * The function waits for all the events specified in @p ewmask to become
- * pending then the events are cleared and returned.
+ * @brief Waits for all the specified event flags then clears them.
+ * @details The function waits for all the events specified in @p ewmask
+ * to become pending then the events are cleared and returned.
+ *
* @param ewmask mask of the event ids that the function should wait for
* @param time the number of ticks before the operation timouts
* @return The mask of the served and cleared events.
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 <ch.h>
@@ -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_ */