Tokenized log arguments#

pw_log: Robust and portable logging for embedded projects

The pw_log facade is intended to make the logging backend invisible to the user, but some backend features require additional frontend support, necessitating a break in the abstraction. One of these features is the logging of nested token arguments in tokenized logs, because only the user is able to know which log arguments can be tokens (see pw_tokenizer for context on tokenization, and pw_log_tokenized for an example of a tokenized logging backend). Arguments that have already been tokenized are just unsigned integers, and not all strings can be compile-time constants, so users must be provided with a way of manually marking token arguments.

To this end, pw_log/tokenized_args.h aliases macros from pw_tokenizer to enable logging nested tokens when the active backend uses tokenization. These alias macros revert to plain string logging otherwise, allowing projects to take advantage of nested token logging without breaking readable logs when the project is built with a different logging backend. To support logging nested token arguments, a pw_log backend must add an empty file log_backend_uses_pw_tokenizer.h under public_overrides/pw_log_backend/.

Although the detokenizing backend accepts several different numeric bases, the macros currently only support formatting nested tokens in hexadecimal, which affects how the arguments appear in final logs if they cannot be detokenized for any reason. Undetokenized tokens will appear inline as hex integers prefixed with $#, e.g. $#34d16466.

PW_LOG_TOKEN_TYPE#

If nested tokenization is supported by the logging backend, this is an alias for pw_tokenizer_Token.

For non-tokenizing backends, defaults to const char*.

PW_LOG_TOKEN(string_literal)#: If nested tokenization is supported by the logging backend, this is an alias for PW_TOKENIZE_STRING. No-op otherwise.

PW_LOG_TOKEN_EXPR(string_literal)#: If nested tokenization is supported by the logging backend, this is an alias for PW_TOKENIZE_STRING_EXPR. No-op otherwise.

PW_LOG_TOKEN_FMT(...)#

If nested tokenization is supported by the logging backend, this is an alias for PW_TOKEN_FORMAT.

For non-tokenizing backends, defaults to the string specifier s.

Example usage with inline string arguments:

#include "pw_log/log.h"
#include "pw_log/tokenized_args.h"

// bool active_
PW_LOG_INFO("Component is " PW_LOG_TOKEN_FMT(),
            active_ ? PW_LOG_TOKEN_EXPR("active")
                    : PW_LOG_TOKEN_EXPR("idle"));

Example usage with enums:

#include "pw_log/log.h"
#include "pw_log/tokenized_args.h"

namespace foo {

enum class Color { kRed, kGreen, kBlue };

PW_LOG_TOKEN_TYPE ColorToToken(Color color) {
  switch (color) {
    case Color::kRed:
      return PW_LOG_TOKEN_EXPR("kRed");
    case Color::kGreen:
      return PW_LOG_TOKEN_EXPR("kGreen");
    case Color::kBlue:
      return PW_LOG_TOKEN_EXPR("kBlue");
    default:
      return PW_LOG_TOKEN_EXPR("kUnknown");
  }
}

} // namespace foo

void LogColor(foo::Color color) {
  PW_LOG("Color: [" PW_LOG_TOKEN_FMT() "]", color)
}