From f40c2b95503282f5e6af58aa5b2accc98a68bc74 Mon Sep 17 00:00:00 2001 From: Krzysztof Chruscinski Date: Fri, 26 Aug 2022 15:31:18 +0200 Subject: [PATCH] doc: formatted_output: cbprintf: Align to new features 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 --- doc/services/formatted_output.rst | 44 ++++++++++++++++++++++--------- 1 file changed, 32 insertions(+), 12 deletions(-) diff --git a/doc/services/formatted_output.rst b/doc/services/formatted_output.rst index 909c9d9420d..5f6616795a9 100644 --- a/doc/services/formatted_output.rst +++ b/doc/services/formatted_output.rst @@ -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 *************