zcy
/
tinySA
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Reformatted doxygen tags into the kernel sources to make them more readable. 

git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1567 35acf78f-673a-0410-8e92-d51de3d6d3f4
master
gdisirio 2010-02-06 10:55:53 +00:00
parent 6f7c30adff
commit f17db1931e
21 changed files with 817 additions and 828 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

17
os/kernel/include/ch.h
View File

@ -18,8 +18,11 @@
*/
/**
* @file ch.h
* @brief ChibiOS/RT main include file, it includes everything else.
* @file ch.h
* @brief ChibiOS/RT main include file.
* @details This header includes all the required kernel headers so it is the
* only kernel header you usually want to include in your application.
*
* @addtogroup kernel_info
* @{
*/
@ -28,27 +31,27 @@
#define _CH_H_
/**
* ChibiOS/RT identification macro.
* @brief ChibiOS/RT identification macro.
*/
#define _CHIBIOS_RT_
/**
* Kernel version string.
* @brief Kernel version string.
*/
#define CH_KERNEL_VERSION "1.5.1unstable"
/**
* Kernel version major number.
* @brief Kernel version major number.
*/
#define CH_KERNEL_MAJOR 1
/**
* Kernel version minor number.
* @brief Kernel version minor number.
*/
#define CH_KERNEL_MINOR 5
/**
* Kernel version patch number.
* @brief Kernel version patch number.
*/
#define CH_KERNEL_PATCH 1

5
os/kernel/include/channels.h
View File

@ -18,8 +18,9 @@
*/
/**
* @file channels.h
* @brief I/O channels.
* @file channels.h
* @brief I/O channels.
*
* @addtogroup io_channels
* @{
*/

22
os/kernel/include/events.h
View File

