doc: posix: structural reorganization of posix docs

Revise the structure of the POSIX API docs. This separates related items out to dedicated pages. Further improvements could yet be made - e.g. using the 'collapse' feature to expand and collapse large sections of text or tables. Signed-off-by: Christopher Friedt <[email protected]> (cherry picked from commit 3b45235)
zephyrproject-rtos · Dec 7, 2023 · 15ada15 · 15ada15
1 parent 2d8508b
commit 15ada15
Show file tree

Hide file tree

Showing 11 changed files with 851 additions and 179 deletions.
diff --git a/doc/_scripts/redirects.py b/doc/_scripts/redirects.py
@@ -71,7 +71,7 @@
     ('guides/pm/power_domain', 'services/pm/power_domain'),
     ('guides/pm/system', 'services/pm/system'),
     ('guides/portability/index', 'services/portability/index'),
-    ('guides/portability/posix', 'services/portability/posix'),
+    ('guides/portability/posix', 'services/portability/posix/index'),
     ('guides/porting/arch', 'hardware/porting/arch'),
     ('guides/porting/board_porting', 'hardware/porting/board_porting'),
     ('guides/porting/index', 'hardware/porting/index'),

diff --git a/doc/introduction/index.rst b/doc/introduction/index.rst
@@ -80,6 +80,8 @@ Zephyr offers a large and ever growing number of features including:
      * Red/black tree ready queue
      * Traditional multi-queue ready queue
 
+.. _zephyr_intro_configurability:
+
 **Highly configurable / Modular for flexibility**
    Allows an application to incorporate *only* the capabilities it needs as it
    needs them, and to specify their quantity and size.

diff --git a/doc/services/portability/index.rst b/doc/services/portability/index.rst
@@ -14,6 +14,6 @@ supported by the Zephyr RTOS.
 .. toctree::
    :maxdepth: 1
 
-   posix.rst
+   posix/index.rst
    cmsis_rtos_v1.rst
    cmsis_rtos_v2.rst
