Add support for CONFIGURE_POSIX_TIMERS_FACE_BEHAVIOR

This adds the configure option CONFIGURE_POSIX_TIMERS_FACE_BEHAVIOR
which allows the application to choose whether to have the POSIX
timer_create() function follow the behavior defined by POSIX or
the FACE Technical Standard.

Updates #4691.

4 files changed, 129 insertions, 2 deletions

diff --git a/cpukit/include/rtems/confdefs.h b/cpukit/include/rtems/confdefs.h
index e6dd3d70ee..3927d26ec5 100644
--- a/cpukit/include/rtems/confdefs.h
+++ b/cpukit/include/rtems/confdefs.h
@@ -64,6 +64,7 @@
 #include <rtems/confdefs/clock.h>
 #include <rtems/confdefs/console.h>
 #include <rtems/confdefs/extensions.h>
+#include <rtems/confdefs/face.h>
 #include <rtems/confdefs/inittask.h>
 #include <rtems/confdefs/initthread.h>
 #include <rtems/confdefs/iodrivers.h>
diff --git a/cpukit/include/rtems/confdefs/face.h b/cpukit/include/rtems/confdefs/face.h
new file mode 100644
index 0000000000..25f321108c
--- /dev/null
+++ b/cpukit/include/rtems/confdefs/face.h
@@ -0,0 +1,81 @@
+/* SPDX-License-Identifier: BSD-2-Clause */
+
+/**
+ * @file
+ *
+ * @ingroup RTEMSImplApplConfig
+ *
+ * @brief This header file evaluates configuration options related to
+ *   the FACE Technical Standard.
+ *
+ * The FACE Technical Standard (https://opengroup.org/face) is an
+ * open standard designed for safety critical embedded systems. It
+ * includes POSIX profiles and requirements that promote safety
+ * and portability. As a general rules, the profiles place a minimum
+ * on the services which an operating system must provide. Those
+ * same profile definitions represent the maximum services which
+ * an application may use. 
+ */
+
+/*
+ * Copyright (C) 2022 On-Line Applications Research Corporation (OAR)
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ * 1. Redistributions of source code must retain the above copyright
+ *    notice, this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright
+ *    notice, this list of conditions and the following disclaimer in the
+ *    documentation and/or other materials provided with the distribution.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ */
+
+#ifndef _RTEMS_CONFDEFS_FACE_H
+#define _RTEMS_CONFDEFS_FACE_H
+
+#ifndef __CONFIGURATION_TEMPLATE_h
+#error "Do not include this file directly, use <rtems/confdefs.h> instead"
+#endif
+
+#ifdef CONFIGURE_INIT
+
+#include <rtems/posix/timer.h>
+
+#ifdef CONFIGURE_POSIX_TIMERS_FACE_BEHAVIOR
+  int _POSIX_Timer_Is_allowed(
+    clockid_t clock_id
+  )
+  {
+    /*
+     * Per the FACE Technical Standard, POSIX timers should not be
+     * allowed on CLOCK_REALTIME for safety reasons. If the application
+     * wants the FACE behavior, then this method is instantiated.
+     */
+    if (  clock_id == CLOCK_REALTIME ) {
+      return EPERM;
+    }
+
+    if ( clock_id != CLOCK_MONOTONIC ) {
+      return EINVAL;
+    }
+
+    return 0;
+  }
+
+#endif /* CONFIGURE_POSIX_TIMERS_FACE_BEHAVIOR */
+
+#endif /* CONFIGURE_INIT */
+
+#endif /* _RTEMS_CONFDEFS_FACE_H */
diff --git a/cpukit/include/rtems/posix/timer.h b/cpukit/include/rtems/posix/timer.h
index 05a6f36eab..86b45ba05d 100644
--- a/cpukit/include/rtems/posix/timer.h
+++ b/cpukit/include/rtems/posix/timer.h
@@ -94,6 +94,24 @@ extern Objects_Information _POSIX_Timer_Information;
     NULL \
   )
 
+/**
+ * @brief Follow POSIX or FACE Technical Standard on timer_create
+ *
+ * POSIX allows for the creation of timers based on CLOCK_REALTIME.
+ * This is viewed as a safety issue by the FACE Technical Standard
+ * and required to return an error. These are conflicting behaviors.
+ * This method is instanced by configuration when FACE conformant
+ * behavior is desired by the application.
+ *
+ * @param[in] clock_id is the clock ID to validate
+ *
+ * @return 0 if @a clock_id is allowed for use. Otherwise an errno value.
+ */
+int _POSIX_Timer_Is_allowed(
+  clockid_t clock_id
+);
+
+
 /** @} */
 
 #ifdef __cplusplus
diff --git a/cpukit/posix/src/psxtimercreate.c b/cpukit/posix/src/psxtimercreate.c
index 0eefac3f42..907da01836 100644
--- a/cpukit/posix/src/psxtimercreate.c
+++ b/cpukit/posix/src/psxtimercreate.c
@@ -51,6 +51,31 @@
 #include <rtems/seterr.h>
 #include <rtems/sysinit.h>
 
+RTEMS_WEAK int _POSIX_Timer_Is_allowed(
+  clockid_t clock_id
+)
+{
+  int rc = 0;
+
+  /*
+   * Allow timer_create(CLOCK_REALTIME. ...) per POSIX by default
+   * on CLOCK_REALTIME or CLOCK_MONOTONIC.
+   *
+   * But per the FACE Technical Standard, POSIX timers should not be
+   * allowed on CLOCK_REALTIME for safety reasons. If the application
+   * configures that it wants the FACE behavior, then this method
+   * is overridden by <rtems/confdefs/timer.h>.
+   */
+
+  if (  clock_id != CLOCK_REALTIME ) {
+    if ( clock_id != CLOCK_MONOTONIC ) {
+      rc  = EINVAL;
+    }
+  }
+
+  return rc;
+}
+
 int timer_create(
   clockid_t        clock_id,
   struct sigevent *__restrict evp,
@@ -58,9 +83,11 @@ int timer_create(
 )
 {
   POSIX_Timer_Control *ptimer;
+  int                  rc;
 
-  if (  clock_id != CLOCK_REALTIME && clock_id != CLOCK_MONOTONIC )
-    rtems_set_errno_and_return_minus_one( EINVAL );
+  rc = _POSIX_Timer_Is_allowed( clock_id );
+  if ( rc != 0 )
+    rtems_set_errno_and_return_minus_one( rc );
 
   if ( !timerid )
     rtems_set_errno_and_return_minus_one( EINVAL );