posix: timers: deprecate the non-standard option POSIX_CLOCK

The POSIX_CLOCK option does not correspond to any standard
option. It was used to active features of several distinct
POSIX Options and Option Groups, which complicated API and
application configuration as a result.

POSIX_CLOCK is being deprecated in order to ensure that Zephyr's
POSIX Kconfig variables correspond to those defined in the
specification, as of IEEE 1003.1-2017.

With this deprecation, we introduce the following Kconfig
options that map directly to standard POSIX Option Groups by
simply removing "CONFIG_":

* CONFIG_POSIX_TIMERS

Similarly, we introduce the following Kconfig options that
map directly to standard POSIX Options by simply removing
"CONFIG":

* CONFIG_POSIX_CLOCK_SELECTION
* CONFIG_POSIX_CPUTIME
* CONFIG_POSIX_DELAYTIMER_MAX
* CONFIG_POSIX_MONOTONIC_CLOCK
* CONFIG_POSIX_TIMEOUTS
* CONFIG_POSIX_TIMER_MAX

In order to maintain parity with the current feature set, we
introduce the following Kconfig options that map directly to
standard POSIX Option Groups by simply removing "CONFIG_":

* CONFIG_POSIX_MULTI_PROCESS - sleep()

Similarly, in order to maintain parity with the current feature
set, we introduce the following additional Kconfig options that
map directly to standard POSIX Options by simply removing
"CONFIG":

* CONFIG_XSI_SINGLE_PROCESS - gettimeofday()

Signed-off-by: Chris Friedt <[email protected]>

doc/connectivity/networking/api/lwm2m.rst

@@ -521,7 +521,7 @@ engine.
 
 Data caches depends on one of the SenML data formats
 :kconfig:option:`CONFIG_LWM2M_RW_SENML_CBOR_SUPPORT` or
-:kconfig:option:`CONFIG_LWM2M_RW_SENML_JSON_SUPPORT` and needs :kconfig:option:`CONFIG_POSIX_CLOCK`
+:kconfig:option:`CONFIG_LWM2M_RW_SENML_JSON_SUPPORT` and needs :kconfig:option:`CONFIG_POSIX_TIMERS`
 so it can request a timestamp from the system and :kconfig:option:`CONFIG_RING_BUFFER` for ring
 buffer.
 

doc/services/portability/posix/aep/index.rst

@@ -63,7 +63,7 @@ The *Minimal Realtime System Profile* (PSE51) includes all of the
     :ref:`_POSIX_FSYNC <posix_option_fsync>`, 200809L, :kconfig:option:`CONFIG_POSIX_FSYNC`
     :ref:`_POSIX_MEMLOCK <posix_option_memlock>`, -1,
     :ref:`_POSIX_MEMLOCK_RANGE <posix_option_memlock_range>`, -1,
-    :ref:`_POSIX_MONOTONIC_CLOCK <posix_option_monotonic_clock>`, 200809L, :kconfig:option:`CONFIG_POSIX_CLOCK`
+    :ref:`_POSIX_MONOTONIC_CLOCK <posix_option_monotonic_clock>`, 200809L, :kconfig:option:`CONFIG_POSIX_MONOTONIC_CLOCK`
     :ref:`_POSIX_SHARED_MEMORY_OBJECTS <posix_shared_memory_objects>`, -1,
     :ref:`_POSIX_SYNCHRONIZED_IO <posix_option_synchronized_io>`, -1,
     :ref:`_POSIX_THREAD_ATTR_STACKADDR<posix_option_thread_attr_stackaddr>`, 200809L, :kconfig:option:`CONFIG_PTHREAD`

doc/services/portability/posix/conformance/index.rst

@@ -63,7 +63,7 @@ POSIX System Interfaces
     _POSIX_VERSION, 200809L,
     :ref:`_POSIX_ASYNCHRONOUS_IO<posix_option_asynchronous_io>`, 200809L, :ref:`†<posix_undefined_behaviour>`
     :ref:`_POSIX_BARRIERS<posix_option_group_barriers>`, 200809L, :kconfig:option:`CONFIG_PTHREAD_BARRIER`
