2008-07-18 Joel Sherrill <joel.sherrill@oarcorp.com>

	PR 1291/cpukit
	* itron/inline/rtems/itron/semaphore.inl, itron/src/twai_sem.c,
	posix/include/mqueue.h, posix/include/rtems/posix/mqueue.h,
	posix/include/rtems/posix/semaphore.h,
	posix/include/rtems/posix/time.h, posix/src/condtimedwait.c,
	posix/src/mqueuereceive.c, posix/src/mqueuerecvsupp.c,
	posix/src/mqueuesend.c, posix/src/mqueuesendsupp.c,
	posix/src/mqueuetimedreceive.c, posix/src/mqueuetimedsend.c,
	posix/src/mutextimedlock.c, posix/src/mutextranslatereturncode.c,
	posix/src/posixtimespecabsolutetimeout.c,
	posix/src/prwlocktimedrdlock.c, posix/src/prwlocktimedwrlock.c,
	posix/src/semaphoretranslatereturncode.c,
	posix/src/semaphorewaitsupp.c, posix/src/semtimedwait.c,
	posix/src/semtrywait.c, posix/src/semwait.c,
	posix/src/sigtimedwait.c, posix/src/timersettime.c,
	posix/src/ualarm.c, rtems/src/semobtain.c,
	rtems/src/semtranslatereturncode.c,
	score/include/rtems/score/coremutex.h,
	score/include/rtems/score/coresem.h, score/src/coresemseize.c: This
	patch addresses issues on implementation of the timeout on the
	following POSIX services. Some of these services incorrectly took a
	timeout as a relative time. Others would compute a 0 delta to timeout
	if the absolute time and the current time were equal and thus
	incorrectly block the caller forever. The root of the confusion is
	that POSIX specifies that if the timeout is incorrect (e.g. in the
	past, is now, or is numerically invalid), that it does not matter if
	the call would succeed without blocking. This is in contrast to RTEMS
	programming style where all errors are checked before any critical
	sections are entered. This fix implemented a more uniform way of
	handling POSIX absolute time timeouts.
	    + pthread_cond_timedwait - could block forever
	    + mq_timedreceive - used relative not absolute time
	    + mq_timedsend - used relative not absolute time
	    + pthread_mutex_timedlock - used relative not absolute time
	    + pthread_rwlock_timedrdlock- used relative not absolute time
	    + pthread_rwlock_timedwrlock- used relative not absolute time
	    + sem_timedwait - could block forever

4 files changed, 62 insertions, 25 deletions

diff --git a/cpukit/posix/include/mqueue.h b/cpukit/posix/include/mqueue.h
index fe6975016d..c317d0c7bf 100644
--- a/cpukit/posix/include/mqueue.h
+++ b/cpukit/posix/include/mqueue.h
@@ -3,7 +3,7 @@
  */
 
 /*
- *  COPYRIGHT (c) 1989-2007.
+ *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).
  *
  *  The license and distribution terms for this file may be
@@ -33,47 +33,53 @@ extern "C" {
  *  15.1.1 Data Structures, P1003.1b-1993, p. 271
  */
 
+/**
+ *  Message queue id type
+ */
 typedef Objects_Id  mqd_t;
 
+/**
+ *  This is the message queue attributes structure.
+ */
 struct mq_attr {
-  long  mq_flags;     /* Message queue flags */
-  long  mq_maxmsg;    /* Maximum number of messages */
-  long  mq_msgsize;   /* Maximum message size */
-  long  mq_curmsgs;   /* Number of messages currently queued */
+  /** This is the message queue flags */
+  long  mq_flags;
+  /** This is the maximum number of messages */
+  long  mq_maxmsg;
+  /** This is the maximum message size */
+  long  mq_msgsize;
+  /** This is the mumber of messages currently queued */
+  long  mq_curmsgs;
 };
 
-/*
+/**
  *  15.2.2 Open a Message Queue, P1003.1b-1993, p. 272
  */
-
 mqd_t mq_open(
   const char *name,
   int         oflag,
   ...
 );
 
-/*
+/**
  *  15.2.2 Close a Message Queue, P1003.1b-1993, p. 275
  */
-
 int mq_close(
   mqd_t  mqdes
 );
 
-/*
+/**
  *  15.2.2 Remove a Message Queue, P1003.1b-1993, p. 276
  */
-
 int mq_unlink(
   const char *name
 );
 
-/*
+/**
  *  15.2.4 Send a Message to a Message Queue, P1003.1b-1993, p. 277
  *
- *  NOTE: P1003.4b/D8, p. 45 adds mq_timedsend().
+ *  @note P1003.4b/D8, p. 45 adds mq_timedsend().
  */
