1.. _posix_overview:
2
3Overview
4########
5
6The Portable Operating System Interface (POSIX) is a family of standards specified by the
7`IEEE Computer Society`_ for maintaining compatibility between operating systems. Zephyr
8implements a subset of the standard POSIX API specified by `IEEE 1003.1-2017`_ (also known as
9POSIX-1.2017).
10
11..  figure:: posix.svg
12    :align: center
13    :alt: POSIX Support in Zephyr
14
15    POSIX support in Zephyr
16
17.. note::
18    This page does not document Zephyr's :ref:`POSIX architecture<Posix arch>`, which is used to
19    run Zephyr as a native application under the host operating system for prototyping,
20    test, and diagnostic purposes.
21
22With the POSIX support available in Zephyr, an existing POSIX conformant
23application can be ported to run on the Zephyr kernel, and therefore leverage
24Zephyr features and functionality. Additionally, a library designed to be
25POSIX conformant can be ported to Zephyr kernel based applications with no changes.
26
27The POSIX API is an increasingly popular OSAL (operating system abstraction layer) for IoT and
28embedded applications, as can be seen in Zephyr, AWS:FreeRTOS, TI-RTOS, and NuttX.
29
30Benefits of POSIX support in Zephyr include:
31
32- Offering a familiar API to non-embedded programmers, especially from Linux
33- Enabling reuse (portability) of existing libraries based on POSIX APIs
34- Providing an efficient API subset appropriate for small (MCU) embedded systems
35
36.. _posix_subprofiles:
37
38POSIX Subprofiles
39=================
40
41While Zephyr supports running multiple :ref:`threads <threads_v2>` (possibly in an
42:ref:`SMP <smp_arch>` configuration), as well as
43:ref:`Virtual Memory and MMUs <memory_management_api>`, Zephyr code and data normally share a
44common address space that is partitioned into separate :ref:`Memory Domains <memory_domain>`. The
45Zephyr kernel executable code and the application executable code are typically compiled into the
46same binary artifact. From that perspective, Zephyr apps can be seen as running in the context of
47a single process.
48
49While multi-purpose operating systems (OS) offer full POSIX conformance, Real-Time Operating
50Systems (RTOS) such as Zephyr typically serve a fixed-purpose, have limited hardware resources,
51and experience limited user interaction. In such systems, full POSIX conformance can be
52impractical and unnecessary.
53
54For that reason, POSIX defined the following :ref:`Application Environment Profiles (AEP)<posix_aep>`
55as part of `IEEE 1003.13-2003`_ (also known as POSIX.13-2003). Each AEP adds incrementally more
56features over the required :ref:`POSIX System Interfaces <posix_system_interfaces>`.
57
58..  figure:: aep.svg
59    :align: center
60    :scale: 150%
61    :alt: POSIX Application Environment Profiles (AEP)
62
63    POSIX Application Environment Profiles (AEP)
64
65* Minimal Realtime System Profile (:ref:`PSE51 <posix_aep_pse51>`)
66* Realtime Controller System Profile (:ref:`PSE52 <posix_aep_pse52>`)
67* Dedicated Realtime System Profile (:ref:`PSE53 <posix_aep_pse53>`)
68* Multi-Purpose Realtime System (PSE54)
69
70POSIX.13-2003 AEP were formalized in 2003 via "Units of Functionality" but the specification is now
71inactive (for reference only). Nevertheless, the intent is still captured as part of POSIX-1.2017
72via :ref:`Options<posix_options>` and :ref:`Option Groups<posix_option_groups>`.
73
74For more information, please see `IEEE 1003.1-2017, Section E, Subprofiling Considerations`_.
75
76.. _posix_apps:
77
78POSIX Applications in Zephyr
79============================
80
81A POSIX app in Zephyr is :ref:`built like any other app<application>` and therefore requires the
82usual :file:`prj.conf`, :file:`CMakeLists.txt`, and source code. For example, the app below
83leverages the ``nanosleep()`` and ``perror()`` POSIX functions.
84
85.. code-block:: cfg
86   :caption: `prj.conf` for a simple POSIX app in Zephyr
87
88    CONFIG_POSIX_API=y
89
90.. code-block:: c
91   :caption: A simple app that uses Zephyr's POSIX API
92
93    #include <stddef.h>
94    #include <stdio.h>
95    #include <time.h>
96
97    void megasleep(size_t megaseconds)
98    {
99        struct timespec ts = {
100            .tv_sec = megaseconds * 1000000,
101            .tv_nsec = 0,
102        };
103
104        printf("See you in a while!\n");
105        if (nanosleep(&ts, NULL) == -1) {
106            perror("nanosleep");
107        }
108    }
109
110    int main()
111    {
112        megasleep(42);
113        return 0;
114    }
115
116For more examples of POSIX applications, please see the
117:zephyr:code-sample-category:`POSIX sample applications<posix>`.
118
119.. _posix_config:
120
121Configuration
122=============
123
124Like most features in Zephyr, POSIX features are
125:ref:`highly configurable<zephyr_intro_configurability>` but disabled by default. Users must
126explicitly choose to enable POSIX options via :ref:`Kconfig<kconfig>` selection.
127
128Subprofiles
129+++++++++++
130
131Enable one of the Kconfig options below to quickly configure a pre-defined
132:ref:`POSIX subprofile <posix_subprofiles>`.
133
134* :kconfig:option:`CONFIG_POSIX_AEP_CHOICE_BASE` (:ref:`Base <posix_system_interfaces_required>`)
135* :kconfig:option:`CONFIG_POSIX_AEP_CHOICE_PSE51` (:ref:`PSE51 <posix_aep_pse51>`)
136* :kconfig:option:`CONFIG_POSIX_AEP_CHOICE_PSE52` (:ref:`PSE52 <posix_aep_pse52>`)
137* :kconfig:option:`CONFIG_POSIX_AEP_CHOICE_PSE53` (:ref:`PSE53 <posix_aep_pse53>`)
138
139Additional POSIX :ref:`Options and Option Groups <posix_option_groups>` may be enabled as needed
140via Kconfig (e.g. ``CONFIG_POSIX_C_LIB_EXT=y``). Further fine-tuning may be accomplished via
141:ref:`additional POSIX-related Kconfig options <posix_kconfig_options>`.
142
143Subprofiles, Options, and Option Groups should be considered the preferred way to configure POSIX
144in Zephyr going forward.
145
146Legacy
147++++++
148
149Historically, Zephyr used :kconfig:option:`CONFIG_POSIX_API` to configure a set of POSIX features
150that was overloaded and always increasing in size.
151
152* :kconfig:option:`CONFIG_POSIX_API`
153
154The option is now frozen, and can be considered equivalent to the following:
155
156* :kconfig:option:`CONFIG_POSIX_AEP_CHOICE_PSE51`
157* :kconfig:option:`CONFIG_POSIX_FD_MGMT`
158* :kconfig:option:`CONFIG_POSIX_MESSAGE_PASSING`
159* :kconfig:option:`CONFIG_POSIX_NETWORKING`
160
161However, :kconfig:option:`CONFIG_POSIX_API` should be considered legacy and should not be used for
162new Zephyr applications.
163
164.. _IEEE: https://www.ieee.org/
165.. _IEEE Computer Society: https://www.computer.org/
166.. _IEEE 1003.1-2017: https://standards.ieee.org/ieee/1003.1/7101/
167.. _IEEE 1003.13-2003: https://standards.ieee.org/ieee/1003.13/3322/
168.. _IEEE 1003.1-2017, Section E, Subprofiling Considerations:
169    https://pubs.opengroup.org/onlinepubs/9699919799/xrat/V4_subprofiles.html
170