pw_log_tokenized

Overview

Main docs: Home

Namespaces
namespace	pw
	The Pigweed namespace.

Classes
struct	pw::log_tokenized::internal::BitField< T, kBits, kShift >
class	pw::log_tokenized::internal::BitField< T, 0, kShift >
class	pw::log_tokenized::GenericMetadata< kLevelBits, kLineBits, kFlagBits, kModuleBits, T >

Macros
#define	PW_LOG_TOKENIZED_ENCODING_BUFFER_SIZE_BYTES    PW_TOKENIZER_CFG_ENCODING_BUFFER_SIZE_BYTES
#define	PW_LOG_TOKENIZED_FIELD_PREFIX   "■"
#define	PW_LOG_TOKENIZED_KEY_VALUE_SEPARATOR   "♦"
#define	_PW_LOG_TOKENIZED_FIELD(name, contents)
#define	PW_LOG_TOKENIZED_FORMAT_STRING(module, message)
#define	PW_LOG_TOKENIZED_LEVEL_BITS   PW_LOG_LEVEL_BITS
	Bits to allocate for the log level. Defaults to PW_LOG_LEVEL_BITS (3).
#define	PW_LOG_TOKENIZED_LINE_BITS   11
#define	PW_LOG_TOKENIZED_FLAG_BITS   2
	Bits to use for implementation-defined flags. Defaults to 2.
#define	PW_LOG_TOKENIZED_MODULE_BITS   16
#define	_PW_LOG_TOKENIZED_LEVEL(value)   ((uintptr_t)0)
#define	_PW_LOG_TOKENIZED_LINE(line)
#define	_PW_LOG_TOKENIZED_FLAGS(value)
#define	_PW_LOG_TOKENIZED_MODULE(value)
#define	PW_LOG_TOKENIZED_TO_GLOBAL_HANDLER_WITH_METADATA( level, module, flags, message, ...)
#define	PW_LOG_TOKENIZED_TO_GLOBAL_HANDLER_WITH_PAYLOAD    PW_LOG_TOKENIZED_TO_GLOBAL_HANDLER_WITH_METADATA
	Legacy alias for PW_LOG_TOKENIZED_TO_GLOBAL_HANDLER_WITH_METADATA.
#define	PW_LOG_TOKENIZED_ENCODE_MESSAGE(metadata, format, ...)
#define	PW_LOG_TOKENIZED_TO_GLOBAL_HANDLER(level, module, flags, message, ...)
#define	PW_LOG_TOKENIZED_ENCODE_MESSAGE_LIGHT(format, ...)

Typedefs
using	pw::log_tokenized::Metadata = GenericMetadata< PW_LOG_TOKENIZED_LEVEL_BITS, PW_LOG_TOKENIZED_LINE_BITS, PW_LOG_TOKENIZED_FLAG_BITS, PW_LOG_TOKENIZED_MODULE_BITS >

Functions
InlineString< kBase64EncodedBufferSizeBytes >	pw::log_tokenized::PrefixedBase64Encode (span< const std::byte > binary_message)
template<typename Function >
constexpr StatusWithSize	pw::log_tokenized::ParseFields (std::string_view string, Function field_consumer, std::string_view field_prefix=PW_LOG_TOKENIZED_FIELD_PREFIX, std::string_view key_val_separator=PW_LOG_TOKENIZED_KEY_VALUE_SEPARATOR)
void	pw_log_tokenized_HandleLog (uint32_t metadata, const uint8_t encoded_message[], size_t size_bytes)
void	pw_log_tokenized_HandleLogWithoutMetadata (const uint8_t encoded_message[], size_t size_bytes)
static constexpr T	pw::log_tokenized::internal::BitField< T, kBits, kShift >::Get (T value)
static constexpr T	pw::log_tokenized::internal::BitField< T, kBits, kShift >::Shift (T value)
static constexpr T	pw::log_tokenized::internal::BitField< T, 0, kShift >::Get (T)
static constexpr T	pw::log_tokenized::internal::BitField< T, 0, kShift >::Shift (T)
template<T log_level = 0, T module = 0, T flags = 0, T line = 0>
static constexpr GenericMetadata	pw::log_tokenized::GenericMetadata< kLevelBits, kLineBits, kFlagBits, kModuleBits, T >::Set ()
constexpr	pw::log_tokenized::GenericMetadata< kLevelBits, kLineBits, kFlagBits, kModuleBits, T >::GenericMetadata (T log_level, T module, T flags, T line)
constexpr	pw::log_tokenized::GenericMetadata< kLevelBits, kLineBits, kFlagBits, kModuleBits, T >::GenericMetadata (T value)
constexpr T	pw::log_tokenized::GenericMetadata< kLevelBits, kLineBits, kFlagBits, kModuleBits, T >::level () const
	The log level of this message.
