1db9b009a7
This commit uses the new .. zephyr:code-sample-category directive to categorize code samples across the tree. Updates existing legacy references to manually defined targets to now use :zephyr:code-sample-category: role instead. Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
169 lines
6.4 KiB
ReStructuredText
169 lines
6.4 KiB
ReStructuredText
.. _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:
|
|
|
|
- Offering a familiar API to non-embedded programmers, especially from Linux
|
|
- Enabling reuse (portability) of existing libraries based on POSIX APIs
|
|
- Providing an efficient API subset appropriate for small (MCU) embedded systems
|
|
|
|
.. _posix_subprofiles:
|
|
|
|
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)
|
|
|
|
* Minimal Realtime System Profile (:ref:`PSE51 <posix_aep_pse51>`)
|
|
* Realtime Controller System Profile (:ref:`PSE52 <posix_aep_pse52>`)
|
|
* Dedicated Realtime System Profile (:ref:`PSE53 <posix_aep_pse53>`)
|
|
* Multi-Purpose Realtime System (PSE54)
|
|
|
|
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:
|
|
|
|
POSIX Applications in Zephyr
|
|
============================
|
|
|
|
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:
|
|
|
|
Configuration
|
|
=============
|
|
|
|
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>`.
|
|
|
|
* :kconfig:option:`CONFIG_POSIX_AEP_CHOICE_BASE` (:ref:`Base <posix_system_interfaces_required>`)
|
|
* :kconfig:option:`CONFIG_POSIX_AEP_CHOICE_PSE51` (:ref:`PSE51 <posix_aep_pse51>`)
|
|
* :kconfig:option:`CONFIG_POSIX_AEP_CHOICE_PSE52` (:ref:`PSE52 <posix_aep_pse52>`)
|
|
* :kconfig:option:`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.
|
|
|
|
* :kconfig:option:`CONFIG_POSIX_API`
|
|
|
|
The option is now frozen, and can be considered equivalent to the following:
|
|
|
|
* :kconfig:option:`CONFIG_POSIX_AEP_CHOICE_PSE51`
|
|
* :kconfig:option:`CONFIG_POSIX_FD_MGMT`
|
|
* :kconfig:option:`CONFIG_POSIX_MESSAGE_PASSING`
|
|
* :kconfig:option:`CONFIG_POSIX_NETWORKING`
|
|
|
|
However, :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
|