From 739e082469038768291810d6b37525d89cae14d3 Mon Sep 17 00:00:00 2001
From: Thorsten de Buhr <thorsten.deBuhr@arm.com>
Date: Fri, 4 Sep 2026 11:23:25 +0200
Subject: [PATCH] feat(ctrace): decode Armv8-M DWT match packets

---
 tools/ctrace/src/decode/DwtPacketDecoder.cpp  |  16 ++++++
 tools/ctrace/src/model/TraceEvent.h           |  12 +++--
 tools/ctrace/src/model/TraceSelection.cpp     |   6 +++
 tools/ctrace/src/output/csv/CsvRowMapper.cpp  |   2 +
 tools/ctrace/src/output/ctf/CtfEncoder.cpp    |  17 +++++++
 tools/ctrace/src/output/ctf/CtfEncoder.h      |   2 +
 .../src/output/ctf/CtfMetadataWriter.cpp      |  21 ++++++++
 tools/ctrace/src/output/ctf/CtfSchema.h       |   3 ++
 .../src/output/ctf/TraceCompassXmlWriter.cpp  |  35 +++++++++++++
 tools/ctrace/test/data/README.md              |  10 ++++
 .../trace-match/trace-match.ctrace-run.yml    |  47 ++++++++++++++++++
 .../test/data/trace-match/trace-match.raw     | Bin 0 -> 18 bytes
 .../test/integration/src/CtraceIntegTests.cpp |  46 +++++++++++++++++
 .../unit/src/decode/DwtPacketDecoderTests.cpp |  42 ++++++++++++++++
 .../unit/src/model/TraceSelectionTests.cpp    |   4 ++
 .../unit/src/output/csv/CsvRowMapperTests.cpp |   3 ++
 .../unit/src/output/ctf/CtfEncoderTests.cpp   |  32 ++++++++++++
 .../src/output/ctf/CtfMetadataWriterTests.cpp |  19 ++++++-
 .../unit/src/output/ctf/CtfSchemaTests.cpp    |   3 +-
 .../ctrace/test/unit/support/CtfTestSupport.h |   3 ++
 20 files changed, 317 insertions(+), 6 deletions(-)
 create mode 100644 tools/ctrace/test/data/trace-match/trace-match.ctrace-run.yml
 create mode 100644 tools/ctrace/test/data/trace-match/trace-match.raw

diff --git a/tools/ctrace/src/decode/DwtPacketDecoder.cpp b/tools/ctrace/src/decode/DwtPacketDecoder.cpp
index 562f77dd7..b64dfa165 100644
--- a/tools/ctrace/src/decode/DwtPacketDecoder.cpp
+++ b/tools/ctrace/src/decode/DwtPacketDecoder.cpp
@@ -55,6 +55,8 @@ constexpr std::uint32_t kPmuOverflowMask = 0xffU;
 
 constexpr std::uint8_t kArmv7MFullPcBytes = 4U;
 constexpr std::uint8_t kArmv7MAddressOffsetBytes = 2U;
+constexpr std::uint8_t kArmv8MMatchBytes = 1U;
+constexpr std::uint32_t kArmv8MMatchValue = 1U;
 
 /** @brief Describes an invalid DWT event-counter payload. */
 static std::string invalidEventCounterMessage(const DwtPayloadPacket& payload)
