aboutsummaryrefslogtreecommitdiffstats
path: root/os/kernel/src
diff options
context:
space:
mode:
Diffstat (limited to 'os/kernel/src')
-rw-r--r--os/kernel/src/chcond.c20
-rw-r--r--os/kernel/src/chdebug.c2
-rw-r--r--os/kernel/src/chevents.c30
-rw-r--r--os/kernel/src/chheap.c11
-rw-r--r--os/kernel/src/chlists.c29
-rw-r--r--os/kernel/src/chmboxes.c18
-rw-r--r--os/kernel/src/chmemcore.c9
-rw-r--r--os/kernel/src/chmempools.c12
-rw-r--r--os/kernel/src/chmsg.c8
-rw-r--r--os/kernel/src/chmtx.c18
-rw-r--r--os/kernel/src/chqueues.c32
-rw-r--r--os/kernel/src/chregistry.c4
-rw-r--r--os/kernel/src/chschd.c17
-rw-r--r--os/kernel/src/chsem.c22
-rw-r--r--os/kernel/src/chsys.c7
-rw-r--r--os/kernel/src/chthreads.c34
-rw-r--r--os/kernel/src/chvt.c8
17 files changed, 247 insertions, 34 deletions
diff --git a/os/kernel/src/chcond.c b/os/kernel/src/chcond.c
index 71729139f..0ad9d459d 100644
--- a/os/kernel/src/chcond.c
+++ b/os/kernel/src/chcond.c
@@ -43,10 +43,10 @@
/**
* @brief Initializes s @p CondVar structure.
- * @note This function can be invoked before the kernel is initialized
- * because it just prepares a @p CondVar structure.
*
* @param[out] cp pointer to a @p CondVar structure
+ *
+ * @init
*/
void chCondInit(CondVar *cp) {
@@ -59,6 +59,8 @@ void chCondInit(CondVar *cp) {
* @brief Signals one thread that is waiting on the condition variable.
*
* @param[in] cp pointer to the @p CondVar structure
+ *
+ * @api
*/
void chCondSignal(CondVar *cp) {
@@ -78,6 +80,8 @@ void chCondSignal(CondVar *cp) {
* reschedule must not be performed in ISRs.
*
* @param[in] cp pointer to the @p CondVar structure
+ *
+ * @iclass
*/
void chCondSignalI(CondVar *cp) {
@@ -91,6 +95,8 @@ void chCondSignalI(CondVar *cp) {
* @brief Signals all threads that are waiting on the condition variable.
*
* @param[in] cp pointer to the @p CondVar structure
+ *
+ * @api
*/
void chCondBroadcast(CondVar *cp) {
@@ -108,6 +114,8 @@ void chCondBroadcast(CondVar *cp) {
* reschedule must not be performed in ISRs.
*
* @param[in] cp pointer to the @p CondVar structure
+ *
+ * @iclass
*/
void chCondBroadcastI(CondVar *cp) {
@@ -134,6 +142,8 @@ void chCondBroadcastI(CondVar *cp) {
* @p chCondSignal().
* @retval RDY_RESET if the condvar has been signaled using
* @p chCondBroadcast().
+ *
+ * @api
*/
msg_t chCondWait(CondVar *cp) {
msg_t msg;
@@ -158,6 +168,8 @@ msg_t chCondWait(CondVar *cp) {
* @p chCondSignal().
* @retval RDY_RESET if the condvar has been signaled using
* @p chCondBroadcast().
+ *
+ * @sclass
*/
msg_t chCondWaitS(CondVar *cp) {
Thread *ctp = currp;
@@ -204,6 +216,8 @@ msg_t chCondWaitS(CondVar *cp) {
* @p chCondBroadcast().
* @retval RDY_TIMEOUT if the condvar has not been signaled within the
* specified timeout.
+ *
+ * @api
*/
msg_t chCondWaitTimeout(CondVar *cp, systime_t time) {
msg_t msg;
@@ -239,6 +253,8 @@ msg_t chCondWaitTimeout(CondVar *cp, systime_t time) {
* @p chCondBroadcast().
* @retval RDY_TIMEOUT if the condvar has not been signaled within the
* specified timeout.
+ *
+ * @sclass
*/
msg_t chCondWaitTimeoutS(CondVar *cp, systime_t time) {
Mutex *mp;
diff --git a/os/kernel/src/chdebug.c b/os/kernel/src/chdebug.c
index dcf42c2b3..80323e183 100644
--- a/os/kernel/src/chdebug.c
+++ b/os/kernel/src/chdebug.c
@@ -55,6 +55,8 @@ void trace_init(void) {
* @brief Inserts in the circular debug trace buffer a context switch record.
*
* @param[in] otp the thread being switched out
+ *
+ * @notapi
*/
void chDbgTrace(Thread *otp) {
diff --git a/os/kernel/src/chevents.c b/os/kernel/src/chevents.c
index aac3a22af..a66a7fa28 100644
--- a/os/kernel/src/chevents.c
+++ b/os/kernel/src/chevents.c
@@ -68,6 +68,8 @@
* @param[in] elp pointer to the @p EventListener structure
* @param[in] mask the mask of event flags to be ORed to the thread when
* the event source is broadcasted
+ *
+ * @api
*/
void chEvtRegisterMask(EventSource *esp, EventListener *elp, eventmask_t mask) {
@@ -91,6 +93,8 @@ void chEvtRegisterMask(EventSource *esp, EventListener *elp, eventmask_t mask) {
*
* @param[in] esp pointer to the @p EventSource structure
* @param[in] elp pointer to the @p EventListener structure
+ *
+ * @api
*/
void chEvtUnregister(EventSource *esp, EventListener *elp) {
EventListener *p;
@@ -114,6 +118,8 @@ void chEvtUnregister(EventSource *esp, EventListener *elp) {
*
* @param[in] mask the events to be cleared
* @return The pending events that were cleared.
+ *
+ * @api
*/
eventmask_t chEvtClearFlags(eventmask_t mask) {
eventmask_t m;
@@ -133,6 +139,8 @@ eventmask_t chEvtClearFlags(eventmask_t mask) {
*
* @param[in] mask the event flags to be ORed
* @return The current pending events mask.
+ *
+ * @api
*/
eventmask_t chEvtAddFlags(eventmask_t mask) {
@@ -149,6 +157,8 @@ eventmask_t chEvtAddFlags(eventmask_t mask) {
*
* @param[in] tp the thread to be signaled
* @param[in] mask the event flags set to be ORed
+ *
+ * @api
*/
void chEvtSignal(Thread *tp, eventmask_t mask) {
@@ -169,6 +179,8 @@ void chEvtSignal(Thread *tp, eventmask_t mask) {
*
* @param[in] tp the thread to be signaled
* @param[in] mask the event flags set to be ORed
+ *
+ * @iclass
*/
void chEvtSignalI(Thread *tp, eventmask_t mask) {
@@ -188,6 +200,8 @@ void chEvtSignalI(Thread *tp, eventmask_t mask) {
* Source.
*
* @param[in] esp pointer to the @p EventSource structure
+ *
+ * @api
*/
void chEvtBroadcast(EventSource *esp) {
@@ -206,6 +220,8 @@ void chEvtBroadcast(EventSource *esp) {
* reschedule must not be performed in ISRs.
*
* @param[in] esp pointer to the @p EventSource structure
+ *
+ * @iclass
*/
void chEvtBroadcastI(EventSource *esp) {
EventListener *elp;
@@ -225,6 +241,8 @@ void chEvtBroadcastI(EventSource *esp) {
* @param[in] mask mask of the event flags 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.
+ *
+ * @api
*/
void chEvtDispatch(const evhandler_t *handlers, eventmask_t mask) {
eventid_t eid;
@@ -258,6 +276,8 @@ void chEvtDispatch(const evhandler_t *handlers, eventmask_t mask) {
* @param[in] mask mask of the event flags that the function should wait
* for, @p ALL_EVENTS enables all the events
* @return The mask of the lowest id served and cleared event.
+ *
+ * @api
*/
eventmask_t chEvtWaitOne(eventmask_t mask) {
Thread *ctp = currp;
@@ -285,6 +305,8 @@ eventmask_t chEvtWaitOne(eventmask_t mask) {
* @param[in] mask mask of the event flags that the function should wait
* for, @p ALL_EVENTS enables all the events
* @return The mask of the served and cleared events.
+ *
+ * @api
*/
eventmask_t chEvtWaitAny(eventmask_t mask) {
Thread *ctp = currp;
@@ -311,6 +333,8 @@ eventmask_t chEvtWaitAny(eventmask_t mask) {
* @param[in] mask mask of the event flags that the function should wait
* for, @p ALL_EVENTS requires all the events
* @return The mask of the served and cleared events.
+ *
+ * @api
*/
eventmask_t chEvtWaitAll(eventmask_t mask) {
Thread *ctp = currp;
@@ -348,6 +372,8 @@ eventmask_t chEvtWaitAll(eventmask_t mask) {
* .
* @return The mask of the lowest id served and cleared event.
* @retval 0 if the operation has timed out.
+ *
+ * @api
*/
eventmask_t chEvtWaitOneTimeout(eventmask_t mask, systime_t time) {
Thread *ctp = currp;
@@ -385,6 +411,8 @@ eventmask_t chEvtWaitOneTimeout(eventmask_t mask, systime_t time) {
* .
* @return The mask of the served and cleared events.
* @retval 0 if the operation has timed out.
+ *
+ * @api
*/
eventmask_t chEvtWaitAnyTimeout(eventmask_t mask, systime_t time) {
Thread *ctp = currp;
@@ -420,6 +448,8 @@ eventmask_t chEvtWaitAnyTimeout(eventmask_t mask, systime_t time) {
* .
* @return The mask of the served and cleared events.
* @retval 0 if the operation has timed out.
+ *
+ * @api
*/
eventmask_t chEvtWaitAllTimeout(eventmask_t mask, systime_t time) {
Thread *ctp = currp;
diff --git a/os/kernel/src/chheap.c b/os/kernel/src/chheap.c
index fc92e3c18..13db7cf6b 100644
--- a/os/kernel/src/chheap.c
+++ b/os/kernel/src/chheap.c
@@ -61,7 +61,8 @@ static MemoryHeap default_heap;
/**
* @brief Initializes the default heap.
- * @note Internal use only.
+ *
+ * @notapi
*/
void heap_init(void) {
default_heap.h_provider = chCoreAlloc;
@@ -82,6 +83,8 @@ void heap_init(void) {
* @param[out] heapp pointer to the memory heap descriptor to be initialized
* @param[in] buf heap buffer base
* @param[in] size heap size
+ *
+ * @init
*/
void chHeapInit(MemoryHeap *heapp, void *buf, size_t size) {
union heap_header *hp;
@@ -113,6 +116,8 @@ void chHeapInit(MemoryHeap *heapp, void *buf, size_t size) {
* size for alignment and fragmentation reasons.
* @return A pointer to the allocated block.
* @retval NULL if the block cannot be allocated.
+ *
+ * @api
*/
void *chHeapAlloc(MemoryHeap *heapp, size_t size) {
union heap_header *qp, *hp, *fp;
@@ -173,6 +178,8 @@ void *chHeapAlloc(MemoryHeap *heapp, size_t size) {
* @brief Frees a previously allocated memory block.
*
* @param[in] p pointer to the memory block to be freed
+ *
+ * @api
*/
void chHeapFree(void *p) {
union heap_header *qp, *hp;
@@ -227,6 +234,8 @@ void chHeapFree(void *p) {
* @param[in] sizep pointer to a variable that will receive the total
* fragmented free space
* @return The number of fragments in the heap.
+ *
+ * @api
*/
size_t chHeapStatus(MemoryHeap *heapp, size_t *sizep) {
union heap_header *qp;
diff --git a/os/kernel/src/chlists.c b/os/kernel/src/chlists.c
index 83bdf8b35..878f1360c 100644
--- a/os/kernel/src/chlists.c
+++ b/os/kernel/src/chlists.c
@@ -23,7 +23,7 @@
*
* @addtogroup internals
* @details All the functions present in this module, while public, are not
- * an OS API and should not be directly used in the user applications
+ * OS APIs and should not be directly used in the user applications
* code.
* @{
*/
@@ -32,12 +32,13 @@
#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.
+ * @note The insertion is done by scanning the list from the highest
+ * priority toward the lowest.
*
* @param[in] tp the pointer to the thread to be inserted in the list
* @param[in] tqp the pointer to the threads list header
+ *
+ * @notapi
*/
void prio_insert(Thread *tp, ThreadsQueue *tqp) {
@@ -56,10 +57,11 @@ void prio_insert(Thread *tp, ThreadsQueue *tqp) {
/**
* @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
+ *
+ * @notapi
*/
void queue_insert(Thread *tp, ThreadsQueue *tqp) {
@@ -72,10 +74,11 @@ 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.
*
* @param[in] tqp the pointer to the threads list header
* @return The removed thread pointer.
+ *
+ * @notapi
*/
Thread *fifo_remove(ThreadsQueue *tqp) {
Thread *tp = tqp->p_next;
@@ -88,10 +91,11 @@ 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.
*
* @param[in] tqp the pointer to the threads list header
* @return The removed thread pointer.
+ *
+ * @notapi
*/
Thread *lifo_remove(ThreadsQueue *tqp) {
Thread *tp = tqp->p_prev;
@@ -104,10 +108,11 @@ Thread *lifo_remove(ThreadsQueue *tqp) {
* @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.
*
* @param[in] tp the pointer to the thread to be removed from the queue
* @return The removed thread pointer.
+ *
+ * @notapi
*/
Thread *dequeue(Thread *tp) {
@@ -118,10 +123,11 @@ Thread *dequeue(Thread *tp) {
/**
* @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
+ *
+ * @notapi
*/
void list_insert(Thread *tp, ThreadsList *tlp) {
@@ -131,11 +137,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.
+ * @pre The list must be non-empty before calling this function.
*
* @param[in] tlp the pointer to the threads list header
* @return The removed thread pointer.
+ *
+ * @notapi
*/
Thread *list_remove(ThreadsList *tlp) {
diff --git a/os/kernel/src/chmboxes.c b/os/kernel/src/chmboxes.c
index 279778e48..b2cef2470 100644
--- a/os/kernel/src/chmboxes.c
+++ b/os/kernel/src/chmboxes.c
@@ -54,12 +54,12 @@
#if CH_USE_MAILBOXES || defined(__DOXYGEN__)
/**
* @brief Initializes a Mailbox object.
- * @note This function can be invoked before the kernel is initialized
- * because it just prepares a @p Mailbox structure.
*
* @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
+ *
+ * @init
*/
void chMBInit(Mailbox *mbp, msg_t *buf, cnt_t n) {
@@ -77,6 +77,8 @@ void chMBInit(Mailbox *mbp, msg_t *buf, cnt_t n) {
* the queued messages are lost.
*
* @param[in] mbp the pointer to an initialized Mailbox object
+ *
+ * @api
*/
void chMBReset(Mailbox *mbp) {
@@ -106,6 +108,8 @@ void chMBReset(Mailbox *mbp) {
* @retval RDY_OK if a message has been correctly posted.
* @retval RDY_RESET if the mailbox has been reset while waiting.
* @retval RDY_TIMEOUT if the operation has timed out.
+ *
+ * @api
*/
msg_t chMBPost(Mailbox *mbp, msg_t msg, systime_t time) {
msg_t rdymsg;
@@ -132,6 +136,8 @@ msg_t chMBPost(Mailbox *mbp, msg_t msg, systime_t time) {
* @retval RDY_OK if a message has been correctly posted.
* @retval RDY_RESET if the mailbox has been reset while waiting.
* @retval RDY_TIMEOUT if the operation has timed out.
+ *
+ * @sclass
*/
msg_t chMBPostS(Mailbox *mbp, msg_t msg, systime_t time) {
msg_t rdymsg;
@@ -165,6 +171,8 @@ msg_t chMBPostS(Mailbox *mbp, msg_t msg, systime_t time) {
* @retval RDY_OK if a message has been correctly posted.
* @retval RDY_RESET if the mailbox has been reset while waiting.
* @retval RDY_TIMEOUT if the operation has timed out.
+ *
+ * @api
*/
msg_t chMBPostAhead(Mailbox *mbp, msg_t msg, systime_t time) {
msg_t rdymsg;
@@ -191,6 +199,8 @@ msg_t chMBPostAhead(Mailbox *mbp, msg_t msg, systime_t time) {
* @retval RDY_OK if a message has been correctly posted.
* @retval RDY_RESET if the mailbox has been reset while waiting.
* @retval RDY_TIMEOUT if the operation has timed out.
+ *
+ * @sclass
*/
msg_t chMBPostAheadS(Mailbox *mbp, msg_t msg, systime_t time) {
msg_t rdymsg;
@@ -224,6 +234,8 @@ msg_t chMBPostAheadS(Mailbox *mbp, msg_t msg, systime_t time) {
* @retval RDY_OK if a message has been correctly fetched.
* @retval RDY_RESET if the mailbox has been reset while waiting.
* @retval RDY_TIMEOUT if the operation has timed out.
+ *
+ * @api
*/
msg_t chMBFetch(Mailbox *mbp, msg_t *msgp, systime_t time) {
msg_t rdymsg;
@@ -250,6 +262,8 @@ msg_t chMBFetch(Mailbox *mbp, msg_t *msgp, systime_t time) {
* @retval RDY_OK if a message has been correctly fetched.
* @retval RDY_RESET if the mailbox has been reset while waiting.
* @retval RDY_TIMEOUT if the operation has timed out.
+ *
+ * @sclass
*/
msg_t chMBFetchS(Mailbox *mbp, msg_t *msgp, systime_t time) {
msg_t rdymsg;
diff --git a/os/kernel/src/chmemcore.c b/os/kernel/src/chmemcore.c
index 04edb7dae..69d3014a5 100644
--- a/os/kernel/src/chmemcore.c
+++ b/os/kernel/src/chmemcore.c
@@ -50,7 +50,8 @@ static uint8_t *endmem;
/**
* @brief Low level memory manager initialization.
- * @note Internal use only.
+ *
+ * @notapi
*/
void core_init(void) {
#if CH_MEMCORE_SIZE == 0
@@ -76,6 +77,8 @@ void core_init(void) {
* @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.
+ *
+ * @api
*/
void *chCoreAlloc(size_t size) {
void *p;
@@ -95,6 +98,8 @@ void *chCoreAlloc(size_t size) {
* @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.
+ *
+ * @iclass
*/
void *chCoreAllocI(size_t size) {
void *p;
@@ -111,6 +116,8 @@ void *chCoreAllocI(size_t size) {
* @brief Core memory status.
*
* @return The size, in bytes, of the free core memory.
+ *
+ * @api
*/
size_t chCoreStatus(void) {
diff --git a/os/kernel/src/chmempools.c b/os/kernel/src/chmempools.c
index e1817aa60..092944b59 100644
--- a/os/kernel/src/chmempools.c
+++ b/os/kernel/src/chmempools.c
@@ -37,8 +37,6 @@
#if CH_USE_MEMPOOLS || defined(__DOXYGEN__)
/**
* @brief Initializes an empty memory pool.
- * @note This function can be invoked before the kernel is initialized
- * because it just prepares a @p MemoryPool structure.
* @note The size is internally aligned to be a multiple of the
* @p stkalign_t type size.
*
@@ -49,6 +47,8 @@
* @param[in] provider memory provider function for the memory pool or
* @p NULL if the pool is not allowed to grow
* automatically
+ *
+ * @init
*/
void chPoolInit(MemoryPool *mp, size_t size, memgetfunc_t provider) {
@@ -65,6 +65,8 @@ void chPoolInit(MemoryPool *mp, size_t size, memgetfunc_t provider) {
* @param[in] mp pointer to a @p MemoryPool structure
* @return The pointer to the allocated object.
* @retval NULL if pool is empty.
+ *
+ * @iclass
*/
void *chPoolAllocI(MemoryPool *mp) {
void *objp;
@@ -86,6 +88,8 @@ void *chPoolAllocI(MemoryPool *mp) {
* @param[in] mp pointer to a @p MemoryPool structure
* @return The pointer to the allocated object.
* @retval NULL if pool is empty.
+ *
+ * @api
*/
void *chPoolAlloc(MemoryPool *mp) {
void *objp;
@@ -105,6 +109,8 @@ void *chPoolAlloc(MemoryPool *mp) {
*
* @param[in] mp pointer to a @p MemoryPool structure
* @param[in] objp the pointer to the object to be released or added
+ *
+ * @iclass
*/
void chPoolFreeI(MemoryPool *mp, void *objp) {
struct pool_header *php = objp;
@@ -125,6 +131,8 @@ void chPoolFreeI(MemoryPool *mp, void *objp) {
*
* @param[in] mp pointer to a @p MemoryPool structure
* @param[in] objp the pointer to the object to be released or added
+ *
+ * @api
*/
void chPoolFree(MemoryPool *mp, void *objp) {
diff --git a/os/kernel/src/chmsg.c b/os/kernel/src/chmsg.c
index 09acf7b42..c3b4848b0 100644
--- a/os/kernel/src/chmsg.c
+++ b/os/kernel/src/chmsg.c
@@ -61,6 +61,8 @@
* @param[in] tp the pointer to the thread
* @param[in] msg the message
* @return The answer message from @p chMsgRelease().
+ *
+ * @api
*/
msg_t chMsgSend(Thread *tp, msg_t msg) {
Thread *ctp = currp;
@@ -88,6 +90,8 @@ msg_t chMsgSend(Thread *tp, msg_t msg) {
* because the sending thread is suspended until then.
*
* @return The message.
+ *
+ * @api
*/
msg_t chMsgWait(void) {
msg_t msg;
@@ -114,6 +118,8 @@ msg_t chMsgWait(void) {
*
* @return The message.
* @retval 0 if the queue is empty.
+ *
+ * @api
*/
msg_t chMsgGet(void) {
msg_t msg;
@@ -130,6 +136,8 @@ msg_t chMsgGet(void) {
* using @p chMsgWait() or @p chMsgGet().
*
* @param[in] msg the message returned to the message sender
+ *
+ * @api
*/
void chMsgRelease(msg_t msg) {
diff --git a/os/kernel/src/chmtx.c b/os/kernel/src/chmtx.c
index 9698d3cd8..b84c4d57e 100644
--- a/os/kernel/src/chmtx.c
+++ b/os/kernel/src/chmtx.c
@@ -70,10 +70,10 @@
/**
* @brief Initializes s @p Mutex structure.
- * @note This function can be invoked before the kernel is initialized
- * because it just prepares a @p Mutex structure.
*
* @param[out] mp pointer to a @p Mutex structure
+ *
+ * @init
*/
void chMtxInit(Mutex *mp) {
@@ -89,6 +89,8 @@ void chMtxInit(Mutex *mp) {
* mutexes.
*
* @param[in] mp pointer to the @p Mutex structure
+ *
+ * @api
*/
void chMtxLock(Mutex *mp) {
@@ -105,6 +107,8 @@ void chMtxLock(Mutex *mp) {
* mutexes.
*
* @param[in] mp pointer to the @p Mutex structure
+ *
+ * @sclass
*/
void chMtxLockS(Mutex *mp) {
Thread *ctp = currp;
@@ -184,6 +188,8 @@ void chMtxLockS(Mutex *mp) {
* @return The operation status.
* @retval TRUE if the mutex has been successfully acquired
* @retval FALSE if the lock attempt failed.
+ *
+ * @api
*/
bool_t chMtxTryLock(Mutex *mp) {
bool_t b;
@@ -210,6 +216,8 @@ bool_t chMtxTryLock(Mutex *mp) {
* @return The operation status.
* @retval TRUE if the mutex has been successfully acquired
* @retval FALSE if the lock attempt failed.
+ *
+ * @sclass
*/
bool_t chMtxTryLockS(Mutex *mp) {
@@ -230,6 +238,8 @@ bool_t chMtxTryLockS(Mutex *mp) {
* owned mutexes.
*
* @return A pointer to the unlocked mutex.
+ *
+ * @api
*/
Mutex *chMtxUnlock(void) {
Thread *ctp = currp;
@@ -288,6 +298,8 @@ Mutex *chMtxUnlock(void) {
* function must be performed before unlocking the kernel.
*
* @return A pointer to the unlocked mutex.
+ *
+ * @sclass
*/
Mutex *chMtxUnlockS(void) {
Thread *ctp = currp;
@@ -342,6 +354,8 @@ Mutex *chMtxUnlockS(void) {
* mutexes one by one and not just because the call overhead,
* this function does not have any overhead related to the priority
* inheritance mechanism.
+ *
+ * @api
*/
void chMtxUnlockAll(void) {
Thread *ctp = currp;
diff --git a/os/kernel/src/chqueues.c b/os/kernel/src/chqueues.c
index 485984fdf..b02fa6a64 100644
--- a/os/kernel/src/chqueues.c
+++ b/os/kernel/src/chqueues.c
@@ -50,8 +50,6 @@
* @brief Initializes an input queue.
* @details A Semaphore is internally initialized and works as a counter of
* the bytes contained in the queue.
- * @note This function can be invoked before the kernel is initialized
- * because it just prepares a @p InputQueue structure.
* @note The callback is invoked from within the S-Locked system state,
* see @ref system_states.
*
@@ -60,6 +58,8 @@
* @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.
+ *
+ * @init
*/
void chIQInit(InputQueue *iqp, uint8_t *bp, size_t size, qnotify_t infy) {
@@ -77,6 +77,8 @@ void chIQInit(InputQueue *iqp, uint8_t *bp, size_t size, qnotify_t infy) {
* obtain immediate attention from the high level layers.
*
* @param[in] iqp pointer to an @p InputQueue structure
+ *
+ * @iclass
*/
void chIQResetI(InputQueue *iqp) {
@@ -94,10 +96,12 @@ void chIQResetI(InputQueue *iqp) {
* @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.
+ *
+ * @iclass
*/
msg_t chIQPutI(InputQueue *iqp, uint8_t b) {
- if (chIQIsFull(iqp))
+ if (chIQIsFullI(iqp))
return Q_FULL;
*iqp->q_wrptr++ = b;
@@ -122,6 +126,8 @@ msg_t chIQPutI(InputQueue *iqp, uint8_t b) {
* @return A byte value from the queue.
* @retval Q_TIMEOUT if the specified time expired.
* @retval Q_RESET if the queue was reset.
+ *
+ * @api
*/
msg_t chIQGetTimeout(InputQueue *iqp, systime_t time) {
uint8_t b;
@@ -165,6 +171,8 @@ msg_t chIQGetTimeout(InputQueue *iqp, systime_t time) {
* - @a TIME_INFINITE no timeout.
* .
* @return The number of bytes effectively transferred.
+ *
+ * @api
*/
size_t chIQReadTimeout(InputQueue *iqp, uint8_t *bp,
size_t n, systime_t time) {
@@ -175,7 +183,7 @@ size_t chIQReadTimeout(InputQueue *iqp, uint8_t *bp,
chSysLock();
while (TRUE) {
- if (chIQIsEmpty(iqp)) {
+ if (chIQIsEmptyI(iqp)) {
if (nfy)
nfy();
if ((chSemWaitTimeoutS(&iqp->q_sem, time) != RDY_OK)) {
@@ -207,8 +215,6 @@ size_t chIQReadTimeout(InputQueue *iqp, uint8_t *bp,
* @brief Initializes an output queue.
* @details A Semaphore is internally initialized and works as a counter of
* the free bytes in the queue.
- * @note This function can be invoked before the kernel is initialized
- * because it just prepares a @p OutputQueue structure.
* @note The callback is invoked from within the S-Locked system state,
* see @ref system_states.
*
@@ -217,6 +223,8 @@ size_t chIQReadTimeout(InputQueue *iqp, uint8_t *bp,
* @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.
+ *
+ * @init
*/
void chOQInit(OutputQueue *oqp, uint8_t *bp, size_t size, qnotify_t onfy) {
@@ -234,6 +242,8 @@ void chOQInit(OutputQueue *oqp, uint8_t *bp, size_t size, qnotify_t onfy) {
* obtain immediate attention from the high level layers.
*
* @param[in] oqp pointer to an @p OutputQueue structure
+ *
+ * @iclass
*/
void chOQResetI(OutputQueue *oqp) {
@@ -258,6 +268,8 @@ void chOQResetI(OutputQueue *oqp) {
* @retval Q_OK if the operation succeeded.
* @retval Q_TIMEOUT if the specified time expired.
* @retval Q_RESET if the queue was reset.
+ *
+ * @api
*/
msg_t chOQPutTimeout(OutputQueue *oqp, uint8_t b, systime_t time) {
msg_t msg;
@@ -285,11 +297,13 @@ msg_t chOQPutTimeout(OutputQueue *oqp, uint8_t b, systime_t time) {
* @param[in] oqp pointer to an @p OutputQueue structure
* @return The byte value from the queue.
* @retval Q_EMPTY if the queue is empty.
+ *
+ * @iclass
*/
msg_t chOQGetI(OutputQueue *oqp) {
uint8_t b;
- if (chOQIsEmpty(oqp))
+ if (chOQIsEmptyI(oqp))
return Q_EMPTY;
b = *oqp->q_rdptr++;
@@ -320,6 +334,8 @@ msg_t chOQGetI(OutputQueue *oqp) {
* - @a TIME_INFINITE no timeout.
* .
* @return The number of bytes effectively transferred.
+ *
+ * @api
*/
size_t chOQWriteTimeout(OutputQueue *oqp, const uint8_t *bp,
size_t n, systime_t time) {
@@ -330,7 +346,7 @@ size_t chOQWriteTimeout(OutputQueue *oqp, const uint8_t *bp,
chSysLock();
while (TRUE) {
- if (chOQIsFull(oqp)) {
+ if (chOQIsFullI(oqp)) {
if (nfy)
nfy();
if ((chSemWaitTimeoutS(&oqp->q_sem, time) != RDY_OK)) {
diff --git a/os/kernel/src/chregistry.c b/os/kernel/src/chregistry.c
index 216758c85..95893de85 100644
--- a/os/kernel/src/chregistry.c
+++ b/os/kernel/src/chregistry.c
@@ -58,6 +58,8 @@
* least one thread in the system.
*
* @return A reference to the most ancient thread.
+ *
+ * @api
*/
Thread *chRegFirstThread(void) {
Thread *tp;
@@ -79,6 +81,8 @@ Thread *chRegFirstThread(void) {
* @param[in] tp pointer to the thread
* @return A reference to the next thread.
* @retval NULL if there is no next thread.
+ *
+ * @api
*/
Thread *chRegNextThread(Thread *tp) {
Thread *ntp;
diff --git a/os/kernel/src/chschd.c b/os/kernel/src/chschd.c
index 213d999ce..c7db9ad60 100644
--- a/os/kernel/src/chschd.c
+++ b/os/kernel/src/chschd.c
@@ -41,7 +41,8 @@ ReadyList rlist;
/**
* @brief Scheduler initialization.
- * @note Internally invoked by the @p chSysInit(), not an API.
+ *
+ * @notapi
*/
void scheduler_init(void) {
@@ -66,6 +67,8 @@ void scheduler_init(void) {
*
* @param[in] tp the thread to be made ready
* @return The thread pointer.
+ *
+ * @iclass
*/
#if !defined(PORT_OPTIMIZED_READYI) || defined(__DOXYGEN__)
#if CH_OPTIMIZE_SPEED
@@ -101,6 +104,8 @@ Thread *chSchReadyI(Thread *tp) {
* @ref thread_states are defined into @p threads.h.
*
* @param[in] newstate the new thread state
+ *
+ * @sclass
*/
#if !defined(PORT_OPTIMIZED_GOSLEEPS) || defined(__DOXYGEN__)
void chSchGoSleepS(tstate_t newstate) {
@@ -163,6 +168,8 @@ static void wakeup(void *p) {
* .
* @return The wakeup message.
* @retval RDY_TIMEOUT if a timeout occurs.
+ *
+ * @sclass
*/
msg_t chSchGoSleepTimeoutS(tstate_t newstate, systime_t time) {
@@ -194,6 +201,8 @@ msg_t chSchGoSleepTimeoutS(tstate_t newstate, systime_t time) {
*
* @param[in] ntp the Thread to be made ready
* @param[in] msg message to the awakened thread
+ *
+ * @sclass
*/
#if !defined(PORT_OPTIMIZED_WAKEUPS) || defined(__DOXYGEN__)
void chSchWakeupS(Thread *ntp, msg_t msg) {
@@ -222,6 +231,8 @@ 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.
+ *
+ * @iclass
*/
#if !defined(PORT_OPTIMIZED_DORESCHEDULEI) || defined(__DOXYGEN__)
void chSchDoRescheduleI(void) {
@@ -244,6 +255,8 @@ void chSchDoRescheduleI(void) {
* @brief Performs a reschedule 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.
+ *
+ * @iclass
*/
#if !defined(PORT_OPTIMIZED_RESCHEDULES) || defined(__DOXYGEN__)
void chSchRescheduleS(void) {
@@ -262,6 +275,8 @@ void chSchRescheduleS(void) {
*
* @retval TRUE if there is a thread that should go in running state.
* @retval FALSE if a reschedule is not required.
+ *
+ * @iclass
*/
#if !defined(PORT_OPTIMIZED_ISRESCHREQUIREDEXI) || defined(__DOXYGEN__)
bool_t chSchIsRescRequiredExI(void) {
diff --git a/os/kernel/src/chsem.c b/os/kernel/src/chsem.c
index 750402266..58cd94808 100644
--- a/os/kernel/src/chsem.c
+++ b/os/kernel/src/chsem.c
@@ -68,12 +68,12 @@
/**
* @brief Initializes a semaphore with the specified counter value.
- * @note This function can be invoked before the kernel is initialized
- * because it just prepares a @p Semaphore structure.
*
* @param[out] sp pointer to a @p Semaphore structure
* @param[in] n initial value of the semaphore counter. Must be
* non-negative.
+ *
+ * @init
*/
void chSemInit(Semaphore *sp, cnt_t n) {
@@ -95,6 +95,8 @@ void chSemInit(Semaphore *sp, cnt_t n) {
* @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.
+ *
+ * @api
*/
void chSemReset(Semaphore *sp, cnt_t n) {
@@ -120,6 +122,8 @@ void chSemReset(Semaphore *sp, cnt_t n) {
* @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.
+ *
+ * @iclass
*/
void chSemResetI(Semaphore *sp, cnt_t n) {
cnt_t cnt;
@@ -146,6 +150,8 @@ void chSemResetI(Semaphore *sp, cnt_t n) {
* @retval RDY_OK if the thread has not stopped on the semaphore or the
* semaphore has been signaled.
* @retval RDY_RESET if the semaphore has been reset using @p chSemReset().
+ *
+ * @api
*/
msg_t chSemWait(Semaphore *sp) {
msg_t msg;
@@ -165,6 +171,8 @@ msg_t chSemWait(Semaphore *sp) {
* @retval RDY_OK if the thread has not stopped on the semaphore or the
* semaphore has been signaled.
* @retval RDY_RESET if the semaphore has been reset using @p chSemReset().
+ *
+ * @sclass
*/
msg_t chSemWaitS(Semaphore *sp) {
@@ -200,6 +208,8 @@ msg_t chSemWaitS(Semaphore *sp) {
* @retval RDY_RESET if the semaphore has been reset using @p chSemReset().
* @retval RDY_TIMEOUT if the semaphore has not been signaled or reset within
* the specified timeout.
+ *
+ * @api
*/
msg_t chSemWaitTimeout(Semaphore *sp, systime_t time) {
msg_t msg;
@@ -226,6 +236,8 @@ msg_t chSemWaitTimeout(Semaphore *sp, systime_t time) {
* @retval RDY_RESET if the semaphore has been reset using @p chSemReset().
* @retval RDY_TIMEOUT if the semaphore has not been signaled or reset within
* the specified timeout.
+ *
+ * @sclass
*/
msg_t chSemWaitTimeoutS(Semaphore *sp, systime_t time) {
@@ -252,6 +264,8 @@ msg_t chSemWaitTimeoutS(Semaphore *sp, systime_t time) {
* @brief Performs a signal operation on a semaphore.
*
* @param[in] sp pointer to a @p Semaphore structure
+ *
+ * @api
*/
void chSemSignal(Semaphore *sp) {
@@ -276,6 +290,8 @@ void chSemSignal(Semaphore *sp) {
* reschedule must not be performed in ISRs.
*
* @param[in] sp pointer to a @p Semaphore structure
+ *
+ * @iclass
*/
void chSemSignalI(Semaphore *sp) {
@@ -308,6 +324,8 @@ void chSemSignalI(Semaphore *sp) {
* @retval RDY_OK if the thread has not stopped on the semaphore or the
* semaphore has been signaled.
* @retval RDY_RESET if the semaphore has been reset using @p chSemReset().
+ *
+ * @api
*/
msg_t chSemSignalWait(Semaphore *sps, Semaphore *spw) {
msg_t msg;
diff --git a/os/kernel/src/chsys.c b/os/kernel/src/chsys.c
index 809212a7b..a567b73da 100644
--- a/os/kernel/src/chsys.c
+++ b/os/kernel/src/chsys.c
@@ -66,6 +66,10 @@ void _idle_thread(void *p) {
* @pre Interrupts must be still disabled when @p chSysInit() is invoked
* and are internally enabled.
* @post The main thread is created with priority @p NORMALPRIO.
+ * @note This function has special, architecture-dependent, requirements,
+ * see the notes into the various port reference manuals.
+ *
+ * @special
*/
void chSysInit(void) {
static Thread mainthread;
@@ -100,10 +104,11 @@ void chSysInit(void) {
* @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.
+ *
+ * @iclass
*/
void chSysTimerHandlerI(void) {
diff --git a/os/kernel/src/chthreads.c b/os/kernel/src/chthreads.c
index 5bcadb96d..c4aa7437c 100644
--- a/os/kernel/src/chthreads.c
+++ b/os/kernel/src/chthreads.c
@@ -64,6 +64,8 @@
* @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.
+ *
+ * @notapi
*/
Thread *init_thread(Thread *tp, tprio_t prio) {
@@ -128,6 +130,8 @@ static void memfill(uint8_t *startp, uint8_t *endp, uint8_t v) {
* @p NULL.
* @return The pointer to the @p Thread structure allocated for
* the thread into the working space area.
+ *
+ * @api
*/
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 */
@@ -158,6 +162,8 @@ Thread *chThdInit(void *wsp, size_t size, tprio_t prio, tfunc_t pf, void *arg) {
* @p NULL.
* @return The pointer to the @p Thread structure allocated for
* the thread into the working space area.
+ *
+ * @api
*/
Thread *chThdCreateStatic(void *wsp, size_t size,
tprio_t prio, tfunc_t pf, void *arg) {
@@ -185,6 +191,8 @@ Thread *chThdCreateStatic(void *wsp, size_t size,
* @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.
+ *
+ * @api
*/
Thread *chThdCreateFromHeap(MemoryHeap *heapp, size_t size,
tprio_t prio, tfunc_t pf, void *arg) {
@@ -219,6 +227,8 @@ Thread *chThdCreateFromHeap(MemoryHeap *heapp, size_t size,
* @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.
+ *
+ * @api
*/
Thread *chThdCreateFromMemoryPool(MemoryPool *mp, tprio_t prio,
tfunc_t pf, void *arg) {
@@ -246,6 +256,8 @@ Thread *chThdCreateFromMemoryPool(MemoryPool *mp, tprio_t prio,
*
* @param[in] newprio the new priority level of the running thread
* @return The old priority level.
+ *
+ * @api
*/
tprio_t chThdSetPriority(tprio_t newprio) {
tprio_t oldprio;
@@ -278,6 +290,8 @@ tprio_t chThdSetPriority(tprio_t newprio) {
*
* @param[in] tp pointer to the thread
* @return The pointer to the thread.
+ *
+ * @api
*/
Thread *chThdResume(Thread *tp) {
@@ -299,6 +313,8 @@ Thread *chThdResume(Thread *tp) {
* condition.
*
* @param[in] tp pointer to the thread
+ *
+ * @api
*/
void chThdTerminate(Thread *tp) {
@@ -318,6 +334,8 @@ void chThdTerminate(Thread *tp) {
* interpreted as a normal time specification not as an
* immediate timeout specification.
* .
+ *
+ * @api
*/
void chThdSleep(systime_t time) {
@@ -333,6 +351,8 @@ void chThdSleep(systime_t time) {
* specified value.
*
* @param[in] time absolute system time
+ *
+ * @api
*/
void chThdSleepUntil(systime_t time) {
@@ -346,6 +366,8 @@ void chThdSleepUntil(systime_t time) {
* @brief Yields the time slot.
* @details Yields the CPU control to the next thread in the ready list with
* equal priority, if any.
+ *
+ * @api
*/
void chThdYield(void) {
@@ -360,9 +382,13 @@ void chThdYield(void) {
* specified exit status code, other threads can retrieve the
* exit status code by invoking the function @p chThdWait().
* @post Eventual code after this function will never be executed,
- * this function never returns.
+ * this function never returns. The compiler has no way to
+ * know this so do not assume that the compiler would remove
+ * the dead code.
*
* @param[in] msg thread exit code
+ *
+ * @api
*/
void chThdExit(msg_t msg) {
Thread *tp = currp;
@@ -391,6 +417,8 @@ void chThdExit(msg_t msg) {
* @param[in] tp pointer to the thread
* @return The same thread pointer passed as parameter
* representing the new reference.
+ *
+ * @api
*/
Thread *chThdAddRef(Thread *tp) {
@@ -411,6 +439,8 @@ Thread *chThdAddRef(Thread *tp) {
* @note Static threads are not affected.
*
* @param[in] tp pointer to the thread
+ *
+ * @api
*/
void chThdRelease(Thread *tp) {
trefs_t refs;
@@ -469,6 +499,8 @@ void chThdRelease(Thread *tp) {
*
* @param[in] tp pointer to the thread
* @return The exit code from the terminated thread.
+ *
+ * @api
*/
msg_t chThdWait(Thread *tp) {
msg_t msg;
diff --git a/os/kernel/src/chvt.c b/os/kernel/src/chvt.c
index 058433c09..070a9c620 100644
--- a/os/kernel/src/chvt.c
+++ b/os/kernel/src/chvt.c
@@ -36,6 +36,8 @@ VTList vtlist;
/**
* @brief Virtual Timers initialization.
* @note Internal use only.
+ *
+ * @notapi
*/
void vt_init(void) {
@@ -58,6 +60,8 @@ void vt_init(void) {
* be disposed or reused.
* @param[in] par a parameter that will be passed to the callback
* function
+ *
+ * @iclass
*/
void chVTSetI(VirtualTimer *vtp, systime_t time, vtfunc_t vtfunc, void *par) {
VirtualTimer *p;
@@ -85,6 +89,8 @@ void chVTSetI(VirtualTimer *vtp, systime_t time, vtfunc_t vtfunc, void *par) {
* @note The timer MUST be active when this function is invoked.
*
* @param[in] vtp the @p VirtualTimer structure pointer
+ *
+ * @iclass
*/
void chVTResetI(VirtualTimer *vtp) {
@@ -110,6 +116,8 @@ void chVTResetI(VirtualTimer *vtp) {
* @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.
+ *
+ * @api
*/
bool_t chTimeIsWithin(systime_t start, systime_t end) {