doc: develop: Improve C language support documentation

This commit reworks the C language support documentation such that it
is more up to date and contains more information about the Newlib.

Signed-off-by: Stephanos Ioannidis <[email protected]>

doc/develop/languages/c/index.rst

@@ -0,0 +1,64 @@
+.. _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.
+
+.. _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
+
+   minimal_libc.rst
+   newlib.rst
+
+.. _`C Standard Library`: https://en.wikipedia.org/wiki/C_standard_library

doc/develop/languages/c/minimal_libc.rst

@@ -0,0 +1,41 @@
+.. _c_library_minimal:
+
+Minimal libc
+############
+
+The most basic C library, named "minimal libc", is part of the Zephyr codebase
+and provides the minimal subset of the standard C library required to meet the
+needs of Zephyr and its subsystems, primarily in the areas of string
+manipulation and display.
+
+It is very low footprint and is suitable for projects that do not rely on less
+frequently used portions of the ISO C standard library. It can also be used
+with a number of different toolchains.
+
+The minimal libc implementation can be found in :file:`lib/libc/minimal` in the
+main Zephyr tree.
+
+Error numbers
+*************
+
+Error numbers are used throughout Zephyr APIs to signal error conditions as
+return values from functions. They are typically returned as the negative value
+of the integer literals defined in this section, and are defined in the
+:file:`errno.h` header file.
+
+A subset of the error numbers defined in the `POSIX errno.h specification`_ and
+other de-facto standard sources have been added to the minimal libc.
+
+A conscious effort is made in Zephyr to keep the values of the minimal libc
+error numbers consistent with the different implementations of the C standard
+libraries supported by Zephyr. The minimal libc :file:`errno.h` is checked
+against that of the :ref:`Newlib <c_library_newlib>` to ensure that the error
+numbers are kept aligned.
+
+Below is a list of the error number definitions. For the actual numeric values
+please refer to `errno.h`_.
+
+.. doxygengroup:: system_errno
+
+.. _`POSIX errno.h specification`: https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/errno.h.html
+.. _`errno.h`: https://github.com/zephyrproject-rtos/zephyr/blob/main/lib/libc/minimal/include/errno.h

doc/develop/languages/c/newlib.rst

@@ -0,0 +1,59 @@
+.. _c_library_newlib:
+
+Newlib
+######
+
+`Newlib`_ is a complete C library implementation written for the embedded
+systems. It is a separate open source project and is not included in source
+code form with Zephyr. Instead, the :ref:`toolchain_zephyr_sdk` includes a
+precompiled library for each supported architecture (:file:`libc.a` and
+:file:`libm.a`).
+
+.. note::
+   Other 3rd-party toolchains, such as :ref:`toolchain_gnuarmemb`, also bundle
+   the Newlib as a precompiled library.
+
+Zephyr implements the "API hook" functions that are invoked by the C standard
+library functions in the Newlib. These hook functions are implemented in
+:file:`lib/libc/newlib/libc-hooks.c` and translate the library internal system
+calls to the equivalent Zephyr API calls.
+
+The Newlib included in the :ref:`toolchain_zephyr_sdk` comes in two versions:
+'full' and 'nano' variants.
+
+Full Newlib
+***********
+
+The Newlib full variant (:file:`libc.a` and :file:`libm.a`) is the most capable
+variant of the Newlib available in the Zephyr SDK, and supports almost all
+standard C library features. It is optimized for performance (prefers
+performance over code size) and its footprint is significantly larger than the
+the nano variant.
+
+This variant can be enabled by selecting the
+:kconfig:option:`CONFIG_NEWLIB_LIBC` and de-selecting the
+:kconfig:option:`CONFIG_NEWLIB_LIBC_NANO` in the application configuration
+file.
+
+Nano Newlib
+***********
+
+The Newlib nano variant (:file:`libc_nano.a` and :file:`libm_nano.a`) is the
+size-optimized version of the Newlib, and supports all features that the full
+variant supports except the ``long long`` and ``double`` type format
+specifiers.
+
+This variant can be enabled by selecting the
+:kconfig:option:`CONFIG_NEWLIB_LIBC` and
+:kconfig:option:`CONFIG_NEWLIB_LIBC_NANO` in the application configuration
+file.
+
+Note that the Newlib nano variant is not available for all architectures. The
+availability of the nano variant is specified by the
+:kconfig:option:`CONFIG_HAS_NEWLIB_LIBC_NANO`.
+
+When available (:kconfig:option:`CONFIG_HAS_NEWLIB_LIBC_NANO` is selected),
+the Newlib nano variant is enabled by default unless
+:kconfig:option:`CONFIG_NEWLIB_LIBC_NANO` is explicitly de-selected.
+
+.. _`Newlib`: https://sourceware.org/newlib/

doc/develop/languages/index.rst

@@ -6,5 +6,5 @@ Language Support
 .. toctree::
    :maxdepth: 2
 
-   c_language.rst
+   c/index.rst
    cpp_language.rst