@@ -244,6 +246,20 @@ void DwtPacketDecoder::decodeDataTrace(const DwtPayloadPacket& payload, std::vec
   event.quality = payload.quality;
 
   if (packetType == DwtDataPacketType::Address) {
+    const auto isMatch = !secondarySubtype && payload.size == kArmv8MMatchBytes && payload.value == kArmv8MMatchValue;
+    if (isMatch) {
+      auto& pending = m_pendingDataTrace[comparator];
+      if (pending.has_value()) {
+        flushPending(comparator, qualityForPendingFlush(*pending, payload.quality), payload.tcyc, output);
+      }
+      TraceEvent match{DwtMatchTraceEvent{comparator}};
+      match.index = payload.index;
+      match.traceBusId = payload.traceBusId;
+      match.tcyc = payload.tcyc;
+      match.quality = payload.quality;
+      output.push_back(std::move(match));
+      return;
+    }
     const auto expectedSize = secondarySubtype ? kArmv7MAddressOffsetBytes : kArmv7MFullPcBytes;
     if (payload.size != expectedSize) {
       auto flushed = flush(payload.quality, payload.tcyc);
diff --git a/tools/ctrace/src/model/TraceEvent.h b/tools/ctrace/src/model/TraceEvent.h
index 16fd27e1a..5e6706171 100644
--- a/tools/ctrace/src/model/TraceEvent.h
+++ b/tools/ctrace/src/model/TraceEvent.h
@@ -95,6 +95,11 @@ struct DwtAddressTraceEvent {
   DwtAddressTraceLocation location;
 };
 
+/** @brief Reports that one DWT comparator generated a match without additional trace data. */
+struct DwtMatchTraceEvent {
+  std::uint32_t comparator = 0;
+};
+
 /** @brief Returns the program counter carried by a DWT address event, if present. */
 inline std::optional<std::uint32_t> dwtAddressPc(const DwtAddressTraceEvent& event)
 {
@@ -230,9 +235,10 @@ struct TraceIssueEvent {
 };
 
 /** @brief Stores the semantic payload of a decoded trace event. */
-using TraceEventPayload = std::variant<SoftwareTraceEvent, DwtDataTraceEvent, DwtAddressTraceEvent, ExceptionTraceEvent,
-                                       DwtEventTraceEvent, PmuTraceEvent, PcSampleTraceEvent, LocalTimestampTraceEvent,
-                                       GlobalTimestampTraceEvent, OverflowTraceEvent, SyncTraceEvent, TraceIssueEvent>;
+using TraceEventPayload =
+    std::variant<SoftwareTraceEvent, DwtDataTraceEvent, DwtAddressTraceEvent, DwtMatchTraceEvent, ExceptionTraceEvent,
+                 DwtEventTraceEvent, PmuTraceEvent, PcSampleTraceEvent, LocalTimestampTraceEvent,
+                 GlobalTimestampTraceEvent, OverflowTraceEvent, SyncTraceEvent, TraceIssueEvent>;
 
 /** @brief Describes timestamp and data-loss quality at an event. */
 struct TraceQuality {
diff --git a/tools/ctrace/src/model/TraceSelection.cpp b/tools/ctrace/src/model/TraceSelection.cpp
index 2fafbb4b5..c0a7d223e 100644
--- a/tools/ctrace/src/model/TraceSelection.cpp
+++ b/tools/ctrace/src/model/TraceSelection.cpp
@@ -36,6 +36,12 @@ static std::optional<TraceEventType> typeFor(const DwtAddressTraceEvent&)
   return TraceEventType::Dwt;
 }
 
+/** @brief Maps a comparator-only DWT match payload to data trace output. */
+static std::optional<TraceEventType> typeFor(const DwtMatchTraceEvent&)
+{
+  return TraceEventType::Dwt;
+}
+
 /** @brief Maps an exception payload to its selectable event type. */
 static std::optional<TraceEventType> typeFor(const ExceptionTraceEvent&)
 {
diff --git a/tools/ctrace/src/output/csv/CsvRowMapper.cpp b/tools/ctrace/src/output/csv/CsvRowMapper.cpp
index f5b5d557d..c2ad981fe 100644
--- a/tools/ctrace/src/output/csv/CsvRowMapper.cpp
+++ b/tools/ctrace/src/output/csv/CsvRowMapper.cpp
@@ -170,6 +170,8 @@ static CsvRow eventToCsvRow(const TraceEvent& event)
     if (const auto offset = dwtAddressOffset(*address)) {
       row[column(CsvColumn::Offset)] = hexValue(*offset, 2);
     }
+  } else if (const auto* match = traceEventPayload<DwtMatchTraceEvent>(event)) {
+    row[column(CsvColumn::Source)] = std::to_string(match->comparator);
   } else if (const auto* exception = traceEventPayload<ExceptionTraceEvent>(event)) {
     row[column(CsvColumn::Source)] = std::to_string(exception->number);
     row[column(CsvColumn::Value)] = exceptionActionCsvValue(exception->action);
diff --git a/tools/ctrace/src/output/ctf/CtfEncoder.cpp b/tools/ctrace/src/output/ctf/CtfEncoder.cpp
index e83475920..3f0494bac 100644
--- a/tools/ctrace/src/output/ctf/CtfEncoder.cpp
+++ b/tools/ctrace/src/output/ctf/CtfEncoder.cpp
@@ -200,6 +200,10 @@ void CtfEncoder::writeEvent(const TraceEvent& event)
     if (selected) {
       writeDwtAddrEvent(event, *address);
     }
+  } else if (const auto* match = traceEventPayload<DwtMatchTraceEvent>(event)) {
+    if (selected) {
+      writeDwtMatchEvent(event, *match);
+    }
   } else if (const auto* counters = traceEventPayload<DwtEventTraceEvent>(event)) {
     if (selected) {
       writeDwtEvent(event, *counters);
@@ -363,6 +367,19 @@ void CtfEncoder::writeDwtAddrEvent(const TraceEvent& event, const DwtAddressTrac
                        });
 }
 
+void CtfEncoder::writeDwtMatchEvent(const TraceEvent& event, const DwtMatchTraceEvent& match)
+{
+  constexpr auto payloadSize = 1U + 1U + 4U;
+  const auto eventTimestamp = allocateEventTimestamp(event.traceBusId);
+  const auto quality = computeSampleQuality(event);
+  m_stream.writeRecord(CtfSchema::value(CtfSchema::EventId::DwtMatch), eventTimestamp, event.traceBusId, payloadSize,
+                       [&](CtfStreamWriter::Record& record) {
+                         record.writeU8(static_cast<std::uint8_t>(match.comparator & 0xffU));
+                         record.writeU8(quality.first);
+                         record.writeU32(quality.second);
+                       });
+}
+
 void CtfEncoder::writeDwtEvent(const TraceEvent& event, const DwtEventTraceEvent& counters)
 {
   constexpr auto payloadSize = 1U + 1U + 4U;
diff --git a/tools/ctrace/src/output/ctf/CtfEncoder.h b/tools/ctrace/src/output/ctf/CtfEncoder.h
index 594fcff89..265549007 100644
--- a/tools/ctrace/src/output/ctf/CtfEncoder.h
+++ b/tools/ctrace/src/output/ctf/CtfEncoder.h
@@ -75,6 +75,8 @@ class CtfEncoder final {
   void reportDwtSizeMismatch(const TraceEvent& event, const DwtDataTraceEvent& data, const ResolvedTraceSource* source);
   /** @brief Encodes one DWT address event. */
   void writeDwtAddrEvent(const TraceEvent& event, const DwtAddressTraceEvent& address);
+  /** @brief Encodes one comparator-only DWT match event. */
+  void writeDwtMatchEvent(const TraceEvent& event, const DwtMatchTraceEvent& match);
   /** @brief Expands one DWT event-counter mask into individual CTF records. */
   void writeDwtEvent(const TraceEvent& event, const DwtEventTraceEvent& counters);
   /** @brief Expands one PMU trace-on-overflow mask into individual CTF records. */
diff --git a/tools/ctrace/src/output/ctf/CtfMetadataWriter.cpp b/tools/ctrace/src/output/ctf/CtfMetadataWriter.cpp
index 68e132ff0..60d115c9c 100644
--- a/tools/ctrace/src/output/ctf/CtfMetadataWriter.cpp
+++ b/tools/ctrace/src/output/ctf/CtfMetadataWriter.cpp
@@ -440,6 +440,26 @@ event {
 )";
 }
 
+/** @brief Writes the comparator-only DWT match event declaration. */
+static void writeDwtMatchEvent(std::ostream& out)
+{
+  out << R"(
+event {
+    id = )"
+      << CtfSchema::value(CtfSchema::EventId::DwtMatch) << R"(;
+    name = ")"
+      << CtfSchema::eventName(CtfSchema::EventId::DwtMatch) << R"(";
+    stream_id = )"
+      << CtfSchema::SwoStreamId << R"(;
+    fields := struct {
+        cmsis_dwt_comparator_t cmsis_dwt_comparator;
+        uint8_t cmsis_sample_flags;
+        uint32_t cmsis_overflow_count;
+    };
+};
+)";
+}
+
 /** @brief Writes the DWT event-counter declaration. */
 static void writeDwtEvent(std::ostream& out)
 {
@@ -565,6 +585,7 @@ void CtfMetadataWriter::write(const std::filesystem::path& outputDir, const std:
   writeItmEvent(out);
   writeDwtValueEvent(out);
   writeDwtAddressEvent(out);
+  writeDwtMatchEvent(out);
   writeDwtEvent(out);
   writePmuEvent(out);
   writeStatusEvents(out);
diff --git a/tools/ctrace/src/output/ctf/CtfSchema.h b/tools/ctrace/src/output/ctf/CtfSchema.h
index 343602045..a71427484 100644
--- a/tools/ctrace/src/output/ctf/CtfSchema.h
+++ b/tools/ctrace/src/output/ctf/CtfSchema.h
@@ -31,6 +31,7 @@ enum class EventId : std::uint32_t {
   PcSample = 6U,
   DwtEvent = 7U,
   PmuEvent = 8U,
+  DwtMatch = 9U,
 };
 
 /** @brief Classifies CTF trace-status records. */
@@ -255,6 +256,8 @@ constexpr std::string_view eventName(EventId id)
     return "DWT_EVENT";
   case EventId::PmuEvent:
     return "PMU_EVENT";
+  case EventId::DwtMatch:
+    return "DWT_MATCH";
   }
   return "UNKNOWN";
 }
diff --git a/tools/ctrace/src/output/ctf/TraceCompassXmlWriter.cpp b/tools/ctrace/src/output/ctf/TraceCompassXmlWriter.cpp
index a8a59b5b3..6315b0c06 100644
--- a/tools/ctrace/src/output/ctf/TraceCompassXmlWriter.cpp
+++ b/tools/ctrace/src/output/ctf/TraceCompassXmlWriter.cpp
@@ -133,6 +133,30 @@ static std::string eventCounterHandlers(CtfSchema::EventId eventId, std::string_
   return handlers.str();
 }
 
+/** @brief Generates one visible pulse for every comparator-only DWT match. */
+static std::string dwtMatchHandler()
+{
+  std::ostringstream handler;
+  handler << R"(            <stateChange>
+                <stateAttribute type="constant" value=")"
+          << CtfSchema::eventName(CtfSchema::EventId::DwtMatch) << R"(" />
+                <stateAttribute type="eventField" value="cmsis_dwt_comparator" />
+                <stateValue type="int" value="1" stack="push" />
+            </stateChange>
+            <stateChange>
+                <stateAttribute type="constant" value=")"
+          << CtfSchema::eventName(CtfSchema::EventId::DwtMatch) << R"(" />
+                <stateAttribute type="eventField" value="cmsis_dwt_comparator" />
+                <stateValue type="null" stack="pop" />
+                <futureTime type="script" value="timestamp + )"
+          << kEventPulseNanoseconds << R"(" scriptEngine="rhino">
+                    <stateValue id="timestamp" type="eventField" value="timestamp" />
+                </futureTime>
+            </stateChange>
+)";
+  return handler.str();
+}
+
 /** @brief Generates the Trace Compass state-provider definition. */
 static std::string stateProviderXml()
 {
@@ -159,6 +183,10 @@ static std::string stateProviderXml()
         <eventHandler eventName=")"
       << CtfSchema::eventName(CtfSchema::EventId::Itm) << R"(">
 )" << valueHandlers(CtfSchema::EventId::Itm, "itm", "cmsis_itm_channel", "value")
+      << R"(        </eventHandler>
+        <eventHandler eventName=")"
+      << CtfSchema::eventName(CtfSchema::EventId::DwtMatch) << R"(">
+)" << dwtMatchHandler()
       << R"(        </eventHandler>
         <eventHandler eventName=")"
       << CtfSchema::eventName(CtfSchema::EventId::DwtEvent) << R"(">
