aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorgdisirio <gdisirio@35acf78f-673a-0410-8e92-d51de3d6d3f4>2009-03-11 09:22:59 +0000
committergdisirio <gdisirio@35acf78f-673a-0410-8e92-d51de3d6d3f4>2009-03-11 09:22:59 +0000
commit80a8621ec04e3fa9588ad09cbf0f1b6da1429776 (patch)
tree4e4cc8a942480df8e57312051d6484c155e17502
parent7dbc6a75678e6e06ec99786eb945d043b64e9721 (diff)
downloadChibiOS-80a8621ec04e3fa9588ad09cbf0f1b6da1429776.tar.gz
ChibiOS-80a8621ec04e3fa9588ad09cbf0f1b6da1429776.tar.bz2
ChibiOS-80a8621ec04e3fa9588ad09cbf0f1b6da1429776.zip
Documentation improvements.
git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@830 35acf78f-673a-0410-8e92-d51de3d6d3f4
-rw-r--r--readme.txt3
-rw-r--r--src/chdebug.c8
-rw-r--r--src/chheap.c16
-rw-r--r--src/chlists.c20
-rw-r--r--src/chmempools.c19
-rw-r--r--src/chmsg.c18
-rw-r--r--src/chmtx.c24
-rw-r--r--src/chqueues.c106
-rw-r--r--src/chschd.c2
-rw-r--r--src/chsem.c1
-rw-r--r--src/chserial.c84
-rw-r--r--src/chsys.c20
12 files changed, 166 insertions, 155 deletions
diff --git a/readme.txt b/readme.txt
index 7607cc93d..c938f3dff 100644
--- a/readme.txt
+++ b/readme.txt
@@ -83,7 +83,8 @@ Win32-MinGW - ChibiOS/RT simulator and demo into a WIN32 process,
- FIX: Removed unused chSysPuts() macro (bug 2672678).
- FIX: Renamed function chSysInTimeWindow() as chTimeIsWithin() and renamed
the macro chSysGetTime() in chTimeNow(), the old names are still recognized
- but marked as deprecated (fixes the bug 2678953 but goes a bit further).
+ but marked as deprecated (fixes the bug 2678953 but goes a bit further by
+ introducing a new API category "Time").
- Removed testcond.c|h and moved the test cases into testmtx.c. Mutexes and
condvars have to be tested together.
- Added architecture diagram to the documentation.
diff --git a/src/chdebug.c b/src/chdebug.c
index c8dba33e6..dc16a27bc 100644
--- a/src/chdebug.c
+++ b/src/chdebug.c
@@ -44,8 +44,8 @@ void trace_init(void) {
/**
* @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
+ * @param[in] otp the thread being switched out
+ * @param[in] ntp the thread to be resumed
*/
void chDbgTrace(Thread *otp, Thread *ntp) {
@@ -62,14 +62,14 @@ void chDbgTrace(Thread *otp, Thread *ntp) {
/**
* @brief Pointer to the panic message.
* @details This pointer is meant to be accessed through the debugger, it is
- * written once and then the system is halted.
+ * written once and then the system is halted.
*/
char *panic_msg;
/**
* @brief Prints a panic message on the console and then halts the system.
*
- * @param msg the pointer to the panic message string
+ * @param[in] msg the pointer to the panic message string
*/
void chDbgPanic(char *msg) {
diff --git a/src/chheap.c b/src/chheap.c
index adfe2842f..82b1ba785 100644
--- a/src/chheap.c
+++ b/src/chheap.c
@@ -95,13 +95,13 @@ void heap_init(void) {
/**
* @brief Allocates a block of memory from the heap by using the first-fit
- * algorithm.
+ * algorithm.
* @details The allocated block is guaranteed to be properly aligned for a
- * pointer data type.
+ * 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.
+ * @param[in] 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.
* @return A pointer to the allocated block.
* @retval NULL if the block cannot be allocated.
*/
@@ -148,7 +148,7 @@ void *chHeapAlloc(size_t size) {
/**
* @brief Frees a previously allocated memory block.
*
- * @param p the memory block pointer
+ * @param[in] p the memory block pointer
*/
void chHeapFree(void *p) {
struct header *qp, *hp;
@@ -195,8 +195,8 @@ void chHeapFree(void *p) {
/**
* @brief Reports the heap status.
*
- * @param sizep pointer to a variable that will receive the total fragmented
- * free space
+ * @param[in] sizep pointer to a variable that will receive the total
+ * fragmented free space
* @return The number of fragments in the heap.
* @note This function is meant to be used in the test suite, it should not be
* really useful for the application code.
diff --git a/src/chlists.c b/src/chlists.c
index 39bea02cc..a3ec568a0 100644
--- a/src/chlists.c
+++ b/src/chlists.c
@@ -29,8 +29,8 @@
/**
* @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
+ * @param[in] tp the pointer to the thread to be inserted in the list
+ * @param[in] 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.
@@ -52,8 +52,8 @@ void prio_insert(Thread *tp, ThreadsQueue *tqp) {
/**
* @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
+ * @param[in] tp the pointer to the thread to be inserted in the list
+ * @param[in] tqp the pointer to the threads list header
* @note This function is @b not an API.
*/
void queue_insert(Thread *tp, ThreadsQueue *tqp) {
@@ -65,7 +65,7 @@ void queue_insert(Thread *tp, ThreadsQueue *tqp) {
/**
* @brief Removes the first-out Thread from a queue and returns it.
*
- * @param tqp the pointer to the threads list header
+ * @param[in] tqp the pointer to the threads list header
* @return The removed thread pointer.
* @note This function is @b not an API.
*/
@@ -79,7 +79,7 @@ Thread *fifo_remove(ThreadsQueue *tqp) {
/**
* @brief Removes the last-out Thread from a queue and returns it.
*
- * @param tqp the pointer to the threads list header
+ * @param[in] tqp the pointer to the threads list header
* @return The removed thread pointer.
* @note This function is @b not an API.
*/
@@ -93,7 +93,7 @@ Thread *lifo_remove(ThreadsQueue *tqp) {
/**
* @brief Removes a Thread from a FIFO list and returns it.
*
- * @param tp the pointer to the thread to be removed from the list
+ * @param[in] 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.
*/
@@ -107,8 +107,8 @@ Thread *dequeue(Thread *tp) {
/**
* @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
+ * @param[in] tp the pointer to the thread to be inserted in the list
+ * @param[in] tlp the pointer to the threads list header
* @note This function is @b not an API.
*/
void list_insert(Thread *tp, ThreadsList *tlp) {
@@ -120,7 +120,7 @@ void list_insert(Thread *tp, ThreadsList *tlp) {
/**
* @brief Pops a Thread from the top of a stack list and returns it.
*
- * @param tlp the pointer to the threads list header
+ * @param[in] 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.
diff --git a/src/chmempools.c b/src/chmempools.c
index 7d3a162bb..dd6f3d1ba 100644
--- a/src/chmempools.c
+++ b/src/chmempools.c
@@ -27,12 +27,12 @@
#include <ch.h>
#if CH_USE_MEMPOOLS
-
/**
* @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
+ * @param[out] mp pointer to a @p MemoryPool structure
+ * @param[in] size the size of the objects contained in this memory pool,
+ * the minimum accepted size is the size of a pointer to void
*/
void chPoolInit(MemoryPool *mp, size_t size) {
@@ -45,7 +45,7 @@ void chPoolInit(MemoryPool *mp, size_t size) {
/**
* @brief Allocates an object from a memory pool.
*
- * @param mp pointer to a @p MemoryPool structure
+ * @param[in] mp pointer to a @p MemoryPool structure
* @return The pointer to the allocated object.
* @retval NULL if pool is empty.
*/
@@ -63,7 +63,7 @@ void *chPoolAllocI(MemoryPool *mp) {
/**
* @brief Allocates an object from a memory pool.
*
- * @param mp pointer to a @p MemoryPool structure
+ * @param[in] mp pointer to a @p MemoryPool structure
* @return The pointer to the allocated object.
* @retval NULL if pool is empty.
*/
@@ -79,8 +79,8 @@ void *chPoolAlloc(MemoryPool *mp) {
/**
* @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
+ * @param[in] mp pointer to a @p MemoryPool structure
+ * @param[in] 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
* memory pool.
*/
@@ -96,8 +96,8 @@ void chPoolFreeI(MemoryPool *mp, void *objp) {
/**
* @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
+ * @param[in] mp pointer to a @p MemoryPool structure
+ * @param[in] 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
* memory pool.
*/
@@ -107,7 +107,6 @@ void chPoolFree(MemoryPool *mp, void *objp) {
chPoolFreeI(mp, objp);
chSysUnlock();
}
-
#endif /* CH_USE_MEMPOOLS */
/** @} */
diff --git a/src/chmsg.c b/src/chmsg.c
index 6744b7ac9..c506b6847 100644
--- a/src/chmsg.c
+++ b/src/chmsg.c
@@ -37,10 +37,10 @@
/**
* @brief Sends a message to the specified thread.
* @details The sender is stopped until the receiver executes a
- * @p chMsgRelease()after receiving the message.
+ * @p chMsgRelease()after receiving the message.
*
- * @param tp the pointer to the thread
- * @param msg the message
+ * @param[in] tp the pointer to the thread
+ * @param[in] msg the message
* @return The return message from @p chMsgRelease().
*/
msg_t chMsgSend(Thread *tp, msg_t msg) {
@@ -62,13 +62,13 @@ msg_t chMsgSend(Thread *tp, msg_t msg) {
#if CH_USE_EVENTS && CH_USE_MESSAGES_EVENT
/**
* @brief Sends a message to the specified thread and atomically pends an
- * events set.
+ * events set.
* @details The sender is stopped until the receiver executes a
- * @p chMsgRelease() after receiving the message.
+ * @p chMsgRelease() after receiving the message.
*
- * @param tp the pointer to the thread
- * @param msg the message
- * @param mask the event flags set to be pended
+ * @param[in] tp the pointer to the thread
+ * @param[in] msg the message
+ * @param[in] mask the event flags set to be pended
* @return The return message from @p chMsgRelease().
* @note This function assumes that the receiving thread is not sleeping into
* a @p chMsgWait(). The use case is that the server thread is waiting
@@ -136,7 +136,7 @@ msg_t chMsgGet(void) {
/**
* @brief Releases the thread waiting on top of the messages queue.
*
- * @param msg the message returned to the message sender
+ * @param[in] msg the message returned to the message sender
* @note You can call this function only if there is a message already in the
* queue else the result will be unpredictable (a crash most likely).
* Exiting from the @p chMsgWait() ensures you have at least one
diff --git a/src/chmtx.c b/src/chmtx.c
index b1d32d220..5fcb6fd5e 100644
--- a/src/chmtx.c
+++ b/src/chmtx.c
@@ -31,7 +31,7 @@
/**
* @brief Initializes s @p Mutex structure.
*
- * @param mp pointer to a @p Mutex structure
+ * @param[out] 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.
@@ -47,7 +47,7 @@ void chMtxInit(Mutex *mp) {
/**
* @brief Locks the specified mutex.
*
- * @param mp pointer to the @p Mutex structure
+ * @param[in] mp pointer to the @p Mutex structure
*/
void chMtxLock(Mutex *mp) {
@@ -61,7 +61,7 @@ void chMtxLock(Mutex *mp) {
/**
* @brief Locks the specified mutex.
*
- * @param mp pointer to the @p Mutex structure
+ * @param[in] mp pointer to the @p Mutex structure
* @note This function must be called within a @p chSysLock() / @p chSysUnlock()
* block.
*/
@@ -136,10 +136,10 @@ void chMtxLockS(Mutex *mp) {
/**
* @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.
+ * 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
+ * @param[in] mp pointer to the @p Mutex structure
* @retval TRUE if the mutex was successfully acquired
* @retval FALSE if the lock attempt failed.
*/
@@ -157,9 +157,9 @@ bool_t chMtxTryLock(Mutex *mp) {
/**
* @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
+ * the priority inheritance mechanism because it does not try to
+ * enter a sleep state on the mutex.
+ * @param[in] mp pointer to the @p Mutex structure
* @retval TRUE if the mutex was successfully acquired
* @retval FALSE if the lock attempt failed.
* @note This function must be called within a @p chSysLock() / @p chSysUnlock()
@@ -273,9 +273,9 @@ Mutex *chMtxUnlockS(void) {
/**
* @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.
+ * mutexes one by one and not just because the call overhead,
+ * this function does not have any overhead related to the priority
+ * inheritance mechanism.
*/
void chMtxUnlockAll(void) {
diff --git a/src/chqueues.c b/src/chqueues.c
index 6dcc61af6..b7e14e69d 100644
--- a/src/chqueues.c
+++ b/src/chqueues.c
@@ -31,13 +31,14 @@
/**
* @brief Initializes an input queue.
* @details A Semaphore is internally initialized and works as a counter of
- * the bytes contained in the queue.
+ * 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
- * @param inotify pointer to a callback function that is invoked when
- * some data is read from the Queue. The value can be @p NULL.
+ * @param[out] qp pointer to a @p Queue structure
+ * @param[in] buffer pointer to a memory area allocated as queue buffer
+ * @param[in] size size of the queue buffer
+ * @param[in] inotify pointer to a callback function that is invoked when
+ * some data is read from the Queue. The value can be
+* @p NULL.
*/
void chIQInit(Queue *qp, uint8_t *buffer, size_t size, qnotify_t inotify) {
@@ -51,7 +52,7 @@ void chIQInit(Queue *qp, uint8_t *buffer, size_t size, qnotify_t inotify) {
* @brief Resets an input queue.
* @details All the data is lost and the waiting threads resumed.
*
- * @param qp pointer to a @p Queue structure
+ * @param[in] qp pointer to a @p Queue structure
*/
void chIQReset(Queue *qp) {
@@ -66,8 +67,8 @@ void chIQReset(Queue *qp) {
/**
* @brief Inserts a byte into an input queue.
*
- * @param qp pointer to a @p Queue structure
- * @param b the byte value to be written
+ * @param[in] qp pointer to a @p Queue structure
+ * @param[in] b the byte value to be written
* @retval Q_OK if the operation is successful.
* @retval Q_FULL if the queue is full.
* @note This function is the lower side endpoint of the Input Queue.
@@ -89,9 +90,9 @@ msg_t chIQPutI(Queue *qp, uint8_t b) {
/**
* @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.
+ * a byte arrives in the queue.
*
- * @param qp pointer to a @p Queue structure
+ * @param[in] qp pointer to a @p Queue structure
* @return A byte value from the queue.
* @retval Q_RESET if the queue was reset.
*/
@@ -120,10 +121,10 @@ msg_t chIQGet(Queue *qp) {
/**
* @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.
+ * 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 timeouts
+ * @param[in] qp pointer to a @p Queue structure
+ * @param[in] time the number of ticks before the operation timeouts
* @return A byte value from the queue.
* @retval Q_TIMEOUT if the specified time expired.
* @retval Q_RESET if the queue was reset.
@@ -156,11 +157,11 @@ msg_t chIQGetTimeout(Queue *qp, systime_t time) {
/**
* @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.
+ * empty.
*
- * @param qp pointer to a @p Queue structure
- * @param buffer the data buffer
- * @param n the maximum amount of data to be read
+ * @param[in] qp pointer to a @p Queue structure
+ * @param[out] buffer the data buffer
+ * @param[in] n the maximum amount of data to be read
* @return The number of bytes read.
* @note This function is the upper side endpoint of the input queue.
* @note The function is not atomic, if you need atomicity it is suggested
@@ -200,13 +201,14 @@ size_t chIQRead(Queue *qp, uint8_t *buffer, size_t n) {
/**
* @brief Initializes an output queue.
* @details A Semaphore is internally initialized and works as a counter of the
- * free bytes in the queue.
+ * 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
- * @param onotify pointer to a callback function that is invoked when
- * some data is written in the Queue. The value can be @p NULL.
+ * @param[out] qp pointer to a @p Queue structure
+ * @param[in] buffer pointer to a memory area allocated as queue buffer
+ * @param[in] size size of the queue buffer
+ * @param[in] onotify pointer to a callback function that is invoked when
+ * some data is written in the Queue. The value can be
+ * @p NULL.
*/
void chOQInit(Queue *qp, uint8_t *buffer, size_t size, qnotify_t onotify) {
@@ -220,7 +222,7 @@ void chOQInit(Queue *qp, uint8_t *buffer, size_t size, qnotify_t onotify) {
* @brief Resets an Output Queue.
* @details All the data is lost and the waiting threads resumed.
*
- * @param qp pointer to a @p Queue structure
+ * @param[in] qp pointer to a @p Queue structure
*/
void chOQReset(Queue *qp) {
@@ -235,10 +237,10 @@ void chOQReset(Queue *qp) {
/**
* @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.
+ * has free space available.
*
- * @param qp pointer to a @p Queue structure
- * @param b the byte value to be written
+ * @param[in] qp pointer to a @p Queue structure
+ * @param[in] b the byte value to be written
*/
void chOQPut(Queue *qp, uint8_t b) {
@@ -258,7 +260,7 @@ void chOQPut(Queue *qp, uint8_t b) {
/**
* @brief Gets a byte from an output queue.
*
- * @param qp pointer to a @p Queue structure
+ * @param[in] qp pointer to a @p Queue structure
* @return The byte value from the queue.
* @retval Q_EMPTY if the queue is empty.
* @note This function is the lower side endpoint of the output queue.
@@ -281,11 +283,11 @@ msg_t chOQGetI(Queue *qp) {
/**
* @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.
+ * full.
*
- * @param qp pointer to a @p Queue structure
- * @param buffer the data buffer
- * @param n the maximum amount of data to be written
+ * @param[in] qp pointer to a @p Queue structure
+ * @param[in] buffer the data buffer
+ * @param[in] n the maximum amount of data to be written
* @return The number of written bytes.
* @note This function is the upper side endpoint of the output queue.
* @note The function is not atomic, if you need atomicity it is suggested
@@ -327,13 +329,15 @@ size_t chOQWrite(Queue *qp, uint8_t *buffer, size_t n) {
/**
* @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
- * @param inotify pointer to a callback function that is invoked when
- * some data is read from the queue. The value can be @p NULL.
- * @param onotify pointer to a callback function that is invoked when
- * some data is written to the queue. The value can be @p NULL.
+ * @param[out] qp pointer to the @p HalfDuplexQueue structure
+ * @param[in] buffer pointer to a memory area allocated as buffer for the queue
+ * @param[in] size the size of the queue buffer
+ * @param[in] inotify pointer to a callback function that is invoked when
+ * some data is read from the queue. The value can be
+ * @p NULL.
+ * @param[in] onotify pointer to a callback function that is invoked when
+ * some data is written to the queue. The value can be
+ * @p NULL.
*/
void chHDQInit(HalfDuplexQueue *qp, uint8_t *buffer, size_t size,
qnotify_t inotify, qnotify_t onotify) {
@@ -349,9 +353,9 @@ void chHDQInit(HalfDuplexQueue *qp, uint8_t *buffer, size_t size,
/**
* @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.
+ * thread is suspended.
*
- * @param qp pointer to a @p HalfDuplexQueue structure
+ * @param[in] qp pointer to a @p HalfDuplexQueue structure
* @return The byte value.
* @retval Q_RESET if the queue was reset.
*/
@@ -384,10 +388,10 @@ msg_t chHDQGetReceive(HalfDuplexQueue *qp) {
/**
* @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.
+ * thread is suspended.
*
- * @param qp pointer to a @p HalfDuplexQueue structure
- * @param time the number of ticks before the operation timouts
+ * @param[in] qp pointer to a @p HalfDuplexQueue structure
+ * @param[in] time the number of ticks before the operation timouts
* @return The byte value.
* @retval Q_TIMEOUT if a timeout occurs.
* @note The function is available only if the @p CH_USE_QUEUES_TIMEOUT and
@@ -423,10 +427,10 @@ msg_t chHDQGetReceiveTimeout(HalfDuplexQueue *qp, systime_t time) {
/**
* @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.
+ * cleared and the queue goes in transmission mode.
*
- * @param qp pointer to a @p HalfDuplexQueue structure
- * @param b the byte value to be written
+ * @param[in] qp pointer to a @p HalfDuplexQueue structure
+ * @param[in] b the byte value to be written
*/
void chHDQPutTransmit(HalfDuplexQueue *qp, uint8_t b) {
@@ -457,7 +461,7 @@ void chHDQPutTransmit(HalfDuplexQueue *qp, uint8_t b) {
/**
* @brief Gets a byte from the transmit queue.
*
- * @param qp pointer to a @p HalfDuplexQueue structure
+ * @param[in] qp pointer to a @p HalfDuplexQueue structure
* @return The byte value.
* @retval Q_EMPTY if the transmit queue is empty (not in transmission mode).
* @note This function must be called with interrupts disabled or from an
@@ -480,8 +484,8 @@ msg_t chHDQGetTransmitI(HalfDuplexQueue *qp) {
* @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
+ * @param[in] qp pointer to a @p HalfDuplexQueue structure
+ * @param[in] b the byte value to be written
* @retval Q_OK if the operation is successful.
* @retval Q_FULL if the driver is in transmit mode or the receive queue is full.
* @note This function must be called with interrupts disabled or from an
diff --git a/src/chschd.c b/src/chschd.c
index 4d094d786..b246d8f57 100644
--- a/src/chschd.c
+++ b/src/chschd.c
@@ -76,7 +76,7 @@ Thread *chSchReadyI(Thread *tp) {
* @details The next highest priority thread becomes running. The threads
* states are described into @p threads.h.
*
- * @param newstate the new thread state
+ * @param[in] 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.
*/
diff --git a/src/chsem.c b/src/chsem.c
index 6c254e836..21f80c284 100644
--- a/src/chsem.c
+++ b/src/chsem.c
@@ -136,6 +136,7 @@ msg_t chSemWaitS(Semaphore *sp) {
* the following special values are allowed:
* - @a TIME_IMMEDIATE immediate timeout.
* - @a TIME_INFINITE no timeout.
+ * .
* @retval RDY_OK if the semaphore was signaled or not taken.
* @retval RDY_RESET if the semaphore was reset using @p chSemReset().
* @retval RDY_TIMEOUT if the semaphore was not signaled or reset within the
diff --git a/src/chserial.c b/src/chserial.c
index 67cb96bab..725df207d 100644
--- a/src/chserial.c
+++ b/src/chserial.c
@@ -30,17 +30,19 @@
/**
* @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.
+ * 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
- * @param inotify pointer to a callback function that is invoked when
- * some data is read from the Queue. The value can be @p NULL.
- * @param ob pointer to a memory area allocated for the Output Queue buffer
- * @param osize size of the Output Queue buffer
- * @param onotify pointer to a callback function that is invoked when
- * some data is written in the Queue. The value can be @p NULL.
+ * @param[out] sd pointer to a @p FullDuplexDriver structure
+ * @param[in] ib pointer to a memory area allocated for the Input Queue buffer
+ * @param[in] isize size of the Input Queue buffer
+ * @param[in] inotify pointer to a callback function that is invoked when
+ * some data is read from the Queue. The value can be
+ * @p NULL.
+ * @param[in] ob pointer to a memory area allocated for the Output Queue buffer
+ * @param[in] osize size of the Output Queue buffer
+ * @param[in] onotify pointer to a callback function that is invoked when
+ * some data is written in the Queue. The value can be
+ * @p NULL.
*/
void chFDDInit(FullDuplexDriver *sd,
uint8_t *ib, size_t isize, qnotify_t inotify,
@@ -60,9 +62,10 @@ void chFDDInit(FullDuplexDriver *sd,
/**
* @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
+ * routine in order to enqueue incoming data and generate the
+ * related events.
+ * @param[in] sd pointer to a @p FullDuplexDriver structure
+ * @param[in] b the byte to be written in the driver's Input Queue
*/
void chFDDIncomingDataI(FullDuplexDriver *sd, uint8_t b) {
@@ -75,12 +78,12 @@ void chFDDIncomingDataI(FullDuplexDriver *sd, uint8_t b) {
/**
* @brief Handles outgoing data.
* @details Must be called from the output interrupt service routine in order
- * to get the next byte to be transmitted.
+ * to get the next byte to be transmitted.
*
- * @param sd pointer to a @p FullDuplexDriver structure
+ * @param[in] sd pointer to a @p FullDuplexDriver structure
* @return The byte value read from the driver's output queue.
* @retval Q_EMPTY if the queue is empty (the lower driver usually disables
- * the interrupt source when this happens).
+ * the interrupt source when this happens).
*/
msg_t chFDDRequestDataI(FullDuplexDriver *sd) {
@@ -93,10 +96,10 @@ msg_t chFDDRequestDataI(FullDuplexDriver *sd) {
/**
* @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.
+ * 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
+ * @param[in] sd pointer to a @p FullDuplexDriver structure
+ * @param[in] mask condition flags to be added to the mask
*/
void chFDDAddFlagsI(FullDuplexDriver *sd, dflags_t mask) {
@@ -107,7 +110,7 @@ void chFDDAddFlagsI(FullDuplexDriver *sd, dflags_t mask) {
/**
* @brief Returns and clears the errors mask associated to the driver.
*
- * @param sd pointer to a @p FullDuplexDriver structure
+ * @param[in] sd pointer to a @p FullDuplexDriver structure
* @return The condition flags modified since last time this function was
* invoked.
*/
@@ -124,15 +127,17 @@ dflags_t chFDDGetAndClearFlags(FullDuplexDriver *sd) {
/**
* @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.
+ * 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
- * @param inotify pointer to a callback function that is invoked when
- * some data is read from the queue. The value can be @p NULL.
- * @param onotify pointer to a callback function that is invoked when
- * some data is written in the queue. The value can be @p NULL.
+ * @param[out] sd pointer to a @p HalfDuplexDriver structure
+ * @param[in] b pointer to a memory area allocated for the queue buffer
+ * @param[in] size the buffer size
+ * @param[in] inotify pointer to a callback function that is invoked when
+ * some data is read from the queue. The value can be
+ * @p NULL.
+ * @param[in] onotify pointer to a callback function that is invoked when
+ * some data is written in the queue. The value can be
+ * @p NULL.
*/
void chHDDInit(HalfDuplexDriver *sd, uint8_t *b, size_t size,
qnotify_t inotify, qnotify_t onotify) {
@@ -149,9 +154,10 @@ void chHDDInit(HalfDuplexDriver *sd, uint8_t *b, size_t size,
/**
* @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
+ * routine in order to enqueue incoming data and generate the
+ * related events.
+ * @param[in] sd pointer to a @p FullDuplexDriver structure
+ * @param[in] b the byte to be written in the driver's input queue
*/
void chHDDIncomingDataI(HalfDuplexDriver *sd, uint8_t b) {
@@ -163,13 +169,13 @@ void chHDDIncomingDataI(HalfDuplexDriver *sd, uint8_t b) {
/**
* @brief Handles outgoing data.
- * @brief Must be called from the output interrupt service routine in order
- * to get the next byte to be transmitted.
+ * @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 HalfDuplexDriver structure
+ * @param[in] sd pointer to a @p HalfDuplexDriver structure
* @return The byte value read from the driver's output queue.
* @retval Q_EMPTY if the queue is empty (the lower driver usually disables
- * the interrupt source when this happens).
+ * the interrupt source when this happens).
*/
msg_t chHDDRequestDataI(HalfDuplexDriver *sd) {
@@ -182,10 +188,10 @@ msg_t chHDDRequestDataI(HalfDuplexDriver *sd) {
/**
* @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.
+ * 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
+ * @param[in] sd pointer to a @p HalfDuplexDriver structure
+ * @param[in] mask condition flags to be added to the mask
*/
void chHDDAddFlagsI(HalfDuplexDriver *sd, dflags_t mask) {
@@ -196,7 +202,7 @@ void chHDDAddFlagsI(HalfDuplexDriver *sd, dflags_t mask) {
/**
* @brief Returns and clears the errors mask associated to the driver.
*
- * @param sd pointer to a @p HalfDuplexDriver structure
+ * @param[in] 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 666d0cfef..cedd3d28b 100644
--- a/src/chsys.c
+++ b/src/chsys.c
@@ -31,13 +31,12 @@ static WORKING_AREA(idle_thread_wa, IDLE_THREAD_STACK_SIZE);
/**
* @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.
+ * 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.
+ * @param[in] p the thread parameter, unused in this scenario
*/
static void idle_thread(void *p) {
@@ -50,7 +49,7 @@ static void idle_thread(void *p) {
/**
* @brief ChibiOS/RT initialization.
* @details After executing this function the current instructions stream
- * becomes the main thread.
+ * becomes the main thread.
*
* @note Interrupts should be still disabled when @p chSysInit() is invoked
* and are internally enabled.
@@ -88,10 +87,11 @@ void chSysInit(void) {
/**
* @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.
+ * 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.
+ * together with the @p CH_TIME_QUANTUM macro, the round robin interval.
*/
void chSysTimerHandlerI(void) {