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 <krzysztof.chruscinski@nordicsemi.no>

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
+  the compiler and cannot distinguish between ``%p`` and ``%s`` if char pointer
-  arguments (``%s``). :c:macro:`CBPRINTF_MUST_RUNTIME_PACKAGE` can be used to
+  is used. It treats all (unsigned) char pointers as ``%s`` thus it will attempt
-  determine at compile time if static packaging can be applied. Macro determines
+  to append string to a package. It can be handled correctly during conversion
-  need for runtime packaging based on presence of char pointers in the argument
+  from **transient** package to **self-contained** package using
-  list so there are cases when it will be false positive, e.g. ``%p`` with char
+  :c:macro:`CBPRINTF_PACKAGE_CONVERT_PTR_CHECK` flag. However, it requires access
-  pointer.
+  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
+and resembles *va_list* stack frame. It is followed by data associated with character
-strings. Each string contains 1 byte header which contains index of the location
+pointer arguments used by the string which are not appended to the string (but may
-where address argument is stored. During packaging address is set to null and
+be appended later by :c:func:`cbprinf_package_convert`). Finally, package, optionally,
-before string formatting it is updated to point to the current string location
+contains appended strings. Each string contains 1 byte header which contains index
-within the package. Updating address argument must happen just before string
+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
 *************