@@ -380,6 +408,13 @@ static std::string viewsXml()
       << CtfSchema::eventName(CtfSchema::EventId::DwtAddress)
       << '/' << R"(*"><display type="constant" value="address" /><name type="self" /></entry>
     </xyView>
+    <timeGraphView id="arm.cmsis.swo.tg.dwt_match.v1">
+        <head><analysis id="arm.cmsis.swo.analysis.v1" /><label value="DWT Match" /></head>
+        <definedValue name="Something happened" value="1" color="#F6BD16" />
+        <entry path=")"
+      << CtfSchema::eventName(CtfSchema::EventId::DwtMatch)
+      << '/' << R"(*" displayText="true"><display type="constant" value="1" /><name type="self" /></entry>
+    </timeGraphView>
     <timeGraphView id="arm.cmsis.swo.tg.dwt_event.v1">
         <head><analysis id="arm.cmsis.swo.analysis.v1" /><label value="DWT Event Counters" /></head>
 )";
diff --git a/tools/ctrace/test/data/README.md b/tools/ctrace/test/data/README.md
index f4fef1e54..66dfb7ff1 100644
--- a/tools/ctrace/test/data/README.md
+++ b/tools/ctrace/test/data/README.md
@@ -49,6 +49,16 @@ packet preservation and bitwise CTF expansion across the boundary.
 - Raw capture excerpt: `97807dad2f69b1274df8960d3459426d1da4a6892d05e7623f3e16f06c5d85c8`
 - Trace-run YAML: `a7b924d89854ac85e2751d1297ec78783fa12cb3fa54f5638691dd48d546a34e`
 
