cbprintf.h

Go to the documentation of this file.

/*
 * Copyright (c) 2020 Nordic Semiconductor ASA
 *
 * SPDX-License-Identifier: Apache-2.0
 */
 
#ifndef ZEPHYR_INCLUDE_SYS_CBPRINTF_H_
#define ZEPHYR_INCLUDE_SYS_CBPRINTF_H_
 
#include <stdarg.h>
#include <stddef.h>
#include <stdint.h>
#include <zephyr/toolchain.h>
#include <string.h>
 
#ifdef CONFIG_CBPRINTF_LIBC_SUBSTS
#include <stdio.h>
#endif /* CONFIG_CBPRINTF_LIBC_SUBSTS */
 
/* Determine if _Generic is supported using macro from toolchain.h.
 *
 * @note Z_C_GENERIC is also set for C++ where functionality is implemented
 * using overloading and templates.
 */
#ifndef Z_C_GENERIC
#if defined(__cplusplus) || TOOLCHAIN_HAS_C_GENERIC
#define Z_C_GENERIC 1
#else
#define Z_C_GENERIC 0
#endif
#endif
 
#ifdef __xtensa__
#define Z_PKG_HDR_EXT_XTENSA_ALIGNMENT 8
#ifdef CONFIG_CBPRINTF_PACKAGE_HEADER_STORE_CREATION_FLAGS
#define Z_PKG_DESC_XTENSA_PADDING 1
#else
#define Z_PKG_DESC_XTENSA_PADDING 0
#endif
#endif /* __xtensa__ */
 
struct cbprintf_package_desc {
        uint8_t len;
 
        uint8_t str_cnt;
 
        uint8_t ro_str_cnt;
 
        uint8_t rw_str_cnt;
 
#ifdef CONFIG_CBPRINTF_PACKAGE_HEADER_STORE_CREATION_FLAGS
        uint32_t pkg_flags;
#endif
#ifdef __xtensa__
        /*
         * On Xtensa, the first argument needs to be aligned to 8-byte.
         * With 32-bit pointers, we need another 4 bytes padding so
         * that whole struct cbprintf_package_hdr_ext is of multiple of
         * 8 bytes.
         */
        uint32_t xtensa_padding[Z_PKG_DESC_XTENSA_PADDING];
#endif
 
} __packed;
 
union cbprintf_package_hdr {
        struct cbprintf_package_desc desc;
 
        void *raw;
 
#if defined(CONFIG_CBPRINTF_PACKAGE_HEADER_STORE_CREATION_FLAGS) && !defined(CONFIG_64BIT)
        void *raw2[2];
#endif
 
} __packed;
 
 
 
struct cbprintf_package_hdr_ext {
        union cbprintf_package_hdr hdr;
 
        char *fmt;
 
        /*
         * When extending this struct, make sure this align
         * to pointer size.
         */
} __packed;
 
 
#ifdef __xtensa__
BUILD_ASSERT(sizeof(struct cbprintf_package_hdr_ext) % Z_PKG_HDR_EXT_XTENSA_ALIGNMENT == 0,
             "Package header size on Xtensa must be aligned");
#endif
/* Z_C_GENERIC is used there */
#include <zephyr/sys/cbprintf_internal.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
#ifdef __xtensa__
#define CBPRINTF_PACKAGE_ALIGNMENT 16
#else
#define CBPRINTF_PACKAGE_ALIGNMENT \
        Z_POW2_CEIL(COND_CODE_1(CONFIG_CBPRINTF_PACKAGE_LONGDOUBLE, \
                (sizeof(long double)), (MAX(sizeof(double), sizeof(long long)))))
#endif
 
BUILD_ASSERT(Z_IS_POW2(CBPRINTF_PACKAGE_ALIGNMENT));
 
 
#define CBPRINTF_PACKAGE_CONST_CHAR_RO BIT(0)
 
#define CBPRINTF_PACKAGE_ADD_RO_STR_POS BIT(1)
 
#define CBPRINTF_PACKAGE_ADD_RW_STR_POS BIT(2)
 
#define Z_CBPRINTF_PACKAGE_FIRST_RO_STR_BITS 3
#define Z_CBPRINTF_PACKAGE_FIRST_RO_STR_OFFSET 3
#define Z_CBPRINTF_PACKAGE_FIRST_RO_STR_MASK BIT_MASK(Z_CBPRINTF_PACKAGE_FIRST_RO_STR_BITS)
 
