michaelh/zephyr
1
0
Fork 0
Code Releases Activity

doc: formatted_output: cbprintf: Align to new features

Browse source 
Align documentation with current set of supported features. Mainly,
it mentions a static packaging limitation and how to handle that.

Added section which summarizes limitations and recommendations.

Signed-off-by: Krzysztof Chruscinski <krzysztof.chruscinski@nordicsemi.no>
This commit is contained in:
Krzysztof Chruscinski 2022-08-26 15:31:18 +02:00 • committed by Fabio Baltieri
commit f40c2b9550
1 changed files with 32 additions and 12 deletions
Download patch file Download diff file Expand all files Collapse all files

44
doc/services/formatted_output.rst
View file

@ -83,12 +83,17 @@ Package can be created using two methods:
and package is created as simple assignments to a provided memory. This method
is significantly faster than runtime (more than 15 times) but has following
limitations: requires ``_Generic`` keyword (C11 feature) to be supported by
the compiler and can only create a package that is known to have no string
arguments (``%s``). :c:macro:`CBPRINTF_MUST_RUNTIME_PACKAGE` can be used to
determine at compile time if static packaging can be applied. Macro determines
need for runtime packaging based on presence of char pointers in the argument
list so there are cases when it will be false positive, e.g. ``%p`` with char
pointer.
the compiler and cannot distinguish between ``%p`` and ``%s`` if char pointer
is used. It treats all (unsigned) char pointers as ``%s`` thus it will attempt
to append string to a package. It can be handled correctly during conversion
from **transient** package to **self-contained** package using
:c:macro:`CBPRINTF_PACKAGE_CONVERT_PTR_CHECK` flag. However, it requires access
to the format string and it is not always possible thus it is recommended to
cast char pointers used for ``%p`` to ``void *``. There is a logging warning
generated by :c:func:`cbprintf_package_convert` called with
:c:macro:`CBPRINTF_PACKAGE_CONVERT_PTR_CHECK` flag when char pointer is used with
``%p``.
Several Kconfig options control behavior of the packaging:
@ -112,11 +117,13 @@ Cbprintf package format
Format of the package contains paddings which are platform specific. Package consists
of header which contains size of package (excluding appended strings) and number of
appended strings. It is followed by the arguments which contains alignment paddings
and resembles *va_list* stack frame. Finally, package optionally contains appended
strings. Each string contains 1 byte header which contains index of the location
where address argument is stored. During packaging address is set to null and
before string formatting it is updated to point to the current string location
within the package. Updating address argument must happen just before string
and resembles *va_list* stack frame. It is followed by data associated with character
pointer arguments used by the string which are not appended to the string (but may
be appended later by :c:func:`cbprinf_package_convert`). Finally, package, optionally,
contains appended strings. Each string contains 1 byte header which contains index
of the location where address argument is stored. During packaging address is set
to null and before string formatting it is updated to point to the current string
location within the package. Updating address argument must happen just before string
formatting since address changes whenever package is copied.
+------------------+-------------------------------------------------------------------------+
@ -144,7 +151,8 @@ formatting since address changes whenever package is copied.
+------------------+-------------------------------------------------------------------------+
| String location | Indexes of words within the package where read-only strings are located |
| information +-------------------------------------------------------------------------+
| (optional) | Indexes of words within the package where transient strings are located |
| (optional) | Pairs of argument index and argument location index where transient |
| | strings are located |
+------------------+-------------------------------------------------------------------------+
| Appended | 1 byte: Index within the package to the location of associated argument |
| strings +-------------------------------------------------------------------------+
@ -161,6 +169,18 @@ formatting since address changes whenever package is copied.
things the ``%n`` specifier, most format flags, precision control, and
floating point are not supported.
.. _cbprintf_packaging_limitations:
Limitations and recommendations
===============================
* C11 ``_Generic`` support is required by the compiler to use static (fast) packaging.
* It is recommended to cast any character pointer used with ``%p`` format specifier to
other pointer type (e.g. ``void *``). If format string is not accessible then only
static packaging is possible and it will append all detected strings. Character pointer
used for ``%p`` will be considered as string pointer. Copying from unexpected location
can have serious consequences (e.g., memory fault or security violation).
API Reference
*************