-
 int mq_send(
   mqd_t         mqdes,
   const char   *msg_ptr,
@@ -90,7 +96,7 @@ int mq_timedsend(
   const char            *msg_ptr,
   size_t                 msg_len,
   unsigned int           msg_prio,
-  const struct timespec *timeout
+  const struct timespec *abstime
 );
 
 #endif /* _POSIX_TIMEOUTS */
@@ -115,7 +121,7 @@ ssize_t mq_timedreceive(
   char                  *msg_ptr,
   size_t                 msg_len,
   unsigned int          *msg_prio,
-  const struct timespec *timeout
+  const struct timespec *abstime
 );
 
 #endif /* _POSIX_TIMEOUTS */
diff --git a/cpukit/posix/include/rtems/posix/mqueue.h b/cpukit/posix/include/rtems/posix/mqueue.h
index 475f9a2432..67dda09d93 100644
--- a/cpukit/posix/include/rtems/posix/mqueue.h
+++ b/cpukit/posix/include/rtems/posix/mqueue.h
@@ -6,7 +6,7 @@
  */
  
 /*
- *  COPYRIGHT (c) 1989-1999.
+ *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).
  *
  *  The license and distribution terms for this file may be
@@ -112,6 +112,7 @@ ssize_t _POSIX_Message_queue_Receive_support(
   char               *msg_ptr,
   size_t              msg_len,
   unsigned int       *msg_prio,
+  boolean             wait,
   Watchdog_Interval   timeout
 );
 
@@ -128,6 +129,7 @@ int _POSIX_Message_queue_Send_support(
   const char         *msg_ptr,
   size_t              msg_len,
   uint32_t            msg_prio,
+  boolean             wait,
   Watchdog_Interval   timeout
 );
 
diff --git a/cpukit/posix/include/rtems/posix/semaphore.h b/cpukit/posix/include/rtems/posix/semaphore.h
index 804a8bd0e3..f345aed8bd 100644
--- a/cpukit/posix/include/rtems/posix/semaphore.h
+++ b/cpukit/posix/include/rtems/posix/semaphore.h
@@ -7,7 +7,7 @@
  *  This include file contains all the private support information for
  *  POSIX Semaphores.
  *
- *  COPYRIGHT (c) 1989-2007.
+ *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).
  *
  *  The license and distribution terms for this file may be
@@ -153,9 +153,9 @@ void _POSIX_Semaphore_Delete(
  */
 
 int _POSIX_Semaphore_Wait_support(
-  sem_t                          *sem,
-  Core_semaphore_Blocking_option  blocking,
-  Watchdog_Interval               timeout
+  sem_t               *sem,
+  boolean              blocking,
+  Watchdog_Interval    timeout
 );
 
 /*
diff --git a/cpukit/posix/include/rtems/posix/time.h b/cpukit/posix/include/rtems/posix/time.h
index 8f4d4b6257..0782996399 100644
--- a/cpukit/posix/include/rtems/posix/time.h
+++ b/cpukit/posix/include/rtems/posix/time.h
@@ -3,7 +3,7 @@
  */
 
 /*
- *  COPYRIGHT (c) 1989-2007.
+ *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).
  *
  *  The license and distribution terms for this file may be
@@ -18,10 +18,39 @@
 
 #include <rtems/score/timespec.h>
 
-/*
- *  _POSIX_Absolute_timeout_to_ticks
+/** @brief Absolute Timeout Conversion Results
+ *
+ *  This enumeration defines the possible results of converting
+ *  an absolute time used for timeouts to POSIX blocking calls to
+ *  a number of ticks.
+ */
+typedef enum {
+  /** The timeout is invalid. */
+  POSIX_ABSOLUTE_TIMEOUT_INVALID,
+  /** The timeout represents a time that is in the past. */
+  POSIX_ABSOLUTE_TIMEOUT_IS_IN_PAST,
+  /** The timeout represents a time that is equal to the current time. */
+  POSIX_ABSOLUTE_TIMEOUT_IS_NOW,
+  /** The timeout represents a time that is in the future. */
+  POSIX_ABSOLUTE_TIMEOUT_IS_IN_FUTURE,
+} POSIX_Absolute_timeout_conversion_results_t;
+
+/**
+ *  @brief Convert Absolute Timeout to Ticks
+ *
+ *  This method takes an absolute time being used as a timeout
+ *  to a blocking directive, validates it and returns the number
+ *  of corresponding clock ticks for use by the SuperCore.
+ *
+ *  @param[in] abstime is the timeout
+ *  @param[in] ticks_out will contain the number of ticks
+ *
+ *  @return This method returns the number of ticks in @a ticks_out
+ *          and a status value indicating whether the absolute time
+ *          is valid, in the past, equal to the current time or in 
+ *          the future as it should be.
  */
-int _POSIX_Absolute_timeout_to_ticks(
+POSIX_Absolute_timeout_conversion_results_t _POSIX_Absolute_timeout_to_ticks(
   const struct timespec *abstime,
   Watchdog_Interval     *ticks_out
 );