Line data Source code
1 0 : /*
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 1 : struct cbprintf_package_desc {
46 : /** Package length (in 32 bit words) */
47 1 : uint8_t len;
48 :
49 : /** Number of appended strings in the package. */
50 1 : uint8_t str_cnt;
51 :
52 : /** Number of read-only strings, indexes appended to the package */
53 1 : uint8_t ro_str_cnt;
54 :
55 : /** Number of read-write strings, indexes appended to the package */
56 1 : 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 1 : union cbprintf_package_hdr {
79 : /** Header description */
80 1 : struct cbprintf_package_desc desc;
81 :
82 0 : 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 1 : struct cbprintf_package_hdr_ext {
97 : /** Header of package */
98 1 : union cbprintf_package_hdr hdr;
99 :
100 : /** Pointer to format string */
101 1 : 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 1 : #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 1 : #define CBPRINTF_PACKAGE_CONST_CHAR_RO BIT(0)
157 :
158 : /** @brief Append locations (within the package) of read-only string pointers. */
159 1 : #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 1 : #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 1 : #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 1 : #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 1 : #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 1 : #define CBPRINTF_PACKAGE_CONVERT_RO_STR BIT(0)
219 :
220 : /** @brief Append read-write strings from source package to destination package.
221 : *
222 : * If package was created with @ref CBPRINTF_PACKAGE_ADD_RW_STR_POS it contains
223 : * arrays of indexes where string address can be found in the package. When flag
224 : * is set, list of read-write strings is examined and if they are not determined
225 : * to be read-only, they are copied into the destination package.
226 : * If @ref CBPRINTF_PACKAGE_CONVERT_RO_STR is not set, remaining string locations
227 : * are considered as pointing to read-only location and they are copy to the
228 : * package if @ref CBPRINTF_PACKAGE_CONVERT_KEEP_RO_STR is set.
229 : */
230 1 : #define CBPRINTF_PACKAGE_CONVERT_RW_STR BIT(1)
231 :
232 : /** @brief Keep read-only location indexes in the package.
233 : *
234 : * If it is set read-only string pointers are kept in the package after copy. If
235 : * not set they are discarded.
236 : */
237 1 : #define CBPRINTF_PACKAGE_CONVERT_KEEP_RO_STR BIT(2)
238 :
239 : /** @brief Check format string if %p argument was treated as %s in the package.
240 : *
241 : * Static packaging is done based only on types of arguments used for a format
242 : * string. Without looking into format specifiers present in the string. Because
243 : * of that if (unsigned) char pointer is used for %p it will be considered as
244 : * a string location and during conversion an attempt to append a string to a
245 : * package may be performed. This can lead to misbehavior, in the best case
246 : * package will be bigger and in the worst case memory fault or security violation
247 : * may occur.
248 : *
249 : * When this flag is set, format string will be checked to detect cases when
250 : * string candidate is a pointer used for %p and string appending from unexpected
251 : * location is avoided. Additionally, an log warning is generated to encourage
252 : * user to cast such argument to void *. It is recommended because there are
253 : * configurations where string is not accessible and inspection cannot be done.
254 : * In those cases there are no means to detect such cases.
255 : */
256 1 : #define CBPRINTF_PACKAGE_CONVERT_PTR_CHECK BIT(3)
257 :
258 : /**@} */
259 :
260 : /**
261 : * @defgroup Z_CBVPRINTF_PROCESS_FLAGS cbvprintf processing flags.
262 : * @{
263 : */
264 :
265 : /** @brief Indicates the arguments are tagged.
266 : *
267 : * This tells z_cbvprintf_impl() that the incoming arguments are
268 : * tagged, and should be processed accordingly.
269 : */
270 : #define Z_CBVPRINTF_PROCESS_FLAG_TAGGED_ARGS BIT(0)
271 :
272 : /**@} */
273 :
274 : #include <zephyr/sys/cbprintf_enums.h>
275 :
276 : /** @brief Signature for a cbprintf callback function.
277 : *
278 : * This function expects two parameters:
279 : *
280 : * * @p c a character to output. The output behavior should be as if
281 : * this was cast to an unsigned char.
282 : * * @p ctx a pointer to an object that provides context for the
283 : * output operation.
284 : *
285 : * The declaration does not specify the parameter types. This allows a
286 : * function like @c fputc to be used without requiring all context pointers to
287 : * be to a @c FILE object.
288 : *
289 : * @return the value of @p c cast to an unsigned char then back to
290 : * int, or a negative error code that will be returned from
291 : * cbprintf().
292 : */
293 : #ifdef __CHECKER__
294 : typedef int (*cbprintf_cb)(int c, void *ctx);
295 : #else
296 1 : typedef int (*cbprintf_cb)(/* int c, void *ctx */);
297 : #endif
298 :
299 : /* Create local cbprintf_cb type to make calng-based compilers happy when handles
300 : * OUTC() macro (see below). With strict rules (Wincompatible-function-pointer-types-strict)
301 : * it's prohibited to pass arguments with mismatched types.
302 : */
303 0 : typedef int (*cbprintf_cb_local)(int c, void *ctx);
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 1 : 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 1 : 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 1 : #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 1 : ... /* 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 1 : 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 1 : 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 1 : 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 : /* @internal 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. */
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 : */
572 1 : 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 : */
620 1 : 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 1 : 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 1 : 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
744 1 : 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
778 1 : 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
803 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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_ */
|