constexpr T	pw::log_tokenized::GenericMetadata< kLevelBits, kLineBits, kFlagBits, kModuleBits, T >::line_number () const
constexpr T	pw::log_tokenized::GenericMetadata< kLevelBits, kLineBits, kFlagBits, kModuleBits, T >::flags () const
	The flags provided to the log call.
constexpr T	pw::log_tokenized::GenericMetadata< kLevelBits, kLineBits, kFlagBits, kModuleBits, T >::module () const
	The 16-bit tokenized version of the module name (PW_LOG_MODULE_NAME).
constexpr T	pw::log_tokenized::GenericMetadata< kLevelBits, kLineBits, kFlagBits, kModuleBits, T >::value () const
	The underlying packed metadata.

Variables
constexpr size_t	pw::log_tokenized::kBase64EncodedBufferSizeBytes
constexpr size_t	pw::log_tokenized::kEncodingBufferSizeBytes

Macro Definition Documentation

_PW_LOG_TOKENIZED_FIELD

#define _PW_LOG_TOKENIZED_FIELD	(		name,
			contents
	)

Value:

  PW_LOG_TOKENIZED_FIELD_PREFIX name PW_LOG_TOKENIZED_KEY_VALUE_SEPARATOR \
      contents

_PW_LOG_TOKENIZED_FLAGS

#define _PW_LOG_TOKENIZED_FLAGS

(

value

)

Value:

  (((uintptr_t)(value) & (((uintptr_t)1 << PW_LOG_TOKENIZED_FLAG_BITS) - 1)) \
   << (PW_LOG_TOKENIZED_LEVEL_BITS + PW_LOG_TOKENIZED_LINE_BITS))

_PW_LOG_TOKENIZED_LINE

#define _PW_LOG_TOKENIZED_LINE

(

line

)

Value:

  ((uintptr_t)(line < (1 << PW_LOG_TOKENIZED_LINE_BITS) ? line : 0) \
   << PW_LOG_TOKENIZED_LEVEL_BITS)

_PW_LOG_TOKENIZED_MODULE

#define _PW_LOG_TOKENIZED_MODULE

(

value

)

Value:

  ((uintptr_t)(value) << ((PW_LOG_TOKENIZED_LEVEL_BITS + \
                           PW_LOG_TOKENIZED_LINE_BITS +  \
                           PW_LOG_TOKENIZED_FLAG_BITS)))

PW_LOG_TOKENIZED_ENCODE_MESSAGE

#define PW_LOG_TOKENIZED_ENCODE_MESSAGE	(		metadata,
			format,
			...
	)

Value:

  do {                                                                       \
    PW_TOKENIZE_FORMAT_STRING(                                               \
        PW_TOKENIZER_DEFAULT_DOMAIN, UINT32_MAX, format, __VA_ARGS__);       \
    _pw_log_tokenized_EncodeTokenizedLog(metadata,                           \
                                         _pw_tokenizer_token,                \
                                         PW_TOKENIZER_ARG_TYPES(__VA_ARGS__) \
                                             PW_COMMA_ARGS(__VA_ARGS__));    \
  } while (0)

Encodes a log message and metadata into the tokenized format.

This macro tokenizes the format string and calls the backend handler with packed metadata.

PW_LOG_TOKENIZED_ENCODE_MESSAGE_LIGHT

#define PW_LOG_TOKENIZED_ENCODE_MESSAGE_LIGHT	(		format,
			...
	)

Value:

  do {                                                                   \
    PW_TOKENIZE_FORMAT_STRING(                                           \
        PW_TOKENIZER_DEFAULT_DOMAIN, UINT32_MAX, format, __VA_ARGS__);   \
    _pw_log_tokenized_EncodeTokenizedLogWithoutMetadata(                 \
        _pw_tokenizer_token,                                             \
        PW_TOKENIZER_ARG_TYPES(__VA_ARGS__) PW_COMMA_ARGS(__VA_ARGS__)); \
  } while (0)

Encodes a log message into the tokenized format without metadata.

