Log.h

Go to the documentation of this file.

/*
 * Copyright (c) 2019-2025 Texas Instruments Incorporated - http://www.ti.com
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * *  Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 *
 * *  Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 *
 * *  Neither the name of Texas Instruments Incorporated nor the names of
 *    its contributors may be used to endorse or promote products derived
 *    from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */

#ifndef ti_log_Log__include
#define ti_log_Log__include


#include <stdint.h>
#include <stddef.h>

#if defined (__cplusplus)
extern "C" {
#endif

/*
 *  ======== ti_log_Log_ENABLE ========
 *  Enable instrumentation using link-time optimization implementation
 *
 *  Define this symbol to add instrumentation at compile time.
 *  It must be defined before including this header file.
 */

#if defined(DOXYGEN) || ti_log_Log_ENABLE
/*
 *  =============================
 *  ======== Log Enabled ========
 *  =============================
 */

#define Log_TI_LOG_VERSION 0.2.0

#define Log_MODULE_DEFINE(name, init) const Log_Module LogMod_ ## name = init

#if defined(DOXYGEN) || defined(__IAR_SYSTEMS_ICC__)
#define Log_MODULE_DEFINE_WEAK(name, init) const __weak Log_Module LogMod_ ## name = init
#elif defined(__TI_COMPILER_VERSION__) || (defined(__clang__) && defined(__ti_version__)) || defined(__GNUC__)
#define Log_MODULE_DEFINE_WEAK(name, init) const Log_Module LogMod_ ## name __attribute__((weak)) = init
#else
#error "Incompatible compiler: Logging is currently supported by the following \
compilers: TI ARM Compiler, TI CLANG Compiler, GCC, IAR. Please migrate to a \
supported compiler."
#endif

#define Log_MODULE_USE(name) extern const Log_Module LogMod_ ## name

#define LOG_MODULE_SYM(name) LogMod_ ## name

/* This macro protects against side effects of the C preprocessor expansion
 * of log statements. Each log API should be guarded by it.
 * An article explaining this behavior can be found here:
 * https://gcc.gnu.org/onlinedocs/cpp/Swallowing-the-Semicolon.html
 */
#define _Log_GUARD_MACRO(x) do{ x }while(0)

/*
 *
 *  ======== Log Private Macros ========
 *
 *  The following macros are intended to be private to the log module and
 *  are not intended for use by the user. Private macros will start with _Log.
 *
 *  In the case of multi level macros (macros that invoke other macros), a
 *  letter is appended at the end of the definition. With each level of nesting,
 *  the appended letter is incremented.
 *
 *  For example: _Log_test --> _Log_test_A --> _Log_test_B
 */
/* Extracts the first/remaining argument from __VA_ARGS__ */
#define _Log_CAR_ARG(N, ...) N
#define _Log_CDR_ARG(N, ...) __VA_ARGS__


/*
 *  ======== Meta string tokenization macros ========
 */
/*  Helper macro to concatenate two symbols */
#define _Log_CONCAT2_A(x,y) x ## _ ## y
#define _Log_CONCAT2(x,y) _Log_CONCAT2_A(x,y)
#define _Log_CONCAT3(x,y,z) _Log_CONCAT2(x,_Log_CONCAT2(y,z))

/*  Helper macro to concatenate two symbols */
#define _Log__TOKEN2STRING_A(x) #x
#define _Log_TOKEN2STRING(x) _Log__TOKEN2STRING_A(x)

/* Macro to place meta string in a memory section separated by record separator */
#define _Log_APPEND_META_TO_FORMAT(opcode,                                     \
                                    file,                                      \
                                    line,                                      \
                                    level,                                     \
                                    module,                                    \
                                    format,                                    \
                                    nargs)                                     \
                                    _Log_TOKEN2STRING(opcode)     "\x1e"       \
                                    _Log_TOKEN2STRING(file)       "\x1e"       \
                                    _Log_TOKEN2STRING(line)       "\x1e"       \
                                    _Log_TOKEN2STRING(level)      "\x1e"       \
                                    _Log_TOKEN2STRING(module)     "\x1e"       \
                                    _Log_TOKEN2STRING(format)     "\x1e"       \
                                    _Log_TOKEN2STRING(nargs)

