Skip to content

Commit 3b45235

Browse files
cfriedtcfriedt
committed
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]>
1 parent 5efa5b2 commit 3b45235

File tree

11 files changed

+851
-179
lines changed

11 files changed

+851
-179
lines changed

‎doc/_scripts/redirects.py

+1-1
Original file line numberDiff line numberDiff line change
@@ -71,7 +71,7 @@
7171
('guides/pm/power_domain', 'services/pm/power_domain'),
7272
('guides/pm/system', 'services/pm/system'),
7373
('guides/portability/index', 'services/portability/index'),
74-
('guides/portability/posix', 'services/portability/posix'),
74+
('guides/portability/posix', 'services/portability/posix/index'),
7575
('guides/porting/arch', 'hardware/porting/arch'),
7676
('guides/porting/board_porting', 'hardware/porting/board_porting'),
7777
('guides/porting/index', 'hardware/porting/index'),

‎doc/introduction/index.rst

+2
Original file line numberDiff line numberDiff line change
@@ -80,6 +80,8 @@ Zephyr offers a large and ever growing number of features including:
8080
* Red/black tree ready queue
8181
* Traditional multi-queue ready queue
8282

83+
.. _zephyr_intro_configurability:
84+
8385
**Highly configurable / Modular for flexibility**
8486
Allows an application to incorporate *only* the capabilities it needs as it
8587
needs them, and to specify their quantity and size.

‎doc/services/portability/index.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,6 @@ supported by the Zephyr RTOS.
1414
.. toctree::
1515
:maxdepth: 1
1616

17-
posix.rst
17+
posix/index.rst
1818
cmsis_rtos_v1.rst
1919
cmsis_rtos_v2.rst

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