-    :ref:`_POSIX_CLOCK_SELECTION<posix_option_group_clock_selection>`, 200809L, :kconfig:option:`CONFIG_POSIX_CLOCK`
+    :ref:`_POSIX_CLOCK_SELECTION<posix_option_group_clock_selection>`, 200809L, :kconfig:option:`CONFIG_POSIX_CLOCK_SELECTION`
     _POSIX_MAPPED_FILES, -1, :ref:`†<posix_undefined_behaviour>`
     _POSIX_MEMORY_PROTECTION, -1, :ref:`†<posix_undefined_behaviour>`
     :ref:`_POSIX_READER_WRITER_LOCKS<posix_option_reader_writer_locks>`, 200809L, :kconfig:option:`CONFIG_PTHREAD_IPC`
@@ -73,21 +73,21 @@ POSIX System Interfaces
     :ref:`_POSIX_THREAD_SAFE_FUNCTIONS<posix_thread_safe_functions>`, -1,
     :ref:`_POSIX_THREADS<posix_option_group_threads_base>`, -1, :kconfig:option:`CONFIG_PTHREAD_IPC`
     :ref:`_POSIX_TIMEOUTS<posix_option_timeouts>`, 200809L, :kconfig:option:`CONFIG_PTHREAD_IPC`
-    :ref:`_POSIX_TIMERS<posix_option_group_timers>`, 200809L, :kconfig:option:`CONFIG_POSIX_CLOCK`
+    :ref:`_POSIX_TIMERS<posix_option_group_timers>`, 200809L, :kconfig:option:`CONFIG_POSIX_TIMERS`
     _POSIX2_C_BIND, 200809L,
 
 .. csv-table:: POSIX System Interfaces (Optional)
    :header: Symbol, Support, Remarks
    :widths: 50, 10, 50
 
     _POSIX_ADVISORY_INFO, -1,
-    _POSIX_CPUTIME, 200809L, :kconfig:option:`CONFIG_POSIX_CLOCK`
+    _POSIX_CPUTIME, 200809L, :kconfig:option:`CONFIG_POSIX_CPUTIME`
     :ref:`_POSIX_FSYNC<posix_option_fsync>`, 200809L, :kconfig:option:`CONFIG_POSIX_FSYNC`
     _POSIX_IPV6, 200809L, :kconfig:option:`CONFIG_NET_IPV6`
     _POSIX_MEMLOCK, -1,
     _POSIX_MEMLOCK_RANGE, -1,
     :ref:`_POSIX_MESSAGE_PASSING<posix_option_message_passing>`, 200809L, :kconfig:option:`CONFIG_POSIX_MQUEUE`
-    :ref:`_POSIX_MONOTONIC_CLOCK<posix_option_monotonic_clock>`, 200809L, :kconfig:option:`CONFIG_POSIX_CLOCK`
+    :ref:`_POSIX_MONOTONIC_CLOCK<posix_option_monotonic_clock>`, 200809L, :kconfig:option:`CONFIG_POSIX_MONOTONIC_CLOCK`
     _POSIX_PRIORITIZED_IO, -1,
     :ref:`_POSIX_PRIORITY_SCHEDULING<posix_option_priority_scheduling>`, 200809L, :kconfig:option:`CONFIG_POSIX_PRIORITY_SCHEDULING`
     _POSIX_RAW_SOCKETS, 200809L, :kconfig:option:`CONFIG_NET_SOCKETS_PACKET`

doc/services/portability/posix/kconfig/index.rst

@@ -25,7 +25,6 @@ implementation of the POSIX API.
 * :kconfig:option:`CONFIG_NET_SOCKETS`
 * :kconfig:option:`CONFIG_NET_SOCKETS_POLL_MAX`
 * :kconfig:option:`CONFIG_POSIX_API`
-* :kconfig:option:`CONFIG_POSIX_CLOCK`
 * :kconfig:option:`CONFIG_POSIX_FS`
 * :kconfig:option:`CONFIG_POSIX_MAX_FDS`
 * :kconfig:option:`CONFIG_POSIX_MAX_OPEN_FILES`
