andreika-git
/
ChibiOS
mirror of https://github.com/andreika-git/ChibiOS.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@649 35acf78f-673a-0410-8e92-d51de3d6d3f4

This commit is contained in:
gdisirio 2009-01-20 16:26:48 +00:00
parent b1d77bf4bc
commit 22e22db016
22 changed files with 613 additions and 403 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

45
docs/ch.txt
View File

@ -66,15 +66,17 @@
* The possible groups are: @a Sys, @a Sch, @a VT, @a Thd, @a Sem, @a Mtx, * The possible groups are: @a Sys, @a Sch, @a VT, @a Thd, @a Sem, @a Mtx,
* @a Cond, @a Evt, @a Msg, @a IQ, @a OQ, @a HQ, @a FDD, @a HDD, @a Dbg, * @a Cond, @a Evt, @a Msg, @a IQ, @a OQ, @a HQ, @a FDD, @a HDD, @a Dbg,
* @a Heap, @a Pool. * @a Heap, @a Pool.
*
* @section api_suffixes API Names Suffixes
* The suffix is not present for normal APIs but can be one of * The suffix is not present for normal APIs but can be one of
* the following: * the following:
* - <b>"I"</b>, I-Class APIs are invokable only from the I-Locked or S-Locked * - <b>None</b>, APIs without any suffix can be invoked only from the user
* states. See @ref system_states. * code in the <b>Normal</b> state unless differently specified. See
* - <b>"S"</b>, S-Class APIs are invokable only from the S-Locked state. See
* @ref system_states. * @ref system_states.
* * - <b>"I"</b>, I-Class APIs are invokable only from the <b>I-Locked</b> or
* The APIs without suffix can be invoked only from the user code in the Normal * <b>S-Locked</b> states. See @ref system_states.
* state unless differently specified.<br> * - <b>"S"</b>, S-Class APIs are invokable only from the <b>S-Locked</b>
* state. See @ref system_states.
* Examples: @p chThdCreateStatic(), @p chSemSignalI(), @p chIQGetTimeout(). * Examples: @p chThdCreateStatic(), @p chSemSignalI(), @p chIQGetTimeout().
* *
* @section interrupt_classes Interrupt Classes * @section interrupt_classes Interrupt Classes
@ -557,12 +559,43 @@
*/ */
/** @} */ /** @} */
/**
* @defgroup utilities_library Utilities Library
* @{
* @brief Utilities Library.
* @details This is a collection of useful library code that is not part of
* the base kernel services.
* <h2>Notes</h2>
* The library code does not follow the same naming convention of the
* system APIs in order to make very clear that it is not "core" code.<br>
* The main difference is that library code is not formally tested in the
* test suite but through usage in the various demo application.
*/
/** @} */
/** /**
* @defgroup CPlusPlusLibrary C++ Wrapper * @defgroup CPlusPlusLibrary C++ Wrapper
* @{ * @{
* C++ wrapper module. This module allows to use the ChibiOS/RT functionalities * C++ wrapper module. This module allows to use the ChibiOS/RT functionalities
* from C++ as classes and objects rather the traditional "C" APIs. * from C++ as classes and objects rather the traditional "C" APIs.
*
* @ingroup utilities_library
* @file ch.hpp C++ wrapper classes and definitions. * @file ch.hpp C++ wrapper classes and definitions.
* @file ch.cpp C++ wrapper code. * @file ch.cpp C++ wrapper code.
*/ */
/** @} */ /** @} */
/**
* @defgroup event_timer Events Generator Timer
* @{
* @brief Event Generator Timer.
* @details This timer generates an event at regular intervals. The
* listening threads can use the event to perform time related activities.
* Multiple threads can listen to the same timer.
*
* @ingroup utilities_library
* @file evtimer.c Events Generator Timer code.
* @file evtimer.h Events Generator Timer structures and macros.
*/
/** @} */

63
src/chcond.c
View File

