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 (len == 0) {
533 : return 0;
534 : }
535 :
536 : if ((desc->size - desc->off) < len) {
537 : return -ENOSPC;
538 : }
539 :
540 : memcpy(&((uint8_t *)desc->buf)[desc->off], buf, len);
541 : desc->off += len;
542 :
543 : return len;
544 : }
545 :
546 : /** @brief Copy package with optional appending of strings.
547 : *
548 : * @ref cbprintf_package_convert is used to convert and store converted package
549 : * in the new location.
550 : *
551 : * @param in_packaged Input package.
552 : *
553 : * @param in_len Input package length. If 0 package length will be retrieved
554 : * from the @p in_packaged
555 : *
556 : * @param[out] packaged Output package. If null only length of the output package
557 : * is calculated.
558 : *
559 : * @param len Available space in the location pointed by @p packaged. Not used when
560 : * @p packaged is null.
561 : *
562 : * @param flags Flags. See @ref CBPRINTF_PACKAGE_CONVERT_FLAGS.
563 : *
564 : * @param[in, out] strl if @p packaged is null, it is a pointer to the array where
565 : * @p strl_len first string lengths will is stored. If @p packaged is not null,
566 : * it contains lengths of first @p strl_len strings. It can be used to optimize
567 : * copying so that string length is calculated only once (at length calculation
568 : * phase when @p packaged is null.)
569 : *
570 : * @param strl_len Number of elements in @p strl array.
571 : *
572 : * @retval Positive Output package size.
573 : * @retval -ENOSPC if @p packaged was not null and the space required to store
574 : * exceed @p len.
575 : */
576 1 : static inline int cbprintf_package_copy(void *in_packaged,
577 : size_t in_len,
578 : void *packaged,
579 : size_t len,
580 : uint32_t flags,
581 : uint16_t *strl,
582 : size_t strl_len)
583 : {
584 : struct z_cbprintf_buf_desc buf_desc = {
585 : .buf = packaged,
586 : .size = len,
587 : .off = 0,
588 : };
589 :
590 : return cbprintf_package_convert(in_packaged, in_len,
591 : packaged ? z_cbprintf_cpy : NULL, &buf_desc,
592 : flags, strl, strl_len);
593 : }
594 :
595 : /** @brief Convert package to fully self-contained (fsc) package.
596 : *
597 : * Package may not be self contain since strings by default are stored by address.
598 : * Package may be partially self-contained when transient (not read only) strings
599 : * are appended to the package. Such package can be decoded only when there is an
600 : * access to read-only strings.
601 : *
602 : * Fully self-contained has (fsc) contains all strings used in the package. A package
603 : * can be converted to fsc package if it was create with @ref CBPRINTF_PACKAGE_ADD_RO_STR_POS
604 : * flag. Such package will contain necessary data to find read only strings in
605 : * the package and copy them into the package body.
606 : *
607 : * @param in_packaged pointer to original package created with
608 : * @ref CBPRINTF_PACKAGE_ADD_RO_STR_POS.
609 : *
610 : * @param in_len @p in_packaged length.
611 : *
612 : * @param packaged pointer to location where fully self-contained version of the
613 : * input package will be written. Pass a null pointer to calculate space required.
614 : *
615 : * @param len must be set to the number of bytes available at @p packaged. Not
616 : * used if @p packaged is null.
617 : *
618 : * @retval nonegative the number of bytes successfully stored at @p packaged.
619 : * This will not exceed @p len. If @p packaged is null, calculated length.
620 : * @retval -ENOSPC if @p packaged was not null and the space required to store
621 : * exceed @p len.
622 : * @retval -EINVAL if @p in_packaged is null.
623 : */
624 1 : static inline int cbprintf_fsc_package(void *in_packaged,
625 : size_t in_len,
626 : void *packaged,
627 : size_t len)
628 : {
629 : return cbprintf_package_copy(in_packaged, in_len, packaged, len,
630 : CBPRINTF_PACKAGE_CONVERT_RO_STR |
631 : CBPRINTF_PACKAGE_CONVERT_RW_STR, NULL, 0);
632 : }
633 :
634 : /** @brief Generate the output for a previously captured format
635 : * operation using an external formatter.
636 : *
637 : * @param out the function used to emit each generated character.
638 : *
639 : * @param formatter external formatter function.
640 : *
641 : * @param ctx a pointer to an object that provides context for the
642 : * external formatter.
643 : *
644 : * @param packaged the data required to generate the formatted output, as
645 : * captured by cbprintf_package() or cbvprintf_package(). The alignment
646 : * requirement on this data is the same as when it was initially created.
647 : *
648 : * @note Memory indicated by @p packaged will be modified in a non-destructive
649 : * way, meaning that it could still be reused with this function again.
650 : *
651 : * @return printf like return values: the number of characters printed,
652 : * or a negative error value returned from external formatter.
653 : */
654 1 : int cbpprintf_external(cbprintf_cb out,
655 : cbvprintf_external_formatter_func formatter,
656 : void *ctx,
657 : void *packaged);
658 :
659 : /** @brief *printf-like output through a callback.
660 : *
661 : * This is essentially printf() except the output is generated
662 : * character-by-character using the provided @p out function. This allows
663 : * formatting text of unbounded length without incurring the cost of a
664 : * temporary buffer.
665 : *
666 : * All formatting specifiers of C99 are recognized, and most are supported if
667 : * the functionality is enabled.
668 : *
669 : * @note The functionality of this function is significantly reduced
670 : * when @kconfig{CONFIG_CBPRINTF_NANO} is selected.
671 : *
672 : * @param out the function used to emit each generated character.
673 : *
674 : * @param ctx context provided when invoking out
675 : *
676 : * @param format a standard ISO C format string with characters and conversion
677 : * specifications.
678 : *
679 : * @param ... arguments corresponding to the conversion specifications found
680 : * within @p format.
681 : *
682 : * @return the number of characters printed, or a negative error value
683 : * returned from invoking @p out.
684 : */
685 : __printf_like(3, 4)
686 1 : int cbprintf(cbprintf_cb out, void *ctx, const char *format, ...);
687 :
688 : /** @brief varargs-aware *printf-like output through a callback.
689 : *
690 : * This is essentially vsprintf() except the output is generated
691 : * character-by-character using the provided @p out function. This allows
692 : * formatting text of unbounded length without incurring the cost of a
693 : * temporary buffer.
694 : *
695 : * @note This function is available only when
696 : * @kconfig{CONFIG_CBPRINTF_LIBC_SUBSTS} is selected.
697 : *
698 : * @note The functionality of this function is significantly reduced when
699 : * @kconfig{CONFIG_CBPRINTF_NANO} is selected.
700 : *
701 : * @param out the function used to emit each generated character.
702 : *
703 : * @param ctx context provided when invoking out
704 : *
705 : * @param format a standard ISO C format string with characters and conversion
706 : * specifications.
707 : *
708 : * @param ap a reference to the values to be converted.
709 : *
710 : * @param flags flags on how to process the inputs.
711 : * @see Z_CBVPRINTF_PROCESS_FLAGS.
712 : *
713 : * @return the number of characters generated, or a negative error value
714 : * returned from invoking @p out.
715 : */
716 : int z_cbvprintf_impl(cbprintf_cb out, void *ctx, const char *format,
717 : va_list ap, uint32_t flags);
718 :
719 : /** @brief varargs-aware *printf-like output through a callback.
720 : *
721 : * This is essentially vsprintf() except the output is generated
722 : * character-by-character using the provided @p out function. This allows
723 : * formatting text of unbounded length without incurring the cost of a
724 : * temporary buffer.
725 : *
726 : * @note This function is available only when
727 : * @kconfig{CONFIG_CBPRINTF_LIBC_SUBSTS} is selected.
728 : *
729 : * @note The functionality of this function is significantly reduced when
730 : * @kconfig{CONFIG_CBPRINTF_NANO} is selected.
731 : *
732 : * @param out the function used to emit each generated character.
733 : *
734 : * @param ctx context provided when invoking out
735 : *
736 : * @param format a standard ISO C format string with characters and conversion
737 : * specifications.
738 : *
739 : * @param ap a reference to the values to be converted.
740 : *
741 : * @return the number of characters generated, or a negative error value
742 : * returned from invoking @p out.
743 : */
744 : #ifdef CONFIG_PICOLIBC
745 : int cbvprintf(cbprintf_cb out, void *ctx, const char *format, va_list ap);
746 : #else
747 : static inline
748 1 : int cbvprintf(cbprintf_cb out, void *ctx, const char *format, va_list ap)
749 : {
750 : return z_cbvprintf_impl(out, ctx, format, ap, 0);
751 : }
752 : #endif
753 :
754 : /** @brief varargs-aware *printf-like output through a callback with tagged arguments.
755 : *
756 : * This is essentially vsprintf() except the output is generated
757 : * character-by-character using the provided @p out function. This allows
758 : * formatting text of unbounded length without incurring the cost of a
759 : * temporary buffer.
760 : *
761 : * Note that the argument list @p ap are tagged.
762 : *
763 : * @note This function is available only when
764 : * @kconfig{CONFIG_CBPRINTF_LIBC_SUBSTS} is selected.
765 : *
766 : * @note The functionality of this function is significantly reduced when
767 : * @kconfig{CONFIG_CBPRINTF_NANO} is selected.
768 : *
769 : * @param out the function used to emit each generated character.
770 : *
771 : * @param ctx context provided when invoking out
772 : *
773 : * @param format a standard ISO C format string with characters and conversion
774 : * specifications.
775 : *
776 : * @param ap a reference to the values to be converted.
777 : *
778 : * @return the number of characters generated, or a negative error value
779 : * returned from invoking @p out.
780 : */
781 : static inline
782 1 : int cbvprintf_tagged_args(cbprintf_cb out, void *ctx,
783 : const char *format, va_list ap)
784 : {
785 : return z_cbvprintf_impl(out, ctx, format, ap,
786 : Z_CBVPRINTF_PROCESS_FLAG_TAGGED_ARGS);
787 : }
788 :
789 : /** @brief Generate the output for a previously captured format
790 : * operation.
791 : *
792 : * @param out the function used to emit each generated character.
793 : *
794 : * @param ctx context provided when invoking out
795 : *
796 : * @param packaged the data required to generate the formatted output, as
797 : * captured by cbprintf_package() or cbvprintf_package(). The alignment
798 : * requirement on this data is the same as when it was initially created.
799 : *
800 : * @note Memory indicated by @p packaged will be modified in a non-destructive
801 : * way, meaning that it could still be reused with this function again.
802 : *
803 : * @return the number of characters printed, or a negative error value
804 : * returned from invoking @p out.
805 : */
806 : static inline
807 1 : int cbpprintf(cbprintf_cb out, void *ctx, void *packaged)
808 : {
809 : #if defined(CONFIG_CBPRINTF_PACKAGE_SUPPORT_TAGGED_ARGUMENTS)
810 : union cbprintf_package_hdr *hdr =
811 : (union cbprintf_package_hdr *)packaged;
812 :
813 : if ((hdr->desc.pkg_flags & CBPRINTF_PACKAGE_ARGS_ARE_TAGGED)
814 : == CBPRINTF_PACKAGE_ARGS_ARE_TAGGED) {
815 : return cbpprintf_external(out, cbvprintf_tagged_args,
816 : ctx, packaged);
817 : }
818 : #endif
819 :
820 : return cbpprintf_external(out, cbvprintf, ctx, packaged);
821 : }
822 :
823 : #ifdef CONFIG_CBPRINTF_LIBC_SUBSTS
824 :
825 : #ifdef CONFIG_PICOLIBC
826 :
827 : #define fprintfcb(stream, ...) fprintf(stream, __VA_ARGS__)
828 : #define vfprintfcb(stream, format, ap) vfprintf(stream, format, ap)
829 : #define printfcb(format, ...) printf(format, __VA_ARGS__)
830 : #define vprintfcb(format, ap) vprintf(format, ap)
831 : #define snprintfcb(str, size, ...) snprintf(str, size, __VA_ARGS__)
832 : #define vsnprintfcb(str, size, format, ap) vsnprintf(str, size, format, ap)
833 :
834 : #else
835 :
836 : /** @brief fprintf using Zephyrs cbprintf infrastructure.
837 : *
838 : * @note This function is available only when
839 : * @kconfig{CONFIG_CBPRINTF_LIBC_SUBSTS} is selected.
840 : *
841 : * @note The functionality of this function is significantly reduced
842 : * when @kconfig{CONFIG_CBPRINTF_NANO} is selected.
843 : *
844 : * @param stream the stream to which the output should be written.
845 : *
846 : * @param format a standard ISO C format string with characters and
847 : * conversion specifications.
848 : *
849 : * @param ... arguments corresponding to the conversion specifications found
850 : * within @p format.
851 : *
852 : * return The number of characters printed.
853 : */
854 : __printf_like(2, 3)
855 1 : int fprintfcb(FILE * stream, const char *format, ...);
856 :
857 : /** @brief vfprintf using Zephyrs cbprintf infrastructure.
858 : *
859 : * @note This function is available only when
860 : * @kconfig{CONFIG_CBPRINTF_LIBC_SUBSTS} is selected.
861 : *
862 : * @note The functionality of this function is significantly reduced when
863 : * @kconfig{CONFIG_CBPRINTF_NANO} is selected.
864 : *
865 : * @param stream the stream to which the output should be written.
866 : *
867 : * @param format a standard ISO C format string with characters and conversion
868 : * specifications.
869 : *
870 : * @param ap a reference to the values to be converted.
871 : *
872 : * @return The number of characters printed.
873 : */
874 1 : int vfprintfcb(FILE *stream, const char *format, va_list ap);
875 :
876 : /** @brief printf using Zephyrs cbprintf infrastructure.
877 : *
878 : * @note This function is available only when
879 : * @kconfig{CONFIG_CBPRINTF_LIBC_SUBSTS} is selected.
880 : *
881 : * @note The functionality of this function is significantly reduced
882 : * when @kconfig{CONFIG_CBPRINTF_NANO} is selected.
883 : *
884 : * @param format a standard ISO C format string with characters and
885 : * conversion specifications.
886 : *
887 : * @param ... arguments corresponding to the conversion specifications found
888 : * within @p format.
889 : *
890 : * @return The number of characters printed.
891 : */
892 : __printf_like(1, 2)
893 1 : int printfcb(const char *format, ...);
894 :
895 : /** @brief vprintf using Zephyrs cbprintf infrastructure.
896 : *
897 : * @note This function is available only when
898 : * @kconfig{CONFIG_CBPRINTF_LIBC_SUBSTS} is selected.
899 : *
900 : * @note The functionality of this function is significantly reduced when
901 : * @kconfig{CONFIG_CBPRINTF_NANO} is selected.
902 : *
903 : * @param format a standard ISO C format string with characters and conversion
904 : * specifications.
905 : *
906 : * @param ap a reference to the values to be converted.
907 : *
908 : * @return The number of characters printed.
909 : */
910 1 : int vprintfcb(const char *format, va_list ap);
911 :
912 : /** @brief snprintf using Zephyrs cbprintf infrastructure.
913 : *
914 : * @note This function is available only when
915 : * @kconfig{CONFIG_CBPRINTF_LIBC_SUBSTS} is selected.
916 : *
917 : * @note The functionality of this function is significantly reduced
918 : * when @kconfig{CONFIG_CBPRINTF_NANO} is selected.
919 : *
920 : * @param str where the formatted content should be written
921 : *
922 : * @param size maximum number of chaacters for the formatted output,
923 : * including the terminating null byte.
924 : *
925 : * @param format a standard ISO C format string with characters and
926 : * conversion specifications.
927 : *
928 : * @param ... arguments corresponding to the conversion specifications found
929 : * within @p format.
930 : *
931 : * @return The number of characters that would have been written to @p
932 : * str, excluding the terminating null byte. This is greater than the
933 : * number actually written if @p size is too small.
934 : */
935 : __printf_like(3, 4)
936 1 : int snprintfcb(char *str, size_t size, const char *format, ...);
937 :
938 : /** @brief vsnprintf using Zephyrs cbprintf infrastructure.
939 : *
940 : * @note This function is available only when
941 : * @kconfig{CONFIG_CBPRINTF_LIBC_SUBSTS} is selected.
942 : *
943 : * @note The functionality of this function is significantly reduced when
944 : * @kconfig{CONFIG_CBPRINTF_NANO} is selected.
945 : *
946 : * @param str where the formatted content should be written
947 : *
948 : * @param size maximum number of chaacters for the formatted output, including
949 : * the terminating null byte.
950 : *
951 : * @param format a standard ISO C format string with characters and conversion
952 : * specifications.
953 : *
954 : * @param ap a reference to the values to be converted.
955 : *
956 : * @return The number of characters that would have been written to @p
957 : * str, excluding the terminating null byte. This is greater than the
958 : * number actually written if @p size is too small.
959 : */
960 1 : int vsnprintfcb(char *str, size_t size, const char *format, va_list ap);
961 :
962 : #endif /* CONFIG_PICOLIBC */
963 : #endif /* CONFIG_CBPRINTF_LIBC_SUBSTS */
964 :
965 : /**
966 : * @}
967 : */
968 :
969 : #ifdef __cplusplus
970 : }
971 : #endif
972 :
973 : #endif /* ZEPHYR_INCLUDE_SYS_CBPRINTF_H_ */
|
