From 63638289d51e2d43022d25e3b85869830d3a80de Mon Sep 17 00:00:00 2001
From: Yuanyao Zhong <82843247+yyzhong-g@users.noreply.github.com>
Date: Thu, 17 Mar 2022 23:36:49 -0400
Subject: [PATCH] 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 |  6 ++++++
 src/trace/README.md   | 40 ++++++++++++++++++++++++++++++++++++++++
 2 files changed, 46 insertions(+)
 create mode 100644 src/trace/README.md

diff --git a/.github/.wordlist.txt b/.github/.wordlist.txt
index 4b3359cc8684a4..6bc042eaf8c714 100644
--- 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
new file mode 100644
index 00000000000000..64e699d4b08db0
--- /dev/null
+++ 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);
+  }
+```