@ -31,8 +31,12 @@
#if defined(CH_USE_CONDVARS) && defined(CH_USE_MUTEXES) #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 * @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) { 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 * @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 * @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) { 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 * @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 * @param cp pointer to the @p CondVar structure
* @note This function must be called within a @p chSysLock() / @p chSysUnlock()
*/ */
void chCondBroadcastI(CondVar *cp) { void chCondBroadcastI(CondVar *cp) {
@ -98,17 +99,16 @@ void chCondBroadcastI(CondVar *cp) {
} }
/** /**
* Waits on the condition variable releasing the mutex lock. * @brief Waits on the condition variable releasing the mutex lock.
* * @details Releases the mutex, waits on the condition variable, and finally
* Releases the mutex, waits on the condition variable, and finally acquires * acquires the mutex again. This is done atomically.
* the mutex again. This is done atomically.
*
* The thread MUST already have locked the mutex when calling chCondWait().
* *
* @param cp pointer to the @p CondVar structure * @param cp pointer to the @p CondVar structure
* @return The wakep mode. * @return The wakep mode.
* @retval RDY_OK if the condvar was signaled using chCondSignal(). * @retval RDY_OK if the condvar was signaled using chCondSignal().
* @retval RDY_RESET if the condvar was signaled using chCondBroadcast(). * @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 chCondWait(CondVar *cp) {
msg_t msg; msg_t msg;
@ -122,18 +122,16 @@ msg_t chCondWait(CondVar *cp) {
} }
/** /**
* Waits on the condition variable releasing the mutex lock. * @brief Waits on the condition variable releasing the mutex lock.
* * @details Releases the mutex, waits on the condition variable, and finally
* Releases the mutex, waits on the condition variable, and finally acquires * acquires the mutex again. This is done atomically.
* the mutex again. This is done atomically.
*
* The thread MUST already have locked the mutex when calling chCondWait().
* *
* @param cp pointer to the @p CondVar structure * @param cp pointer to the @p CondVar structure
* @return The wakep mode. * @return The wakep mode.
* @retval RDY_OK if the condvar was signaled using chCondSignal(). * @retval RDY_OK if the condvar was signaled using chCondSignal().
* @retval RDY_RESET if the condvar was signaled using chCondBroadcast(). * @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) { msg_t chCondWaitS(CondVar *cp) {
Mutex *mp; Mutex *mp;
@ -152,12 +150,9 @@ msg_t chCondWaitS(CondVar *cp) {
#ifdef CH_USE_CONDVARS_TIMEOUT #ifdef CH_USE_CONDVARS_TIMEOUT
/** /**
* Waits on the condition variable releasing the mutex lock. * @brief Waits on the condition variable releasing the mutex lock.
* * @details Releases the mutex, waits on the condition variable, and finally
* Releases the mutex, waits on the condition variable, and finally acquires * acquires the mutex again. This is done atomically.
* the mutex again. This is done atomically.
*
* The thread MUST already have locked the mutex when calling chCondWait().
* *
* @param cp pointer to the @p CondVar structure * @param cp pointer to the @p CondVar structure
* @param time the number of ticks before the operation fails * @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_RESET if the condvar was signaled using chCondBroadcast().
* @retval RDY_TIMEOUT if the condvar was not signaled within the specified * @retval RDY_TIMEOUT if the condvar was not signaled within the specified
* timeout. * timeout.
* @note The thread MUST already have locked the mutex when calling
* @p chCondWaitTimeout().
*/ */
msg_t chCondWaitTimeout(CondVar *cp, systime_t time) { msg_t chCondWaitTimeout(CondVar *cp, systime_t time) {
msg_t msg; msg_t msg;
@ -179,12 +176,9 @@ msg_t chCondWaitTimeout(CondVar *cp, systime_t time) {
} }
/** /**
* Waits on the condition variable releasing the mutex lock. * @brief Waits on the condition variable releasing the mutex lock.
* * @details Releases the mutex, waits on the condition variable, and finally
* Releases the mutex, waits on the condition variable, and finally acquires * acquires the mutex again. This is done atomically.
* the mutex again. This is done atomically.
*
* The thread MUST already have locked the mutex when calling chCondWait().
* *
* @param cp pointer to the @p CondVar structure * @param cp pointer to the @p CondVar structure
* @param time the number of ticks before the operation fails * @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_RESET if the condvar was signaled using chCondBroadcast().
* @retval RDY_TIMEOUT if the condvar was not signaled within the specified * @retval RDY_TIMEOUT if the condvar was not signaled within the specified
* timeout. * 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) { msg_t chCondWaitTimeoutS(CondVar *cp, systime_t time) {
Mutex *mp; Mutex *mp;

11
src/chdebug.c
View File

@ -24,7 +24,7 @@
char *panicmsg; char *panicmsg;
/** /**
* Debug subsystem initialization. * @brief Debug subsystem initialization.
*/ */
void chDbgInit(void) { 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 * @param msg the pointer to the message string
*/ */
void chDbgPanic(char *msg) { void chDbgPanic(char *msg) {
@ -48,12 +50,13 @@ void chDbgPanic(char *msg) {
#ifdef CH_USE_TRACE #ifdef CH_USE_TRACE
/** /**
* Public trace buffer. * @brief Public trace buffer.
*/ */
TraceBuffer dbgtb; 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 otp the thread being switched out
* @param ntp the thread to be resumed * @param ntp the thread to be resumed
*/ */

66
src/chevents.c
View File

@ -25,7 +25,8 @@
#ifdef CH_USE_EVENTS #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 esp pointer to the @p EventSource structure
* @param elp pointer to the @p EventListener structure * @param elp pointer to the @p EventListener structure
* @param emask the mask of event flags to be pended to the thread when the * @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 esp pointer to the @p EventSource structure
* @param elp pointer to the @p EventListener structure * @param elp pointer to the @p EventListener structure
* @note If the event listener is not registered on the specified event source * @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 * @param mask the events to be cleared
* @return The pending events that were 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 * @brief Makes an events mask pending in the current thread, this is \b much
* using @p chEvtBroadcast(). * faster than using @p chEvtBroadcast().
*
* @param mask the events to be pended * @param mask the events to be pended
* @return The current pending events mask. * @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 * @param esp pointer to the @p EventSource structure
*/ */
void chEvtBroadcast(EventSource *esp) { 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 * @param esp pointer to the @p EventSource structure
* @note This function does not reschedule.
*/ */
void chEvtBroadcastI(EventSource *esp) { void chEvtBroadcastI(EventSource *esp) {
EventListener *elp; 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 mask mask of the events to be dispatched
* @param handlers an array of @p evhandler_t. The array must be * @param handlers an array of @p evhandler_t. The array must be
* have indexes from zero up the higher registered event * 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) || \ #if defined(CH_OPTIMIZE_SPEED) || !defined(CH_USE_EVENTS_TIMEOUT) || \
defined(__DOXIGEN__) defined(__DOXIGEN__)
/** /**
* A pending event among those specified in @p ewmask is selected, cleared and * @brief A pending event among those specified in @p ewmask is selected,
* its mask returned. * cleared and its mask returned.
*
* @param ewmask mask of the events that the function should wait for, * @param ewmask mask of the events that the function should wait for,
* @p ALL_EVENTS enables all the events * @p ALL_EVENTS enables all the events
* @return The mask of the lowest id served and cleared event. * @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. * @brief Waits for any of the specified events.
* The function waits for any event among those specified in @p ewmask to * @details The function waits for any event among those specified in
* become pending then the events are cleared and returned. * @p ewmask to become pending then the events are cleared and returned.
*
* @param ewmask mask of the events that the function should wait for, * @param ewmask mask of the events that the function should wait for,
* @p ALL_EVENTS enables all the events * @p ALL_EVENTS enables all the events
* @return The mask of the served and cleared 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. * @brief Waits for all the specified event flags then clears them.
* The function waits for all the events specified in @p ewmask to become * @details The function waits for all the events specified in @p ewmask to
* pending then the events are cleared and returned. * become pending then the events are cleared and returned.
*
* @param ewmask mask of the event ids that the function should wait for * @param ewmask mask of the event ids that the function should wait for
* @return The mask of the served and cleared events. * @return The mask of the served and cleared events.
*/ */
@ -239,9 +250,10 @@ eventmask_t chEvtWaitAll(eventmask_t ewmask) {
#ifdef CH_USE_EVENTS_TIMEOUT #ifdef CH_USE_EVENTS_TIMEOUT
/** /**
* Waits for a single event. * @brief Waits for a single event.
* A pending event among those specified in @p ewmask is selected, cleared and * @details A pending event among those specified in @p ewmask is selected,
* its mask returned. * cleared and its mask returned.
*
* @param ewmask mask of the events that the function should wait for, * @param ewmask mask of the events that the function should wait for,
* @p ALL_EVENTS enables all the events * @p ALL_EVENTS enables all the events
* @param time the number of ticks before the operation timouts * @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. * @brief Waits for any of the specified events.
* The function waits for any event among those specified in @p ewmask to * @details The function waits for any event among those specified in @p ewmask
* become pending then the events are cleared and returned. * to become pending then the events are cleared and returned.
*
* @param ewmask mask of the events that the function should wait for, * @param ewmask mask of the events that the function should wait for,
* @p ALL_EVENTS enables all the events * @p ALL_EVENTS enables all the events
* @param time the number of ticks before the operation timouts * @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. * @brief Waits for all the specified event flags then clears them.
* The function waits for all the events specified in @p ewmask to become * @details The function waits for all the events specified in @p ewmask to
* pending then the events are cleared and returned. * become pending then the events are cleared and returned.
*
* @param ewmask mask of the event ids that the function should wait for * @param ewmask mask of the event ids that the function should wait for
* @param time the number of ticks before the operation timouts * @param time the number of ticks before the operation timouts
* @return The mask of the served and cleared events. * @return The mask of the served and cleared events.

17
src/chheap.c
View File

@ -63,7 +63,8 @@ static struct {
} heap; } heap;
/** /**
* Initializes the allocator subsystem. * @brief Initializes the allocator subsystem.
*
* @note It is internally invoked, this function should not normally be * @note It is internally invoked, this function should not normally be
* invoked from the user code. * 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. * @brief Allocates a block of memory from the heap by using the first-fit
* The allocated block is guaranteed to be properly aligned for a pointer data * algorithm.
* type. * @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 * @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 * block may be a bit bigger than the requested size for alignment
* and fragmentation reasons. * and fragmentation reasons.
@ -142,7 +145,8 @@ void *chHeapAlloc(size_t size) {
(p)->h_size) (p)->h_size)
/** /**
* Frees a previously allocated memory block. * @brief Frees a previously allocated memory block.
*
* @param p the memory block pointer * @param p the memory block pointer
*/ */
void chHeapFree(void *p) { 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 * @param sizep pointer to a variable that will receive the total fragmented
* free space * free space
* @return The number of fragments in the heap. * @return The number of fragments in the heap.

28
src/chlists.c
View File

@ -25,13 +25,13 @@
#if !defined(CH_OPTIMIZE_SPEED) || defined(__DOXIGEN__) #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 tp the pointer to the thread to be inserted in the list
* @param tqp the pointer to the threads list header * @param tqp the pointer to the threads list header
* @note The insertion is done by scanning the list from the highest priority * @note The insertion is done by scanning the list from the highest priority
* toward the lowest. * 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) { 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 tp the pointer to the thread to be inserted in the list
* @param tqp the pointer to the threads list header * @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) { 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 * @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. * @note This function is @b not an API.
*/ */
Thread *fifo_remove(ThreadsQueue *tqp) { Thread *fifo_remove(ThreadsQueue *tqp) {
Thread *tp = tqp->p_next; 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 * @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. * @note This function is @b not an API.
*/ */
Thread *lifo_remove(ThreadsQueue *tqp) { Thread *lifo_remove(ThreadsQueue *tqp) {
Thread *tp = tqp->p_next; 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 * @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. * @note This function is @b not an API.
*/ */
Thread *dequeue(Thread *tp) { 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 tp the pointer to the thread to be inserted in the list
* @param tlp the pointer to the threads list header * @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) { 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 * @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 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) { Thread *list_remove(ThreadsList *tlp) {

15
src/chmempools.c
View File

@ -27,7 +27,8 @@
#ifdef CH_USE_MEMPOOLS #ifdef CH_USE_MEMPOOLS
/** /**
* Initializes an empty memory pool. * @brief Initializes an empty memory pool.
*
* @param mp pointer to a @p MemoryPool structure * @param mp pointer to a @p MemoryPool structure
* @param size the size of the objects contained in this memory pool * @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 * @param mp pointer to a @p MemoryPool structure
* @return The pointer to the allocated object. * @return The pointer to the allocated object.
* @retval NULL if pool is empty. * @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 * @param mp pointer to a @p MemoryPool structure
* @return The pointer to the allocated object. * @return The pointer to the allocated object.
* @retval NULL if pool is empty. * @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 mp pointer to a @p MemoryPool structure
* @param objp the pointer to the object to be released or added * @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 * @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 mp pointer to a @p MemoryPool structure
* @param objp the pointer to the object to be released or added * @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 * @note the object is assumed to be of the right size for the specified

18
src/chmsg.c
View File

@ -25,8 +25,9 @@
#ifdef CH_USE_MESSAGES #ifdef CH_USE_MESSAGES
/** /**
* Sends a message to the specified thread. The client is stopped until the * @brief Sends a message to the specified thread.
* server executes a @p chMsgRelease() after receiving the message. * @details The sender is stopped until the receiver executes a
* @p chMsgRelease()after receiving the message.
* *
* @param tp the pointer to the thread * @param tp the pointer to the thread
* @param msg the message, it can be a pointer to a complex structure * @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 #ifdef CH_USE_MESSAGES_EVENT
/** /**
* Sends a message to the specified thread and atomically triggers an event. * @brief Sends a message to the specified thread and atomically triggers
* The client is stopped until the server executes a @p chMsgRelease() * an event.
* after receiving the message. * @details The sender is stopped until the receiver executes a
* @p chMsgRelease() after receiving the message.
* *
* @param tp the pointer to the thread * @param tp the pointer to the thread
* @param msg the message, it can be a pointer to a complex structure * @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 #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 * @return The pointer to the message structure. Note, it is always the
* message associated to the thread on the top of the messages queue. * 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 * @return The pointer to the message structure. Note, it is always the
* message associated to the thread on the top of the messages queue. * 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 * @param msg the message returned to the message sender
* @note You can call this function only if there is a message already in the * @note You can call this function only if there is a message already in the

33
src/chmtx.c
View File

@ -27,8 +27,12 @@
#ifdef CH_USE_MUTEXES #ifdef CH_USE_MUTEXES
/** /**
* Initializes s @p Mutex structure. * @brief Initializes s @p Mutex structure.
*
* @param mp pointer to a @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) { 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 * @param mp pointer to the @p Mutex structure
*/ */
void chMtxLock(Mutex *mp) { 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 * @param mp pointer to the @p Mutex structure
* @note This function must be called within a @p chSysLock() / @p chSysUnlock() * @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 * the priority inheritance mechanism because it does not try to enter a sleep
* state on the mutex. * state on the mutex.
*
* @param mp pointer to the @p Mutex structure * @param mp pointer to the @p Mutex structure
* @retval TRUE if the mutex was successfully acquired * @retval TRUE if the mutex was successfully acquired
* @retval FALSE if the lock attempt failed. * @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 * the priority inheritance mechanism because it does not try to enter a sleep
* state on the mutex. * state on the mutex.
* @param mp pointer to the @p Mutex structure * @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. * @return The pointer to the unlocked mutex.
*/ */
Mutex *chMtxUnlock(void) { 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. * @return The pointer to the unlocked mutex.
* @note This function must be called within a @p chSysLock() / @p chSysUnlock() * @note This function must be called within a @p chSysLock() / @p chSysUnlock()
* block. * block.
@ -234,10 +244,11 @@ Mutex *chMtxUnlockS(void) {
} }
/** /**
* Unlocks all the mutexes owned by the invoking thread, this is <b>MUCH MORE</b> * @brief Unlocks all the mutexes owned by the invoking thread.
* efficient than releasing the mutexes one by one and not just because the * @details This function is <b>MUCH MORE</b> efficient than releasing the
* call overhead, this function does not have any overhead related to the * mutexes one by one and not just because the call overhead, this function
* priority inheritance mechanism. * does not have any overhead related to the priority inheritance mechanism
* too.
*/ */
void chMtxUnlockAll(void) { void chMtxUnlockAll(void) {

89
src/chqueues.c
View File

@ -27,8 +27,10 @@
#ifdef CH_USE_QUEUES #ifdef CH_USE_QUEUES
/** /**
* Initializes an input queue. A Semaphore is internally initialized * @brief Initializes an input queue.
* and works as a counter of the bytes contained in the 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 qp pointer to a @p Queue structure
* @param buffer pointer to a memory area allocated as queue buffer * @param buffer pointer to a memory area allocated as queue buffer
* @param size size of the 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 * @brief Resets an input queue.
* resumed. * @details All the data is lost and the waiting threads resumed.
*
* @param qp pointer to a @p Queue structure * @param qp pointer to a @p Queue structure
*/ */
void chIQReset(Queue *qp) { 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 qp pointer to a @p Queue structure
* @param b the byte value to be written * @param b the byte value to be written
* @retval Q_OK if the operation is successful. * @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 * @brief Gets a byte from the input queue.
* calling thread is suspended until a byte arrives in the 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 * @param qp pointer to a @p Queue structure
* @return A byte value from the queue. * @return A byte value from the queue.
* @retval Q_RESET if the queue was reset. * @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) #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 * @brief Gets a byte from the input queue.
* calling thread is suspended until a byte arrives in the queue or the * @details If the queue is empty then the calling thread is suspended until
* specified time expires. * a byte arrives in the queue or the specified time expires.
*
* @param qp pointer to a @p Queue structure * @param qp pointer to a @p Queue structure
* @param time the number of ticks before the operation timouts * @param time the number of ticks before the operation timouts
* @return A byte value from the queue. * @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) */ #endif /* defined(CH_USE_QUEUES_TIMEOUT) && defined(CH_USE_SEMAPHORES_TIMEOUT) */
/** /**
* Reads some data from the input queue into the specified buffer. The function * @brief Reads some data from the input queue into the specified buffer.
* is non-blocking and can return zero if the queue is empty. * @details The function is non-blocking and can return zero if the queue is
* empty.
*
* @param qp pointer to a @p Queue structure * @param qp pointer to a @p Queue structure
* @param buffer the data buffer * @param buffer the data buffer
* @param n the maximum amount of data to be read * @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 * @brief Initializes an output queue.
* and works as a counter of the free bytes in the 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 qp pointer to a @p Queue structure
* @param buffer pointer to a memory area allocated as queue buffer * @param buffer pointer to a memory area allocated as queue buffer
* @param size size of the 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 * @brief Resets an Output Queue.
* resumed. * @details All the data is lost and the waiting threads resumed.
*
* @param qp pointer to a @p Queue structure * @param qp pointer to a @p Queue structure
*/ */
void chOQReset(Queue *qp) { 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 * @brief Inserts a byte in the output queue.
* is suspended until the queue has free space available. * @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 qp pointer to a @p Queue structure
* @param b the byte value to be written * @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 * @param qp pointer to a @p Queue structure
* @return The byte value from the queue. * @return The byte value from the queue.
* @retval Q_EMPTY if the queue is empty. * @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 * @brief Writes some data from the specified buffer into the queue.
* is non-blocking and can return zero if the queue is full. * @details The function is non-blocking and can return zero if the queue is
* full.
*
* @param qp pointer to a @p Queue structure * @param qp pointer to a @p Queue structure
* @param buffer the data buffer * @param buffer the data buffer
* @param n the maximum amount of data to be written * @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 #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 qp pointer to the @p HalfDuplexQueue structure
* @param buffer pointer to a memory area allocated as buffer for the queue * @param buffer pointer to a memory area allocated as buffer for the queue
* @param size the size of the queue buffer * @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 * @brief Reads a byte from the receive queue.
* transmission mode then the invoking thread is suspended. * @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 qp pointer to a @p HalfDuplexQueue structure
* @return The byte value. * @return The byte value.
* @retval Q_RESET if the queue was reset. * @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) #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 * @brief Reads a byte from the receive queue.
* transmission mode then the invoking thread is suspended. * @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 qp pointer to a @p HalfDuplexQueue structure
* @param time the number of ticks before the operation timouts * @param time the number of ticks before the operation timouts
* @return The byte value. * @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) */ #endif /* defined(CH_USE_QUEUES_TIMEOUT) && defined(CH_USE_SEMAPHORES_TIMEOUT) */
/** /**
* Writes a byte into the transmit queue. If the buffer contains unread * @brief Writes a byte into the transmit queue.
* input data then the the buffer is cleared and the queue goes in * @details If the buffer contains unread input data then the the buffer is
* transmission mode. * cleared and the queue goes in transmission mode.
*
* @param qp pointer to a @p HalfDuplexQueue structure * @param qp pointer to a @p HalfDuplexQueue structure
* @param b the byte value to be written * @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 * @param qp pointer to a @p HalfDuplexQueue structure
* @return The byte value. * @return The byte value.
* @retval Q_EMPTY if the transmit queue is empty (not in transmission mode). * @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 * @brief Writes a byte into the receive queue.
* then the byte is lost. * @details If the queue is in transmission mode then the byte is lost.
*
* @param qp pointer to a @p HalfDuplexQueue structure * @param qp pointer to a @p HalfDuplexQueue structure
* @param b the byte value to be written * @param b the byte value to be written
* @retval Q_OK if the operation is successful. * @retval Q_OK if the operation is successful.

36
src/chschd.c
View File

@ -29,7 +29,7 @@ ReadyList rlist;
/** @endcond */ /** @endcond */
/** /**
* Scheduler initialization. * @brief Scheduler initialization.
* @note Internally invoked by the @p chSysInit(). * @note Internally invoked by the @p chSysInit().
*/ */
void chSchInit(void) { 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 * @param tp the Thread to be made ready
* @return The Thread pointer. * @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 * @brief Puts the current thread to sleep into the specified state.
* priority thread becomes running. The threads states are described into * @details The next highest priority thread becomes running. The threads
* @p threads.h * states are described into @p threads.h.
*
* @param newstate the new thread state * @param newstate the new thread state
* @note The function must be called in the system mutex zone. * @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. * @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. * @brief Puts the current thread to sleep into the specified state.
* * @details The next highest priority thread becomes running. The thread put
* Puts the current thread to sleep into the specified state. The next highest * to sleep is awakened after the specified time has elapsed.
* priority thread becomes running. The thread put to sleep is awakened after
* the specified time has elapsed.
* *
* @param newstate the new thread state * @param newstate the new thread state
* @param time the number of ticks before the operation timeouts. the value * @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 ntp the Thread to be made ready
* @param msg message to the awakened thread * @param msg message to the awakened thread
* @note The function must be called in the system mutex zone. * @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. * @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. * @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
* If a thread with a higher priority than the current thread is in the * the ready list then make the higher priority thread running.
* ready list then make the higher priority thread running.
* *
* @note The function must be called in the system mutex zone. * @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 TRUE if there is a thread that should go in running state.
* @retval FALSE if a reschedulation is not required. * @retval FALSE if a reschedulation is not required.

34
src/chsem.c
View File

@ -26,10 +26,13 @@
#ifdef CH_USE_SEMAPHORES #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 sp pointer to a @p Semaphore structure
* @param n initial value of the semaphore counter. Must be non-negative. * @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) { 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 sp pointer to a @p Semaphore structure
* @param n the new value of the semaphore counter. The value 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 * @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 sp pointer to a @p Semaphore structure
* @param n the new value of the semaphore counter. The value 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 * @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 * @param sp pointer to a @p Semaphore structure
* @retval RDY_OK if the semaphore was signaled or not taken. * @retval RDY_OK if the semaphore was signaled or not taken.
* @retval RDY_RESET if the semaphore was reset using @p chSemReset(). * @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 * @param sp pointer to a @p Semaphore structure
* @retval RDY_OK if the semaphore was signaled or not taken. * @retval RDY_OK if the semaphore was signaled or not taken.
* @retval RDY_RESET if the semaphore was reset using @p chSemReset(). * @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 #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 sp pointer to a @p Semaphore structure
* @param time the number of ticks before the operation fails * @param time the number of ticks before the operation fails
* @retval RDY_OK if the semaphore was signaled or not taken. * @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 sp pointer to a @p Semaphore structure
* @param time the number of ticks before the operation fails * @param time the number of ticks before the operation fails
* @retval RDY_OK if the semaphore was signaled or not taken. * @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 */ #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 * @param sp pointer to a @p Semaphore structure
* @note The function is available only if the @p CH_USE_SEMAPHORES * @note The function is available only if the @p CH_USE_SEMAPHORES
* option is enabled in @p chconf.h. * 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 * @param sp pointer to a @p Semaphore structure
* @note The function is available only if the @p CH_USE_SEMAPHORES * @note The function is available only if the @p CH_USE_SEMAPHORES
* option is enabled in @p chconf.h. * option is enabled in @p chconf.h.
@ -192,7 +203,8 @@ void chSemSignalI(Semaphore *sp) {
#ifdef CH_USE_SEMSW #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 sps pointer to a @p Semaphore structure to be signaled
* @param spw pointer to a @p Semaphore structure to be wait on * @param spw pointer to a @p Semaphore structure to be wait on
* @retval RDY_OK if the semaphore was signaled or not taken. * @retval RDY_OK if the semaphore was signaled or not taken.

48
src/chserial.c
View File

@ -26,9 +26,10 @@
#ifdef CH_USE_SERIAL_FULLDUPLEX #ifdef CH_USE_SERIAL_FULLDUPLEX
/** /**
* Initializes a generic full duplex driver. The HW dependent part of the * @brief Initializes a generic full duplex driver.
* initialization has to be performed outside, usually in the hardware * @details The HW dependent part of the initialization has to be performed
* initialization code. * outside, usually in the hardware initialization code.
*
* @param sd pointer to a @p FullDuplexDriver structure * @param sd pointer to a @p FullDuplexDriver structure
* @param ib pointer to a memory area allocated for the Input Queue buffer * @param ib pointer to a memory area allocated for the Input Queue buffer
* @param isize size of 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 * @brief Handles incoming data.
* order to enqueue incoming data and generate the related events. * @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 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
*/ */
@ -66,8 +68,9 @@ void chFDDIncomingDataI(FullDuplexDriver *sd, uint8_t b) {
} }
/** /**
* Must be called from the output interrupt service routine in order to get * @brief Handles outgoing data.
* 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 FullDuplexDriver structure * @param sd pointer to a @p FullDuplexDriver structure
* @return The byte value read from the driver's output queue. * @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. * notify I/O conditions as errors, signals change etc.
*
* @param sd pointer to a @p FullDuplexDriver structure * @param sd pointer to a @p FullDuplexDriver structure
* @param mask condition flags to be added to the mask * @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 * @param sd pointer to a @p FullDuplexDriver structure
* @return The condition flags modified since last time this function was * @return The condition flags modified since last time this function was
* invoked. * invoked.
@ -111,9 +117,10 @@ dflags_t chFDDGetAndClearFlags(FullDuplexDriver *sd) {
#ifdef CH_USE_SERIAL_HALFDUPLEX #ifdef CH_USE_SERIAL_HALFDUPLEX
/** /**
* Initializes a generic half duplex driver. The HW dependent part of the * @brief Initializes a generic half duplex driver.
* initialization has to be performed outside, usually in the hardware * @details The HW dependent part of the initialization has to be performed
* initialization code. * outside, usually in the hardware initialization code.
*
* @param sd pointer to a @p HalfDuplexDriver structure * @param sd pointer to a @p HalfDuplexDriver structure
* @param b pointer to a memory area allocated for the queue buffer * @param b pointer to a memory area allocated for the queue buffer
* @param size the buffer size * @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 * @brief Handles incoming data.
* order to enqueue incoming data and generate the related events. * @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 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
*/ */
@ -147,8 +155,9 @@ void chHDDIncomingDataI(HalfDuplexDriver *sd, uint8_t b) {
} }
/** /**
* Must be called from the output interrupt service routine in order to get * @brief Handles outgoing data.
* the next byte to be transmitted. * @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 * @param sd pointer to a @p HalfDuplexDriver structure
* @return The byte value read from the driver's output queue. * @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. * notify I/O conditions as errors, signals change etc.
*
* @param sd pointer to a @p HalfDuplexDriver structure * @param sd pointer to a @p HalfDuplexDriver structure
* @param mask condition flags to be added to the mask * @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 * @param sd pointer to a @p HalfDuplexDriver structure
* @return The condition flags modified since last time this function was * @return The condition flags modified since last time this function was
* invoked. * invoked.

20
src/chsys.c
View File

@ -27,10 +27,12 @@
static WORKING_AREA(idle_thread_wa, IDLE_THREAD_STACK_SIZE); static WORKING_AREA(idle_thread_wa, IDLE_THREAD_STACK_SIZE);
/** /**
* This function implements the idle thread infinite loop. The function should * @brief This function implements the idle thread infinite loop.
* put the processor in the lowest power mode capable to serve interrupts. * @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 * 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. * thread is executed only if there are no other ready threads in the system.
*
* @param p the thread parameter, unused in this scenario * @param p the thread parameter, unused in this scenario
* @note Implementation should declare this function as a weak symbol in order * @note Implementation should declare this function as a weak symbol in order
* to allow applications to re-implement it. * 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 * @brief ChibiOS/RT initialization.
* instructions stream becomes the main thread. * @details After executing this function the current instructions stream
* becomes the main thread.
*
* @note Interrupts should be still disabled when @p chSysInit() is invoked * @note Interrupts should be still disabled when @p chSysInit() is invoked
* and are internally enabled. * and are internally enabled.
* @note The main thread is created with priority @p NORMALPRIO. * @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. * @brief Handles time ticks for round robin preemption and timer increments.
* Decrements the remaining time quantum of the running thread and preempts * @details Decrements the remaining time quantum of the running thread
* it when the quantum is used up. Increments system time and manages the * and preempts it when the quantum is used up. Increments system time and
* timers. * manages the timers.
* @note The frequency of the timer determines the system tick granularity and, * @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.
*/ */

77
src/chthreads.c
View File

@ -64,9 +64,10 @@ static void memfill(uint8_t *p, uint32_t n, uint8_t v) {
#endif #endif
/** /**
* Initializes a new thread. * @brief Initializes a new thread.
* The new thread is initialized but not inserted in the ready list, the * @details The new thread is initialized but not inserted in the ready list,
* initial state is @p PRSUSPENDED. * the initial state is @p PRSUSPENDED.
*
* @param prio the priority level for the new thread. Usually the threads are * @param prio the priority level for the new thread. Usually the threads are
* created with priority @p NORMALPRIO, priorities * created with priority @p NORMALPRIO, priorities
* can range from @p LOWPRIO to @p HIGHPRIO. * 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. * thread into the working space area.
* @note A thread can terminate by calling @p chThdExit() or by simply * @note A thread can terminate by calling @p chThdExit() or by simply
* returning from its main function. * 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, Thread *chThdInit(void *workspace, size_t wsize,
tprio_t prio, tfunc_t pf, void *arg) { 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 workspace pointer to a working area dedicated to the thread stack
* @param wsize size of the working area. * @param wsize size of the working area.
* @param prio the priority level for the new thread. Usually the threads are * @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) #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 wsize size of the working area to be allocated
* @param prio the priority level for the new thread. Usually the threads are * @param prio the priority level for the new thread. Usually the threads are
* created with priority @p NORMALPRIO, priorities * 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) #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 mp the memory pool
* @param prio the priority level for the new thread. Usually the threads are * @param prio the priority level for the new thread. Usually the threads are
* created with priority @p NORMALPRIO, priorities * 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) */ #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 * @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 * @param tpp pointer to a @p Thread pointer, the @p Thread pointer is set
* to point to the suspended process before it enters the * to point to the suspended process before it enters the
* @p PRSUSPENDED state, it is set to @p NULL after it is resumed. * @p PRSUSPENDED state. The variable pointed by this parameter
* This allows to implement a "test and resume" on the variable * must be set to @p NULL on entry.
* into interrupt handlers. * @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) { void chThdSuspend(Thread **tpp) {
@ -222,14 +231,16 @@ void chThdSuspend(Thread **tpp) {
chDbgAssert(*tpp == NULL, "chthreads.c, chThdSuspend()"); chDbgAssert(*tpp == NULL, "chthreads.c, chThdSuspend()");
*tpp = currp; *tpp = currp;
chSchGoSleepS(PRSUSPENDED); chSchGoSleepS(PRSUSPENDED);
*tpp = NULL;
chSysUnlock(); chSysUnlock();
} }
/** /**
* Resumes a suspended thread. * @brief Resumes a suspended thread.
*
* @param tp the pointer to the thread * @param tp the pointer to the thread
* @return 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) { 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 * @param tp the pointer to the thread
* @note The thread is not termitated but a termination request is added to * @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 * 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 * @param time the delay in system ticks
*/ */
void chThdSleep(systime_t time) { 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 * @brief Suspends the invoking thread until the system time arrives to the
* value. * specified value.
*
* @param time the absolute system time * @param time the absolute system time
*/ */
void chThdSleepUntil(systime_t 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 * @param msg the thread exit code. The code can be retrieved by using
* @p chThdWait(). * @p chThdWait().
@ -299,19 +313,18 @@ void chThdExit(msg_t msg) {
#ifdef CH_USE_WAITEXIT #ifdef CH_USE_WAITEXIT
/** /**
* Blocks the execution of the invoking thread until the specified thread * @brief Blocks the execution of the invoking thread until the specified
* terminates then the exit code is returned. * thread terminates then the exit code is returned.
* The memory used by the exited thread is handled in different ways depending * @details The memory used by the exited thread is handled in different ways
* on the API that spawned the thread: * depending on the API that spawned the thread:
* <ul> * - If the thread was spawned by @p chThdCreateStatic() or by @p chThdInit()
* <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
* then nothing happens and the thread working area is not released or * modified in any way. This is the default, totally static, behavior.
* modified in any way. This is the default, totally static, behavior.</li> * - If the thread was spawned by @p chThdCreateFromHeap() then the working
* <li>If the thread was spawned by @p chThdCreateFromHeap() then the working * area is returned to the system heap.
* area is returned to the system heap.</li> * - If the thread was spawned by @p chThdCreateFromMemoryPool() then the
* <li>If the thread was spawned by @p chThdCreateFromMemoryPool() then the * working area is returned to the owning memory pool.
* working area is returned to the owning memory pool.</li> *
* </ul>
* @param tp the thread pointer * @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 * @note After invoking @p chThdWait() the thread pointer becomes invalid and

17
src/chvt.c
View File

@ -27,7 +27,8 @@
VTList vtlist; VTList vtlist;
/** /**
* Virtual Timers initialization. * @brief Virtual Timers initialization.
*
* @note Internal use only. * @note Internal use only.
*/ */
void chVTInit(void) { 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 vtp the @p VirtualTimer structure pointer
* @param time the number of time ticks, the value zero is not allowed * @param time the number of time ticks, the value zero is not allowed
* @param vtfunc the timer callback function. After invoking the callback * @param vtfunc the timer callback function. After invoking the callback
* the timer is disabled and the structure can be disposed or * the timer is disabled and the structure can be disposed or
* reused. * reused.
* @param par a parameter that will be passed to the callback function * @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 within
* @note The associated function is invoked by an interrupt handler. * the I-Locked state, see @ref system_states.
*/ */
void chVTSetI(VirtualTimer *vtp, systime_t time, vtfunc_t vtfunc, void *par) { void chVTSetI(VirtualTimer *vtp, systime_t time, vtfunc_t vtfunc, void *par) {
VirtualTimer *p; 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 * @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. * @note The timer MUST be active when this function is invoked.
*/ */
void chVTResetI(VirtualTimer *vtp) { 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 start the start of the time window (inclusive)
* @param end the end of the time window (non inclusive) * @param end the end of the time window (non inclusive)
*/ */

52
src/include/sys.h
View File

@ -26,22 +26,24 @@
#define _SYS_H_ #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 * @param msg the message to be printed on the system console
*/ */
#define chSysPuts(msg) port_puts(msg) #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 * unrecoverable error is detected (as example because a programming error in
* the application code that triggers an assertion while in debug mode). * the application code that triggers an assertion while in debug mode).
*/ */
#define chSysHalt() port_halt() #define chSysHalt() port_halt()
/** /**
* Performs a context switch. * @brief Performs a context switch.
* This is the most critical code in any port, this function is responsible * @details This is the most critical code in any port, this function
* for the context switch between 2 threads. * is responsible for the context switch between 2 threads.
*
* @param otp the thread to be switched out * @param otp the thread to be switched out
* @param ntp the thread to be switched in * @param ntp the thread to be switched in
* @note The implementation of this code affects <b>directly</b> the context * @note The implementation of this code affects <b>directly</b> the context
@ -50,9 +52,10 @@
#define chSysSwitchI(otp, ntp) port_switch(otp, ntp) #define chSysSwitchI(otp, ntp) port_switch(otp, ntp)
/** /**
* Raises the system interrupt priority mask to the maximum level. * @brief Raises the system interrupt priority mask to the maximum level.
* All the maskable interrupt sources are disabled regardless their hardware * @details All the maskable interrupt sources are disabled regardless their
* priority. * hardware priority.
*
* @note The implementation is architecture dependent, it may just disable the * @note The implementation is architecture dependent, it may just disable the
* interrupts or be exactly equivalent to @p chSysDisable(). * interrupts or be exactly equivalent to @p chSysDisable().
* @note Do not invoke this API from within a kernel lock. * @note Do not invoke this API from within a kernel lock.
@ -60,9 +63,10 @@
#define chSysDisable() port_disable() #define chSysDisable() port_disable()
/** /**
* Raises the system interrupt priority mask to system level. * @brief Raises the system interrupt priority mask to system level.
* The interrupt sources that should not be able to preempt the kernel are * @details The interrupt sources that should not be able to preempt the kernel
* disabled, interrupt sources with higher priority are still enabled. * are disabled, interrupt sources with higher priority are still enabled.
*
* @note The implementation is architecture dependent, it may just disable the * @note The implementation is architecture dependent, it may just disable the
* interrupts. * interrupts.
* @note Do not invoke this API from within a kernel lock. * @note Do not invoke this API from within a kernel lock.
@ -72,8 +76,9 @@
#define chSysSuspend() port_suspend() #define chSysSuspend() port_suspend()
/** /**
* Lowers the system interrupt priority mask to user level. * @brief Lowers the system interrupt priority mask to user level.
* All the interrupt sources are enabled. * @details All the interrupt sources are enabled.
*
* @note The implementation is architecture dependent, it may just enable the * @note The implementation is architecture dependent, it may just enable the
* interrupts. * interrupts.
* @note Do not invoke this API from within a kernel lock. * @note Do not invoke this API from within a kernel lock.
@ -83,7 +88,8 @@
#define chSysEnable() port_enable() #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 * @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. * a better idea to use the semaphores or mutexes instead.
* @see CH_USE_NESTED_LOCKS * @see CH_USE_NESTED_LOCKS
@ -100,7 +106,8 @@
#endif /* !defined(CH_USE_NESTED_LOCKS) */ #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 * @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. * a better idea to use the semaphores or mutexes instead.
* @see CH_USE_NESTED_LOCKS * @see CH_USE_NESTED_LOCKS
@ -117,7 +124,8 @@
#endif /* !defined(CH_USE_NESTED_LOCKS) */ #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 * @note This API may do nothing on some architectures, it is required because
* on ports that support preemptable interrupt handlers it is required to * on ports that support preemptable interrupt handlers it is required to
* raise the interrupt mask to the same level of the system mutual * raise the interrupt mask to the same level of the system mutual
@ -129,7 +137,8 @@
#define chSysLockI() port_lock_from_isr() #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 * @note This API may do nothing on some architectures, it is required because
* on ports that support preemptable interrupt handlers it is required to * on ports that support preemptable interrupt handlers it is required to
* raise the interrupt mask to the same level of the system mutual * raise the interrupt mask to the same level of the system mutual
@ -141,14 +150,16 @@
#define chSysUnlockI() port_unlock_from_isr() #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 Usually IRQ handlers functions are also declared naked.
* @note On some architectures this macro can be empty. * @note On some architectures this macro can be empty.
*/ */
#define CH_IRQ_PROLOGUE() PORT_IRQ_PROLOGUE() #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 Usually IRQ handlers function are also declared naked.
* @note This macro usually performs the final reschedulation by using * @note This macro usually performs the final reschedulation by using
* @p chSchRescRequiredI() and @p chSchDoRescheduleI(). * @p chSchRescRequiredI() and @p chSchDoRescheduleI().
@ -156,7 +167,8 @@
#define CH_IRQ_EPILOGUE() PORT_IRQ_EPILOGUE() #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 * @note @p id can be a function name or a vector number depending on the
* port implementation. * port implementation.
*/ */

267
src/lib/ch.hpp
View File

@ -30,50 +30,55 @@
namespace chibios_rt { namespace chibios_rt {
/** /**
* Class encapsulating the base system functionalities. * @brief Class encapsulating the base system functionalities.
*/ */
class System { class System {
public: public:
/** /**
* ChibiOS/RT initialization. * @brief ChibiOS/RT initialization.
* The system is initialized, the idle thread is spawned and the current * @details The system is initialized, the idle thread is spawned and the
* instruction flow becomes the main thread with priority @p NORMALPRIO. * current instruction flow becomes the main thread with priority
* @p NORMALPRIO.
*/ */
static void Init(void); static void Init(void);
/** /**
* Disables interrupts. * @brief Kernel lock.
*
* @note On some ports it is faster to invoke chSysLock() directly because * @note On some ports it is faster to invoke chSysLock() directly because
* inlining. * inlining.
*/ */
static void Lock(void); static void Lock(void);
/** /**
* Enables interrupts. * @brief Kernel unlock.
*
* @note On some ports it is faster to invoke chSysUnlock() directly * @note On some ports it is faster to invoke chSysUnlock() directly
* because inlining. * because inlining.
*/ */
static void Unlock(void); 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. * @note the system tick time interval is implementation dependent.
*/ */
static systime_t GetTime(void); static systime_t GetTime(void);
}; };
/** /**
* Timer class. * @brief Timer class.
*/ */
class Timer { class Timer {
public: public:
/** /**
* Embedded @p VirtualTimer structure. * @brief Embedded @p VirtualTimer structure.
*/ */
struct ::VirtualTimer timer; struct ::VirtualTimer timer;
/** /**
* Starts the timer. * @brief Starts the timer.
*
* @param time the time in system ticks * @param time the time in system ticks
* @param vtfunc the timer callback function * @param vtfunc the timer callback function
* @param par the parameter for the 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); 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 It must be called with the interrupts disabled.
* @note The timer MUST be active when this function is invoked. * @note The timer MUST be active when this function is invoked.
*/ */
void Reset(); void Reset();
/** /**
* Returns the timer status. * @brief Returns the timer status.
*
* @retval TRUE The timer is armed. * @retval TRUE The timer is armed.
* @retval FALSE The timer already fired its callback. * @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 * @brief Base class for a ChibiOS/RT thread.
* function @p Main(). * @details The thread body is the virtual function @p Main().
*/ */
class BaseThread { class BaseThread {
public: public:
/** /**
* Pointer to the system thread. * @brief Pointer to the system thread.
*/ */
::Thread *thread_ref; ::Thread *thread_ref;
/** /**
* Thread constructor. * @brief Thread constructor.
* The thread object is initialized and a system thread is started. * @details The thread object is initialized and a system thread is
* started.
*
* @param workspace pointer to the workspace area * @param workspace pointer to the workspace area
* @param wsize size of the workspace area * @param wsize size of the workspace area
* @param prio thread priority * @param prio thread priority
@ -118,53 +127,60 @@ namespace chibios_rt {
BaseThread(void *workspace, size_t wsize, tprio_t prio); BaseThread(void *workspace, size_t wsize, tprio_t prio);
/** /**
* Thread exit. * @brief Thread exit.
*
* @param msg the exit message * @param msg the exit message
*/ */
static void Exit(msg_t msg); static void Exit(msg_t msg);
#ifdef CH_USE_WAITEXIT #ifdef CH_USE_WAITEXIT
/** /**
* Synchronization on Thread exit. * @brief Synchronization on Thread exit.
*
* @return the exit message from the thread * @return the exit message from the thread
*/ */
msg_t Wait(void); msg_t Wait(void);
#endif /* CH_USE_WAITEXIT */ #endif /* CH_USE_WAITEXIT */
/** /**
* Resumes the thread. * @brief Resumes the thread.
* The thread encapsulated into the object is resumed. * @details The thread encapsulated into the object is resumed.
*/ */
void Resume(void); void Resume(void);
/** /**
* Change thread priority. * @brief Changes the thread priority.
*
* @param newprio the new priority level * @param newprio the new priority level
*/ */
static void SetPriority(tprio_t newprio); static void SetPriority(tprio_t newprio);
/** /**
* Requests thread termination. * @brief Requests thread termination.
* A termination flag is pended on the thread, it is thread responsibility * @details A termination flag is pended on the thread, it is thread
* to detect it and exit. * responsibility to detect it and exit.
*/ */
void Terminate(void); 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 * @param n the number of system ticks
*/ */
static void Sleep(systime_t n); 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 * @param time the system time
*/ */
static void SleepUntil(systime_t time); static void SleepUntil(systime_t time);
#ifdef CH_USE_MESSAGES #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 tp the target thread
* @param msg the sent message * @param msg the sent message
* @return The returned message. * @return The returned message.
@ -172,33 +188,38 @@ namespace chibios_rt {
static msg_t SendMessage(::Thread *tp, msg_t msg); 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 * @param msg the sent message
* @return The returned message. * @return The returned message.
*/ */
msg_t SendMessage(msg_t msg); 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. * @return The incoming message.
*/ */
static msg_t WaitMessage(void); static msg_t WaitMessage(void);
/** /**
* Returns an enqueued message or @p NULL. * @brief Returns an enqueued message or @p NULL.
*
* @return The incoming message. * @return The incoming message.
* @retval NULL No incoming message. * @retval NULL No incoming message.
*/ */
static msg_t GetMessage(void); 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 * @param msg the answer message
*/ */
static void ReleaseMessage(msg_t msg); 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 TRUE A message is waiting in queue.
* @retval FALSE A message is not waiting in queue. * @retval FALSE A message is not waiting in queue.
*/ */
@ -206,15 +227,18 @@ namespace chibios_rt {
#endif /* CH_USE_MESSAGES */ #endif /* CH_USE_MESSAGES */
/** /**
* Thread body function. * @brief Thread body function.
*
* @return The exit message. * @return The exit message.
*/ */
virtual msg_t Main(void); virtual msg_t Main(void);
}; };
/** /**
* Enhanced threads template class. This class introduces thread names * @brief Enhanced threads template class.
* and static working area allocation. * @details This class introduces thread names and static working area
* allocation.
*
* @param N the working area size for the thread class * @param N the working area size for the thread class
*/ */
template <int N> template <int N>
@ -224,13 +248,14 @@ namespace chibios_rt {
public: public:
/** /**
* The thread name. * @brief The thread name.
*/ */
const char *name; const char *name;
/** /**
* Full constructor. It allows to set a priority level for the new thread * @brief Full constructor.
* and specify the special option flags. * @details This constructor allows to set a priority level for the new
* thread.
* @param tname the name to be assigned to the thread * @param tname the name to be assigned to the thread
* @param prio the priority 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 * @brief Simplified constructor.
* specifying a name. In is assumed @p NORMALPRIO as initial priority * @details This constructor allows to create a thread by simply
* and no special option flags. * specifying a name. In is assumed @p NORMALPRIO as initial priority.
*
* @param tname the name to be assigned to the thread * @param tname the name to be assigned to the thread
*/ */
EnhancedThread(const char *tname) : EnhancedThread(const char *tname) :
@ -255,30 +281,33 @@ namespace chibios_rt {
#ifdef CH_USE_SEMAPHORES #ifdef CH_USE_SEMAPHORES
/** /**
* Class encapsulating a @p Semaphore. * @brief Class encapsulating a @p Semaphore.
*/ */
class Semaphore { class Semaphore {
public: public:
/** /**
* Embedded @p Semaphore structure. * @brief Embedded @p Semaphore structure.
*/ */
struct ::Semaphore sem; struct ::Semaphore sem;
/** /**
* Semaphore constructor. * @brief Semaphore constructor.
* The embedded @p ::Semaphore structure is initialized. * @details The embedded @p ::Semaphore structure is initialized.
*
* @param n the semaphore counter value, must be greater or equal to zero * @param n the semaphore counter value, must be greater or equal to zero
*/ */
Semaphore(cnt_t n); Semaphore(cnt_t n);
/** /**
* Resets a semaphore. * @brief Resets a semaphore.
* @param n the new semaphore counter value, must be greater or equal to zero *
* @param n the new semaphore counter value, must be greater or equal to zero
*/ */
void Reset(cnt_t n); 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_OK if the semaphore was signaled or not taken.
* @retval RDY_RESET if the semaphore was reset. * @retval RDY_RESET if the semaphore was reset.
*/ */
@ -286,7 +315,8 @@ namespace chibios_rt {
#ifdef CH_USE_SEMAPHORES_TIMEOUT #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 * @param time the number of ticks before the operation fails
* @retval RDY_OK if the semaphore was signaled or not taken. * @retval RDY_OK if the semaphore was signaled or not taken.
* @retval RDY_RESET if the semaphore was reset. * @retval RDY_RESET if the semaphore was reset.
@ -297,14 +327,16 @@ namespace chibios_rt {
#endif /* CH_USE_SEMAPHORES_TIMEOUT */ #endif /* CH_USE_SEMAPHORES_TIMEOUT */
/** /**
* Signal operation on the semaphore. * @brief Signal operation on the semaphore.
* The semaphore is signaled, the next thread in queue, if any, is awakened. * @details The semaphore is signaled, the next thread in queue, if any,
* is awakened.
*/ */
void Signal(void); void Signal(void);
#ifdef CH_USE_SEMSW #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 ssem pointer to a @p Semaphore to be signaled
* @param wsem pointer to a @p Semaphore to be wait on * @param wsem pointer to a @p Semaphore to be wait on
* @retval RDY_OK if the semaphore was signaled or not taken. * @retval RDY_OK if the semaphore was signaled or not taken.
@ -317,82 +349,85 @@ namespace chibios_rt {
#ifdef CH_USE_MUTEXES #ifdef CH_USE_MUTEXES
/** /**
* Class encapsulating a @p Mutex. * @brief Class encapsulating a @p Mutex.
*/ */
class Mutex { class Mutex {
public: public:
/** /**
* Embedded @p Mutex structure. * @brief Embedded @p Mutex structure.
*/ */
struct ::Mutex mutex; struct ::Mutex mutex;
/** /**
* Mutex constructor. * @brief Mutex constructor.
* The embedded @p ::Mutex structure is initialized. * @details The embedded @p ::Mutex structure is initialized.
*/ */
Mutex(void); 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 TRUE if the mutex was successfully acquired
* @retval FALSE if the lock attempt failed. * @retval FALSE if the lock attempt failed.
*/ */
bool TryLock(void); bool TryLock(void);
/** /**
* Locks the mutex. * @brief Locks the mutex.
* Performs a lock operation on the mutex, if the mutex is already locked * @details Performs a lock operation on the mutex, if the mutex is
* then the thread enters the mutex priority queue and waits. * already locked then the thread enters the mutex priority queue and
* waits.
*/ */
void Lock(void); void Lock(void);
/** /**
* Unlocks the mutex. * @brief Unlocks the mutex.
* Performs an unlock operation on the mutex, the next waiting thread, if * @details Performs an unlock operation on the mutex, the next waiting
* any, is resumed and locks the mutex. * thread, if any, is resumed and locks the mutex.
*/ */
static void Unlock(void); static void Unlock(void);
/** /**
* Unlocks all the mutexes owned by the invoking thread. * @brief Unlocks all the mutexes owned by the invoking thread.
* This operation is <b>MUCH MORE</b> efficient than releasing the mutexes * @details This operation is <b>MUCH MORE</b> efficient than releasing
* one by one and not just because the call overhead, this function does not * the mutexes one by one and not just because the call overhead, this
* have any overhead related to the priority inheritance mechanism. * function does not have any overhead related to the priority inheritance
* mechanism.
*/ */
static void UnlockAll(void); static void UnlockAll(void);
}; };
#ifdef CH_USE_CONDVARS #ifdef CH_USE_CONDVARS
/** /**
* Class encapsulating a @p CondVar. * @brief Class encapsulating a @p CondVar.
*/ */
class CondVar { class CondVar {
public: public:
/** /**
* Embedded @p CondVar structure. * @brief Embedded @p CondVar structure.
*/ */
struct ::CondVar condvar; struct ::CondVar condvar;
/** /**
* CondVar constructor. * @brief CondVar constructor.
* The embedded @p ::CondVar structure is initialized. * @details The embedded @p ::CondVar structure is initialized.
*/ */
CondVar(void); CondVar(void);
/** /**
* Signals the CondVar. * @brief Signals the CondVar.
* The next thread waiting on the @p CondVar, if any, is awakened. * @details The next thread waiting on the @p CondVar, if any, is awakened.
*/ */
void Signal(void); void Signal(void);
/** /**
* Broadcasts the CondVar. * @brief Broadcasts the CondVar.
* All the threads waiting on the @p CondVar, if any, are awakened. * @details All the threads waiting on the @p CondVar, if any, are awakened.
*/ */
void Broadcast(void); 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. * @return The wakep mode.
* @retval RDY_OK if the condvar was signaled using chCondSignal(). * @retval RDY_OK if the condvar was signaled using chCondSignal().
* @retval RDY_RESET if the condvar was signaled using chCondBroadcast(). * @retval RDY_RESET if the condvar was signaled using chCondBroadcast().
@ -401,7 +436,8 @@ namespace chibios_rt {
#ifdef CH_USE_CONDVARS_TIMEOUT #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 * @param time the number of ticks before the operation fails
* @return The wakep mode. * @return The wakep mode.
* @retval RDY_OK if the condvar was signaled using chCondSignal(). * @retval RDY_OK if the condvar was signaled using chCondSignal().
@ -417,30 +453,32 @@ namespace chibios_rt {
#ifdef CH_USE_EVENTS #ifdef CH_USE_EVENTS
/** /**
* Class encapsulating an @p EventSource. * @brief Class encapsulating an @p EventSource.
*/ */
class Event { class Event {
public: public:
/** /**
* Embedded @p EventSource structure. * @brief Embedded @p EventSource structure.
*/ */
struct ::EventSource event; struct ::EventSource event;
/** /**
* Event constructor. * @brief Event constructor.
* The embedded @p ::EventSource structure is initialized. * @details The embedded @p ::EventSource structure is initialized.
*/ */
Event(void); 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 elp pointer to the @p EventListener structure
* @param eid numeric identifier assigned to the Event Listener * @param eid numeric identifier assigned to the Event Listener
*/ */
void Register(EventListener *elp, eventid_t eid); 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 elp pointer to the @p EventListener structure
* @param emask the mask of event flags to be pended to the thread when the * @param emask the mask of event flags to be pended to the thread when the
* event source is broadcasted * event source is broadcasted
@ -449,35 +487,40 @@ namespace chibios_rt {
void RegisterMask(EventListener *elp, eventmask_t emask); void RegisterMask(EventListener *elp, eventmask_t emask);
/** /**
* Unregisters a listener. * @brief Unregisters a listener.
* The specified listeners is no more signaled by the event source. * @details The specified listeners is no more signaled by the event
* source.
*
* @param elp the listener to be unregistered * @param elp the listener to be unregistered
*/ */
void Unregister(EventListener *elp); void Unregister(EventListener *elp);
/** /**
* Broadcasts an event. * @brief Broadcasts an event.
* All the listeners registered on the event source are signaled. * @details All the listeners registered on the event source are signaled.
*/ */
void Broadcast(void); 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 * @param mask the events to be cleared
* @return The pending events that were cleared. * @return The pending events that were cleared.
*/ */
static eventmask_t Clear(eventmask_t mask); static eventmask_t Clear(eventmask_t mask);
/** /**
* Makes an events mask pending in the current thread, this is \b much * @brief Makes an events mask pending in the current thread.
* faster than using @p Broadcast(). * @details This functon is @b much faster than using @p Broadcast().
*
* @param mask the events to be pended * @param mask the events to be pended
* @return The current pending events mask. * @return The current pending events mask.
*/ */
static eventmask_t Pend(eventmask_t 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 mask mask of the events to be dispatched
* @param handlers an array of @p evhandler_t. The array must be * @param handlers an array of @p evhandler_t. The array must be
* have indexes from zero up the higher registered event * 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); static void Dispatch(const evhandler_t handlers[], eventmask_t mask);
/** /**
* A pending event among those specified in @p ewmask is selected, cleared and * @brief Waits for a single event.
* its mask returned. * @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, * @param ewmask mask of the events that the function should wait for,
* @p ALL_EVENTS enables all the events * @p ALL_EVENTS enables all the events
* @return The mask of the lowest id served and cleared event. * @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); static eventmask_t WaitOne(eventmask_t ewmask);
/** /**
* Waits for any of the specified events. * @brief Waits for any of the specified events.
* The function waits for any event among those specified in @p ewmask to * @details The function waits for any event among those specified in
* become pending then the events are cleared and returned. * @p ewmask to become pending then the events are cleared and returned.
*
* @param ewmask mask of the events that the function should wait for, * @param ewmask mask of the events that the function should wait for,
* @p ALL_EVENTS enables all the events * @p ALL_EVENTS enables all the events
* @return The mask of the served and cleared events. * @return The mask of the served and cleared events.
@ -510,9 +556,10 @@ namespace chibios_rt {
static eventmask_t WaitAny(eventmask_t ewmask); static eventmask_t WaitAny(eventmask_t ewmask);
/** /**
* Waits for all the specified event flags then clears them. * @brief Waits for all the specified event flags then clears them.
* The function waits for all the events specified in @p ewmask to become * @details The function waits for all the events specified in @p ewmask
* pending then the events are cleared and returned. * to become pending then the events are cleared and returned.
*
* @param ewmask mask of the event ids that the function should wait for * @param ewmask mask of the event ids that the function should wait for
* @return The mask of the served and cleared events. * @return The mask of the served and cleared events.
*/ */
@ -520,9 +567,9 @@ namespace chibios_rt {
#ifdef CH_USE_EVENTS_TIMEOUT #ifdef CH_USE_EVENTS_TIMEOUT
/** /**
* Waits for a single event. * @brief Waits for a single event.
* A pending event among those specified in @p ewmask is selected, cleared * @details A pending event among those specified in @p ewmask is selected,
* and its mask returned. * cleared and its mask returned.
* @param ewmask mask of the events that the function should wait for, * @param ewmask mask of the events that the function should wait for,
* @p ALL_EVENTS enables all the events * @p ALL_EVENTS enables all the events
* @param time the number of ticks before the operation timouts * @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); static eventmask_t WaitOneTimeout(eventmask_t ewmask, systime_t time);
/** /**
* Waits for any of the specified events. * @brief Waits for any of the specified events.
* The function waits for any event among those specified in @p ewmask to * @details The function waits for any event among those specified in
* become pending then the events are cleared and returned. * @p ewmask to become pending then the events are cleared and returned.
*
* @param ewmask mask of the events that the function should wait for, * @param ewmask mask of the events that the function should wait for,
* @p ALL_EVENTS enables all the events * @p ALL_EVENTS enables all the events
* @param time the number of ticks before the operation timouts * @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); static eventmask_t WaitAnyTimeout(eventmask_t ewmask, systime_t time);
/** /**
* Waits for all the specified event flags then clears them. * @brief Waits for all the specified event flags then clears them.
* The function waits for all the events specified in @p ewmask to become * @details The function waits for all the events specified in @p ewmask
* pending then the events are cleared and returned. * to become pending then the events are cleared and returned.
*
* @param ewmask mask of the event ids that the function should wait for * @param ewmask mask of the event ids that the function should wait for
* @param time the number of ticks before the operation timouts * @param time the number of ticks before the operation timouts
* @return The mask of the served and cleared events. * @return The mask of the served and cleared events.

15
src/lib/evtimer.c
View File

@ -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> #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 * @brief Starts the timer
* no effect. * @details If the timer was already running then the function has no effect.
*
* @param etp pointer to an initialized @p EvTimer structure. * @param etp pointer to an initialized @p EvTimer structure.
*/ */
void evtStart(EvTimer *etp) { 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 * @brief Stops the timer.
* no effect. * @details If the timer was already stopped then the function has no effect.
*
* @param etp pointer to an initialized @p EvTimer structure. * @param etp pointer to an initialized @p EvTimer structure.
*/ */
void evtStop(EvTimer *etp) { void evtStop(EvTimer *etp) {

7
src/lib/evtimer.h
View File

@ -18,10 +18,8 @@
*/ */
/** /**
* @file evtimer.h * @addtogroup event_timer
* @{ * @{
* Event Timer definitions.
* @see evtimer.c
*/ */
#ifndef _EVTIMER_H_ #ifndef _EVTIMER_H_
@ -46,7 +44,8 @@ extern "C" {
#endif #endif
/** /**
* Initializes an @p EvTimer structure. * @brief Initializes an @p EvTimer structure.
*
* @param etp the EvTimer structure to be initialized * @param etp the EvTimer structure to be initialized
* @param time the interval in system ticks * @param time the interval in system ticks
*/ */

51
src/templates/chcore.c
View File

@ -32,72 +32,79 @@
*/ */
/** /**
* Port-related initialization code. * @brief Port-related initialization code.
*
* @note This function is usually empty. * @note This function is usually empty.
*/ */
void port_init(void){ void port_init(void){
} }
/** /**
* Kernel-unlock action. Usually this function just disables interrupts but * @brief Kernel-unlock action.
* may perform more actions. * @details Usually this function just disables interrupts but may perform more
* actions.
*/ */
void port_lock(void) { void port_lock(void) {
} }
/** /**
* Kernel-unlock action. Usually this function just disables interrupts but * @brief Kernel-unlock action.
* may perform more actions. * @details Usually this function just disables interrupts but may perform more
* actions.
*/ */
void port_unlock(void) { void port_unlock(void) {
} }
/** /**
* Kernel-lock action from an interrupt handler. This function is invoked * @brief Kernel-lock action from an interrupt handler.
* before invoking I-class APIs from interrupt handlers. The implementation * @details This function is invoked before invoking I-class APIs from
* is architecture dependent, in its simplest form it is void. * interrupt handlers. The implementation is architecture dependent, in its
* simplest form it is void.
*/ */
void port_lock_from_isr(void) { void port_lock_from_isr(void) {
} }
/** /**
* Kernel-unlock action from an interrupt handler. This function is invoked * @brief Kernel-unlock action from an interrupt handler.
* after invoking I-class APIs from interrupt handlers. The implementation * @details This function is invoked after invoking I-class APIs from interrupt
* is architecture dependent, in its simplest form it is void. * handlers. The implementation is architecture dependent, in its simplest form
* it is void.
*/ */
void port_unlock_from_isr(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. * @note Of course non maskable interrupt sources are not included.
*/ */
void port_disable() { 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) { void port_suspend(void) {
} }
/** /**
* Enables all the interrupt sources. * @brief Enables all the interrupt sources.
*/ */
void port_enable(void) { void port_enable(void) {
} }
/** /**
* Enters an architecture-dependent halt mode. The function is meant to return * @brief Enters an architecture-dependent halt mode.
* when an interrupt becomes pending. The simplest implementation is an empty * @details The function is meant to return when an interrupt becomes pending.
* function but this will not take advantage of architecture-specific power * The simplest implementation is an empty function but this will not take
* saving modes. * advantage of architecture-specific power saving modes.
*/ */
void port_wait_for_interrupt(void) { 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 * unrecoverable error is detected (as example because a programming error in
* the application code that triggers an assertion while in debug mode). * 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 otp the thread to be switched out
* @param ntp the thread to be switched in * @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 * @param msg pointer to the message
*/ */
void port_puts(char *msg) { void port_puts(char *msg) {

7
src/templates/chtypes.h
View File

@ -63,9 +63,16 @@ typedef uint32_t systime_t;
/** Counter, recommended fastest signed.*/ /** Counter, recommended fastest signed.*/
typedef int32_t cnt_t; typedef int32_t cnt_t;
/** Inline function modifier. */
#define INLINE inline #define INLINE inline
/** Packed structure modifier (within). */
#define PACK_STRUCT_STRUCT __attribute__((packed)) #define PACK_STRUCT_STRUCT __attribute__((packed))
/** Packed structure modifier (before). */
#define PACK_STRUCT_BEGIN #define PACK_STRUCT_BEGIN
/** Packed structure modifier (after). */
#define PACK_STRUCT_END #define PACK_STRUCT_END
#endif /* _CHTYPES_H_ */ #endif /* _CHTYPES_H_ */