This macro tokenizes the format string and calls the backend handler _pw_log_tokenized_EncodeTokenizedLogWithoutMetadata.

PW_LOG_TOKENIZED_FORMAT_STRING

#define PW_LOG_TOKENIZED_FORMAT_STRING	(		module,
			message
	)

Value:

  _PW_LOG_TOKENIZED_FIELD("msg", message)               \
  _PW_LOG_TOKENIZED_FIELD("module", module)             \
  _PW_LOG_TOKENIZED_FIELD("file", __FILE__)

This macro takes the pw_log module name and format string to produce a new string that will be tokenized. Any information can be packed into this string without affecting code size, since tokenization removes it from the binary. By default, pw_log_tokenized includes three fields as key-value pair: log module, message, and file path (__FILE__).

PW_LOG_TOKENIZED_LINE_BITS

#define PW_LOG_TOKENIZED_LINE_BITS   11

Bits to allocate for the line number. Defaults to 11 (up to line 2047). If the line number is too large to be represented by this field, line is reported as 0.

Including the line number can slightly increase code size. Without the line number, the log metadata argument is the same for all logs with the same level and flags. With the line number, each metadata value is unique and must be encoded as a separate word in the binary. Systems with extreme space constraints may exclude line numbers by setting this macro to 0.

It is possible to include line numbers in tokenized log format strings, but that is discouraged because line numbers change whenever a file is edited. Passing the line number with the metadata is a lightweight way to include it.

PW_LOG_TOKENIZED_MODULE_BITS

#define PW_LOG_TOKENIZED_MODULE_BITS   16

Bits to use for the tokenized version of PW_LOG_MODULE_NAME. Defaults to 16, which gives a ~1% probability of a collision with 37 module names.

PW_LOG_TOKENIZED_TO_GLOBAL_HANDLER

#define PW_LOG_TOKENIZED_TO_GLOBAL_HANDLER	(		level,
			module,
			flags,
			message,
			...
	)

Value:

  do {                                                                         \
    (void)level;                                                               \
    (void)flags;                                                               \
    PW_LOG_TOKENIZED_ENCODE_MESSAGE_LIGHT(                                     \
        PW_LOG_TOKENIZED_FORMAT_STRING(module, message), __VA_ARGS__);         \
  } while (0)

This macro implements PW_LOG using pw_tokenizer without any metadata. Users must implement pw_log_tokenized_HandleLogWithoutMetadata(const uint8_t* buffer, size_t size).

PW_LOG_TOKENIZED_TO_GLOBAL_HANDLER_WITH_METADATA

#define PW_LOG_TOKENIZED_TO_GLOBAL_HANDLER_WITH_METADATA	(		level,
			module,
			flags,
			message,
			...
	)

Value:

  do {                                                                       \
    _PW_TOKENIZER_CONST uintptr_t _pw_log_tokenized_module_token =           \
        PW_TOKENIZE_STRING_MASK("pw_log_module_names",                       \
                                ((1u << PW_LOG_TOKENIZED_MODULE_BITS) - 1u), \
                                module);                                     \
    const uintptr_t _pw_log_tokenized_level = level;                         \
    PW_LOG_TOKENIZED_ENCODE_MESSAGE(                                         \
        (_PW_LOG_TOKENIZED_LEVEL(_pw_log_tokenized_level) |                  \
         _PW_LOG_TOKENIZED_MODULE(_pw_log_tokenized_module_token) |          \
         _PW_LOG_TOKENIZED_FLAGS(flags) | _PW_LOG_TOKENIZED_LINE(__LINE__)), \
        PW_LOG_TOKENIZED_FORMAT_STRING(module, message),                     \
        __VA_ARGS__);                                                        \
  } while (0)

This macro implements PW_LOG using pw_tokenizer. Users must implement pw_log_tokenized_HandleLog(uint32_t metadata, const uint8_t* buffer, size_t size). The log level, module token, and flags are packed into the metadata argument.

Two strings are tokenized in this macro:

• The log format string, tokenized in the default tokenizer domain.
• Log module name, masked to 16 bits and tokenized in the "pw_log_module_names" tokenizer domain.

To use this macro, implement pw_log_tokenized_HandleLog(), which is defined in pw_log_tokenized/handler.h. The log metadata can be accessed using pw::log_tokenized::Metadata. For example:

