pw_trace_tokenized/public/pw_trace_tokenized/trace_tokenized.h - pigweed/pigweed - Git at Google

 // Copyright 2020 The Pigweed Authors
 //
 // Licensed under the Apache License, Version 2.0 (the "License"); you may not
 // use this file except in compliance with the License. You may obtain a copy of
 // the License at
 //
 //     https://www.apache.org/licenses/LICENSE-2.0
 //
 // Unless required by applicable law or agreed to in writing, software
 // distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
 // WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 // License for the specific language governing permissions and limitations under
 // the License.
 //==============================================================================
 //
 // This file provides the interface for working with the tokenized trace
 // backend.

 #pragma once

 #include <stdbool.h>
 #include <stdint.h>
 #include <string.h>

 #ifndef PW_TRACE_GET_TIME_DELTA
 #ifdef __cplusplus
 #include <type_traits>
 #endif  // __cplusplus
 #endif  // PW_TRACE_GET_TIME_DELTA

 #include "pw_tokenizer/tokenize.h"
 #include "pw_trace_tokenized/internal/trace_tokenized_internal.h"

 // Configurable options

 // Since not all strings are tokenizeable, labels can be passed as arguments.
 // PW_TRACE_CONFIG_ARG_LABEL_SIZE_BYTES configures the maximum number of
 // characters to include, if more are provided the string will be clipped.
 #ifndef PW_TRACE_CONFIG_ARG_LABEL_SIZE_BYTES
 #define PW_TRACE_CONFIG_ARG_LABEL_SIZE_BYTES 20
 #endif  // PW_TRACE_CONFIG_ARG_LABEL_SIZE_BYTES

 // PW_TRACE_TIME_TYPE sets the type for trace time.
 #ifndef PW_TRACE_TIME_TYPE
 #define PW_TRACE_TIME_TYPE uint32_t
 #endif  // PW_TRACE_TIME_TYPE

 // PW_TRACE_GET_TIME is the macro which is called to get the current time for a
 // trace event. It's default is to use pw_trace_GetTraceTime() which needs to be
 // provided by the platform.
 #ifndef PW_TRACE_GET_TIME
 #define PW_TRACE_GET_TIME() pw_trace_GetTraceTime()
 extern PW_TRACE_TIME_TYPE pw_trace_GetTraceTime();
 #endif  // PW_TRACE_GET_TIME

 // PW_TRACE_GET_TIME_TICKS_PER_SECOND is the macro which is called to determine
 // the unit of the trace time. It's default is to use
 // pw_trace_GetTraceTimeTicksPerSecond() which needs to be provided by the
 // platform.
 #ifndef PW_TRACE_GET_TIME_TICKS_PER_SECOND
 #define PW_TRACE_GET_TIME_TICKS_PER_SECOND() \
   pw_trace_GetTraceTimeTicksPerSecond()
 extern size_t pw_trace_GetTraceTimeTicksPerSecond();
 #endif  // PW_TRACE_GET_TIME_TICKS_PER_SECOND

 // PW_TRACE_GET_TIME_DELTA is te macro which is called to determine
 // the delta between two PW_TRACE_TIME_TYPE variables. It should return a
 // delta of the two times, in the same type.
 // The default implementation just subtracts the two, which is suitable if
 // values either never wrap, or are unsigned and do not wrap multiple times
 // between trace events. If either of these are not the case a different
 // implemention should be used.
 #ifndef PW_TRACE_GET_TIME_DELTA
 #define PW_TRACE_GET_TIME_DELTA(last_time, current_time) \
   ((current_time) - (last_time))
 #ifdef __cplusplus
 static_assert(
     std::is_unsigned<PW_TRACE_TIME_TYPE>::value,
     "Default time delta implementation only works for unsigned time types.");
 #endif  // __cplusplus
 #endif  // PW_TRACE_GET_TIME_DELTA

 // PW_TRACE_LOCK is called when a new event is being processed to ensure only
 // one event is sent to the sinks at a time. Is is also called when registering
 // and unregistering callbacks and sinks.
 #ifndef PW_TRACE_LOCK
 #define PW_TRACE_LOCK()
 #endif  // PW_TRACE_LOCK

 // PW_TRACE_UNLOCK is called after sending the data to all the sinks.
 #ifndef PW_TRACE_UNLOCK
 #define PW_TRACE_UNLOCK()
 #endif  // PW_TRACE_UNLOCK

 #ifdef __cplusplus
 namespace pw {
 namespace trace {

 using EventType = pw_trace_EventType;

 class TokenizedTraceImpl {
  public:
   void Enable(bool enable) { enabled_ = enable; }
   bool IsEnabled() const { return enabled_; }

   void HandleTraceEvent(uint32_t trace_token,
                         EventType event_type,
                         const char* module,
                         uint32_t trace_id,
                         uint8_t flags,
                         const void* data_buffer,
                         size_t data_size);

  private:
   PW_TRACE_TIME_TYPE last_trace_time_ = 0;
   bool enabled_ = false;
 };

 // A singleton object of the TokenizedTraceImpl class which can be used to
 // interface with trace using the C++ API.
 // Example: pw::trace::TokenizedTrace::Instance().Enable(true);
 class TokenizedTrace {
  public:
   static TokenizedTraceImpl& Instance() { return instance_; };

  private:
   static TokenizedTraceImpl instance_;
 };

 }  // namespace trace
 }  // namespace pw
 #endif  // __cplusplus

 // PW_TRACE_SET_ENABLED is used to enable or disable tracing.
 #define PW_TRACE_SET_ENABLED(enabled) pw_trace_Enable(enabled)

 // PW_TRACE_REF provides the uint32_t token value for a specific trace event.
 // this can be used in the callback to perform specific actions for that trace.
 // All the fields must match exactly to generate the correct trace reference.
 // If the trace does not have a group, use PW_TRACE_GROUP_LABEL_DEFAULT.
 //
 // For example this can be used to skip a specific trace:
 //   pw_trace_TraceEventReturnFlags TraceEventCallback(
 //       uint32_t trace_ref,
 //       pw_trace_EventType event_type,
 //       const char* module,
 //       uint32_t trace_id,
 //       uint8_t flags) {
 //     auto skip_trace_ref = PW_TRACE_REF(PW_TRACE_TYPE_INSTANT,
 //                                        "test_module",    // Module
 //                                        "test_label",     // Label
 //                                        PW_TRACE_FLAGS_DEFAULT,
 //                                        PW_TRACE_GROUP_LABEL_DEFAULT);
 //     if (trace_ref == skip_trace_ref) {
 //       return PW_TRACE_EVENT_RETURN_FLAGS_SKIP_EVENT;
 //     }
 //     return 0;
 //   }
 //
 // The above trace ref would provide the tokenize value for the string:
 //     "1|0|test_module||test_label"
 //
 // Another example:
 //    #define PW_TRACE_MODULE test_module
 //    PW_TRACE_INSTANT_DATA_FLAG(2, "label", "group", id, "%d", 5, 1);
 // Would internally generate a token value for the string:
 //    "1|2|test_module|group|label|%d"
 // The trace_id, and data value are runtime values and not included in the
 // token string.
 #define PW_TRACE_REF(event_type, module, label, flags, group)          \
   PW_TOKENIZE_STRING_DOMAIN("trace",                                   \
                             PW_STRINGIFY(event_type) "|" PW_STRINGIFY( \
                                 flags) "|" module "|" group "|" label)

 #define PW_TRACE_REF_DATA(event_type, module, label, flags, group, type)    \
   PW_TOKENIZE_STRING_DOMAIN(                                                \
       "trace",                                                              \
       PW_STRINGIFY(event_type) "|" PW_STRINGIFY(flags) "|" module "|" group \
                                                        "|" label "|" type)
	// Copyright 2020 The Pigweed Authors
	//
	// Licensed under the Apache License, Version 2.0 (the "License"); you may not
	// use this file except in compliance with the License. You may obtain a copy of
	// the License at
	//
	// https://www.apache.org/licenses/LICENSE-2.0
	//
	// Unless required by applicable law or agreed to in writing, software
	// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
	// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
	// License for the specific language governing permissions and limitations under
	// the License.
	//==============================================================================
	//
	// This file provides the interface for working with the tokenized trace
	// backend.

	#pragma once

	#include <stdbool.h>
	#include <stdint.h>
	#include <string.h>

	#ifndef PW_TRACE_GET_TIME_DELTA
	#ifdef __cplusplus
	#include <type_traits>
	#endif // __cplusplus
	#endif // PW_TRACE_GET_TIME_DELTA

	#include "pw_tokenizer/tokenize.h"
	#include "pw_trace_tokenized/internal/trace_tokenized_internal.h"

	// Configurable options

	// Since not all strings are tokenizeable, labels can be passed as arguments.
	// PW_TRACE_CONFIG_ARG_LABEL_SIZE_BYTES configures the maximum number of
	// characters to include, if more are provided the string will be clipped.
	#ifndef PW_TRACE_CONFIG_ARG_LABEL_SIZE_BYTES
	#define PW_TRACE_CONFIG_ARG_LABEL_SIZE_BYTES 20
	#endif // PW_TRACE_CONFIG_ARG_LABEL_SIZE_BYTES

	// PW_TRACE_TIME_TYPE sets the type for trace time.
	#ifndef PW_TRACE_TIME_TYPE
	#define PW_TRACE_TIME_TYPE uint32_t
	#endif // PW_TRACE_TIME_TYPE

	// PW_TRACE_GET_TIME is the macro which is called to get the current time for a
	// trace event. It's default is to use pw_trace_GetTraceTime() which needs to be
	// provided by the platform.
	#ifndef PW_TRACE_GET_TIME
	#define PW_TRACE_GET_TIME() pw_trace_GetTraceTime()
	extern PW_TRACE_TIME_TYPE pw_trace_GetTraceTime();
	#endif // PW_TRACE_GET_TIME

	// PW_TRACE_GET_TIME_TICKS_PER_SECOND is the macro which is called to determine
	// the unit of the trace time. It's default is to use
	// pw_trace_GetTraceTimeTicksPerSecond() which needs to be provided by the
	// platform.
	#ifndef PW_TRACE_GET_TIME_TICKS_PER_SECOND
	#define PW_TRACE_GET_TIME_TICKS_PER_SECOND() \
	pw_trace_GetTraceTimeTicksPerSecond()
	extern size_t pw_trace_GetTraceTimeTicksPerSecond();
	#endif // PW_TRACE_GET_TIME_TICKS_PER_SECOND

	// PW_TRACE_GET_TIME_DELTA is te macro which is called to determine
	// the delta between two PW_TRACE_TIME_TYPE variables. It should return a
	// delta of the two times, in the same type.
	// The default implementation just subtracts the two, which is suitable if
	// values either never wrap, or are unsigned and do not wrap multiple times
	// between trace events. If either of these are not the case a different
	// implemention should be used.
	#ifndef PW_TRACE_GET_TIME_DELTA
	#define PW_TRACE_GET_TIME_DELTA(last_time, current_time) \
	((current_time) - (last_time))
	#ifdef __cplusplus
	static_assert(
	std::is_unsigned<PW_TRACE_TIME_TYPE>::value,
	"Default time delta implementation only works for unsigned time types.");
	#endif // __cplusplus
	#endif // PW_TRACE_GET_TIME_DELTA

	// PW_TRACE_LOCK is called when a new event is being processed to ensure only
	// one event is sent to the sinks at a time. Is is also called when registering
	// and unregistering callbacks and sinks.
	#ifndef PW_TRACE_LOCK
	#define PW_TRACE_LOCK()
	#endif // PW_TRACE_LOCK

	// PW_TRACE_UNLOCK is called after sending the data to all the sinks.
	#ifndef PW_TRACE_UNLOCK
	#define PW_TRACE_UNLOCK()
	#endif // PW_TRACE_UNLOCK

	#ifdef __cplusplus
	namespace pw {
	namespace trace {

	using EventType = pw_trace_EventType;

	class TokenizedTraceImpl {
	public:
	void Enable(bool enable) { enabled_ = enable; }
	bool IsEnabled() const { return enabled_; }

	void HandleTraceEvent(uint32_t trace_token,
	EventType event_type,
	const char* module,
	uint32_t trace_id,
	uint8_t flags,
	const void* data_buffer,
	size_t data_size);

	private:
	PW_TRACE_TIME_TYPE last_trace_time_ = 0;
	bool enabled_ = false;
	};

	// A singleton object of the TokenizedTraceImpl class which can be used to
	// interface with trace using the C++ API.
	// Example: pw::trace::TokenizedTrace::Instance().Enable(true);
	class TokenizedTrace {
	public:
	static TokenizedTraceImpl& Instance() { return instance_; };

	private:
	static TokenizedTraceImpl instance_;
	};

	} // namespace trace
	} // namespace pw
	#endif // __cplusplus

	// PW_TRACE_SET_ENABLED is used to enable or disable tracing.
	#define PW_TRACE_SET_ENABLED(enabled) pw_trace_Enable(enabled)

	// PW_TRACE_REF provides the uint32_t token value for a specific trace event.
	// this can be used in the callback to perform specific actions for that trace.
	// All the fields must match exactly to generate the correct trace reference.
	// If the trace does not have a group, use PW_TRACE_GROUP_LABEL_DEFAULT.
	//
	// For example this can be used to skip a specific trace:
	// pw_trace_TraceEventReturnFlags TraceEventCallback(
	// uint32_t trace_ref,
	// pw_trace_EventType event_type,
	// const char* module,
	// uint32_t trace_id,
	// uint8_t flags) {
	// auto skip_trace_ref = PW_TRACE_REF(PW_TRACE_TYPE_INSTANT,
	// "test_module", // Module
	// "test_label", // Label
	// PW_TRACE_FLAGS_DEFAULT,
	// PW_TRACE_GROUP_LABEL_DEFAULT);
	// if (trace_ref == skip_trace_ref) {
	// return PW_TRACE_EVENT_RETURN_FLAGS_SKIP_EVENT;
	// }
	// return 0;
	// }
	//
	// The above trace ref would provide the tokenize value for the string:
	// "1\|0\|test_module\|\|test_label"
	//
	// Another example:
	// #define PW_TRACE_MODULE test_module
	// PW_TRACE_INSTANT_DATA_FLAG(2, "label", "group", id, "%d", 5, 1);
	// Would internally generate a token value for the string:
	// "1\|2\|test_module\|group\|label\|%d"
	// The trace_id, and data value are runtime values and not included in the
	// token string.
	#define PW_TRACE_REF(event_type, module, label, flags, group) \
	PW_TOKENIZE_STRING_DOMAIN("trace", \
	PW_STRINGIFY(event_type) "\|" PW_STRINGIFY( \
	flags) "\|" module "\|" group "\|" label)

	#define PW_TRACE_REF_DATA(event_type, module, label, flags, group, type) \
	PW_TOKENIZE_STRING_DOMAIN( \
	"trace", \
	PW_STRINGIFY(event_type) "\|" PW_STRINGIFY(flags) "\|" module "\|" group \
	"\|" label "\|" type)