config: Document CONFIGURE_POSIX_TIMERS_FACE_BEHAVIOR

Update #4691.

1 files changed, 49 insertions, 0 deletions

diff --git a/cpukit/doxygen/appl-config.h b/cpukit/doxygen/appl-config.h
index 85290fd4bc..005d47e7b1 100644
--- a/cpukit/doxygen/appl-config.h
+++ b/cpukit/doxygen/appl-config.h
@@ -1995,6 +1995,55 @@
 
 /** @} */
 
+/* Generated from spec:/acfg/if/group-face */
+
+/**
+ * @defgroup RTEMSApplConfigFACETechnicalStandardRelatedConfiguration \
+ *   FACE Technical Standard Related Configuration
+ *
+ * @ingroup RTEMSApplConfig
+ *
+ * This section describes configuration options related to adapting RTEMS
+ * behavior to be aligned with the FACE Technical Standard. The FACE Technical
+ * Standard is a product of the FACE Consortium which operates under the Open
+ * Group. The FACE Consortium was founded by avionics organizations to improve
+ * the portability of cockpit software across various platforms. It addresses
+ * technical and business concerns.
+ *
+ * Most important from an RTEMS perspective, the FACE Technical Standard
+ * defines four POSIX profiles: Security, Safety Base, Safety Extended, and the
+ * General Purpose Profile. Each has an increasingly larger subset of POSIX
+ * APIs. In the Security and Safety profiles, ARINC 653 is required. It is
+ * optional in the General Purpose Profile.
+ *
+ * The RTEMS Project has been tracking alignment with the FACE POSIX profiles
+ * and they are included in the "RTEMS POSIX 1003.1 Compliance Guide."
+ *
+ * @{
+ */
+
+/* Generated from spec:/acfg/if/posix-timer-face-behavior */
+
+/**
+ * @brief This configuration option is a boolean feature define.
+ *
+ * If this configuration option is defined, then POSIX timers may not be
+ * created to use the CLOCK_REALTIME.  Per POSIX, this is allowed behavior but
+ * per the FACE Technical Standard, it is not. Using POSIX timers based on
+ * CLOCK_REALTIME (e.g., time of day) is unsafe for real-time safety systems as
+ * setting CLOCK_REALTIME will perturb any active timers.
+ *
+ * If this option is not defined, POSIX timers may be created to use the
+ * CLOCK_REALTIME in compliance with the POSIX specification.
+ *
+ * @par Default Configuration
+ * If this configuration option is undefined, then the described feature is not
+ * enabled.
+ */
+#define CONFIGURE_POSIX_TIMERS_FACE_BEHAVIOR
+
+/** @} */
+
 /* Generated from spec:/acfg/if/group-filesystem */
 
 /**