extern "C" void pw_log_tokenized_HandleLog(
    uint32_t metadata, const uint8_t data[], size_t size) {
  pw::log_tokenized::Metadata metadata(metadata);
 
  if (metadata.level() >= kLogLevel && ModuleEnabled(metadata.module())) {
    EmitLogMessage(data, size, metadata.flags());
  }
}

Typedef Documentation

Metadata

using pw::log_tokenized::Metadata = typedef GenericMetadata<PW_LOG_TOKENIZED_LEVEL_BITS, PW_LOG_TOKENIZED_LINE_BITS, PW_LOG_TOKENIZED_FLAG_BITS, PW_LOG_TOKENIZED_MODULE_BITS>

The Metadata alias simplifies the bit field width templatization of GenericMetadata by pulling from this module's configuration options. In most cases, it's recommended to use Metadata to create or read metadata payloads.

A Metadata object can be created from a uint32_t.

Function Documentation

GenericMetadata()

template<unsigned kLevelBits, unsigned kLineBits, unsigned kFlagBits, unsigned kModuleBits, typename T = uintptr_t>

constexpr pw::log_tokenized::GenericMetadata< kLevelBits, kLineBits, kFlagBits, kModuleBits, T >::GenericMetadata ( T  log_level, T  module, T  flags, T  line  )

inlineconstexpr

Only use this constructor for creating metadata from runtime values. This constructor is unable to warn at compilation when values will not fit in the specified bit field widths.

line_number()

template<unsigned kLevelBits, unsigned kLineBits, unsigned kFlagBits, unsigned kModuleBits, typename T = uintptr_t>

constexpr T pw::log_tokenized::GenericMetadata< kLevelBits, kLineBits, kFlagBits, kModuleBits, T >::line_number ( ) const

inlineconstexpr

The line number of the log call. The first line in a file is 1. If the line number is 0, it was too large to be stored.

ParseFields()

template<typename Function >

constexpr StatusWithSize pw::log_tokenized::ParseFields ( std::string_view  string, Function  field_consumer, std::string_view  field_prefix = PW_LOG_TOKENIZED_FIELD_PREFIX, std::string_view  key_val_separator = PW_LOG_TOKENIZED_KEY_VALUE_SEPARATOR  )

constexpr

Parses metadata fields from a tokenized log format string.

This function iterates through a string, parsing key-value pairs that are formatted in the pw_log_tokenized style. For each / field found, it invokes the provided field_consumer function with the / extracted key and value.

Parameters

[in]	string	The string to parse.
[in]	field_consumer	A function or lambda to be called for each parsed field. It must accept two std::string_view arguments: the key and the value.

Returns

pw::StatusWithSize instead of the number of fields parsed. If the key is unterminated, returns pw::Status::DataLoss() with the number of fields parsed.

PrefixedBase64Encode()

InlineString< kBase64EncodedBufferSizeBytes > pw::log_tokenized::PrefixedBase64Encode ( span< const std::byte >  binary_message )

inline

Encodes a binary tokenized log in the prefixed Base64 format. Calls pw::tokenizer::PrefixedBase64Encode for a string sized to fit a kEncodingBufferSizeBytes tokenized log.

pw_log_tokenized_HandleLog()

void pw_log_tokenized_HandleLog	(	uint32_t	metadata,
		const uint8_t	encoded_message[],
		size_t	size_bytes
	)

Function that is called for each log message. The metadata uint32_t can be converted to a pw::log_tokenized::Metadata. The message is passed as a pointer to a buffer and a size. The pointer is invalidated after this function returns, so the buffer must be copied.

pw_log_tokenized_HandleLogWithoutMetadata()

void pw_log_tokenized_HandleLogWithoutMetadata	(	const uint8_t	encoded_message[],
		size_t	size_bytes
	)

Function that is called for each log message. The message is passed as a pointer to a buffer and a size. The pointer is invalidated after this function returns, so the buffer must be copied.

Variable Documentation

kBase64EncodedBufferSizeBytes

constexpr size_t pw::log_tokenized::kBase64EncodedBufferSizeBytes

inlineconstexpr

Initial value:

=
    tokenizer::Base64EncodedBufferSize(kEncodingBufferSizeBytes)

kEncodingBufferSizeBytes

constexpr size_t pw::log_tokenized::kEncodingBufferSizeBytes

inlineconstexpr

Initial value:

=
     PW_TOKENIZER_CFG_ENCODING_BUFFER_SIZE_BYTES