+The `trace-match` fixture is completely synthetic. It was generated from the
+Armv8-M ITM and DWT packet definitions and was not captured from real hardware.
+It contains a hardware synchronization packet followed by one Data Trace Match
+packet for each comparator 0 through 3 and local timestamps. The integration
+test verifies the generated CSV rows, CTF records, labels, and Trace Compass
+timeline configuration.
+
+- Generated raw trace: `5cffb5803675dc02ecd5ed4939a42c660ad7cabd3542b8ca1506230e20d14a50`
+- Generated trace-run YAML: `b40c10634b8ba335b14b75f0026758ad84dd68aaf68f0a1bbfd2a5745756c5e8`
+
 `trace-run` contains only the small current-schema inputs needed by executable
 tests. Reader unit tests cover only the fields consumed by ctrace. A C++
 entry-point test creates a reviewable eight-byte ITM stream below the build tree
diff --git a/tools/ctrace/test/data/trace-match/trace-match.ctrace-run.yml b/tools/ctrace/test/data/trace-match/trace-match.ctrace-run.yml
new file mode 100644
index 000000000..8bc8b8ad6
--- /dev/null
+++ b/tools/ctrace/test/data/trace-match/trace-match.ctrace-run.yml
@@ -0,0 +1,47 @@
+ctrace-run:
+  generated-by: synthetic Armv8-M DWT match fixture
+  ctrace-setup:
+    - timestamps:
+        clock: 1000000
+      data:
+        - location: 0x20000000
+          label: Match Comparator 0
+          output: match
+        - location: 0x20000004
+          label: Match Comparator 1
+          output: match
+        - location: 0x20000008
+          label: Match Comparator 2
+          output: match
+        - location: 0x2000000C
+          label: Match Comparator 3
+          output: match
+  ctrace-refs:
+    - ctrace-ref: data#0
+      type: dwt
+      label: Match Comparator 0
+      address: 0x20000000
+      size: 4
+      data-type: unsigned
+      source: 0
+    - ctrace-ref: data#1
+      type: dwt
+      label: Match Comparator 1
+      address: 0x20000004
+      size: 4
+      data-type: unsigned
+      source: 1
+    - ctrace-ref: data#2
+      type: dwt
+      label: Match Comparator 2
+      address: 0x20000008
+      size: 4
+      data-type: unsigned
+      source: 2
+    - ctrace-ref: data#3
+      type: dwt
+      label: Match Comparator 3
+      address: 0x2000000C
+      size: 4
+      data-type: unsigned
+      source: 3
diff --git a/tools/ctrace/test/data/trace-match/trace-match.raw b/tools/ctrace/test/data/trace-match/trace-match.raw
new file mode 100644
index 0000000000000000000000000000000000000000..8ccf552bce88878db5366e429cc7af78bca0647f
GIT binary patch
literal 18
XcmZQz0D=ZrMuAX9g;Yj^Qbq>=6Cwhc

