From 03e9777c3ff29c9bdaca33facb9eb2bb58df25c6 Mon Sep 17 00:00:00 2001
From: DevTekVE <devtekve@gmail.com>
Date: Sat, 6 Sep 2025 21:05:15 +0200
Subject: [PATCH] Improve debugging for safety (#36055)

* feat: add debugging configurations for replay drive and LLDB attachment

* Add readme with video demo

* clean

* docs: update debugging safety documentation with demo link

* no need for mp4 then added on PR

* Update SConstruct

* bump opendbc

* updating readme

* updating readme

* updating readme

* is this better / worth it?

* final cleanups

* hacky. but does it work?

* Yep that worked!

---------

Co-authored-by: Adeeb Shihadeh <adeebshihadeh@gmail.com>
---
 .vscode/launch.json      | 41 +++++++++++++++++++++++++++++++++++++++-
 docs/DEBUGGING_SAFETY.md | 30 +++++++++++++++++++++++++++++
 2 files changed, 70 insertions(+), 1 deletion(-)
 create mode 100644 docs/DEBUGGING_SAFETY.md

diff --git a/.vscode/launch.json b/.vscode/launch.json
index a6b341d9ea..f090061c42 100644
--- a/.vscode/launch.json
+++ b/.vscode/launch.json
@@ -23,6 +23,11 @@
       "id": "args",
       "description": "Arguments to pass to the process",
       "type": "promptString"
+    },
+    {
+      "id": "replayArg",
+      "type": "promptString",
+      "description": "Enter route or segment to replay."
     }
   ],
   "configurations": [
@@ -40,7 +45,41 @@
       "type": "cppdbg",
       "request": "launch",
       "program": "${workspaceFolder}/${input:cpp_process}",
-      "cwd": "${workspaceFolder}",
+      "cwd": "${workspaceFolder}"
+    },
+    {
+      "name": "Attach LLDB to Replay drive",
+      "type": "lldb",
+      "request": "attach",
+      "pid": "${command:pickMyProcess}",
+      "initCommands": [
+        "script import time; time.sleep(3)"
+      ]
+    },
+    {
+      "name": "Replay drive",
+      "type": "debugpy",
+      "request": "launch",
+      "program": "${workspaceFolder}/opendbc/safety/tests/safety_replay/replay_drive.py",
+      "args": [
+        "${input:replayArg}"
+      ],
+      "console": "integratedTerminal",
+      "justMyCode": false,
+      "env": {
+        "PYTHONPATH": "${workspaceFolder}"
+      },
+      "subProcess": true,
+      "stopOnEntry": false
+    }
+  ],
+  "compounds": [
+    {
+      "name": "Replay drive + Safety LLDB",
+      "configurations": [
+        "Replay drive",
+        "Attach LLDB to Replay drive"
+      ]
     }
   ]
 }
\ No newline at end of file
diff --git a/docs/DEBUGGING_SAFETY.md b/docs/DEBUGGING_SAFETY.md
new file mode 100644
index 0000000000..cd0a46b446
--- /dev/null
+++ b/docs/DEBUGGING_SAFETY.md
@@ -0,0 +1,30 @@
+# Debugging Panda Safety with Replay Drive + LLDB
+
+## 1. Start the debugger in VS Code
+
+* Select **Replay drive + Safety LLDB**.
+* Enter the route or segment when prompted.
+[<img src="https://github.com/user-attachments/assets/b0cc320a-083e-46a7-a9f8-ca775bbe5604">](https://github.com/user-attachments/assets/b0cc320a-083e-46a7-a9f8-ca775bbe5604)
+
+## 2. Attach LLDB
+
+* When prompted, pick the running **`replay_drive` process**.
+* ⚠️ Attach quickly, or `replay_drive` will start consuming messages.
+
+> [!TIP]
+> Add a Python breakpoint at the start of `replay_drive.py` to pause execution and give yourself time to attach LLDB.
+
+## 3. Set breakpoints in VS Code
+Breakpoints can be set directly in `modes/xxx.h` (or any C file).
+No extra LLDB commands are required — just place breakpoints in the editor.
+
+## 4. Resume execution
+Once attached, you can step through both Python (on the replay) and C safety code as CAN logs are replayed.
+
+> [!NOTE]
+> * Use short routes for quicker iteration.
+> * Pause `replay_drive` early to avoid wasting log messages.
+
+## Video
+
+View a demo of this workflow on the PR that added it: https://github.com/commaai/openpilot/pull/36055#issue-3352911578
\ No newline at end of file