1.. _c_library_newlib:
2
3Newlib
4######
5
6`Newlib`_ is a complete C library implementation written for the embedded
7systems. It is a separate open source project and is not included in source
8code form with Zephyr. Instead, the :ref:`toolchain_zephyr_sdk` includes a
9precompiled library for each supported architecture (:file:`libc.a` and
10:file:`libm.a`).
11
12.. note::
13   Other 3rd-party toolchains, such as :ref:`toolchain_gnuarmemb`, also bundle
14   the Newlib as a precompiled library.
15
16Zephyr implements the "API hook" functions that are invoked by the C standard
17library functions in the Newlib. These hook functions are implemented in
18:file:`lib/libc/newlib/libc-hooks.c` and translate the library internal system
19calls to the equivalent Zephyr API calls.
20
21Types of Newlib
22***************
23
24The Newlib included in the :ref:`toolchain_zephyr_sdk` comes in two versions:
25'full' and 'nano' variants.
26
27Full Newlib
28===========
29
30The Newlib full variant (:file:`libc.a` and :file:`libm.a`) is the most capable
31variant of the Newlib available in the Zephyr SDK, and supports almost all
32standard C library features. It is optimized for performance (prefers
33performance over code size) and its footprint is significantly larger than the
34nano variant.
35
36This variant can be enabled by selecting the
37:kconfig:option:`CONFIG_NEWLIB_LIBC` and de-selecting the
38:kconfig:option:`CONFIG_NEWLIB_LIBC_NANO` in the application configuration
39file.
40
41Nano Newlib
42===========
43
44The Newlib nano variant (:file:`libc_nano.a` and :file:`libm_nano.a`) is the
45size-optimized version of the Newlib, and supports all features that the full
46variant supports except the new format specifiers introduced in C99, such as
47the ``char``, ``long long`` type format specifiers (i.e. ``%hhX`` and
48``%llX``).
49
50This variant can be enabled by selecting the
51:kconfig:option:`CONFIG_NEWLIB_LIBC` and
52:kconfig:option:`CONFIG_NEWLIB_LIBC_NANO` in the application configuration
53file.
54
55Note that the Newlib nano variant is not available for all architectures. The
56availability of the nano variant is specified by the
57:kconfig:option:`CONFIG_HAS_NEWLIB_LIBC_NANO`.
58
59.. _`Newlib`: https://sourceware.org/newlib/
60
61Formatted Output
62****************
63
64Newlib supports all standard C formatted input and output functions, including
65``printf``, ``fprintf``, ``sprintf`` and ``sscanf``.
66
67The Newlib formatted input and output function implementation supports all
68format specifiers defined by the C standard with the following exceptions:
69
70* Floating point format specifiers (e.g. ``%f``) require
71  :kconfig:option:`CONFIG_NEWLIB_LIBC_FLOAT_PRINTF` and
72  :kconfig:option:`CONFIG_NEWLIB_LIBC_FLOAT_SCANF` to be enabled.
73* C99 format specifiers are not supported in the Newlib nano variant (i.e.
74  ``%hhX`` for ``char``, ``%llX`` for ``long long``, ``%jX`` for ``intmax_t``,
75  ``%zX`` for ``size_t``, ``%tX`` for ``ptrdiff_t``).
76
77Dynamic Memory Management
78*************************
79
80Newlib implements an internal heap allocator to manage the memory blocks used
81by the standard dynamic memory management interface functions (for example,
82:c:func:`malloc` and :c:func:`free`).
83
84The internal heap allocator implemented by the Newlib may vary across the
85different types of the Newlib used. For example, the heap allocator implemented
86in the Full Newlib (:file:`libc.a` and :file:`libm.a`) of the Zephyr SDK
87requests larger memory chunks to the operating system and has a significantly
88higher minimum memory requirement compared to that of the Nano Newlib
89(:file:`libc_nano.a` and :file:`libm_nano.a`).
90
91The only interface between the Newlib dynamic memory management functions and
92the Zephyr-side libc hooks is the :c:func:`sbrk` function, which is used by the
93Newlib to manage the size of the memory pool reserved for its internal heap
94allocator.
95
96The :c:func:`_sbrk` hook function, implemented in :file:`libc-hooks.c`, handles
97the memory pool size change requests from the Newlib and ensures that the
98Newlib internal heap allocator memory pool size does not exceed the amount of
99available memory space by returning an error when the system is out of memory.
100
101When userspace is enabled, the Newlib internal heap allocator memory pool is
102placed in a dedicated memory partition called ``z_malloc_partition``, which can
103be accessed from the user mode threads.
104
105The amount of memory space available for the Newlib heap depends on the system
106configurations:
107
108* When MMU is enabled (:kconfig:option:`CONFIG_MMU` is selected), the amount of
109  memory space reserved for the Newlib heap is set by the size of the free
110  memory space returned by the :c:func:`k_mem_free_get` function or the
111  :kconfig:option:`CONFIG_NEWLIB_LIBC_MAX_MAPPED_REGION_SIZE`, whichever is the
112  smallest.
113
114* When MPU is enabled and the MPU requires power-of-two partition size and
115  address alignment (:kconfig:option:`CONFIG_NEWLIB_LIBC_ALIGNED_HEAP_SIZE` is
116  set to a non-zero value), the amount of memory space reserved for the Newlib
117  heap is set by the :kconfig:option:`CONFIG_NEWLIB_LIBC_ALIGNED_HEAP_SIZE`.
118
119* Otherwise, the amount of memory space reserved for the Newlib heap is equal
120  to the amount of free (unallocated) memory in the SRAM region.
121
122The standard dynamic memory management interface functions implemented by the
123Newlib are thread safe and may be simultaneously called by multiple threads.
124