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 <commits@restyled.io>

.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

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);
+  }
+```