@@ -46,4 +45,3 @@ implementation of the POSIX API.
 * :kconfig:option:`CONFIG_PTHREAD_RECYCLER_DELAY_MS`
 * :kconfig:option:`CONFIG_PTHREAD_SPINLOCK`
 * :kconfig:option:`CONFIG_SEM_VALUE_MAX`
-* :kconfig:option:`CONFIG_TIMER`

include/zephyr/posix/posix_features.h

@@ -31,11 +31,13 @@
 #define _POSIX_BARRIERS _POSIX_VERSION
 #endif
 
-#ifdef CONFIG_POSIX_CLOCK
+#ifdef CONFIG_POSIX_CLOCK_SELECTION
 #define _POSIX_CLOCK_SELECTION _POSIX_VERSION
 #endif
 
-/* #define _POSIX_CPUTIME (-1L) */
+#ifdef CONFIG_POSIX_CPUTIME
+#define _POSIX_CPUTIME _POSIX_VERSION
+#endif
 
 #ifdef CONFIG_POSIX_FSYNC
 #define _POSIX_FSYNC _POSIX_VERSION
@@ -55,7 +57,7 @@
 #define _POSIX_MESSAGE_PASSING _POSIX_VERSION
 #endif
 
-#ifdef CONFIG_POSIX_CLOCK
+#ifdef CONFIG_POSIX_MONOTONIC_CLOCK
 #define _POSIX_MONOTONIC_CLOCK _POSIX_VERSION
 #endif
 
@@ -124,11 +126,11 @@
 #endif
 #endif
 
-#ifdef CONFIG_POSIX_CLOCK
+#ifdef CONFIG_POSIX_TIMEOUTS
 #define _POSIX_TIMEOUTS _POSIX_VERSION
 #endif
 
-#ifdef CONFIG_POSIX_CLOCK
+#ifdef CONFIG_POSIX_TIMERS
 #define _POSIX_TIMERS _POSIX_VERSION
 #endif
 

include/zephyr/posix/sys/sysconf.h

