| // 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 describes Pigweed's public user-facing tracing API. |
| // |
| // THIS PUBLIC API IS NOT STABLE OR COMPLETE! |
| // |
| |
| #pragma once |
| |
| #include <stdbool.h> |
| #include <stdint.h> |
| |
| #include "pw_preprocessor/util.h" |
| #include "pw_trace/internal/trace_internal.h" |
| |
| // Backend defines PW_TRACE in the form: |
| // #define PW_TRACE(event_type, flags, label, group_label, trace_id) |
| |
| // trace_backend.h must ultimately resolve to a header that implements the |
| // macros required by the tracing facade, as described below. |
| // |
| // Inputs: Macros the downstream user provides to control the tracing system: |
| // |
| // PW_TRACE_MODULE_NAME |
| // - The module name the backend should use |
| // |
| // Outputs: Macros trace_backend.h is expected to provide: |
| // |
| // PW_TRACE(event_type, flags, label, group_label, trace_id) |
| // PW_TRACE_DATA(event_type, flags, label, group_label, trace_id, |
| // data_format_string, data, data_size) |
| // - Implementing PW_TRACE_DATA is optional. If not defined, all data |
| // traces will be removed. |
| // |
| // event_type will pass the macro value which is defined by the backend when |
| // enabling the trace type. |
| // |
| // Enabling traces: The backend can define these macros to enable the different |
| // trace types. If not defined those traces are removed. |
| // |
| // PW_TRACE_TYPE_INSTANT: Instant trace, with only a label. |
| // PW_TRACE_TYPE_INSTANT_GROUP: Instant trace, with a label and a group. |
| // PW_TRACE_TYPE_DURATION_START: Start trace, with only a label. |
| // PW_TRACE_TYPE_DURATION_END: End trace, with only a label. |
| // PW_TRACE_TYPE_DURATION_GROUP_START: Start trace, with a label and a group. |
| // PW_TRACE_TYPE_DURATION_GROUP_END: End trace, with a label and a group. |
| // PW_TRACE_TYPE_ASYNC_START: Start trace, with label, group, and trace_id. |
| // PW_TRACE_TYPE_ASYNC_INSTANT: Instant trace, with label, group, and trace_id |
| // PW_TRACE_TYPE_ASYNC_END: End trace, with label, group, and trace_id. |
| // |
| // Defaults: The backend can use the macros to change what the default value is |
| // if not provided. |
| // |
| // PW_TRACE_FLAGS_DEFAULT: Default value if no flags are provided. |
| // PW_TRACE_TRACE_ID_DEFAULT: Default value if not trace_id provided. |
| // PW_TRACE_GROUP_LABEL_DEFAULT: Default value if not group_label provided. |
| |
| #include "pw_trace_backend/trace_backend.h" |
| |
| // Default: Module name |
| #ifndef PW_TRACE_MODULE_NAME |
| #define PW_TRACE_MODULE_NAME "" |
| #endif // PW_TRACE_MODULE_NAME |
| |
| // Default: Flags values currently set if not provided |
| #ifndef PW_TRACE_FLAGS |
| #define PW_TRACE_FLAGS PW_TRACE_FLAGS_DEFAULT |
| #endif // PW_TRACE_FLAGS |
| |
| // PW_TRACE_INSTANT(label) |
| // PW_TRACE_INSTANT(label, group) |
| // PW_TRACE_INSTANT(label, group, trace_id) |
| // |
| // Used to trace an instantaneous event in code. |
| // |
| // Example usage: |
| // PW_TRACE_INSTANT("HERE"); |
| // |
| // Arguments: |
| // label: A string literal which desribes the trace |
| // group <optional>: A string literal which groups this trace with others in |
| // the same module and group. |
| // trace_id <optional>: A runtime uint32_t which groups this trace with |
| // others with the same module group and trace_id. |
| // Every trace with a trace_id must also have a group. |
| #define PW_TRACE_INSTANT(...) PW_TRACE_INSTANT_FLAG(PW_TRACE_FLAGS, __VA_ARGS__) |
| |
| // PW_TRACE_INSTANT_FLAG(flag, label) |
| // PW_TRACE_INSTANT_FLAG(flag, label, group) |
| // PW_TRACE_INSTANT_FLAG(flag, label, group, trace_id) |
| // |
| // These macros mirror PW_TRACE_INSTANT but intruduce the flag argument to |
| // specify a flag value which is used instead of PW_TRACE_FLAGS. The flag goes |
| // at the start, group and trace_id arguments are still optional. |
| #define PW_TRACE_INSTANT_FLAG(...) \ |
| PW_DELEGATE_BY_ARG_COUNT(_PW_TRACE_INSTANT_ARGS, __VA_ARGS__) |
| |
| // PW_TRACE_INSTANT_DATA(label, data_format_string, data, size) |
| // PW_TRACE_INSTANT_DATA(label, group, data_format_string, data, size) |
| // PW_TRACE_INSTANT_DATA(label, group, trace_id, data_format_string, data, size) |
| // |
| // These macros mirror PW_TRACE_INSTANT but introduce arguments to specify a |
| // user-supplied data buffer to append to the trace event. |
| // |
| // Arguments: |
| // data_format_string: A string which is used by the decoder to identify the |
| // data. This could for example be either be printf style |
| // tokens, python struct packed fmt string or a custom |
| // label recognized by the decoder. |
| // data: A pointer to a buffer of arbitrary caller-provided data (void*). |
| // size: The size of the data (size_t). |
| #define PW_TRACE_INSTANT_DATA(...) \ |
| PW_TRACE_INSTANT_DATA_FLAG(PW_TRACE_FLAGS, __VA_ARGS__) |
| |
| // PW_TRACE_INSTANT_DATA_FLAG(flag, label, data_format_string, data, size) |
| // PW_TRACE_INSTANT_DATA_FLAG(flag, |
| // label, |
| // group, |
| // data_format_string, |
| // data, |
| // size) |
| // PW_TRACE_INSTANT_DATA_FLAG(flag, |
| // label, |
| // group, |
| // trace_id, |
| // data_format_string, |
| // data, |
| // size) |
| // |
| // These macros mirror PW_TRACE_INSTANT_DATA but intruduce the flag argument to |
| // specify a flag value which is used instead of PW_TRACE_FLAGS. The flag goes |
| // at the start, group and trace_id arguments are still optional. |
| // |
| // Arguments: |
| // data_format_string: A string which is used by the decoder to identify the |
| // data. This could for example be either be printf style |
| // tokens, python struct packed fmt string or a custom |
| // label recognized by the decoder. |
| // data: A pointer to a buffer of arbitrary caller-provided data (void*). |
| // size: The size of the data (size_t). |
| #define PW_TRACE_INSTANT_DATA_FLAG(...) \ |
| PW_DELEGATE_BY_ARG_COUNT(_PW_TRACE_INSTANT_DATA_ARGS, __VA_ARGS__) |
| |
| // PW_TRACE_START(label) |
| // PW_TRACE_START(label, group) |
| // PW_TRACE_START(label, group, trace_id) |
| // |
| // Used to start tracing an event, should be paired with an PW_TRACE_END (or |
| // PW_TRACE_END_DATA) with the same module/label/group/trace_id. |
| // |
| // Example usage: |
| // PW_TRACE_START("label"); |
| // .. Do something .. |
| // PW_TRACE_END("label"); |
| // |
| // Arguments: |
| // label: A string literal which desribes the trace |
| // group <optional>: A string literal which groups this trace with others in |
| // the same module and group. |
| // trace_id <optional>: A runtime uint32_t which groups this trace with |
| // others with the same module group and trace_id. |
| // Every trace with a trace_id must also have a group. |
| #define PW_TRACE_START(...) PW_TRACE_START_FLAG(PW_TRACE_FLAGS, __VA_ARGS__) |
| |
| // PW_TRACE_START_FLAG(flag, label) |
| // PW_TRACE_START_FLAG(flag, label, group) |
| // PW_TRACE_START_FLAG(flag, label, group, trace_id) |
| // |
| // These macros mirror PW_TRACE_START but intruduce the flag argument to |
| // specify a flag value which is used instead of PW_TRACE_FLAGS. The flag goes |
| // at the start, group and trace_id arguments are still optional. |
| #define PW_TRACE_START_FLAG(...) \ |
| PW_DELEGATE_BY_ARG_COUNT(_PW_TRACE_START_ARGS, __VA_ARGS__) |
| |
| // PW_TRACE_START_DATA(label, data_format_string, data, size) |
| // PW_TRACE_START_DATA(label, group, data_format_string, data, size) |
| // PW_TRACE_START_DATA(flag, |
| // label, |
| // group, |
| // trace_id, |
| // data_format_string, |
| // data, |
| // size) |
| // |
| // These macros mirror PW_TRACE_START but introduce arguments to specify a |
| // user-supplied data buffer to append to the trace event. |
| // |
| // NOTE: A trace duration start/end can be combined with a duration data |
| // start/end, to include data at only one of the trace points and not the other. |
| // |
| // Arguments: |
| // data_format_string: A string which is used by the decoder to identify the |
| // data. This could for example be either be printf style |
| // tokens, python struct packed fmt string or a custom |
| // label recognized by the decoder. |
| // data: A pointer to a buffer of arbitrary caller-provided data (void*). |
| // size: The size of the data (size_t). |
| #define PW_TRACE_START_DATA(...) \ |
| PW_TRACE_START_DATA_FLAG(PW_TRACE_FLAGS, __VA_ARGS__) |
| |
| // PW_TRACE_START_DATA_FLAG(flag, label, data_format_string, data, size) |
| // PW_TRACE_START_DATA_FLAG(flag, label, group, data_format_string, data, size) |
| // PW_TRACE_START_DATA_FLAG(flag, |
| // label, |
| // group, |
| // trace_id, |
| // data_format_string, |
| // data, |
| // size) |
| // |
| // These macros mirror PW_TRACE_START_DATA but intruduce the flag argument to |
| // specify a flag value which is used instead of PW_TRACE_FLAGS. The flag goes |
| // at the start, group and trace_id arguments are still optional. |
| // |
| // Arguments: |
| // data_format_string: A string which is used by the decoder to identify the |
| // data. This could for example be either be printf style |
| // tokens, python struct packed fmt string or a custom |
| // label recognized by the decoder. |
| // data: A pointer to a buffer of arbitrary caller-provided data (void*). |
| // size: The size of the data (size_t). |
| #define PW_TRACE_START_DATA_FLAG(...) \ |
| PW_DELEGATE_BY_ARG_COUNT(_PW_TRACE_START_DATA_ARGS, __VA_ARGS__) |
| |
| // PW_TRACE_END(label) |
| // PW_TRACE_END(label, group) |
| // PW_TRACE_END(label, group, trace_id) |
| // |
| // Used to start tracing an event, should be paired with an PW_TRACE_START (or |
| // PW_TRACE_START_DATA) with the same module/label/group/trace_id. |
| // |
| // Example usage: |
| // PW_TRACE_START("label"); |
| // .. Do something .. |
| // PW_TRACE_END("label"); |
| // |
| // Arguments: |
| // label: A string literal which desribes the trace |
| // group <optional>: A string literal which groups this trace with others in |
| // the same module and group. |
| // trace_id <optional>: A runtime uint32_t which groups this trace with |
| // others with the same module group and trace_id. |
| // Every trace with a trace_id must also have a group. |
| #define PW_TRACE_END(...) PW_TRACE_END_FLAG(PW_TRACE_FLAGS, __VA_ARGS__) |
| |
| // PW_TRACE_END_FLAG(flag, label) |
| // PW_TRACE_END_FLAG(flag, label, group) |
| // PW_TRACE_END_FLAG(flag, label, group, trace_id) |
| // |
| // Is the same as PW_TRACE_END but uses the provided flag value instead of |
| // PW_TRACE_FLAGS. The flag goes at the start, group and trace_id are still |
| // optional. |
| #define PW_TRACE_END_FLAG(...) \ |
| PW_DELEGATE_BY_ARG_COUNT(_PW_TRACE_END_ARGS, __VA_ARGS__) |
| |
| // PW_TRACE_END_DATA(label, data_format_string, data, size) |
| // PW_TRACE_END_DATA(label, group, data_format_string, data, size) |
| // PW_TRACE_END_DATA(label, group, trace_id, data_format_string, data, size) |
| // |
| // These macros mirror PW_TRACE_END but introduce arguments to specify a |
| // user-supplied data buffer to append to the trace event. |
| // |
| // NOTE: A trace duration start/end can be combined with a duration data |
| // start/end, to include data at only one of the trace points and not the other. |
| // |
| // Arguments: |
| // data_format_string: A string which is used by the decoder to identify the |
| // data. This could for example be either be printf style |
| // tokens, python struct packed fmt string or a custom |
| // label recognized by the decoder. |
| // data: A pointer to a buffer of arbitrary caller-provided data (void*). |
| // size: The size of the data (size_t). |
| #define PW_TRACE_END_DATA(...) \ |
| PW_TRACE_END_DATA_FLAG(PW_TRACE_FLAGS, __VA_ARGS__) |
| |
| // PW_TRACE_END_DATA_FLAG(flag, label, data_format_string, data, size) |
| // PW_TRACE_END_DATA_FLAG(flag, label, group, data_format_string, data, size) |
| // PW_TRACE_END_DATA_FLAG(flag, |
| // label, |
| // group, |
| // trace_id, |
| // data_format_string, |
| // data, |
| // size) |
| // |
| // These macros mirror PW_TRACE_END_DATA but intruduce the flag argument to |
| // specify a flag value which is used instead of PW_TRACE_FLAGS. The flag goes |
| // at the start, group and trace_id arguments are still optional. |
| // |
| // Arguments: |
| // data_format_string: A string which is used by the decoder to identify the |
| // data. This could for example be either be printf style |
| // tokens, python struct packed fmt string or a custom |
| // label recognized by the decoder. |
| // data: A pointer to a buffer of arbitrary caller-provided data (void*). |
| // size: The size of the data (size_t). |
| #define PW_TRACE_END_DATA_FLAG(...) \ |
| PW_DELEGATE_BY_ARG_COUNT(_PW_TRACE_END_DATA_ARGS, __VA_ARGS__) |
| |
| #ifdef __cplusplus |
| |
| // PW_TRACE_SCOPE(label) |
| // PW_TRACE_SCOPE(label, group) |
| // PW_TRACE_SCOPE(label, group, trace_id) |
| // |
| // C++ Scope API measures durations until the object loses scope. |
| // This can for example, provide a convenient method of tracing |
| // functions or loops. |
| // |
| // Arguments: |
| // label: A string literal which desribes the trace |
| // group <optional>: A string literal which groups this trace with others in |
| // the same module and group. |
| // trace_id <optional>: A runtime uint32_t which groups this trace with |
| // others with the same module group and trace_id. |
| // Every trace with a trace_id must also have a group. |
| // Example: |
| // { |
| // PW_TRACE_SCOPE("Bar"); |
| // // Do some stuff |
| // } |
| // |
| // { |
| // PW_TRACE_SCOPE("Group", "Foo"); |
| // { |
| // PW_TRACE_SCOPE("Group", "SubFoo"); |
| // // Do some stuff |
| // } |
| // // Do some stuff |
| // } |
| // |
| // Which can be visualized as |
| // Bar: [----------------Bar----------------] |
| // Group: [----------------Foo----------------] |
| // [------SubFoo-------] |
| #ifndef PW_TRACE_SCOPE |
| #define PW_TRACE_SCOPE(...) PW_TRACE_SCOPE_FLAG(PW_TRACE_FLAGS, __VA_ARGS__) |
| #endif // PW_TRACE_SCOPE |
| // PW_TRACE_SCOPE_FLAG(flag, label) |
| // PW_TRACE_SCOPE_FLAG(flag, label, group) |
| // PW_TRACE_SCOPE_FLAG(flag, label, group, trace_id) |
| // |
| // These macros mirror PW_TRACE_SCOPE but intruduce the flag argument to |
| // specify a flag value which is used instead of PW_TRACE_FLAGS. The flag goes |
| // at the start, group and trace_id arguments are still optional. |
| #ifndef PW_TRACE_SCOPE_FLAG |
| #define PW_TRACE_SCOPE_FLAG(...) \ |
| PW_DELEGATE_BY_ARG_COUNT(_PW_TRACE_SCOPE_ARGS, __VA_ARGS__) |
| #endif // PW_TRACE_SCOPE_FLAG |
| |
| // PW_TRACE_FUNCTION() |
| // PW_TRACE_FUNCTION(group) |
| // PW_TRACE_FUNCTION(group, trace_id) |
| // |
| // C++ Function API measures durations until the function returns. |
| // This is the same as PW_TRACE_SCOPE, but uses the function name as the label. |
| // |
| // Arguments: |
| // group <optional>: A string literal which groups this trace with others in |
| // the same module and group. |
| // trace_id <optional>: A runtime uint32_t which groups this trace with |
| // others with the same module group and trace_id. |
| // Every trace with a trace_id must also have a group. |
| // Example: |
| // void Bar() { |
| // PW_TRACE_FUNCTION(); |
| // // Do some stuff |
| // } |
| // |
| // void Child() { |
| // PW_TRACE_FUNCTION("Group"); |
| // // Do some stuff |
| // } |
| // |
| // void Parent() { |
| // PW_TRACE_FUNCTION("Group"); |
| // // Do some stuff |
| // Child(); |
| // } |
| // |
| // Which can be visualized as |
| // Bar: [----------------Bar----------------] |
| // Group: [----------------Parent----------------] |
| // [------Child-------] |
| #ifndef PW_TRACE_FUNCTION |
| #define PW_TRACE_FUNCTION(...) \ |
| PW_DELEGATE_BY_ARG_COUNT(_PW_TRACE_FUNCTION_ARGS, __VA_ARGS__) |
| // PW_TRACE_FUNCTION_FLAG(PW_TRACE_FLAGS, __VA_ARGS__) |
| #endif // PW_TRACE_FUNCTION |
| |
| // PW_TRACE_FUNCTION_FLAG(flag) |
| // PW_TRACE_FUNCTION_FLAG(flag, group) |
| // PW_TRACE_FUNCTION_FLAG(flag, group, trace_id) |
| // |
| // These macros mirror PW_TRACE_FUNCTION but intruduce the flag argument to |
| // specify a flag value which is used instead of PW_TRACE_FLAGS. The flag goes |
| // at the start, group and trace_id arguments are still optional. |
| #ifndef PW_TRACE_FUNCTION_FLAG |
| #define PW_TRACE_FUNCTION_FLAG(...) \ |
| PW_DELEGATE_BY_ARG_COUNT(_PW_TRACE_FUNCTION_FLAGS_ARGS, __VA_ARGS__) |
| #endif // PW_TRACE_FUNCTION_FLAG |
| |
| #endif // __cplusplus |