literal 0
HcmV?d00001

diff --git a/tools/ctrace/test/integration/src/CtraceIntegTests.cpp b/tools/ctrace/test/integration/src/CtraceIntegTests.cpp
index 45d325561..af5b6f215 100644
--- a/tools/ctrace/test/integration/src/CtraceIntegTests.cpp
+++ b/tools/ctrace/test/integration/src/CtraceIntegTests.cpp
@@ -178,6 +178,52 @@ TEST_F(CtraceIntegTests, ExpandsDwtEventCountersAcrossCsvAndCtf)
                  "<label value=\"DWT Event Counters\" />");
 }
 
+TEST_F(CtraceIntegTests, ConvertsDwtMatchAcrossCsvAndCtf)
+{
+  const auto fixtureDirectory = testDataDirectory() / "trace-match";
+  copyFixtureFile(fixtureDirectory, "trace-match.raw", "trace-match.SWO.raw");
+  copyFixtureFile(fixtureDirectory, "trace-match.ctrace-run.yml");
+
+  // This Armv8-M packet stream is completely synthetic and was generated from
+  // the architecture specification without a capture from real hardware.
+  constexpr std::array<unsigned char, 18U> expectedRaw{{
+      0x00U, 0x00U, 0x00U, 0x00U, 0x00U, 0x80U, 0x45U, 0x01U, 0x10U,
+      0x55U, 0x01U, 0x20U, 0x65U, 0x01U, 0x30U, 0x75U, 0x01U, 0x40U,
+  }};
+  EXPECT_EQ(readBinaryFile(workDirectory() / "trace-match.SWO.raw"),
+            std::vector<unsigned char>(expectedRaw.begin(), expectedRaw.end()));
+
+  const auto result = run({"ctrace", workDirectory().string(), "--target", "trace-match", "--all"});
+  EXPECT_EQ(0, result.exitCode) << result.stderrText;
+  EXPECT_EQ("cycles,stream,type,source,value,pc,offset,note\n"
+            "1,,dwt,0,,,,\n"
+            "3,,dwt,1,,,,\n"
+            "6,,dwt,2,,,,\n"
+            "10,,dwt,3,,,,\n",
+            readTextFile(workDirectory() / "trace-match.SWO.csv"));
+
+  const auto records = CtfTestSupport::readCtfRecords(workDirectory() / "trace-match.ctf" / "stream_0");
+  std::vector<std::uint64_t> matchTimestamps;
+  std::vector<std::uint8_t> matchComparators;
+  for (const auto& record : records) {
+    if (record.id != CtfSchema::value(CtfSchema::EventId::DwtMatch)) {
+      continue;
+    }
+    ASSERT_EQ(record.payload.size(), 6U);
+    matchTimestamps.push_back(record.timestamp);
+    matchComparators.push_back(record.payload[0U]);
+  }
+  EXPECT_EQ(matchTimestamps, (std::vector<std::uint64_t>{1U, 3U, 6U, 10U}));
+  EXPECT_EQ(matchComparators, (std::vector<std::uint8_t>{0U, 1U, 2U, 3U}));
+
+  const auto metadata = readTextFile(workDirectory() / "trace-match.ctf" / "metadata");
+  expectContains(metadata, "name = \"DWT_MATCH\"");
+  expectContains(metadata, "\"Match Comparator 3\" = 3");
+  const auto xml = readTextFile(workDirectory() / "trace-match.SWO.traceanalysis.xml");
+  expectContains(xml, "<label value=\"DWT Match\" />");
+  expectContains(xml, "<definedValue name=\"Something happened\" value=\"1\"");
+}
+
 TEST_F(CtraceIntegTests, ConvertsCapturedDwtEventCountersAcrossOverflow)
 {
   const auto fixtureDirectory = testDataDirectory() / "trace-event";
diff --git a/tools/ctrace/test/unit/src/decode/DwtPacketDecoderTests.cpp b/tools/ctrace/test/unit/src/decode/DwtPacketDecoderTests.cpp
index 6767292e2..b3cc33290 100644
--- a/tools/ctrace/test/unit/src/decode/DwtPacketDecoderTests.cpp
+++ b/tools/ctrace/test/unit/src/decode/DwtPacketDecoderTests.cpp
@@ -277,6 +277,48 @@ TEST(CtraceUnitTests, testDwtPacketDecoderPreservesRepeatedAddressFragments)
   verify(9U, 0x1000U, 0x2000U);
 }
 
