Skip to content

doc: posix: structural reorganization of posix docs #64540

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Nov 23, 2023
Merged

doc: posix: structural reorganization of posix docs #64540

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion doc/_scripts/redirects.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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'),
Expand Down
2 changes: 2 additions & 0 deletions doc/introduction/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion doc/services/portability/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
191 changes: 191 additions & 0 deletions doc/services/portability/posix/aep/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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/
145 changes: 145 additions & 0 deletions doc/services/portability/posix/conformance/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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::
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If you make it a subheading instead of a note, and have the heading spelled "Undefined behavior" (it will arguably make it stand even more, and will make it more clear for folks why they landed there when clicking on one of the "unsupported" links), then you can :ref:`posix_undefined_behaviour` directly in your table and it will already have a meaningful and usable title

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, I'm not crazy about that standing out, to be honest.

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>`
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The obelus feels very lonely and tiny in this column (and also hard to click for people and not very accessible).
See my comment re: how to change the note to a heading, and then this can simply become

Suggested change
_POSIX_JOB_CONTROL, -1, :ref:`†<posix_undefined_behaviour>`
_POSIX_JOB_CONTROL, -1, :ref:`posix_undefined_behaviour`

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, again, I'm not super happy about lumping so many things into undefined behaviour. Ideally the gap would be significantly smaller but that also takes time and work. Additionally, I'd like to look at a better solution for generating these tables rather than maintaining them by hand.

_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,
Loading