| .. _language_c: |
| |
| C Language Support |
| ################## |
| |
| C is a general-purpose low-level programming language that is widely used for |
| writing code for embedded systems. |
| |
| Zephyr is primarily written in C and natively supports applications written in |
| the C language. All Zephyr API functions and macros are implemented in C and |
| available as part of the C header files under the :file:`include` directory, so |
| writing Zephyr applications in C gives the developers access to the most |
| features. |
| |
| The ``main()`` function must have the return type of ``int`` as Zephyr |
| applications run in a "hosted" environment as defined by the C |
| standard. Applications must return zero (0) from main. All non-zero return |
| values are reserved. |
| |
| .. _c_standards: |
| |
| Language Standards |
| ****************** |
| |
| Zephyr does not target a specific version of the C standards; however, the |
| Zephyr codebase makes extensive use of the features newly introduced in the |
| 1999 release of the ISO C standard (ISO/IEC 9899:1999, hereinafter referred to |
| as C99) such as those listed below, effectively requiring the use of a compiler |
| toolchain that supports the C99 standard and above: |
| |
| * inline functions |
| * standard boolean types (``bool`` in ``<stdbool.h>``) |
| * fixed-width integer types (``[u]intN_t`` in ``<stdint.h>``) |
| * designated initializers |
| * variadic macros |
| * ``restrict`` qualification |
| |
| Some Zephyr components make use of the features newly introduced in the 2011 |
| release of the ISO C standard (ISO/IEC 9899:2011, hereinafter referred to as |
| C11) such as the type-generic expressions using the ``_Generic`` keyword. For |
| example, the :c:func:`cbprintf` component, used as the default formatted output |
| processor for Zephyr, makes use of the C11 type-generic expressions, and this |
| effectively requires most Zephyr applications to be compiled using a compiler |
| toolchain that supports the C11 standard and above. |
| |
| In summary, it is recommended to use a compiler toolchain that supports at |
| least the C11 standard for developing with Zephyr. It is, however, important to |
| note that some optional Zephyr components and external modules may make use of |
| the C language features that have been introduced in more recent versions of |
| the standards, in which case it will be necessary to use a more up-to-date |
| compiler toolchain that supports such standards. |
| |
| .. _c_library: |
| |
| Standard Library |
| **************** |
| |
| The `C Standard Library`_ is an integral part of any C program, and Zephyr |
| provides the support for a number of different C libraries for the applications |
| to choose from, depending on the compiler toolchain being used to build the |
| application. |
| |
| .. toctree:: |
| :maxdepth: 2 |
| |
| common_libc.rst |
| minimal_libc.rst |
| newlib.rst |
| picolibc.rst |
| |
| .. _`C Standard Library`: https://en.wikipedia.org/wiki/C_standard_library |
| |
| .. _c_library_formatted_output: |
| |
| Formatted Output |
| **************** |
| |
| C defines standard formatted output functions such as ``printf`` and |
| ``sprintf`` and these functions are implemented by the C standard |
| libraries. |
| |
| Each C standard library has its own set of requirements and configurations for |
| selecting the formatted output modes and capabilities. Refer to each C standard |
| library documentation for more details. |
| |
| .. _c_library_dynamic_mem: |
| |
| Dynamic Memory Management |
| ************************* |
| |
| C defines a standard dynamic memory management interface (for example, |
| :c:func:`malloc` and :c:func:`free`) and these functions are implemented by the |
| C standard libraries. |
| |
| While the details of the dynamic memory management implementation varies across |
| different C standard libraries, all supported libraries must conform to the |
| following conventions. Every supported C standard library shall: |
| |
| * manage its own memory heap either internally or by invoking the hook |
| functions (for example, :c:func:`sbrk`) implemented in :file:`libc-hooks.c`. |
| |
| * maintain the architecture- and memory region-specific alignment requirements |
| for the memory blocks allocated by the standard dynamic memory allocation |
| interface (for example, :c:func:`malloc`). |
| |
| * allocate memory blocks inside the ``z_malloc_partition`` memory partition |
| when userspace is enabled. See :ref:`memory_domain_predefined_partitions`. |
| |
| For more details regarding the C standard library-specific memory management |
| implementation, refer to each C standard library documentation. |
| |
| .. note:: |
| Native Zephyr applications should use the :ref:`memory management API |
| <memory_management_api>` supported by the Zephyr kernel such as |
| :c:func:`k_malloc` in order to take advantage of the advanced features |
| that they offer. |
| |
| C standard dynamic memory management interface functions such as |
| :c:func:`malloc` should be used only by the portable applications and |
| libraries that target multiple operating systems. |