mirror of
https://github.com/zephyrproject-rtos/zephyr
synced 2025-08-11 07:16:04 +00:00
33103828dc
This commit adds a C99 stdio value formatter capability where generated text is emitted through a callback. This allows generation of arbitrarily long output without a buffer, functionality that is core to printk, logging, and other system and application needs. The formatter supports most C99 specifications, excluding: * %Lf long double conversion * wide character output Kconfig options allow disabling features like floating-point conversion if they are not necessary. By default most conversions are enabled. The original z_vprintk() implementation is adapted to meet the interface requirements of cbvprintf, and made available as an opt-in feature for space-constrained applications that do not need full formatting support. Signed-off-by: Peter Bigot <peter.bigot@nordicsemi.no>
56 lines
2.2 KiB
ReStructuredText
56 lines
2.2 KiB
ReStructuredText
.. _formatted_output:
|
|
|
|
Formatted Output
|
|
################
|
|
|
|
Applications as well as Zephyr itself requires infrastructure to format
|
|
values for user consumption. The standard C99 library ``*printf()``
|
|
functionality fulfills this need for streaming output devices or memory
|
|
buffers, but in an embedded system devices may not accept streamed data
|
|
and memory may not be available to store the formatted output.
|
|
|
|
Internal Zephyr API traditionally provided this both for
|
|
:c:func:`printk` and for Zephyr's internal minimal libc, but with
|
|
separate internal interfaces. Logging, tracing, shell, and other
|
|
applications made use of either these APIs or standard libc routines
|
|
based on build options.
|
|
|
|
The :c:func:`cbprintf` public APIs convert C99 format strings and
|
|
arguments, providing output produced one character at a time through a
|
|
callback mechanism, replacing the original internal functions and
|
|
providing support for almost all C99 format specifications. Existing
|
|
use of ``s*printf()`` C libraries in Zephyr can be converted to
|
|
:c:func:`snprintfcb()` to avoid pulling in libc implementations.
|
|
|
|
Several Kconfig options control the set of features that are enabled,
|
|
allowing some control over features and memory usage:
|
|
|
|
* :option:`CONFIG_CBPRINTF_FULL_INTEGRAL`
|
|
or :option:`CONFIG_CBPRINTF_REDUCED_INTEGRAL`
|
|
* :option:`CONFIG_CBPRINTF_FP_SUPPORT`
|
|
* :option:`CONFIG_CBPRINTF_FP_A_SUPPORT`
|
|
* :option:`CONFIG_CBPRINTF_FP_ALWAYS_A`
|
|
* :option:`CONFIG_CBPRINTF_N_SPECIFIER`
|
|
|
|
:option:`CONFIG_CBPRINTF_LIBC_SUBSTS` can be used to provide functions
|
|
that behave like standard libc functions but use the selected cbprintf
|
|
formatter rather than pulling in another formatter from libc.
|
|
|
|
In addition :option:`CONFIG_CBPRINTF_NANO` can be used to revert back to
|
|
the very space-optimized but limited formatter used for :c:func:`printk`
|
|
before this capability was added.
|
|
|
|
.. warning::
|
|
|
|
If :option:`CONFIG_MINIMAL_LIBC` is selected in combination with
|
|
:option:`CONFIG_CBPRINTF_NANO` formatting with C standard library
|
|
functions like ``printf`` or ``snprintf`` is limited. Among other
|
|
things the ``%n`` specifier, most format flags, precision control, and
|
|
floating point are not supported.
|
|
|
|
API Reference
|
|
*************
|
|
|
|
.. doxygengroup:: cbprintf_apis
|
|
:project: Zephyr
|