1.. _formatted_output:
2
3Formatted Output
4################
5
6Applications as well as Zephyr itself requires infrastructure to format
7values for user consumption.  The standard C99 library ``*printf()``
8functionality fulfills this need for streaming output devices or memory
9buffers, but in an embedded system devices may not accept streamed data
10and memory may not be available to store the formatted output.
11
12Internal Zephyr API traditionally provided this both for
13:c:func:`printk` and for Zephyr's internal minimal libc, but with
14separate internal interfaces.  Logging, tracing, shell, and other
15applications made use of either these APIs or standard libc routines
16based on build options.
17
18The :c:func:`cbprintf` public APIs convert C99 format strings and
19arguments, providing output produced one character at a time through a
20callback mechanism, replacing the original internal functions and
21providing support for almost all C99 format specifications.  Existing
22use of ``s*printf()`` C libraries in Zephyr can be converted to
23:c:func:`snprintfcb()` to avoid pulling in libc implementations.
24
25Several Kconfig options control the set of features that are enabled,
26allowing some control over features and memory usage:
27
28* :kconfig:option:`CONFIG_CBPRINTF_FULL_INTEGRAL`
29  or :kconfig:option:`CONFIG_CBPRINTF_REDUCED_INTEGRAL`
30* :kconfig:option:`CONFIG_CBPRINTF_FP_SUPPORT`
31* :kconfig:option:`CONFIG_CBPRINTF_FP_A_SUPPORT`
32* :kconfig:option:`CONFIG_CBPRINTF_FP_ALWAYS_A`
33* :kconfig:option:`CONFIG_CBPRINTF_N_SPECIFIER`
34
35:kconfig:option:`CONFIG_CBPRINTF_LIBC_SUBSTS` can be used to provide functions
36that behave like standard libc functions but use the selected cbprintf
37formatter rather than pulling in another formatter from libc.
38
39In addition :kconfig:option:`CONFIG_CBPRINTF_NANO` can be used to revert back to
40the very space-optimized but limited formatter used for :c:func:`printk`
41before this capability was added.
42
43.. _cbprintf_packaging:
44
45Cbprintf Packaging
46******************
47
48Typically, strings are formatted synchronously when a function from ``printf``
49family is called. However, there are cases when it is beneficial that formatting
50is deferred. In that case, a state (format string and arguments) must be captured.
51Such state forms a self-contained package which contains format string and
52arguments. Additionally, package may contain copies of strings which are
53part of a format string (format string or any ``%s`` argument). Package primary
54content resembles va_list stack frame thus standard formatting functions are
55used to process a package. Since package contains data which is processed as
56va_list frame, strict alignment must be maintained. Due to required padding,
57size of the package depends on alignment. When package is copied, it should be
58copied to a memory block with the same alignment as origin.
59
60Package can have following variants:
61
62* **Self-contained** - non read-only strings appended to the package. String can be
63  formatted from such package as long as there is access to read-only string
64  locations. Package may contain information where read-only strings are located
65  within the package. That information can be used to convert packet to fully
66  self-contained package.
67* **Fully self-contained** - all strings are appended to the package. String can be
68  formatted from such package without any external data.
69* **Transient**- only arguments are stored. Package contain information
70  where pointers to non read-only strings are located within the package. Optionally,
71  it may contain read-only string location information. String can be formatted
72  from such package as long as non read-only strings are still valid and read-only
73  strings are accessible. Alternatively, package can be converted to **self-contained**
74  package or **fully self-contained** if information about read-only string
75  locations is present in the package.
76
77Package can be created using two methods:
78
79* runtime - using :c:func:`cbprintf_package` or :c:func:`cbvprintf_package`. This
80  method scans format string and based on detected format specifiers builds the
81  package.
82* static - types of arguments are detected at compile time by the preprocessor
83  and package is created as simple assignments to a provided memory. This method
84  is significantly faster than runtime (more than 15 times) but has following
85  limitations: requires ``_Generic`` keyword (C11 feature) to be supported by
86  the compiler and cannot distinguish between ``%p`` and ``%s`` if char pointer
87  is used. It treats all (unsigned) char pointers as ``%s`` thus it will attempt
88  to append string to a package. It can be handled correctly during conversion
89  from **transient** package to **self-contained** package using
90  :c:macro:`CBPRINTF_PACKAGE_CONVERT_PTR_CHECK` flag. However, it requires access
91  to the format string and it is not always possible thus it is recommended to
92  cast char pointers used for ``%p`` to ``void *``. There is a logging warning
93  generated by :c:func:`cbprintf_package_convert` called with
94  :c:macro:`CBPRINTF_PACKAGE_CONVERT_PTR_CHECK` flag when char pointer is used with
95  ``%p``.
96
97
98Several Kconfig options control behavior of the packaging:
99
100* :kconfig:option:`CONFIG_CBPRINTF_PACKAGE_LONGDOUBLE`
101* :kconfig:option:`CONFIG_CBPRINTF_STATIC_PACKAGE_CHECK_ALIGNMENT`
102
103Cbprintf package conversion
104===========================
105
106It is possible to convert package to a variant which contains more information, e.g
107**transient** package can be converted to **self-contained**. Conversion to
108**fully self-contained** package is possible if :c:macro:`CBPRINTF_PACKAGE_ADD_RO_STR_POS`
109flag was used when package was created.
110
111:c:func:`cbprintf_package_copy` is used to calculate space needed for the new
112package and to copy and convert a package.
113
114Cbprintf package format
115=======================
116
117Format of the package contains paddings which are platform specific. Package consists
118of header which contains size of package (excluding appended strings) and number of
119appended strings. It is followed by the arguments which contains alignment paddings
120and resembles *va_list* stack frame. It is followed by data associated with character
121pointer arguments used by the string which are not appended to the string (but may
122be appended later by :c:func:`cbprinf_package_convert`). Finally, package, optionally,
123contains appended strings. Each string contains 1 byte header which contains index
124of the location where address argument is stored. During packaging address is set
125to null and before string formatting it is updated to point to the current string
126location within the package. Updating address argument must happen just before string
127formatting since address changes whenever package is copied.
128
129+------------------+-------------------------------------------------------------------------+
130| Header           | 1 byte: Argument list size including header and *fmt* (in 32 bit words) |
131|                  +-------------------------------------------------------------------------+
132| sizeof(void \*)  | 1 byte: Number of strings appended to the package                       |
133|                  +-------------------------------------------------------------------------+
134|                  | 1 byte: Number of read-only string argument locations                   |
135|                  +-------------------------------------------------------------------------+
136|                  | 1 byte: Number of transient string argument locations                   |
137|                  +-------------------------------------------------------------------------+
138|                  | platform specific padding to sizeof(void \*)                            |
139+------------------+-------------------------------------------------------------------------+
140| Arguments        | Pointer to *fmt* (or null if *fmt* is appended to the package)          |
141|                  +-------------------------------------------------------------------------+
142|                  | (optional padding for platform specific alignment)                      |
143|                  +-------------------------------------------------------------------------+
144|                  | argument 0                                                              |
145|                  +-------------------------------------------------------------------------+
146|                  | (optional padding for platform specific alignment)                      |
147|                  +-------------------------------------------------------------------------+
148|                  | argument 1                                                              |
149|                  +-------------------------------------------------------------------------+
150|                  | ...                                                                     |
151+------------------+-------------------------------------------------------------------------+
152| String location  | Indexes of words within the package where read-only strings are located |
153| information      +-------------------------------------------------------------------------+
154| (optional)       | Pairs of argument index and argument location index where transient     |
155|                  | strings are located                                                     |
156+------------------+-------------------------------------------------------------------------+
157| Appended         | 1 byte: Index within the package to the location of associated argument |
158| strings          +-------------------------------------------------------------------------+
159| (optional)       | Null terminated string                                                  |
160|                  +-------------------------------------------------------------------------+
161|                  | ...                                                                     |
162+------------------+-------------------------------------------------------------------------+
163
164.. warning::
165
166  If :kconfig:option:`CONFIG_MINIMAL_LIBC` is selected in combination with
167  :kconfig:option:`CONFIG_CBPRINTF_NANO` formatting with C standard library
168  functions like ``printf`` or ``snprintf`` is limited.  Among other
169  things the ``%n`` specifier, most format flags, precision control, and
170  floating point are not supported.
171
172.. _cbprintf_packaging_limitations:
173
174Limitations and recommendations
175===============================
176
177* C11 ``_Generic`` support is required by the compiler to use static (fast) packaging.
178* It is recommended to cast any character pointer used with ``%p`` format specifier to
179  other pointer type (e.g. ``void *``). If format string is not accessible then only
180  static packaging is possible and it will append all detected strings. Character pointer
181  used for ``%p`` will be considered as string pointer. Copying from unexpected location
182  can have serious consequences (e.g., memory fault or security violation).
183
184API Reference
185*************
186
187.. doxygengroup:: cbprintf_apis
188