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,
* @a Cond, @a Evt, @a Msg, @a IQ, @a OQ, @a HQ, @a FDD, @a HDD, @a Dbg,
* @a Heap, @a Pool.
*
* @section api_suffixes API Names Suffixes
* The suffix is not present for normal APIs but can be one of
* the following:
* - <b>"I"</b>, I-Class APIs are invokable only from the I-Locked or S-Locked
* states. See @ref system_states.
* - <b>"S"</b>, S-Class APIs are invokable only from the S-Locked state. See
* - <b>None</b>, APIs without any suffix can be invoked only from the user
* code in the <b>Normal</b> state unless differently specified. See
* @ref system_states.
*
* The APIs without suffix can be invoked only from the user code in the Normal
* state unless differently specified.<br>
* - <b>"I"</b>, I-Class APIs are invokable only from the <b>I-Locked</b> or
* <b>S-Locked</b> states. See @ref system_states.
* - <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().
*
* @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
* @{
* C++ wrapper module. This module allows to use the ChibiOS/RT functionalities
* from C++ as classes and objects rather the traditional "C" APIs.
*
* @ingroup utilities_library
* @file ch.hpp C++ wrapper classes and definitions.
* @file ch.cpp C++ wrapper code.
*/
/** @} */
/**
* @defgroup event_timer Events Generator Timer
* @{
* @brief Event Generator Timer.
* @details This timer generates an event at regular intervals. The
* listening threads can use the event to perform time related activities.
* Multiple threads can listen to the same timer.
*
* @ingroup utilities_library
* @file evtimer.c Events Generator Timer code.
* @file evtimer.h Events Generator Timer structures and macros.
*/
/** @} */

63
src/chcond.c
View File

@ -31,8 +31,12 @@
#if defined(CH_USE_CONDVARS) && defined(CH_USE_MUTEXES)
/**
* Initializes s @p CondVar structure.
* @brief Initializes s @p CondVar structure.
*
* @param cp pointer to a @p CondVar structure
* @note This function can be invoked from within an interrupt handler even if
* it is not an I-Class API because it does not touch any critical kernel
* data structure.
*/
void chCondInit(CondVar *cp) {
@ -40,7 +44,7 @@ void chCondInit(CondVar *cp) {
}
/**
* Signals one thread that is waiting on the condition variable.
* @brief Signals one thread that is waiting on the condition variable.
*
* @param cp pointer to the @p CondVar structure
*/
@ -55,11 +59,9 @@ void chCondSignal(CondVar *cp) {
}
/**
* Signals one thread that is waiting on the condition variable.
* @brief Signals one thread that is waiting on the condition variable.
*
* @param cp pointer to the @p CondVar structure
* @note This function must be called within a @p chSysLock() / @p chSysUnlock()
* block.
*/
void chCondSignalI(CondVar *cp) {
@ -68,7 +70,7 @@ void chCondSignalI(CondVar *cp) {
}
/**
* Signals all threads that are waiting on the condition variable.
* @brief Signals all threads that are waiting on the condition variable.
*
* @param cp pointer to the @p CondVar structure
*/
@ -83,10 +85,9 @@ void chCondBroadcast(CondVar *cp) {
}
/**
* Signals all threads that are waiting on the condition variable.
* @brief Signals all threads that are waiting on the condition variable.
*
* @param cp pointer to the @p CondVar structure
* @note This function must be called within a @p chSysLock() / @p chSysUnlock()
*/
void chCondBroadcastI(CondVar *cp) {
@ -98,17 +99,16 @@ void chCondBroadcastI(CondVar *cp) {
}
/**
* Waits on the condition variable releasing the mutex lock.
*
* Releases the mutex, waits on the condition variable, and finally acquires
* the mutex again. This is done atomically.
*
* The thread MUST already have locked the mutex when calling chCondWait().
* @brief Waits on the condition variable releasing the mutex lock.
* @details Releases the mutex, waits on the condition variable, and finally
* acquires the mutex again. This is done atomically.
*
* @param cp pointer to the @p CondVar structure
* @return The wakep mode.
* @retval RDY_OK if the condvar was signaled using chCondSignal().
* @retval RDY_RESET if the condvar was signaled using chCondBroadcast().
* @note The thread MUST already have locked the mutex when calling
* @p chCondWait().
*/
msg_t chCondWait(CondVar *cp) {
msg_t msg;
@ -122,18 +122,16 @@ msg_t chCondWait(CondVar *cp) {
}
/**
* Waits on the condition variable releasing the mutex lock.
*
* Releases the mutex, waits on the condition variable, and finally acquires
* the mutex again. This is done atomically.
*
* The thread MUST already have locked the mutex when calling chCondWait().
* @brief Waits on the condition variable releasing the mutex lock.
* @details Releases the mutex, waits on the condition variable, and finally
* acquires the mutex again. This is done atomically.
*
* @param cp pointer to the @p CondVar structure
* @return The wakep mode.
* @retval RDY_OK if the condvar was signaled using chCondSignal().
* @retval RDY_RESET if the condvar was signaled using chCondBroadcast().
* @note This function must be called within a @p chSysLock() / @p chSysUnlock()
* @note The thread MUST already have locked the mutex when calling
* @p chCondWaitS().
*/
msg_t chCondWaitS(CondVar *cp) {
Mutex *mp;
@ -152,12 +150,9 @@ msg_t chCondWaitS(CondVar *cp) {
#ifdef CH_USE_CONDVARS_TIMEOUT
/**
* Waits on the condition variable releasing the mutex lock.
*
* Releases the mutex, waits on the condition variable, and finally acquires
* the mutex again. This is done atomically.
*
* The thread MUST already have locked the mutex when calling chCondWait().
* @brief Waits on the condition variable releasing the mutex lock.
* @details Releases the mutex, waits on the condition variable, and finally
* acquires the mutex again. This is done atomically.
*
* @param cp pointer to the @p CondVar structure
* @param time the number of ticks before the operation fails
@ -166,6 +161,8 @@ msg_t chCondWaitS(CondVar *cp) {
* @retval RDY_RESET if the condvar was signaled using chCondBroadcast().
* @retval RDY_TIMEOUT if the condvar was not signaled within the specified
* timeout.
* @note The thread MUST already have locked the mutex when calling
* @p chCondWaitTimeout().
*/
msg_t chCondWaitTimeout(CondVar *cp, systime_t time) {
msg_t msg;
@ -179,12 +176,9 @@ msg_t chCondWaitTimeout(CondVar *cp, systime_t time) {
}
/**
* Waits on the condition variable releasing the mutex lock.
*
* Releases the mutex, waits on the condition variable, and finally acquires
* the mutex again. This is done atomically.
*
* The thread MUST already have locked the mutex when calling chCondWait().
* @brief Waits on the condition variable releasing the mutex lock.
* @details Releases the mutex, waits on the condition variable, and finally
* acquires the mutex again. This is done atomically.
*
* @param cp pointer to the @p CondVar structure
* @param time the number of ticks before the operation fails
@ -193,7 +187,8 @@ msg_t chCondWaitTimeout(CondVar *cp, systime_t time) {
* @retval RDY_RESET if the condvar was signaled using chCondBroadcast().
* @retval RDY_TIMEOUT if the condvar was not signaled within the specified
* timeout.
* @note This function must be called within a @p chSysLock() / @p chSysUnlock()
* @note The thread MUST already have locked the mutex when calling
* @p chCondWaitTimeoutS().
*/
msg_t chCondWaitTimeoutS(CondVar *cp, systime_t time) {
Mutex *mp;

11
src/chdebug.c
View File

@ -24,7 +24,7 @@
char *panicmsg;
/**
* Debug subsystem initialization.
* @brief Debug subsystem initialization.
*/
void chDbgInit(void) {
@ -35,7 +35,9 @@ void chDbgInit(void) {
}
/**
* Prints a panic message on the console/debugger and then halts the system.
* @brief Prints a panic message on the console/debugger and then halts the
* system.
*
* @param msg the pointer to the message string
*/
void chDbgPanic(char *msg) {
@ -48,12 +50,13 @@ void chDbgPanic(char *msg) {
#ifdef CH_USE_TRACE
/**
* Public trace buffer.
* @brief Public trace buffer.
*/
TraceBuffer dbgtb;
/**
* Inserts in the circular debug trace buffer a context switch record.
* @brief Inserts in the circular debug trace buffer a context switch record.
*
* @param otp the thread being switched out
* @param ntp the thread to be resumed
*/

66
src/chevents.c
View File

@ -25,7 +25,8 @@
#ifdef CH_USE_EVENTS
/**
* Registers an Event Listener on an Event Source.
* @brief Registers an Event Listener on an Event Source.
*
* @param esp pointer to the @p EventSource structure
* @param elp pointer to the @p EventListener structure
* @param emask the mask of event flags to be pended to the thread when the
@ -45,7 +46,8 @@ void chEvtRegisterMask(EventSource *esp, EventListener *elp, eventmask_t emask)
}
/**
* Unregisters an Event Listener from its Event Source.
* @brief Unregisters an Event Listener from its Event Source.
*
* @param esp pointer to the @p EventSource structure
* @param elp pointer to the @p EventListener structure
* @note If the event listener is not registered on the specified event source
@ -71,7 +73,8 @@ void chEvtUnregister(EventSource *esp, EventListener *elp) {
}
/**
* Clears the pending events specified in the mask.
* @brief Clears the pending events specified in the mask.
*
* @param mask the events to be cleared
* @return The pending events that were cleared.
*/
@ -88,8 +91,9 @@ eventmask_t chEvtClear(eventmask_t mask) {
}
/**
* Makes an events mask pending in the current thread, this is \b much faster than
* using @p chEvtBroadcast().
* @brief Makes an events mask pending in the current thread, this is \b much
* faster than using @p chEvtBroadcast().
*
* @param mask the events to be pended
* @return The current pending events mask.
*/
@ -104,7 +108,9 @@ eventmask_t chEvtPend(eventmask_t mask) {
}
/**
* Signals all the Event Listeners registered on the specified Event Source.
* @brief Signals all the Event Listeners registered on the specified Event
* Source.
*
* @param esp pointer to the @p EventSource structure
*/
void chEvtBroadcast(EventSource *esp) {
@ -118,9 +124,10 @@ void chEvtBroadcast(EventSource *esp) {
}
/**
* Signals all the Event Listeners registered on the specified Event Source.
* @brief Signals all the Event Listeners registered on the specified Event
* Source.
*
* @param esp pointer to the @p EventSource structure
* @note This function does not reschedule.
*/
void chEvtBroadcastI(EventSource *esp) {
EventListener *elp;
@ -141,7 +148,8 @@ void chEvtBroadcastI(EventSource *esp) {
}
/**
* Invokes the event handlers associated with a mask.
* @brief Invokes the event handlers associated with a mask.
*
* @param mask mask of the events to be dispatched
* @param handlers an array of @p evhandler_t. The array must be
* have indexes from zero up the higher registered event
@ -163,8 +171,9 @@ void chEvtDispatch(const evhandler_t handlers[], eventmask_t mask) {
#if defined(CH_OPTIMIZE_SPEED) || !defined(CH_USE_EVENTS_TIMEOUT) || \
defined(__DOXIGEN__)
/**
* A pending event among those specified in @p ewmask is selected, cleared and
* its mask returned.
* @brief A pending event among those specified in @p ewmask is selected,
* cleared and its mask returned.
*
* @param ewmask mask of the events that the function should wait for,
* @p ALL_EVENTS enables all the events
* @return The mask of the lowest id served and cleared event.
@ -192,9 +201,10 @@ eventmask_t chEvtWaitOne(eventmask_t ewmask) {
}
/**
* Waits for any of the specified events.
* The function waits for any event among those specified in @p ewmask to
* become pending then the events are cleared and returned.
* @brief Waits for any of the specified events.
* @details The function waits for any event among those specified in
* @p ewmask to become pending then the events are cleared and returned.
*
* @param ewmask mask of the events that the function should wait for,
* @p ALL_EVENTS enables all the events
* @return The mask of the served and cleared events.
@ -216,9 +226,10 @@ eventmask_t chEvtWaitAny(eventmask_t ewmask) {
}
/**
* Waits for all the specified event flags then clears them.
* The function waits for all the events specified in @p ewmask to become
* pending then the events are cleared and returned.
* @brief Waits for all the specified event flags then clears them.
* @details The function waits for all the events specified in @p ewmask to
* become pending then the events are cleared and returned.
*
* @param ewmask mask of the event ids that the function should wait for
* @return The mask of the served and cleared events.
*/
@ -239,9 +250,10 @@ eventmask_t chEvtWaitAll(eventmask_t ewmask) {
#ifdef CH_USE_EVENTS_TIMEOUT
/**
* Waits for a single event.
* A pending event among those specified in @p ewmask is selected, cleared and
* its mask returned.
* @brief Waits for a single event.
* @details A pending event among those specified in @p ewmask is selected,
* cleared and its mask returned.
*
* @param ewmask mask of the events that the function should wait for,
* @p ALL_EVENTS enables all the events
* @param time the number of ticks before the operation timouts
@ -272,9 +284,10 @@ eventmask_t chEvtWaitOneTimeout(eventmask_t ewmask, systime_t time) {
}
/**
* Waits for any of the specified events.
* The function waits for any event among those specified in @p ewmask to
* become pending then the events are cleared and returned.
* @brief Waits for any of the specified events.
* @details The function waits for any event among those specified in @p ewmask
* to become pending then the events are cleared and returned.
*
* @param ewmask mask of the events that the function should wait for,
* @p ALL_EVENTS enables all the events
* @param time the number of ticks before the operation timouts
@ -299,9 +312,10 @@ eventmask_t chEvtWaitAnyTimeout(eventmask_t ewmask, systime_t time) {
}
/**
* Waits for all the specified event flags then clears them.
* The function waits for all the events specified in @p ewmask to become
* pending then the events are cleared and returned.
* @brief Waits for all the specified event flags then clears them.
* @details The function waits for all the events specified in @p ewmask to
* become pending then the events are cleared and returned.
*
* @param ewmask mask of the event ids that the function should wait for
* @param time the number of ticks before the operation timouts
* @return The mask of the served and cleared events.

17
src/chheap.c
View File

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

28
src/chlists.c
View File

@ -25,13 +25,13 @@
#if !defined(CH_OPTIMIZE_SPEED) || defined(__DOXIGEN__)
/**
* Inserts a thread into a priority ordered queue.
* @brief Inserts a thread into a priority ordered queue.
*
* @param tp the pointer to the thread to be inserted in the list
* @param tqp the pointer to the threads list header
* @note The insertion is done by scanning the list from the highest priority
* toward the lowest.
* @note This function is \b not an API.
* @note This function is @b not an API.
*/
void prio_insert(Thread *tp, ThreadsQueue *tqp) {
@ -48,11 +48,11 @@ void prio_insert(Thread *tp, ThreadsQueue *tqp) {
}
/**
* Inserts a Thread into a queue.
* @brief Inserts a Thread into a queue.
*
* @param tp the pointer to the thread to be inserted in the list
* @param tqp the pointer to the threads list header
* @note This function is \b not an API.
* @note This function is @b not an API.
*/
void queue_insert(Thread *tp, ThreadsQueue *tqp) {
@ -61,11 +61,11 @@ void queue_insert(Thread *tp, ThreadsQueue *tqp) {
}
/**
* Removes the first-out Thread from a queue and returns it.
* @brief Removes the first-out Thread from a queue and returns it.
*
* @param tqp the pointer to the threads list header
* @return The removed thread pointer.
* @note This function is \b not an API.
* @note This function is @b not an API.
*/
Thread *fifo_remove(ThreadsQueue *tqp) {
Thread *tp = tqp->p_next;
@ -75,11 +75,11 @@ Thread *fifo_remove(ThreadsQueue *tqp) {
}
/**
* Removes the last-out Thread from a queue and returns it.
* @brief Removes the last-out Thread from a queue and returns it.
*
* @param tqp the pointer to the threads list header
* @return The removed thread pointer.
* @note This function is \b not an API.
* @note This function is @b not an API.
*/
Thread *lifo_remove(ThreadsQueue *tqp) {
Thread *tp = tqp->p_next;
@ -89,11 +89,11 @@ Thread *lifo_remove(ThreadsQueue *tqp) {
}
/**
* Removes a Thread from a FIFO list and returns it.
* @brief Removes a Thread from a FIFO list and returns it.
*
* @param tp the pointer to the thread to be removed from the list
* @return The removed thread pointer.
* @note This function is \b not an API.
* @note This function is @b not an API.
*/
Thread *dequeue(Thread *tp) {
@ -103,11 +103,11 @@ Thread *dequeue(Thread *tp) {
}
/**
* Pushes a Thread on top of a stack list.
* @brief Pushes a Thread on top of a stack list.
*
* @param tp the pointer to the thread to be inserted in the list
* @param tlp the pointer to the threads list header
* @note This function is \b not an API.
* @note This function is @b not an API.
*/
void list_insert(Thread *tp, ThreadsList *tlp) {
@ -116,12 +116,12 @@ void list_insert(Thread *tp, ThreadsList *tlp) {
}
/**
* Pops a Thread from the top of a stack list and returns it.
* @brief Pops a Thread from the top of a stack list and returns it.
*
* @param tlp the pointer to the threads list header
* @return The removed thread pointer.
* @note The list must be non-empty before calling this function.
* @note This function is \b not an API.
* @note This function is @b not an API.
*/
Thread *list_remove(ThreadsList *tlp) {

15
src/chmempools.c
View File

@ -27,7 +27,8 @@
#ifdef CH_USE_MEMPOOLS
/**
* Initializes an empty memory pool.
* @brief Initializes an empty memory pool.
*
* @param mp pointer to a @p MemoryPool structure
* @param size the size of the objects contained in this memory pool
*/
@ -41,7 +42,8 @@ void chPoolInit(MemoryPool *mp, size_t size) {
}
/**
* Allocates an object from a memory pool.
* @brief Allocates an object from a memory pool.
*
* @param mp pointer to a @p MemoryPool structure
* @return The pointer to the allocated object.
* @retval NULL if pool is empty.
@ -58,7 +60,8 @@ void *chPoolAllocI(MemoryPool *mp) {
}
/**
* Allocates an object from a memory pool.
* @brief Allocates an object from a memory pool.
*
* @param mp pointer to a @p MemoryPool structure
* @return The pointer to the allocated object.
* @retval NULL if pool is empty.
@ -73,7 +76,8 @@ void *chPoolAlloc(MemoryPool *mp) {
}
/**
* Releases (or adds) an object into (to) a memory pool.
* @brief Releases (or adds) an object into (to) a memory pool.
*
* @param mp pointer to a @p MemoryPool structure
* @param objp the pointer to the object to be released or added
* @note the object is assumed to be of the right size for the specified
@ -90,7 +94,8 @@ void chPoolFreeI(MemoryPool *mp, void *objp) {
}
/**
* Releases (or adds) an object into (to) a memory pool.
* @brief Releases (or adds) an object into (to) a memory pool.
*
* @param mp pointer to a @p MemoryPool structure
* @param objp the pointer to the object to be released or added
* @note the object is assumed to be of the right size for the specified

18
src/chmsg.c
View File

@ -25,8 +25,9 @@
#ifdef CH_USE_MESSAGES
/**
* Sends a message to the specified thread. The client is stopped until the
* server executes a @p chMsgRelease() after receiving the message.
* @brief Sends a message to the specified thread.
* @details The sender is stopped until the receiver executes a
* @p chMsgRelease()after receiving the message.
*
* @param tp the pointer to the thread
* @param msg the message, it can be a pointer to a complex structure
@ -54,9 +55,10 @@ msg_t chMsgSend(Thread *tp, msg_t msg) {
#ifdef CH_USE_MESSAGES_EVENT
/**
* Sends a message to the specified thread and atomically triggers an event.
* The client is stopped until the server executes a @p chMsgRelease()
* after receiving the message.
* @brief Sends a message to the specified thread and atomically triggers
* an event.
* @details The sender is stopped until the receiver executes a
* @p chMsgRelease() after receiving the message.
*
* @param tp the pointer to the thread
* @param msg the message, it can be a pointer to a complex structure
@ -88,7 +90,7 @@ msg_t chMsgSendWithEvent(Thread *tp, msg_t msg, EventSource *esp) {
#endif
/**
* Suspends the thread and waits for an incoming message.
* @brief Suspends the thread and waits for an incoming message.
*
* @return The pointer to the message structure. Note, it is always the
* message associated to the thread on the top of the messages queue.
@ -110,7 +112,7 @@ msg_t chMsgWait(void) {
}
/**
* Returns the next message in the queue.
* @brief Returns the next message in the queue.
*
* @return The pointer to the message structure. Note, it is always the
* message associated to the thread on the top of the messages queue.
@ -132,7 +134,7 @@ msg_t chMsgGet(void) {
}
/**
* Releases the thread waiting on top of the messages queue.
* @brief Releases the thread waiting on top of the messages queue.
*
* @param msg the message returned to the message sender
* @note You can call this function only if there is a message already in the

33
src/chmtx.c
View File

@ -27,8 +27,12 @@
#ifdef CH_USE_MUTEXES
/**
* Initializes s @p Mutex structure.
* @brief Initializes s @p Mutex structure.
*
* @param mp pointer to a @p Mutex structure
* @note This function can be invoked from within an interrupt handler even if
* it is not an I-Class API because it does not touch any critical kernel
* data structure.
*/
void chMtxInit(Mutex *mp) {
@ -37,7 +41,8 @@ void chMtxInit(Mutex *mp) {
}
/**
* Locks the specified mutex.
* @brief Locks the specified mutex.
*
* @param mp pointer to the @p Mutex structure
*/
void chMtxLock(Mutex *mp) {
@ -50,7 +55,7 @@ void chMtxLock(Mutex *mp) {
}
/**
* Locks the specified mutex.
* @brief Locks the specified mutex.
*
* @param mp pointer to the @p Mutex structure
* @note This function must be called within a @p chSysLock() / @p chSysUnlock()
@ -110,9 +115,11 @@ void chMtxLockS(Mutex *mp) {
}
/**
* Tries to lock a mutex. This function does not have any overhead related to
* @brief Tries to lock a mutex.
* @details This function does not have any overhead related to
* the priority inheritance mechanism because it does not try to enter a sleep
* state on the mutex.
*
* @param mp pointer to the @p Mutex structure
* @retval TRUE if the mutex was successfully acquired
* @retval FALSE if the lock attempt failed.
@ -129,7 +136,8 @@ bool_t chMtxTryLock(Mutex *mp) {
}
/**
* Tries to lock a mutex. This function does not have any overhead related to
* @brief Tries to lock a mutex.
* @details This function does not have any overhead related to
* the priority inheritance mechanism because it does not try to enter a sleep
* state on the mutex.
* @param mp pointer to the @p Mutex structure
@ -149,7 +157,8 @@ bool_t chMtxTryLockS(Mutex *mp) {
}
/**
* Unlocks the next owned mutex in reverse lock order.
* @brief Unlocks the next owned mutex in reverse lock order.
*
* @return The pointer to the unlocked mutex.
*/
Mutex *chMtxUnlock(void) {
@ -194,7 +203,8 @@ Mutex *chMtxUnlock(void) {
}
/**
* Unlocks the next owned mutex in reverse lock order.
* @brief Unlocks the next owned mutex in reverse lock order.
*
* @return The pointer to the unlocked mutex.
* @note This function must be called within a @p chSysLock() / @p chSysUnlock()
* block.
@ -234,10 +244,11 @@ Mutex *chMtxUnlockS(void) {
}
/**
* Unlocks all the mutexes owned by the invoking thread, this is <b>MUCH MORE</b>
* efficient than releasing the mutexes one by one and not just because the
* call overhead, this function does not have any overhead related to the
* priority inheritance mechanism.
* @brief Unlocks all the mutexes owned by the invoking thread.
* @details This function is <b>MUCH MORE</b> efficient than releasing the
* mutexes one by one and not just because the call overhead, this function
* does not have any overhead related to the priority inheritance mechanism
* too.
*/
void chMtxUnlockAll(void) {

89
src/chqueues.c
View File

@ -27,8 +27,10 @@
#ifdef CH_USE_QUEUES
/**
* Initializes an input queue. A Semaphore is internally initialized
* and works as a counter of the bytes contained in the queue.
* @brief Initializes an input queue.
* @details A Semaphore is internally initialized and works as a counter of
* the bytes contained in the queue.
*
* @param qp pointer to a @p Queue structure
* @param buffer pointer to a memory area allocated as queue buffer
* @param size size of the queue buffer
@ -44,8 +46,9 @@ void chIQInit(Queue *qp, uint8_t *buffer, size_t size, qnotify_t inotify) {
}
/**
* Resets an input queue. All the data is lost and the waiting threads
* resumed.
* @brief Resets an input queue.
* @details All the data is lost and the waiting threads resumed.
*
* @param qp pointer to a @p Queue structure
*/
void chIQReset(Queue *qp) {
@ -59,7 +62,8 @@ void chIQReset(Queue *qp) {
}
/**
* Inserts a byte into an input queue.
* @brief Inserts a byte into an input queue.
*
* @param qp pointer to a @p Queue structure
* @param b the byte value to be written
* @retval Q_OK if the operation is successful.
@ -81,8 +85,10 @@ msg_t chIQPutI(Queue *qp, uint8_t b) {
}
/**
* Gets a byte from the input queue, if the queue is empty then the
* calling thread is suspended until a byte arrives in the queue.
* @brief Gets a byte from the input queue.
* @details If the queue is empty then the calling thread is suspended until
* a byte arrives in the queue.
*
* @param qp pointer to a @p Queue structure
* @return A byte value from the queue.
* @retval Q_RESET if the queue was reset.
@ -110,9 +116,10 @@ msg_t chIQGet(Queue *qp) {
#if defined(CH_USE_QUEUES_TIMEOUT) && defined(CH_USE_SEMAPHORES_TIMEOUT)
/**
* Gets a byte from the input queue, if the queue is empty then the
* calling thread is suspended until a byte arrives in the queue or the
* specified time expires.
* @brief Gets a byte from the input queue.
* @details If the queue is empty then the calling thread is suspended until
* a byte arrives in the queue or the specified time expires.
*
* @param qp pointer to a @p Queue structure
* @param time the number of ticks before the operation timouts
* @return A byte value from the queue.
@ -145,8 +152,10 @@ msg_t chIQGetTimeout(Queue *qp, systime_t time) {
#endif /* defined(CH_USE_QUEUES_TIMEOUT) && defined(CH_USE_SEMAPHORES_TIMEOUT) */
/**
* Reads some data from the input queue into the specified buffer. The function
* is non-blocking and can return zero if the queue is empty.
* @brief Reads some data from the input queue into the specified buffer.
* @details The function is non-blocking and can return zero if the queue is
* empty.
*
* @param qp pointer to a @p Queue structure
* @param buffer the data buffer
* @param n the maximum amount of data to be read
@ -187,8 +196,10 @@ size_t chIQRead(Queue *qp, uint8_t *buffer, size_t n) {
}
/**
* Initializes an output queue. A Semaphore is internally initialized
* and works as a counter of the free bytes in the queue.
* @brief Initializes an output queue.
* @details A Semaphore is internally initialized and works as a counter of the
* free bytes in the queue.
*
* @param qp pointer to a @p Queue structure
* @param buffer pointer to a memory area allocated as queue buffer
* @param size size of the queue buffer
@ -204,8 +215,9 @@ void chOQInit(Queue *qp, uint8_t *buffer, size_t size, qnotify_t onotify) {
}
/**
* Resets an Output Queue. All the data is lost and the waiting threads
* resumed.
* @brief Resets an Output Queue.
* @details All the data is lost and the waiting threads resumed.
*
* @param qp pointer to a @p Queue structure
*/
void chOQReset(Queue *qp) {
@ -219,8 +231,10 @@ void chOQReset(Queue *qp) {
}
/**
* Inserts a byte in the output queue, if the queue is full then the thread
* is suspended until the queue has free space available.
* @brief Inserts a byte in the output queue.
* @details If the queue is full then the thread is suspended until the queue
* has free space available.
*
* @param qp pointer to a @p Queue structure
* @param b the byte value to be written
*/
@ -240,7 +254,8 @@ void chOQPut(Queue *qp, uint8_t b) {
}
/**
* Gets a byte from an output queue.
* @brief Gets a byte from an output queue.
*
* @param qp pointer to a @p Queue structure
* @return The byte value from the queue.
* @retval Q_EMPTY if the queue is empty.
@ -262,8 +277,10 @@ msg_t chOQGetI(Queue *qp) {
}
/**
* Writes some data from the specified buffer into the queue. The function
* is non-blocking and can return zero if the queue is full.
* @brief Writes some data from the specified buffer into the queue.
* @details The function is non-blocking and can return zero if the queue is
* full.
*
* @param qp pointer to a @p Queue structure
* @param buffer the data buffer
* @param n the maximum amount of data to be written
@ -306,7 +323,8 @@ size_t chOQWrite(Queue *qp, uint8_t *buffer, size_t n) {
#ifdef CH_USE_QUEUES_HALFDUPLEX
/**
* Initializes an half duplex queue.
* @brief Initializes an half duplex queue.
*
* @param qp pointer to the @p HalfDuplexQueue structure
* @param buffer pointer to a memory area allocated as buffer for the queue
* @param size the size of the queue buffer
@ -327,8 +345,10 @@ void chHDQInit(HalfDuplexQueue *qp, uint8_t *buffer, size_t size,
}
/**
* Reads a byte from the receive queue, if the queue is empty or is in
* transmission mode then the invoking thread is suspended.
* @brief Reads a byte from the receive queue.
* @details If the queue is empty or is in transmission mode then the invoking
* thread is suspended.
*
* @param qp pointer to a @p HalfDuplexQueue structure
* @return The byte value.
* @retval Q_RESET if the queue was reset.
@ -360,8 +380,10 @@ msg_t chHDQGetReceive(HalfDuplexQueue *qp) {
#if defined(CH_USE_QUEUES_TIMEOUT) && defined(CH_USE_SEMAPHORES_TIMEOUT)
/**
* Reads a byte from the receive queue, if the queue is empty or is in
* transmission mode then the invoking thread is suspended.
* @brief Reads a byte from the receive queue.
* @details If the queue is empty or is in transmission mode then the invoking
* thread is suspended.
*
* @param qp pointer to a @p HalfDuplexQueue structure
* @param time the number of ticks before the operation timouts
* @return The byte value.
@ -397,9 +419,10 @@ msg_t chHDQGetReceiveTimeout(HalfDuplexQueue *qp, systime_t time) {
#endif /* defined(CH_USE_QUEUES_TIMEOUT) && defined(CH_USE_SEMAPHORES_TIMEOUT) */
/**
* Writes a byte into the transmit queue. If the buffer contains unread
* input data then the the buffer is cleared and the queue goes in
* transmission mode.
* @brief Writes a byte into the transmit queue.
* @details If the buffer contains unread input data then the the buffer is
* cleared and the queue goes in transmission mode.
*
* @param qp pointer to a @p HalfDuplexQueue structure
* @param b the byte value to be written
*/
@ -430,7 +453,8 @@ void chHDQPutTransmit(HalfDuplexQueue *qp, uint8_t b) {
}
/**
* Gets a byte from the transmit queue.
* @brief Gets a byte from the transmit queue.
*
* @param qp pointer to a @p HalfDuplexQueue structure
* @return The byte value.
* @retval Q_EMPTY if the transmit queue is empty (not in transmission mode).
@ -451,8 +475,9 @@ msg_t chHDQGetTransmitI(HalfDuplexQueue *qp) {
}
/**
* Writes a byte into the receive queue. If the queue is in transmission mode
* then the byte is lost.
* @brief Writes a byte into the receive queue.
* @details If the queue is in transmission mode then the byte is lost.
*
* @param qp pointer to a @p HalfDuplexQueue structure
* @param b the byte value to be written
* @retval Q_OK if the operation is successful.

36
src/chschd.c
View File

@ -29,7 +29,7 @@ ReadyList rlist;
/** @endcond */
/**
* Scheduler initialization.
* @brief Scheduler initialization.
* @note Internally invoked by the @p chSysInit().
*/
void chSchInit(void) {
@ -42,7 +42,7 @@ void chSchInit(void) {
}
/**
* Inserts a thread in the Ready List.
* @brief Inserts a thread in the Ready List.
*
* @param tp the Thread to be made ready
* @return The Thread pointer.
@ -70,9 +70,10 @@ Thread *chSchReadyI(Thread *tp) {
}
/**
* Puts the current thread to sleep into the specified state, the next highest
* priority thread becomes running. The threads states are described into
* @p threads.h
* @brief Puts the current thread to sleep into the specified state.
* @details The next highest priority thread becomes running. The threads
* states are described into @p threads.h.
*
* @param newstate the new thread state
* @note The function must be called in the system mutex zone.
* @note The function is not meant to be used in the user code directly.
@ -104,11 +105,9 @@ static void wakeup(void *p) {
}
/**
* Puts the current thread to sleep.
*
* Puts the current thread to sleep into the specified state. The next highest
* priority thread becomes running. The thread put to sleep is awakened after
* the specified time has elapsed.
* @brief Puts the current thread to sleep into the specified state.
* @details The next highest priority thread becomes running. The thread put
* to sleep is awakened after the specified time has elapsed.
*
* @param newstate the new thread state
* @param time the number of ticks before the operation timeouts. the value
@ -134,10 +133,10 @@ msg_t chSchGoSleepTimeoutS(tstate_t newstate, systime_t time) {
}
/**
* Wakes up a thread.
* @brief Wakes up a thread.
* @details The thread is inserted into the ready list or immediately made
* running depending on its relative priority compared to the current thread.
*
* The thread is inserted into the ready list or immediately made running
* depending on its relative priority compared to the current thread.
* @param ntp the Thread to be made ready
* @param msg message to the awakened thread
* @note The function must be called in the system mutex zone.
@ -170,7 +169,7 @@ void chSchWakeupS(Thread *ntp, msg_t msg) {
}
/**
* Switch to the first thread on the runnable queue.
* @brief Switches to the first thread on the runnable queue.
*
* @note It is intended to be called if @p chSchRescRequiredI() evaluates to @p TRUE.
*/
@ -190,10 +189,9 @@ void chSchDoRescheduleI(void) {
}
/**
* Reschedule only if a higher priority thread is runnable.
*
* If a thread with a higher priority than the current thread is in the
* ready list then make the higher priority thread running.
* @brief Performs a reschedulation if a higher priority thread is runnable.
* @details If a thread with a higher priority than the current thread is in
* the ready list then make the higher priority thread running.
*
* @note The function must be called in the system mutex zone.
*/
@ -205,7 +203,7 @@ void chSchRescheduleS(void) {
}
/**
* Evaluates if rescheduling is required.
* @brief Evaluates if a reschedulation is required.
*
* @retval TRUE if there is a thread that should go in running state.
* @retval FALSE if a reschedulation is not required.

34
src/chsem.c
View File

@ -26,10 +26,13 @@
#ifdef CH_USE_SEMAPHORES
/**
* Initializes a semaphore with the specified counter value.
* @brief Initializes a semaphore with the specified counter value.
*
* @param sp pointer to a @p Semaphore structure
* @param n initial value of the semaphore counter. Must be non-negative.
* @note Can be called with interrupts disabled or enabled.
* @note This function can be invoked from within an interrupt handler even if
* it is not an I-Class API because it does not touch any critical kernel
* data structure.
*/
void chSemInit(Semaphore *sp, cnt_t n) {
@ -39,7 +42,8 @@ void chSemInit(Semaphore *sp, cnt_t n) {
}
/**
* Performs a reset operation on the semaphore.
* @brief Performs a reset operation on the semaphore.
*
* @param sp pointer to a @p Semaphore structure
* @param n the new value of the semaphore counter. The value must be non-negative.
* @note The released threads can recognize they were waked up by a reset
@ -57,7 +61,8 @@ void chSemReset(Semaphore *sp, cnt_t n) {
}
/**
* Performs a reset operation on the semaphore.
* @brief Performs a reset operation on the semaphore.
*
* @param sp pointer to a @p Semaphore structure
* @param n the new value of the semaphore counter. The value must be non-negative.
* @note The released threads can recognize they were waked up by a reset
@ -76,7 +81,8 @@ void chSemResetI(Semaphore *sp, cnt_t n) {
}
/**
* Performs a wait operation on a semaphore.
* @brief Performs a wait operation on a semaphore.
*
* @param sp pointer to a @p Semaphore structure
* @retval RDY_OK if the semaphore was signaled or not taken.
* @retval RDY_RESET if the semaphore was reset using @p chSemReset().
@ -93,7 +99,8 @@ msg_t chSemWait(Semaphore *sp) {
}
/**
* Performs a wait operation on a semaphore.
* @brief Performs a wait operation on a semaphore.
*
* @param sp pointer to a @p Semaphore structure
* @retval RDY_OK if the semaphore was signaled or not taken.
* @retval RDY_RESET if the semaphore was reset using @p chSemReset().
@ -113,7 +120,8 @@ msg_t chSemWaitS(Semaphore *sp) {
#ifdef CH_USE_SEMAPHORES_TIMEOUT
/**
* Performs a wait operation on a semaphore with timeout specification.
* @brief Performs a wait operation on a semaphore with timeout specification.
*
* @param sp pointer to a @p Semaphore structure
* @param time the number of ticks before the operation fails
* @retval RDY_OK if the semaphore was signaled or not taken.
@ -135,7 +143,8 @@ msg_t chSemWaitTimeout(Semaphore *sp, systime_t time) {
}
/**
* Performs a wait operation on a semaphore with timeout specification.
* @brief Performs a wait operation on a semaphore with timeout specification.
*
* @param sp pointer to a @p Semaphore structure
* @param time the number of ticks before the operation fails
* @retval RDY_OK if the semaphore was signaled or not taken.
@ -157,7 +166,8 @@ msg_t chSemWaitTimeoutS(Semaphore *sp, systime_t time) {
#endif /* CH_USE_SEMAPHORES_TIMEOUT */
/**
* Performs a signal operation on a semaphore.
* @brief Performs a signal operation on a semaphore.
*
* @param sp pointer to a @p Semaphore structure
* @note The function is available only if the @p CH_USE_SEMAPHORES
* option is enabled in @p chconf.h.
@ -173,7 +183,8 @@ void chSemSignal(Semaphore *sp) {
}
/**
* Performs a signal operation on a semaphore.
* @brief Performs a signal operation on a semaphore.
*
* @param sp pointer to a @p Semaphore structure
* @note The function is available only if the @p CH_USE_SEMAPHORES
* option is enabled in @p chconf.h.
@ -192,7 +203,8 @@ void chSemSignalI(Semaphore *sp) {
#ifdef CH_USE_SEMSW
/**
* Performs atomic signal and wait operations on two semaphores.
* @brief Performs atomic signal and wait operations on two semaphores.
*
* @param sps pointer to a @p Semaphore structure to be signaled
* @param spw pointer to a @p Semaphore structure to be wait on
* @retval RDY_OK if the semaphore was signaled or not taken.

48
src/chserial.c
View File

@ -26,9 +26,10 @@
#ifdef CH_USE_SERIAL_FULLDUPLEX
/**
* Initializes a generic full duplex driver. The HW dependent part of the
* initialization has to be performed outside, usually in the hardware
* initialization code.
* @brief Initializes a generic full duplex driver.
* @details The HW dependent part of the initialization has to be performed
* outside, usually in the hardware initialization code.
*
* @param sd pointer to a @p FullDuplexDriver structure
* @param ib pointer to a memory area allocated for the Input Queue buffer
* @param isize size of the Input Queue buffer
@ -52,8 +53,9 @@ void chFDDInit(FullDuplexDriver *sd,
}
/**
* This function must be called from the input interrupt service routine in
* order to enqueue incoming data and generate the related events.
* @brief Handles incoming data.
* @details This function must be called from the input interrupt service
* routine in order to enqueue incoming data and generate the related events.
* @param sd pointer to a @p FullDuplexDriver structure
* @param b the byte to be written in the driver's Input Queue
*/
@ -66,8 +68,9 @@ void chFDDIncomingDataI(FullDuplexDriver *sd, uint8_t b) {
}
/**
* Must be called from the output interrupt service routine in order to get
* the next byte to be transmitted.
* @brief Handles outgoing data.
* @details Must be called from the output interrupt service routine in order
* to get the next byte to be transmitted.
*
* @param sd pointer to a @p FullDuplexDriver structure
* @return The byte value read from the driver's output queue.
@ -83,8 +86,10 @@ msg_t chFDDRequestDataI(FullDuplexDriver *sd) {
}
/**
* Must be called from the I/O interrupt service routine in order to
* @brief Handles communication events/errors.
* @details Must be called from the I/O interrupt service routine in order to
* notify I/O conditions as errors, signals change etc.
*
* @param sd pointer to a @p FullDuplexDriver structure
* @param mask condition flags to be added to the mask
*/
@ -95,7 +100,8 @@ void chFDDAddFlagsI(FullDuplexDriver *sd, dflags_t mask) {
}
/**
* This function returns and clears the errors mask associated to the driver.
* @brief Returns and clears the errors mask associated to the driver.
*
* @param sd pointer to a @p FullDuplexDriver structure
* @return The condition flags modified since last time this function was
* invoked.
@ -111,9 +117,10 @@ dflags_t chFDDGetAndClearFlags(FullDuplexDriver *sd) {
#ifdef CH_USE_SERIAL_HALFDUPLEX
/**
* Initializes a generic half duplex driver. The HW dependent part of the
* initialization has to be performed outside, usually in the hardware
* initialization code.
* @brief Initializes a generic half duplex driver.
* @details The HW dependent part of the initialization has to be performed
* outside, usually in the hardware initialization code.
*
* @param sd pointer to a @p HalfDuplexDriver structure
* @param b pointer to a memory area allocated for the queue buffer
* @param size the buffer size
@ -133,8 +140,9 @@ void chHDDInit(HalfDuplexDriver *sd, uint8_t *b, size_t size,
}
/**
* This function must be called from the input interrupt service routine in
* order to enqueue incoming data and generate the related events.
* @brief Handles incoming data.
* @details This function must be called from the input interrupt service
* routine in order to enqueue incoming data and generate the related events.
* @param sd pointer to a @p FullDuplexDriver structure
* @param b the byte to be written in the driver's input queue
*/
@ -147,8 +155,9 @@ void chHDDIncomingDataI(HalfDuplexDriver *sd, uint8_t b) {
}
/**
* Must be called from the output interrupt service routine in order to get
* the next byte to be transmitted.
* @brief Handles outgoing data.
* @brief Must be called from the output interrupt service routine in order
* to get the next byte to be transmitted.
*
* @param sd pointer to a @p HalfDuplexDriver structure
* @return The byte value read from the driver's output queue.
@ -164,8 +173,10 @@ msg_t chHDDRequestDataI(HalfDuplexDriver *sd) {
}
/**
* Must be called from the I/O interrupt service routine in order to
* @brief Handles communication events/errors.
* @details Must be called from the I/O interrupt service routine in order to
* notify I/O conditions as errors, signals change etc.
*
* @param sd pointer to a @p HalfDuplexDriver structure
* @param mask condition flags to be added to the mask
*/
@ -176,7 +187,8 @@ void chHDDAddFlagsI(HalfDuplexDriver *sd, dflags_t mask) {
}
/**
* This function returns and clears the errors mask associated to the driver.
* @brief Returns and clears the errors mask associated to the driver.
*
* @param sd pointer to a @p HalfDuplexDriver structure
* @return The condition flags modified since last time this function was
* invoked.

20
src/chsys.c
View File

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

77
src/chthreads.c
View File

@ -64,9 +64,10 @@ static void memfill(uint8_t *p, uint32_t n, uint8_t v) {
#endif
/**
* Initializes a new thread.
* The new thread is initialized but not inserted in the ready list, the
* initial state is @p PRSUSPENDED.
* @brief Initializes a new thread.
* @details The new thread is initialized but not inserted in the ready list,
* the initial state is @p PRSUSPENDED.
*
* @param prio the priority level for the new thread. Usually the threads are
* created with priority @p NORMALPRIO, priorities
* can range from @p LOWPRIO to @p HIGHPRIO.
@ -78,7 +79,9 @@ static void memfill(uint8_t *p, uint32_t n, uint8_t v) {
* thread into the working space area.
* @note A thread can terminate by calling @p chThdExit() or by simply
* returning from its main function.
* @note This function can be invoked from within an interrupt handler.
* @note This function can be invoked from within an interrupt handler even if
* it is not an I-Class API because it does not touch any critical kernel
* data structure.
*/
Thread *chThdInit(void *workspace, size_t wsize,
tprio_t prio, tfunc_t pf, void *arg) {
@ -96,7 +99,8 @@ Thread *chThdInit(void *workspace, size_t wsize,
}
/**
* Creates a new thread into a static memory area.
* @brief Creates a new thread into a static memory area.
*
* @param workspace pointer to a working area dedicated to the thread stack
* @param wsize size of the working area.
* @param prio the priority level for the new thread. Usually the threads are
@ -117,7 +121,8 @@ Thread *chThdCreateStatic(void *workspace, size_t wsize,
#if defined(CH_USE_DYNAMIC) && defined(CH_USE_WAITEXIT) && defined(CH_USE_HEAP)
/**
* Creates a new thread allocating the memory from the heap.
* @brief Creates a new thread allocating the memory from the heap.
*
* @param wsize size of the working area to be allocated
* @param prio the priority level for the new thread. Usually the threads are
* created with priority @p NORMALPRIO, priorities
@ -149,7 +154,9 @@ Thread *chThdCreateFromHeap(size_t wsize, tprio_t prio,
#if defined(CH_USE_DYNAMIC) && defined(CH_USE_WAITEXIT) && defined(CH_USE_MEMPOOLS)
/**
* Creates a new thread allocating the memory from the specified Memory Pool.
* @brief Creates a new thread allocating the memory from the specified Memory
* Pool.
*
* @param mp the memory pool
* @param prio the priority level for the new thread. Usually the threads are
* created with priority @p NORMALPRIO, priorities
@ -182,7 +189,7 @@ Thread *chThdCreateFromMemoryPool(MemoryPool *mp, tprio_t prio,
#endif /* defined(CH_USE_DYNAMIC) && defined(CH_USE_WAITEXIT) && defined(CH_USE_MEMPOOLS) */
/**
* Changes the running thread priority, reschedules if necessary.
* @brief Changes the running thread priority then reschedules if necessary.
*
* @param newprio the new priority of the running thread
*/
@ -208,13 +215,15 @@ void chThdSetPriority(tprio_t newprio) {
}
/**
* Suspends the invoking thread.
* @brief Suspends the invoking thread.
*
* @param tpp pointer to a @p Thread pointer, the @p Thread pointer is set
* to point to the suspended process before it enters the
* @p PRSUSPENDED state, it is set to @p NULL after it is resumed.
* This allows to implement a "test and resume" on the variable
* into interrupt handlers.
* @p PRSUSPENDED state. The variable pointed by this parameter
* must be set to @p NULL on entry.
* @note The resume operation is meant to be executed into an interrupt or timer
* handler. The handler is also responsible to clear the variable pointed
* by @p tpp after invoking @p chThdResumeI().
*/
void chThdSuspend(Thread **tpp) {
@ -222,14 +231,16 @@ void chThdSuspend(Thread **tpp) {
chDbgAssert(*tpp == NULL, "chthreads.c, chThdSuspend()");
*tpp = currp;
chSchGoSleepS(PRSUSPENDED);
*tpp = NULL;
chSysUnlock();
}
/**
* Resumes a suspended thread.
* @brief Resumes a suspended thread.
*
* @param tp the pointer to the thread
* @return The pointer to the thread.
* @note This call is supposed to resume threads created with @p chThdInit().
* It should not be used on threads suspended using @p chThdSuspend().
*/
Thread *chThdResume(Thread *tp) {
@ -241,7 +252,8 @@ Thread *chThdResume(Thread *tp) {
}
/**
* Requests a thread termination.
* @brief Requests a thread termination.
*
* @param tp the pointer to the thread
* @note The thread is not termitated but a termination request is added to
* its @p p_flags field. The thread can read this status by
@ -255,7 +267,8 @@ void chThdTerminate(Thread *tp) {
}
/**
* Suspends the invoking thread for the specified time.
* @brief Suspends the invoking thread for the specified time.
*
* @param time the delay in system ticks
*/
void chThdSleep(systime_t time) {
@ -266,8 +279,9 @@ void chThdSleep(systime_t time) {
}
/**
* Suspends the invoking thread until the system time arrives to the specified
* value.
* @brief Suspends the invoking thread until the system time arrives to the
* specified value.
*
* @param time the absolute system time
*/
void chThdSleepUntil(systime_t time) {
@ -279,7 +293,7 @@ void chThdSleepUntil(systime_t time) {
}
/**
* Terminates the current thread by specifying an exit status code.
* @brief Terminates the current thread by specifying an exit status code.
*
* @param msg the thread exit code. The code can be retrieved by using
* @p chThdWait().
@ -299,19 +313,18 @@ void chThdExit(msg_t msg) {
#ifdef CH_USE_WAITEXIT
/**
* Blocks the execution of the invoking thread until the specified thread
* terminates then the exit code is returned.
* The memory used by the exited thread is handled in different ways depending
* on the API that spawned the thread:
* <ul>
* <li>If the thread was spawned by @p chThdCreateStatic() or by @p chThdInit()
* then nothing happens and the thread working area is not released or
* modified in any way. This is the default, totally static, behavior.</li>
* <li>If the thread was spawned by @p chThdCreateFromHeap() then the working
* area is returned to the system heap.</li>
* <li>If the thread was spawned by @p chThdCreateFromMemoryPool() then the
* working area is returned to the owning memory pool.</li>
* </ul>
* @brief Blocks the execution of the invoking thread until the specified
* thread terminates then the exit code is returned.
* @details The memory used by the exited thread is handled in different ways
* depending on the API that spawned the thread:
* - If the thread was spawned by @p chThdCreateStatic() or by @p chThdInit()
* then nothing happens and the thread working area is not released or
* modified in any way. This is the default, totally static, behavior.
* - If the thread was spawned by @p chThdCreateFromHeap() then the working
* area is returned to the system heap.
* - If the thread was spawned by @p chThdCreateFromMemoryPool() then the
* working area is returned to the owning memory pool.
*
* @param tp the thread pointer
* @return The exit code from the terminated thread
* @note After invoking @p chThdWait() the thread pointer becomes invalid and

17
src/chvt.c
View File

@ -27,7 +27,8 @@
VTList vtlist;
/**
* Virtual Timers initialization.
* @brief Virtual Timers initialization.
*
* @note Internal use only.
*/
void chVTInit(void) {
@ -38,15 +39,16 @@ void chVTInit(void) {
}
/**
* Enables a virtual timer.
* @brief Enables a virtual timer.
*
* @param vtp the @p VirtualTimer structure pointer
* @param time the number of time ticks, the value zero is not allowed
* @param vtfunc the timer callback function. After invoking the callback
* the timer is disabled and the structure can be disposed or
* reused.
* @param par a parameter that will be passed to the callback function
* @note Must be called with the interrupts disabled.
* @note The associated function is invoked by an interrupt handler.
* @note The associated function is invoked by an interrupt handler within
* the I-Locked state, see @ref system_states.
*/
void chVTSetI(VirtualTimer *vtp, systime_t time, vtfunc_t vtfunc, void *par) {
VirtualTimer *p;
@ -69,9 +71,9 @@ void chVTSetI(VirtualTimer *vtp, systime_t time, vtfunc_t vtfunc, void *par) {
}
/**
* Disables a Virtual Timer.
* @brief Disables a Virtual Timer.
*
* @param vtp the @p VirtualTimer structure pointer
* @note It must be called with the interrupts disabled.
* @note The timer MUST be active when this function is invoked.
*/
void chVTResetI(VirtualTimer *vtp) {
@ -84,7 +86,8 @@ void chVTResetI(VirtualTimer *vtp) {
}
/**
* Checks if the current system time is within the specified time window.
* @brief Checks if the current system time is within the specified time window.
*
* @param start the start of the time window (inclusive)
* @param end the end of the time window (non inclusive)
*/

52
src/include/sys.h
View File

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

267
src/lib/ch.hpp
View File

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

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>
@ -37,8 +34,9 @@ static void tmrcb(void *p) {
}
/**
* Starts the timer, if the timer was already running then the function has
* no effect.
* @brief Starts the timer
* @details If the timer was already running then the function has no effect.
*
* @param etp pointer to an initialized @p EvTimer structure.
*/
void evtStart(EvTimer *etp) {
@ -52,8 +50,9 @@ void evtStart(EvTimer *etp) {
}
/**
* Stops the timer, if the timer was already stopped then the function has
* no effect.
* @brief Stops the timer.
* @details If the timer was already stopped then the function has no effect.
*
* @param etp pointer to an initialized @p EvTimer structure.
*/
void evtStop(EvTimer *etp) {

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_
@ -46,7 +44,8 @@ extern "C" {
#endif
/**
* Initializes an @p EvTimer structure.
* @brief Initializes an @p EvTimer structure.
*
* @param etp the EvTimer structure to be initialized
* @param time the interval in system ticks
*/

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.
*/
void port_init(void){
}
/**
* Kernel-unlock action. Usually this function just disables interrupts but
* may perform more actions.
* @brief Kernel-unlock action.
* @details Usually this function just disables interrupts but may perform more
* actions.
*/
void port_lock(void) {
}
/**
* Kernel-unlock action. Usually this function just disables interrupts but
* may perform more actions.
* @brief Kernel-unlock action.
* @details Usually this function just disables interrupts but may perform more
* actions.
*/
void port_unlock(void) {
}
/**
* Kernel-lock action from an interrupt handler. This function is invoked
* before invoking I-class APIs from interrupt handlers. The implementation
* is architecture dependent, in its simplest form it is void.
* @brief Kernel-lock action from an interrupt handler.
* @details This function is invoked before invoking I-class APIs from
* interrupt handlers. The implementation is architecture dependent, in its
* simplest form it is void.
*/
void port_lock_from_isr(void) {
}
/**
* Kernel-unlock action from an interrupt handler. This function is invoked
* after invoking I-class APIs from interrupt handlers. The implementation
* is architecture dependent, in its simplest form it is void.
* @brief Kernel-unlock action from an interrupt handler.
* @details This function is invoked after invoking I-class APIs from interrupt
* handlers. The implementation is architecture dependent, in its simplest form
* it is void.
*/
void port_unlock_from_isr(void) {
}
/**
* Disables all the interrupt sources.
* @brief Disables all the interrupt sources.
*
* @note Of course non maskable interrupt sources are not included.
*/
void port_disable() {
}
/**
* Disables the interrupt sources that are not supposed to preempt the kernel.
* @brief Disables the interrupt sources that are not supposed to preempt the kernel.
*/
void port_suspend(void) {
}
/**
* Enables all the interrupt sources.
* @brief Enables all the interrupt sources.
*/
void port_enable(void) {
}
/**
* Enters an architecture-dependent halt mode. The function is meant to return
* when an interrupt becomes pending. The simplest implementation is an empty
* function but this will not take advantage of architecture-specific power
* saving modes.
* @brief Enters an architecture-dependent halt mode.
* @details The function is meant to return when an interrupt becomes pending.
* The simplest implementation is an empty function but this will not take
* advantage of architecture-specific power saving modes.
*/
void port_wait_for_interrupt(void) {
}
/**
* Halts the system. This function is invoked by the operating system when an
* @brief Halts the system.
* @details This function is invoked by the operating system when an
* unrecoverable error is detected (as example because a programming error in
* the application code that triggers an assertion while in debug mode).
*/
@ -109,7 +116,8 @@ void port_halt(void) {
}
/**
* Performs a context switch between two threads.
* @brief Performs a context switch between two threads.
*
* @param otp the thread to be switched out
* @param ntp the thread to be switched in
*/
@ -117,7 +125,8 @@ void port_switch(Thread *otp, Thread *ntp) {
}
/**
* Prints a message on the system console.
* @brief Prints a message on the system console.
*
* @param msg pointer to the message
*/
void port_puts(char *msg) {

7
src/templates/chtypes.h
View File

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