lib: os: cbprintf: Add macros for static packaging

Added macro for determining if string can be statically packaged.
Added macro for static packaging of a string.

Added cbprintf_internal.h with internal macros to avoid spoiling
API file.

Additionally, added option for packaging to store first char pointer
(fmt) as a standard pointer witouth 1 byte header which distinguish
between storing by pointer and storing by value. This can significantly
reduce storage, e.g. string without any arguments uses one word vs
two word (byte header + alignment).

Signed-off-by: Krzysztof Chruscinski <[email protected]>

Author: nordic-krch

include/sys/cbprintf.h

@@ -11,6 +11,7 @@
 #include <stddef.h>
 #include <stdint.h>
 #include <toolchain.h>
+#include <sys/cbprintf_internal.h>
 
 #ifdef __cplusplus
 extern "C" {
@@ -22,6 +23,14 @@ extern "C" {
  * @{
  */
 
+/**@defgroup CBPRINTF_PACKAGE_FLAGS packaging flags.
+ * @{ */
+
+/** @brief Indicate that format string is packaged as pointer. */
+#define CBPRINTF_PACKAGE_FMT_AS_PTR BIT(0)
+
+/**@} */
+
 /** @brief Signature for a cbprintf callback function.
  *
  * This function expects two parameters:
@@ -41,6 +50,62 @@ extern "C" {
  */
 typedef int (*cbprintf_cb)(/* int c, void *ctx */);
 
+/** @brief Determine if string must be packaged in run time.
+ *
+ * Static packaging can be applied if size and of the package can be determined
+ * at compile time. In general, package size can be determined at compile time
+ * if there are no string arguments which might be copied into package body if
+ * they are considered transient.
+ *
+ * @param skip number of read only string arguments in the parameter list. It
+ * shall be non-zero if there are known read only string arguments present
+ * in the string (e.g. function name).
+ * @param ... String with arguments.
+ *
+ * @retval 1 if string must be packaged in run time.
+ * @retval 0 string can be statically packaged.
+ */
+#define CBPRINTF_MUST_RUNTIME_PACKAGE(skip, .../* fmt, ... */) \
+	Z_CBPRINTF_MUST_RUNTIME_PACKAGE(skip, __VA_ARGS__)
+
+/** @brief Statically package string.
+ *
+ * Build string package based on formatted string. Macro produces same package
+ * as if @ref cbprintf_package was used with CBPRINTF_PACKAGE_FMT_AS_PTR set.
+ *
+ * @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.
+
+ * @param len on input this must be set to the number of bytes available at @p
+ * packaged. If @p packaged is NULL the input value is ignored.  On output
+ * the referenced value will be updated to the number of bytes required to
+ * completely store the packed information.  The @p len parameter must not be
+ * null.
+ *
+ * @param fmt_as_ptr Set to 1 to package format string as void pointer without
+ * header. It optimizes package size for read only strings. It must be a
+ * constant value at compile time.
+ *
+ * @param ... formatted string with arguments. Format string must be constant.
+ */
+#define CBPRINTF_STATIC_PACKAGE(packaged, len, fmt_as_ptr, ... /* fmt, ... */) \
+	Z_CBPRINTF_STATIC_PACKAGE(packaged, len, fmt_as_ptr, __VA_ARGS__)
+
+/** @brief Calculate package size at compile time.
+ *
+ * @param fmt_as_ptr Set to 1 to package format string as void pointer without
+ * header. It optimizes package size for read only strings.
+ *
+ * @param ... String with arguments.
+ *
+ * @return Calculated package size. As it is determined at compile time it can
+ * be assigned to a const variable.
+ */
+#define CBPRINTF_STATIC_PACKAGE_SIZE(fmt_as_ptr, ... /* fmt, ... */) \
+	Z_CBPRINTF_STATIC_PACKAGE_SIZE(fmt_as_ptr, __VA_ARGS__)
+
 /** @brief Capture state required to output formatted data later.
  *
  * Like cbprintf() but instead of processing the arguments and emitting the
@@ -66,6 +131,8 @@ typedef int (*cbprintf_cb)(/* int c, void *ctx */);
  * completely store the packed information.  The @p len parameter must not be
  * null.
  *
+ * @param flags Flags. See @ref CBPRINTF_PACKAGE_FLAGS.
+ *
  * @param format a standard ISO C format string with characters and conversion
  * specifications.
  *
@@ -78,9 +145,10 @@ typedef int (*cbprintf_cb)(/* int c, void *ctx */);
  * @retval -ENOSPC if @p packaged was not null and the space required to store
  * exceed the input value of @p *len.
  */
-__printf_like(3, 4)
+__printf_like(4, 5)
 int cbprintf_package(uint8_t *packaged,
 		     size_t *len,
+		     uint32_t flags,
 		     const char *format,
 		     ...);
 
@@ -109,6 +177,8 @@ int cbprintf_package(uint8_t *packaged,
  * completely store the packed information.  The @p len parameter must not be
  * null.
  *
+ * @param flags Flags. See @ref CBPRINTF_PACKAGE_FLAGS.
+ *
  * @param format a standard ISO C format string with characters and conversion
  * specifications.
  *
@@ -123,6 +193,7 @@ int cbprintf_package(uint8_t *packaged,
  */
 int cbvprintf_package(uint8_t *packaged,
 		      size_t *len,
+		      uint32_t flags,
 		      const char *format,
 		      va_list ap);
 
@@ -133,6 +204,8 @@ int cbvprintf_package(uint8_t *packaged,
  *
  * @param ctx context provided when invoking out
  *
+ * @param flags Flags. See @ref CBPRINTF_PACKAGE_FLAGS.
+ *
  * @param packaged the data required to generate the formatted output, as
  * captured by cbprintf_package() or cbvprintf_package().
  *
@@ -141,6 +214,7 @@ int cbvprintf_package(uint8_t *packaged,
  */
 int cbpprintf(cbprintf_cb out,
 	      void *ctx,
+	      uint32_t flags,
 	      const uint8_t *packaged);
 
 /** @brief *printf-like output through a callback.

include/sys/cbprintf_internal.h

@@ -0,0 +1,215 @@
+/*
+ * Copyright (c) 2020 Nordic Semiconductor ASA
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#ifndef ZEPHYR_INCLUDE_SYS_CBPRINTF_INTERNAL_H_
+#define ZEPHYR_INCLUDE_SYS_CBPRINTF_INTERNAL_H_
+
+#include <stdarg.h>
+#include <stddef.h>
+#include <stdint.h>
+#include <toolchain.h>
+#include <sys/util.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/** @brief Return 1 if argument is a pointer to char or wchar_t
+ *
+ * @param x argument.
+ *
+ * @return 1 if char * or wchar_t *, 0 otherwise.
+ */
+#define Z_CBPRINTF_IS_PCHAR(x) _Generic((x), \
+			char *: 1, \
+			const char *: 1, \
+			volatile char *: 1, \
+			const volatile char *: 1, \
+			wchar_t *: 1, \
+			const wchar_t *: 1, \
+			volatile wchar_t *: 1, \
+			const volatile wchar_t *: 1, \
+			default: 0)
+
+
+/** @brief Calculate number of char * or wchar_t * arguments in the arguments.
+ *
+ * @param fmt string.
+ *
+ * @param ... string arguments.
+ *
+ * @return number of arguments which are char * or wchar_t *.
+ */
+#define Z_CBPRINTF_HAS_PCHAR_ARGS_(fmt, ...) \
+	(FAST_FOR_EACH(Z_CBPRINTF_IS_PCHAR, (+),  __VA_ARGS__))
+
+/**
+ * @brief Check if formatted string must be packaged in runtime.
+ *
+ * @param skip number of char/wchar_t pointers in the argument list which are
+ * accepted for static packaging.
+ *
+ * @param ... String with arguments (fmt, ...).
+ *
+ * @retval 1 if string must be packaged at runtime.
+ * @retval 0 if string can be statically packaged.
+ */
+#define Z_CBPRINTF_MUST_RUNTIME_PACKAGE(skip, ...) \
+	COND_CODE_0(NUM_VA_ARGS_LESS_1(__VA_ARGS__), \
+			(0), \
+			((Z_CBPRINTF_HAS_PCHAR_ARGS_(__VA_ARGS__) - skip) > 0 ?\
+			 1 : 0))
+
+/** @brief Get storage size for given argument.
+ *
+ * Floats are promoted to double so they use size of double, others int storage
+ * or it's own storage size if it is bigger than int. Strings are stored in
+ * the package with 1 byte header indicating if string is stored as pointer or
+ * by value.
+ *
+ * @param x argument.
+ *
+ * @return Number of bytes used for storing the argument.
+ */
+#define Z_CBPRINTF_ARG_SIZE(v) \
+	_Generic((v), void *:sizeof(void *), \
+		      float: sizeof(double), \
+		      default: (MAX(sizeof(int), sizeof((v)+0))) + \
+			      _Generic((v) + 0, char *: 1, default: 0))
+
+/** @brief Get storage size in words.
+ *
+ * @param x argument.
+ *
+ * @return number of words needed for storage.
+ */
+#define Z_CBPRINTF_ARG_WSIZE(x) (Z_CBPRINTF_ARG_SIZE(x) / sizeof(int))
+
+/** @brief Macro for packaging single argument.
+ *
+ * Macro handles special cases:
+ * - promotions of arguments smaller than int
+ * - promotion of float
+ * - char * packaging which is prefixed with null byte.
+ * - special treatment of void * which would generate warning on arithmetic
+ *   operation ((void *)ptr + 0).
+ */
+#define Z_CBPRINTF_PACK(__buf, x, _arg_wsize) do {\
+	uint8_t *_buf = __buf; \
+	*_buf = 0; \
+	_buf += _Generic((x), \
+			void *: 0, \
+			default: _Generic((x)+0, \
+					 char *:1, \
+					 volatile char *: 1, \
+					 default: 0)); \
+	double _d = _Generic((x), \
+			float: (x), \
+			default: 0.0); \
+	(void)_d; \
+	int _i = _Generic((x), \
+			short: (x), \
+			default: 0); \
+	(void)_i; \
+	void *_v = _Generic((x), \
+			void *: (x), \
+			default: NULL); \
+	(void)_v; \
+	__auto_type _a = _Generic((x), \
+				  void *: NULL, \
+				  default: (x) + 0); \
+	z_cbprintf_wcpy(_buf, \
+			(void *)_Generic((x), \
+					float: &_d, \
+					short: &_i, \
+					void *: &_v, \
+					default: &_a), \
+			_arg_wsize ); \
+} while (0)
+
+/** @brief Safely package arguments to a buffer.
+ *
+ * Argument is put into the buffer if capable buffer is provided. Length is
+ * incremented even if data is not packaged.
+ *
+ * @param _buf buffer.
+ *
+ * @param _idx index. Index is postincremented.
+ *
+ * @param _max maximum index (buffer capacity).
+ *
+ * @param _arg argument.
+ */
+#define Z_CBPRINTF_PACK_ARG(_buf, _idx, _max, _arg) \
+	do { \
+		uint32_t _arg_size = Z_CBPRINTF_ARG_SIZE(_arg); \
+		uint32_t _arg_wsize = _arg_size / sizeof(uint32_t); \
+		if (_buf && _idx < _max) { \
+			Z_CBPRINTF_PACK(&_buf[_idx], _arg, _arg_wsize); \
+		} \
+		_idx += _arg_size; \
+	} while (0)
+
+/** @brief Package single argument.
+ *
+ * Macro is called in a loop for each argument in the string.
+ *
+ * @param arg argument.
+ */
+#define Z_CBPRINTF_LOOP_PACK_ARG(arg) \
+	do { \
+		Z_CBPRINTF_PACK_ARG(__package_buf, __package_len, \
+				    __package_max, arg); \
+	} while (0)
+
+/** @brief Statically package a formatted string with arguments.
+ *
+ * @param buf buffer. If null then only length is calculated.
+ *
+ * @param len buffer capacity on input, package size on output.
+ *
+ * @param fmt_as_ptr Flag indicating that format string is stored as void
+ * pointer.
+ *
+ * @param ... String with variable list of arguments.
+ */
+#define Z_CBPRINTF_STATIC_PACKAGE(buf, len, fmt_as_ptr, ... /* fmt, ... */) \
+	do { \
+		uint8_t *__package_buf = buf; \
+		size_t __package_max = (buf != NULL) ? len : SIZE_MAX; \
+		size_t __package_len = 0; \
+		FAST_FOR_EACH(Z_CBPRINTF_LOOP_PACK_ARG, (;), \
+			IF_ENABLED(fmt_as_ptr, ((uint8_t *)))__VA_ARGS__); \
+		len = __package_len; \
+	} while (0)
+
+#define Z_CBPRINTF_FMT_SIZE(fmt_as_ptr) (sizeof(void *) + (fmt_as_ptr ? 0 : 1))
+
+/** @brief Calculate package size. 0 is retuned if only null pointer is given.*/
+#define Z_CBPRINTF_STATIC_PACKAGE_SIZE(fmt_as_ptr, ...) \
+	COND_CODE_0(NUM_VA_ARGS_LESS_1(__VA_ARGS__), \
+		(FAST_GET_ARG_N(1, __VA_ARGS__) == NULL ? \
+			0 : Z_CBPRINTF_FMT_SIZE(fmt_as_ptr)), \
+		(Z_CBPRINTF_FMT_SIZE(fmt_as_ptr) + \
+		 FAST_FOR_EACH(Z_CBPRINTF_ARG_SIZE, \
+				(+), FAST_GET_ARGS_LESS_N(1,__VA_ARGS__))))
+
+static inline void z_cbprintf_wcpy(void *dst, void *src, uint32_t wlen)
+{
+	uint32_t *dst32 = dst;
+	uint32_t *src32 = src;
+
+	for (uint32_t i = 0; i < wlen; i++) {
+		dst32[i] = src32[i];
+	}
+}
+
+#ifdef __cplusplus
+}
+#endif
+
+
+#endif /* ZEPHYR_INCLUDE_SYS_CBPRINTF_INTERNAL_H_ */