doc: release: posix: deprecate non-normative POSIX Kconfig

Add release notes for the deprecation of a number of POSIX
Kconfig options. These have been deprecated so that we can
use more normative Kconfig variable identifiers, based on
the Options and Option Groups of IEEE 1003.1-2017.

To simplify migration, use

python $ZEPHYR_BASE/scripts/utils/migrate_posix_kconfigs.py \
    -r root_path

Additionally, document the removal of PTHREAD_BARRIER_DEFINE(),
EFD_IN_USE, EFD_FLAGS_SET, which were previously deprecated
>= 2 release cycles before.

Signed-off-by: Chris Friedt <cfriedt@tenstorrent.com>

doc/releases/migration-guide-3.7.rst

@@ -581,6 +581,19 @@ Modem
 * The ``CONFIG_MODEM_CHAT_LOG_BUFFER`` Kconfig option was
   renamed to :kconfig:option:`CONFIG_MODEM_CHAT_LOG_BUFFER_SIZE`. (:github:`70405`)
 
+.. _zephyr_3.7_posix_api_migration:
+
+POSIX API
+=========
+
+* The :ref:`POSIX API Kconfig deprecations <zephyr_3.7_posix_api_deprecations>` may require
+  changes to Kconfig files (``prj.conf``, etc), as outlined in the release notes. A more automated
+  approach is available via the provided migration script. Simply run the following:
+
+  .. code-block:: bash
+
+    $ python ${ZEPHYR_BASE}/scripts/utils/migrate_posix_kconfigs.py -r root_path
+
 Shell
 =====
 

doc/releases/release-notes-3.7.rst

@@ -62,6 +62,55 @@ Deprecated in this release
    Application developer will now need to set the advertised name themselves by updating the advertising data
    or the scan response data.
 