#define CBPRINTF_PACKAGE_FIRST_RO_STR_CNT(n) \
        (n << Z_CBPRINTF_PACKAGE_FIRST_RO_STR_OFFSET)
 
#define Z_CBPRINTF_PACKAGE_FIRST_RO_STR_CNT_GET(flags) \
        (((flags) >> Z_CBPRINTF_PACKAGE_FIRST_RO_STR_OFFSET) & Z_CBPRINTF_PACKAGE_FIRST_RO_STR_MASK)
 
#define CBPRINTF_PACKAGE_ADD_STRING_IDXS \
        (CBPRINTF_PACKAGE_ADD_RO_STR_POS | CBPRINTF_PACKAGE_CONST_CHAR_RO)
 
#define CBPRINTF_PACKAGE_ARGS_ARE_TAGGED BIT(6)
 
#define CBPRINTF_PACKAGE_CONVERT_RO_STR BIT(0)
#define CBPRINTF_PACKAGE_COPY_RO_STR CBPRINTF_PACKAGE_CONVERT_RO_STR __DEPRECATED_MACRO
 
#define CBPRINTF_PACKAGE_CONVERT_RW_STR BIT(1)
#define CBPRINTF_PACKAGE_COPY_RW_STR CBPRINTF_PACKAGE_CONVERT_RW_STR __DEPRECATED_MACRO
 
#define CBPRINTF_PACKAGE_CONVERT_KEEP_RO_STR BIT(2)
#define CBPRINTF_PACKAGE_COPY_KEEP_RO_STR CBPRINTF_PACKAGE_CONVERT_KEEP_RO_STR __DEPRECATED_MACRO
 
#define CBPRINTF_PACKAGE_CONVERT_PTR_CHECK BIT(3)
 
#define Z_CBVPRINTF_PROCESS_FLAG_TAGGED_ARGS BIT(0)
 
#include <zephyr/sys/cbprintf_enums.h>
 
#ifdef __CHECKER__
typedef int (*cbprintf_cb)(int c, void *ctx);
#else
typedef int (*cbprintf_cb)(/* int c, void *ctx */);
#endif
 
/* Create local cbprintf_cb type to make calng-based compilers happy when handles
 * OUTC() macro (see below). With strict rules (Wincompatible-function-pointer-types-strict)
 * it's prohibited to pass arguments with mismatched types.
 */
typedef int (*cbprintf_cb_local)(int c, void *ctx);
 
typedef int (*cbprintf_convert_cb)(const void *buf, size_t len, void *ctx);
 
typedef int (*cbvprintf_external_formatter_func)(cbprintf_cb out, void *ctx,
                                                 const char *fmt, va_list ap);
 
#define CBPRINTF_MUST_RUNTIME_PACKAGE(flags, ... /* fmt, ... */) \
        Z_CBPRINTF_MUST_RUNTIME_PACKAGE(flags, __VA_ARGS__)
 
#define CBPRINTF_STATIC_PACKAGE(packaged, inlen, outlen, align_offset, flags, \
                                ... /* fmt, ... */) \
        Z_CBPRINTF_STATIC_PACKAGE(packaged, inlen, outlen, \
                                  align_offset, flags, __VA_ARGS__)
 
__printf_like(4, 5)
int cbprintf_package(void *packaged,
                     size_t len,
                     uint32_t flags,
                     const char *format,
                     ...);
 
int cbvprintf_package(void *packaged,
                      size_t len,
                      uint32_t flags,
                      const char *format,
                      va_list ap);
 
int cbprintf_package_convert(void *in_packaged,
                             size_t in_len,
                             cbprintf_convert_cb cb,
                             void *ctx,
                             uint32_t flags,
                             uint16_t *strl,
                             size_t strl_len);
 
/* @internal Context used for package copying. */
struct z_cbprintf_buf_desc {
        void *buf;
        size_t size;
        size_t off;
};
 