diff --git a/doc/services/portability/posix/aep/index.rst b/doc/services/portability/posix/aep/index.rst
@@ -0,0 +1,191 @@
+.. _posix_aep:
+
+POSIX Application Environment Profiles (AEP)
+############################################
+
+Although inactive, `IEEE 1003.13-2003`_ defined a number of AEP that inspired the modern
+subprofiling options of `IEEE 1003.1-2017`_. The single-purpose realtime system profiles
+are listed below, for reference, in terms that agree with the current POSIX-1 standard. PSE54
+is not considered at this time.
+
+.. _posix_aep_pse51:
+
+Minimal Realtime System Profile (PSE51)
+=======================================
+
+.. Conforming implementations shall define _POSIX_AEP_REALTIME_MINIMAL to the value 200312L
+
+.. csv-table:: PSE51 System Interfaces
+   :header: Symbol, Support, Remarks
+   :widths: 50, 10, 50
+
+    _POSIX_AEP_REALTIME_MINIMAL, -1,
+
+.. csv-table:: PSE51 Option Groups
+   :header: Symbol, Support, Remarks
+   :widths: 50, 10, 50
+
+    POSIX_C_LANG_JUMP,,
+    POSIX_C_LANG_SUPPORT, yes, :ref:`†<posix_undefined_behaviour>`
+    POSIX_DEVICE_IO,, :ref:`†<posix_undefined_behaviour>`
+    POSIX_FILE_LOCKING,,
+    POSIX_SIGNALS,, :ref:`†<posix_undefined_behaviour>`
+    POSIX_SINGLE_PROCESS,, :ref:`†<posix_undefined_behaviour>`
+    POSIX_THREADS_BASE, yes, :ref:`†<posix_undefined_behaviour>`
+    XSI_THREADS_EXT, yes, :ref:`†<posix_undefined_behaviour>`
+
+.. csv-table:: PSE51 Option Requirements
+   :header: Symbol, Support, Remarks
+   :widths: 50, 10, 50
+
+    _POSIX_CLOCK_SELECTION, 200809L, :kconfig:option:`CONFIG_POSIX_CLOCK`
+    _POSIX_FSYNC, -1,
+    _POSIX_MEMLOCK, -1,
+    _POSIX_MEMLOCK_RANGE, -1,
+    _POSIX_MONOTONIC_CLOCK, 200809L, :kconfig:option:`CONFIG_POSIX_CLOCK`
+    _POSIX_REALTIME_SIGNALS, -1,
+    _POSIX_SEMAPHORES, 200809L, :kconfig:option:`CONFIG_PTHREAD_IPC`
+    _POSIX_SHARED_MEMORY_OBJECTS, -1,
+    _POSIX_SYNCHRONIZED_IO, -1,
+    _POSIX_THREAD_ATTR_STACKADDR, 200809L, :kconfig:option:`CONFIG_PTHREAD`
+    _POSIX_THREAD_ATTR_STACKSIZE, 200809L, :kconfig:option:`CONFIG_PTHREAD`
+    _POSIX_THREAD_CPUTIME, -1,
+    _POSIX_THREAD_PRIO_INHERIT, 200809L, :kconfig:option:`CONFIG_PTHREAD_MUTEX`
+    _POSIX_THREAD_PRIO_PROTECT, -1,
+    _POSIX_THREAD_PRIORITY_SCHEDULING, -1,
+    _POSIX_THREAD_SPORADIC_SERVER, -1,
+    _POSIX_TIMEOUTS, 200809L, :kconfig:option:`CONFIG_PTHREAD_IPC`
+    _POSIX_TIMERS, 200809L, :kconfig:option:`CONFIG_POSIX_CLOCK`
+
+.. note::
+    For PSE51 support, 44 of 75 symbols are currently implemented.
+
+.. _posix_aep_pse52:
+
+Realtime Controller System Profile (PSE52)
+==========================================
+
+.. Conforming implementations shall define _POSIX_AEP_REALTIME_CONTROLLER to the value 200312L
+
+.. csv-table:: PSE52 System Interfaces
+   :header: Symbol, Support, Remarks
+   :widths: 50, 10, 50
+
+    _POSIX_AEP_REALTIME_CONTROLLER, -1,
+
+.. csv-table:: PSE52 Option Groups
+   :header: Symbol, Support, Remarks
+   :widths: 50, 10, 50
+
+    POSIX_C_LANG_JUMP,,
+    POSIX_C_LANG_MATH, yes,
+    POSIX_C_LANG_SUPPORT, yes, :ref:`†<posix_undefined_behaviour>`
+    POSIX_DEVICE_IO,, :ref:`†<posix_undefined_behaviour>`
+    POSIX_FD_MGMT,,
+    POSIX_FILE_LOCKING,,
+    POSIX_FILE_SYSTEM,,
+    POSIX_SIGNALS,, :ref:`†<posix_undefined_behaviour>`
+    POSIX_SINGLE_PROCESS,, :ref:`†<posix_undefined_behaviour>`
+    POSIX_THREADS_BASE, yes, :ref:`†<posix_undefined_behaviour>`
+    XSI_THREADS_EXT, yes, :ref:`†<posix_undefined_behaviour>`
+
+.. csv-table:: PSE52 Option Requirements
+   :header: Symbol, Support, Remarks
+   :widths: 50, 10, 50
+
+    _POSIX_CLOCK_SELECTION, 200809L, :kconfig:option:`CONFIG_POSIX_CLOCK`
+    _POSIX_FSYNC, -1,
+    _POSIX_MAPPED_FILES, -1,
+    _POSIX_MEMLOCK, -1,
+    _POSIX_MEMLOCK_RANGE, -1,
+    _POSIX_MESSAGE_PASSING, 200809L, :kconfig:option:`CONFIG_POSIX_MQUEUE`
+    _POSIX_MONOTONIC_CLOCK, 200809L, :kconfig:option:`CONFIG_POSIX_CLOCK`
+    _POSIX_REALTIME_SIGNALS, -1,
+    _POSIX_SEMAPHORES, 200809L, :kconfig:option:`CONFIG_PTHREAD_IPC`
+    _POSIX_SHARED_MEMORY_OBJECTS, -1,
+    _POSIX_SYNCHRONIZED_IO, -1,
+    _POSIX_THREAD_ATTR_STACKADDR, 200809L, :kconfig:option:`CONFIG_PTHREAD`
+    _POSIX_THREAD_ATTR_STACKSIZE, 200809L, :kconfig:option:`CONFIG_PTHREAD`
+    _POSIX_THREAD_CPUTIME, -1,
+    _POSIX_THREAD_PRIO_INHERIT, 200809L, :kconfig:option:`CONFIG_PTHREAD_MUTEX`
+    _POSIX_THREAD_PRIO_PROTECT, -1,
+    _POSIX_THREAD_PRIORITY_SCHEDULING, -1,
+    _POSIX_THREAD_SPORADIC_SERVER, -1,
+    _POSIX_TIMEOUTS, 200809L, :kconfig:option:`CONFIG_PTHREAD_IPC`
+    _POSIX_TIMERS, 200809L, :kconfig:option:`CONFIG_POSIX_CLOCK`
+    _POSIX_TRACE, -1,
+    _POSIX_TRACE_EVENT_FILTER, -1,
+    _POSIX_TRACE_LOG, -1,
+
+.. _posix_aep_pse53:
+
+Dedicated Realtime System Profile (PSE53)
+=========================================
+
+.. Conforming implementations shall define _POSIX_AEP_REALTIME_MINIMAL to the value 200312L
+
+.. csv-table:: PSE53 System Interfaces
+   :header: Symbol, Support, Remarks
+   :widths: 50, 10, 50
+
+    _POSIX_AEP_REALTIME_CONTROLLER, -1,
+
+.. csv-table:: PSE53 Option Groups
+   :header: Symbol, Support, Remarks
+   :widths: 50, 10, 50
+
+    POSIX_C_LANG_JUMP,,
+    POSIX_C_LANG_MATH, yes,
+    POSIX_C_LANG_SUPPORT, yes, :ref:`†<posix_undefined_behaviour>`
+    POSIX_DEVICE_IO,, :ref:`†<posix_undefined_behaviour>`
+    POSIX_FD_MGMT,,
+    POSIX_FILE_LOCKING,,
+    POSIX_FILE_SYSTEM,,
+    POSIX_MULTI_PROCESS,, :ref:`†<posix_undefined_behaviour>`
+    POSIX_NETWORKING, yes, :ref:`†<posix_undefined_behaviour>`
+    POSIX_PIPE,, :ref:`†<posix_undefined_behaviour>`
+    POSIX_SIGNALS,, :ref:`†<posix_undefined_behaviour>`
+    POSIX_SIGNAL_JUMP,, :ref:`†<posix_undefined_behaviour>`
+    POSIX_SINGLE_PROCESS,, :ref:`†<posix_undefined_behaviour>`
+    POSIX_THREADS_BASE, yes, :ref:`†<posix_undefined_behaviour>`
+    XSI_THREADS_EXT, yes, :ref:`†<posix_undefined_behaviour>`
+
+.. csv-table:: PSE53 Option Requirements
+   :header: Symbol, Support, Remarks
+   :widths: 50, 10, 50
+
+    _POSIX_ASYNCHRONOUS_IO, -1,
+    _POSIX_CLOCK_SELECTION, 200809L, :kconfig:option:`CONFIG_POSIX_CLOCK`
+    _POSIX_CPUTIME, -1,
+    _POSIX_FSYNC, -1,
+    _POSIX_MAPPED_FILES, -1,
+    _POSIX_MEMLOCK, -1,
+    _POSIX_MEMLOCK_RANGE, -1,
+    _POSIX_MEMORY_PROTECTION, -1,
+    _POSIX_MESSAGE_PASSING, 200809L, :kconfig:option:`CONFIG_POSIX_MQUEUE`
+    _POSIX_MONOTONIC_CLOCK, 200809L, :kconfig:option:`CONFIG_POSIX_CLOCK`
+    _POSIX_PRIORITIZED_IO, -1,
+    _POSIX_PRIORITY_SCHEDULING, -1,
+    _POSIX_RAW_SOCKETS, 200809L, :kconfig:option:`CONFIG_NET_SOCKETS`
+    _POSIX_REALTIME_SIGNALS, -1,
+    _POSIX_SEMAPHORES, 200809L, :kconfig:option:`CONFIG_PTHREAD_IPC`
+    _POSIX_SHARED_MEMORY_OBJECTS, -1,
+    _POSIX_SPAWN, -1,
+    _POSIX_SPORADIC_SERVER, -1,
+    _POSIX_SYNCHRONIZED_IO, -1,
+    _POSIX_THREAD_ATTR_STACKADDR, 200809L, :kconfig:option:`CONFIG_PTHREAD`
+    _POSIX_THREAD_ATTR_STACKSIZE, 200809L, :kconfig:option:`CONFIG_PTHREAD`
+    _POSIX_THREAD_CPUTIME, -1,
+    _POSIX_THREAD_PRIO_INHERIT, 200809L, :kconfig:option:`CONFIG_PTHREAD_MUTEX`
+    _POSIX_THREAD_PRIO_PROTECT, -1,
+    _POSIX_THREAD_PRIORITY_SCHEDULING, -1,
+    _POSIX_THREAD_PROCESS_SHARED, -1,
+    _POSIX_THREAD_SPORADIC_SERVER, -1,
+    _POSIX_TIMEOUTS, 200809L, :kconfig:option:`CONFIG_PTHREAD_IPC`
+    _POSIX_TIMERS, 200809L, :kconfig:option:`CONFIG_POSIX_CLOCK`
+    _POSIX_TRACE, -1,
+    _POSIX_TRACE_EVENT_FILTER, -1,
+    _POSIX_TRACE_LOG, -1,
+
+.. _IEEE 1003.1-2017: https://standards.ieee.org/ieee/1003.1/7101/
+.. _IEEE 1003.13-2003: https://standards.ieee.org/ieee/1003.13/3322/
diff --git a/doc/services/portability/posix/conformance/index.rst b/doc/services/portability/posix/conformance/index.rst
@@ -0,0 +1,145 @@
+.. _posix_conformance:
+
+POSIX Conformance
+#################
+
+As per `IEEE 1003.1-2017`, this section details Zephyr's POSIX conformance.
+
+.. _posix_undefined_behaviour:
+
+.. note::
+   As per POSIX 1003.13, single process mode is supported directly by both PSE51 and PSE52
+   profiles. While Zephyr includes support for many features found in PSE53, PSE53 itself requires
+   supporting multiple processes. Since supporting multiple processes is beyond the scope of
+   Zephyr's current design, some features requiring multi-process capabilities may exhibit
+   undefined behaviour, which we denote with the † (obelus) symbol.
+
+.. _posix_system_interfaces:
+
+POSIX System Interfaces
+=======================
+
+.. The following have values greater than -1 in Zephyr, conformant with the POSIX specification.
+
+.. csv-table:: POSIX System Interfaces
+   :header: Symbol, Support, Remarks
+   :widths: 50, 10, 50
+
+    _POSIX_CHOWN_RESTRICTED, 0,
+    _POSIX_NO_TRUNC, 0,
+    _POSIX_VDISABLE, 0,
+
+.. The following should be valued greater than zero in Zephyr, in order to be strictly conformant
+    with the POSIX specification.
+
+.. csv-table:: POSIX System Interfaces
+   :header: Symbol, Support, Remarks
+   :widths: 50, 10, 50
+
+    _POSIX_JOB_CONTROL, -1, :ref:`†<posix_undefined_behaviour>`
+    _POSIX_REGEXP, -1, :ref:`†<posix_undefined_behaviour>`
+    _POSIX_SAVED_IDS, -1, :ref:`†<posix_undefined_behaviour>`
+    _POSIX_SHELL, -1, :ref:`†<posix_undefined_behaviour>`
+
+.. TODO: POSIX_ASYNCHRONOUS_IO, and other interfaces below, are mandatory. That means that a
+   strictly conforming application need not be modified in order to compile against Zephyr.
+   However, we may add implementations that simply fail with ENOSYS as long as the functional
+   modification is clearly documented. The implementation is not required for PSE51 or PSE52
+   and beyond that POSIX async I/O functions are rarely used in practice.
+
+.. csv-table:: POSIX System Interfaces
+   :header: Symbol, Support, Remarks
+   :widths: 50, 10, 50
+
+    _POSIX_VERSION, 200809L,
+    _POSIX_ASYNCHRONOUS_IO, -1, :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`
+    _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>`, -1, :kconfig:option:`CONFIG_PTHREAD_IPC`
+    _POSIX_REALTIME_SIGNALS, -1, :ref:`†<posix_undefined_behaviour>`
+    :ref:`_POSIX_SEMAPHORES<posix_option_group_semaphores>`, 200809L, :kconfig:option:`CONFIG_PTHREAD_IPC`
+    :ref:`_POSIX_SPIN_LOCKS<posix_option_group_spin_locks>`, 200809L, :kconfig:option:`CONFIG_PTHREAD_SPINLOCK`
+    _POSIX_THREAD_SAFE_FUNCTIONS, 200809L,
+    :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`
+    _POSIX2_C_BIND, 200809L,
+
+.. csv-table:: POSIX System Interfaces (Optional)
+   :header: Symbol, Support, Remarks
+   :widths: 50, 10, 50
+
+    _POSIX_ADVISORY_INFO, -1,
+    _POSIX_CPUTIME, -1,
+    _POSIX_FSYNC, -1,
+    _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`
+    _POSIX_MONOTONIC_CLOCK, 200809L, :kconfig:option:`CONFIG_POSIX_CLOCK`
+    _POSIX_PRIORITIZED_IO, -1,
+    :ref:`_POSIX_PRIORITY_SCHEDULING<posix_option_priority_scheduling>`, -1, :kconfig:option:`CONFIG_PTHREAD`
+    _POSIX_RAW_SOCKETS, 200809L, :kconfig:option:`CONFIG_NET_SOCKETS`
+    _POSIX_SHARED_MEMORY_OBJECTS, -1,
+    _POSIX_SPAWN, -1,
+    _POSIX_SPORADIC_SERVER, -1,
+    _POSIX_SYNCHRONIZED_IO, -1,
+    :ref:`_POSIX_THREAD_ATTR_STACKADDR<posix_option_thread_attr_stackaddr>`, 200809L, :kconfig:option:`CONFIG_PTHREAD`
+    _POSIX_THREAD_CPUTIME, -1,
+    :ref:`_POSIX_THREAD_ATTR_STACKSIZE<posix_option_thread_attr_stacksize>`, 200809L, :kconfig:option:`CONFIG_PTHREAD`
+    _POSIX_THREAD_PRIO_INHERIT, 200809L, :kconfig:option:`CONFIG_PTHREAD_MUTEX`
+    _POSIX_THREAD_PRIO_PROTECT, -1,
+    :ref:`_POSIX_THREAD_PRIORITY_SCHEDULING<posix_option_thread_priority_scheduling>`, 200809L, :kconfig:option:`CONFIG_PTHREAD`
+    _POSIX_THREAD_PROCESS_SHARED, -1,
+    _POSIX_THREAD_SPORADIC_SERVER, -1,
+    _POSIX_TRACE, -1,
+    _POSIX_TRACE_EVENT_FILTER, -1,
+    _POSIX_TRACE_INHERIT, -1,
+    _POSIX_TRACE_LOG, -1,
+    _POSIX_TYPED_MEMORY_OBJECTS, -1,
+    _XOPEN_CRYPT, -1,
+    _XOPEN_REALTIME, -1,
+    _XOPEN_REALTIME_THREADS, -1,
+    :ref:`_XOPEN_STREAMS<posix_option_xopen_streams>`, -1, :kconfig:option:`CONFIG_NET_SOCKETS`
+    _XOPEN_UNIX, -1,
+
+POSIX Shell and Utilities
+=========================
+
+Zephyr does not support a POSIX shell or utilities at this time.
+
+.. csv-table:: POSIX Shell and Utilities
+   :header: Symbol, Support, Remarks
+   :widths: 50, 10, 50
+
+    _POSIX2_C_DEV, -1, :ref:`†<posix_undefined_behaviour>`
+    _POSIX2_CHAR_TERM, -1, :ref:`†<posix_undefined_behaviour>`
+    _POSIX2_FORT_DEV, -1, :ref:`†<posix_undefined_behaviour>`
+    _POSIX2_FORT_RUN, -1, :ref:`†<posix_undefined_behaviour>`
+    _POSIX2_LOCALEDEF, -1, :ref:`†<posix_undefined_behaviour>`
+    _POSIX2_PBS, -1, :ref:`†<posix_undefined_behaviour>`
+    _POSIX2_PBS_ACCOUNTING, -1, :ref:`†<posix_undefined_behaviour>`
+    _POSIX2_PBS_LOCATE, -1, :ref:`†<posix_undefined_behaviour>`
+    _POSIX2_PBS_MESSAGE, -1, :ref:`†<posix_undefined_behaviour>`
+    _POSIX2_PBS_TRACK, -1, :ref:`†<posix_undefined_behaviour>`
+    _POSIX2_SW_DEV, -1, :ref:`†<posix_undefined_behaviour>`
+    _POSIX2_UPE, -1, :ref:`†<posix_undefined_behaviour>`
+    _POSIX2_UNIX, -1, :ref:`†<posix_undefined_behaviour>`
+    _POSIX2_UUCP, -1, :ref:`†<posix_undefined_behaviour>`
+
+XSI Conformance
+###############
+
+XSI System Interfaces
+=====================
+
+.. csv-table:: XSI System Interfaces
+   :header: Symbol, Support, Remarks
+   :widths: 50, 10, 50
+
+    _POSIX_FSYNC, -1, :ref:`†<posix_undefined_behaviour>`
+    :ref:`_POSIX_THREAD_ATTR_STACKADDR<posix_option_thread_attr_stackaddr>`, 200809L, :kconfig:option:`CONFIG_PTHREAD`
+    :ref:`_POSIX_THREAD_ATTR_STACKSIZE<posix_option_thread_attr_stacksize>`, 200809L, :kconfig:option:`CONFIG_PTHREAD`
+    _POSIX_THREAD_PROCESS_SHARED, -1,