1 /* 2 * Copyright (c) 2020 Nordic Semiconductor ASA 3 * 4 * SPDX-License-Identifier: Apache-2.0 5 */ 6 7 #ifndef ZEPHYR_INCLUDE_SYS_CBPRINTF_H_ 8 #define ZEPHYR_INCLUDE_SYS_CBPRINTF_H_ 9 10 #include <stdarg.h> 11 #include <stddef.h> 12 #include <stdint.h> 13 #include <toolchain.h> 14 15 #ifdef CONFIG_CBPRINTF_LIBC_SUBSTS 16 #include <stdio.h> 17 #endif /* CONFIG_CBPRINTF_LIBC_SUBSTS */ 18 19 /* Determine if _Generic is supported. 20 * In general it's a C11 feature but it was added also in: 21 * - GCC 4.9.0 https://gcc.gnu.org/gcc-4.9/changes.html 22 * - Clang 3.0 https://releases.llvm.org/3.0/docs/ClangReleaseNotes.html 23 * 24 * @note Z_C_GENERIC is also set for C++ where functionality is implemented 25 * using overloading and templates. 26 */ 27 #ifndef Z_C_GENERIC 28 #if defined(__cplusplus) || (((__STDC_VERSION__ >= 201112L) || \ 29 ((__GNUC__ * 10000 + __GNUC_MINOR__ * 100 + __GNUC_PATCHLEVEL__) >= 40900) || \ 30 ((__clang_major__ * 10000 + __clang_minor__ * 100 + __clang_patchlevel__) >= 30000))) 31 #define Z_C_GENERIC 1 32 #else 33 #define Z_C_GENERIC 0 34 #endif 35 #endif 36 37 /* Z_C_GENERIC is used there */ 38 #include <sys/cbprintf_internal.h> 39 40 #ifdef __cplusplus 41 extern "C" { 42 #endif 43 44 /** 45 * @defgroup cbprintf_apis Formatted Output APIs 46 * @ingroup support_apis 47 * @{ 48 */ 49 50 /** @brief Required alignment of the buffer used for packaging. */ 51 #ifdef __xtensa__ 52 #define CBPRINTF_PACKAGE_ALIGNMENT 16 53 #elif defined(CONFIG_X86) && !defined(CONFIG_64BIT) 54 /* sizeof(long double) is 12 on x86-32, which is not power of 2. 55 * So set it manually. 56 */ 57 #define CBPRINTF_PACKAGE_ALIGNMENT \ 58 (IS_ENABLED(CONFIG_CBPRINTF_PACKAGE_LONGDOUBLE) ? \ 59 16 : MAX(sizeof(double), sizeof(long long))) 60 #else 61 #define CBPRINTF_PACKAGE_ALIGNMENT \ 62 (IS_ENABLED(CONFIG_CBPRINTF_PACKAGE_LONGDOUBLE) ? \ 63 sizeof(long double) : MAX(sizeof(double), sizeof(long long))) 64 #endif 65 66 /**@defgroup CBPRINTF_PACKAGE_FLAGS Package flags. 67 * @{ 68 */ 69 70 /** @brief Append indexes of read-only string arguments in the package. 71 * 72 * When used, package contains locations of read-only string arguments. Package 73 * with that information can be converted to fully self-contain package using 74 * @ref cbprintf_fsc_package. 75 */ 76 #define CBPRINTF_PACKAGE_ADD_STRING_IDXS BIT(0) 77 78 /**@} */ 79 80 /** @brief Signature for a cbprintf callback function. 81 * 82 * This function expects two parameters: 83 * 84 * * @p c a character to output. The output behavior should be as if 85 * this was cast to an unsigned char. 86 * * @p ctx a pointer to an object that provides context for the 87 * output operation. 88 * 89 * The declaration does not specify the parameter types. This allows a 90 * function like @c fputc to be used without requiring all context pointers to 91 * be to a @c FILE object. 92 * 93 * @return the value of @p c cast to an unsigned char then back to 94 * int, or a negative error code that will be returned from 95 * cbprintf(). 96 */ 97 typedef int (*cbprintf_cb)(/* int c, void *ctx */); 98 99 /** @brief Determine if string must be packaged in run time. 100 * 101 * Static packaging can be applied if size of the package can be determined 102 * at compile time. In general, package size can be determined at compile time 103 * if there are no string arguments which might be copied into package body if 104 * they are considered transient. 105 * 106 * @param skip number of read only string arguments in the parameter list. It 107 * shall be non-zero if there are known read only string arguments present 108 * in the string (e.g. function name prefix in the log message). 109 * 110 * @param ... String with arguments. 111 * 112 * @retval 1 if string must be packaged in run time. 113 * @retval 0 string can be statically packaged. 114 */ 115 #define CBPRINTF_MUST_RUNTIME_PACKAGE(skip, ... /* fmt, ... */) \ 116 Z_CBPRINTF_MUST_RUNTIME_PACKAGE(skip, __VA_ARGS__) 117 118 /** @brief Statically package string. 119 * 120 * Build string package from formatted string. It assumes that formatted 121 * string is in the read only memory. 122 * 123 * If _Generic is not supported then runtime packaging is performed. 124 * 125 * @param packaged pointer to where the packaged data can be stored. Pass a null 126 * pointer to skip packaging but still calculate the total space required. 127 * The data stored here is relocatable, that is it can be moved to another 128 * contiguous block of memory. It must be aligned to the size of the longest 129 * argument. It is recommended to use CBPRINTF_PACKAGE_ALIGNMENT for alignment. 130 * 131 * @param inlen set to the number of bytes available at @p packaged. If 132 * @p packaged is NULL the value is ignored. 133 * 134 * @param outlen variable updated to the number of bytes required to completely 135 * store the packed information. If input buffer was too small it is set to 136 * -ENOSPC. 137 * 138 * @param align_offset input buffer alignment offset in bytes. Where offset 0 139 * means that buffer is aligned to CBPRINTF_PACKAGE_ALIGNMENT. Xtensa requires 140 * that @p packaged is aligned to CBPRINTF_PACKAGE_ALIGNMENT so it must be 141 * multiply of CBPRINTF_PACKAGE_ALIGNMENT or 0. 142 * 143 * @param flags option flags. See @ref CBPRINTF_PACKAGE_FLAGS. 144 * 145 * @param ... formatted string with arguments. Format string must be constant. 146 */ 147 #define CBPRINTF_STATIC_PACKAGE(packaged, inlen, outlen, align_offset, flags, \ 148 ... /* fmt, ... */) \ 149 Z_CBPRINTF_STATIC_PACKAGE(packaged, inlen, outlen, \ 150 align_offset, flags, __VA_ARGS__) 151 152 /** @brief Capture state required to output formatted data later. 153 * 154 * Like cbprintf() but instead of processing the arguments and emitting the 155 * formatted results immediately all arguments are captured so this can be 156 * done in a different context, e.g. when the output function can block. 157 * 158 * In addition to the values extracted from arguments this will ensure that 159 * copies are made of the necessary portions of any string parameters that are 160 * not confirmed to be stored in read-only memory (hence assumed to be safe to 161 * refer to directly later). 162 * 163 * @param packaged pointer to where the packaged data can be stored. Pass a 164 * null pointer to store nothing but still calculate the total space required. 165 * The data stored here is relocatable, that is it can be moved to another 166 * contiguous block of memory. However, under condition that alignment is 167 * maintained. It must be aligned to at least the size of a pointer. 168 * 169 * @param len this must be set to the number of bytes available at @p packaged 170 * if it is not null. If @p packaged is null then it indicates hypothetical 171 * buffer alignment offset in bytes compared to CBPRINTF_PACKAGE_ALIGNMENT 172 * alignment. Buffer alignment offset impacts returned size of the package. 173 * Xtensa requires that buffer is always aligned to CBPRINTF_PACKAGE_ALIGNMENT 174 * so it must be multiply of CBPRINTF_PACKAGE_ALIGNMENT or 0 when @p packaged is 175 * null. 176 * 177 * @param flags option flags. See @ref CBPRINTF_PACKAGE_FLAGS. 178 * 179 * @param format a standard ISO C format string with characters and conversion 180 * specifications. 181 * 182 * @param ... arguments corresponding to the conversion specifications found 183 * within @p format. 184 * 185 * @retval nonegative the number of bytes successfully stored at @p packaged. 186 * This will not exceed @p len. 187 * @retval -EINVAL if @p format is not acceptable 188 * @retval -EFAULT if @p packaged alignment is not acceptable 189 * @retval -ENOSPC if @p packaged was not null and the space required to store 190 * exceed @p len. 191 */ 192 __printf_like(4, 5) 193 int cbprintf_package(void *packaged, 194 size_t len, 195 uint32_t flags, 196 const char *format, 197 ...); 198 199 /** @brief Capture state required to output formatted data later. 200 * 201 * Like cbprintf() but instead of processing the arguments and emitting the 202 * formatted results immediately all arguments are captured so this can be 203 * done in a different context, e.g. when the output function can block. 204 * 205 * In addition to the values extracted from arguments this will ensure that 206 * copies are made of the necessary portions of any string parameters that are 207 * not confirmed to be stored in read-only memory (hence assumed to be safe to 208 * refer to directly later). 209 * 210 * @param packaged pointer to where the packaged data can be stored. Pass a 211 * null pointer to store nothing but still calculate the total space required. 212 * The data stored here is relocatable, that is it can be moved to another 213 * contiguous block of memory. The pointer must be aligned to a multiple of 214 * the largest element in the argument list. 215 * 216 * @param len this must be set to the number of bytes available at @p packaged. 217 * Ignored if @p packaged is NULL. 218 * 219 * @param flags option flags. See @ref CBPRINTF_PACKAGE_FLAGS. 220 * 221 * @param format a standard ISO C format string with characters and conversion 222 * specifications. 223 * 224 * @param ap captured stack arguments corresponding to the conversion 225 * specifications found within @p format. 226 * 227 * @retval nonegative the number of bytes successfully stored at @p packaged. 228 * This will not exceed @p len. 229 * @retval -EINVAL if @p format is not acceptable 230 * @retval -ENOSPC if @p packaged was not null and the space required to store 231 * exceed @p len. 232 */ 233 int cbvprintf_package(void *packaged, 234 size_t len, 235 uint32_t flags, 236 const char *format, 237 va_list ap); 238 239 /** @brief Convert package to fully self-contained (fsc) package. 240 * 241 * By default, package does not contain read only strings. However, if needed 242 * it may be converted to a fully self-contained package which contains all 243 * strings. In order to allow such conversion, original package must be created 244 * with @ref CBPRINTF_PACKAGE_ADD_STRING_IDXS flag. Such package will contain 245 * necessary data to find read only strings in the package and copy them into 246 * package body. 247 * 248 * @param in_packaged pointer to original package created with 249 * @ref CBPRINTF_PACKAGE_ADD_STRING_IDXS. 250 * 251 * @param in_len @p in_packaged length. 252 * 253 * @param packaged pointer to location where fully self-contained version of the 254 * input package will be written. Pass a null pointer to calculate space required. 255 * 256 * @param len must be set to the number of bytes available at @p packaged. Not 257 * used if @p packaged is null. 258 * 259 * @retval nonegative the number of bytes successfully stored at @p packaged. 260 * This will not exceed @p len. If @p packaged is null, calculated length. 261 * @retval -ENOSPC if @p packaged was not null and the space required to store 262 * exceed @p len. 263 * @retval -EINVAL if @p in_packaged is null. 264 */ 265 int cbprintf_fsc_package(void *in_packaged, 266 size_t in_len, 267 void *packaged, 268 size_t len); 269 270 /** @brief Generate the output for a previously captured format 271 * operation. 272 * 273 * @param out the function used to emit each generated character. 274 * 275 * @param ctx context provided when invoking out 276 * 277 * @param packaged the data required to generate the formatted output, as 278 * captured by cbprintf_package() or cbvprintf_package(). The alignment 279 * requirement on this data is the same as when it was initially created. 280 * 281 * @note Memory indicated by @p packaged will be modified in a non-destructive 282 * way, meaning that it could still be reused with this function again. 283 * 284 * @return the number of characters printed, or a negative error value 285 * returned from invoking @p out. 286 */ 287 int cbpprintf(cbprintf_cb out, 288 void *ctx, 289 void *packaged); 290 291 /** @brief *printf-like output through a callback. 292 * 293 * This is essentially printf() except the output is generated 294 * character-by-character using the provided @p out function. This allows 295 * formatting text of unbounded length without incurring the cost of a 296 * temporary buffer. 297 * 298 * All formatting specifiers of C99 are recognized, and most are supported if 299 * the functionality is enabled. 300 * 301 * @note The functionality of this function is significantly reduced 302 * when @kconfig{CONFIG_CBPRINTF_NANO} is selected. 303 * 304 * @param out the function used to emit each generated character. 305 * 306 * @param ctx context provided when invoking out 307 * 308 * @param format a standard ISO C format string with characters and conversion 309 * specifications. 310 * 311 * @param ... arguments corresponding to the conversion specifications found 312 * within @p format. 313 * 314 * @return the number of characters printed, or a negative error value 315 * returned from invoking @p out. 316 */ 317 __printf_like(3, 4) 318 int cbprintf(cbprintf_cb out, void *ctx, const char *format, ...); 319 320 /** @brief varargs-aware *printf-like output through a callback. 321 * 322 * This is essentially vsprintf() except the output is generated 323 * character-by-character using the provided @p out function. This allows 324 * formatting text of unbounded length without incurring the cost of a 325 * temporary buffer. 326 * 327 * @note This function is available only when 328 * @kconfig{CONFIG_CBPRINTF_LIBC_SUBSTS} is selected. 329 * 330 * @note The functionality of this function is significantly reduced when 331 * @kconfig{CONFIG_CBPRINTF_NANO} is selected. 332 * 333 * @param out the function used to emit each generated character. 334 * 335 * @param ctx context provided when invoking out 336 * 337 * @param format a standard ISO C format string with characters and conversion 338 * specifications. 339 * 340 * @param ap a reference to the values to be converted. 341 * 342 * @return the number of characters generated, or a negative error value 343 * returned from invoking @p out. 344 */ 345 int cbvprintf(cbprintf_cb out, void *ctx, const char *format, va_list ap); 346 347 #ifdef CONFIG_CBPRINTF_LIBC_SUBSTS 348 349 /** @brief fprintf using Zephyrs cbprintf infrastructure. 350 * 351 * @note This function is available only when 352 * @kconfig{CONFIG_CBPRINTF_LIBC_SUBSTS} is selected. 353 * 354 * @note The functionality of this function is significantly reduced 355 * when @kconfig{CONFIG_CBPRINTF_NANO} is selected. 356 * 357 * @param stream the stream to which the output should be written. 358 * 359 * @param format a standard ISO C format string with characters and 360 * conversion specifications. 361 * 362 * @param ... arguments corresponding to the conversion specifications found 363 * within @p format. 364 * 365 * return The number of characters printed. 366 */ 367 __printf_like(2, 3) 368 int fprintfcb(FILE * stream, const char *format, ...); 369 370 /** @brief vfprintf using Zephyrs cbprintf infrastructure. 371 * 372 * @note This function is available only when 373 * @kconfig{CONFIG_CBPRINTF_LIBC_SUBSTS} is selected. 374 * 375 * @note The functionality of this function is significantly reduced when 376 * @kconfig{CONFIG_CBPRINTF_NANO} is selected. 377 * 378 * @param stream the stream to which the output should be written. 379 * 380 * @param format a standard ISO C format string with characters and conversion 381 * specifications. 382 * 383 * @param ap a reference to the values to be converted. 384 * 385 * @return The number of characters printed. 386 */ 387 int vfprintfcb(FILE *stream, const char *format, va_list ap); 388 389 /** @brief printf using Zephyrs cbprintf infrastructure. 390 * 391 * @note This function is available only when 392 * @kconfig{CONFIG_CBPRINTF_LIBC_SUBSTS} is selected. 393 * 394 * @note The functionality of this function is significantly reduced 395 * when @kconfig{CONFIG_CBPRINTF_NANO} is selected. 396 * 397 * @param format a standard ISO C format string with characters and 398 * conversion specifications. 399 * 400 * @param ... arguments corresponding to the conversion specifications found 401 * within @p format. 402 * 403 * @return The number of characters printed. 404 */ 405 __printf_like(1, 2) 406 int printfcb(const char *format, ...); 407 408 /** @brief vprintf using Zephyrs cbprintf infrastructure. 409 * 410 * @note This function is available only when 411 * @kconfig{CONFIG_CBPRINTF_LIBC_SUBSTS} is selected. 412 * 413 * @note The functionality of this function is significantly reduced when 414 * @kconfig{CONFIG_CBPRINTF_NANO} is selected. 415 * 416 * @param format a standard ISO C format string with characters and conversion 417 * specifications. 418 * 419 * @param ap a reference to the values to be converted. 420 * 421 * @return The number of characters printed. 422 */ 423 int vprintfcb(const char *format, va_list ap); 424 425 /** @brief snprintf using Zephyrs cbprintf infrastructure. 426 * 427 * @note This function is available only when 428 * @kconfig{CONFIG_CBPRINTF_LIBC_SUBSTS} is selected. 429 * 430 * @note The functionality of this function is significantly reduced 431 * when @kconfig{CONFIG_CBPRINTF_NANO} is selected. 432 * 433 * @param str where the formatted content should be written 434 * 435 * @param size maximum number of chaacters for the formatted output, 436 * including the terminating null byte. 437 * 438 * @param format a standard ISO C format string with characters and 439 * conversion specifications. 440 * 441 * @param ... arguments corresponding to the conversion specifications found 442 * within @p format. 443 * 444 * @return The number of characters that would have been written to @p 445 * str, excluding the terminating null byte. This is greater than the 446 * number actually written if @p size is too small. 447 */ 448 __printf_like(3, 4) 449 int snprintfcb(char *str, size_t size, const char *format, ...); 450 451 /** @brief vsnprintf using Zephyrs cbprintf infrastructure. 452 * 453 * @note This function is available only when 454 * @kconfig{CONFIG_CBPRINTF_LIBC_SUBSTS} is selected. 455 * 456 * @note The functionality of this function is significantly reduced when 457 * @kconfig{CONFIG_CBPRINTF_NANO} is selected. 458 * 459 * @param str where the formatted content should be written 460 * 461 * @param size maximum number of chaacters for the formatted output, including 462 * the terminating null byte. 463 * 464 * @param format a standard ISO C format string with characters and conversion 465 * specifications. 466 * 467 * @param ap a reference to the values to be converted. 468 * 469 * @return The number of characters that would have been written to @p 470 * str, excluding the terminating null byte. This is greater than the 471 * number actually written if @p size is too small. 472 */ 473 int vsnprintfcb(char *str, size_t size, const char *format, va_list ap); 474 475 #endif /* CONFIG_CBPRINTF_LIBC_SUBSTS */ 476 477 /** 478 * @} 479 */ 480 481 #ifdef __cplusplus 482 } 483 #endif 484 485 #endif /* ZEPHYR_INCLUDE_SYS_CBPRINTF_H_ */ 486
