lib: cbprintf: add support for deferred formatting

In applications like logging the call site where arguments to
formatting are available may not be suitable for performing the
formatting, e.g. when the output operation can sleep.  Add API that
supports capturing data that may be transient into a buffer that can
be saved, and API that then produces the output later using the
packaged arguments.

[ Documentation and commit log from Peter Bigot. ]

Signed-off-by: Nicolas Pitre <[email protected]>
Signed-off-by: Peter Bigot <[email protected]>

Author: Nicolas Pitre

CODEOWNERS

@@ -462,6 +462,7 @@
 /lib/gui/                                 @vanwinkeljan
 /lib/open-amp/                            @arnopo
 /lib/os/                                  @dcpleung @nashif @andyross
+/lib/os/cbprintf_packaged.c               @npitre
 /lib/posix/                               @pfalcon
 /lib/cmsis_rtos_v2/                       @nashif
 /lib/cmsis_rtos_v1/                       @nashif

include/sys/cbprintf.h

@@ -9,6 +9,7 @@
 
 #include <stdarg.h>
 #include <stddef.h>
+#include <stdint.h>
 #include <toolchain.h>
 
 #ifdef CONFIG_CBPRINTF_LIBC_SUBSTS
@@ -44,6 +45,102 @@ extern "C" {
  */
 typedef int (*cbprintf_cb)(/* int c, void *ctx */);
 
+/** @brief Capture state required to output formatted data later.
+ *
+ * Like cbprintf() but instead of processing the arguments and emitting the
+ * formatted results immediately all arguments are captured so this can be
+ * done in a different context, e.g. when the output function can block.
+ *
+ * In addition to the values extracted from arguments this will ensure that
+ * copies are made of the necessary portions of any string parameters that are
+ * not confirmed to be stored in read-only memory (hence assumed to be safe to
+ * refer to directly later).
+ *
+ * @param packaged pointer to where the packaged data can be stored.  Pass a
+ * null pointer to store nothing but still calculate the total space required.
+ * The data stored here is relocatable, that is it can be moved to another
+ * contiguous block of memory. The pointer must be aligned to a multiple of
+ * the largest element in the argument list.
+ *
+ * @param len this must be set to the number of bytes available at @p packaged.
+ * Ignored if @p packaged is NULL.
+ *
+ * @param format a standard ISO C format string with characters and conversion
+ * specifications.
+ *
+ * @param ... arguments corresponding to the conversion specifications found
+ * within @p format.
+ *
+ * @retval nonegative the number of bytes successfully stored at @p packaged.
+ * This will not exceed @p len.
+ * @retval -EINVAL if @p format is not acceptable
+ * @retval -ENOSPC if @p packaged was not null and the space required to store
+ * exceed @p len.
+ */
+__printf_like(3, 4)
+int cbprintf_package(void *packaged,
+		     size_t len,
+		     const char *format,
+		     ...);
+
+/** @brief Capture state required to output formatted data later.
+ *
+ * Like cbprintf() but instead of processing the arguments and emitting the
+ * formatted results immediately all arguments are captured so this can be
+ * done in a different context, e.g. when the output function can block.
+ *
+ * In addition to the values extracted from arguments this will ensure that
+ * copies are made of the necessary portions of any string parameters that are
+ * not confirmed to be stored in read-only memory (hence assumed to be safe to
+ * refer to directly later).
+ *
+ * @param packaged pointer to where the packaged data can be stored.  Pass a
+ * null pointer to store nothing but still calculate the total space required.
+ * The data stored here is relocatable, that is it can be moved to another
+ * contiguous block of memory. The pointer must be aligned to a multiple of
+ * the largest element in the argument list.
+ *
+ * @param len this must be set to the number of bytes available at @p packaged.
+ * Ignored if @p packaged is NULL.
+ *
+ * @param format a standard ISO C format string with characters and conversion
+ * specifications.
+ *
+ * @param ap captured stack arguments corresponding to the conversion
+ * specifications found within @p format.
+ *
+ * @retval nonegative the number of bytes successfully stored at @p packaged.
+ * This will not exceed @p len.
+ * @retval -EINVAL if @p format is not acceptable
+ * @retval -ENOSPC if @p packaged was not null and the space required to store
+ * exceed @p len.
+ */
+int cbvprintf_package(void *packaged,
+		      size_t len,
+		      const char *format,
+		      va_list ap);
+
+/** @brief Generate the output for a previously captured format
+ * operation.
+ *
+ * @param out the function used to emit each generated character.
+ *
+ * @param ctx context provided when invoking out
+ *
+ * @param packaged the data required to generate the formatted output, as
+ * captured by cbprintf_package() or cbvprintf_package(). The alignment
+ * requirement on this data is the same as when it was initially created.
+ *
+ * @note Memory indicated by @p packaged will be modified in a non-destructive
+ * way, meaning that it could still be reused with this function again.
+ *
+ * @return the number of characters printed, or a negative error value
+ * returned from invoking @p out.
+ */
+int cbpprintf(cbprintf_cb out,
+	      void *ctx,
+	      void *packaged);
+
 /** @brief *printf-like output through a callback.
  *
  * This is essentially printf() except the output is generated

lib/os/CMakeLists.txt

@@ -4,6 +4,7 @@ zephyr_sources_ifdef(CONFIG_BASE64 base64.c)
 
 zephyr_sources(
   cbprintf.c
+  cbprintf_packaged.c
   crc32c_sw.c
   crc32_sw.c
   crc16_sw.c