+191
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,191 @@
1+
.. _posix_aep:
2+
3+
POSIX Application Environment Profiles (AEP)
4+
############################################
5+
6+
Although inactive, `IEEE 1003.13-2003`_ defined a number of AEP that inspired the modern
7+
subprofiling options of `IEEE 1003.1-2017`_. The single-purpose realtime system profiles
8+
are listed below, for reference, in terms that agree with the current POSIX-1 standard. PSE54
9+
is not considered at this time.
10+
11+
.. _posix_aep_pse51:
12+
13+
Minimal Realtime System Profile (PSE51)
14+
=======================================
15+
16+
.. Conforming implementations shall define _POSIX_AEP_REALTIME_MINIMAL to the value 200312L
17+
18+
.. csv-table:: PSE51 System Interfaces
19+
:header: Symbol, Support, Remarks
20+
:widths: 50, 10, 50
21+
22+
_POSIX_AEP_REALTIME_MINIMAL, -1,
23+
24+
.. csv-table:: PSE51 Option Groups
25+
:header: Symbol, Support, Remarks
26+
:widths: 50, 10, 50
27+
28+
POSIX_C_LANG_JUMP,,
29+
POSIX_C_LANG_SUPPORT, yes, :ref:`†<posix_undefined_behaviour>`
30+
POSIX_DEVICE_IO,, :ref:`†<posix_undefined_behaviour>`
31+
POSIX_FILE_LOCKING,,
32+
POSIX_SIGNALS,, :ref:`†<posix_undefined_behaviour>`
33+
POSIX_SINGLE_PROCESS,, :ref:`†<posix_undefined_behaviour>`
34+
POSIX_THREADS_BASE, yes, :ref:`†<posix_undefined_behaviour>`
35+
XSI_THREADS_EXT, yes, :ref:`†<posix_undefined_behaviour>`
36+
37+
.. csv-table:: PSE51 Option Requirements
38+
:header: Symbol, Support, Remarks
39+
:widths: 50, 10, 50
40+
41+
_POSIX_CLOCK_SELECTION, 200809L, :kconfig:option:`CONFIG_POSIX_CLOCK`
42+
_POSIX_FSYNC, -1,
43+
_POSIX_MEMLOCK, -1,
44+
_POSIX_MEMLOCK_RANGE, -1,
45+
_POSIX_MONOTONIC_CLOCK, 200809L, :kconfig:option:`CONFIG_POSIX_CLOCK`
46+
_POSIX_REALTIME_SIGNALS, -1,
47+
_POSIX_SEMAPHORES, 200809L, :kconfig:option:`CONFIG_PTHREAD_IPC`
48+
_POSIX_SHARED_MEMORY_OBJECTS, -1,
49+
_POSIX_SYNCHRONIZED_IO, -1,
50+
_POSIX_THREAD_ATTR_STACKADDR, 200809L, :kconfig:option:`CONFIG_PTHREAD`
51+
_POSIX_THREAD_ATTR_STACKSIZE, 200809L, :kconfig:option:`CONFIG_PTHREAD`
52+
_POSIX_THREAD_CPUTIME, -1,
53+
_POSIX_THREAD_PRIO_INHERIT, 200809L, :kconfig:option:`CONFIG_PTHREAD_MUTEX`
54+
_POSIX_THREAD_PRIO_PROTECT, -1,
55+
_POSIX_THREAD_PRIORITY_SCHEDULING, -1,
56+
_POSIX_THREAD_SPORADIC_SERVER, -1,
57+
_POSIX_TIMEOUTS, 200809L, :kconfig:option:`CONFIG_PTHREAD_IPC`
58+
_POSIX_TIMERS, 200809L, :kconfig:option:`CONFIG_POSIX_CLOCK`
59+
60+
.. note::
61+
For PSE51 support, 44 of 75 symbols are currently implemented.
62+
63+
.. _posix_aep_pse52:
64+
65+
Realtime Controller System Profile (PSE52)
66+
==========================================
67+
68+
.. Conforming implementations shall define _POSIX_AEP_REALTIME_CONTROLLER to the value 200312L
69+
70+
.. csv-table:: PSE52 System Interfaces
71+
:header: Symbol, Support, Remarks
72+
:widths: 50, 10, 50
73+
74+
_POSIX_AEP_REALTIME_CONTROLLER, -1,
75+
76+
.. csv-table:: PSE52 Option Groups
77+
:header: Symbol, Support, Remarks
78+
:widths: 50, 10, 50
79+
80+
POSIX_C_LANG_JUMP,,
81+
POSIX_C_LANG_MATH, yes,
82+
POSIX_C_LANG_SUPPORT, yes, :ref:`†<posix_undefined_behaviour>`
83+
POSIX_DEVICE_IO,, :ref:`†<posix_undefined_behaviour>`
84+
POSIX_FD_MGMT,,
85+
POSIX_FILE_LOCKING,,
86+
POSIX_FILE_SYSTEM,,
87+
POSIX_SIGNALS,, :ref:`†<posix_undefined_behaviour>`
88+
POSIX_SINGLE_PROCESS,, :ref:`†<posix_undefined_behaviour>`
89+
POSIX_THREADS_BASE, yes, :ref:`†<posix_undefined_behaviour>`
90+
XSI_THREADS_EXT, yes, :ref:`†<posix_undefined_behaviour>`
91+
92+
.. csv-table:: PSE52 Option Requirements
93+
:header: Symbol, Support, Remarks
94+
:widths: 50, 10, 50
95+
96+
_POSIX_CLOCK_SELECTION, 200809L, :kconfig:option:`CONFIG_POSIX_CLOCK`
97+
_POSIX_FSYNC, -1,
98+
_POSIX_MAPPED_FILES, -1,
99+
_POSIX_MEMLOCK, -1,
100+
_POSIX_MEMLOCK_RANGE, -1,
101+
_POSIX_MESSAGE_PASSING, 200809L, :kconfig:option:`CONFIG_POSIX_MQUEUE`
102+
_POSIX_MONOTONIC_CLOCK, 200809L, :kconfig:option:`CONFIG_POSIX_CLOCK`
103+
_POSIX_REALTIME_SIGNALS, -1,
104+
_POSIX_SEMAPHORES, 200809L, :kconfig:option:`CONFIG_PTHREAD_IPC`
105+
_POSIX_SHARED_MEMORY_OBJECTS, -1,
106+
_POSIX_SYNCHRONIZED_IO, -1,
107+
_POSIX_THREAD_ATTR_STACKADDR, 200809L, :kconfig:option:`CONFIG_PTHREAD`
108+
_POSIX_THREAD_ATTR_STACKSIZE, 200809L, :kconfig:option:`CONFIG_PTHREAD`
109+
_POSIX_THREAD_CPUTIME, -1,
110+
_POSIX_THREAD_PRIO_INHERIT, 200809L, :kconfig:option:`CONFIG_PTHREAD_MUTEX`
111+
_POSIX_THREAD_PRIO_PROTECT, -1,
112+
_POSIX_THREAD_PRIORITY_SCHEDULING, -1,
113+
_POSIX_THREAD_SPORADIC_SERVER, -1,
114+
_POSIX_TIMEOUTS, 200809L, :kconfig:option:`CONFIG_PTHREAD_IPC`
115+
_POSIX_TIMERS, 200809L, :kconfig:option:`CONFIG_POSIX_CLOCK`
116+
_POSIX_TRACE, -1,
117+
_POSIX_TRACE_EVENT_FILTER, -1,
118+
_POSIX_TRACE_LOG, -1,
119+
120+
.. _posix_aep_pse53:
121+
122+
Dedicated Realtime System Profile (PSE53)
123+
=========================================
124+
125+
.. Conforming implementations shall define _POSIX_AEP_REALTIME_MINIMAL to the value 200312L
126+
127+
.. csv-table:: PSE53 System Interfaces
128+
:header: Symbol, Support, Remarks
129+
:widths: 50, 10, 50
130+
131+
_POSIX_AEP_REALTIME_CONTROLLER, -1,
132+
133+
.. csv-table:: PSE53 Option Groups
134+
:header: Symbol, Support, Remarks
135+
:widths: 50, 10, 50
136+
137+
POSIX_C_LANG_JUMP,,
138+
POSIX_C_LANG_MATH, yes,
139+
POSIX_C_LANG_SUPPORT, yes, :ref:`†<posix_undefined_behaviour>`
140+
POSIX_DEVICE_IO,, :ref:`†<posix_undefined_behaviour>`
141+
POSIX_FD_MGMT,,
142+
POSIX_FILE_LOCKING,,
143+
POSIX_FILE_SYSTEM,,
144+
POSIX_MULTI_PROCESS,, :ref:`†<posix_undefined_behaviour>`
145+
POSIX_NETWORKING, yes, :ref:`†<posix_undefined_behaviour>`
146+
POSIX_PIPE,, :ref:`†<posix_undefined_behaviour>`
147+
POSIX_SIGNALS,, :ref:`†<posix_undefined_behaviour>`
148+
POSIX_SIGNAL_JUMP,, :ref:`†<posix_undefined_behaviour>`
149+
POSIX_SINGLE_PROCESS,, :ref:`†<posix_undefined_behaviour>`
150+
POSIX_THREADS_BASE, yes, :ref:`†<posix_undefined_behaviour>`
151+
XSI_THREADS_EXT, yes, :ref:`†<posix_undefined_behaviour>`
152+
153+
.. csv-table:: PSE53 Option Requirements
154+
:header: Symbol, Support, Remarks
155+
:widths: 50, 10, 50
156+
157+
_POSIX_ASYNCHRONOUS_IO, -1,
158+
_POSIX_CLOCK_SELECTION, 200809L, :kconfig:option:`CONFIG_POSIX_CLOCK`
159+
_POSIX_CPUTIME, -1,
160+
_POSIX_FSYNC, -1,
161+
_POSIX_MAPPED_FILES, -1,
162+
_POSIX_MEMLOCK, -1,
163+
_POSIX_MEMLOCK_RANGE, -1,
164+
_POSIX_MEMORY_PROTECTION, -1,
165+
_POSIX_MESSAGE_PASSING, 200809L, :kconfig:option:`CONFIG_POSIX_MQUEUE`
166+
_POSIX_MONOTONIC_CLOCK, 200809L, :kconfig:option:`CONFIG_POSIX_CLOCK`
167+
_POSIX_PRIORITIZED_IO, -1,
168+
_POSIX_PRIORITY_SCHEDULING, -1,
169+
_POSIX_RAW_SOCKETS, 200809L, :kconfig:option:`CONFIG_NET_SOCKETS`
170+
_POSIX_REALTIME_SIGNALS, -1,
171+
_POSIX_SEMAPHORES, 200809L, :kconfig:option:`CONFIG_PTHREAD_IPC`
172+
_POSIX_SHARED_MEMORY_OBJECTS, -1,
173+
_POSIX_SPAWN, -1,
174+
_POSIX_SPORADIC_SERVER, -1,
175+
_POSIX_SYNCHRONIZED_IO, -1,
176+
_POSIX_THREAD_ATTR_STACKADDR, 200809L, :kconfig:option:`CONFIG_PTHREAD`
177+
_POSIX_THREAD_ATTR_STACKSIZE, 200809L, :kconfig:option:`CONFIG_PTHREAD`
178+
_POSIX_THREAD_CPUTIME, -1,
179+
_POSIX_THREAD_PRIO_INHERIT, 200809L, :kconfig:option:`CONFIG_PTHREAD_MUTEX`
180+
_POSIX_THREAD_PRIO_PROTECT, -1,
181+
_POSIX_THREAD_PRIORITY_SCHEDULING, -1,
182+
_POSIX_THREAD_PROCESS_SHARED, -1,
183+
_POSIX_THREAD_SPORADIC_SERVER, -1,
184+
_POSIX_TIMEOUTS, 200809L, :kconfig:option:`CONFIG_PTHREAD_IPC`
185+
_POSIX_TIMERS, 200809L, :kconfig:option:`CONFIG_POSIX_CLOCK`
186+
_POSIX_TRACE, -1,
187+
_POSIX_TRACE_EVENT_FILTER, -1,
188+
_POSIX_TRACE_LOG, -1,
189+
190+
.. _IEEE 1003.1-2017: https://standards.ieee.org/ieee/1003.1/7101/
191+
.. _IEEE 1003.13-2003: https://standards.ieee.org/ieee/1003.13/3322/

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