/* Place a string in trace format section named ".log_data" locally
 * This section must exist in the linker file
 */
#if defined(__IAR_SYSTEMS_ICC__)
#define _Log_PLACE_FORMAT_IN_SECTOR(name, opcode, level, module, format, nargs)\
            __root static const char name[] @ ".log_data" =                    \
            _Log_APPEND_META_TO_FORMAT(opcode,                                 \
                                       __FILE__,                               \
                                       __LINE__,                               \
                                       level,                                  \
                                       module,                                 \
                                       format,                                 \
                                       nargs);                                 \
           __root static const char * const _Log_CONCAT2(Ptr, name) @ _Log_TOKEN2STRING(_Log_CONCAT2(.log_ptr, module)) = name;
#elif defined(__TI_COMPILER_VERSION__) || (defined(__clang__) && defined(__ti_version__)) || defined(__GNUC__)
#define _Log_PLACE_FORMAT_IN_SECTOR(name, opcode, level, module, format, nargs)\
            static const char name[]                                           \
            __attribute__((used,section(".log_data"))) =                       \
            _Log_APPEND_META_TO_FORMAT(opcode,                                 \
                                        __FILE__,                              \
                                        __LINE__,                              \
                                        level,                                 \
                                        module,                                \
                                        format,                                \
                                        nargs);                                \
            static const char * const _Log_CONCAT2(Ptr, name)                  \
            __attribute__((used,section(_Log_TOKEN2STRING(_Log_CONCAT3(.log_ptr, __LINE__, module))))) = name;
#else
#error "Incompatible compiler: Logging is currently supported by the following \
compilers: TI ARM Compiler, TI CLANG Compiler, GCC, IAR. Please migrate to a \
supported compiler."
#endif

/*
 *  ======== Variadic macro workaround ========
 */
/*  Helper macro to count the number of arguments in __VA_ARGS_ */
#define _Log_NUMARGS(...) _Log_NUMARGS_A(__VA_ARGS__, 8, 7, 6, 5, 4, 3, 2, 1, 0)
#define _Log_NUMARGS_A(...) _Log_NUMARGS_B(__VA_ARGS__)
#define _Log_NUMARGS_B(_first, _8, _7, _6, _5, _4, _3, _2, _1, N, ...) N

/*
 * Helper to select arg/noarg variant macro since empty va_arg fails
 * when arguments are expected. Eg
 *   Log_VARIANT(test, A, 7, "Hello") -> test__noarg(A, 7, "Hello")
 *   Log_VARIANT(test, A, 7, "Hello %d", 42) -> test__arg1(A, 7, "Hello %d", 42)
 */
#define _Log_VARIANT(x, module, level, ...) \
    _Log_CONCAT2(x, _Log_NUMARGS_B(__VA_ARGS__, _arg8, _arg7, _arg6, _arg5, _arg4, _arg3, _arg2, _arg1, _noarg)) ( module, level, __VA_ARGS__ )

/*
 *  ======== Module-level preprocessor include macros ========
 */

/* Helper macro to extract the second argument of a variable number of input
 * args
 */
#define _Log_SECOND_ARG(x, y, ...) y

/* Temporary token name.
 * Name must end in "1" for preprocessor substitution below to work.
 */
#define _Log_TOKEN_1 0,

/* Helper macro to check whether a symbol is defined with a non-zero value.
 * If x is a preprocessor define, the conversion below shows the macro output:
 * x = 0 -> 0
 * x = 1 -> 1
 * x (no value) -> 0
 * (undefined) -> 0
 */
#define _Log_DEFINED(x)     _Log_DEFINED_A(x)