/* @internal Function callback used for package copying. */
static inline int z_cbprintf_cpy(const void *buf, size_t len, void *ctx)
{
        struct z_cbprintf_buf_desc *desc = (struct z_cbprintf_buf_desc *)ctx;
 
        if ((desc->size - desc->off) < len) {
                return -ENOSPC;
        }
 
        memcpy(&((uint8_t *)desc->buf)[desc->off], buf, len);
        desc->off += len;
 
        return len;
}
 
static inline int 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)
{
        struct z_cbprintf_buf_desc buf_desc = {
                .buf = packaged,
                .size = len,
                .off = 0,
        };
 
        return cbprintf_package_convert(in_packaged, in_len,
                                        packaged ? z_cbprintf_cpy : NULL, &buf_desc,
                                        flags, strl, strl_len);
}
 
static inline int cbprintf_fsc_package(void *in_packaged,
                                       size_t in_len,
                                       void *packaged,
                                       size_t len)
{
        return cbprintf_package_copy(in_packaged, in_len, packaged, len,
                                     CBPRINTF_PACKAGE_CONVERT_RO_STR |
                                     CBPRINTF_PACKAGE_CONVERT_RW_STR, NULL, 0);
}
 
int cbpprintf_external(cbprintf_cb out,
                       cbvprintf_external_formatter_func formatter,
                       void *ctx,
                       void *packaged);
 
__printf_like(3, 4)
int cbprintf(cbprintf_cb out, void *ctx, const char *format, ...);
 
int z_cbvprintf_impl(cbprintf_cb out, void *ctx, const char *format,
                     va_list ap, uint32_t flags);
 
#ifdef CONFIG_PICOLIBC
int cbvprintf(cbprintf_cb out, void *ctx, const char *format, va_list ap);
#else
static inline
int cbvprintf(cbprintf_cb out, void *ctx, const char *format, va_list ap)
{
        return z_cbvprintf_impl(out, ctx, format, ap, 0);
}
#endif
 
static inline
int cbvprintf_tagged_args(cbprintf_cb out, void *ctx,
                          const char *format, va_list ap)
{
        return z_cbvprintf_impl(out, ctx, format, ap,
                                Z_CBVPRINTF_PROCESS_FLAG_TAGGED_ARGS);
}
 
static inline
int cbpprintf(cbprintf_cb out, void *ctx, void *packaged)
{
#if defined(CONFIG_CBPRINTF_PACKAGE_SUPPORT_TAGGED_ARGUMENTS)
        union cbprintf_package_hdr *hdr =
                (union cbprintf_package_hdr *)packaged;
 
        if ((hdr->desc.pkg_flags & CBPRINTF_PACKAGE_ARGS_ARE_TAGGED)
            == CBPRINTF_PACKAGE_ARGS_ARE_TAGGED) {
                return cbpprintf_external(out, cbvprintf_tagged_args,
                                          ctx, packaged);
        }
#endif
 
        return cbpprintf_external(out, cbvprintf, ctx, packaged);
}
 
#ifdef CONFIG_CBPRINTF_LIBC_SUBSTS
 
#ifdef CONFIG_PICOLIBC
 
#define fprintfcb(stream, ...) fprintf(stream, __VA_ARGS__)
#define vfprintfcb(stream, format, ap) vfprintf(stream, format, ap)
#define printfcb(format, ...) printf(format, __VA_ARGS__)
#define vprintfcb(format, ap) vprintf(format, ap)
#define snprintfcb(str, size, ...) snprintf(str, size, __VA_ARGS__)
#define vsnprintfcb(str, size, format, ap) vsnprintf(str, size, format, ap)
 
#else
 
__printf_like(2, 3)
int fprintfcb(FILE * stream, const char *format, ...);
 
int vfprintfcb(FILE *stream, const char *format, va_list ap);
 
__printf_like(1, 2)
int printfcb(const char *format, ...);
 
int vprintfcb(const char *format, va_list ap);
 
__printf_like(3, 4)
int snprintfcb(char *str, size_t size, const char *format, ...);
 
int vsnprintfcb(char *str, size_t size, const char *format, va_list ap);
 
#endif /* CONFIG_PICOLIBC */
#endif /* CONFIG_CBPRINTF_LIBC_SUBSTS */
 
#ifdef __cplusplus
}
#endif
 
#endif /* ZEPHYR_INCLUDE_SYS_CBPRINTF_H_ */