Add instructions on how to add trace events (#16393)

* Add instructions on how to add trace events * Restyled by prettier-markdown * Add words to wordlist Co-authored-by: Restyled.io <[email protected]>
project-chip · Dec 12, 2023 · 6363828 · 6363828
1 parent a147a91
commit 6363828
Show file tree

Hide file tree

Showing 2 changed files with 46 additions and 0 deletions.
diff --git a/.github/.wordlist.txt b/.github/.wordlist.txt
@@ -156,6 +156,7 @@ BTP
 btvirt
 buildwithmatter
 burndown
+ButtonIsr
 BytesMain
 bz
 bzip
@@ -604,6 +605,7 @@ Infineon
 ini
 init
 inlined
+InputLoop
 installDebug
 instantiation
 integrations
@@ -654,6 +656,7 @@ kGroup
 kInvalidCommandId
 KitProg
 kManage
+kNewButton
 kNodeIdNotSpecified
 knownissues
 kOperate
@@ -1080,6 +1083,8 @@ sdl
 SED
 SEGGER
 semver
+SendButton
+SendNewInputEvent
 sendto
 SERIALDEVICE
 SerialNumber
@@ -1307,6 +1312,7 @@ vous
 VPN
 VSC
 VSCode
+WaitNewInputEvent
 WakeOnLan
 WantedBy
 webpage

diff --git a/src/trace/README.md b/src/trace/README.md
@@ -0,0 +1,40 @@
+# Matter tracing
+
+Matter tracing provides a tool for applications to trace information about the
+execution of the application. It depends on
+[pw_trace module](https://pigweed.dev/pw_trace/).
+
+## How to add trace events
+
+1. Include "trace/trace.h" in the source file.
+2. Add "\${chip_root}/src/trace" as deps in BUILD.gn.
+3. Add MATTER*TRACE_EVENT*\* in functions to be traced.
+
+## Example
+
+```
+#include "pw_trace/trace.h"
+
+  void SendButton() {
+    MATTER_TRACE_EVENT_FUNCTION();
+    // do something
+  }
+
+  void InputLoop() {
+    while(1) {
+      auto event = WaitNewInputEvent()
+      MATTER_TRACE_EVENT_SCOPE("Handle Event");  // measure until loop finished
+      if (event == kNewButton){
+        SendButton();
+        MATTER_TRACE_EVENT_END("button");  // Trace event was started in ButtonIsr
+      } else {
+        MATTER_TRACE_EVENT_INSTANT("Unknown event");
+      }
+    }
+  }
+
+  void ButtonIsr() {
+    MATTER_TRACE_EVENT_START("button");
+    SendNewInputEvent(kNewButton);
+  }
+```