1.. _c_library_picolibc:
2
3Picolibc
4########
5
6`Picolibc`_ is a complete C library implementation written for the
7embedded systems, targeting `C17 (ISO/IEC 9899:2018)`_ and `POSIX 2018
8(IEEE Std 1003.1-2017)`_ standards. Picolibc is an external open
9source project which is provided for Zephyr as a module, and included
10as part of the :ref:`toolchain_zephyr_sdk` in precompiled form for
11each supported architecture (:file:`libc.a`).
12
13.. note::
14   Picolibc is also available for other 3rd-party toolchains, such as
15   :ref:`toolchain_gnuarmemb`.
16
17Zephyr implements the “API hook” functions that are invoked by the C
18standard library functions in the Picolibc. These hook functions are
19implemented in :file:`lib/libc/picolibc/libc-hooks.c` and translate
20the library internal system calls to the equivalent Zephyr API calls.
21
22.. _`Picolibc`: https://github.com/picolibc/picolibc
23.. _`C17 (ISO/IEC 9899:2018)`: https://www.iso.org/standard/74528.html
24.. _`POSIX 2018 (IEEE Std 1003.1-2017)`: https://pubs.opengroup.org/onlinepubs/9699919799/functions/printf.html
25
26.. _c_library_picolibc_module:
27
28Picolibc Module
29===============
30
31When built as a Zephyr module, there are several configuration knobs
32available to adjust the feature set in the library, balancing what the
33library supports versus the code size of the resulting
34functions. Because the standard C++ library must be compiled for the
35target C library, the Picolibc module cannot be used with applications
36which use the standard C++ library. Building the Picolibc module will
37increase the time it takes to compile the application.
38
39The Picolibc module can be enabled by selecting
40:kconfig:option:`CONFIG_PICOLIBC_USE_MODULE` in the application
41configuration file.
42
43When updating the Picolibc module to a newer version, the
44:ref:`toolchain-bundled Picolibc in the Zephyr SDK
45<c_library_picolibc_toolchain>` must also be updated to the same version.
46
47.. _c_library_picolibc_toolchain:
48
49Toolchain Picolibc
50==================
51
52Starting with version 0.16, the Zephyr SDK includes precompiled
53versions of Picolibc for every target architecture, along with
54precompiled versions of libstdc++.
55
56The toolchain version of Picolibc can be enabled by de-selecting
57:kconfig:option:`CONFIG_PICOLIBC_USE_MODULE` in the application
58configuration file.
59
60For every release of Zephyr, the toolchain-bundled Picolibc and the
61:ref:`Picolibc module <c_library_picolibc_module>` are guaranteed to be in
62sync when using the
63:ref:`recommended version of Zephyr SDK <toolchain_zephyr_sdk_compatibility>`.
64
65Building Without Toolchain bundled Picolibc
66-------------------------------------------
67
68For toolchain where there is no bundled Picolibc, it is still
69possible to use Picolibc by building it from source. Note that
70any restrictions mentioned in :ref:`c_library_picolibc_module`
71still apply.
72
73To build without toolchain bundled Picolibc, the toolchain must
74enable :kconfig:option:`CONFIG_PICOLIBC_SUPPORTED`. For example,
75this needs to be added to the toolchain Kconfig file:
76
77.. code-block:: kconfig
78
79   config TOOLCHAIN_<name>_PICOLIBC_SUPPORTED
80      def_bool y
81      select PICOLIBC_SUPPORTED
82
83By enabling :kconfig:option:`CONFIG_PICOLIBC_SUPPORTED`, the build
84system would automatically build Picolibc from source with its module
85when there is no toolchain bundled Picolibc.
86
87Formatted Output
88****************
89
90Picolibc supports all standard C formatted input and output functions,
91including :c:func:`printf`, :c:func:`fprintf`, :c:func:`sprintf` and
92:c:func:`sscanf`.
93
94Picolibc formatted input and output function implementation supports
95all format specifiers defined by the C17 and POSIX 2018 standards with
96the following exceptions:
97
98* Floating point format specifiers (e.g. ``%f``) require
99  :kconfig:option:`CONFIG_PICOLIBC_IO_FLOAT`.
100
101* Long long format specifiers (e.g. ``%lld``) require
102  :kconfig:option:`CONFIG_PICOLIBC_IO_LONG_LONG`. This option is
103  automatically enabled with :kconfig:option:`CONFIG_PICOLIBC_IO_FLOAT`.
104
105Printk, cbprintf and friends
106****************************
107
108When using Picolibc, Zephyr formatted output functions are
109implemented in terms of stdio calls. This includes:
110
111 * printk, snprintk and vsnprintk
112 * cbprintf and cbvprintf
113 * fprintfcb, vfprintfcb, printfcb, vprintfcb, snprintfcb and vsnprintfcb
114
115When using tagged args
116(:kconfig:option:`CONFIG_CBPRINTF_PACKAGE_SUPPORT_TAGGED_ARGUMENTS` and
117:c:macro:`CBPRINTF_PACKAGE_ARGS_ARE_TAGGED`), calls to cbpprintf will
118not use Picolibc, so formatting of output using those code will differ
119from Picolibc results as the cbprintf functions are not completely
120C/POSIX compliant.
121
122Math Functions
123**************
124
125Picolibc provides full C17/`IEEE STD 754-2019`_ support for float,
126double and long double math operations, except for long double
127versions of the Bessel functions.
128
129.. _`IEEE STD 754-2019`: https://ieeexplore.ieee.org/document/8766229
130
131Thread Local Storage
132********************
133
134Picolibc uses Thread Local Storage (TLS) (where supported) for data
135which is supposed to remain local to each thread, like
136:c:macro:`errno`. This means that TLS support is enabled when using
137Picolibc. As all TLS variables are allocated out of the thread stack
138area, this can affect stack size requirements by a few bytes.
139
140C Library Local Variables
141*************************
142
143Picolibc uses a few internal variables for things like heap
144management. These are collected in a dedicated memory partition called
145:c:var:`z_libc_partition`. Applications using
146:kconfig:option:`CONFIG_USERSPACE` and memory domains must ensure that
147this partition is included in any domain active during Picolibc calls.
148
149Dynamic Memory Management
150*************************
151
152Picolibc uses the malloc api family implementation provided by the
153:ref:`common C library <c_library_common>`, which itself is built upon the
154:ref:`kernel memory heap API <heap_v2>`.
155