doc/services/portability/posix/overview/index.rst
.. _posix_overview:
Overview ########
The Portable Operating System Interface (POSIX) is a family of standards specified by the
IEEE Computer Society_ for maintaining compatibility between operating systems. Zephyr
implements a subset of the standard POSIX API specified by IEEE 1003.1-2017_ (also known as
POSIX-1.2017).
.. figure:: posix.svg :align: center :alt: POSIX Support in Zephyr
POSIX support in Zephyr
.. note::
This page does not document Zephyr's :ref:POSIX architecture<Posix arch>, which is used to
run Zephyr as a native application under the host operating system for prototyping,
test, and diagnostic purposes.
With the POSIX support available in Zephyr, an existing POSIX conformant application can be ported to run on the Zephyr kernel, and therefore leverage Zephyr features and functionality. Additionally, a library designed to be POSIX conformant can be ported to Zephyr kernel based applications with no changes.
The POSIX API is an increasingly popular OSAL (operating system abstraction layer) for IoT and embedded applications, as can be seen in Zephyr, AWS:FreeRTOS, TI-RTOS, and NuttX.
Benefits of POSIX support in Zephyr include:
.. _posix_subprofiles:
While Zephyr supports running multiple :ref:threads <threads_v2> (possibly in an
:ref:SMP <smp_arch> configuration), as well as
:ref:Virtual Memory and MMUs <memory_management_api>, Zephyr code and data normally share a
common address space that is partitioned into separate :ref:Memory Domains <memory_domain>. The
Zephyr kernel executable code and the application executable code are typically compiled into the
same binary artifact. From that perspective, Zephyr apps can be seen as running in the context of
a single process.
While multi-purpose operating systems (OS) offer full POSIX conformance, Real-Time Operating Systems (RTOS) such as Zephyr typically serve a fixed-purpose, have limited hardware resources, and experience limited user interaction. In such systems, full POSIX conformance can be impractical and unnecessary.
For that reason, POSIX defined the following :ref:Application Environment Profiles (AEP)<posix_aep>
as part of IEEE 1003.13-2003_ (also known as POSIX.13-2003). Each AEP adds incrementally more
features over the required :ref:POSIX System Interfaces <posix_system_interfaces>.
.. figure:: aep.svg :align: center :scale: 150% :alt: POSIX Application Environment Profiles (AEP)
POSIX Application Environment Profiles (AEP)
PSE51 <posix_aep_pse51>)PSE52 <posix_aep_pse52>)PSE53 <posix_aep_pse53>)POSIX.13-2003 AEP were formalized in 2003 via "Units of Functionality" but the specification is now
inactive (for reference only). Nevertheless, the intent is still captured as part of POSIX-1.2017
via :ref:Options<posix_options> and :ref:Option Groups<posix_option_groups>.
For more information, please see IEEE 1003.1-2017, Section E, Subprofiling Considerations_.
.. _posix_apps:
A POSIX app in Zephyr is :ref:built like any other app<application> and therefore requires the
usual :file:prj.conf, :file:CMakeLists.txt, and source code. For example, the app below
leverages the nanosleep() and perror() POSIX functions.
.. code-block:: cfg
:caption: prj.conf for a simple POSIX app in Zephyr
CONFIG_POSIX_API=y
.. code-block:: c :caption: A simple app that uses Zephyr's POSIX API
#include <stddef.h>
#include <stdio.h>
#include <time.h>
void megasleep(size_t megaseconds)
{
struct timespec ts = {
.tv_sec = megaseconds * 1000000,
.tv_nsec = 0,
};
printf("See you in a while!\n");
if (nanosleep(&ts, NULL) == -1) {
perror("nanosleep");
}
}
int main()
{
megasleep(42);
return 0;
}
For more examples of POSIX applications, please see the
:zephyr:code-sample-category:POSIX sample applications<posix>.
.. _posix_config:
Like most features in Zephyr, POSIX features are
:ref:highly configurable<zephyr_intro_configurability> but disabled by default. Users must
explicitly choose to enable POSIX options via :ref:Kconfig<kconfig> selection.
Subprofiles +++++++++++
Enable one of the Kconfig options below to quickly configure a pre-defined
:ref:POSIX subprofile <posix_subprofiles>.
CONFIG_POSIX_AEP_CHOICE_BASE (:ref:Base <posix_system_interfaces_required>)CONFIG_POSIX_AEP_CHOICE_PSE51 (:ref:PSE51 <posix_aep_pse51>)CONFIG_POSIX_AEP_CHOICE_PSE52 (:ref:PSE52 <posix_aep_pse52>)CONFIG_POSIX_AEP_CHOICE_PSE53 (:ref:PSE53 <posix_aep_pse53>)Additional POSIX :ref:Options and Option Groups <posix_option_groups> may be enabled as needed
via Kconfig (e.g. CONFIG_POSIX_C_LIB_EXT=y). Further fine-tuning may be accomplished via
:ref:additional POSIX-related Kconfig options <posix_kconfig_options>.
Subprofiles, Options, and Option Groups should be considered the preferred way to configure POSIX in Zephyr going forward.
Legacy ++++++
Historically, Zephyr used :kconfig:option:CONFIG_POSIX_API to configure a set of POSIX features
that was overloaded and always increasing in size.
CONFIG_POSIX_APIThe option is now frozen, and can be considered equivalent to the following:
CONFIG_POSIX_AEP_CHOICE_PSE51CONFIG_POSIX_FD_MGMTCONFIG_POSIX_MESSAGE_PASSINGCONFIG_POSIX_NETWORKINGHowever, :kconfig:option:CONFIG_POSIX_API should be considered legacy and should not be used for
new Zephyr applications.
.. _IEEE: https://www.ieee.org/ .. _IEEE Computer Society: https://www.computer.org/ .. _IEEE 1003.1-2017: https://standards.ieee.org/ieee/1003.1/7101/ .. _IEEE 1003.13-2003: https://standards.ieee.org/ieee/1003.13/3322/ .. _IEEE 1003.1-2017, Section E, Subprofiling Considerations: https://pubs.opengroup.org/onlinepubs/9699919799/xrat/V4_subprofiles.html