Improvements to messages, new functions chMsgWaitS(), chMsgWaitTimeoutS(), chMsgWaitTimeout() (NIL).

git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@13187 27425a3e-05d8-49a3-a47f-9c15f0e5edd8

os/nil/include/chmsg.h

@@ -54,6 +54,24 @@
  * @name    Macro Functions
  * @{
  */
+/**
+ * @brief   Suspends the thread and waits for an incoming message.
+ * @post    After receiving a message the function @p chMsgGet() must be
+ *          called in order to retrieve the message and then @p chMsgRelease()
+ *          must be invoked in order to acknowledge the reception and send
+ *          the answer.
+ * @note    If the message is a pointer then 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.
+ * @note    The reference counter of the sender thread is not increased, the
+ *          returned pointer is a temporary reference.
+ *
+ * @return              A pointer to the thread carrying the message.
+ *
+ * @sclass
+ */
+#define chMsgWaitS() chMsgWaitTimeoutS(TIME_INFINITE)
+
 /**
  * @brief   Returns the message carried by the specified thread.
  * @pre     This function must be invoked immediately after exiting a call
@@ -91,6 +109,8 @@ extern "C" {
 #endif
   msg_t chMsgSend(thread_t *tp, msg_t msg);
   thread_t *chMsgWait(void);
+  thread_t *chMsgWaitTimeout(sysinterval_t timeout);
+  thread_t *chMsgWaitTimeoutS(sysinterval_t timeout);
   void chMsgRelease(thread_t *tp, msg_t msg);
 #ifdef __cplusplus
 }

os/nil/src/chmsg.c

@@ -101,11 +101,79 @@ thread_t *chMsgWait(void) {
   thread_t *tp;
 
   chSysLock();
+  tp = chMsgWaitS();
+  chSysUnlock();
+
+  return tp;
+}
+
+/**
+ * @brief   Suspends the thread and waits for an incoming message or a
+ *          timeout to occur.
+ * @post    After receiving a message the function @p chMsgGet() must be
+ *          called in order to retrieve the message and then @p chMsgRelease()
+ *          must be invoked in order to acknowledge the reception and send
+ *          the answer.
+ * @note    If the message is a pointer then 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.
+ * @note    The reference counter of the sender thread is not increased, the
+ *          returned pointer is a temporary reference.
+ *
+ * @param[in] timeout   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 pointer to the thread carrying the message.
+ * @retval NULL         if a timeout occurred.
+ *
+ * @api
+ */
+thread_t *chMsgWaitTimeout(sysinterval_t timeout) {
+  thread_t *tp;
+
+  chSysLock();
+  tp = chMsgWaitTimeoutS(timeout);
+  chSysUnlock();
+
+  return tp;
+}
+
+/**
+ * @brief   Suspends the thread and waits for an incoming message or a
+ *          timeout to occur.
+ * @post    After receiving a message the function @p chMsgGet() must be
+ *          called in order to retrieve the message and then @p chMsgRelease()
+ *          must be invoked in order to acknowledge the reception and send
+ *          the answer.
+ * @note    If the message is a pointer then 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.
+ * @note    The reference counter of the sender thread is not increased, the
+ *          returned pointer is a temporary reference.
+ *
+ * @param[in] timeout   the number of ticks before the operation timeouts,
+ *                      the following special values are allowed:
+ *                      - @a TIME_INFINITE no timeout.
+ *                      .
+ * @return              A pointer to the thread carrying the message.
+ * @retval NULL         if a timeout occurred.
+ *
+ * @sclass
+ */
+thread_t *chMsgWaitTimeoutS(sysinterval_t timeout) {
+  thread_t *tp;
+
+  chDbgCheckClassS();
+
   tp = nil_find_thread(NIL_STATE_SNDMSGQ, nil.current);
   if (tp == NULL) {
-    tp = (thread_t *)chSchGoSleepTimeoutS(NIL_STATE_WTMSG, TIME_INFINITE);
+    msg_t msg = chSchGoSleepTimeoutS(NIL_STATE_WTMSG, timeout);
+    if (msg != MSG_TIMEOUT) {
+      return (thread_t *)msg;
+    }
   }
-  chSysUnlock();
 
   return tp;
 }

os/rt/src/chmsg.c

@@ -121,6 +121,8 @@ msg_t chMsgSend(thread_t *tp, msg_t msg) {
 thread_t *chMsgWaitS(void) {
   thread_t *tp;
 
+  chDbgCheckClassS();
+
   if (!chMsgIsPendingI(currp)) {
     chSchGoSleepS(CH_STATE_WTMSG);
   }

readme.txt

@@ -75,9 +75,10 @@
 
 *** Next ***
 - LIB: Added support for delegate threads to OSLIB.
+- NIL: Improvements to messages, new functions chMsgWaitS(),
+       chMsgWaitTimeoutS(), chMsgWaitTimeout().  
 - RT:  Improvements to messages, new functions chMsgWaitS(),
-       chMsgWaitTimeoutS(), chMsgWaitTimeout(), chMsgWaitPollS(),
-       chMsgWaitPoll().  
+       chMsgWaitTimeoutS(), chMsgWaitTimeout(), chMsgPollS(), chMsgPoll().  
 - HAL: TRNG support added to STM32F7xx, STM32G0xx, STM32G4xx, STM32H7xx
        and STM32L0xx.
 - NEW: Added support for .cc files extensions in makefiles.