/* If x is 1, _Log_TOKEN_##y turns into _Log_TOKEN_1 and is replaced with "0,"
 * If x is anything else, _Log_TOKEN_##y turns into _Log_TOKEN_y.
 */
#define _Log_DEFINED_A(y)   _Log_DEFINED_B(_Log_TOKEN_##y)

/* If z is "0,", _Log_SECOND_ARG is called with the triplet "0, 1, 0" and
 * selects the second item in it, 1.
 * If z is anything else, _Log_SECOND_ARG is called with the tuple "z 1, 0" and
 * selects the second item in it, 0.
 */
#define _Log_DEFINED_B(z)   _Log_SECOND_ARG(z 1, 0)

/* Empty Log buf macro to use when a log module is not enabled in the
 * preprocessor during compilation
 */
#define _Log_buf_C_0(module, level, format, data, size)

/* Log_buf macro to use when a log module is enabled in the preprocessor during
 * compilation.
 */
#define _Log_buf_C_1(module, level, format, data, size)                                                 \
    _Log_GUARD_MACRO(                                                                                   \
        Log_MODULE_USE(module);                                                                         \
        _Log_PLACE_FORMAT_IN_SECTOR(_Log_CONCAT2(LogSymbol, __LINE__),                                  \
                                    LOG_OPCODE_BUFFER,                                                  \
                                    level,                                                              \
                                    LogMod_ ## module,                                                  \
                                    format,                                                             \
                                    0);                                                                 \
        LogMod_ ## module.buf(&LogMod_ ## module,                                                       \
                              level,                                                                    \
                              (uint32_t)&_Log_CONCAT3(Ptr, LogSymbol, __LINE__),                        \
                              data,                                                                     \
                              size);                                                                    \
    )

/* First level indirection macro for Log_buf that delegates between an empty
 * implementation and the actual log emission based on whether a module is
 * enabled in the preprocessor during compilation.
 *
 * The _Log_DEFINED() macro generates a token output of [0, 1] that is then
 * concatenated with "_Log_buf_C" to form the correct delegate macro name.
 *
 * The expected module define name is ti_log_Log_ENABLE_ | <module> and must be
 * set to 1. E.g. "-Dti_log_Log_ENABLE_MyLogModule=1". Just defining the symbol in
 * the preprocessor will not emit any logs.
 */
