pw_log_tokenized

Oveview

Main docs: https://pigweed.dev/pw_log_tokenized.

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
#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

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)
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
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_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_LEVEL_BITS

#define PW_LOG_TOKENIZED_LEVEL_BITS   PW_LOG_LEVEL_BITS

Bits to allocate for the log level. Defaults to

embed:rst:inline :c:macro:`PW_LOG_LEVEL_BITS` 

(3).

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

embed:rst:inline :c:macro:`PW_LOG_MODULE_NAME` 

. Defaults to 16, which gives a ~1% probability of a collision with 37 module names.

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.

module()

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

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

inlineconstexpr

The 16-bit tokenized version of the module name (

embed:rst:inline :c:macro:`PW_LOG_MODULE_NAME` 

).

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

embed:rst:inline :c:enumerator:`StatusWithSize` 

instead of the number of fields parsed. If the key is unterminated, returns

embed:rst:inline :c:enumerator:`DATA_LOSS` 

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

embed:rst:inline :cpp:func:`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

embed:rst:inline :cpp:type:`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.

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