+.. _zephyr_3.7_posix_api_deprecations:
+
+ * POSIX API
+
+  * Deprecated :c:macro:`PTHREAD_BARRIER_DEFINE` has been removed.
+  * Deprecated :c:macro:`EFD_IN_USE` and :c:macro:`EFD_FLAGS_SET` have been removed.
+
+  * In efforts to use Kconfig options that map directly to the Options and Option Groups in
+    IEEE 1003.1-2017, the following Kconfig options have been deprecated (replaced by):
+
+    * :kconfig:option:`CONFIG_EVENTFD_MAX` (:kconfig:option:`CONFIG_ZVFS_EVENTFD_MAX`)
+    * :kconfig:option:`CONFIG_FNMATCH` (:kconfig:option:`CONFIG_POSIX_C_LIB_EXT`)
+    * :kconfig:option:`CONFIG_GETENTROPY` (:kconfig:option:`CONFIG_POSIX_C_LIB_EXT`)
+    * :kconfig:option:`CONFIG_GETOPT` (:kconfig:option:`CONFIG_POSIX_C_LIB_EXT`)
+    * :kconfig:option:`CONFIG_MAX_PTHREAD_COUNT` (:kconfig:option:`CONFIG_POSIX_THREAD_THREADS_MAX`)
+    * :kconfig:option:`CONFIG_MAX_PTHREAD_KEY_COUNT` (:kconfig:option:`CONFIG_POSIX_THREAD_KEYS_MAX`)
+    * :kconfig:option:`CONFIG_MAX_TIMER_COUNT` (:kconfig:option:`CONFIG_POSIX_TIMER_MAX`)
+    * :kconfig:option:`CONFIG_POSIX_LIMITS_RTSIG_MAX` (:kconfig:option:`CONFIG_POSIX_RTSIG_MAX`)
+    * :kconfig:option:`CONFIG_POSIX_CLOCK` (:kconfig:option:`CONFIG_POSIX_CLOCK_SELECTION`,
+      :kconfig:option:`CONFIG_POSIX_CPUTIME`, :kconfig:option:`CONFIG_POSIX_MONOTONIC_CLOCK`,
+      :kconfig:option:`CONFIG_POSIX_TIMERS`, and :kconfig:option:`CONFIG_POSIX_TIMEOUTS`)
+    * :kconfig:option:`CONFIG_POSIX_CONFSTR` (:kconfig:option:`CONFIG_POSIX_SINGLE_PROCESS`)
+    * :kconfig:option:`CONFIG_POSIX_ENV` (:kconfig:option:`CONFIG_POSIX_SINGLE_PROCESS`)
+    * :kconfig:option:`CONFIG_POSIX_FS` (:kconfig:option:`CONFIG_POSIX_FILE_SYSTEM`)
+    * :kconfig:option:`CONFIG_POSIX_MAX_FDS` (:kconfig:option:`CONFIG_POSIX_OPEN_MAX` and
+      :kconfig:option:`CONFIG_ZVFS_OPEN_MAX`)
+    * :kconfig:option:`CONFIG_POSIX_MAX_OPEN_FILES` (:kconfig:option:`CONFIG_POSIX_OPEN_MAX` and
+      :kconfig:option:`CONFIG_ZVFS_OPEN_MAX`)
+    * :kconfig:option:`CONFIG_POSIX_MQUEUE` (:kconfig:option:`CONFIG_POSIX_MESSAGE_PASSING`)
+    * :kconfig:option:`CONFIG_POSIX_PUTMSG` (:kconfig:option:`CONFIG_XOPEN_STREAMS`)
+    * :kconfig:option:`CONFIG_POSIX_SIGNAL` (:kconfig:option:`CONFIG_POSIX_SIGNALS`)
+    * :kconfig:option:`CONFIG_POSIX_SYSCONF` (:kconfig:option:`CONFIG_POSIX_SINGLE_PROCESS`)
+    * :kconfig:option:`CONFIG_POSIX_SYSLOG` (:kconfig:option:`CONFIG_XSI_SYSTEM_LOGGING`)
+    * :kconfig:option:`CONFIG_POSIX_UNAME` (:kconfig:option:`CONFIG_POSIX_SINGLE_PROCESS`)
+    * :kconfig:option:`CONFIG_PTHREAD` (:kconfig:option:`CONFIG_POSIX_THREADS`)
+    * :kconfig:option:`CONFIG_PTHREAD_BARRIER` (:kconfig:option:`CONFIG_POSIX_BARRIERS`)
+    * :kconfig:option:`CONFIG_PTHREAD_COND` (:kconfig:option:`CONFIG_POSIX_THREADS`)
+    * :kconfig:option:`CONFIG_PTHREAD_IPC` (:kconfig:option:`CONFIG_POSIX_THREADS`)
+    * :kconfig:option:`CONFIG_PTHREAD_KEY` (:kconfig:option:`CONFIG_POSIX_THREADS`)
+    * :kconfig:option:`CONFIG_PTHREAD_MUTEX` (:kconfig:option:`CONFIG_POSIX_THREADS`)
+    * :kconfig:option:`CONFIG_PTHREAD_RWLOCK` (:kconfig:option:`CONFIG_POSIX_READER_WRITER_LOCKS`)
+    * :kconfig:option:`CONFIG_PTHREAD_SPINLOCK` (:kconfig:option:`CONFIG_POSIX_SPIN_LOCKS`)
+    * :kconfig:option:`CONFIG_SEM_NAMELEN_MAX` (:kconfig:option:`CONFIG_POSIX_SEM_NAMELEN_MAX`)
+    * :kconfig:option:`CONFIG_SEM_VALUE_MAX` (:kconfig:option:`CONFIG_POSIX_SEM_VALUE_MAX`)
+    * :kconfig:option:`CONFIG_TIMER` (:kconfig:option:`CONFIG_POSIX_TIMERS`)
+    * :kconfig:option:`CONFIG_TIMER_DELAYTIMER_MAX` (:kconfig:option:`CONFIG_POSIX_DELAYTIMER_MAX`)
+
+    Please see the :ref:`POSIX API migration guide <zephyr_3.7_posix_api_migration>`.
+
  * SPI
 
   * Deprecated :c:func:`spi_is_ready` API function has been removed.

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

