Fixes to the documentation, swapped the values of constants TIME_INFINITE and TIME_IMMEDIATE (previously TIME_ZERO).

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

8 files changed, 95 insertions, 82 deletions

diff --git a/src/chcond.c b/src/chcond.c
index fea5bebee..ef58f1ddf 100644
--- a/src/chcond.c
+++ b/src/chcond.c
@@ -164,8 +164,9 @@ msg_t chCondWaitS(CondVar *cp) {
  * @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_ZERO) as timeout

- *                 specification.

+ *                 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().

@@ -191,8 +192,9 @@ msg_t chCondWaitTimeout(CondVar *cp, systime_t time) {
  * @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_ZERO) as timeout

- *                 specification.

+ *                 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().

diff --git a/src/chevents.c b/src/chevents.c
index 5633b7de3..a7089cb13 100644
--- a/src/chevents.c
+++ b/src/chevents.c
@@ -290,7 +290,7 @@ eventmask_t chEvtWaitAll(eventmask_t ewmask) {
  *                   @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_ZERO immediate timeout.

+ *                 - @a TIME_IMMEDIATE immediate timeout.

  *                 - @a TIME_INFINITE no timeout.

  *                 .

  * @return The mask of the lowest id served and cleared event.

@@ -307,7 +307,7 @@ eventmask_t chEvtWaitOneTimeout(eventmask_t ewmask, systime_t time) {
   chSysLock();

 

   if ((m = (currp->p_epending & ewmask)) == 0) {

-    if (TIME_ZERO == time)

+    if (TIME_IMMEDIATE == time)

       return (eventmask_t)0;

     currp->p_ewmask = ewmask;

     if (chSchGoSleepTimeoutS(PRWTOREVT, time) < RDY_OK)

@@ -331,7 +331,7 @@ eventmask_t chEvtWaitOneTimeout(eventmask_t ewmask, systime_t time) {
  *                   @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_ZERO immediate timeout.

+ *                 - @a TIME_IMMEDIATE immediate timeout.

  *                 - @a TIME_INFINITE no timeout.

  *                 .

  * @return The mask of the served and cleared events.

@@ -343,7 +343,7 @@ eventmask_t chEvtWaitAnyTimeout(eventmask_t ewmask, systime_t time) {
   chSysLock();

 

   if ((m = (currp->p_epending & ewmask)) == 0) {

-    if (TIME_ZERO == time)

+    if (TIME_IMMEDIATE == time)

       return (eventmask_t)0;

     currp->p_ewmask = ewmask;

     if (chSchGoSleepTimeoutS(PRWTOREVT, time) < RDY_OK)

@@ -364,7 +364,7 @@ eventmask_t chEvtWaitAnyTimeout(eventmask_t ewmask, systime_t time) {
  * @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_ZERO immediate timeout.

+ *                 - @a TIME_IMMEDIATE immediate timeout.

  *                 - @a TIME_INFINITE no timeout.

  *                 .

  * @return The mask of the served and cleared events.

@@ -375,7 +375,7 @@ eventmask_t chEvtWaitAllTimeout(eventmask_t ewmask, systime_t time) {
   chSysLock();

 

   if ((currp->p_epending & ewmask) != ewmask) {

-    if (TIME_ZERO == time)

+    if (TIME_IMMEDIATE == time)

       return (eventmask_t)0;

     currp->p_ewmask = ewmask;

     if (chSchGoSleepTimeoutS(PRWTANDEVT, time) < RDY_OK)

diff --git a/src/chmboxes.c b/src/chmboxes.c
index 25c4001ef..743b5a568 100644
--- a/src/chmboxes.c
+++ b/src/chmboxes.c
@@ -72,7 +72,7 @@ void chMBReset(Mailbox *mbp) {
  * @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_ZERO immediate timeout.

+ *                 - @a TIME_IMMEDIATE immediate timeout.

  *                 - @a TIME_INFINITE no timeout.

  *                 .

  * @return The operation status.

@@ -98,7 +98,7 @@ msg_t chMBPost(Mailbox *mbp, msg_t msg, systime_t time) {
  * @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_ZERO immediate timeout.

+ *                 - @a TIME_IMMEDIATE immediate timeout.

  *                 - @a TIME_INFINITE no timeout.

  *                 .

  * @return The operation status.

@@ -131,7 +131,7 @@ msg_t chMBPostS(Mailbox *mbp, msg_t msg, systime_t time) {
  * @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_ZERO immediate timeout.

+ *                 - @a TIME_IMMEDIATE immediate timeout.

  *                 - @a TIME_INFINITE no timeout.

  *                 .

  * @return The operation status.

@@ -157,7 +157,7 @@ msg_t chMBPostAhead(Mailbox *mbp, msg_t msg, systime_t time) {
  * @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_ZERO immediate timeout.

+ *                 - @a TIME_IMMEDIATE immediate timeout.

  *                 - @a TIME_INFINITE no timeout.

  *                 .

  * @return The operation status.

@@ -190,7 +190,7 @@ msg_t chMBPostAheadS(Mailbox *mbp, msg_t msg, systime_t time) {
  * @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_ZERO immediate timeout.

+ *                 - @a TIME_IMMEDIATE immediate timeout.

  *                 - @a TIME_INFINITE no timeout.

  *                 .

  * @return The operation status.

@@ -216,7 +216,7 @@ msg_t chMBFetch(Mailbox *mbp, msg_t *msgp, systime_t time) {
  * @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_ZERO immediate timeout.

+ *                 - @a TIME_IMMEDIATE immediate timeout.

  *                 - @a TIME_INFINITE no timeout.

  *                 .

  * @return The operation status.

diff --git a/src/chschd.c b/src/chschd.c
index 629a659e0..8a5c27857 100644
--- a/src/chschd.c
+++ b/src/chschd.c
@@ -124,7 +124,7 @@ static void wakeup(void *p) {
  * @param[in] newstate the new thread state
  * @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_ZERO) as timeout
+ *                 It is not possible to specify @p TIME_IMMEDIATE as timeout
  *                 specification.
  * @return The wakeup message.
  * @retval RDY_TIMEOUT if a timeout occurs.
diff --git a/src/chsem.c b/src/chsem.c
index b5717e69c..6c254e836 100644
--- a/src/chsem.c
+++ b/src/chsem.c
@@ -134,7 +134,7 @@ msg_t chSemWaitS(Semaphore *sp) {
  * @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_ZERO immediate timeout.

+ *             - @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().

@@ -158,7 +158,7 @@ msg_t chSemWaitTimeout(Semaphore *sp, systime_t time) {
  * @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_ZERO immediate timeout.

+ *                 - @a TIME_IMMEDIATE immediate timeout.

  *                 - @a TIME_INFINITE no timeout.

  *                 .

  * @retval RDY_OK if the semaphore was signaled or not taken.

@@ -173,7 +173,7 @@ msg_t chSemWaitTimeoutS(Semaphore *sp, systime_t time) {
   chDbgCheck(sp != NULL, "chSemWaitTimeoutS");

 

   if (--sp->s_cnt < 0) {

-    if (TIME_ZERO == time)

+    if (TIME_IMMEDIATE == time)

       return RDY_TIMEOUT;

     sem_insert(currp, &sp->s_queue);

     currp->p_wtsemp = sp;

diff --git a/src/chthreads.c b/src/chthreads.c
index 902867a41..a22514f09 100644
--- a/src/chthreads.c
+++ b/src/chthreads.c
@@ -69,15 +69,16 @@ static void memfill(uint8_t *startp, uint8_t *endp, uint8_t v) {
 /**
  * @brief Initializes a new thread.
  * @details The new thread is initialized but not inserted in the ready list,
- * the initial state is @p PRSUSPENDED.
+ *          the initial state is @p PRSUSPENDED.
  *
- * @param prio the priority level for the new thread. Usually the threads are
- *             created with priority @p NORMALPRIO, priorities
- *             can range from @p LOWPRIO to @p HIGHPRIO.
- * @param workspace pointer to a working area dedicated to the thread stack
- * @param wsize size of the working area.
- * @param pf the thread function
- * @param arg an argument passed to the thread function. It can be @p NULL.
+ * @param[out] workspace pointer to a working area dedicated to the thread
+ *                       stack
+ * @param[in] wsize size of the working area.
+ * @param[in] prio the priority level for the new thread. Usually the threads
+ *                 are created with priority @p NORMALPRIO, priorities
+ *                 can range from @p LOWPRIO to @p HIGHPRIO.
+ * @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.
  * @note A thread can terminate by calling @p chThdExit() or by simply
@@ -109,13 +110,14 @@ Thread *chThdInit(void *workspace, size_t wsize,
 /**
  * @brief Creates a new thread into a static memory area.
  *
- * @param workspace pointer to a working area dedicated to the thread stack
- * @param wsize size of the working area.
- * @param prio the priority level for the new thread. Usually the threads are
- *             created with priority @p NORMALPRIO, priorities
+ * @param[out] workspace pointer to a working area dedicated to the thread
+ *                       stack
+ * @param[in] wsize size of the working area.
+ * @param[in] prio the priority level for the new thread. Usually the threads
+ *             are created with priority @p NORMALPRIO, priorities
  *             can range from @p LOWPRIO to @p HIGHPRIO.
- * @param pf the thread function
- * @param arg an argument passed to the thread function. It can be @p NULL.
+ * @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.
  * @note A thread can terminate by calling @p chThdExit() or by simply
@@ -131,12 +133,12 @@ Thread *chThdCreateStatic(void *workspace, size_t wsize,
 /**
  * @brief Creates a new thread allocating the memory from the heap.
  *
- * @param wsize size of the working area to be allocated
- * @param prio the priority level for the new thread. Usually the threads are
- *             created with priority @p NORMALPRIO, priorities
- *             can range from @p LOWPRIO to @p HIGHPRIO.
- * @param pf the thread function
- * @param arg an argument passed to the thread function. It can be @p NULL.
+ * @param[in] wsize size of the working area to be allocated
+ * @param[in] prio the priority level for the new thread. Usually the threads
+ *                 are created with priority @p NORMALPRIO, priorities
+ *                 can range from @p LOWPRIO to @p HIGHPRIO.
+ * @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.
@@ -163,14 +165,14 @@ Thread *chThdCreateFromHeap(size_t wsize, tprio_t prio,
 #if CH_USE_DYNAMIC && CH_USE_WAITEXIT && CH_USE_MEMPOOLS
 /**
  * @brief Creates a new thread allocating the memory from the specified Memory
- * Pool.
+ *        Pool.
  *
- * @param mp the memory pool
- * @param prio the priority level for the new thread. Usually the threads are
- *             created with priority @p NORMALPRIO, priorities
- *             can range from @p LOWPRIO to @p HIGHPRIO.
- * @param pf the thread function
- * @param arg an argument passed to the thread function. It can be @p NULL.
+ * @param[in] mp the memory pool
+ * @param[in] prio the priority level for the new thread. Usually the threads
+ *                 are created with priority @p NORMALPRIO, priorities
+ *                 can range from @p LOWPRIO to @p HIGHPRIO.
+ * @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.
@@ -200,9 +202,9 @@ Thread *chThdCreateFromMemoryPool(MemoryPool *mp, tprio_t prio,
 
 /**
  * @brief Changes the running thread priority level then reschedules if
- * necessary.
+ *        necessary.
  *
- * @param newprio the new priority level of the running thread
+ * @param[in] newprio the new priority level of the running thread
  * @return The old priority level.
  * @note The function returns the real thread priority regardless of the
  *       actual priority that could be higher than the real priority because
@@ -232,7 +234,7 @@ tprio_t chThdSetPriority(tprio_t newprio) {
 /**
  * @brief Resumes a suspended thread.
  *
- * @param tp the pointer to the thread
+ * @param[in] tp the pointer to the thread
  * @return The pointer to the thread.
  * @note This call is supposed to resume threads created with @p chThdInit().
  *       It should not be used on threads suspended using @p chThdSuspend().
@@ -251,7 +253,7 @@ Thread *chThdResume(Thread *tp) {
 /**
  * @brief Requests a thread termination.
  *
- * @param tp the pointer to the thread
+ * @param[in] tp the pointer to the thread
  * @note The thread is not termitated but a termination request is added to
  *       its @p p_flags field. The thread can read this status by
  *       invoking @p chThdShouldTerminate() and then terminate cleanly.
@@ -266,10 +268,14 @@ void chThdTerminate(Thread *tp) {
 /**
  * @brief Suspends the invoking thread for the specified time.
  *
- * @param time the delay in system ticks
+ * @param[in] time the delay in system ticks, the values @p TIME_IMMEDIATE and
+ *                 @p TIME_INFINITE are not allowed
  */
 void chThdSleep(systime_t time) {
 
+  chDbgCheck((time != TIME_IMMEDIATE) && (time != TIME_INFINITE),
+             "chThdSleep");
+
   chSysLock();
   chThdSleepS(time);
   chSysUnlock();
@@ -277,9 +283,9 @@ void chThdSleep(systime_t time) {
 
 /**
  * @brief Suspends the invoking thread until the system time arrives to the
- * specified value.
+ *        specified value.
  *
- * @param time the absolute system time
+ * @param[in] time the absolute system time
  */
 void chThdSleepUntil(systime_t time) {
 
@@ -292,8 +298,8 @@ void chThdSleepUntil(systime_t time) {
 /**
  * @brief Terminates the current thread by specifying an exit status code.
  *
- * @param msg the thread exit code. The code can be retrieved by using
- *            @p chThdWait().
+ * @param[in] msg the thread exit code. The code can be retrieved by using
+ *                @p chThdWait().
  */
 void chThdExit(msg_t msg) {
   Thread *tp = currp;
@@ -311,18 +317,19 @@ void chThdExit(msg_t msg) {
 #if CH_USE_WAITEXIT
 /**
  * @brief Blocks the execution of the invoking thread until the specified
- * thread terminates then the exit code is returned.
+ *        thread terminates then the exit code is returned.
  * @details The memory used by the exited thread is handled in different ways
- * depending on the API that spawned the thread:
- * - If the thread was spawned by @p chThdCreateStatic() or by @p chThdInit()
- *   then nothing happens and the thread working area is not released or
- *   modified in any way. This is the default, totally static, behavior.
- * - If the thread was spawned by @p chThdCreateFromHeap() then the working
- *   area is returned to the system heap.
- * - If the thread was spawned by @p chThdCreateFromMemoryPool() then the
- *   working area is returned to the owning memory pool.
- *
- * @param tp the thread pointer
+ *          depending on the API that spawned the thread:
+ *          - If the thread was spawned by @p chThdCreateStatic() or by
+ *            @p chThdInit() then nothing happens and the thread working area
+ *            is not released or modified in any way. This is the default,
+ *            totally static, behavior.
+ *          - If the thread was spawned by @p chThdCreateFromHeap() then
+ *            the working area is returned to the system heap.
+ *          - If the thread was spawned by @p chThdCreateFromMemoryPool()
+ *            then the working area is returned to the owning memory pool.
+ *          .
+ * @param[in] tp the thread pointer
  * @return The exit code from the terminated thread
  * @note After invoking @p chThdWait() the thread pointer becomes invalid and
  *       must not be used as parameter for further system calls.
diff --git a/src/chvt.c b/src/chvt.c
index f37ddd423..76ab6a7f3 100644
--- a/src/chvt.c
+++ b/src/chvt.c
@@ -43,13 +43,15 @@ void vt_init(void) {
 /**

  * @brief Enables a virtual timer.

  *

- * @param vtp the @p VirtualTimer structure pointer

- * @param time the number of time ticks, the values @p TIME_ZERO and

- *             @p TIME_INFINITE are not allowed

- * @param vtfunc the timer callback function. After invoking the callback

- *               the timer is disabled and the structure can be disposed or

- *               reused.

- * @param par a parameter that will be passed to the callback function

+ * @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.

  */

@@ -57,7 +59,7 @@ void chVTSetI(VirtualTimer *vtp, systime_t time, vtfunc_t vtfunc, void *par) {
   VirtualTimer *p;

 

   chDbgCheck((vtp != NULL) && (vtfunc != NULL) &&

-             (time != TIME_ZERO) && (time != TIME_INFINITE), "chVTSetI");

+             (time != TIME_IMMEDIATE) && (time != TIME_INFINITE), "chVTSetI");

 

   vtp->vt_par = par;

   vtp->vt_func = vtfunc;

@@ -77,7 +79,7 @@ void chVTSetI(VirtualTimer *vtp, systime_t time, vtfunc_t vtfunc, void *par) {
 /**

  * @brief Disables a Virtual Timer.

  *

- * @param vtp the @p VirtualTimer structure pointer

+ * @param[in] vtp the @p VirtualTimer structure pointer

  * @note The timer MUST be active when this function is invoked.

  */

 void chVTResetI(VirtualTimer *vtp) {

@@ -96,8 +98,10 @@ void chVTResetI(VirtualTimer *vtp) {
 /**

  * @brief Checks if the current system time is within the specified time window.

  *

- * @param start the start of the time window (inclusive)

- * @param end the end of the time window (non inclusive)

+ * @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 chSysInTimeWindow(systime_t start, systime_t end) {

 

diff --git a/src/include/scheduler.h b/src/include/scheduler.h
index 565496dd3..648cb7bc5 100644
--- a/src/include/scheduler.h
+++ b/src/include/scheduler.h
@@ -44,16 +44,16 @@
 /**
  * Zero time specification for some syscalls with a timeout
  * specification.
- * @note Not all functions accept @p TIME_ZERO as timeout parameter, see the
- *       specific documentation.
+ * @note Not all functions accept @p TIME_IMMEDIATE as timeout parameter,
+ *       see the specific function documentation.
  */
-#define TIME_ZERO   ((systime_t)0)
+#define TIME_IMMEDIATE  ((systime_t)-1)
 
 /**
  * Infinite time specification for all the syscalls with a timeout
  * specification.
  */
-#define TIME_INFINITE   ((systime_t)-1)
+#define TIME_INFINITE   ((systime_t)0)
 
 /** The priority of the first thread on the given ready list. */
 #define firstprio(rlp)  ((rlp)->p_next->p_prio)