pw_trace: tokenizer trigger example
Uses the trace sample app to demonstrate how to use trace events as
triggrs to capture a specific sequence of events. in this case the
example captures all events when handling job 3 of the sample app.
Change-Id: Ib278ad5318f428e1dee8813fd0d6cff9b77b1c1a
Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/13921
Commit-Queue: Rob Oliver <rgoliver@google.com>
Reviewed-by: (☞ﾟ∀ﾟ)☞ Tennessee Carmel-Veilleux <tennessee@google.com>
diff --git a/BUILD.gn b/BUILD.gn
index e89bf65..1398351 100644
--- a/BUILD.gn
+++ b/BUILD.gn
@@ -112,6 +112,7 @@
deps += [
"$dir_pw_trace:trace_example_basic",
"$dir_pw_trace_tokenized:trace_tokenized_example_basic",
+ "$dir_pw_trace_tokenized:trace_tokenized_example_trigger",
]
}
}
diff --git a/pw_trace_tokenized/BUILD b/pw_trace_tokenized/BUILD
index c5dfe52..a4c02f1 100644
--- a/pw_trace_tokenized/BUILD
+++ b/pw_trace_tokenized/BUILD
@@ -152,3 +152,14 @@
],
srcs = [ "example/basic.cc" ]
)
+
+pw_cc_binary(
+ name = "trace_tokenized_example_trigger",
+ deps = [
+ ":pw_trace_example_to_file",
+ "//pw_log",
+ "//dir_pw_trace",
+ "//dir_pw_trace:pw_trace_sample_app",
+ ],
+ srcs = [ "example/trigger.cc" ]
+)
diff --git a/pw_trace_tokenized/BUILD.gn b/pw_trace_tokenized/BUILD.gn
index 97892fb..a8baa57 100644
--- a/pw_trace_tokenized/BUILD.gn
+++ b/pw_trace_tokenized/BUILD.gn
@@ -140,3 +140,13 @@
]
sources = [ "example/basic.cc" ]
}
+
+pw_executable("trace_tokenized_example_trigger") {
+ deps = [
+ ":trace_example_to_file",
+ "$dir_pw_log",
+ "$dir_pw_trace",
+ "$dir_pw_trace:trace_sample_app",
+ ]
+ sources = [ "example/trigger.cc" ]
+}
diff --git a/pw_trace_tokenized/docs.rst b/pw_trace_tokenized/docs.rst
index 61715fc..aeee29e 100644
--- a/pw_trace_tokenized/docs.rst
+++ b/pw_trace_tokenized/docs.rst
@@ -194,3 +194,11 @@
-----
The basic example turns on tracing and dumps all trace output to a file provided
on the command line.
+
+Trigger
+-------
+The trigger example demonstrates how a trace event can be used as a trigger to
+start and stop capturing a trace. The examples makes use of `PW_TRACE_REF` and
+`PW_TRACE_REF_DATA` to specify a start and stop event for the capture. This can
+be useful if the trace buffer is small and you wish to capture a specific
+series of events.
diff --git a/pw_trace_tokenized/example/trigger.cc b/pw_trace_tokenized/example/trigger.cc
new file mode 100644
index 0000000..8cfaa19
--- /dev/null
+++ b/pw_trace_tokenized/example/trigger.cc
@@ -0,0 +1,95 @@
+// 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.
+//==============================================================================
+// BUID
+// ninja -C out
+// host_clang_debug/obj/pw_trace_tokenized/bin/trace_tokenized_example_trigger
+//
+// RUN
+// .out/host_clang_debug/obj/pw_trace_tokenized/bin/trace_tokenized_example_trigger
+// trace.bin
+//
+// DECODE
+// python pw_trace_tokenized/py/trace_tokenized.py -i trace.bin -o trace.json
+// ./out/host_clang_debug/obj/pw_trace_tokenized/bin/trace_tokenized_example_basic
+//
+// VIEW
+// In chrome navigate to chrome://tracing, and load the trace.json file.
+
+#include "pw_log/log.h"
+#include "pw_trace/example/sample_app.h"
+#include "pw_trace/trace.h"
+#include "pw_trace_tokenized/example/trace_to_file.h"
+#include "pw_trace_tokenized/trace_callback.h"
+#include "pw_trace_tokenized/trace_tokenized.h"
+
+namespace {
+
+constexpr uint32_t kTriggerId = 3;
+constexpr uint32_t kTriggerStartTraceRef =
+ PW_TRACE_REF_DATA(PW_TRACE_TYPE_ASYNC_START,
+ "Processing", // Module
+ "Job", // Label
+ PW_TRACE_FLAGS_DEFAULT,
+ "Process",
+ "@pw_py_struct_fmt:B");
+constexpr uint32_t kTriggerEndTraceRef = PW_TRACE_REF(PW_TRACE_TYPE_ASYNC_END,
+ "Processing", // Module
+ "Job", // Label
+ PW_TRACE_FLAGS_DEFAULT,
+ "Process");
+
+} // namespace
+
+pw_trace_TraceEventReturnFlags TraceEventCallback(void* user_data,
+ uint32_t trace_ref,
+ pw_trace_EventType event_type,
+ const char* module,
+ uint32_t trace_id,
+ uint8_t flags) {
+ PW_UNUSED(user_data);
+ PW_UNUSED(event_type);
+ PW_UNUSED(module);
+ PW_UNUSED(flags);
+ if (trace_ref == kTriggerStartTraceRef && trace_id == kTriggerId) {
+ PW_LOG_INFO("Trace capture started!");
+ PW_TRACE_SET_ENABLED(true);
+ }
+ if (trace_ref == kTriggerEndTraceRef && trace_id == kTriggerId) {
+ PW_LOG_INFO("Trace capture ended!");
+ return PW_TRACE_EVENT_RETURN_FLAGS_DISABLE_AFTER_PROCESSING;
+ }
+ return 0;
+}
+
+int main(int argc, char** argv) { // Take filename as arg
+ if (argc != 2) {
+ PW_LOG_ERROR("Expected output file name as argument.\n");
+ return -1;
+ }
+
+ // Register trigger callback
+ pw::trace::Callbacks::Instance().RegisterEventCallback(
+ TraceEventCallback, pw::trace::CallbacksImpl::kCallOnEveryEvent);
+
+ // Ensure tracing is off at start, the trigger will turn it on.
+ PW_TRACE_SET_ENABLED(false);
+
+ // Dump trace data to the file passed in.
+ pw::trace::TraceToFile trace_to_file(argv[1]);
+
+ PW_LOG_INFO("Running trigger example...");
+ RunTraceSampleApp();
+ return 0;
+}
\ No newline at end of file
