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 <zephyr/toolchain.h>
14 #include <string.h>
15
16 #ifdef CONFIG_CBPRINTF_LIBC_SUBSTS
17 #include <stdio.h>
18 #endif /* CONFIG_CBPRINTF_LIBC_SUBSTS */
19
20 /* Determine if _Generic is supported using macro from toolchain.h.
21 *
22 * @note Z_C_GENERIC is also set for C++ where functionality is implemented
23 * using overloading and templates.
24 */
25 #ifndef Z_C_GENERIC
26 #if defined(__cplusplus) || TOOLCHAIN_HAS_C_GENERIC
27 #define Z_C_GENERIC 1
28 #else
29 #define Z_C_GENERIC 0
30 #endif
31 #endif
32
33 #ifdef __xtensa__
34 #define Z_PKG_HDR_EXT_XTENSA_ALIGNMENT 8
35 #ifdef CONFIG_CBPRINTF_PACKAGE_HEADER_STORE_CREATION_FLAGS
36 #define Z_PKG_DESC_XTENSA_PADDING 1
37 #else
38 #define Z_PKG_DESC_XTENSA_PADDING 0
39 #endif
40 #endif /* __xtensa__ */
41
42 /**
43 * @brief cbprintf package descriptor.
44 */
45 struct cbprintf_package_desc {
46 /** Package length (in 32 bit words) */
47 uint8_t len;
48
49 /** Number of appended strings in the package. */
50 uint8_t str_cnt;
51
52 /** Number of read-only strings, indexes appended to the package */
53 uint8_t ro_str_cnt;
54
55 /** Number of read-write strings, indexes appended to the package */
56 uint8_t rw_str_cnt;
57
58 #ifdef CONFIG_CBPRINTF_PACKAGE_HEADER_STORE_CREATION_FLAGS
59 /** Flags used to create the package */
60 uint32_t pkg_flags;
61 #endif
62 #ifdef __xtensa__
63 /*
64 * On Xtensa, the first argument needs to be aligned to 8-byte.
65 * With 32-bit pointers, we need another 4 bytes padding so
66 * that whole struct cbprintf_package_hdr_ext is of multiple of
67 * 8 bytes.
68 */
69 uint32_t xtensa_padding[Z_PKG_DESC_XTENSA_PADDING];
70 #endif
71
72 } __packed;
73
74 /** @brief cbprintf package header
75 *
76 * cbprintf package header, without the format string pointer.
77 */
78 union cbprintf_package_hdr {
79 /** Header description */
80 struct cbprintf_package_desc desc;
81
82 void *raw;
83
84 #if defined(CONFIG_CBPRINTF_PACKAGE_HEADER_STORE_CREATION_FLAGS) && !defined(CONFIG_64BIT)
85 void *raw2[2];
86 #endif
87
88 } __packed;
89
90
91
92 /** @brief cbprintf package header with format string pointer.
93 *
94 * cbprintf package header with format string pointer.
95 */
96 struct cbprintf_package_hdr_ext {
97 /** Header of package */
98 union cbprintf_package_hdr hdr;
99
100 /** Pointer to format string */
101 char *fmt;
102
103 /*
104 * When extending this struct, make sure this align
105 * to pointer size.
106 */
107 } __packed;
108
109
110 /**
111 * @cond INTERNAL_HIDDEN
112 *
113 * Assert that the package hdr does indeed align properly.
114 */
115 #ifdef __xtensa__
116 BUILD_ASSERT(sizeof(struct cbprintf_package_hdr_ext) % Z_PKG_HDR_EXT_XTENSA_ALIGNMENT == 0,
117 "Package header size on Xtensa must be aligned");
118 #endif
119 /**
120 * @endcond
121 */
122
123 /* Z_C_GENERIC is used there */
124 #include <zephyr/sys/cbprintf_internal.h>
125
126 #ifdef __cplusplus
127 extern "C" {
128 #endif
129
130 /**
131 * @defgroup cbprintf_apis Formatted Output APIs
132 * @ingroup utilities
133 * @{
134 */
135
136 /** @brief Required alignment of the buffer used for packaging. */
137 #ifdef __xtensa__
138 #define CBPRINTF_PACKAGE_ALIGNMENT 16
139 #else
140 #define CBPRINTF_PACKAGE_ALIGNMENT \
141 Z_POW2_CEIL(COND_CODE_1(CONFIG_CBPRINTF_PACKAGE_LONGDOUBLE, \
142 (sizeof(long double)), (MAX(sizeof(double), sizeof(long long)))))
143 #endif
144
145 BUILD_ASSERT(Z_IS_POW2(CBPRINTF_PACKAGE_ALIGNMENT));
146
147
148 /**@defgroup CBPRINTF_PACKAGE_FLAGS Package flags
149 * @{
150 */
151
152 /** @brief Assume that const char pointer is pointing to read only (constant) strings.
153 *
154 * Flag is valid only for @ref CBPRINTF_STATIC_PACKAGE.
155 */
156 #define CBPRINTF_PACKAGE_CONST_CHAR_RO BIT(0)
157
158 /** @brief Append locations (within the package) of read-only string pointers. */
159 #define CBPRINTF_PACKAGE_ADD_RO_STR_POS BIT(1)
160
161 /** @brief Append locations (within the package) of read-write string pointers.
162 *
163 * When this flag is not used then read-write strings are appended to the package.
164 */
165 #define CBPRINTF_PACKAGE_ADD_RW_STR_POS BIT(2)
166
167 #define Z_CBPRINTF_PACKAGE_FIRST_RO_STR_BITS 3
168 #define Z_CBPRINTF_PACKAGE_FIRST_RO_STR_OFFSET 3
169 #define Z_CBPRINTF_PACKAGE_FIRST_RO_STR_MASK BIT_MASK(Z_CBPRINTF_PACKAGE_FIRST_RO_STR_BITS)
170
171 /** @brief Indicate that @p n first string format arguments are char pointers to
172 * read-only location.
173 *
174 * Runtime algorithm (address analysis) is skipped for those strings.
175 *
176 * @param n Number of string arguments considered as read-only.
177 */
178 #define CBPRINTF_PACKAGE_FIRST_RO_STR_CNT(n) \
179 (n << Z_CBPRINTF_PACKAGE_FIRST_RO_STR_OFFSET)
180
181 /** @brief Get number of first format string arguments which are known to be read-only
182 * string.
183 */
184 #define Z_CBPRINTF_PACKAGE_FIRST_RO_STR_CNT_GET(flags) \
185 (((flags) >> Z_CBPRINTF_PACKAGE_FIRST_RO_STR_OFFSET) & Z_CBPRINTF_PACKAGE_FIRST_RO_STR_MASK)
186
187 /** @brief Append indexes of read-only string arguments in the package.
188 *
189 * When used, package contains locations of read-only string arguments. Package
190 * with that information can be converted to fully self-contain package using
191 * @ref cbprintf_fsc_package.
192 */
193 #define CBPRINTF_PACKAGE_ADD_STRING_IDXS \
194 (CBPRINTF_PACKAGE_ADD_RO_STR_POS | CBPRINTF_PACKAGE_CONST_CHAR_RO)
195
196 /** @brief Indicate the incoming arguments are tagged.
197 *
198 * When set, this indicates that the incoming arguments are tagged, and
199 * need to be processed accordingly.
200 */
201 #define CBPRINTF_PACKAGE_ARGS_ARE_TAGGED BIT(6)
202
203 /**@} */
204
205 /**
206 * @defgroup CBPRINTF_PACKAGE_CONVERT_FLAGS Package convert flags
207 * @{
208 */
209
210 /** @brief Append read-only strings from source package to destination package.
211 *
212 * If package was created with @ref CBPRINTF_PACKAGE_ADD_RO_STR_POS
213 * or @ref CBPRINTF_PACKAGE_ADD_RW_STR_POS it contains arrays of indexes where
214 * string address can be found in the package. When flag is set, read-only strings
215 * are copied into destination package. Address of strings indicated as read-write
216 * are also checked and if determined to be read-only they are also copied.
217 */
218 #define CBPRINTF_PACKAGE_CONVERT_RO_STR BIT(0)
219 /** @deprecated Use @ref CBPRINTF_PACKAGE_CONVERT_RO_STR instead. */
220 #define CBPRINTF_PACKAGE_COPY_RO_STR CBPRINTF_PACKAGE_CONVERT_RO_STR __DEPRECATED_MACRO
221
222 /** @brief Append read-write strings from source package to destination package.
223 *
224 * If package was created with @ref CBPRINTF_PACKAGE_ADD_RW_STR_POS it contains
225 * arrays of indexes where string address can be found in the package. When flag
226 * is set, list of read-write strings is examined and if they are not determined
227 * to be read-only, they are copied into the destination package.
228 * If @ref CBPRINTF_PACKAGE_CONVERT_RO_STR is not set, remaining string locations
229 * are considered as pointing to read-only location and they are copy to the
230 * package if @ref CBPRINTF_PACKAGE_CONVERT_KEEP_RO_STR is set.
231 */
232 #define CBPRINTF_PACKAGE_CONVERT_RW_STR BIT(1)
233 /** @deprecated Use @ref CBPRINTF_PACKAGE_CONVERT_RW_STR instead. */
234 #define CBPRINTF_PACKAGE_COPY_RW_STR CBPRINTF_PACKAGE_CONVERT_RW_STR __DEPRECATED_MACRO
235
236 /** @brief Keep read-only location indexes in the package.
237 *
238 * If it is set read-only string pointers are kept in the package after copy. If
239 * not set they are discarded.
240 */
241 #define CBPRINTF_PACKAGE_CONVERT_KEEP_RO_STR BIT(2)
242 /** @deprecated Use @ref CBPRINTF_PACKAGE_CONVERT_KEEP_RO_STR instead. */
243 #define CBPRINTF_PACKAGE_COPY_KEEP_RO_STR CBPRINTF_PACKAGE_CONVERT_KEEP_RO_STR __DEPRECATED_MACRO
244
245 /** @brief Check format string if %p argument was treated as %s in the package.
246 *
247 * Static packaging is done based only on types of arguments used for a format
248 * string. Without looking into format specifiers present in the string. Because
249 * of that if (unsigned) char pointer is used for %p it will be considered as
250 * a string location and during conversion an attempt to append a string to a
251 * package may be performed. This can lead to misbehavior, in the best case
252 * package will be bigger and in the worst case memory fault or security violation
253 * may occur.
254 *
255 * When this flag is set, format string will be checked to detect cases when
256 * string candidate is a pointer used for %p and string appending from unexpected
257 * location is avoided. Additionally, an log warning is generated to encourage
258 * user to cast such argument to void *. It is recommended because there are
259 * configurations where string is not accessible and inspection cannot be done.
260 * In those cases there are no means to detect such cases.
261 */
262 #define CBPRINTF_PACKAGE_CONVERT_PTR_CHECK BIT(3)
263
264 /**@} */
265
266 /**
267 * @defgroup Z_CBVPRINTF_PROCESS_FLAGS cbvprintf processing flags.
268 * @{
269 */
270
271 /** @brief Indicates the arguments are tagged.
272 *
273 * This tells z_cbvprintf_impl() that the incoming arguments are
274 * tagged, and should be processed accordingly.
275 */
276 #define Z_CBVPRINTF_PROCESS_FLAG_TAGGED_ARGS BIT(0)
277
278 /**@} */
279
280 #include <zephyr/sys/cbprintf_enums.h>
281
282 /** @brief Signature for a cbprintf callback function.
283 *
284 * This function expects two parameters:
285 *
286 * * @p c a character to output. The output behavior should be as if
287 * this was cast to an unsigned char.
288 * * @p ctx a pointer to an object that provides context for the
289 * output operation.
290 *
291 * The declaration does not specify the parameter types. This allows a
292 * function like @c fputc to be used without requiring all context pointers to
293 * be to a @c FILE object.
294 *
295 * @return the value of @p c cast to an unsigned char then back to
296 * int, or a negative error code that will be returned from
297 * cbprintf().
298 */
299 #ifdef __CHECKER__
300 typedef int (*cbprintf_cb)(int c, void *ctx);
301 #else
302 typedef int (*cbprintf_cb)(/* int c, void *ctx */);
303 #endif
304
305 /** @brief Signature for a cbprintf multibyte callback function.
306 *
307 * @param buf data.
308 * @param len data length.
309 * @param ctx a pointer to an object that provides context for the operation.
310 *
311 * return Amount of copied data or negative error code.
312 */
313 typedef int (*cbprintf_convert_cb)(const void *buf, size_t len, void *ctx);
314
315 /** @brief Signature for a external formatter function identical to cbvprintf.
316 *
317 * This function expects the following parameters:
318 *
319 * @param out the function used to emit each generated character.
320 *
321 * @param ctx a pointer to an object that provides context for the
322 * external formatter.
323 *
324 * @param fmt a standard ISO C format string with characters and
325 * conversion specifications.
326 *
327 * @param ap captured stack arguments corresponding to the conversion
328 * specifications found within @p fmt.
329 *
330 * @return vprintf like return values: the number of characters printed,
331 * or a negative error value returned from external formatter.
332 */
333 typedef int (*cbvprintf_external_formatter_func)(cbprintf_cb out, void *ctx,
334 const char *fmt, va_list ap);
335
336 /** @brief Determine if string must be packaged in run time.
337 *
338 * Static packaging can be applied if size of the package can be determined
339 * at compile time. In general, package size can be determined at compile time
340 * if there are no string arguments which might be copied into package body if
341 * they are considered transient.
342 *
343 * @note By default any char pointers are considered to be pointing at transient
344 * strings. This can be narrowed down to non const pointers by using
345 * @ref CBPRINTF_PACKAGE_CONST_CHAR_RO.
346 *
347 * @param ... String with arguments.
348 * @param flags option flags. See @ref CBPRINTF_PACKAGE_FLAGS.
349 *
350 * @retval 1 if string must be packaged in run time.
351 * @retval 0 string can be statically packaged.
352 */
353 #define CBPRINTF_MUST_RUNTIME_PACKAGE(flags, ... /* fmt, ... */) \
354 Z_CBPRINTF_MUST_RUNTIME_PACKAGE(flags, __VA_ARGS__)
355
356 /** @brief Statically package string.
357 *
358 * Build string package from formatted string. It assumes that formatted
359 * string is in the read only memory.
360 *
361 * If _Generic is not supported then runtime packaging is performed.
362 *
363 * @param packaged pointer to where the packaged data can be stored. Pass a null
364 * pointer to skip packaging but still calculate the total space required.
365 * The data stored here is relocatable, that is it can be moved to another
366 * contiguous block of memory. It must be aligned to the size of the longest
367 * argument. It is recommended to use CBPRINTF_PACKAGE_ALIGNMENT for alignment.
368 *
369 * @param inlen set to the number of bytes available at @p packaged. If
370 * @p packaged is NULL the value is ignored.
371 *
372 * @param outlen variable updated to the number of bytes required to completely
373 * store the packed information. If input buffer was too small it is set to
374 * -ENOSPC.
375 *
376 * @param align_offset input buffer alignment offset in bytes. Where offset 0
377 * means that buffer is aligned to CBPRINTF_PACKAGE_ALIGNMENT. Xtensa requires
378 * that @p packaged is aligned to CBPRINTF_PACKAGE_ALIGNMENT so it must be
379 * multiply of CBPRINTF_PACKAGE_ALIGNMENT or 0.
380 *
381 * @param flags option flags. See @ref CBPRINTF_PACKAGE_FLAGS.
382 *
383 * @param ... formatted string with arguments. Format string must be constant.
384 */
385 #define CBPRINTF_STATIC_PACKAGE(packaged, inlen, outlen, align_offset, flags, \
386 ... /* fmt, ... */) \
387 Z_CBPRINTF_STATIC_PACKAGE(packaged, inlen, outlen, \
388 align_offset, flags, __VA_ARGS__)
389
390 /** @brief Capture state required to output formatted data later.
391 *
392 * Like cbprintf() but instead of processing the arguments and emitting the
393 * formatted results immediately all arguments are captured so this can be
394 * done in a different context, e.g. when the output function can block.
395 *
396 * In addition to the values extracted from arguments this will ensure that
397 * copies are made of the necessary portions of any string parameters that are
398 * not confirmed to be stored in read-only memory (hence assumed to be safe to
399 * refer to directly later).
400 *
401 * @param packaged pointer to where the packaged data can be stored. Pass a
402 * null pointer to store nothing but still calculate the total space required.
403 * The data stored here is relocatable, that is it can be moved to another
404 * contiguous block of memory. However, under condition that alignment is
405 * maintained. It must be aligned to at least the size of a pointer.
406 *
407 * @param len this must be set to the number of bytes available at @p packaged
408 * if it is not null. If @p packaged is null then it indicates hypothetical
409 * buffer alignment offset in bytes compared to CBPRINTF_PACKAGE_ALIGNMENT
410 * alignment. Buffer alignment offset impacts returned size of the package.
411 * Xtensa requires that buffer is always aligned to CBPRINTF_PACKAGE_ALIGNMENT
412 * so it must be multiply of CBPRINTF_PACKAGE_ALIGNMENT or 0 when @p packaged is
413 * null.
414 *
415 * @param flags option flags. See @ref CBPRINTF_PACKAGE_FLAGS.
416 *
417 * @param format a standard ISO C format string with characters and conversion
418 * specifications.
419 *
420 * @param ... arguments corresponding to the conversion specifications found
421 * within @p format.
422 *
423 * @retval nonegative the number of bytes successfully stored at @p packaged.
424 * This will not exceed @p len.
425 * @retval -EINVAL if @p format is not acceptable
426 * @retval -EFAULT if @p packaged alignment is not acceptable
427 * @retval -ENOSPC if @p packaged was not null and the space required to store
428 * exceed @p len.
429 */
430 __printf_like(4, 5)
431 int cbprintf_package(void *packaged,
432 size_t len,
433 uint32_t flags,
434 const char *format,
435 ...);
436
437 /** @brief Capture state required to output formatted data later.
438 *
439 * Like cbprintf() but instead of processing the arguments and emitting the
440 * formatted results immediately all arguments are captured so this can be
441 * done in a different context, e.g. when the output function can block.
442 *
443 * In addition to the values extracted from arguments this will ensure that
444 * copies are made of the necessary portions of any string parameters that are
445 * not confirmed to be stored in read-only memory (hence assumed to be safe to
446 * refer to directly later).
447 *
448 * @param packaged pointer to where the packaged data can be stored. Pass a
449 * null pointer to store nothing but still calculate the total space required.
450 * The data stored here is relocatable, that is it can be moved to another
451 * contiguous block of memory. The pointer must be aligned to a multiple of
452 * the largest element in the argument list.
453 *
454 * @param len this must be set to the number of bytes available at @p packaged.
455 * Ignored if @p packaged is NULL.
456 *
457 * @param flags option flags. See @ref CBPRINTF_PACKAGE_FLAGS.
458 *
459 * @param format a standard ISO C format string with characters and conversion
460 * specifications.
461 *
462 * @param ap captured stack arguments corresponding to the conversion
463 * specifications found within @p format.
464 *
465 * @retval nonegative the number of bytes successfully stored at @p packaged.
466 * This will not exceed @p len.
467 * @retval -EINVAL if @p format is not acceptable
468 * @retval -ENOSPC if @p packaged was not null and the space required to store
469 * exceed @p len.
470 */
471 int cbvprintf_package(void *packaged,
472 size_t len,
473 uint32_t flags,
474 const char *format,
475 va_list ap);
476
477 /** @brief Convert a package.
478 *
479 * Converting may include appending strings used in the package to the package body.
480 * If input package was created with @ref CBPRINTF_PACKAGE_ADD_RO_STR_POS or
481 * @ref CBPRINTF_PACKAGE_ADD_RW_STR_POS, it contains information where strings
482 * are located within the package. This information can be used to copy strings
483 * during the conversion.
484 *
485 * @p cb is called with portions of the output package. At the end of the conversion
486 * @p cb is called with null buffer.
487 *
488 * @param in_packaged Input package.
489 *
490 * @param in_len Input package length. If 0 package length will be retrieved
491 * from the @p in_packaged
492 *
493 * @param cb callback called with portions of the converted package. If null only
494 * length of the output package is calculated.
495 *
496 * @param ctx Context provided to the @p cb.
497 *
498 * @param flags Flags. See @ref CBPRINTF_PACKAGE_CONVERT_FLAGS.
499 *
500 * @param[in, out] strl if @p packaged is null, it is a pointer to the array where
501 * @p strl_len first string lengths will is stored. If @p packaged is not null,
502 * it contains lengths of first @p strl_len strings. It can be used to optimize
503 * copying so that string length is calculated only once (at length calculation
504 * phase when @p packaged is null.)
505 *
506 * @param strl_len Number of elements in @p strl array.
507 *
508 * @retval Positive output package size.
509 * @retval -ENOSPC if @p packaged was not null and the space required to store
510 * exceed @p len.
511 */
512 int cbprintf_package_convert(void *in_packaged,
513 size_t in_len,
514 cbprintf_convert_cb cb,
515 void *ctx,
516 uint32_t flags,
517 uint16_t *strl,
518 size_t strl_len);
519
520 /* @interal Context used for package copying. */
521 struct z_cbprintf_buf_desc {
522 void *buf;
523 size_t size;
524 size_t off;
525 };
526
527 /* @internal Function callback used for package copying. */
z_cbprintf_cpy(const void * buf,size_t len,void * ctx)528 static inline int z_cbprintf_cpy(const void *buf, size_t len, void *ctx)
529 {
530 struct z_cbprintf_buf_desc *desc = (struct z_cbprintf_buf_desc *)ctx;
531
532 if ((desc->size - desc->off) < len) {
533 return -ENOSPC;
534 }
535
536 memcpy(&((uint8_t *)desc->buf)[desc->off], buf, len);
537 desc->off += len;
538
539 return len;
540 }
541
542 /** @brief Copy package with optional appending of strings.
543 *
544 * @ref cbprintf_package_convert is used to convert and store converted package
545 * in the new location.
546 *
547 * @param in_packaged Input package.
548 *
549 * @param in_len Input package length. If 0 package length will be retrieved
550 * from the @p in_packaged
551 *
552 * @param[out] packaged Output package. If null only length of the output package
553 * is calculated.
554 *
555 * @param len Available space in the location pointed by @p packaged. Not used when
556 * @p packaged is null.
557 *
558 * @param flags Flags. See @ref CBPRINTF_PACKAGE_CONVERT_FLAGS.
559 *
560 * @param[in, out] strl if @p packaged is null, it is a pointer to the array where
561 * @p strl_len first string lengths will is stored. If @p packaged is not null,
562 * it contains lengths of first @p strl_len strings. It can be used to optimize
563 * copying so that string length is calculated only once (at length calculation
564 * phase when @p packaged is null.)
565 *
566 * @param strl_len Number of elements in @p strl array.
567 *
568 * @retval Positive Output package size.
569 * @retval -ENOSPC if @p packaged was not null and the space required to store
570 * exceed @p len.
571 */
cbprintf_package_copy(void * in_packaged,size_t in_len,void * packaged,size_t len,uint32_t flags,uint16_t * strl,size_t strl_len)572 static inline int cbprintf_package_copy(void *in_packaged,
573 size_t in_len,
574 void *packaged,
575 size_t len,
576 uint32_t flags,
577 uint16_t *strl,
578 size_t strl_len)
579 {
580 struct z_cbprintf_buf_desc buf_desc = {
581 .buf = packaged,
582 .size = len,
583 .off = 0,
584 };
585
586 return cbprintf_package_convert(in_packaged, in_len,
587 packaged ? z_cbprintf_cpy : NULL, &buf_desc,
588 flags, strl, strl_len);
589 }
590
591 /** @brief Convert package to fully self-contained (fsc) package.
592 *
593 * Package may not be self contain since strings by default are stored by address.
594 * Package may be partially self-contained when transient (not read only) strings
595 * are appended to the package. Such package can be decoded only when there is an
596 * access to read-only strings.
597 *
598 * Fully self-contained has (fsc) contains all strings used in the package. A package
599 * can be converted to fsc package if it was create with @ref CBPRINTF_PACKAGE_ADD_RO_STR_POS
600 * flag. Such package will contain necessary data to find read only strings in
601 * the package and copy them into the package body.
602 *
603 * @param in_packaged pointer to original package created with
604 * @ref CBPRINTF_PACKAGE_ADD_RO_STR_POS.
605 *
606 * @param in_len @p in_packaged length.
607 *
608 * @param packaged pointer to location where fully self-contained version of the
609 * input package will be written. Pass a null pointer to calculate space required.
610 *
611 * @param len must be set to the number of bytes available at @p packaged. Not
612 * used if @p packaged is null.
613 *
614 * @retval nonegative the number of bytes successfully stored at @p packaged.
615 * This will not exceed @p len. If @p packaged is null, calculated length.
616 * @retval -ENOSPC if @p packaged was not null and the space required to store
617 * exceed @p len.
618 * @retval -EINVAL if @p in_packaged is null.
619 */
cbprintf_fsc_package(void * in_packaged,size_t in_len,void * packaged,size_t len)620 static inline int cbprintf_fsc_package(void *in_packaged,
621 size_t in_len,
622 void *packaged,
623 size_t len)
624 {
625 return cbprintf_package_copy(in_packaged, in_len, packaged, len,
626 CBPRINTF_PACKAGE_CONVERT_RO_STR |
627 CBPRINTF_PACKAGE_CONVERT_RW_STR, NULL, 0);
628 }
629
630 /** @brief Generate the output for a previously captured format
631 * operation using an external formatter.
632 *
633 * @param out the function used to emit each generated character.
634 *
635 * @param formatter external formatter function.
636 *
637 * @param ctx a pointer to an object that provides context for the
638 * external formatter.
639 *
640 * @param packaged the data required to generate the formatted output, as
641 * captured by cbprintf_package() or cbvprintf_package(). The alignment
642 * requirement on this data is the same as when it was initially created.
643 *
644 * @note Memory indicated by @p packaged will be modified in a non-destructive
645 * way, meaning that it could still be reused with this function again.
646 *
647 * @return printf like return values: the number of characters printed,
648 * or a negative error value returned from external formatter.
649 */
650 int cbpprintf_external(cbprintf_cb out,
651 cbvprintf_external_formatter_func formatter,
652 void *ctx,
653 void *packaged);
654
655 /** @brief *printf-like output through a callback.
656 *
657 * This is essentially printf() except the output is generated
658 * character-by-character using the provided @p out function. This allows
659 * formatting text of unbounded length without incurring the cost of a
660 * temporary buffer.
661 *
662 * All formatting specifiers of C99 are recognized, and most are supported if
663 * the functionality is enabled.
664 *
665 * @note The functionality of this function is significantly reduced
666 * when @kconfig{CONFIG_CBPRINTF_NANO} is selected.
667 *
668 * @param out the function used to emit each generated character.
669 *
670 * @param ctx context provided when invoking out
671 *
672 * @param format a standard ISO C format string with characters and conversion
673 * specifications.
674 *
675 * @param ... arguments corresponding to the conversion specifications found
676 * within @p format.
677 *
678 * @return the number of characters printed, or a negative error value
679 * returned from invoking @p out.
680 */
681 __printf_like(3, 4)
682 int cbprintf(cbprintf_cb out, void *ctx, const char *format, ...);
683
684 /** @brief varargs-aware *printf-like output through a callback.
685 *
686 * This is essentially vsprintf() except the output is generated
687 * character-by-character using the provided @p out function. This allows
688 * formatting text of unbounded length without incurring the cost of a
689 * temporary buffer.
690 *
691 * @note This function is available only when
692 * @kconfig{CONFIG_CBPRINTF_LIBC_SUBSTS} is selected.
693 *
694 * @note The functionality of this function is significantly reduced when
695 * @kconfig{CONFIG_CBPRINTF_NANO} is selected.
696 *
697 * @param out the function used to emit each generated character.
698 *
699 * @param ctx context provided when invoking out
700 *
701 * @param format a standard ISO C format string with characters and conversion
702 * specifications.
703 *
704 * @param ap a reference to the values to be converted.
705 *
706 * @param flags flags on how to process the inputs.
707 * @see Z_CBVPRINTF_PROCESS_FLAGS.
708 *
709 * @return the number of characters generated, or a negative error value
710 * returned from invoking @p out.
711 */
712 int z_cbvprintf_impl(cbprintf_cb out, void *ctx, const char *format,
713 va_list ap, uint32_t flags);
714
715 /** @brief varargs-aware *printf-like output through a callback.
716 *
717 * This is essentially vsprintf() except the output is generated
718 * character-by-character using the provided @p out function. This allows
719 * formatting text of unbounded length without incurring the cost of a
720 * temporary buffer.
721 *
722 * @note This function is available only when
723 * @kconfig{CONFIG_CBPRINTF_LIBC_SUBSTS} is selected.
724 *
725 * @note The functionality of this function is significantly reduced when
726 * @kconfig{CONFIG_CBPRINTF_NANO} is selected.
727 *
728 * @param out the function used to emit each generated character.
729 *
730 * @param ctx context provided when invoking out
731 *
732 * @param format a standard ISO C format string with characters and conversion
733 * specifications.
734 *
735 * @param ap a reference to the values to be converted.
736 *
737 * @return the number of characters generated, or a negative error value
738 * returned from invoking @p out.
739 */
740 #ifdef CONFIG_PICOLIBC
741 int cbvprintf(cbprintf_cb out, void *ctx, const char *format, va_list ap);
742 #else
743 static inline
cbvprintf(cbprintf_cb out,void * ctx,const char * format,va_list ap)744 int cbvprintf(cbprintf_cb out, void *ctx, const char *format, va_list ap)
745 {
746 return z_cbvprintf_impl(out, ctx, format, ap, 0);
747 }
748 #endif
749
750 /** @brief varargs-aware *printf-like output through a callback with tagged arguments.
751 *
752 * This is essentially vsprintf() except the output is generated
753 * character-by-character using the provided @p out function. This allows
754 * formatting text of unbounded length without incurring the cost of a
755 * temporary buffer.
756 *
757 * Note that the argument list @p ap are tagged.
758 *
759 * @note This function is available only when
760 * @kconfig{CONFIG_CBPRINTF_LIBC_SUBSTS} is selected.
761 *
762 * @note The functionality of this function is significantly reduced when
763 * @kconfig{CONFIG_CBPRINTF_NANO} is selected.
764 *
765 * @param out the function used to emit each generated character.
766 *
767 * @param ctx context provided when invoking out
768 *
769 * @param format a standard ISO C format string with characters and conversion
770 * specifications.
771 *
772 * @param ap a reference to the values to be converted.
773 *
774 * @return the number of characters generated, or a negative error value
775 * returned from invoking @p out.
776 */
777 static inline
cbvprintf_tagged_args(cbprintf_cb out,void * ctx,const char * format,va_list ap)778 int cbvprintf_tagged_args(cbprintf_cb out, void *ctx,
779 const char *format, va_list ap)
780 {
781 return z_cbvprintf_impl(out, ctx, format, ap,
782 Z_CBVPRINTF_PROCESS_FLAG_TAGGED_ARGS);
783 }
784
785 /** @brief Generate the output for a previously captured format
786 * operation.
787 *
788 * @param out the function used to emit each generated character.
789 *
790 * @param ctx context provided when invoking out
791 *
792 * @param packaged the data required to generate the formatted output, as
793 * captured by cbprintf_package() or cbvprintf_package(). The alignment
794 * requirement on this data is the same as when it was initially created.
795 *
796 * @note Memory indicated by @p packaged will be modified in a non-destructive
797 * way, meaning that it could still be reused with this function again.
798 *
799 * @return the number of characters printed, or a negative error value
800 * returned from invoking @p out.
801 */
802 static inline
cbpprintf(cbprintf_cb out,void * ctx,void * packaged)803 int cbpprintf(cbprintf_cb out, void *ctx, void *packaged)
804 {
805 #if defined(CONFIG_CBPRINTF_PACKAGE_SUPPORT_TAGGED_ARGUMENTS)
806 union cbprintf_package_hdr *hdr =
807 (union cbprintf_package_hdr *)packaged;
808
809 if ((hdr->desc.pkg_flags & CBPRINTF_PACKAGE_ARGS_ARE_TAGGED)
810 == CBPRINTF_PACKAGE_ARGS_ARE_TAGGED) {
811 return cbpprintf_external(out, cbvprintf_tagged_args,
812 ctx, packaged);
813 }
814 #endif
815
816 return cbpprintf_external(out, cbvprintf, ctx, packaged);
817 }
818
819 #ifdef CONFIG_CBPRINTF_LIBC_SUBSTS
820
821 #ifdef CONFIG_PICOLIBC
822
823 #define fprintfcb(stream, ...) fprintf(stream, __VA_ARGS__)
824 #define vfprintfcb(stream, format, ap) vfprintf(stream, format, ap)
825 #define printfcb(format, ...) printf(format, __VA_ARGS__)
826 #define vprintfcb(format, ap) vprintf(format, ap)
827 #define snprintfcb(str, size, ...) snprintf(str, size, __VA_ARGS__)
828 #define vsnprintfcb(str, size, format, ap) vsnprintf(str, size, format, ap)
829
830 #else
831
832 /** @brief fprintf using Zephyrs cbprintf infrastructure.
833 *
834 * @note This function is available only when
835 * @kconfig{CONFIG_CBPRINTF_LIBC_SUBSTS} is selected.
836 *
837 * @note The functionality of this function is significantly reduced
838 * when @kconfig{CONFIG_CBPRINTF_NANO} is selected.
839 *
840 * @param stream the stream to which the output should be written.
841 *
842 * @param format a standard ISO C format string with characters and
843 * conversion specifications.
844 *
845 * @param ... arguments corresponding to the conversion specifications found
846 * within @p format.
847 *
848 * return The number of characters printed.
849 */
850 __printf_like(2, 3)
851 int fprintfcb(FILE * stream, const char *format, ...);
852
853 /** @brief vfprintf using Zephyrs cbprintf infrastructure.
854 *
855 * @note This function is available only when
856 * @kconfig{CONFIG_CBPRINTF_LIBC_SUBSTS} is selected.
857 *
858 * @note The functionality of this function is significantly reduced when
859 * @kconfig{CONFIG_CBPRINTF_NANO} is selected.
860 *
861 * @param stream the stream to which the output should be written.
862 *
863 * @param format a standard ISO C format string with characters and conversion
864 * specifications.
865 *
866 * @param ap a reference to the values to be converted.
867 *
868 * @return The number of characters printed.
869 */
870 int vfprintfcb(FILE *stream, const char *format, va_list ap);
871
872 /** @brief printf using Zephyrs cbprintf infrastructure.
873 *
874 * @note This function is available only when
875 * @kconfig{CONFIG_CBPRINTF_LIBC_SUBSTS} is selected.
876 *
877 * @note The functionality of this function is significantly reduced
878 * when @kconfig{CONFIG_CBPRINTF_NANO} is selected.
879 *
880 * @param format a standard ISO C format string with characters and
881 * conversion specifications.
882 *
883 * @param ... arguments corresponding to the conversion specifications found
884 * within @p format.
885 *
886 * @return The number of characters printed.
887 */
888 __printf_like(1, 2)
889 int printfcb(const char *format, ...);
890
891 /** @brief vprintf using Zephyrs cbprintf infrastructure.
892 *
893 * @note This function is available only when
894 * @kconfig{CONFIG_CBPRINTF_LIBC_SUBSTS} is selected.
895 *
896 * @note The functionality of this function is significantly reduced when
897 * @kconfig{CONFIG_CBPRINTF_NANO} is selected.
898 *
899 * @param format a standard ISO C format string with characters and conversion
900 * specifications.
901 *
902 * @param ap a reference to the values to be converted.
903 *
904 * @return The number of characters printed.
905 */
906 int vprintfcb(const char *format, va_list ap);
907
908 /** @brief snprintf using Zephyrs cbprintf infrastructure.
909 *
910 * @note This function is available only when
911 * @kconfig{CONFIG_CBPRINTF_LIBC_SUBSTS} is selected.
912 *
913 * @note The functionality of this function is significantly reduced
914 * when @kconfig{CONFIG_CBPRINTF_NANO} is selected.
915 *
916 * @param str where the formatted content should be written
917 *
918 * @param size maximum number of chaacters for the formatted output,
919 * including the terminating null byte.
920 *
921 * @param format a standard ISO C format string with characters and
922 * conversion specifications.
923 *
924 * @param ... arguments corresponding to the conversion specifications found
925 * within @p format.
926 *
927 * @return The number of characters that would have been written to @p
928 * str, excluding the terminating null byte. This is greater than the
929 * number actually written if @p size is too small.
930 */
931 __printf_like(3, 4)
932 int snprintfcb(char *str, size_t size, const char *format, ...);
933
934 /** @brief vsnprintf using Zephyrs cbprintf infrastructure.
935 *
936 * @note This function is available only when
937 * @kconfig{CONFIG_CBPRINTF_LIBC_SUBSTS} is selected.
938 *
939 * @note The functionality of this function is significantly reduced when
940 * @kconfig{CONFIG_CBPRINTF_NANO} is selected.
941 *
942 * @param str where the formatted content should be written
943 *
944 * @param size maximum number of chaacters for the formatted output, including
945 * the terminating null byte.
946 *
947 * @param format a standard ISO C format string with characters and conversion
948 * specifications.
949 *
950 * @param ap a reference to the values to be converted.
951 *
952 * @return The number of characters that would have been written to @p
953 * str, excluding the terminating null byte. This is greater than the
954 * number actually written if @p size is too small.
955 */
956 int vsnprintfcb(char *str, size_t size, const char *format, va_list ap);
957
958 #endif /* CONFIG_PICOLIBC */
959 #endif /* CONFIG_CBPRINTF_LIBC_SUBSTS */
960
961 /**
962 * @}
963 */
964
965 #ifdef __cplusplus
966 }
967 #endif
968
969 #endif /* ZEPHYR_INCLUDE_SYS_CBPRINTF_H_ */
970