@@ -39,7 +39,7 @@ POSIX System Interfaces
     _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_POSIX_READER_WRITER_LOCKS`
-    :ref:`_POSIX_REALTIME_SIGNALS<posix_option_group_realtime_signals>`, -1,
+    :ref:`_POSIX_REALTIME_SIGNALS<posix_option_group_realtime_signals>`, -1, :kconfig:option:`CONFIG_POSIX_REALTIME_SIGNALS`
     :ref:`_POSIX_SEMAPHORES<posix_option_group_semaphores>`, 200809L, :kconfig:option:`CONFIG_POSIX_SEMAPHORES`
     :ref:`_POSIX_SPIN_LOCKS<posix_option_group_spin_locks>`, 200809L, :kconfig:option:`CONFIG_POSIX_SPIN_LOCKS`
     :ref:`_POSIX_THREAD_SAFE_FUNCTIONS<posix_thread_safe_functions>`, -1, :kconfig:option:`CONFIG_POSIX_THREAD_SAFE_FUNCTIONS`

lib/posix/options/signal.c

@@ -8,6 +8,7 @@
 #include <errno.h>
 #include <stdio.h>
 
+#include <zephyr/posix/pthread.h>
 #include <zephyr/posix/signal.h>
 
 #define SIGNO_WORD_IDX(_signo) (signo / BITS_PER_LONG)

scripts/utils/migrate_posix_kconfigs.py

@@ -0,0 +1,137 @@
+"""
+Utility script to migrate Zephyr-based projects to normative POSIX Kconfig options.
+
+This script should be used for migrating from versions of Zephyr older than v3.7.0 to Zephyr
+version v3.7.0 or later.
+
+Usage::
+
+    python $ZEPHYR_BASE/scripts/utils/migrate_posix_kconfigs.py -r root_path
+
+The utility will process c, cpp, h, hpp, rst, conf, CMakeLists.txt,
+yml, yaml and Kconfig files.
+
+
+Copyright (c) 2022 Nordic Semiconductor ASA
+Copyright (c) 2024 Tenstorrent AI ULC
+SPDX-License-Identifier: Apache-2.0
+"""
+
+import argparse
+from pathlib import Path
+import re
+import sys
+
+
+ZEPHYR_BASE = Path(__file__).parents[2]
+
+FILE_PATTERNS = (
+    r".+\.c", r".+\.cpp", r".+\.hpp", r".+\.h", r".+\.rst", r".+\.conf",
+    r".+\.yml", r".+\.yaml", r"CMakeLists.txt", r"Kconfig(\..+)?"
+)
+
+REPLACEMENTS = {
+    "EVENTFD_MAX": "ZVFS_EVENTFD_MAX",
+    "FNMATCH": "POSIX_C_LIB_EXT",
+    "GETENTROPY": "POSIX_C_LIB_EXT",
+    "GETOPT": "POSIX_C_LIB_EXT",
+    "MAX_PTHREAD_COUNT": "POSIX_THREAD_THREADS_MAX",
+    "MAX_PTHREAD_KEY_COUNT": "POSIX_THREAD_KEYS_MAX",
+    "MAX_TIMER_COUNT": "POSIX_TIMER_MAX",
+    "MSG_COUNT_MAX": "POSIX_MQ_OPEN_MAX",
+    "POSIX_CLOCK": "POSIX_TIMERS",
+    "POSIX_CONFSTR": "POSIX_SINGLE_PROCESS",
+    "POSIX_ENV": "POSIX_SINGLE_PROCESS",
+    "POSIX_FS": "POSIX_FILE_SYSTEM",
+    "POSIX_LIMITS_RTSIG_MAX": "POSIX_RTSIG_MAX",
+    "POSIX_MAX_FDS": "ZVFS_OPEN_MAX",
+    "POSIX_MAX_OPEN_FILES": "ZVFS_OPEN_MAX",
+    "POSIX_MQUEUE": "POSIX_MESSAGE_PASSING",
+    "POSIX_PUTMSG": "XOPEN_STREAMS",
+    "POSIX_SIGNAL": "POSIX_SIGNALS",
+    "POSIX_SYSCONF": "POSIX_SINGLE_PROCESS",
+    "POSIX_SYSLOG": "XSI_SYSTEM_LOGGING",
+    "POSIX_UNAME": "POSIX_SINGLE_PROCESS",
+    "PTHREAD": "POSIX_THREADS",
+    "PTHREAD_BARRIER": "POSIX_BARRIERS",
+    "PTHREAD_COND": "POSIX_THREADS",
+    "PTHREAD_IPC": "POSIX_THREADS",
+    "PTHREAD_KEY": "POSIX_THREADS",
+    "PTHREAD_MUTEX": "POSIX_THREADS",
+    "PTHREAD_RWLOCK": "POSIX_READER_WRITER_LOCKS",
+    "PTHREAD_SPINLOCK": "POSIX_SPIN_LOCKS",
+    "TIMER": "POSIX_TIMERS",
+    "TIMER_DELAYTIMER_MAX": "POSIX_DELAYTIMER_MAX",
+    "SEM_NAMELEN_MAX": "POSIX_SEM_NAME_MAX",
+    "SEM_VALUE_MAX": "POSIX_SEM_VALUE_MAX",
+}
+
+MESSAGES = {
+    "POSIX_CLOCK":
+        "POSIX_CLOCK is a one-to-many replacement. If this simple substitution is not "
+        "sufficient, it's best to try a combination of POSIX_CLOCK_SELECTION, POSIX_CPUTIME, "
+        "POSIX_MONOTONIC_CLOCK, POSIX_TIMERS, and POSIX_TIMEOUTS.",
+    "POSIX_MAX_FDS":
+        "A read-only version of this symbol is POSIX_OPEN_MAX, which is of course, the standard "
+        "symbol. ZVFS_OPEN_MAX may be set by the user. Consider using POSIX_MAX_FDS if the "
+        "use-case is read-only.",
+}
+
+
+def process_file(path):
+    modified = False
+    output = []
+
+    try:
+        with open(path) as f:
+            lines = f.readlines()
+
+            for line in lines:
+                longest = ""
+                length = 0
+                for m in REPLACEMENTS:
+                    if re.match(".*" + m + ".*", line) and len(m) > length:
+                        length = len(m)
+                        longest = m
+
+                if length != 0:
+                    modified = True
+                    line = line.replace(longest, REPLACEMENTS[longest])
+                    msg = MESSAGES.get(longest)
+                    if msg:
+                        print(
+                            f"Notice: {longest} -> {REPLACEMENTS[longest]}: {msg}")
+
+                output.append(line)
+
+        if modified is False:
+            return
+
+        with open(path, "w") as f:
+            f.writelines(output)
+
+    except UnicodeDecodeError:
+        print(f"Unable to read lines from {path}", file=sys.stderr)
+    except Exception as e:
+        print(f"Failed with exception {e}", e)
+
+
+def process_tree(project):
+    for p in project.glob("**/*"):
+        for fp in FILE_PATTERNS:
+            cfp = re.compile(".+/" + fp + "$")
+            if re.match(cfp, str(p)) is not None:
+                process_file(p)
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(allow_abbrev=False)
+    parser.add_argument(
+        "-r",
+        "--root",
+        type=Path,
+        required=True,
+        help="Zephyr-based project path")
+    args = parser.parse_args()
+
+    process_tree(args.root)