+TEST(CtraceUnitTests, testDwtPacketDecoderEmitsComparatorOnlyMatch)
+{
+  DwtPacketDecoder decoder;
+  auto payload = dwtPayload(12U, 1U, 1U, 17U, 3U, 99U);
+  payload.quality = TraceQuality{true, false, 7U};
+
+  const auto packets = decoder.decode(payload);
+  ASSERT_EQ(packets.size(), 1U);
+  const auto* match = traceEventPayload<DwtMatchTraceEvent>(packets.front());
+  ASSERT_NE(match, nullptr);
+  EXPECT_EQ(match->comparator, 2U);
+  EXPECT_EQ(packets.front().index, 17U);
+  EXPECT_EQ(packets.front().traceBusId, 3U);
+  EXPECT_EQ(packets.front().tcyc, std::optional<std::uint64_t>(99U));
+  ASSERT_TRUE(packets.front().quality.has_value());
+  EXPECT_TRUE(packets.front().quality->overflow);
+  EXPECT_FALSE(packets.front().quality->timestampReliable);
+  EXPECT_EQ(packets.front().quality->overflowCount, 7U);
+  EXPECT_EQ(traceEventType(packets.front()), TraceEventType::Dwt);
+  EXPECT_EQ(CsvRowMapper::row(packets.front()), "99,3,dwt,2,,,,");
+}
+
+TEST(CtraceUnitTests, testDwtPacketDecoderFlushesPendingComparatorBeforeMatch)
+{
+  DwtPacketDecoder decoder;
+  auto pc = dwtPayload(8U, 4U, 0x08001234U, 10U, 3U, 90U);
+  pc.quality.timestampReliable = true;
+  EXPECT_TRUE(decoder.decode(pc).empty());
+
+  auto match = dwtPayload(8U, 1U, 1U, 11U, 3U, 100U);
+  match.quality.timestampReliable = true;
+  const auto packets = decoder.decode(match);
+  ASSERT_EQ(packets.size(), 2U);
+  ASSERT_NE(traceEventPayload<DwtAddressTraceEvent>(packets[0]), nullptr);
+  EXPECT_EQ(dwtAddressPc(*traceEventPayload<DwtAddressTraceEvent>(packets[0])),
+            std::optional<std::uint32_t>(0x08001234U));
+  EXPECT_NE(traceEventPayload<DwtMatchTraceEvent>(packets[1]), nullptr);
+  EXPECT_EQ(packets[0].tcyc, std::optional<std::uint64_t>(100U));
+  EXPECT_EQ(packets[1].tcyc, std::optional<std::uint64_t>(100U));
+  EXPECT_TRUE(decoder.flush({}, 101U).empty());
+}
+
 TEST(CtraceUnitTests, testDwtPacketDecoderRejectsUnsupportedAddressWidths)
 {
   const auto verify = [](std::uint8_t discriminator, std::uint8_t size) {
diff --git a/tools/ctrace/test/unit/src/model/TraceSelectionTests.cpp b/tools/ctrace/test/unit/src/model/TraceSelectionTests.cpp
index 3c98264f2..44f3e10ca 100644
--- a/tools/ctrace/test/unit/src/model/TraceSelectionTests.cpp
+++ b/tools/ctrace/test/unit/src/model/TraceSelectionTests.cpp
@@ -67,6 +67,10 @@ TEST(CtraceUnitTests, testTraceSelection)
   ASSERT_TRUE(traceEventSelectedForOutput(dwt, TraceSelection{{"itm", "dwt"}, {}}))
       << "TraceSelection type OR mismatch";
 
+  TraceEvent dwtMatch{DwtMatchTraceEvent{2U}};
+  ASSERT_TRUE(traceEventSelectedForOutput(dwtMatch, TraceSelection{{"dwt"}, {}}))
+      << "TraceSelection DWT match type mismatch";
+
   TraceEvent exception{ExceptionTraceEvent{11U, ExceptionAction::Entered}};
   ASSERT_TRUE(traceEventSelectedForOutput(exception, TraceSelection{{"exception"}, {}}))
       << "TraceSelection exception type mismatch";
diff --git a/tools/ctrace/test/unit/src/output/csv/CsvRowMapperTests.cpp b/tools/ctrace/test/unit/src/output/csv/CsvRowMapperTests.cpp
index d887d9fa9..fd133d728 100644
--- a/tools/ctrace/test/unit/src/output/csv/CsvRowMapperTests.cpp
+++ b/tools/ctrace/test/unit/src/output/csv/CsvRowMapperTests.cpp
@@ -39,6 +39,7 @@ TEST(CtraceUnitTests, testCsvRowMapperAndTraceEventSchema)
       {TraceEvent{SoftwareTraceEvent{}}, TraceEventType::Itm},
       {TraceEvent{DwtDataTraceEvent{}}, TraceEventType::Dwt},
       {TraceEvent{DwtAddressTraceEvent{0U, DwtPcTraceLocation{0U}}}, TraceEventType::Dwt},
+      {TraceEvent{DwtMatchTraceEvent{}}, TraceEventType::Dwt},
       {TraceEvent{ExceptionTraceEvent{}}, TraceEventType::Exception},
       {TraceEvent{DwtEventTraceEvent{}}, TraceEventType::Event},
       {TraceEvent{PmuTraceEvent{}}, TraceEventType::Pmu},
@@ -65,6 +66,8 @@ TEST(CtraceUnitTests, testCsvRowMapperAndTraceEventSchema)
       << "CSV must render the raw hexadecimal DWT value with the two-byte SWO width";
   ASSERT_TRUE(CsvRowMapper::row(softwarePacket(1U)) == ",,itm,1,0x00,,,")
       << "CSV must leave the stream field empty for unformatted input";
+  ASSERT_TRUE(CsvRowMapper::row(TraceEvent{DwtMatchTraceEvent{2U}}) == ",,dwt,2,,,,")
+      << "CSV must expose a match only through its DWT comparator source";
   ASSERT_TRUE(CsvRowMapper::row(atCycle(TraceEvent{PcSampleTraceEvent{0x08001234U, false}}, 949339000U)) ==
               "949339000,,pcsample,,,0x08001234,,")
       << "CSV PC-sample row mismatch";
diff --git a/tools/ctrace/test/unit/src/output/ctf/CtfEncoderTests.cpp b/tools/ctrace/test/unit/src/output/ctf/CtfEncoderTests.cpp
index 197b59762..120b2a3ec 100644
--- a/tools/ctrace/test/unit/src/output/ctf/CtfEncoderTests.cpp
+++ b/tools/ctrace/test/unit/src/output/ctf/CtfEncoderTests.cpp
@@ -181,6 +181,38 @@ TEST(CtraceUnitTests, testCtfEncoderExpandsDwtEventCounterMask)
   EXPECT_NE(metadata.find("cmsis_dwt_event_counter_t cmsis_dwt_event_counter;"), std::string::npos);
 }
 
+TEST(CtraceUnitTests, testCtfEncoderWritesDwtMatch)
+{
+  const TemporaryTestPath temporaryPath("ctrace-ctf-dwt-match-test");
+  const auto& outputDirectory = temporaryPath.createDirectory();
+
+  CtfEncoder encoder(CtfEncoderConfig{
+      1000000U,
+      TraceSelection{{"dwt"}, {}},
+      {},
+  });
+  encoder.start(outputDirectory);
+  auto match = onStream(atCycle(TraceEvent{DwtMatchTraceEvent{2U}}, 123U), 3U);
+  match.quality = TraceQuality{true, false, 7U};
+  encoder.writeEvent(match);
+  encoder.stop();
+
+  const auto records = readCtfRecords(outputDirectory / "stream_0");
+  ASSERT_EQ(records.size(), 1U);
+  const auto& record = records.front();
+  EXPECT_EQ(record.id, CtfSchema::value(CtfSchema::EventId::DwtMatch));
+  EXPECT_EQ(record.timestamp, 123U);
+  EXPECT_EQ(record.traceBusId, 3U);
+  ASSERT_EQ(record.payload.size(), 6U);
+  EXPECT_EQ(record.payload[0U], 2U);
+  EXPECT_EQ(record.payload[1U], CtfSchema::SampleFlagOverflow | CtfSchema::SampleFlagBeforeFirstTimestamp);
+  EXPECT_EQ(readLe32(record.payload, 2U), 7U);
+
+  const auto metadata = readTestTextFile(outputDirectory / "metadata");
+  EXPECT_NE(metadata.find("name = \"DWT_MATCH\""), std::string::npos);
+  EXPECT_NE(metadata.find("cmsis_dwt_comparator_t cmsis_dwt_comparator;"), std::string::npos);
+}
+
 TEST(CtraceUnitTests, testCtfEncoderExpandsPmuEventCounterMask)
 {
   const TemporaryTestPath temporaryPath("ctrace-ctf-pmu-event-test");
diff --git a/tools/ctrace/test/unit/src/output/ctf/CtfMetadataWriterTests.cpp b/tools/ctrace/test/unit/src/output/ctf/CtfMetadataWriterTests.cpp
index 436e65e71..c2610f09c 100644
--- a/tools/ctrace/test/unit/src/output/ctf/CtfMetadataWriterTests.cpp
+++ b/tools/ctrace/test/unit/src/output/ctf/CtfMetadataWriterTests.cpp
@@ -90,10 +90,10 @@ TEST(CtraceUnitTests, testTraceCompassXmlUsesCurrentCtfEvents)
   const TemporaryTestPath path("ctrace-trace-compass-schema.xml");
   TraceCompassXmlWriter::writeFile(path.path());
   const auto xml = readTestTextFile(path.path());
-  constexpr std::array<CtfSchema::EventId, 8U> visualizedEvents{
+  constexpr std::array<CtfSchema::EventId, 9U> visualizedEvents{
       CtfSchema::EventId::Itm,       CtfSchema::EventId::DwtValue,    CtfSchema::EventId::DwtAddress,
       CtfSchema::EventId::Exception, CtfSchema::EventId::TraceStatus, CtfSchema::EventId::PcSample,
-      CtfSchema::EventId::DwtEvent,  CtfSchema::EventId::PmuEvent,
+      CtfSchema::EventId::DwtEvent,  CtfSchema::EventId::PmuEvent,    CtfSchema::EventId::DwtMatch,
   };
 
   for (const auto eventId : visualizedEvents) {
@@ -135,6 +135,21 @@ TEST(CtraceUnitTests, testTraceCompassXmlUsesCurrentCtfEvents)
   EXPECT_NE(xml.find("<definedValue name=\"7\" value=\"7\""), std::string::npos);
   EXPECT_NE(xml.find("<entry path=\"PMU_EVENT/" "*\" displayText=\"true\"><display type=\"constant\" value=\"1\" /></entry>"),
             std::string::npos);
+  EXPECT_NE(xml.find("<stateAttribute type=\"constant\" value=\"DWT_MATCH\" />"), std::string::npos);
+  EXPECT_NE(xml.find("<stateAttribute type=\"eventField\" value=\"cmsis_dwt_comparator\" />"),
+            std::string::npos);
+  EXPECT_NE(xml.find("<label value=\"DWT Match\" />"), std::string::npos);
+  EXPECT_NE(xml.find("<definedValue name=\"Something happened\" value=\"1\""), std::string::npos);
+  EXPECT_NE(xml.find("<entry path=\"DWT_MATCH/" "*\" displayText=\"true\"><display type=\"constant\" value=\"1\" />"
+                     "<name type=\"self\" /></entry>"),
+            std::string::npos);
+  const auto matchHandler = xml.find("<eventHandler eventName=\"DWT_MATCH\">");
+  const auto matchHandlerEnd = xml.find("</eventHandler>", matchHandler);
+  ASSERT_NE(matchHandler, std::string::npos);
+  ASSERT_NE(matchHandlerEnd, std::string::npos);
+  const auto matchPulseEnd = xml.find("value=\"timestamp + 1000\"", matchHandler);
+  ASSERT_NE(matchPulseEnd, std::string::npos);
+  EXPECT_LT(matchPulseEnd, matchHandlerEnd);
   const auto threadModeEntry = xml.find("path=\"EXCEPTION/Thread Mode\"");
   const auto returnEntry = xml.find("path=\"EXCEPTION_RETURN/*\" displayText=\"true\"");
   const auto interruptEntries = xml.find("path=\"EXCEPTION/(?!Thread Mode).+\"");
diff --git a/tools/ctrace/test/unit/src/output/ctf/CtfSchemaTests.cpp b/tools/ctrace/test/unit/src/output/ctf/CtfSchemaTests.cpp
index ab2eca416..1daf27bad 100644
--- a/tools/ctrace/test/unit/src/output/ctf/CtfSchemaTests.cpp
+++ b/tools/ctrace/test/unit/src/output/ctf/CtfSchemaTests.cpp
@@ -21,12 +21,13 @@
 
 TEST(CtraceUnitTests, testCtfSchemaUsesDenseIdentifiers)
 {
-  constexpr std::array<std::uint32_t, 9U> eventIds{
+  constexpr std::array<std::uint32_t, 10U> eventIds{
       CtfSchema::value(CtfSchema::EventId::Itm),        CtfSchema::value(CtfSchema::EventId::DwtValue),
       CtfSchema::value(CtfSchema::EventId::DwtAddress), CtfSchema::value(CtfSchema::EventId::TraceStatus),
       CtfSchema::value(CtfSchema::EventId::Exception),  CtfSchema::value(CtfSchema::EventId::GlobalTimestamp),
       CtfSchema::value(CtfSchema::EventId::PcSample),   CtfSchema::value(CtfSchema::EventId::DwtEvent),
       CtfSchema::value(CtfSchema::EventId::PmuEvent),
+      CtfSchema::value(CtfSchema::EventId::DwtMatch),
   };
   constexpr std::array<std::uint8_t, 5U> statusReasons{
       CtfSchema::value(CtfSchema::TraceStatusReason::TraceStart),
diff --git a/tools/ctrace/test/unit/support/CtfTestSupport.h b/tools/ctrace/test/unit/support/CtfTestSupport.h
index 92264ff0f..57c95a409 100644
--- a/tools/ctrace/test/unit/support/CtfTestSupport.h
+++ b/tools/ctrace/test/unit/support/CtfTestSupport.h
@@ -151,6 +151,9 @@ inline std::size_t ctfPayloadSize(const std::vector<unsigned char>& bytes, std::
   if (eventId == CtfSchema::value(CtfSchema::EventId::PmuEvent)) {
     return 6U;
   }
+  if (eventId == CtfSchema::value(CtfSchema::EventId::DwtMatch)) {
+    return 6U;
+  }
   require(false, "CTF test parser encountered an unknown event ID");
   return 0U;
 }