@ -109,7 +109,9 @@ typedef void (*evhandler_t)(eventid_t);
#ifdef __cplusplus
extern "C" {
#endif
void chEvtRegisterMask(EventSource *esp, EventListener *elp, eventmask_t emask);
void chEvtRegisterMask(EventSource *esp,
EventListener *elp,
eventmask_t mask);
void chEvtUnregister(EventSource *esp, EventListener *elp);
eventmask_t chEvtClear(eventmask_t mask);
eventmask_t chEvtPend(eventmask_t mask);
@ -119,23 +121,23 @@ extern "C" {
void chEvtBroadcastI(EventSource *esp);
void chEvtDispatch(const evhandler_t handlers[], eventmask_t mask);
#if CH_OPTIMIZE_SPEED || !CH_USE_EVENTS_TIMEOUT
eventmask_t chEvtWaitOne(eventmask_t ewmask);
eventmask_t chEvtWaitAny(eventmask_t ewmask);
eventmask_t chEvtWaitAll(eventmask_t ewmask);
eventmask_t chEvtWaitOne(eventmask_t mask);
eventmask_t chEvtWaitAny(eventmask_t mask);
eventmask_t chEvtWaitAll(eventmask_t mask);
#endif
#if CH_USE_EVENTS_TIMEOUT
eventmask_t chEvtWaitOneTimeout(eventmask_t ewmask, systime_t time);
eventmask_t chEvtWaitAnyTimeout(eventmask_t ewmask, systime_t time);
eventmask_t chEvtWaitAllTimeout(eventmask_t ewmask, systime_t time);
eventmask_t chEvtWaitOneTimeout(eventmask_t mask, systime_t time);
eventmask_t chEvtWaitAnyTimeout(eventmask_t mask, systime_t time);
eventmask_t chEvtWaitAllTimeout(eventmask_t mask, systime_t time);
#endif
#ifdef __cplusplus
}
#endif
#if !CH_OPTIMIZE_SPEED && CH_USE_EVENTS_TIMEOUT
#define chEvtWaitOne(ewmask) chEvtWaitOneTimeout(ewmask, TIME_INFINITE)
#define chEvtWaitAny(ewmask) chEvtWaitAnyTimeout(ewmask, TIME_INFINITE)
#define chEvtWaitAll(ewmask) chEvtWaitAllTimeout(ewmask, TIME_INFINITE)
#define chEvtWaitOne(ewmask) chEvtWaitOneTimeout(emask, TIME_INFINITE)
#define chEvtWaitAny(ewmask) chEvtWaitAnyTimeout(emask, TIME_INFINITE)
#define chEvtWaitAll(ewmask) chEvtWaitAllTimeout(emask, TIME_INFINITE)
#endif
#endif /* CH_USE_EVENTS */

9
os/kernel/include/heap.h
View File

@ -18,8 +18,9 @@
*/
/**
* @file heap.h
* @brief Heaps macros and structures.
* @file heap.h
* @brief Heaps macros and structures.
*
* @addtogroup heaps
* @{
*/
@ -43,7 +44,7 @@
typedef struct memory_heap MemoryHeap;
/**
* @brief Memory heap block header.
* @brief Memory heap block header.
*/
struct heap_header {
union {
@ -54,7 +55,7 @@ struct heap_header {
};
/**
* @brief Structure describing a memory heap.
* @brief Structure describing a memory heap.
*/
struct memory_heap {
memgetfunc_t h_provider; /**< @brief Memory blocks provider for

123
os/kernel/src/chcond.c
View File

@ -22,8 +22,9 @@
*/
/**
* @file chcond.c
* @brief Condition Variables code.
* @file chcond.c
* @brief Condition Variables code.
*
* @addtogroup condvars Condition Variables
* @{
*/
@ -33,12 +34,12 @@
#if CH_USE_CONDVARS && CH_USE_MUTEXES
/**
* @brief Initializes s @p CondVar structure.
* @brief Initializes s @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.
*
* @param[out] 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.
* @param[out] cp pointer to a @p CondVar structure
*/
void chCondInit(CondVar *cp) {
@ -48,37 +49,37 @@ void chCondInit(CondVar *cp) {
}
/**
* @brief Signals one thread that is waiting on the condition variable.
* @brief Signals one thread that is waiting on the condition variable.
*
* @param[in] cp pointer to the @p CondVar structure
* @param[in] cp pointer to the @p CondVar structure
*/
void chCondSignal(CondVar *cp) {
chDbgCheck(cp != NULL, "chCondSignal");
chSysLock();
if (notempty(&cp->c_queue)) /* any thread ? */
if (notempty(&cp->c_queue))
chSchWakeupS(fifo_remove(&cp->c_queue), RDY_OK);
chSysUnlock();
}
/**
* @brief Signals one thread that is waiting on the condition variable.
* @brief Signals one thread that is waiting on the condition variable.
*
* @param[in] cp pointer to the @p CondVar structure
* @param[in] cp pointer to the @p CondVar structure
*/
void chCondSignalI(CondVar *cp) {
chDbgCheck(cp != NULL, "chCondSignalI");
if (notempty(&cp->c_queue)) /* any thread ? */
if (notempty(&cp->c_queue))
chSchReadyI(fifo_remove(&cp->c_queue))->p_u.rdymsg = RDY_OK;
}
/**
* @brief Signals all threads that are waiting on the condition variable.
* @brief Signals all threads that are waiting on the condition variable.
*
* @param[in] cp pointer to the @p CondVar structure
* @param[in] cp pointer to the @p CondVar structure
*/
void chCondBroadcast(CondVar *cp) {
@ -89,32 +90,32 @@ void chCondBroadcast(CondVar *cp) {
}
/**
* @brief Signals all threads that are waiting on the condition variable.
* @brief Signals all threads that are waiting on the condition variable.
*
* @param[in] cp pointer to the @p CondVar structure
* @param[in] cp pointer to the @p CondVar structure
*/
void chCondBroadcastI(CondVar *cp) {
chDbgCheck(cp != NULL, "chCondBroadcastI");
/* Empties the condition variable queue and inserts all the Threads into the
* ready list in FIFO order. The wakeup message is set to @p RDY_RESET in
* order to make a chCondBroadcast() detectable from a chCondSignal().*/
ready list in FIFO order. The wakeup message is set to @p RDY_RESET in
order to make a chCondBroadcast() detectable from a chCondSignal().*/
while (cp->c_queue.p_next != (void *)&cp->c_queue)
chSchReadyI(fifo_remove(&cp->c_queue))->p_u.rdymsg = RDY_RESET;
}
/**
* @brief 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
* acquires the mutex again. This is done atomically.
* @note The thread MUST already have locked the mutex when calling
* @p chCondWait().
*
* @param[in] 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().
* @param[in] cp pointer to the @p CondVar structure
* @return The wakep mode.
* @retval RDY_OK if the condvar was signaled using @p chCondSignal().
* @retval RDY_RESET if the condvar was signaled using @p chCondBroadcast().
*/
msg_t chCondWait(CondVar *cp) {
msg_t msg;
@ -126,16 +127,16 @@ msg_t chCondWait(CondVar *cp) {
}
/**
* @brief 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
* acquires the mutex again. This is done atomically.
* @note The thread MUST already have locked the mutex when calling
* @p chCondWaitS().
*
* @param[in] 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 chCondWaitS().
* @param[in] cp pointer to the @p CondVar structure
* @return The wakep mode.
* @retval RDY_OK if the condvar was signaled using @p chCondSignal().
* @retval RDY_RESET if the condvar was signaled using @p chCondBroadcast().
*/
msg_t chCondWaitS(CondVar *cp) {
Thread *ctp = currp;
@ -158,23 +159,23 @@ msg_t chCondWaitS(CondVar *cp) {
#if CH_USE_CONDVARS_TIMEOUT
/**
* @brief 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
* acquires the mutex again. This is done atomically.
* @note The thread MUST already have locked the mutex when calling
* @p chCondWaitTimeout().
*
* @param[in] cp pointer to the @p CondVar structure
* @param[in] time the number of ticks before the operation timeouts,
* the special value @p TIME_INFINITE is allowed.
* It is not possible to specify zero @p TIME_IMMEDIATE
* as timeout specification because it would make no sense
* in this function.
* @return The wakep mode.
* @retval RDY_OK if the condvar was signaled using chCondSignal().
* @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().
* @param[in] cp pointer to the @p CondVar structure
* @param[in] time the number of ticks before the operation timeouts,
* the special value @p TIME_INFINITE is allowed.
* It is not possible to specify zero @p TIME_IMMEDIATE
* as timeout specification because it would make no sense
* in this function.
* @return The wakep mode.
* @retval RDY_OK if the condvar was signaled using @p chCondSignal().
* @retval RDY_RESET if the condvar was signaled using @p chCondBroadcast().
* @retval RDY_TIMEOUT if the condvar was not signaled @p within the specified
* timeout.
*/
msg_t chCondWaitTimeout(CondVar *cp, systime_t time) {
msg_t msg;
@ -186,23 +187,23 @@ msg_t chCondWaitTimeout(CondVar *cp, systime_t time) {
}
/**
* @brief 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
* acquires the mutex again. This is done atomically.
* @note The thread MUST already have locked the mutex when calling
* @p chCondWaitTimeoutS().
*
* @param[in] cp pointer to the @p CondVar structure
* @param[in] time the number of ticks before the operation timeouts,
* the special value @p TIME_INFINITE is allowed.
* It is not possible to specify zero @p TIME_IMMEDIATE
* as timeout specification because it would make no sense
* in this function.
* @return The wakep mode.
* @retval RDY_OK if the condvar was signaled using chCondSignal().
* @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 chCondWaitTimeoutS().
* @param[in] cp pointer to the @p CondVar structure
* @param[in] time the number of ticks before the operation timeouts,
* the special value @p TIME_INFINITE is allowed.
* It is not possible to specify zero @p TIME_IMMEDIATE
* as timeout specification because it would make no sense
* in this function.
* @return The wakep mode.
* @retval RDY_OK if the condvar was signaled using @p chCondSignal().
* @retval RDY_RESET if the condvar was signaled using @p chCondBroadcast().
* @retval RDY_TIMEOUT if the condvar was not signaled within the specified
* timeout.
*/
msg_t chCondWaitTimeoutS(CondVar *cp, systime_t time) {
Thread *ctp = currp;

21
os/kernel/src/chdebug.c
View File

@ -18,8 +18,9 @@
*/
/**
* @file chdebug.c
* @brief ChibiOS/RT Debug code.
* @file chdebug.c
* @brief ChibiOS/RT Debug code.
*
* @addtogroup debug
* @{
*/
@ -28,12 +29,12 @@
#if CH_DBG_ENABLE_TRACE
/**
* @brief Public trace buffer.
* @brief Public trace buffer.
*/
TraceBuffer trace_buffer;
/**
* @brief Trace circular buffer subsystem initialization.
* @brief Trace circular buffer subsystem initialization.
*/
void trace_init(void) {
@ -42,10 +43,10 @@ void trace_init(void) {
}
/**
* @brief Inserts in the circular debug trace buffer a context switch record.
* @brief Inserts in the circular debug trace buffer a context switch record.
*
* @param[in] otp the thread being switched out
* @param[in] ntp the thread to be switched in
* @param[in] otp the thread being switched out
* @param[in] ntp the thread to be switched in
*/
void chDbgTrace(Thread *otp, Thread *ntp) {
@ -60,7 +61,7 @@ void chDbgTrace(Thread *otp, Thread *ntp) {
#if CH_DBG_ENABLE_ASSERTS || CH_DBG_ENABLE_CHECKS || CH_DBG_ENABLE_STACK_CHECK
/**
* @brief Pointer to the panic message.
* @brief Pointer to the panic message.
* @details This pointer is meant to be accessed through the debugger, it is
* written once and then the system is halted. This variable can be
* set to @p NULL if the halt is caused by a stack overflow.
@ -68,9 +69,9 @@ void chDbgTrace(Thread *otp, Thread *ntp) {
char *panic_msg;
/**
* @brief Prints a panic message on the console and then halts the system.
* @brief Prints a panic message on the console and then halts the system.
*
* @param[in] msg the pointer to the panic message string
* @param[in] msg the pointer to the panic message string
*/
void chDbgPanic(char *msg) {

247
os/kernel/src/chevents.c
View File

@ -18,8 +18,9 @@
*/
/**
* @file chevents.c
* @brief Events code.
* @file chevents.c
* @brief Events code.
*
* @addtogroup events
* @{
*/
@ -27,15 +28,15 @@
#if CH_USE_EVENTS
/**
* @brief Registers an Event Listener on an Event Source.
* @brief Registers an Event Listener on an Event Source.
* @note Multiple Event Listeners can specify the same bits to be pended.
*
* @param[in] esp pointer to the @p EventSource structure
* @param[in] elp pointer to the @p EventListener structure
* @param[in] emask the mask of event flags to be pended to the thread when the
* event source is broadcasted
* @note Multiple Event Listeners can specify the same bits to be pended.
* @param[in] esp pointer to the @p EventSource structure
* @param[in] elp pointer to the @p EventListener structure
* @param[in] mask the mask of event flags to be pended to the thread when
* the event source is broadcasted
*/
void chEvtRegisterMask(EventSource *esp, EventListener *elp, eventmask_t emask) {
void chEvtRegisterMask(EventSource *esp, EventListener *elp, eventmask_t mask) {
chDbgCheck((esp != NULL) && (elp != NULL), "chEvtRegisterMask");
@ -43,20 +44,20 @@ void chEvtRegisterMask(EventSource *esp, EventListener *elp, eventmask_t emask)
elp->el_next = esp->es_next;
esp->es_next = elp;
elp->el_listener = currp;
elp->el_mask = emask;
elp->el_mask = mask;
chSysUnlock();
}
/**
* @brief Unregisters an Event Listener from its Event Source.
* @brief Unregisters an Event Listener from its Event Source.
* @note If the event listener is not registered on the specified event
* source then the function does nothing.
* @note For optimal performance it is better to perform the unregister
* operations in inverse order of the register operations (elements
* are found on top of the list).
*
* @param[in] esp pointer to the @p EventSource structure
* @param[in] elp pointer to the @p EventListener structure
* @note If the event listener is not registered on the specified event source
* then the function does nothing.
* @note For optimal performance it is better to perform the unregister
* operations in inverse order of the register operations (elements are
* found on top of the list).
* @param[in] esp pointer to the @p EventSource structure
* @param[in] elp pointer to the @p EventListener structure
*/
void chEvtUnregister(EventSource *esp, EventListener *elp) {
EventListener *p;
@ -76,10 +77,10 @@ void chEvtUnregister(EventSource *esp, EventListener *elp) {
}
/**
* @brief Clears the pending events specified in the mask.
* @brief Clears the pending events specified in the mask.
*
* @param[in] mask the events to be cleared
* @return The pending events that were cleared.
* @param[in] mask the events to be cleared
* @return The pending events that were cleared.
*/
eventmask_t chEvtClear(eventmask_t mask) {
eventmask_t m;
@ -94,11 +95,11 @@ eventmask_t chEvtClear(eventmask_t mask) {
}
/**
* @brief Pends a set of event flags on the current thread, this is @b much
* faster than using @p chEvtBroadcast() or @p chEvtSignal().
* @brief Pends a set of event flags on the current thread, this is @b much
* faster than using @p chEvtBroadcast() or @p chEvtSignal().
*
* @param[in] mask the events to be pended
* @return The current pending events mask.
* @param[in] mask the events to be pended
* @return The current pending events mask.
*/
eventmask_t chEvtPend(eventmask_t mask) {
@ -111,10 +112,10 @@ eventmask_t chEvtPend(eventmask_t mask) {
}
/**
* @brief Pends a set of event flags on the specified @p Thread.
* @brief Pends a set of event flags on the specified @p Thread.
*
* @param[in] tp the thread to be signaled
* @param[in] mask the event flags set to be pended
* @param[in] tp the thread to be signaled
* @param[in] mask the event flags set to be pended
*/
void chEvtSignal(Thread *tp, eventmask_t mask) {
@ -126,10 +127,10 @@ void chEvtSignal(Thread *tp, eventmask_t mask) {
}
/**
* @brief Pends a set of event flags on the specified @p Thread.
* @brief Pends a set of event flags on the specified @p Thread.
*
* @param[in] tp the thread to be signaled
* @param[in] mask the event flags set to be pended
* @param[in] tp the thread to be signaled
* @param[in] mask the event flags set to be pended
*/
void chEvtSignalI(Thread *tp, eventmask_t mask) {
@ -145,10 +146,10 @@ void chEvtSignalI(Thread *tp, eventmask_t mask) {
}
/**
* @brief Signals all the Event Listeners registered on the specified Event
* Source.
* @brief Signals all the Event Listeners registered on the specified Event
* Source.
*
* @param[in] esp pointer to the @p EventSource structure
* @param[in] esp pointer to the @p EventSource structure
*/
void chEvtBroadcast(EventSource *esp) {
@ -159,10 +160,10 @@ void chEvtBroadcast(EventSource *esp) {
}
/**
* @brief Signals all the Event Listeners registered on the specified Event
* Source.
* @brief Signals all the Event Listeners registered on the specified Event
* Source.
*
* @param[in] esp pointer to the @p EventSource structure
* @param[in] esp pointer to the @p EventSource structure
*/
void chEvtBroadcastI(EventSource *esp) {
EventListener *elp;
@ -177,11 +178,11 @@ void chEvtBroadcastI(EventSource *esp) {
}
/**
* @brief Invokes the event handlers associated to an event flags mask.
* @brief Invokes the event handlers associated to an event flags mask.
*
* @param[in] mask mask of the events to be dispatched
* @param[in] handlers an array of @p evhandler_t. The array must have size
* equal to the number of bits in eventmask_t.
* @param[in] mask mask of the events to be dispatched
* @param[in] handlers an array of @p evhandler_t. The array must have size
* equal to the number of bits in eventmask_t.
*/
void chEvtDispatch(const evhandler_t handlers[], eventmask_t mask) {
eventid_t eid;
@ -203,29 +204,29 @@ void chEvtDispatch(const evhandler_t handlers[], eventmask_t mask) {
#if CH_OPTIMIZE_SPEED || !CH_USE_EVENTS_TIMEOUT || defined(__DOXYGEN__)
/**
* @brief Waits for exactly one of the specified events.
* @brief Waits for exactly one of the specified events.
* @details The function waits for one event among those specified in
* @p ewmask to become pending then the event is cleared and returned.
* @p mask to become pending then the event is cleared and returned.
* @note One and only one event is served in the function, the one with the
* lowest event id. The function is meant to be invoked into a loop in
* order to serve all the pending events.<br>
* This means that Event Listeners with a lower event identifier have
* an higher priority.
*
* @param[in] 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.
* @note One and only one event is served in the function, the one with the
* lowest event id. The function is meant to be invoked into a loop in
* order to serve all the pending events.<br>
* This means that Event Listeners with a lower event identifier have
* an higher priority.
* @param[in] mask 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.
*/
eventmask_t chEvtWaitOne(eventmask_t ewmask) {
eventmask_t chEvtWaitOne(eventmask_t mask) {
Thread *ctp = currp;
eventmask_t m;
chSysLock();
if ((m = (ctp->p_epending & ewmask)) == 0) {
ctp->p_u.ewmask = ewmask;
if ((m = (ctp->p_epending & mask)) == 0) {
ctp->p_u.ewmask = mask;
chSchGoSleepS(THD_STATE_WTOREVT);
m = ctp->p_epending & ewmask;
m = ctp->p_epending & mask;
}
m &= -m;
ctp->p_epending &= ~m;
@ -235,24 +236,24 @@ eventmask_t chEvtWaitOne(eventmask_t ewmask) {
}
/**
* @brief Waits for any of the specified events.
* @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.
* @p mask to become pending then the events are cleared and returned.
*
* @param[in] 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.
* @param[in] mask 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.
*/
eventmask_t chEvtWaitAny(eventmask_t ewmask) {
eventmask_t chEvtWaitAny(eventmask_t mask) {
Thread *ctp = currp;
eventmask_t m;
chSysLock();
if ((m = (ctp->p_epending & ewmask)) == 0) {
ctp->p_u.ewmask = ewmask;
if ((m = (ctp->p_epending & mask)) == 0) {
ctp->p_u.ewmask = mask;
chSchGoSleepS(THD_STATE_WTOREVT);
m = ctp->p_epending & ewmask;
m = ctp->p_epending & mask;
}
ctp->p_epending &= ~m;
@ -261,63 +262,63 @@ eventmask_t chEvtWaitAny(eventmask_t ewmask) {
}
/**
* @brief Waits for all the specified events.
* @details The function waits for all the events specified in @p ewmask to
* @brief Waits for all the specified events.
* @details The function waits for all the events specified in @p mask to
* become pending then the events are cleared and returned.
*
* @param[in] ewmask mask of the event ids that the function should wait for
* @return The mask of the served and cleared events.
* @param[in] mask mask of the event ids that the function should wait for
* @return The mask of the served and cleared events.
*/
eventmask_t chEvtWaitAll(eventmask_t ewmask) {
eventmask_t chEvtWaitAll(eventmask_t mask) {
Thread *ctp = currp;
chSysLock();
if ((ctp->p_epending & ewmask) != ewmask) {
ctp->p_u.ewmask = ewmask;
if ((ctp->p_epending & mask) != mask) {
ctp->p_u.ewmask = mask;
chSchGoSleepS(THD_STATE_WTANDEVT);
}
ctp->p_epending &= ~ewmask;
ctp->p_epending &= ~mask;
chSysUnlock();
return ewmask;
return mask;
}
#endif /* CH_OPTIMIZE_SPEED || !CH_USE_EVENTS_TIMEOUT */
#if CH_USE_EVENTS_TIMEOUT
/**
* @brief Waits for exactly one of the specified events.
* @brief Waits for exactly one of the specified events.
* @details The function waits for one event among those specified in
* @p ewmask to become pending then the event is cleared and returned.
* @p mask to become pending then the event is cleared and returned.
* @note One and only one event is served in the function, the one with the
* lowest event id. The function is meant to be invoked into a loop in
* order to serve all the pending events.<br>
* This means that Event Listeners with a lower event identifier have
* an higher priority.
*
* @param[in] ewmask mask of the events that the function should wait for,
* @p ALL_EVENTS enables all the events
* @param[in] time the number of ticks before the operation timeouts,
* the following special values are allowed:
* - @a TIME_IMMEDIATE immediate timeout.
* - @a TIME_INFINITE no timeout.
* .
* @return The mask of the lowest id served and cleared event.
* @retval 0 if the specified timeout expired.
* @note One and only one event is served in the function, the one with the
* lowest event id. The function is meant to be invoked into a loop in
* order to serve all the pending events.<br>
* This means that Event Listeners with a lower event identifier have
* an higher priority.
* @param[in] mask mask of the events that the function should wait for,
* @p ALL_EVENTS enables all the events
* @param[in] time the number of ticks before the operation timeouts,
* the following special values are allowed:
* - @a TIME_IMMEDIATE immediate timeout.
* - @a TIME_INFINITE no timeout.
* .
* @return The mask of the lowest id served and cleared event.
* @retval 0 if the specified timeout expired.
*/
eventmask_t chEvtWaitOneTimeout(eventmask_t ewmask, systime_t time) {
eventmask_t chEvtWaitOneTimeout(eventmask_t mask, systime_t time) {
Thread *ctp = currp;
eventmask_t m;
chSysLock();
if ((m = (ctp->p_epending & ewmask)) == 0) {
if ((m = (ctp->p_epending & mask)) == 0) {
if (TIME_IMMEDIATE == time)
return (eventmask_t)0;
ctp->p_u.ewmask = ewmask;
ctp->p_u.ewmask = mask;
if (chSchGoSleepTimeoutS(THD_STATE_WTOREVT, time) < RDY_OK)
return (eventmask_t)0;
m = ctp->p_epending & ewmask;
m = ctp->p_epending & mask;
}
m &= -m;
ctp->p_epending &= ~m;
@ -327,34 +328,34 @@ eventmask_t chEvtWaitOneTimeout(eventmask_t ewmask, systime_t time) {
}
/**
* @brief Waits for any of the specified events.
* @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
* @p mask to become pending then the events are cleared and
* returned.
*
* @param[in] ewmask mask of the events that the function should wait for,
* @p ALL_EVENTS enables all the events
* @param[in] time the number of ticks before the operation timeouts,
* the following special values are allowed:
* - @a TIME_IMMEDIATE immediate timeout.
* - @a TIME_INFINITE no timeout.
* .
* @return The mask of the served and cleared events.
* @retval 0 if the specified timeout expired.
* @param[in] mask mask of the events that the function should wait for,
* @p ALL_EVENTS enables all the events
* @param[in] time the number of ticks before the operation timeouts,
* the following special values are allowed:
* - @a TIME_IMMEDIATE immediate timeout.
* - @a TIME_INFINITE no timeout.
* .
* @return The mask of the served and cleared events.
* @retval 0 if the specified timeout expired.
*/
eventmask_t chEvtWaitAnyTimeout(eventmask_t ewmask, systime_t time) {
eventmask_t chEvtWaitAnyTimeout(eventmask_t mask, systime_t time) {
Thread *ctp = currp;
eventmask_t m;
chSysLock();
if ((m = (ctp->p_epending & ewmask)) == 0) {
if ((m = (ctp->p_epending & mask)) == 0) {
if (TIME_IMMEDIATE == time)
return (eventmask_t)0;
ctp->p_u.ewmask = ewmask;
ctp->p_u.ewmask = mask;
if (chSchGoSleepTimeoutS(THD_STATE_WTOREVT, time) < RDY_OK)
return (eventmask_t)0;
m = ctp->p_epending & ewmask;
m = ctp->p_epending & mask;
}
ctp->p_epending &= ~m;
@ -363,35 +364,35 @@ eventmask_t chEvtWaitAnyTimeout(eventmask_t ewmask, systime_t time) {
}
/**
* @brief Waits for all the specified events.
* @details The function waits for all the events specified in @p ewmask to
* @brief Waits for all the specified events.
* @details The function waits for all the events specified in @p mask to
* become pending then the events are cleared and returned.
*
* @param[in] ewmask mask of the event ids that the function should wait for
* @param[in] time the number of ticks before the operation timeouts,
* the following special values are allowed:
* - @a TIME_IMMEDIATE immediate timeout.
* - @a TIME_INFINITE no timeout.
* .
* @return The mask of the served and cleared events.
* @retval 0 if the specified timeout expired.
* @param[in] mask mask of the event ids that the function should wait for
* @param[in] time the number of ticks before the operation timeouts,
* the following special values are allowed:
* - @a TIME_IMMEDIATE immediate timeout.
* - @a TIME_INFINITE no timeout.
* .
* @return The mask of the served and cleared events.
* @retval 0 if the specified timeout expired.
*/
eventmask_t chEvtWaitAllTimeout(eventmask_t ewmask, systime_t time) {
eventmask_t chEvtWaitAllTimeout(eventmask_t mask, systime_t time) {
Thread *ctp = currp;
chSysLock();
if ((ctp->p_epending & ewmask) != ewmask) {
if ((ctp->p_epending & mask) != mask) {
if (TIME_IMMEDIATE == time)
return (eventmask_t)0;
ctp->p_u.ewmask = ewmask;
ctp->p_u.ewmask = mask;
if (chSchGoSleepTimeoutS(THD_STATE_WTANDEVT, time) < RDY_OK)
return (eventmask_t)0;
}
ctp->p_epending &= ~ewmask;
ctp->p_epending &= ~mask;
chSysUnlock();
return ewmask;
return mask;
}
#endif /* CH_USE_EVENTS_TIMEOUT */

100
os/kernel/src/chheap.c
View File

@ -18,8 +18,9 @@
*/
/**
* @file chheap.c
* @brief Heaps code.
* @file chheap.c
* @brief Heaps code.
*
* @addtogroup heaps
* @{
*/
@ -42,14 +43,13 @@
#if !CH_USE_MALLOC_HEAP
/**
* @brief Default heap descriptor.
* @brief Default heap descriptor.
*/
static MemoryHeap default_heap;
/**
* @brief Initializes the default heap.
*
* @note Internal use only.
* @brief Initializes the default heap.
* @note Internal use only.
*/
void heap_init(void) {
default_heap.h_provider = chCoreAlloc;
@ -63,14 +63,13 @@ void heap_init(void) {
}
/**
* @brief Initializes a memory heap from a static memory area.
* @brief Initializes a memory heap from a static memory area.
* @note Both the heap buffer base and the heap size must be aligned to
* the @p align_t type size.
*
* @param[out] heapp pointer to a memory heap descriptor to be initialized
* @param[in] buf heap buffer base
* @param[in] size heap size
*
* @note Both the heap buffer base and the heap size must be aligned to
* the @p align_t type size.
* @param[out] heapp pointer to the memory heap descriptor to be initialized
* @param[in] buf heap buffer base
* @param[in] size heap size
*/
void chHeapInit(MemoryHeap *heapp, void *buf, size_t size) {
struct heap_header *hp;
@ -90,18 +89,18 @@ void chHeapInit(MemoryHeap *heapp, void *buf, size_t size) {
}
/**
* @brief 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
* algorithm.
* @details The allocated block is guaranteed to be properly aligned for a
* pointer data type (@p align_t).
*
* @param[in] heapp pointer to a heap descriptor or @p NULL in order to access
* the default heap.
* @param[in] size the size of the block to be allocated. Note that the
* allocated block may be a bit bigger than the requested
* size for alignment and fragmentation reasons.
* @return A pointer to the allocated block.
* @retval NULL if the block cannot be allocated.
* @param[in] heapp pointer to a heap descriptor or @p NULL in order to
* access the default heap.
* @param[in] size the size of the block to be allocated. Note that the
* allocated block may be a bit bigger than the requested
* size for alignment and fragmentation reasons.
* @return A pointer to the allocated block.
* @retval NULL if the block cannot be allocated.
*/
void *chHeapAlloc(MemoryHeap *heapp, size_t size) {
struct heap_header *qp, *hp, *fp;
@ -117,17 +116,13 @@ void *chHeapAlloc(MemoryHeap *heapp, size_t size) {
hp = qp->h_u.next;
if (hp->h_size >= size) {
if (hp->h_size < size + sizeof(struct heap_header)) {
/*
* Gets the whole block even if it is slightly bigger than the
* requested size because the fragment would be too small to be
* useful.
*/
/* Gets the whole block even if it is slightly bigger than the
requested size because the fragment would be too small to be
useful.*/
qp->h_u.next = hp->h_u.next;
}
else {
/*
* Block bigger enough, must split it.
*/
/* Block bigger enough, must split it.*/
fp = (void *)((uint8_t *)(hp) + sizeof(struct heap_header) + size);
fp->h_u.next = hp->h_u.next;
fp->h_size = hp->h_size - sizeof(struct heap_header) - size;
@ -144,9 +139,8 @@ void *chHeapAlloc(MemoryHeap *heapp, size_t size) {
H_UNLOCK(heapp);
/*
* More memory is required, tries to get it from the associated provider.
*/
/* More memory is required, tries to get it from the associated provider
else fails.*/
if (heapp->h_provider) {
hp = heapp->h_provider(size + sizeof(struct heap_header));
if (hp != NULL) {
@ -164,9 +158,9 @@ void *chHeapAlloc(MemoryHeap *heapp, size_t size) {
(p)->h_size)
/**
* @brief Frees a previously allocated memory block.
* @brief Frees a previously allocated memory block.
*
* @param[in] p the memory block pointer
* @param[in] p pointer to the memory block to be freed
*/
void chHeapFree(void *p) {
struct heap_header *qp, *hp;
@ -186,25 +180,17 @@ void chHeapFree(void *p) {
if (((qp == &heapp->h_free) || (hp > qp)) &&
((qp->h_u.next == NULL) || (hp < qp->h_u.next))) {
/*
* Insertion after qp.
*/
/* Insertion after qp.*/
hp->h_u.next = qp->h_u.next;
qp->h_u.next = hp;
/*
* Verifies if the newly inserted block should be merged.
*/
/* Verifies if the newly inserted block should be merged.*/
if (LIMIT(hp) == hp->h_u.next) {
/*
* Merge with the next block.
*/
/* Merge with the next block.*/
hp->h_size += hp->h_u.next->h_size + sizeof(struct heap_header);
hp->h_u.next = hp->h_u.next->h_u.next;
}
if ((LIMIT(qp) == hp)) {
/*
* Merge with the previous block.
*/
/* Merge with the previous block.*/
qp->h_size += hp->h_size + sizeof(struct heap_header);
qp->h_u.next = hp->h_u.next;
}
@ -218,17 +204,17 @@ void chHeapFree(void *p) {
}
/**
* @brief Reports the heap status.
* @brief Reports the heap status.
* @note This function is meant to be used in the test suite, it should
* not be really useful for the application code.
* @note This function is not implemented when the @p CH_USE_MALLOC_HEAP
* configuration option is used (it always returns zero).
*
* @param[in] heapp pointer to a heap descriptor or @p NULL in order to access
* the default heap.
* @param[in] sizep pointer to a variable that will receive the total
* fragmented free space
* @return The number of fragments in the heap.
* @note This function is meant to be used in the test suite, it should not be
* really useful for the application code.
* @note This function is not implemented when the @p CH_USE_MALLOC_HEAP
* configuration option is used (it always returns zero).
* @param[in] heapp pointer to a heap descriptor or @p NULL in order to
* access the default heap.
* @param[in] sizep pointer to a variable that will receive the total
* fragmented free space
* @return The number of fragments in the heap.
*/
size_t chHeapStatus(MemoryHeap *heapp, size_t *sizep) {
struct heap_header *qp;

85
os/kernel/src/chlists.c
View File

@ -18,8 +18,9 @@
*/
/**
* @file chlists.c
* @brief Thread queues/lists code.
* @file chlists.c
* @brief Thread queues/lists code.
*
* @addtogroup internals
* @{
*/
@ -27,35 +28,35 @@
#if !CH_OPTIMIZE_SPEED || defined(__DOXYGEN__)
/**
* @brief Inserts a thread into a priority ordered queue.
* @note The insertion is done by scanning the list from the highest priority
* toward the lowest.
* @note This function is @b not an API.
* @brief Inserts a thread into a priority ordered queue.
* @note The insertion is done by scanning the list from the highest priority
* toward the lowest.
* @note This function is @b not an API.
*
* @param[in] tp the pointer to the thread to be inserted in the list
* @param[in] tqp the pointer to the threads list header
* @param[in] tp the pointer to the thread to be inserted in the list
* @param[in] tqp the pointer to the threads list header
*/
void prio_insert(Thread *tp, ThreadsQueue *tqp) {
/* cp iterates over the queue */
/* cp iterates over the queue.*/
Thread *cp = (Thread *)tqp;
do {
/* iterate to next thread in queue */
/* Iterate to next thread in queue.*/
cp = cp->p_next;
/* not end of queue? and cp has equal or higher priority than tp? */
/* Not end of queue? and cp has equal or higher priority than tp?.*/
} while ((cp != (Thread *)tqp) && (cp->p_prio >= tp->p_prio));
/* insert before cp, point tp to next and prev in queue */
/* Insert before cp, point tp to next and prev in queue.*/
tp->p_prev = (tp->p_next = cp)->p_prev;
/* make prev point to tp, and cp point back to tp */
/* Make prev point to tp, and cp point back to tp.*/
tp->p_prev->p_next = cp->p_prev = tp;
}
/**
* @brief Inserts a Thread into a queue.
* @note This function is @b not an API.
* @brief Inserts a Thread into a queue.
* @note This function is @b not an API.
*
* @param[in] tp the pointer to the thread to be inserted in the list
* @param[in] tqp the pointer to the threads list header
* @param[in] tp the pointer to the thread to be inserted in the list
* @param[in] tqp the pointer to the threads list header
*/
void queue_insert(Thread *tp, ThreadsQueue *tqp) {
@ -64,13 +65,13 @@ void queue_insert(Thread *tp, ThreadsQueue *tqp) {
}
/**
* @brief Removes the first-out Thread from a queue and returns it.
* @note If the queue is priority ordered then this function returns the
* thread with the highest priority.
* @note This function is @b not an API.
* @brief Removes the first-out Thread from a queue and returns it.
* @note If the queue is priority ordered then this function returns the
* thread with the highest priority.
* @note This function is @b not an API.
*
* @param[in] tqp the pointer to the threads list header
* @return The removed thread pointer.
* @param[in] tqp the pointer to the threads list header
* @return The removed thread pointer.
*/
Thread *fifo_remove(ThreadsQueue *tqp) {
Thread *tp = tqp->p_next;
@ -80,13 +81,13 @@ Thread *fifo_remove(ThreadsQueue *tqp) {
}
/**
* @brief Removes the last-out Thread from a queue and returns it.
* @note If the queue is priority ordered then this function returns the
* thread with the lowest priority.
* @note This function is @b not an API.
* @brief Removes the last-out Thread from a queue and returns it.
* @note If the queue is priority ordered then this function returns the
* thread with the lowest priority.
* @note This function is @b not an API.
*
* @param[in] tqp the pointer to the threads list header
* @return The removed thread pointer.
* @param[in] tqp the pointer to the threads list header
* @return The removed thread pointer.
*/
Thread *lifo_remove(ThreadsQueue *tqp) {
Thread *tp = tqp->p_prev;
@ -96,13 +97,13 @@ Thread *lifo_remove(ThreadsQueue *tqp) {
}
/**
* @brief Removes a Thread from a queue and returns it.
* @brief Removes a Thread from a queue and returns it.
* @details The thread is removed from the queue regardless of its relative
* position and regardless the used insertion method.
* @note This function is @b not an API.
* @note This function is @b not an API.
*
* @param[in] tp the pointer to the thread to be removed from the queue
* @return The removed thread pointer.
* @param[in] tp the pointer to the thread to be removed from the queue
* @return The removed thread pointer.
*/
Thread *dequeue(Thread *tp) {
@ -112,11 +113,11 @@ Thread *dequeue(Thread *tp) {
}
/**
* @brief Pushes a Thread on top of a stack list.
* @note This function is @b not an API.
* @brief Pushes a Thread on top of a stack list.
* @note This function is @b not an API.
*
* @param[in] tp the pointer to the thread to be inserted in the list
* @param[in] tlp the pointer to the threads list header
* @param[in] tp the pointer to the thread to be inserted in the list
* @param[in] tlp the pointer to the threads list header
*/
void list_insert(Thread *tp, ThreadsList *tlp) {
@ -125,12 +126,12 @@ void list_insert(Thread *tp, ThreadsList *tlp) {
}
/**
* @brief Pops a Thread from the top of a stack list and returns it.
* @note The list must be non-empty before calling this function.
* @note This function is @b not an API.
* @brief Pops a Thread from the top of a stack list and returns it.
* @note The list must be non-empty before calling this function.
* @note This function is @b not an API.
*
* @param[in] tlp the pointer to the threads list header
* @return The removed thread pointer.
* @param[in] tlp the pointer to the threads list header
* @return The removed thread pointer.
*/
Thread *list_remove(ThreadsList *tlp) {

161
os/kernel/src/chmboxes.c
View File

@ -18,8 +18,9 @@
*/
/**
* @file chmboxes.c
* @brief Mailboxes code.
* @file chmboxes.c
* @brief Mailboxes code.
*
* @addtogroup mailboxes
* @{
*/
@ -28,11 +29,11 @@
#if CH_USE_MAILBOXES
/**
* @brief Initializes a Mailbox object.
* @brief Initializes a Mailbox object.
*
* @param[out] mbp the pointer to the Mailbox structure to be initialized
* @param[in] buf the circular messages buffer
* @param[in] n the buffer size as number of @p msg_t
* @param[out] mbp the pointer to the Mailbox structure to be initialized
* @param[in] buf the circular messages buffer
* @param[in] n the buffer size as number of @p msg_t
*/
void chMBInit(Mailbox *mbp, msg_t *buf, cnt_t n) {
@ -45,11 +46,11 @@ void chMBInit(Mailbox *mbp, msg_t *buf, cnt_t n) {
}
/**
* @brief Resets a Mailbox object.
* @brief Resets a Mailbox object.
* @details All the waiting threads are resumed with status @p RDY_RESET and
* the queued messages are lost.
*
* @param[in] mbp the pointer to an initialized Mailbox object
* @param[in] mbp the pointer to an initialized Mailbox object
*/
void chMBReset(Mailbox *mbp) {
@ -64,21 +65,21 @@ void chMBReset(Mailbox *mbp) {
}
/**
* @brief Posts a message into a mailbox.
* @brief Posts a message into a mailbox.
* @details The invoking thread waits until a empty slot in the mailbox becomes
* available or the specified time runs out.
*
* @param[in] mbp the pointer to an initialized Mailbox object
* @param[in] msg the message to be posted on the mailbox
* @param[in] time the number of ticks before the operation timeouts,
* the following special values are allowed:
* - @a TIME_IMMEDIATE immediate timeout.
* - @a TIME_INFINITE no timeout.
* .
* @return The operation status.
* @retval RDY_OK if the message was correctly posted.
* @retval RDY_RESET if the mailbox was reset while waiting.
* @retval RDY_TIMEOUT if the operation timed out.
* @param[in] mbp the pointer to an initialized Mailbox object
* @param[in] msg the message to be posted on the mailbox
* @param[in] time the number of ticks before the operation timeouts,
* the following special values are allowed:
* - @a TIME_IMMEDIATE immediate timeout.
* - @a TIME_INFINITE no timeout.
* .
* @return The operation status.
* @retval RDY_OK if the message was correctly posted.
* @retval RDY_RESET if the mailbox was reset while waiting.
* @retval RDY_TIMEOUT if the operation timed out.
*/
msg_t chMBPost(Mailbox *mbp, msg_t msg, systime_t time) {
msg_t rdymsg;
@ -90,21 +91,21 @@ msg_t chMBPost(Mailbox *mbp, msg_t msg, systime_t time) {
}
/**
* @brief Posts a message into a mailbox.
* @brief Posts a message into a mailbox.
* @details The invoking thread waits until a empty slot in the mailbox becomes
* available or the specified time runs out.
*
* @param[in] mbp the pointer to an initialized Mailbox object
* @param[in] msg the message to be posted on the mailbox
* @param[in] time the number of ticks before the operation timeouts,
* the following special values are allowed:
* - @a TIME_IMMEDIATE immediate timeout.
* - @a TIME_INFINITE no timeout.
* .
* @return The operation status.
* @retval RDY_OK if the message was correctly posted.
* @retval RDY_RESET if the mailbox was reset while waiting.
* @retval RDY_TIMEOUT if the operation timed out.
* @param[in] mbp the pointer to an initialized Mailbox object
* @param[in] msg the message to be posted on the mailbox
* @param[in] time the number of ticks before the operation timeouts,
* the following special values are allowed:
* - @a TIME_IMMEDIATE immediate timeout.
* - @a TIME_INFINITE no timeout.
* .
* @return The operation status.
* @retval RDY_OK if the message was correctly posted.
* @retval RDY_RESET if the mailbox was reset while waiting.
* @retval RDY_TIMEOUT if the operation timed out.
*/
msg_t chMBPostS(Mailbox *mbp, msg_t msg, systime_t time) {
msg_t rdymsg;
@ -123,21 +124,21 @@ msg_t chMBPostS(Mailbox *mbp, msg_t msg, systime_t time) {
}
/**
* @brief Posts an high priority message into a mailbox.
* @brief Posts an high priority message into a mailbox.
* @details The invoking thread waits until a empty slot in the mailbox becomes
* available or the specified time runs out.
*
* @param[in] mbp the pointer to an initialized Mailbox object
* @param[in] msg the message to be posted on the mailbox
* @param[in] time the number of ticks before the operation timeouts,
* the following special values are allowed:
* - @a TIME_IMMEDIATE immediate timeout.
* - @a TIME_INFINITE no timeout.
* .
* @return The operation status.
* @retval RDY_OK if the message was correctly posted.
* @retval RDY_RESET if the mailbox was reset while waiting.
* @retval RDY_TIMEOUT if the operation timed out.
* @param[in] mbp the pointer to an initialized Mailbox object
* @param[in] msg the message to be posted on the mailbox
* @param[in] time the number of ticks before the operation timeouts,
* the following special values are allowed:
* - @a TIME_IMMEDIATE immediate timeout.
* - @a TIME_INFINITE no timeout.
* .
* @return The operation status.
* @retval RDY_OK if the message was correctly posted.
* @retval RDY_RESET if the mailbox was reset while waiting.
* @retval RDY_TIMEOUT if the operation timed out.
*/
msg_t chMBPostAhead(Mailbox *mbp, msg_t msg, systime_t time) {
msg_t rdymsg;
@ -149,21 +150,21 @@ msg_t chMBPostAhead(Mailbox *mbp, msg_t msg, systime_t time) {
}
/**
* @brief Posts an high priority message into a mailbox.
* @brief Posts an high priority message into a mailbox.
* @details The invoking thread waits until a empty slot in the mailbox becomes
* available or the specified time runs out.
*
* @param[in] mbp the pointer to an initialized Mailbox object
* @param[in] msg the message to be posted on the mailbox
* @param[in] time the number of ticks before the operation timeouts,
* the following special values are allowed:
* - @a TIME_IMMEDIATE immediate timeout.
* - @a TIME_INFINITE no timeout.
* .
* @return The operation status.
* @retval RDY_OK if the message was correctly posted.
* @retval RDY_RESET if the mailbox was reset while waiting.
* @retval RDY_TIMEOUT if the operation timed out.
* @param[in] mbp the pointer to an initialized Mailbox object
* @param[in] msg the message to be posted on the mailbox
* @param[in] time the number of ticks before the operation timeouts,
* the following special values are allowed:
* - @a TIME_IMMEDIATE immediate timeout.
* - @a TIME_INFINITE no timeout.
* .
* @return The operation status.
* @retval RDY_OK if the message was correctly posted.
* @retval RDY_RESET if the mailbox was reset while waiting.
* @retval RDY_TIMEOUT if the operation timed out.
*/
msg_t chMBPostAheadS(Mailbox *mbp, msg_t msg, systime_t time) {
msg_t rdymsg;
@ -182,21 +183,21 @@ msg_t chMBPostAheadS(Mailbox *mbp, msg_t msg, systime_t time) {
}
/**
* @brief Retrieves a message from a mailbox.
* @brief Retrieves a message from a mailbox.
* @details The invoking thread waits until a message is posted in the mailbox
* or the specified time runs out.
*
* @param[in] mbp the pointer to an initialized Mailbox object
* @param[out] msgp pointer to a message variable for the received message
* @param[in] time the number of ticks before the operation timeouts,
* the following special values are allowed:
* - @a TIME_IMMEDIATE immediate timeout.
* - @a TIME_INFINITE no timeout.
* .
* @return The operation status.
* @retval RDY_OK if a message was correctly fetched.
* @retval RDY_RESET if the mailbox was reset while waiting.
* @retval RDY_TIMEOUT if the operation timed out.
* @param[in] mbp the pointer to an initialized Mailbox object
* @param[out] msgp pointer to a message variable for the received message
* @param[in] time the number of ticks before the operation timeouts,
* the following special values are allowed:
* - @a TIME_IMMEDIATE immediate timeout.
* - @a TIME_INFINITE no timeout.
* .
* @return The operation status.
* @retval RDY_OK if a message was correctly fetched.
* @retval RDY_RESET if the mailbox was reset while waiting.
* @retval RDY_TIMEOUT if the operation timed out.
*/
msg_t chMBFetch(Mailbox *mbp, msg_t *msgp, systime_t time) {
msg_t rdymsg;
@ -208,21 +209,21 @@ msg_t chMBFetch(Mailbox *mbp, msg_t *msgp, systime_t time) {
}
/**
* @brief Retrieves a message from a mailbox.
* @brief Retrieves a message from a mailbox.
* @details The invoking thread waits until a message is posted in the mailbox
* or the specified time runs out.
*
* @param[in] mbp the pointer to an initialized Mailbox object
* @param[out] msgp pointer to a message variable for the received message
* @param[in] time the number of ticks before the operation timeouts,
* the following special values are allowed:
* - @a TIME_IMMEDIATE immediate timeout.
* - @a TIME_INFINITE no timeout.
* .
* @return The operation status.
* @retval RDY_OK if a message was correctly fetched.
* @retval RDY_RESET if the mailbox was reset while waiting.
* @retval RDY_TIMEOUT if the operation timed out.
* @param[in] mbp the pointer to an initialized Mailbox object
* @param[out] msgp pointer to a message variable for the received message
* @param[in] time the number of ticks before the operation timeouts,
* the following special values are allowed:
* - @a TIME_IMMEDIATE immediate timeout.
* - @a TIME_INFINITE no timeout.
* .
* @return The operation status.
* @retval RDY_OK if a message was correctly fetched.
* @retval RDY_RESET if the mailbox was reset while waiting.
* @retval RDY_TIMEOUT if the operation timed out.
*/
msg_t chMBFetchS(Mailbox *mbp, msg_t *msgp, systime_t time) {
msg_t rdymsg;

19
os/kernel/src/chmemcore.c
View File

@ -18,8 +18,9 @@
*/
/**
* @file chmemcore.c
* @brief Core memory manager code.
* @file chmemcore.c
* @brief Core memory manager code.
*
* @addtogroup memcore
* @{
*/
@ -55,9 +56,9 @@ void core_init(void) {
* <code>sizeof(align_t)</code>.
*
*
* @param[in] size the size of the block to be allocated
* @return A pointer to the allocated memory block.
* @retval NULL allocation failed, core memory exhausted.
* @param[in] size the size of the block to be allocated
* @return A pointer to the allocated memory block.
* @retval NULL allocation failed, core memory exhausted.
*/
void *chCoreAlloc(size_t size) {
void *p;
@ -74,9 +75,9 @@ void *chCoreAlloc(size_t size) {
* type @p align_t so it is not possible to allocate less than
* <code>sizeof(align_t)</code>.
*
* @param[in] size the size of the block to be allocated.
* @return A pointer to the allocated memory block.
* @retval NULL allocation failed, core memory exhausted.
* @param[in] size the size of the block to be allocated.
* @return A pointer to the allocated memory block.
* @retval NULL allocation failed, core memory exhausted.
*/
void *chCoreAllocI(size_t size) {
void *p;
@ -92,7 +93,7 @@ void *chCoreAllocI(size_t size) {
/**
* @brief Core memory left.
*
* @return The size, in bytes, of the free core memory.
* @return The size, in bytes, of the free core memory.
*/
size_t chCoreFree(void) {

65
os/kernel/src/chmempools.c
View File

@ -18,8 +18,9 @@
*/
/**
* @file chmempools.c
* @brief Memory Pools code.
* @file chmempools.c
* @brief Memory Pools code.
*
* @addtogroup pools
* @{
*/
@ -28,16 +29,17 @@
#if CH_USE_MEMPOOLS
/**
* @brief Initializes an empty memory pool.
* @brief Initializes an empty memory pool.
* @note The size is internally aligned to be a multiple of the @p align_t
* type size.
*
* @param[out] mp pointer to a @p MemoryPool structure
* @param[in] size the size of the objects contained in this memory pool,
* the minimum accepted size is the size of a pointer to void.
* @param[in] provider memory provider function for the memory pool or
* @p NULL if the pool is not allowed to grow automatically
*
* @note The size is internally aligned to be a multiple of the @p align_t
* type size.
* @param[out] mp pointer to a @p MemoryPool structure
* @param[in] size the size of the objects contained in this memory pool,
* the minimum accepted size is the size of a pointer to
* void.
* @param[in] provider memory provider function for the memory pool or
* @p NULL if the pool is not allowed to grow
* automatically
*/
void chPoolInit(MemoryPool *mp, size_t size, memgetfunc_t provider) {
@ -49,11 +51,11 @@ void chPoolInit(MemoryPool *mp, size_t size, memgetfunc_t provider) {
}
/**
* @brief Allocates an object from a memory pool.
* @brief Allocates an object from a memory pool.
*
* @param[in] mp pointer to a @p MemoryPool structure
* @return The pointer to the allocated object.
* @retval NULL if pool is empty.
* @param[in] mp pointer to a @p MemoryPool structure
* @return The pointer to the allocated object.
* @retval NULL if pool is empty.
*/
void *chPoolAllocI(MemoryPool *mp) {
void *objp;
@ -70,11 +72,11 @@ void *chPoolAllocI(MemoryPool *mp) {
}
/**
* @brief Allocates an object from a memory pool.
* @brief Allocates an object from a memory pool.
*
* @param[in] mp pointer to a @p MemoryPool structure
* @return The pointer to the allocated object.
* @retval NULL if pool is empty.
* @param[in] mp pointer to a @p MemoryPool structure
* @return The pointer to the allocated object.
* @retval NULL if pool is empty.
*/
void *chPoolAlloc(MemoryPool *mp) {
void *objp;
@ -86,15 +88,14 @@ void *chPoolAlloc(MemoryPool *mp) {
}
/**
* @brief Releases (or adds) an object into (to) a memory pool.
* @brief Releases (or adds) an object into (to) a memory pool.
* @note The object is assumed to be of the right size for the specified
* memory pool.
* @note The object is assumed to be memory aligned to the size of @p align_t
* type.
*
* @param[in] mp pointer to a @p MemoryPool structure
* @param[in] objp the pointer to the object to be released or added
*
* @note The object is assumed to be of the right size for the specified
* memory pool.
* @note The object is assumed to be memory aligned to the size of @p align_t
* type.
* @param[in] mp pointer to a @p MemoryPool structure
* @param[in] objp the pointer to the object to be released or added
*/
void chPoolFreeI(MemoryPool *mp, void *objp) {
struct pool_header *php = objp;
@ -107,12 +108,12 @@ void chPoolFreeI(MemoryPool *mp, void *objp) {
}
/**
* @brief Releases (or adds) an object into (to) a memory pool.
* @brief Releases (or adds) an object into (to) a memory pool.
* @note The object is assumed to be of the right size for the specified
* memory pool.
*
* @param[in] mp pointer to a @p MemoryPool structure
* @param[in] objp the pointer to the object to be released or added
* @note the object is assumed to be of the right size for the specified
* memory pool.
* @param[in] mp pointer to a @p MemoryPool structure
* @param[in] objp the pointer to the object to be released or added
*/
void chPoolFree(MemoryPool *mp, void *objp) {

60
os/kernel/src/chmsg.c
View File

@ -18,8 +18,9 @@
*/
/**
* @file chmsg.c
* @brief Messages code.
* @file chmsg.c
* @brief Messages code.
*
* @addtogroup messages
* @{
*/
@ -35,13 +36,13 @@
#endif
/**
* @brief Sends a message to the specified thread.
* @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[in] tp the pointer to the thread
* @param[in] msg the message
* @return The return message from @p chMsgRelease().
* @param[in] tp the pointer to the thread
* @param[in] msg the message
* @return The answer message from @p chMsgRelease().
*/
msg_t chMsgSend(Thread *tp, msg_t msg) {
Thread *ctp = currp;
@ -61,13 +62,14 @@ msg_t chMsgSend(Thread *tp, msg_t msg) {
}
/**
* @brief Suspends the thread and waits for an incoming message.
* @brief Suspends the thread and waits for an incoming message.
* @note You can assume that the data contained in the message is stable
* until you invoke @p chMsgRelease() because the sending thread is
* suspended until then.
*
* @return The pointer to the message structure. Note, it is always the
* message associated to the thread on the top of the messages queue.
* @note You can assume that the data contained in the message is stable until
* you invoke @p chMsgRelease() because the sending thread is
* suspended until then.
* @return The pointer to the message structure. Note, it is
* always the message associated to the thread on the
* top of the messages queue.
*/
msg_t chMsgWait(void) {
msg_t msg;
@ -81,15 +83,17 @@ msg_t chMsgWait(void) {
}
/**
* @brief Returns the next message in the queue.
* @brief Returns the next message in the queue.
* @note You can assume that the data pointed by the message is stable until
* you invoke @p chMsgRelease() because the sending thread is
* suspended until then. Always remember that the message data is not
* copied between the sender and the receiver, just a pointer is
* passed.
*
* @return The pointer to the message structure. Note, it is always the
* message associated to the thread on the top of the messages queue.
* If the queue is empty then @p NULL is returned.
* @note You can assume that the data pointed by the message is stable until
* you invoke @p chMsgRelease() because the sending thread is
* suspended until then. Always remember that the message data is not
* copied between the sender and the receiver, just a pointer is passed.
* @return The pointer to the message structure. Note, it is
* always the message associated to the thread on the
* top of the messages queue.
* @retval NULL if the queue is empty.
*/
msg_t chMsgGet(void) {
msg_t msg;
@ -101,15 +105,15 @@ msg_t chMsgGet(void) {
}
/**
* @brief Releases the thread waiting on top of the messages queue.
* @brief Releases the thread waiting on top of the messages queue.
* @note You can call this function only if there is a message already in
* the queue else the result will be unpredictable (a crash most likely).
* Exiting from the @p chMsgWait() ensures you have at least one
* message in the queue so it is not a big deal.<br>
* The condition is only tested in debug mode in order to make this
* code as fast as possible.
*
* @param[in] msg the message returned to the message sender
* @note You can call this function only if there is a message already in the
* queue else the result will be unpredictable (a crash most likely).
* Exiting from the @p chMsgWait() ensures you have at least one
* message in the queue so it is not a big deal.<br>
* The condition is only tested in debug mode in order to make this code
* as fast as possible.
* @param[in] msg the message returned to the message sender
*/
void chMsgRelease(msg_t msg) {

55
os/kernel/src/chmtx.c
View File

@ -18,8 +18,9 @@
*/
/**
* @file chmtx.c
* @brief Mutexes code.
* @file chmtx.c
* @brief Mutexes code.
*
* @addtogroup mutexes
* @{
*/
@ -29,12 +30,9 @@
#if CH_USE_MUTEXES
/**
* @brief Initializes s @p Mutex structure.
* @brief Initializes s @p Mutex structure.
*
* @param[out] mp pointer to a @p Mutex structure
* @note This function can be invoked from within an interrupt handler even if
* it is not an I-Class API because it does not touch any critical kernel
* data structure.
* @param[out] mp pointer to a @p Mutex structure
*/
void chMtxInit(Mutex *mp) {
@ -45,9 +43,9 @@ void chMtxInit(Mutex *mp) {
}
/**
* @brief Locks the specified mutex.
* @brief Locks the specified mutex.
*
* @param[in] mp pointer to the @p Mutex structure
* @param[in] mp pointer to the @p Mutex structure
*/
void chMtxLock(Mutex *mp) {
@ -59,11 +57,9 @@ void chMtxLock(Mutex *mp) {
}
/**
* @brief Locks the specified mutex.
* @brief Locks the specified mutex.
*
* @param[in] mp pointer to the @p Mutex structure
* @note This function must be called within a @p chSysLock() / @p chSysUnlock()
* block.
* @param[in] mp pointer to the @p Mutex structure
*/
void chMtxLockS(Mutex *mp) {
Thread *ctp = currp;
@ -121,14 +117,14 @@ void chMtxLockS(Mutex *mp) {
}
/**
* @brief Tries to lock a mutex.
* @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[in] mp pointer to the @p Mutex structure
* @retval TRUE if the mutex was successfully acquired
* @retval FALSE if the lock attempt failed.
* @param[in] mp pointer to the @p Mutex structure
* @retval TRUE if the mutex was successfully acquired
* @retval FALSE if the lock attempt failed.
*/
bool_t chMtxTryLock(Mutex *mp) {
bool_t b;
@ -142,15 +138,14 @@ bool_t chMtxTryLock(Mutex *mp) {
}
/**
* @brief Tries to lock a mutex.
* @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[in] mp pointer to the @p Mutex structure
* @retval TRUE if the mutex was successfully acquired
* @retval FALSE if the lock attempt failed.
* @note This function must be called within a @p chSysLock() / @p chSysUnlock()
* block.
*
* @param[in] mp pointer to the @p Mutex structure
* @retval TRUE if the mutex was successfully acquired
* @retval FALSE if the lock attempt failed.
*/
bool_t chMtxTryLockS(Mutex *mp) {
@ -165,9 +160,9 @@ bool_t chMtxTryLockS(Mutex *mp) {
}
/**
* @brief 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) {
Thread *ctp = currp;
@ -210,12 +205,10 @@ Mutex *chMtxUnlock(void) {
}
/**
* @brief Unlocks the next owned mutex in reverse lock order.
* @brief Unlocks the next owned mutex in reverse lock order.
* @note This function does not reschedule internally.
*
* @return The pointer to the unlocked mutex.
* @note This function must be called within a @p chSysLock() / @p chSysUnlock()
* block.
* @note This function does not reschedule internally.
* @return The pointer to the unlocked mutex.
*/
Mutex *chMtxUnlockS(void) {
Thread *ctp = currp;
@ -254,7 +247,7 @@ Mutex *chMtxUnlockS(void) {
}
/**
* @brief Unlocks all the mutexes owned by the invoking thread.
* @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

177
os/kernel/src/chqueues.c
View File

@ -18,8 +18,9 @@
*/
/**
* @file chqueues.c
* @brief I/O Queues code.
* @file chqueues.c
* @brief I/O Queues code.
*
* @addtogroup io_queues
* @{
*/
@ -29,18 +30,17 @@
#if CH_USE_QUEUES
/**
* @brief Initializes an input queue.
* @brief Initializes an input queue.
* @details A Semaphore is internally initialized and works as a counter of
* the bytes contained in the queue.
* @note The callback is invoked from within the S-Locked system state,
* see @ref system_states.
*
* @param[out] iqp pointer to an @p InputQueue structure
* @param[in] bp pointer to a memory area allocated as queue buffer
* @param[in] size size of the queue buffer
* @param[in] infy pointer to a callback function that is invoked when
* data is read from the queue. The value can be @p NULL.
*
* @note The callback is invoked from within the S-Locked system state,
* see @ref system_states.
* @param[out] iqp pointer to an @p InputQueue structure
* @param[in] bp pointer to a memory area allocated as queue buffer
* @param[in] size size of the queue buffer
* @param[in] infy pointer to a callback function that is invoked when
* data is read from the queue. The value can be @p NULL.
*/
void chIQInit(InputQueue *iqp, uint8_t *bp, size_t size, qnotify_t infy) {
@ -51,13 +51,13 @@ void chIQInit(InputQueue *iqp, uint8_t *bp, size_t size, qnotify_t infy) {
}
/**
* @brief Resets an input queue.
* @brief Resets an input queue.
* @details All the data in the input queue is erased and lost, any waiting
* thread is resumed with status @p Q_RESET.
* @note A reset operation can be used by a low level driver in order to obtain
* immediate attention from the high level layers.
* @note A reset operation can be used by a low level driver in order to
* obtain immediate attention from the high level layers.
*
* @param[in] iqp pointer to an @p InputQueue structure
* @param[in] iqp pointer to an @p InputQueue structure
*/
void chIQResetI(InputQueue *iqp) {
@ -66,14 +66,15 @@ void chIQResetI(InputQueue *iqp) {
}
/**
* @brief Input queue write.
* @brief Input queue write.
* @details A byte value is written into the low end of an input queue.
*
* @param[in] iqp pointer to an @p InputQueue structure
* @param[in] b the byte value to be written in the queue
* @return The operation status, it can be one of:
* @retval Q_OK if the operation has been completed with success.
* @retval Q_FULL if the queue is full and the operation cannot be completed.
* @param[in] iqp pointer to an @p InputQueue structure
* @param[in] b the byte value to be written in the queue
* @return The operation status, it can be one of:
* @retval Q_OK if the operation has been completed with success.
* @retval Q_FULL if the queue is full and the operation cannot be
* completed.
*/
msg_t chIQPutI(InputQueue *iqp, uint8_t b) {
@ -88,20 +89,20 @@ msg_t chIQPutI(InputQueue *iqp, uint8_t b) {
}
/**
* @brief Input queue read with timeout.
* @brief Input queue read with timeout.
* @details This function reads a byte value from an input queue. If the queue
* is empty then the calling thread is suspended until a byte arrives
* in the queue or a timeout occurs.
*
* @param[in] iqp pointer to an @p InputQueue structure
* @param[in] time the number of ticks before the operation timeouts,
* the following special values are allowed:
* - @a TIME_IMMEDIATE immediate timeout.
* - @a TIME_INFINITE no timeout.
* .
* @return A byte value from the queue or:
* @retval Q_TIMEOUT if the specified time expired.
* @retval Q_RESET if the queue was reset.
* @param[in] iqp pointer to an @p InputQueue structure
* @param[in] time the number of ticks before the operation timeouts,
* the following special values are allowed:
* - @a TIME_IMMEDIATE immediate timeout.
* - @a TIME_INFINITE no timeout.
* .
* @return A byte value from the queue or:
* @retval Q_TIMEOUT if the specified time expired.
* @retval Q_RESET if the queue was reset.
*/
msg_t chIQGetTimeout(InputQueue *iqp, systime_t time) {
uint8_t b;
@ -124,25 +125,25 @@ msg_t chIQGetTimeout(InputQueue *iqp, systime_t time) {
}
/**
* @brief Input queue read with timeout.
* @brief Input queue read with timeout.
* @details The function reads data from an input queue into a buffer. The
* operation completes when the specified amount of data has been
* transferred or after the specified timeout or if the queue has
* been reset.
* @note The function is not atomic, if you need atomicity it is suggested
* to use a semaphore or a mutex for mutual exclusion.
* @note The queue callback is invoked before entering a sleep state and at
* the end of the transfer.
* @note The function is not atomic, if you need atomicity it is suggested
* to use a semaphore or a mutex for mutual exclusion.
* @note The queue callback is invoked before entering a sleep state and at
* the end of the transfer.
*
* @param[in] iqp pointer to an @p InputQueue structure
* @param[out] bp pointer to the data buffer
* @param[in] n the maximum amount of data to be transferred
* @param[in] time the number of ticks before the operation timeouts,
* the following special values are allowed:
* - @a TIME_IMMEDIATE immediate timeout.
* - @a TIME_INFINITE no timeout.
* .
* @return The number of bytes effectively transferred.
* @param[in] iqp pointer to an @p InputQueue structure
* @param[out] bp pointer to the data buffer
* @param[in] n the maximum amount of data to be transferred
* @param[in] time the number of ticks before the operation timeouts,
* the following special values are allowed:
* - @a TIME_IMMEDIATE immediate timeout.
* - @a TIME_INFINITE no timeout.
* .
* @return The number of bytes effectively transferred.
*/
size_t chIQReadTimeout(InputQueue *iqp, uint8_t *bp,
size_t n, systime_t time) {
@ -180,18 +181,17 @@ size_t chIQReadTimeout(InputQueue *iqp, uint8_t *bp,
}
/**
* @brief Initializes an output queue.
* @brief Initializes an output queue.
* @details A Semaphore is internally initialized and works as a counter of
* the free bytes in the queue.
* @note The callback is invoked from within the S-Locked system state,
* see @ref system_states.
*
* @param[out] oqp pointer to an @p OutputQueue structure
* @param[in] bp pointer to a memory area allocated as queue buffer
* @param[in] size size of the queue buffer
* @param[in] onfy pointer to a callback function that is invoked when
* data is written to the queue. The value can be @p NULL.
*
* @note The callback is invoked from within the S-Locked system state,
* see @ref system_states.
* @param[out] oqp pointer to an @p OutputQueue structure
* @param[in] bp pointer to a memory area allocated as queue buffer
* @param[in] size size of the queue buffer
* @param[in] onfy pointer to a callback function that is invoked when
* data is written to the queue. The value can be @p NULL.
*/
void chOQInit(OutputQueue *oqp, uint8_t *bp, size_t size, qnotify_t onfy) {
@ -202,14 +202,13 @@ void chOQInit(OutputQueue *oqp, uint8_t *bp, size_t size, qnotify_t onfy) {
}
/**
* @brief Resets an output queue.
* @brief Resets an output queue.
* @details All the data in the output queue is erased and lost, any waiting
* thread is resumed with status @p Q_RESET.
* @note A reset operation can be used by a low level driver in order to
* obtain immediate attention from the high level layers.
*
* @param[in] oqp pointer to an @p OutputQueue structure
*
* @note A reset operation can be used by a low level driver in order to obtain
* immediate attention from the high level layers.
* @param[in] oqp pointer to an @p OutputQueue structure
*/
void chOQResetI(OutputQueue *oqp) {
@ -218,22 +217,22 @@ void chOQResetI(OutputQueue *oqp) {
}
/**
* @brief Output queue write with timeout.
* @brief Output queue write with timeout.
* @details This function writes a byte value to an output queue. If the queue
* is full then the calling thread is suspended until there is space
* in the queue or a timeout occurs.
*
* @param[in] oqp pointer to an @p OutputQueue structure
* @param[in] b the byte value to be written in the queue
* @param[in] time the number of ticks before the operation timeouts,
* the following special values are allowed:
* - @a TIME_IMMEDIATE immediate timeout.
* - @a TIME_INFINITE no timeout.
* .
* @return The operation status:
* @retval Q_OK if the operation succeeded.
* @retval Q_TIMEOUT if the specified time expired.
* @retval Q_RESET if the queue was reset.
* @param[in] oqp pointer to an @p OutputQueue structure
* @param[in] b the byte value to be written in the queue
* @param[in] time the number of ticks before the operation timeouts,
* the following special values are allowed:
* - @a TIME_IMMEDIATE immediate timeout.
* - @a TIME_INFINITE no timeout.
* .
* @return The operation status:
* @retval Q_OK if the operation succeeded.
* @retval Q_TIMEOUT if the specified time expired.
* @retval Q_RESET if the queue was reset.
*/
msg_t chOQPutTimeout(OutputQueue *oqp, uint8_t b, systime_t time) {
msg_t msg;
@ -255,12 +254,12 @@ msg_t chOQPutTimeout(OutputQueue *oqp, uint8_t b, systime_t time) {
}
/**
* @brief Output queue read.
* @brief Output queue read.
* @details A byte value is read from the low end of an output queue.
*
* @param[in] oqp pointer to an @p OutputQueue structure
* @return The byte value from the queue or:
* @retval Q_EMPTY if the queue is empty.
* @param[in] oqp pointer to an @p OutputQueue structure
* @return The byte value from the queue or:
* @retval Q_EMPTY if the queue is empty.
*/
msg_t chOQGetI(OutputQueue *oqp) {
uint8_t b;
@ -276,25 +275,25 @@ msg_t chOQGetI(OutputQueue *oqp) {
}
/**
* @brief Output queue write with timeout.
* @brief Output queue write with timeout.
* @details The function writes data from a buffer to an output queue. The
* operation completes when the specified amount of data has been
* transferred or after the specified timeout or if the queue has
* been reset.
* @note The function is not atomic, if you need atomicity it is suggested
* to use a semaphore or a mutex for mutual exclusion.
* @note The queue callback is invoked before entering a sleep state and at
* the end of the transfer.
* @note The function is not atomic, if you need atomicity it is suggested
* to use a semaphore or a mutex for mutual exclusion.
* @note The queue callback is invoked before entering a sleep state and at
* the end of the transfer.
*
* @param[in] oqp pointer to an @p OutputQueue structure
* @param[out] bp pointer to the data buffer
* @param[in] n the maximum amount of data to be transferred
* @param[in] time the number of ticks before the operation timeouts,
* the following special values are allowed:
* - @a TIME_IMMEDIATE immediate timeout.
* - @a TIME_INFINITE no timeout.
* .
* @return The number of bytes effectively transferred.
* @param[in] oqp pointer to an @p OutputQueue structure
* @param[out] bp pointer to the data buffer
* @param[in] n the maximum amount of data to be transferred
* @param[in] time the number of ticks before the operation timeouts,
* the following special values are allowed:
* - @a TIME_IMMEDIATE immediate timeout.
* - @a TIME_INFINITE no timeout.
* .
* @return The number of bytes effectively transferred.
*/
size_t chOQWriteTimeout(OutputQueue *oqp, const uint8_t *bp,
size_t n, systime_t time) {

13
os/kernel/src/chregistry.c
View File

@ -18,8 +18,9 @@
*/
/**
* @file chregistry.c
* @brief Threads registry code.
* @file chregistry.c
* @brief Threads registry code.
*
* @addtogroup registry
* @{
*/
@ -36,7 +37,7 @@
* @note This function cannot return @p NULL because there is always at
* least one thread in the system.
*
* @return A reference to the first thread.
* @return A reference to the first thread.
*/
Thread *chRegFirstThread(void) {
Thread *tp;
@ -52,9 +53,9 @@ Thread *chRegFirstThread(void) {
* @details The reference counter of the specified thread is decremented and
* the reference counter of the returned thread is incremented.
*
* @param[in] tp pointer to the thread
* @return A reference to the next thread.
* @retval NULL if there is no next thread.
* @param[in] tp pointer to the thread
* @return A reference to the next thread.
* @retval NULL if there is no next thread.
*/
Thread *chRegNextThread(Thread *tp) {

111
os/kernel/src/chschd.c
View File

@ -18,8 +18,9 @@
*/
/**
* @file chschd.c
* @brief Scheduler code.
* @file chschd.c
* @brief Scheduler code.
*
* @addtogroup scheduler
* @{
*/
@ -27,14 +28,13 @@
#include "ch.h"
/**
* @brief Ready list header.
* @brief Ready list header.
*/
ReadyList rlist;
/**
* @brief Scheduler initialization.
*
* @note Internally invoked by the @p chSysInit().
* @brief Scheduler initialization.
* @note Internally invoked by the @p chSysInit(), not an API.
*/
void scheduler_init(void) {
@ -49,12 +49,12 @@ void scheduler_init(void) {
}
/**
* @brief Inserts a thread in the Ready List.
* @brief Inserts a thread in the Ready List.
* @note The function does not reschedule, the @p chSchRescheduleS() should
* be called soon after.
*
* @param[in] tp the Thread to be made ready
* @return The Thread pointer.
* @note The function does not reschedule, the @p chSchRescheduleS() should
* be called soon after.
* @param[in] tp the Thread to be made ready
* @return The Thread pointer.
*/
#if CH_OPTIMIZE_SPEED
/* NOTE: it is inlined in this module only.*/
@ -76,11 +76,11 @@ Thread *chSchReadyI(Thread *tp) {
}
/**
* @brief Puts the current thread to sleep into the specified state.
* @brief Puts the current thread to sleep into the specified state.
* @details The thread goes into a sleeping state. The @ref thread_states are
* described into @p threads.h.
*
* @param[in] newstate the new thread state
* @param[in] newstate the new thread state
*/
void chSchGoSleepS(tstate_t newstate) {
Thread *otp;
@ -121,24 +121,24 @@ static void wakeup(void *p) {
}
/**
* @brief Puts the current thread to sleep into the specified state with
* timeout specification.
* @brief Puts the current thread to sleep into the specified state with
* timeout specification.
* @details The thread goes into a sleeping state, if it is not awakened
* explicitly within the specified timeout then it is forcibly
* awakened with a @p RDY_TIMEOUT low level message. The @ref
* thread_states are described into @p threads.h.
*
* @param[in] newstate the new thread state
* @param[in] time the number of ticks before the operation timeouts, the
* special values are handled as follow:
* - @a TIME_INFINITE the thread enters an infinite sleep
* state, this is equivalent to invoking @p chSchGoSleepS()
* but, of course, less efficient.
* - @a TIME_IMMEDIATE this value is accepted but interpreted
* as a normal time specification not as an immediate timeout
* specification.
* .
* @return The wakeup message.
* @param[in] newstate the new thread state
* @param[in] time the number of ticks before the operation timeouts, the
* special values are handled as follow:
* - @a TIME_INFINITE the thread enters an infinite sleep
* state, this is equivalent to invoking
* @p chSchGoSleepS() but, of course, less efficient.
* - @a TIME_IMMEDIATE this value is accepted but
* interpreted as a normal time specification not as an
* immediate timeout specification.
* .
* @return The wakeup message.
* @retval RDY_TIMEOUT if a timeout occurs.
*/
msg_t chSchGoSleepTimeoutS(tstate_t newstate, systime_t time) {
@ -157,24 +157,25 @@ msg_t chSchGoSleepTimeoutS(tstate_t newstate, systime_t time) {
}
/**
* @brief 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.
* @note It is equivalent to a @p chSchReadyI() followed by a
* @p chSchRescheduleS() but much more efficient.
* @note The function assumes that the current thread has the highest
* priority.
*
* @param[in] ntp the Thread to be made ready
* @param[in] msg message to the awakened thread
* @note It is equivalent to a @p chSchReadyI() followed by a
* @p chSchRescheduleS() but much more efficient.
* @note The function assumes that the current thread has the highest priority
* @param[in] ntp the Thread to be made ready
* @param[in] msg message to the awakened thread
*/
void chSchWakeupS(Thread *ntp, msg_t msg) {
ntp->p_u.rdymsg = msg;
/* If the waken thread has a not-greater priority than the current
* one then it is just inserted in the ready list else it made
* running immediately and the invoking thread goes in the ready
* list instead.*/
one then it is just inserted in the ready list else it made
running immediately and the invoking thread goes in the ready
list instead.*/
if (ntp->p_prio <= currp->p_prio)
chSchReadyI(ntp);
else {
@ -190,10 +191,9 @@ void chSchWakeupS(Thread *ntp, msg_t msg) {
}
/**
* @brief Switches to the first thread on the runnable queue.
*
* @note It is intended to be called if @p chSchRescRequiredI() evaluates to
* @p TRUE.
* @brief Switches to the first thread on the runnable queue.
* @note It is intended to be called if @p chSchRescRequiredI() evaluates
* to @p TRUE.
*/
void chSchDoRescheduleI(void) {
@ -209,7 +209,7 @@ void chSchDoRescheduleI(void) {
}
/**
* @brief Performs a reschedulation 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
* the ready list then make the higher priority thread running.
*/
@ -220,34 +220,33 @@ void chSchRescheduleS(void) {
}
/**
* @brief Evaluates if a reschedulation is required.
* @brief Evaluates if a reschedulation is required.
* @details The decision is taken by comparing the relative priorities and
* depending on the state of the round robin timeout counter.
* @note This function is meant to be used in the timer interrupt handler
* where @p chVTDoTickI() is invoked.
*
* @retval TRUE if there is a thread that should go in running state.
* @retval FALSE if a reschedulation is not required.
*
* @note This function is meant to be used in the timer interrupt handler
* where @p chVTDoTickI() is invoked.
* @retval TRUE if there is a thread that should go in running state.
* @retval FALSE if a reschedulation is not required.
*/
bool_t chSchIsRescRequiredExI(void) {
tprio_t p1 = firstprio(&rlist.r_queue);
tprio_t p2 = currp->p_prio;
#if CH_TIME_QUANTUM > 0
/* If the running thread has not reached its time quantum, reschedule only
* if the first thread on the ready queue has a higher priority.
* Otherwise, if the running thread has used up its time quantum, reschedule
* if the first thread on the ready queue has equal or higher priority.*/
if the first thread on the ready queue has a higher priority.
Otherwise, if the running thread has used up its time quantum, reschedule
if the first thread on the ready queue has equal or higher priority.*/
return rlist.r_preempt ? p1 > p2 : p1 >= p2;
#else
/* If the round robin feature is not enabled then performs a simpler
* comparison.*/
/* If the round robin preemption feature is not enabled then performs a
simpler comparison.*/
return p1 > p2;
#endif
}
/**
* @brief Yields the time slot.
* @brief Yields the time slot.
* @details Yields the CPU control to the next thread in the ready list with
* equal priority, if any.
*/
@ -257,11 +256,9 @@ void chSchDoYieldS(void) {
Thread *cp = (Thread *)&rlist.r_queue;
Thread *otp = currp;
/*
* Note, the following insertion code works because we know that on the
* ready list there is at least one thread with priority equal or higher
* than the current one.
*/
/* Note, the following insertion code works because we know that on the
ready list there is at least one thread with priority equal or higher
than the current one.*/
otp->p_state = THD_STATE_READY;
do {
cp = cp->p_prev;

135
os/kernel/src/chsem.c
View File

@ -18,8 +18,9 @@
*/
/**
* @file chsem.c
* @brief Semaphores code.
* @file chsem.c
* @brief Semaphores code.
*
* @addtogroup semaphores
* @{
*/
@ -35,13 +36,11 @@
#endif
/**
* @brief Initializes a semaphore with the specified counter value.
* @brief Initializes a semaphore with the specified counter value.
*
* @param[out] sp pointer to a @p Semaphore structure
* @param[in] n initial value of the semaphore counter. Must be non-negative.
* @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.
* @param[out] sp pointer to a @p Semaphore structure
* @param[in] n initial value of the semaphore counter. Must be
* non-negative.
*/
void chSemInit(Semaphore *sp, cnt_t n) {
@ -52,13 +51,14 @@ void chSemInit(Semaphore *sp, cnt_t n) {
}
/**
* @brief Performs a reset operation on the semaphore.
* @brief Performs a reset operation on the semaphore.
* @note The released threads can recognize they were waked up by a reset
* rather than a signal because the @p chSemWait() will return
* @p RDY_RESET instead of @p RDY_OK.
*
* @param[in] sp pointer to a @p Semaphore structure
* @param[in] n the new value of the semaphore counter. The value must be non-negative.
* @note The released threads can recognize they were waked up by a reset
* instead than a signal because the @p chSemWait() will return
* @p RDY_RESET instead of @p RDY_OK.
* @param[in] sp pointer to a @p Semaphore structure
* @param[in] n the new value of the semaphore counter. The value must
* be non-negative.
*/
void chSemReset(Semaphore *sp, cnt_t n) {
@ -69,14 +69,15 @@ void chSemReset(Semaphore *sp, cnt_t n) {
}
/**
* @brief Performs a reset operation on the semaphore.
* @brief Performs a reset operation on the semaphore.
* @note The released threads can recognize they were waked up by a reset
* rather than a signal because the @p chSemWait() will return
* @p RDY_RESET instead of @p RDY_OK.
* @note This function does not reschedule.
*
* @param[in] sp pointer to a @p Semaphore structure
* @param[in] n the new value of the semaphore counter. The value must be non-negative.
* @note The released threads can recognize they were waked up by a reset
* instead than a signal because the @p chSemWait() will return
* @p RDY_RESET instead of @p RDY_OK.
* @note This function does not reschedule.
* @param[in] sp pointer to a @p Semaphore structure
* @param[in] n the new value of the semaphore counter. The value must
* be non-negative.
*/
void chSemResetI(Semaphore *sp, cnt_t n) {
cnt_t cnt;
@ -90,11 +91,11 @@ void chSemResetI(Semaphore *sp, cnt_t n) {
}
/**
* @brief Performs a wait operation on a semaphore.
* @brief Performs a wait operation on a semaphore.
*
* @param[in] 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().
* @param[in] 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().
*/
msg_t chSemWait(Semaphore *sp) {
msg_t msg;
@ -106,13 +107,11 @@ msg_t chSemWait(Semaphore *sp) {
}
/**
* @brief Performs a wait operation on a semaphore.
* @brief Performs a wait operation on a semaphore.
*
* @param[in] 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().
* @note This function must be called with interrupts disabled.
* @note This function cannot be called by an interrupt handler.
* @param[in] 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().
*/
msg_t chSemWaitS(Semaphore *sp) {
@ -128,18 +127,18 @@ msg_t chSemWaitS(Semaphore *sp) {
}
/**
* @brief Performs a wait operation on a semaphore with timeout specification.
* @brief Performs a wait operation on a semaphore with timeout specification.
*
* @param[in] sp pointer to a @p Semaphore structure
* @param[in] time the number of ticks before the operation timeouts,
* the following special values are allowed:
* - @a TIME_IMMEDIATE immediate timeout.
* - @a TIME_INFINITE no timeout.
* .
* @retval RDY_OK if the semaphore was signaled or not taken.
* @retval RDY_RESET if the semaphore was reset using @p chSemReset().
* @retval RDY_TIMEOUT if the semaphore was not signaled or reset within the
* specified timeout.
* @param[in] sp pointer to a @p Semaphore structure
* @param[in] time the number of ticks before the operation timeouts,
* the following special values are allowed:
* - @a TIME_IMMEDIATE immediate timeout.
* - @a TIME_INFINITE no timeout.
* .
* @retval RDY_OK if the semaphore was signaled or not taken.
* @retval RDY_RESET if the semaphore was reset using @p chSemReset().
* @retval RDY_TIMEOUT if the semaphore was not signaled or reset within the
* specified timeout.
*/
msg_t chSemWaitTimeout(Semaphore *sp, systime_t time) {
msg_t msg;
@ -151,18 +150,18 @@ msg_t chSemWaitTimeout(Semaphore *sp, systime_t time) {
}
/**
* @brief Performs a wait operation on a semaphore with timeout specification.
* @brief Performs a wait operation on a semaphore with timeout specification.
*
* @param[in] sp pointer to a @p Semaphore structure
* @param[in] time the number of ticks before the operation timeouts,
* the following special values are allowed:
* - @a TIME_IMMEDIATE immediate timeout.
* - @a TIME_INFINITE no timeout.
* .
* @retval RDY_OK if the semaphore was signaled or not taken.
* @retval RDY_RESET if the semaphore was reset using @p chSemReset().
* @retval RDY_TIMEOUT if the semaphore was not signaled or reset within the specified
* timeout.
* @param[in] sp pointer to a @p Semaphore structure
* @param[in] time the number of ticks before the operation timeouts,
* the following special values are allowed:
* - @a TIME_IMMEDIATE immediate timeout.
* - @a TIME_INFINITE no timeout.
* .
* @retval RDY_OK if the semaphore was signaled or not taken.
* @retval RDY_RESET if the semaphore was reset using @p chSemReset().
* @retval RDY_TIMEOUT if the semaphore was not signaled or reset within the
* specified timeout.
*/
msg_t chSemWaitTimeoutS(Semaphore *sp, systime_t time) {
@ -181,11 +180,9 @@ msg_t chSemWaitTimeoutS(Semaphore *sp, systime_t time) {
}
/**
* @brief Performs a signal operation on a semaphore.
* @brief Performs a signal operation on a semaphore.
*
* @param[in] 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.
* @param[in] sp pointer to a @p Semaphore structure
*/
void chSemSignal(Semaphore *sp) {
@ -198,19 +195,17 @@ void chSemSignal(Semaphore *sp) {
}
/**
* @brief Performs a signal operation on a semaphore.
* @brief Performs a signal operation on a semaphore.
* @note This function does not reschedule.
*
* @param[in] 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.
* @note This function does not reschedule.
* @param[in] sp pointer to a @p Semaphore structure
*/
void chSemSignalI(Semaphore *sp) {
chDbgCheck(sp != NULL, "chSemSignalI");
if (sp->s_cnt++ < 0) {
/* NOTE: It is done this way in order to allow a tail call on
/* note, it is done this way in order to allow a tail call on
chSchReadyI().*/
Thread *tp = fifo_remove(&sp->s_queue);
tp->p_u.rdymsg = RDY_OK;
@ -220,14 +215,14 @@ void chSemSignalI(Semaphore *sp) {
#if CH_USE_SEMSW
/**
* @brief Performs atomic signal and wait operations on two semaphores.
* @brief Performs atomic signal and wait operations on two semaphores.
* @note The function is available only if the @p CH_USE_SEMSW
* option is enabled in @p chconf.h.
*
* @param[in] sps pointer to a @p Semaphore structure to be signaled
* @param[in] spw pointer to a @p Semaphore structure to be wait on
* @retval RDY_OK if the semaphore was signaled or not taken.
* @retval RDY_RESET if the semaphore was reset using @p chSemReset().
* @note The function is available only if the @p CH_USE_SEMSW
* option is enabled in @p chconf.h.
* @param[in] sps pointer to a @p Semaphore structure to be signaled
* @param[in] spw pointer to a @p Semaphore structure to be wait on
* @retval RDY_OK if the semaphore was signaled or not taken.
* @retval RDY_RESET if the semaphore was reset using @p chSemReset().
*/
msg_t chSemSignalWait(Semaphore *sps, Semaphore *spw) {
msg_t msg;

35
os/kernel/src/chsys.c
View File

@ -18,8 +18,9 @@
*/
/**
* @file chsys.c
* @brief System related code.
* @file chsys.c
* @brief System related code.
*
* @addtogroup system
* @{
*/
@ -29,7 +30,7 @@
static WORKING_AREA(idle_thread_wa, IDLE_THREAD_STACK_SIZE);
/**
* @brief This function implements the idle thread infinite loop.
* @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
@ -48,13 +49,12 @@ static void idle_thread(void *p) {
}
/**
* @brief ChibiOS/RT initialization.
* @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.
* @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.
*/
void chSysInit(void) {
static Thread mainthread;
@ -72,29 +72,26 @@ void chSysInit(void) {
trace_init();
#endif
/*
* Now this instructions flow becomes the main thread.
*/
/* Now this instructions flow becomes the main thread.*/
(currp = init_thread(&mainthread, NORMALPRIO))->p_state = THD_STATE_CURRENT;
chSysEnable();
/*
* This thread has the lowest priority in the system, its role is just to
* serve interrupts in its context while keeping the lowest energy saving
* mode compatible with the system status.
*/
/* This thread has the lowest priority in the system, its role is just to
serve interrupts in its context while keeping the lowest energy saving
mode compatible with the system status.*/
chThdCreateStatic(idle_thread_wa, sizeof(idle_thread_wa), IDLEPRIO,
(tfunc_t)idle_thread, NULL);
}
/**
* @brief Handles time ticks for round robin preemption and timer increments.
* @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.
* @note The frequency of the timer determines the system tick granularity
* and, together with the @p CH_TIME_QUANTUM macro, the round robin
* interval.
*/
void chSysTimerHandlerI(void) {

126
os/kernel/src/chthreads.c
View File

@ -18,8 +18,9 @@
*/
/**
* @file chthreads.c
* @brief Threads code.
* @file chthreads.c
* @brief Threads code.
*
* @addtogroup threads
* @{
*/
@ -29,10 +30,9 @@
/**
* @brief Initializes a thread structure.
*
* @param[in] tp pointer to the thread
* @param[in] prio the priority level for the new thread
*
* @return The same thread pointer passed as parameter.
* @param[in] tp pointer to the thread
* @param[in] prio the priority level for the new thread
* @return The same thread pointer passed as parameter.
*/
Thread *init_thread(Thread *tp, tprio_t prio) {
@ -86,14 +86,14 @@ static void memfill(uint8_t *startp, uint8_t *endp, uint8_t v) {
* even if it is not an I-Class API because it does not touch
* any critical kernel data structure.
*
* @param[out] wsp pointer to a working area dedicated to the thread stack
* @param[in] size size of the working area
* @param[in] prio the priority level for the new thread
* @param[in] pf the thread function
* @param[in] arg an argument passed to the thread function. It can be
* @p NULL.
* @return The pointer to the @p Thread structure allocated for the
* thread into the working space area.
* @param[out] wsp pointer to a working area dedicated to the thread stack
* @param[in] size size of the working area
* @param[in] prio the priority level for the new thread
* @param[in] pf the thread function
* @param[in] arg an argument passed to the thread function. It can be
* @p NULL.
* @return The pointer to the @p Thread structure allocated for
* the thread into the working space area.
*/
Thread *chThdInit(void *wsp, size_t size, tprio_t prio, tfunc_t pf, void *arg) {
/* Thread structure is layed out in the lower part of the thread workspace */
@ -116,14 +116,14 @@ Thread *chThdInit(void *wsp, size_t size, tprio_t prio, tfunc_t pf, void *arg) {
* @note A thread can terminate by calling @p chThdExit() or by simply
* returning from its main function.
*
* @param[out] wsp pointer to a working area dedicated to the thread stack
* @param[in] size size of the working area
* @param[in] prio the priority level for the new thread
* @param[in] pf the thread function
* @param[in] arg an argument passed to the thread function. It can be
* @p NULL.
* @return The pointer to the @p Thread structure allocated for the
* thread into the working space area.
* @param[out] wsp pointer to a working area dedicated to the thread stack
* @param[in] size size of the working area
* @param[in] prio the priority level for the new thread
* @param[in] pf the thread function
* @param[in] arg an argument passed to the thread function. It can be
* @p NULL.
* @return The pointer to the @p Thread structure allocated for
* the thread into the working space area.
*/
Thread *chThdCreateStatic(void *wsp, size_t size,
tprio_t prio, tfunc_t pf, void *arg) {
@ -142,16 +142,16 @@ Thread *chThdCreateStatic(void *wsp, size_t size,
* @p CH_USE_HEAP and @p CH_USE_WAITEXIT options are enabled
* in @p chconf.h.
*
* @param[in] heapp heap from which allocate the memory or @p NULL for the
* default heap
* @param[in] size size of the working area to be allocated
* @param[in] prio the priority level for the new thread
* @param[in] pf the thread function
* @param[in] arg an argument passed to the thread function. It can be
* @p NULL.
* @return The pointer to the @p Thread structure allocated for the
* thread into the working space area.
* @retval NULL if the memory cannot be allocated.
* @param[in] heapp heap from which allocate the memory or @p NULL for the
* default heap
* @param[in] size size of the working area to be allocated
* @param[in] prio the priority level for the new thread
* @param[in] pf the thread function
* @param[in] arg an argument passed to the thread function. It can be
* @p NULL.
* @return The pointer to the @p Thread structure allocated for
* the thread into the working space area.
* @retval NULL if the memory cannot be allocated.
*/
Thread *chThdCreateFromHeap(MemoryHeap *heapp, size_t size,
tprio_t prio, tfunc_t pf, void *arg) {
@ -179,15 +179,14 @@ Thread *chThdCreateFromHeap(MemoryHeap *heapp, size_t size,
* @p CH_USE_MEMPOOLS and @p CH_USE_WAITEXIT options are enabled
* in @p chconf.h.
*
* @param[in] mp pointer to the memory pool object
* @param[in] prio the priority level for the new thread
* @param[in] pf the thread function
* @param[in] arg an argument passed to the thread function. It can be
* @p NULL.
* @return The pointer to the @p Thread structure allocated for the
* thread into the working space area or @p NULL if the memory cannot
* be allocated.
* @retval NULL if the memory pool is empty.
* @param[in] mp pointer to the memory pool object
* @param[in] prio the priority level for the new thread
* @param[in] pf the thread function
* @param[in] arg an argument passed to the thread function. It can be
* @p NULL.
* @return The pointer to the @p Thread structure allocated for
* the thread into the working space area.
* @retval NULL if the memory pool is empty.
*/
Thread *chThdCreateFromMemoryPool(MemoryPool *mp, tprio_t prio,
tfunc_t pf, void *arg) {
@ -213,8 +212,8 @@ Thread *chThdCreateFromMemoryPool(MemoryPool *mp, tprio_t prio,
* current priority that could be higher than the real priority
* because the priority inheritance mechanism.
*
* @param[in] newprio the new priority level of the running thread
* @return The old priority level.
* @param[in] newprio the new priority level of the running thread
* @return The old priority level.
*/
tprio_t chThdSetPriority(tprio_t newprio) {
tprio_t oldprio;
@ -241,8 +240,8 @@ tprio_t chThdSetPriority(tprio_t newprio) {
* @brief Resumes a suspended thread.
* @note Use this function to resume threads created with @p chThdInit().
*
* @param[in] tp pointer to the thread
* @return The pointer to the thread.
* @param[in] tp pointer to the thread
* @return The pointer to the thread.
*/
Thread *chThdResume(Thread *tp) {
@ -261,7 +260,7 @@ Thread *chThdResume(Thread *tp) {
* its @p p_flags field. The thread can read this status by
* invoking @p chThdShouldTerminate() and then terminate cleanly.
*
* @param[in] tp pointer to the thread
* @param[in] tp pointer to the thread
*/
void chThdTerminate(Thread *tp) {
@ -273,14 +272,14 @@ void chThdTerminate(Thread *tp) {
/**
* @brief Suspends the invoking thread for the specified time.
*
* @param[in] time the delay in system ticks, the special values are handled
* as follow:
* - @a TIME_INFINITE the thread enters an infinite sleep
* state.
* - @a TIME_IMMEDIATE this value is accepted but interpreted
* as a normal time specification not as an immediate
* timeout specification.
* .
* @param[in] time the delay in system ticks, the special values are
* handled as follow:
* - @a TIME_INFINITE the thread enters an infinite sleep
* state.
* - @a TIME_IMMEDIATE this value is accepted but
* interpreted as a normal time specification not as an
* immediate timeout specification.
* .
*/
void chThdSleep(systime_t time) {
@ -295,7 +294,7 @@ void chThdSleep(systime_t time) {
* @brief Suspends the invoking thread until the system time arrives to the
* specified value.
*
* @param[in] time absolute system time
* @param[in] time absolute system time
*/
void chThdSleepUntil(systime_t time) {
@ -320,9 +319,8 @@ void chThdYield(void) {
/**
* @brief Terminates the current thread by specifying an exit status code.
*
* @param[in] msg thread exit code. The code can be retrieved by using
* @p chThdWait().
* @return The same thread pointer passed as parameter.
* @param[in] msg thread exit code. The code can be retrieved by using
* @p chThdWait().
*/
void chThdExit(msg_t msg) {
Thread *tp = currp;
@ -344,9 +342,9 @@ void chThdExit(msg_t msg) {
/**
* @brief Adds a reference to a thread object.
*
* @param[in] tp pointer to the thread
* @return The same thread pointer passed as parameter representing the
* new reference.
* @param[in] tp pointer to the thread
* @return The same thread pointer passed as parameter
* representing the new reference.
*/
Thread *chThdAddRef(Thread *tp) {
@ -364,7 +362,7 @@ Thread *chThdAddRef(Thread *tp) {
* returned to the proper allocator.
* @note Static threads are not affected.
*
* @param[in] tp pointer to the thread
* @param[in] tp pointer to the thread
*/
void chThdRelease(Thread *tp) {
trefs_t refs;
@ -419,8 +417,8 @@ void chThdRelease(Thread *tp) {
* @note If @p CH_USE_DYNAMIC is not specified this function just waits for
* the thread termination, no memory allocators are involved.
*
* @param[in] tp pointer to the thread
* @return The exit code from the terminated thread
* @param[in] tp pointer to the thread
* @return The exit code from the terminated thread.
*/
msg_t chThdWait(Thread *tp) {
msg_t msg;

59
os/kernel/src/chvt.c
View File

@ -18,20 +18,23 @@
*/
/**
* @file chvt.c
* @brief Time and Virtual Timers related code.
* @file chvt.c
* @brief Time and Virtual Timers related code.
*
* @addtogroup time
* @{
*/
#include "ch.h"
/**
* @brief Virtual timers delta list header.
*/
VTList vtlist;
/**
* @brief Virtual Timers initialization.
*
* @note Internal use only.
* @brief Virtual Timers initialization.
* @note Internal use only.
*/
void vt_init(void) {
@ -41,19 +44,20 @@ void vt_init(void) {
}
/**
* @brief Enables a virtual timer.
* @brief Enables a virtual timer.
* @note The associated function is invoked by an interrupt handler within
* the I-Locked state, see @ref system_states.
*
* @param[out] vtp the @p VirtualTimer structure pointer
* @param[in] time the number of time ticks, the value @p TIME_INFINITE is not
* allowed. The value @p TIME_IMMEDIATE is allowed but
* interpreted as a normal time specification not as an
* immediate timeout specification.
* @param[in] vtfunc the timer callback function. After invoking the callback
* the timer is disabled and the structure can be disposed or
* reused.
* @param[in] par a parameter that will be passed to the callback function
* @note The associated function is invoked by an interrupt handler within
* the I-Locked state, see @ref system_states.
* @param[out] vtp the @p VirtualTimer structure pointer
* @param[in] time the number of time ticks, the value @p TIME_INFINITE
* is notallowed. The value @p TIME_IMMEDIATE is allowed
* but interpreted as a normal time specification not as
* an immediate timeout specification.
* @param[in] vtfunc the timer callback function. After invoking the
* callback the timer is disabled and the structure can
* be disposed or reused.
* @param[in] par a parameter that will be passed to the callback
* function
*/
void chVTSetI(VirtualTimer *vtp, systime_t time, vtfunc_t vtfunc, void *par) {
VirtualTimer *p;
@ -77,10 +81,10 @@ void chVTSetI(VirtualTimer *vtp, systime_t time, vtfunc_t vtfunc, void *par) {
}
/**
* @brief Disables a Virtual Timer.
* @brief Disables a Virtual Timer.
* @note The timer MUST be active when this function is invoked.
*
* @param[in] vtp the @p VirtualTimer structure pointer
* @note The timer MUST be active when this function is invoked.
* @param[in] vtp the @p VirtualTimer structure pointer
*/
void chVTResetI(VirtualTimer *vtp) {
@ -97,14 +101,15 @@ void chVTResetI(VirtualTimer *vtp) {
}
/**
* @brief 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.
* @note When start==end then the function returns always true because the
* whole time range is specified.
*
* @param[in] start the start of the time window (inclusive)
* @param[in] end the end of the time window (non inclusive)
* @retval TRUE current time within the specified time window.
* @retval FALSE current time not within the specified time window.
* @note When start==end then the function returns always true because the
* whole time range is specified.
* @param[in] start the start of the time window (inclusive)
* @param[in] end the end of the time window (non inclusive)
* @retval TRUE current time within the specified time window.
* @retval FALSE current time not within the specified time window.
*/
bool_t chTimeIsWithin(systime_t start, systime_t end) {