#define _Log_buf_B(module, level, format, data, size) \
    _Log_CONCAT2(_Log_buf_C, _Log_DEFINED(ti_log_Log_ENABLE_ ## module))(module, level, format, data, size)

/* Redirects to cast all printf arguments to uintptr_t to avoid surprises if
 * passing wider values and the compiler silently allows it.
 *
 *  These redirects also allow us to select which delegate function pointer to
 *  load from the #Log_Module. There are dedicated wrappers for certain printf
 *  argument counts.
 *
 *  - 0-3 args redirect to dedicated functions to avoid loading the argument
 *    count when LTO is enabled.
 *  - 4-8 args redirect to a generic implementation.
 *
 *  The 4-8 args break point is a compromise between how often the wrapper can
 *  be expected to be used in an average application and the constant overhead
 *  associated with providing it at all. There is also overhead per Log_Module
 *  for each additional arg count wrapper used. This overhead is eliminated when
 *  LTO is enabled though.
 */
#define _Log_printf__arg1(module, level, fmt, a0)                              \
    module.printf1(&module,                                                    \
                   level,                                                      \
                   (uint32_t)&_Log_CONCAT3(Ptr, LogSymbol, __LINE__),          \
                   (uintptr_t)a0)
#define _Log_printf__arg2(module, level, fmt, a0, a1)                          \
    module.printf2(&module,                                                    \
                   level,                                                      \
                   (uint32_t)&_Log_CONCAT3(Ptr, LogSymbol, __LINE__),          \
                   (uintptr_t)a0,                                              \
                   (uintptr_t)a1)
#define _Log_printf__arg3(module, level, fmt, a0, a1, a2)                      \
    module.printf3(&module,                                                    \
                   level,                                                      \
                   (uint32_t)&_Log_CONCAT3(Ptr, LogSymbol, __LINE__),          \
                   (uintptr_t)a0,                                              \
                   (uintptr_t)a1,                                              \
                   (uintptr_t)a2)
#define _Log_printf__arg4(module, level, fmt, a0, a1, a2, a3)                  \
    _Log_printf__arg(module, level, fmt, (uintptr_t)a0,                        \
                                         (uintptr_t)a1,                        \
                                         (uintptr_t)a2,                        \
                                         (uintptr_t)a3)
#define _Log_printf__arg5(module, level, fmt, a0, a1, a2, a3, a4)              \
    _Log_printf__arg(module, level, fmt, (uintptr_t)a0,                        \
                                         (uintptr_t)a1,                        \
                                         (uintptr_t)a2,                        \
                                         (uintptr_t)a3,                        \
                                         (uintptr_t)a4)
#define _Log_printf__arg6(module, level, fmt, a0, a1, a2, a3, a4, a5)          \
    _Log_printf__arg(module, level, fmt, (uintptr_t)a0,                        \
                                         (uintptr_t)a1,                        \
                                         (uintptr_t)a2,                        \
                                         (uintptr_t)a3,                        \
                                         (uintptr_t)a4,                        \
                                         (uintptr_t)a5)
#define _Log_printf__arg7(module, level, fmt, a0, a1, a2, a3, a4, a5, a6)      \
    _Log_printf__arg(module, level, fmt, (uintptr_t)a0,                        \
                                         (uintptr_t)a1,                        \
                                         (uintptr_t)a2,                        \
                                         (uintptr_t)a3,                        \
                                         (uintptr_t)a4,                        \
                                         (uintptr_t)a5,                        \
                                         (uintptr_t)a6)
#define _Log_printf__arg8(module, level, fmt, a0, a1, a2, a3, a4, a5, a6, a7)  \
    _Log_printf__arg(module, level, fmt, (uintptr_t)a0,                        \
                                         (uintptr_t)a1,                        \
                                         (uintptr_t)a2,                        \
                                         (uintptr_t)a3,                        \
                                         (uintptr_t)a4,                        \
                                         (uintptr_t)a5,                        \
                                         (uintptr_t)a6,                        \
                                         (uintptr_t)a7)

#define _Log_printf__arg(module, level, ...)                                   \
    module.printf(&module,                                                     \
                  level,                                                       \
                  (uint32_t)&_Log_CONCAT3(Ptr, LogSymbol, __LINE__),           \
                  _Log_NUMARGS(__VA_ARGS__),                                   \
                  _Log_CDR_ARG(__VA_ARGS__))

#define _Log_printf__noarg(module, level, ...)                                 \
    module.printf0(&module,                                                    \
                   level,                                                      \
                   (uint32_t)&_Log_CONCAT3(Ptr, LogSymbol, __LINE__))

/* Empty Log_printf macro to use when a log module is not enabled in the
 * preprocessor during compilation
 */
#define _Log_printf_C_0(opcode, module, level, ...)

/* Log_printf macro to use when a log module is enabled in the preprocessor during
 * compilation.
 */
#define _Log_printf_C_1(opcode, module, level, ...)                             \
    _Log_GUARD_MACRO(                                                           \
        Log_MODULE_USE(module);                                                 \
        _Log_PLACE_FORMAT_IN_SECTOR(_Log_CONCAT2(LogSymbol, __LINE__),          \
                                    opcode,                                     \
                                    level,                                      \
                                    LogMod_ ## module,                          \
                                    _Log_CAR_ARG(__VA_ARGS__),                  \
                                    _Log_NUMARGS(__VA_ARGS__))                  \
        _Log_VARIANT(_Log_printf, LogMod_ ## module, level, __VA_ARGS__);       \
    )

/* First level indirection macro for Log_printf that delegates between an empty
 * implementation and the actual log emission based on whether a module is
 * enabled in the preprocessor during compilation.
 *
 * The _Log_DEFINED() macro generates a token output of [0, 1] that is then
 * concatenated with "_Log_buf_C" to form the correct delegate macro name.
 *
 * The expected module define name is ti_log_Log_ENABLE_ | <module> and must be
 * set to 1. E.g. "-Dti_log_Log_ENABLE_MyLogModule=1". Just defining the symbol
 * in the preprocessor will not emit any logs.
 */
#define _Log_printf_B(opcode, module, level, ...) \
    _Log_CONCAT2(_Log_printf_C, _Log_DEFINED(ti_log_Log_ENABLE_ ## module))(opcode, module, level, __VA_ARGS__)

#define Log_buf(module, level, format, data, size) _Log_buf_B(module, level, format, data, size)

#define Log_printf(module, level, ...) _Log_printf_B(LOG_OPCODE_FORMATED_TEXT, module, level, __VA_ARGS__)

#if defined(__IAR_SYSTEMS_ICC__)
#define _Log_DEFINE_LOG_VERSION(module, version)                                                \
    __root static const char _Log_CONCAT2(Log_ti_log_version, __COUNTER__)[] @ ".log_data" =    \
    _Log_APPEND_META_TO_FORMAT(LOG_OPCODE_VERSION,                                              \
                                                module,                                         \
                                                version,                                        \
                                                0,                                              \
                                                0,                                              \
                                                0,                                              \
                                                0)
#elif defined(__TI_COMPILER_VERSION__) || (defined(__clang__) && defined(__ti_version__)) || defined(__GNUC__)
#define _Log_DEFINE_LOG_VERSION(module, version)                                \
            static const char _Log_CONCAT2(Log_ti_log_version, __COUNTER__)[]   \
            __attribute__((used,section(".log_data"))) =                        \
            _Log_APPEND_META_TO_FORMAT(LOG_OPCODE_VERSION,                      \
                                                module,                         \
                                                version,                        \
                                                0,                              \
                                                0,                              \
                                                0,                              \
                                                0)
#else
#error "Incompatible compiler: Logging is currently supported by the following \
compilers: TI ARM Compiler, TI CLANG Compiler, GCC, IAR. Please migrate to a \
supported compiler."
#endif

/* Generate a symbol in the elf file that defines the version of the Log API */
_Log_DEFINE_LOG_VERSION(Log, Log_TI_LOG_VERSION);

#define Log_MODULE_SET_LEVELS(module, levels)               \
    _Log_GUARD_MACRO(                                       \
        Log_MODULE_USE(module);                             \
        if (LogMod_ ## module.dynamicLevelsPtr != NULL) {   \
            *LogMod_ ## module.dynamicLevelsPtr = levels;   \
        }                                                   \
    )

#define Log_MODULE_GET_LEVELS(module)                       \
    _Log_GUARD_MACRO(                                       \
        Log_MODULE_USE(module);                             \
        if (LogMod_ ## module.dynamicLevelsPtr != NULL) {   \
            *LogMod_ ## module.dynamicLevelsPtr;            \
        }                                                   \
        else {                                              \
            LogMod_ ## module.levels;                       \
        }                                                   \
    )

#else /* defined(DOXYGEN) || ti_log_Log_ENABLE */

/*
 *  =================================================
 *  ======== Log Disabled (default behavior) ========
 *  =================================================
 */

#define Log_MODULE_DEFINE(...)
#define Log_MODULE_DEFINE_WEAK(name, init)
#define Log_MODULE_USE(...)
#define Log_printf(module, level, ...)
#define Log_buf(module, level, ...)
#define _Log_DEFINE_LOG_VERSION(module, version)
#define Log_MODULE_SET_LEVELS(module, levels)
#define Log_MODULE_GET_LEVELS(module)

#endif /* defined(DOXYGEN) || ti_log_Log_ENABLE */



typedef enum Log_Level {
    Log_DEBUG = 1 << 0,

    Log_VERBOSE = 1 << 1,

    Log_INFO = 1 << 2,

    Log_WARNING = 1 << 3,

    Log_ERROR = 1 << 4,

    Log_ALL = Log_DEBUG + Log_VERBOSE + Log_INFO + Log_WARNING + Log_ERROR,

    Log_NONE = 0,
} Log_Level;

typedef const struct Log_Module_ Log_Module;

typedef void (*Log_printf_fxn)(const Log_Module *handle,
                               Log_Level level,
                               uint32_t headerPtr,
                               uint32_t numArgs,
                               ...);

typedef void (*Log_printfN_fxn)(const Log_Module *handle,
                                Log_Level level,
                                uint32_t headerPtr,
                                ...);

typedef void (*Log_buf_fxn)(const Log_Module *handle,
                            Log_Level level,
                            uint32_t headerPtr,
                            uint8_t *data,
                            size_t size);

struct Log_Module_ {
    void                 *sinkConfig;       
    const Log_printf_fxn  printf;           
    const Log_printfN_fxn printf0;          
    const Log_printfN_fxn printf1;          
    const Log_printfN_fxn printf2;          
    const Log_printfN_fxn printf3;          
    const Log_buf_fxn     buf;              
    uint32_t              levels;           
    uint32_t* const       dynamicLevelsPtr; 
};

__attribute__((weak)) void LogSinkDummy_printf(const Log_Module *handle,
                                               Log_Level level,
                                               uint32_t headerPtr,
                                               uint32_t numArgs,
                                               ...)
{
    /* The function is defined as weak to allow definition (as opposed to just a
     * declaration) within this header file without running into symbol
     * conflicts during linking.
     * This way we do not need a separate library dependency just for this dummy
     * log sink.
     */

    /* Cast all input arguments to void to avoid unused argument warnings. */
    (void)handle;
    (void)level;
    (void)headerPtr;
    (void)numArgs;

    /* Do not perform any operations and return immediately. */
}

__attribute__((weak)) void LogSinkDummy_printfN(const Log_Module *handle,
                                                Log_Level level,
                                                uint32_t headerPtr,
                                                ...)
{
    /* The function is defined as weak to allow definition (as opposed to just a
     * declaration) within this header file without running into symbol
     * conflicts during linking.
     * This way we do not need a separate library dependency just for this dummy
     * log sink.
     */

    /* Cast all input arguments to void to avoid unused argument warnings. */
    (void)handle;
    (void)level;
    (void)headerPtr;

    /* Do not perform any operations and return immediately. */
}

__attribute__((weak)) void LogSinkDummy_buf(const Log_Module *handle,
                                            Log_Level level,
                                            uint32_t headerPtr,
                                            uint8_t *data,
                                            size_t size)
{
    /* The function is defined as weak to allow definition (as opposed to just a
     * declaration) within this header file without running into symbol
     * conflicts during linking.
     * This way we do not need a separate library dependency just for this dummy
     * log sink.
     */

    /* Cast all input arguments to void to avoid unused argument warnings. */
    (void)handle;
    (void)level;
    (void)headerPtr;
    (void)data;
    (void)size;

    /* Do not perform any operations and return immediately. */
}

#define Log_MODULE_INIT_SINK_DUMMY                                             \
    {                                                                          \
        .sinkConfig = NULL,                                                    \
        .printf = LogSinkDummy_printf,                                         \
        .printf0 = LogSinkDummy_printfN,                                       \
        .printf1 = LogSinkDummy_printfN,                                       \
        .printf2 = LogSinkDummy_printfN,                                       \
        .printf3 = LogSinkDummy_printfN,                                       \
        .buf = LogSinkDummy_buf,                                               \
        .levels = 0,                                                           \
        .dynamicLevelsPtr = NULL,                                              \
    }

#if defined (__cplusplus)
}
#endif

#endif // ti_log_Log__include