+145
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
.. _posix_conformance:
2+
3+
POSIX Conformance
4+
#################
5+
6+
As per `IEEE 1003.1-2017`, this section details Zephyr's POSIX conformance.
7+
8+
.. _posix_undefined_behaviour:
9+
10+
.. note::
11+
As per POSIX 1003.13, single process mode is supported directly by both PSE51 and PSE52
12+
profiles. While Zephyr includes support for many features found in PSE53, PSE53 itself requires
13+
supporting multiple processes. Since supporting multiple processes is beyond the scope of
14+
Zephyr's current design, some features requiring multi-process capabilities may exhibit
15+
undefined behaviour, which we denote with the † (obelus) symbol.
16+
17+
.. _posix_system_interfaces:
18+
19+
POSIX System Interfaces
20+
=======================
21+
22+
.. The following have values greater than -1 in Zephyr, conformant with the POSIX specification.
23+
24+
.. csv-table:: POSIX System Interfaces
25+
:header: Symbol, Support, Remarks
26+
:widths: 50, 10, 50
27+
28+
_POSIX_CHOWN_RESTRICTED, 0,
29+
_POSIX_NO_TRUNC, 0,
30+
_POSIX_VDISABLE, 0,
31+
32+
.. The following should be valued greater than zero in Zephyr, in order to be strictly conformant
33+
with the POSIX specification.
34+
35+
.. csv-table:: POSIX System Interfaces
36+
:header: Symbol, Support, Remarks
37+
:widths: 50, 10, 50
38+
39+
_POSIX_JOB_CONTROL, -1, :ref:`†<posix_undefined_behaviour>`
40+
_POSIX_REGEXP, -1, :ref:`†<posix_undefined_behaviour>`
41+
_POSIX_SAVED_IDS, -1, :ref:`†<posix_undefined_behaviour>`
42+
_POSIX_SHELL, -1, :ref:`†<posix_undefined_behaviour>`
43+
44+
.. TODO: POSIX_ASYNCHRONOUS_IO, and other interfaces below, are mandatory. That means that a
45+
strictly conforming application need not be modified in order to compile against Zephyr.
46+
However, we may add implementations that simply fail with ENOSYS as long as the functional
47+
modification is clearly documented. The implementation is not required for PSE51 or PSE52
48+
and beyond that POSIX async I/O functions are rarely used in practice.
49+
50+
.. csv-table:: POSIX System Interfaces
51+
:header: Symbol, Support, Remarks
52+
:widths: 50, 10, 50
53+
54+
_POSIX_VERSION, 200809L,
55+
_POSIX_ASYNCHRONOUS_IO, -1, :ref:`†<posix_undefined_behaviour>`
56+
:ref:`_POSIX_BARRIERS<posix_option_group_barriers>`, 200809L, :kconfig:option:`CONFIG_PTHREAD_BARRIER`
57+
:ref:`_POSIX_CLOCK_SELECTION<posix_option_group_clock_selection>`, 200809L, :kconfig:option:`CONFIG_POSIX_CLOCK`
58+
_POSIX_MAPPED_FILES, -1, :ref:`†<posix_undefined_behaviour>`
59+
_POSIX_MEMORY_PROTECTION, -1, :ref:`†<posix_undefined_behaviour>`
60+
:ref:`_POSIX_READER_WRITER_LOCKS<posix_option_reader_writer_locks>`, -1, :kconfig:option:`CONFIG_PTHREAD_IPC`
61+
_POSIX_REALTIME_SIGNALS, -1, :ref:`†<posix_undefined_behaviour>`
62+
:ref:`_POSIX_SEMAPHORES<posix_option_group_semaphores>`, 200809L, :kconfig:option:`CONFIG_PTHREAD_IPC`
63+
:ref:`_POSIX_SPIN_LOCKS<posix_option_group_spin_locks>`, 200809L, :kconfig:option:`CONFIG_PTHREAD_SPINLOCK`
64+
_POSIX_THREAD_SAFE_FUNCTIONS, 200809L,
65+
:ref:`_POSIX_THREADS<posix_option_group_threads_base>`, -1, :kconfig:option:`CONFIG_PTHREAD_IPC`
66+
:ref:`_POSIX_TIMEOUTS<posix_option_timeouts>`, 200809L, :kconfig:option:`CONFIG_PTHREAD_IPC`
67+
:ref:`_POSIX_TIMERS<posix_option_group_timers>`, 200809L, :kconfig:option:`CONFIG_POSIX_CLOCK`
68+
_POSIX2_C_BIND, 200809L,
69+
70+
.. csv-table:: POSIX System Interfaces (Optional)
71+
:header: Symbol, Support, Remarks
72+
:widths: 50, 10, 50
73+
74+
_POSIX_ADVISORY_INFO, -1,
75+
_POSIX_CPUTIME, -1,
76+
_POSIX_FSYNC, -1,
77+
_POSIX_IPV6, 200809L, :kconfig:option:`CONFIG_NET_IPV6`
78+
_POSIX_MEMLOCK, -1,
79+
_POSIX_MEMLOCK_RANGE, -1,
80+
:ref:`_POSIX_MESSAGE_PASSING<posix_option_message_passing>`, 200809L, :kconfig:option:`CONFIG_POSIX_MQUEUE`
81+
_POSIX_MONOTONIC_CLOCK, 200809L, :kconfig:option:`CONFIG_POSIX_CLOCK`
82+
_POSIX_PRIORITIZED_IO, -1,
83+
:ref:`_POSIX_PRIORITY_SCHEDULING<posix_option_priority_scheduling>`, -1, :kconfig:option:`CONFIG_PTHREAD`
84+
_POSIX_RAW_SOCKETS, 200809L, :kconfig:option:`CONFIG_NET_SOCKETS`
85+
_POSIX_SHARED_MEMORY_OBJECTS, -1,
86+
_POSIX_SPAWN, -1,
87+
_POSIX_SPORADIC_SERVER, -1,
88+
_POSIX_SYNCHRONIZED_IO, -1,
89+
:ref:`_POSIX_THREAD_ATTR_STACKADDR<posix_option_thread_attr_stackaddr>`, 200809L, :kconfig:option:`CONFIG_PTHREAD`
90+
_POSIX_THREAD_CPUTIME, -1,
91+
:ref:`_POSIX_THREAD_ATTR_STACKSIZE<posix_option_thread_attr_stacksize>`, 200809L, :kconfig:option:`CONFIG_PTHREAD`
92+
_POSIX_THREAD_PRIO_INHERIT, 200809L, :kconfig:option:`CONFIG_PTHREAD_MUTEX`
93+
_POSIX_THREAD_PRIO_PROTECT, -1,
94+
:ref:`_POSIX_THREAD_PRIORITY_SCHEDULING<posix_option_thread_priority_scheduling>`, 200809L, :kconfig:option:`CONFIG_PTHREAD`
95+
_POSIX_THREAD_PROCESS_SHARED, -1,
96+
_POSIX_THREAD_SPORADIC_SERVER, -1,
97+
_POSIX_TRACE, -1,
98+
_POSIX_TRACE_EVENT_FILTER, -1,
99+
_POSIX_TRACE_INHERIT, -1,
100+
_POSIX_TRACE_LOG, -1,
101+
_POSIX_TYPED_MEMORY_OBJECTS, -1,
102+
_XOPEN_CRYPT, -1,
103+
_XOPEN_REALTIME, -1,
104+
_XOPEN_REALTIME_THREADS, -1,
105+
:ref:`_XOPEN_STREAMS<posix_option_xopen_streams>`, -1, :kconfig:option:`CONFIG_NET_SOCKETS`
106+
_XOPEN_UNIX, -1,
107+
108+
POSIX Shell and Utilities
109+
=========================
110+
111+
Zephyr does not support a POSIX shell or utilities at this time.
112+
113+
.. csv-table:: POSIX Shell and Utilities
114+
:header: Symbol, Support, Remarks
115+
:widths: 50, 10, 50
116+
117+
_POSIX2_C_DEV, -1, :ref:`†<posix_undefined_behaviour>`
118+
_POSIX2_CHAR_TERM, -1, :ref:`†<posix_undefined_behaviour>`
119+
_POSIX2_FORT_DEV, -1, :ref:`†<posix_undefined_behaviour>`
120+
_POSIX2_FORT_RUN, -1, :ref:`†<posix_undefined_behaviour>`
121+
_POSIX2_LOCALEDEF, -1, :ref:`†<posix_undefined_behaviour>`
122+
_POSIX2_PBS, -1, :ref:`†<posix_undefined_behaviour>`
123+
_POSIX2_PBS_ACCOUNTING, -1, :ref:`†<posix_undefined_behaviour>`
124+
_POSIX2_PBS_LOCATE, -1, :ref:`†<posix_undefined_behaviour>`
125+
_POSIX2_PBS_MESSAGE, -1, :ref:`†<posix_undefined_behaviour>`
126+
_POSIX2_PBS_TRACK, -1, :ref:`†<posix_undefined_behaviour>`
127+
_POSIX2_SW_DEV, -1, :ref:`†<posix_undefined_behaviour>`
128+
_POSIX2_UPE, -1, :ref:`†<posix_undefined_behaviour>`
129+
_POSIX2_UNIX, -1, :ref:`†<posix_undefined_behaviour>`
130+
_POSIX2_UUCP, -1, :ref:`†<posix_undefined_behaviour>`
131+
132+
XSI Conformance
133+
###############
134+
135+
XSI System Interfaces
136+
=====================
137+
138+
.. csv-table:: XSI System Interfaces
139+
:header: Symbol, Support, Remarks
140+
:widths: 50, 10, 50
141+
142+
_POSIX_FSYNC, -1, :ref:`†<posix_undefined_behaviour>`
143+
:ref:`_POSIX_THREAD_ATTR_STACKADDR<posix_option_thread_attr_stackaddr>`, 200809L, :kconfig:option:`CONFIG_PTHREAD`
144+
:ref:`_POSIX_THREAD_ATTR_STACKSIZE<posix_option_thread_attr_stacksize>`, 200809L, :kconfig:option:`CONFIG_PTHREAD`
145+
_POSIX_THREAD_PROCESS_SHARED, -1,

0 commit comments

Comments
 (0)