From 1d23eb296156769cff3e41bd7026db1cd2538664 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Fri, 17 Oct 2008 18:33:35 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@474 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/Doxyfile | 2 +- docs/ch.txt | 10 ++++++++++ docs/readme.txt | 35 +++++++++++++++++++++++++++++++++++ readme.txt | 1 + src/chdebug.c | 1 + src/chdelta.c | 3 ++- src/chevents.c | 5 +++-- src/chheap.c | 6 +++--- src/chinit.c | 2 -- src/chlists.c | 35 +++++++++++++++++++++-------------- src/chmempools.c | 3 ++- src/chmsg.c | 9 ++++----- src/chmtx.c | 8 ++++++-- src/chqueues.c | 32 +++++++++++++++++++------------- src/chschd.c | 20 ++++++++++---------- src/chsem.c | 28 ++++++++++++++++++---------- src/chserial.c | 22 +++++++++++----------- src/chthreads.c | 19 ++++++++++--------- src/include/lists.h | 2 +- src/templates/chcore.c | 24 ++++++++++++++++++++++++ src/templates/chcore.h | 24 ++---------------------- src/templates/chtypes.h | 39 +++++++++++++++++++++++++++++---------- 22 files changed, 213 insertions(+), 117 deletions(-) create mode 100644 docs/readme.txt diff --git a/docs/Doxyfile b/docs/Doxyfile index b9baae9ad..98fe036c1 100644 --- a/docs/Doxyfile +++ b/docs/Doxyfile @@ -9,7 +9,7 @@ PROJECT_NUMBER = "0.7.2 beta" OUTPUT_DIRECTORY = . CREATE_SUBDIRS = NO OUTPUT_LANGUAGE = English -BRIEF_MEMBER_DESC = NO +BRIEF_MEMBER_DESC = YES REPEAT_BRIEF = YES ABBREVIATE_BRIEF = "The $name class" \ "The $name widget" \ diff --git a/docs/ch.txt b/docs/ch.txt index 05d38e33c..de2db1c6f 100644 --- a/docs/ch.txt +++ b/docs/ch.txt @@ -328,6 +328,16 @@ */ /** @} */ +/** + * @defgroup ThreadLists Thread Lists and Queues + * @{ + * ChibiOS/RT thread lists and queues utilities. + * @ingroup Kernel + * @file chlists.c Lists and queues code. + * @file lists.h Lists and queues macros and structures. + */ +/** @} */ + /** * @defgroup Threads Threads * @{ diff --git a/docs/readme.txt b/docs/readme.txt new file mode 100644 index 000000000..730d20072 --- /dev/null +++ b/docs/readme.txt @@ -0,0 +1,35 @@ +*** Documentation access *** + +Open ./docs/index.html to open the start page or ./docs/html/index.html in +order to access directly the doxigen documentation. + +*** Documentation rebuild procedure *** + +The following software must be installed: +- Doxigen 1.5.7.1 or later. +- Graphviz 2.21 or later. The ./bin directory must be specified in the path in + order to make Graphviz accessible by doxigen. + +Build procedure: +- Run Doxiwizard. +- Load ./docs/Doxifile from Doxiwizard. +- Start. + +*** Doxygen usage rules *** +- The JavaDoc style is recommended (@ instad of \, /** instead of /*!). +- Params descriptions must not begin with a capital letter and must not be + terminated with a dot unless it is composed of multiple paragraphs. +- Retvals descriptions must not begin with a capital letter but must be + terminated by a dot. +- Normal paragraphs, return rescriptions and notes must start with a capital + letter and must be terminated with a dot. +- Multiple return values should be listed using the @retval command. +- AUTOBRIEF is enabled but deprecated, gradually convert to the use of explicit + @brief command. + +Examples: +@note This is a note. +@retval RDY_OK is a possible return value. +@return The pointer to the created thread is returned. +@param n the number of bytes to be written +@param n the number of bytes to be written. This value can be zero. diff --git a/readme.txt b/readme.txt index 8daa3d017..4395ba1f3 100644 --- a/readme.txt +++ b/readme.txt @@ -94,6 +94,7 @@ Win32-MinGW - ChibiOS/RT simulator and demo into a WIN32 process, - Modified the STM32 demo makefile to use the latest YAGARTO toolchain as default (arm-elf-gcc). - Documentation improvements, added collaboration diagrams and call graphs. + Added a documentation-related readme under ./docs. *** 0.7.1 *** - NEW: New chThdInit() and chThdCreateStatic() APIs now replace the old diff --git a/src/chdebug.c b/src/chdebug.c index 14b57669d..a826776fe 100644 --- a/src/chdebug.c +++ b/src/chdebug.c @@ -36,6 +36,7 @@ void chDbgInit(void) { /** * 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) { diff --git a/src/chdelta.c b/src/chdelta.c index 41f4490d0..62f3b35cc 100644 --- a/src/chdelta.c +++ b/src/chdelta.c @@ -28,7 +28,8 @@ DeltaList dlist; /** - * Virtual Timers initialization. Internal use only. + * Virtual Timers initialization. + * @note Internal use only. */ void chVTInit(void) { diff --git a/src/chevents.c b/src/chevents.c index 87ba7ca95..25d9d5d39 100644 --- a/src/chevents.c +++ b/src/chevents.c @@ -129,7 +129,7 @@ void chEvtBroadcastI(EventSource *esp) { * have indexes from zero up the higher registered event * identifier. The array can be \p NULL or contain \p NULL * elements (no callbacks specified). - * @return the event identifier + * @return The event identifier. * @note Only a single event is served in the function, the one with the * lowest event id. The function is meant to be invoked into a loop so * that all events are received and served.
@@ -153,7 +153,8 @@ eventid_t chEvtWait(eventmask_t ewmask, * identifier. The array can be NULL or contain NULL elements * (no callback specified). * @param time the number of ticks before the operation timouts - * @return the event identifier or \p RDY_TIMEOUT if the specified time expired + * @return The event identifier. + * @retval RDY_TIMEOUT if the specified timeout expired. * @note Only a single event is served in the function, the one with the * lowest event id. The function is meant to be invoked into a loop so * that all events are received and served.
diff --git a/src/chheap.c b/src/chheap.c index 7a2f0ccac..08ead3411 100644 --- a/src/chheap.c +++ b/src/chheap.c @@ -98,8 +98,8 @@ void chHeapInit(void) { * @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. - * @return a pointer to the allocated block or \p NULL if the block cannot be - * allocated. + * @return A pointer to the allocated block. + * @retval NULL if the block cannot be allocated. */ void *chHeapAlloc(size_t size) { struct header *qp, *hp, *fp; @@ -187,7 +187,7 @@ void chHeapFree(void *p) { * Determines 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 + * @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. * @note This function is not implemented when the \p CH_USE_MALLOC_HEAP diff --git a/src/chinit.c b/src/chinit.c index 9162d84f1..5d46808d8 100644 --- a/src/chinit.c +++ b/src/chinit.c @@ -62,11 +62,9 @@ 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. - * * @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/chlists.c b/src/chlists.c index 3f5f3e8ee..3df824397 100644 --- a/src/chlists.c +++ b/src/chlists.c @@ -18,19 +18,20 @@ */ /** - * @addtogroup Threads + * @addtogroup ThreadLists * @{ */ #include #ifndef CH_OPTIMIZE_SPEED -/* +/** * 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 The insertion is done by scanning the list from the highest priority + * toward the lowest. + * @note This function is \b not an API. */ void prio_insert(Thread *tp, ThreadsQueue *tqp) { @@ -46,11 +47,12 @@ void prio_insert(Thread *tp, ThreadsQueue *tqp) { tp->p_prev->p_next = cp->p_prev = tp; } -/* +/** * 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. */ void queue_insert(Thread *tp, ThreadsQueue *tqp) { @@ -58,11 +60,12 @@ void queue_insert(Thread *tp, ThreadsQueue *tqp) { tp->p_prev->p_next = tqp->p_prev = tp; } -/* +/** * 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 + * @return The removed thread pointer. + * @note This function is \b not an API. */ Thread *fifo_remove(ThreadsQueue *tqp) { Thread *tp = tqp->p_next; @@ -71,11 +74,12 @@ Thread *fifo_remove(ThreadsQueue *tqp) { return tp; } -/* +/** * 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 + * @return The removed thread pointer. + * @note This function is \b not an API. */ Thread *lifo_remove(ThreadsQueue *tqp) { Thread *tp = tqp->p_next; @@ -84,11 +88,12 @@ Thread *lifo_remove(ThreadsQueue *tqp) { return tp; } -/* +/** * 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 + * @return The removed thread pointer. + * @note This function is \b not an API. */ Thread *dequeue(Thread *tp) { @@ -97,11 +102,12 @@ Thread *dequeue(Thread *tp) { return tp; } -/* +/** * 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. */ void list_insert(Thread *tp, ThreadsList *tlp) { @@ -109,12 +115,13 @@ void list_insert(Thread *tp, ThreadsList *tlp) { tlp->p_next = tp; } -/* +/** * 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 + * @return The removed thread pointer. * @note The list must be non-empty before calling this function. + * @note This function is \b not an API. */ Thread *list_remove(ThreadsList *tlp) { diff --git a/src/chmempools.c b/src/chmempools.c index 52914b7c6..ae97648a4 100644 --- a/src/chmempools.c +++ b/src/chmempools.c @@ -43,7 +43,8 @@ void chPoolInit(MemoryPool *mp, size_t size) { /** * Allocates an object from a memory pool. * @param mp pointer to a \p MemoryPool structure - * @return the pointer to the allocated object or \p NULL if pool is empty + * @return The pointer to the allocated object. + * @retval NULL if pool is empty. */ void *chPoolAlloc(MemoryPool *mp) { void *objp; diff --git a/src/chmsg.c b/src/chmsg.c index 5a1ce4b15..51a126c0f 100644 --- a/src/chmsg.c +++ b/src/chmsg.c @@ -30,7 +30,7 @@ * * @param tp the pointer to the thread * @param msg the message, it can be a pointer to a complex structure - * @return the return message from \p chMsgRelease() + * @return The return message from \p chMsgRelease(). */ msg_t chMsgSend(Thread *tp, msg_t msg) { @@ -61,8 +61,7 @@ msg_t chMsgSend(Thread *tp, msg_t msg) { * @param tp the pointer to the thread * @param msg the message, it can be a pointer to a complex structure * @param esp the event source to pulse while sending the message - * @return the return message from \p chMsgRelease() - * @return the message return status from \p chMsgRelease() + * @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 * for both messages AND events while waiting into \p chEvtWait(). @@ -91,7 +90,7 @@ msg_t chMsgSendWithEvent(Thread *tp, msg_t msg, EventSource *esp) { /** * Suspends the thread and waits for an incoming message. * - * @return the pointer to the message structure. Note, it is always the + * @return The pointer to the message structure. Note, it is always the * message associated to the thread on the top of the messages queue. * @note You can assume that the data contained in the message is stable until * you invoke \p chMsgRelease() because the sending thread is @@ -113,7 +112,7 @@ msg_t chMsgWait(void) { /** * Returns the next message in the queue. * - * @return the pointer to the message structure. Note, it is always the + * @return The pointer to the message structure. Note, it is always the * message associated to the thread on the top of the messages queue. * If the queue is empty then \p NULL is returned. * @note You can assume that the data pointed by the message is stable until diff --git a/src/chmtx.c b/src/chmtx.c index f5dbaca43..ea3ccccda 100644 --- a/src/chmtx.c +++ b/src/chmtx.c @@ -114,7 +114,8 @@ void chMtxLockS(Mutex *mp) { * 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 - * @return \p TRUE if the mutex was successfully acquired else \p FALSE + * @retval TRUE if the mutex was successfully acquired + * @retval FALSE if the lock attempt failed. */ bool_t chMtxTryLock(Mutex *mp) { bool_t b; @@ -132,7 +133,8 @@ bool_t chMtxTryLock(Mutex *mp) { * 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 - * @return \p TRUE if the mutex was successfully acquired else \p FALSE + * @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() * block. */ @@ -148,6 +150,7 @@ bool_t chMtxTryLockS(Mutex *mp) { /** * Unlocks the next owned mutex in reverse lock order. + * @return The pointer to the unlocked mutex. */ Mutex *chMtxUnlock(void) { Mutex *ump, *mp; @@ -192,6 +195,7 @@ Mutex *chMtxUnlock(void) { /** * 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. * @note This function does not reschedule internally. diff --git a/src/chqueues.c b/src/chqueues.c index ec456c5f1..ed9eb840c 100644 --- a/src/chqueues.c +++ b/src/chqueues.c @@ -62,8 +62,8 @@ void chIQReset(Queue *qp) { * Inserts a byte into an input queue. * @param qp pointer to a \p Queue structure * @param b the byte value to be written - * @return \p Q_OK if the operation is successful or \p Q_FULL if the queue is - * full. + * @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. * @note This function must be called with interrupts disabled or from an * interrupt handler. @@ -84,7 +84,8 @@ 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. * @param qp pointer to a \p Queue structure - * @return a byte from the queue or \p Q_RESET if the queue was reset + * @return A byte value from the queue. + * @retval Q_RESET if the queue was reset. */ msg_t chIQGet(Queue *qp) { uint8_t b; @@ -114,8 +115,9 @@ msg_t chIQGet(Queue *qp) { * specified time expires. * @param qp pointer to a \p Queue structure * @param time the number of ticks before the operation timouts - * @return a byte from the queue, \p Q_TIMEOUT if the specified time expired - * or \p Q_RESET if the queue was reset + * @return A byte value from the queue. + * @retval Q_TIMEOUT if the specified time expired. + * @retval Q_RESET if the queue was reset. * @note The function is available only if the \p CH_USE_QUEUES_TIMEOUT * option is enabled in \p chconf.h. */ @@ -148,7 +150,7 @@ msg_t chIQGetTimeout(Queue *qp, systime_t time) { * @param qp pointer to a \p Queue structure * @param buffer the data buffer * @param n the maximum amount of data to be read - * @return the number of bytes 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 * to use a semaphore for mutual exclusion. @@ -240,7 +242,8 @@ void chOQPut(Queue *qp, uint8_t b) { /** * Gets a byte from an output queue. * @param qp pointer to a \p Queue structure - * @return the byte value or \p Q_EMPTY if the queue is empty + * @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. * @note This function must be called with interrupts disabled or from an * interrupt handler. @@ -264,6 +267,7 @@ msg_t chOQGetI(Queue *qp) { * @param qp pointer to a \p Queue structure * @param buffer the data buffer * @param 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 * to use a semaphore for mutual exclusion. @@ -326,7 +330,8 @@ 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. * @param qp pointer to a \p HalfDuplexQueue structure - * @return the byte value or \p Q_RESET if the queue was reset + * @return The byte value. + * @retval Q_RESET if the queue was reset. */ msg_t chHDQGetReceive(HalfDuplexQueue *qp) { uint8_t b; @@ -359,7 +364,8 @@ msg_t chHDQGetReceive(HalfDuplexQueue *qp) { * 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 or \p Q_TIMEOUT if a timeout occurs + * @return The byte value. + * @retval Q_TIMEOUT if a timeout occurs. * @note The function is available only if the \p CH_USE_QUEUES_TIMEOUT * option is enabled in \p chconf.h. */ @@ -426,8 +432,8 @@ void chHDQPutTransmit(HalfDuplexQueue *qp, uint8_t b) { /** * Gets a byte from the transmit queue. * @param qp pointer to a \p HalfDuplexQueue structure - * @return the byte value or \p Q_EMPTY if the transmit queue is empty (not in - * transmission mode) + * @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 * interrupt handler. */ @@ -449,8 +455,8 @@ msg_t chHDQGetTransmitI(HalfDuplexQueue *qp) { * then the byte is lost. * @param qp pointer to a \p HalfDuplexQueue structure * @param b the byte value to be written - * @return \p Q_OK if the operation is successful or \p Q_FULL if the driver - * is in transmit mode or the receive queue is full. + * @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 * interrupt handler. */ diff --git a/src/chschd.c b/src/chschd.c index 8b606cd1b..c9e4608ca 100644 --- a/src/chschd.c +++ b/src/chschd.c @@ -48,7 +48,7 @@ void chSchInit(void) { * Inserts a thread in the Ready List. * * @param tp the Thread to be made ready - * @return the Thread pointer + * @return The Thread pointer. * @note The function must be called in the system mutex zone. * @note The function does not reschedule, the \p chSchRescheduleS() should * be called soon after. @@ -108,15 +108,16 @@ static void wakeup(void *p) { } /** - * Put the current thread to sleep. + * 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. * * @param newstate the new thread state - * @param time the number of ticks before the operation timouts - * @return the wakeup message, it is \p RDY_TIMEOUT if a timeout occurs + * @param time the number of ticks before the operation timeouts + * @return The wakeup message. + * @retval RDY_TIMEOUT if a timeout occurs. * @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. */ @@ -134,9 +135,8 @@ msg_t chSchGoSleepTimeoutS(tstate_t newstate, systime_t time) { /** * Wakes up a thread. * - * Wakes up a thread. 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. @@ -171,7 +171,7 @@ void chSchWakeupS(Thread *ntp, msg_t msg) { /** * Switch to the first thread on the runnable queue. * - * Intended to be called if \p chSchRescRequired() evaluates to \p TRUE. + * @note It is intended to be called if \p chSchRescRequired() evaluates to \p TRUE. */ void chSchDoRescheduleI(void) { @@ -206,8 +206,8 @@ void chSchRescheduleS(void) { /** * Evaluates if rescheduling is required. * - * @return \p TRUE if there is a thread that should go in running state - * immediately else \p FALSE. + * @retval TRUE if there is a thread that should go in running state. + * @retval FALSE if a reschedulation is not required. */ bool_t chSchRescRequiredI(void) { tprio_t p1 = firstprio(&rlist.r_queue); diff --git a/src/chsem.c b/src/chsem.c index b5c197b6b..011737642 100644 --- a/src/chsem.c +++ b/src/chsem.c @@ -41,7 +41,7 @@ void chSemInit(Semaphore *sp, cnt_t n) { /** * Performs a reset operation on the semaphore. * @param sp pointer to a \p Semaphore structure - * @param n the new value of the semaphore counter. Must be non-negative. + * @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 * instead than a signal because the \p chSemWait() will return * \p RDY_RESET instead of \p RDY_OK. @@ -59,7 +59,7 @@ void chSemReset(Semaphore *sp, cnt_t n) { /** * Performs a reset operation on the semaphore. * @param sp pointer to a \p Semaphore structure - * @param n the new value of the semaphore counter. Must be non-negative. + * @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 * instead than a signal because the \p chSemWait() will return * \p RDY_RESET instead of \p RDY_OK. @@ -78,7 +78,8 @@ void chSemResetI(Semaphore *sp, cnt_t n) { /** * Performs a wait operation on a semaphore. * @param sp pointer to a \p Semaphore structure - * @return the function can return \p RDY_OK or \p RDY_RESET. + * @retval RDY_OK if the semaphore was signaled or not taken. + * @retval RDY_RESET if the semaphore was reset using \p chSemReset(). */ msg_t chSemWait(Semaphore *sp) { msg_t msg; @@ -94,7 +95,8 @@ msg_t chSemWait(Semaphore *sp) { /** * Performs a wait operation on a semaphore. * @param sp pointer to a \p Semaphore structure - * @return the function can return \p RDY_OK or \p RDY_RESET. + * @retval RDY_OK if the semaphore was signaled or not taken. + * @retval RDY_RESET if the semaphore was reset using \p chSemReset(). * @note This function must be called with interrupts disabled. * @note This function cannot be called by an interrupt handler. */ @@ -114,7 +116,12 @@ msg_t chSemWaitS(Semaphore *sp) { * 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 - * @return the function can return \p RDY_OK, \p RDY_TIMEOUT or \p RDY_RESET. + * @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 specified + * timeout. + * @note The function is available only if the \p CH_USE_SEMAPHORES_TIMEOUT + * option is enabled in \p chconf.h. */ msg_t chSemWaitTimeout(Semaphore *sp, systime_t time) { msg_t msg; @@ -131,9 +138,10 @@ msg_t chSemWaitTimeout(Semaphore *sp, systime_t time) { * 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 - * @return the function can return \p RDY_OK, \p RDY_TIMEOUT or \p RDY_RESET. - * @note This function must be called with interrupts disabled. - * @note This function cannot be called by an interrupt handler. + * @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 specified + * timeout. * @note The function is available only if the \p CH_USE_SEMAPHORES_TIMEOUT * option is enabled in \p chconf.h. */ @@ -167,7 +175,6 @@ void chSemSignal(Semaphore *sp) { /** * Performs a signal operation on a semaphore. * @param sp pointer to a \p Semaphore structure - * @note This function must be called with interrupts disabled. * @note The function is available only if the \p CH_USE_SEMAPHORES * option is enabled in \p chconf.h. * @note This function does not reschedule. @@ -188,7 +195,8 @@ void chSemSignalI(Semaphore *sp) { * 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 - * @return the function can return \p RDY_OK or \p RDY_RESET. + * @retval RDY_OK if the semaphore was signaled or not taken. + * @retval RDY_RESET if the semaphore was reset using \p chSemReset(). * @note The function is available only if the \p CH_USE_SEMSW * option is enabled in \p chconf.h. */ diff --git a/src/chserial.c b/src/chserial.c index f185c91fc..4ab65e140 100644 --- a/src/chserial.c +++ b/src/chserial.c @@ -70,9 +70,9 @@ void chFDDIncomingDataI(FullDuplexDriver *sd, uint8_t b) { * the next byte to be transmitted. * * @param sd pointer to a \p FullDuplexDriver structure - * @return the byte read from the driver's Output Queue or \p Q_EMPTY if the - * queue is empty (the lower driver usually disables the interrupt - * source when this happens). + * @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). */ msg_t chFDDRequestDataI(FullDuplexDriver *sd) { @@ -97,8 +97,8 @@ void chFDDAddFlagsI(FullDuplexDriver *sd, dflags_t mask) { /** * This function 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 + * @return The condition flags modified since last time this function was + * invoked. */ dflags_t chFDDGetAndClearFlags(FullDuplexDriver *sd) { dflags_t mask; @@ -136,7 +136,7 @@ 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. * @param sd pointer to a \p FullDuplexDriver structure - * @param b the byte to be written in the driver's Input Queue + * @param b the byte to be written in the driver's input queue */ void chHDDIncomingDataI(HalfDuplexDriver *sd, uint8_t b) { @@ -151,9 +151,9 @@ void chHDDIncomingDataI(HalfDuplexDriver *sd, uint8_t b) { * the next byte to be transmitted. * * @param sd pointer to a \p HalfDuplexDriver structure - * @return the byte read from the driver's Output Queue or \p Q_EMPTY if the - * queue is empty (the lower driver usually disables the interrupt - * source when this happens). + * @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). */ msg_t chHDDRequestDataI(HalfDuplexDriver *sd) { @@ -178,8 +178,8 @@ void chHDDAddFlagsI(HalfDuplexDriver *sd, dflags_t mask) { /** * This function 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 + * @return The condition flags modified since last time this function was + * invoked. */ dflags_t chHDDGetAndClearFlags(HalfDuplexDriver *sd) { dflags_t mask; diff --git a/src/chthreads.c b/src/chthreads.c index 755cda99e..58df0a5c1 100644 --- a/src/chthreads.c +++ b/src/chthreads.c @@ -74,7 +74,7 @@ static void memfill(uint8_t *p, uint32_t n, uint8_t v) { * @param wsize size of the working area. * @param pf the thread function * @param arg an argument passed to the thread function. It can be \p NULL. - * @return the pointer to the \p Thread structure allocated for the + * @return The pointer to the \p Thread structure allocated for the * thread into the working space area. * @note A thread can terminate by calling \p chThdExit() or by simply * returning from its main function. @@ -104,7 +104,7 @@ Thread *chThdInit(void *workspace, size_t wsize, * can range from \p LOWPRIO to \p HIGHPRIO. * @param pf the thread function * @param arg an argument passed to the thread function. It can be \p NULL. - * @return the pointer to the \p Thread structure allocated for the + * @return The pointer to the \p Thread structure allocated for the * thread into the working space area. * @note A thread can terminate by calling \p chThdExit() or by simply * returning from its main function. @@ -124,9 +124,9 @@ Thread *chThdCreateStatic(void *workspace, size_t wsize, * can range from \p LOWPRIO to \p HIGHPRIO. * @param pf the thread function * @param arg an argument passed to the thread function. It can be \p NULL. - * @return the pointer to the \p Thread structure allocated for the - * thread into the working space area or \p NULL if the memory cannot - * be allocated. + * @return The pointer to the \p Thread structure allocated for the + * thread into the working space area. + * @retval NULL if the memory cannot be allocated. * @note A thread can terminate by calling \p chThdExit() or by simply * returning from its main function. * @note The memory allocated for the thread is not released when the thread @@ -156,9 +156,10 @@ Thread *chThdCreateFromHeap(size_t wsize, tprio_t prio, * can range from \p LOWPRIO to \p HIGHPRIO. * @param pf the thread function * @param arg an argument passed to the thread function. It can be \p NULL. - * @return the pointer to the \p Thread structure allocated for the + * @return The pointer to the \p Thread structure allocated for the * thread into the working space area or \p NULL if the memory cannot * be allocated. + * @retval NULL if the memory pool is empty. * @note A thread can terminate by calling \p chThdExit() or by simply * returning from its main function. * @note The memory allocated for the thread is not released when the thread @@ -197,7 +198,7 @@ Thread *chThdCreateFromMemoryPool(MemoryPool *mp, tprio_t prio, * @param wsize size of the working area. * @param pf the thread function * @param arg an argument passed to the thread function. It can be \p NULL. - * @return the pointer to the \p Thread structure allocated for the + * @return The pointer to the \p Thread structure allocated for the * thread into the working space area. * @note A thread can terminate by calling \p chThdExit() or by simply * returning from its main function. @@ -261,7 +262,7 @@ void chThdSuspend(Thread **tpp) { /** * Resumes a suspended thread. * @param tp the pointer to the thread - * @return the pointer to the thread + * @return The pointer to the thread. */ Thread *chThdResume(Thread *tp) { @@ -324,7 +325,7 @@ void chThdExit(msg_t msg) { * working area is returned to the owning memory pool. * * @param tp the thread pointer - * @return the exit code from the terminated thread + * @return The exit code from the terminated thread * @note After invoking \p chThdWait() the thread pointer becomes invalid and * must not be used as parameter for further system calls. * @note The function is available only if the \p CH_USE_WAITEXIT diff --git a/src/include/lists.h b/src/include/lists.h index 5c3c98093..2f4324b71 100644 --- a/src/include/lists.h +++ b/src/include/lists.h @@ -18,7 +18,7 @@ */ /** - * @addtogroup Threads + * @addtogroup ThreadLists * @{ */ diff --git a/src/templates/chcore.c b/src/templates/chcore.c index 2aaa0b06a..95427c161 100644 --- a/src/templates/chcore.c +++ b/src/templates/chcore.c @@ -54,6 +54,30 @@ void chSysHalt(void) { ; } +/** + * Enters the ChibiOS/RT system mutual exclusion zone. The implementation is + * architecture dependent, on single core systems usually this function usually + * just disables the interrupts. + * @note The code in the system mutual exclusion zone must be as light and + * fast as possible, the system performance is affected by this. + * @note The use of system mutual exclusion zones are not recommended in + * the user code, it is a better idea to use the Semaphores instead. + */ +void chSysLock(void) { +} + +/** + * Leaves the ChibiOS/RT system mutual exclusion zone. The implementation is + * architecture dependent, on single core systems usually this function usually + * just enables the interrupts. + * @note The code in the system mutual exclusion zone must be as light and + * fast as possible, the system performance is affected by this. + * @note The use of system mutual exclusion zones are not recommended in + * the user code, it is a better idea to use the Semaphores instead. + */ +void chSysUnlock(void) { +} + /** * Context switch. */ diff --git a/src/templates/chcore.h b/src/templates/chcore.h index c84a237f8..1be2d7145 100644 --- a/src/templates/chcore.h +++ b/src/templates/chcore.h @@ -83,28 +83,6 @@ typedef struct { */ #define WorkingArea(s, n) uint8_t s[UserStackSize(n)]; -/** - * Enters the ChibiOS/RT system mutual exclusion zone, the implementation is - * architecture dependent, on single core systems usually this function - * just disables the interrupts. - * @note The code in the system mutual exclusion zone must be as light and - * fast as possible, the system performance is affected by this. - * @note The use of system mutual exclusion zones are not recommended in - * the user code, it is a better idea to use the Semaphores instead. - */ -#define chSysLock() - -/** - * Leaves the ChibiOS/RT system mutual exclusion zone, the implementation is - * architecture dependent, on single core systems usually this function - * just enables the interrupts. - * @note The code in the system mutual exclusion zone must be as light and - * fast as possible, the system performance is affected by this. - * @note The use of system mutual exclusion zones are not recommended in - * the user code, it is a better idea to use the Semaphores instead. - */ -#define chSysUnlock() - /** * Enables the interrupts, it is only invoked once into \p chSysInit(). */ @@ -130,6 +108,8 @@ extern "C" { #endif void _IdleThread(void *p); void chSysHalt(void); + void chSysLock(void); + void chSysUnlock(void); void chSysSwitchI(Thread *otp, Thread *ntp); void chSysPuts(char *msg); #ifdef __cplusplus diff --git a/src/templates/chtypes.h b/src/templates/chtypes.h index 6c51687ad..92b5dc443 100644 --- a/src/templates/chtypes.h +++ b/src/templates/chtypes.h @@ -33,16 +33,35 @@ #include #endif -typedef int32_t bool_t; /* Signed boolean. */ -typedef uint8_t tmode_t; /* Thread mode flags, uint8_t is ok. */ -typedef uint8_t tstate_t; /* Thread state, uint8_t is ok. */ -typedef uint16_t tid_t; /* Thread id. */ -typedef uint32_t tprio_t; /* Priority, use the fastest unsigned type. */ -typedef int32_t msg_t; /* Message, use signed pointer equivalent.*/ -typedef int32_t eventid_t; /* Event Id, use fastest signed.*/ -typedef uint32_t eventmask_t;/* Event Mask, recommended fastest unsigned.*/ -typedef uint32_t systime_t; /* System Time, recommended fastest unsigned.*/ -typedef int32_t cnt_t; /* Counter, recommended fastest signed.*/ +/** Signed boolean. */ +typedef int32_t bool_t; + +/** Thread mode flags, uint8_t is ok. */ +typedef uint8_t tmode_t; + +/** Thread state, uint8_t is ok. */ +typedef uint8_t tstate_t; + +/** Thread id. */ +typedef uint16_t tid_t; + +/** Priority, use the fastest unsigned type. */ +typedef uint32_t tprio_t; + +/** Message, use signed pointer equivalent.*/ +typedef int32_t msg_t; + +/** Event Id, use fastest signed.*/ +typedef int32_t eventid_t; + +/** Event Mask, recommended fastest unsigned.*/ +typedef uint32_t eventmask_t; + +/** System Time, recommended fastest unsigned.*/ +typedef uint32_t systime_t; + +/** Counter, recommended fastest signed.*/ +typedef int32_t cnt_t; #define INLINE inline #define PACK_STRUCT_STRUCT __attribute__((packed)) -- cgit v1.2.3