@@ -146,8 +146,9 @@ enum {
 	COND_CODE_1(CONFIG_POSIX_ASYNCHRONOUS_IO, (_POSIX_ASYNCHRONOUS_IO), (-1L))
 #define __z_posix_sysconf_SC_BARRIERS COND_CODE_1(CONFIG_PTHREAD_BARRIER, (_POSIX_BARRIERS), (-1L))
 #define __z_posix_sysconf_SC_CLOCK_SELECTION                                                       \
-	COND_CODE_1(CONFIG_POSIX_CLOCK, (_POSIX_CLOCK_SELECTION), (-1L))
-#define __z_posix_sysconf_SC_CPUTIME           (-1L)
+	COND_CODE_1(CONFIG_POSIX_CLOCK_SELECTION, (_POSIX_CLOCK_SELECTION), (-1L))
+#define __z_posix_sysconf_SC_CPUTIME \
+	COND_CODE_1(CONFIG_POSIX_CPUTIME, (_POSIX_CPUTIME), (-1L))
 #define __z_posix_sysconf_SC_FSYNC                                                                 \
 	COND_CODE_1(CONFIG_POSIX_FSYNC, (_POSIX_FSYNC), (-1L))
 #define __z_posix_sysconf_SC_IPV6              COND_CODE_1(CONFIG_NET_IPV6, (_POSIX_IPV6), (-1L))
@@ -159,7 +160,7 @@ enum {
 #define __z_posix_sysconf_SC_MESSAGE_PASSING                                                       \
 	COND_CODE_1(CONFIG_POSIX_MQUEUE, (_POSIX_MESSAGE_PASSING), (-1L))
 #define __z_posix_sysconf_SC_MONOTONIC_CLOCK                                                       \
-	COND_CODE_1(CONFIG_POSIX_CLOCK, (_POSIX_MONOTONIC_CLOCK), (-1L))
+	COND_CODE_1(CONFIG_POSIX_MONOTONIC_CLOCK, (_POSIX_MONOTONIC_CLOCK), (-1L))
 #define __z_posix_sysconf_SC_PRIORITIZED_IO (-1L)
 #define __z_posix_sysconf_SC_PRIORITY_SCHEDULING                                                   \
 	COND_CODE_1(CONFIG_POSIX_PRIORITY_SCHEDULING, (_POSIX_PRIORITY_SCHEDULING), (-1L))
@@ -199,9 +200,9 @@ enum {
 #define __z_posix_sysconf_SC_THREADS                                                               \
 	COND_CODE_1(CONFIG_PTHREAD_IPC, (_POSIX_THREADS), (-1L))
 #define __z_posix_sysconf_SC_TIMEOUTS                                                              \
-	COND_CODE_1(CONFIG_POSIX_CLOCK, (_POSIX_TIMEOUTS), (-1L))
+	COND_CODE_1(CONFIG_POSIX_TIMEOUTS, (_POSIX_TIMEOUTS), (-1L))
 #define __z_posix_sysconf_SC_TIMERS                                                                \
-	COND_CODE_1(CONFIG_TIMERS, (_POSIX_TIMERS), (-1))
+	COND_CODE_1(CONFIG_POSIX_TIMEOUTS, (_POSIX_TIMERS), (-1))
 #define __z_posix_sysconf_SC_TRACE                        (-1L)
 #define __z_posix_sysconf_SC_TRACE_EVENT_FILTER           (-1L)
 #define __z_posix_sysconf_SC_TRACE_EVENT_NAME_MAX         _POSIX_TRACE_NAME_MAX
@@ -228,7 +229,7 @@ enum {
 #define __z_posix_sysconf_SC_2_C_DEV                      _POSIX2_C_DEV
 #define __z_posix_sysconf_SC_2_CHAR_TERM                  (-1L)
 #define __z_posix_sysconf_SC_COLL_WEIGHTS_MAX             _POSIX2_COLL_WEIGHTS_MAX
-#define __z_posix_sysconf_SC_DELAYTIMER_MAX               _POSIX2_DELAYTIMER_MAX
+#define __z_posix_sysconf_SC_DELAYTIMER_MAX               _POSIX_DELAYTIMER_MAX
 #define __z_posix_sysconf_SC_EXPR_NEST_MAX                _POSIX2_EXPR_NEST_MAX
 #define __z_posix_sysconf_SC_2_FORT_DEV                   (-1L)
 #define __z_posix_sysconf_SC_2_FORT_RUN                   (-1L)

lib/libc/minimal/Kconfig

@@ -78,13 +78,13 @@ config MINIMAL_LIBC_RAND
 
 config MINIMAL_LIBC_TIME
 	bool "Time functions"
-	select COMMON_LIBC_TIME if POSIX_CLOCK
+	select COMMON_LIBC_TIME if POSIX_TIMERS
 	select COMMON_LIBC_GMTIME_R
 	default y
 	help
 	  Enable time() and gmtime_r() for the minimal libc.
 
-	  time() requires CONFIG_POSIX_CLOCK=y because it relies on the POSIX
+	  time() requires CONFIG_POSIX_TIMERS=y because it relies on the POSIX
 	  clock_gettime() function.
 
 	  In order to make use of the non-reentrant gmtime(), it is necessary

lib/libc/newlib/libc-hooks.c

@@ -565,7 +565,7 @@ void *_sbrk_r(struct _reent *r, int count)
 
 int _gettimeofday(struct timeval *__tp, void *__tzp)
 {
-#ifdef CONFIG_POSIX_CLOCK
+#ifdef CONFIG_XSI_SINGLE_PROCESS
 	return gettimeofday(__tp, __tzp);
 #else
 	/* Non-posix systems should not call gettimeofday() here as it will

lib/posix/options/CMakeLists.txt

@@ -39,18 +39,22 @@ zephyr_library_sources_ifdef(CONFIG_FNMATCH fnmatch.c)
 zephyr_library_sources_ifdef(CONFIG_GETENTROPY getentropy.c)
 zephyr_library_sources_ifdef(CONFIG_POSIX_API perror.c)
 zephyr_library_sources_ifdef(CONFIG_POSIX_ASYNCHRONOUS_IO aio.c)
-zephyr_library_sources_ifdef(CONFIG_POSIX_CLOCK clock.c)
-zephyr_library_sources_ifdef(CONFIG_POSIX_CLOCK nanosleep.c)
-zephyr_library_sources_ifdef(CONFIG_POSIX_CLOCK sleep.c)
 zephyr_library_sources_ifdef(CONFIG_POSIX_CONFSTR confstr.c)
 zephyr_library_sources_ifdef(CONFIG_POSIX_ENV env.c)
 zephyr_library_sources_ifdef(CONFIG_POSIX_FS fs.c)
 zephyr_library_sources_ifdef(CONFIG_POSIX_MQUEUE mqueue.c)
+zephyr_library_sources_ifdef(CONFIG_POSIX_MULTI_PROCESS
+  sleep.c
+)
 zephyr_library_sources_ifdef(CONFIG_POSIX_NETWORKING net.c)
 zephyr_library_sources_ifdef(CONFIG_POSIX_PUTMSG stropts.c)
 zephyr_library_sources_ifdef(CONFIG_POSIX_SIGNAL signal.c ${STRSIGNAL_TABLE_H})
 zephyr_library_sources_ifdef(CONFIG_POSIX_SYSCONF_IMPL_FULL sysconf.c)
 zephyr_library_sources_ifdef(CONFIG_POSIX_SYSLOG syslog.c)
+zephyr_library_sources_ifdef(CONFIG_POSIX_TIMERS
+  clock.c
+  timer.c
+)
 zephyr_library_sources_ifdef(CONFIG_POSIX_UNAME uname.c)
 zephyr_library_sources_ifdef(CONFIG_PTHREAD_IPC _common.c)
 zephyr_library_sources_ifdef(CONFIG_PTHREAD_BARRIER barrier.c)

lib/posix/options/Kconfig

@@ -13,21 +13,17 @@ config POSIX_API
 	  Enable mostly-standards-compliant implementations of
 	  various POSIX (IEEE 1003.1) APIs.
 
-if POSIX_CLOCK
-
 config PTHREAD_IPC
 	bool "POSIX pthread IPC API"
 	default y if POSIX_API
+	depends on POSIX_TIMERS
 	help
 	  This enables a mostly-standards-compliant implementation of
 	  the pthread mutex, condition variable and barrier IPC
 	  mechanisms.
 
-endif # POSIX_CLOCK
-
 rsource "Kconfig.aio"
 rsource "Kconfig.barrier"
-rsource "Kconfig.clock"
 rsource "Kconfig.cond"
 rsource "Kconfig.confstr"
 rsource "Kconfig.env"
@@ -41,6 +37,7 @@ rsource "Kconfig.key"
 rsource "Kconfig.mqueue"
 rsource "Kconfig.mutex"
 rsource "Kconfig.net"
+rsource "Kconfig.procN"
 rsource "Kconfig.pthread"
 rsource "Kconfig.rwlock"
 rsource "Kconfig.sched"
@@ -52,6 +49,7 @@ rsource "Kconfig.sysconf"
 rsource "Kconfig.syslog"
 rsource "Kconfig.timer"
 rsource "Kconfig.uname"
+rsource "Kconfig.xsi"
 
 rsource "Kconfig.deprecated"
 

lib/posix/options/Kconfig.deprecated

@@ -4,10 +4,34 @@
 
 # This file should be removed after Zephyr 4.0 is released
 
+config MAX_TIMER_COUNT
+	int "Maximum number of timer_t [DEPRECATED]"
+	default 0
+	help
+	  This option is deprecated.
+
+	  Please use CONFIG_POSIX_TIMER_MAX instead.
+
+config POSIX_CLOCK
+	bool "clock and sleep APIs [DEPRECATED]"
+	select DEPRECATED
+	help
+	  This option is deprecated.
+
+	  Please use CONFIG_POSIX_TIMERS instead.
+
 config POSIX_LIMITS_RTSIG_MAX
 	int "_POSIX_RTSIG_MAX value in limits.h [DEPRECATED]"
 	default 0
 	help
 	  This option is deprecated.
 
 	  Please use CONFIG_POSIX_RTSIG_MAX instead.
+
+config TIMER
+	bool "Timer support [DEPRECATED]"
+	select DEPRECATED
+	help
+	  This option is deprecated.
+
+	  Please use CONFIG_POSIX_TIMERS instead.

lib/posix/options/Kconfig.procN

@@ -0,0 +1,15 @@
+# Copyright (c) 2024 Tenstorrent AI ULC
+#
+# SPDX-License-Identifier: Apache-2.0
+
+config POSIX_MULTI_PROCESS
+	bool "Support for multiple POSIX processes"
+	default y if POSIX_API
+	help
+	  Support for multi-processing.
+
+	  Note: Currently Zephyr does not support multiple processes and therefore much of this option
+	  group is not implemented and is considered undefined behaviour.
+
+	  For more information, please see
+	  https://pubs.opengroup.org/onlinepubs/9699919799/xrat/V4_subprofiles.html

lib/posix/options/Kconfig.timer

@@ -1,13 +1,76 @@
 # Copyright (c) 2018 Intel Corporation
+# Copyright (c) 2024 Tenstorrent AI ULC
 #
 # SPDX-License-Identifier: Apache-2.0
 
-TYPE = TIMER
-type = timer_t
-type-function = timer_create
-rsource "Kconfig.template.pooled_type"
+menuconfig POSIX_TIMERS
+	bool "POSIX timers, clocks, and sleep functions"
+	default y if POSIX_API
+	help
+	  Select 'y' here and Zephyr will provide implementations of clock_getres(), clock_gettime(),
+	  clock_settime(), nanosleep(), timer_create(), timer_delete(), timer_getoverrun(),
+	  timer_settime(), and timer_gettime().
+
+	  For more information, please see
+	  https://pubs.opengroup.org/onlinepubs/9699919799/xrat/V4_subprofiles.html
+
+if POSIX_TIMERS
+
+config POSIX_MONOTONIC_CLOCK
+	bool "POSIX Monotonic clock support"
+	default y
+	help
+	  This enables CLOCK_MONOTONIC.
+
+	  For more information, please see
+	  https://pubs.opengroup.org/onlinepubs/9699919799/xrat/V4_port.html
+
+config POSIX_CPUTIME
+	bool "POSIX per-process CPU-time clocks"
+	default y
+	help
+	  This enables CLOCK_PROCESS_CPUTIME_ID.
+
+	  For more information, please see
+	  https://pubs.opengroup.org/onlinepubs/9699919799/xrat/V4_port.html
+
+config POSIX_CLOCK_SELECTION
+	bool "POSIX Clock selection"
+	default y
+	help
+	  This enables POSIX clock selection.
 
-if TIMER
+	  For more information, please see
+	  https://pubs.opengroup.org/onlinepubs/9699919799/xrat/V4_port.html
+
+config POSIX_DELAYTIMER_MAX
+	int "Maximum count returned my timer_getoverrun() in POSIX application"
+	default 32
+	help
+	  This controls the maximum number of times a timer can overrun before
+	  timer_getoverrun() in POSIX compliant application.
+
+	  For more information, please see
+	  https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/limits.h.html
+
+config POSIX_TIMER_MAX
+	int "Maximum number of POSIX timers per process"
+	default 32
+	help
+	  Maximum simultaneously active timer_t in a POSIX application.
+
+	  For more information, please see
+	  https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/limits.h.html
+
+config POSIX_TIMEOUTS
+	bool "Support timeouts for some blocking POSIX services"
+	default y
+	help
+	  Enable mandatory timeouts for some blocking operations.
+
+	  For more information, please see
+	  https://pubs.opengroup.org/onlinepubs/9699919799/xrat/V4_port.html
+	  https://pubs.opengroup.org/onlinepubs/9699919799/xrat/V4_xbd_chap02.html
 
 config TIMER_CREATE_WAIT
 	int "Time to wait for timer availability (in msec) in POSIX application"
@@ -17,11 +80,8 @@ config TIMER_CREATE_WAIT
 	  This controls how long to wait for resources to come available to create
 	  a new timer in POSIX compliant application
 
-config TIMER_DELAYTIMER_MAX
-	int "Maximum count returned my timer_getoverrun() in POSIX application"
-	default 20
-	help
-	  This controls the maximum number of times a timer can overrun before
-	  timer_getoverrun() in POSIX compliant application.
+module = TIMER
+module-str = POSIX Timers
+source "subsys/logging/Kconfig.template.log_config"
 
-endif # TIMER
+endif # POSIX_TIMERS