gdbtool works without modify registers

Major improvements to Photon GDB debugging infrastructure:

1. Symbol-based offset export (thread.cpp)
   - Export struct offsets as global C symbols (gdb_thread_offset_*, gdb_vcpu_offset_*)
   - Remove obsolete gdb_get_* helper functions

2. photongdb.py enhancements
   - Dynamic offset loading from libphoton.so symbols with fallback defaults
   - Works for both living process and coredump records.

3. Documentation updates for both English and Chinese
   - Updated example outputs to reflect new vCPU format
   - Clarified CURRENT vs RUNNING state semantics

Author: Coldwings

CMakeLists.txt

@@ -100,7 +100,7 @@ set(CMAKE_BUILD_RPATH_USE_ORIGIN ON)
 set(CMAKE_POSITION_INDEPENDENT_CODE ON)
 
 if (CMAKE_CXX_COMPILER_ID STREQUAL "GNU")
-    set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Wno-packed-bitfield-compat")
+    set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Wno-packed-bitfield-compat -fno-omit-frame-pointer")
 endif()
 
 if (CMAKE_SYSTEM_PROCESSOR STREQUAL x86_64)
@@ -109,7 +109,7 @@ if (CMAKE_SYSTEM_PROCESSOR STREQUAL x86_64)
         set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -mcrc32")
     endif ()
 elseif ((CMAKE_SYSTEM_PROCESSOR STREQUAL aarch64) OR (CMAKE_SYSTEM_PROCESSOR STREQUAL arm64))
-    set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fsigned-char -fno-stack-protector -fomit-frame-pointer")
+    set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fsigned-char -fno-stack-protector -fno-omit-frame-pointer")
     if (NOT CMAKE_CXX_FLAGS MATCHES "-march=|-mcpu=")
         set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -mcpu=generic+crc+crypto+lse")
     endif ()

doc/docs/miscellaneous/debugging.md

@@ -5,153 +5,123 @@ toc_max_heading_level: 5
 
 # Debugging
 
-`photongdb.py` is a gdb extension to help debugging running process with photon threads.
+`photongdb.py` is a GDB extension for debugging processes with Photon threads. It supports both live debugging and coredump analysis.
 
-It provides a group of extra gdb command to inspect photon thread status, even able to switch to background photon
-stack to inspect stack frames and variables if needed.
+It provides extra GDB commands to inspect Photon thread status and view stack traces of background threads.
 
 ## Build
 
-Build with `-D CMAKE_BUILD_TYPE=Debug`
+Build with `-D CMAKE_BUILD_TYPE=Debug` and `-fno-omit-frame-pointer` for best debugging experience.
 
 ## Usage
 
-When using GDB to debugging (debug running or attaching), load the script to enable this extension
+When using GDB for debugging (attach to process or analyze coredump), load the script to enable this extension:
 
 ```gdb
 (gdb) source <repo_dir>/tools/photongdb.py 
-INFO Photon-GDB-extension loaded
-```
-It will print hint to tells that extension is loaded.
-Extra gdb-commands are added to environment:
-
-:::note
-The `repo_dir` in debugging machine should be the same as the one in build machine.
-:::
-
-```gdb
-photon_current
-photon_ls
-photon_init
-photon_fini
-photon_rst
-photon_fr
+INFO Photon-GDB-extension v2 loaded
+INFO Commands: photon_ls, photon_fr <n>, photon_bt [n], photon_ps, photon_current
+INFO Use photon_fr to select thread, then photon_bt to show its backtrace
 ```
 
 ### Commands
 
-#### `photon_init`
+| Command | Description |
+|---------|-------------|
+| `photon_ls` | List all Photon threads across all vCPUs |
+| `photon_fr <n>` | Select thread n for subsequent operations |
+| `photon_bt [n]` | Show backtrace of selected (or specified) thread |
+| `photon_ps` | Show all threads with their backtraces |
+| `photon_current` | Show currently selected Photon thread info |
 
-Initializing photon thread lookup mode.
+Legacy commands (`photon_init`, `photon_fini`, `photon_rst`) are kept for backward compatibility but no longer needed.
 
-This command will store current stack registers in gdb value `$saved_rsp`, `$saved_rbp`, `$saved_rip`, and enabling
-commands in photon thread lookup mode.
-
-Since to inspect background photon threads needs simulating stack switch for gdb, it will change some registers.
-All commands in this group should be called only after entered photon debugging mode.
+#### `photon_ls`
 
-During photon debugging mode, user should NEVER try to continue running (even step in) before exit the mode, or
-process running status will be messed up, result in unpredictable failure.
+List all Photon threads on all vCPUs. Output format is similar to GDB's `info threads`.
 
 ```gdb
-(gdb) photon_init
-WARNING Entered photon thread lookup mode. PLEASE do not trying step-in or continue before `photon_fini`
-
-(gdb) p $saved_rsp
-$1 = 140737488343040
-(gdb) p $saved_rbp
-$2 = 140737488343040
-(gdb) p $saved_rip
-$3 = 4358880
-
 (gdb) photon_ls
-CURRENT [0] 0x5555558a9e20 0x7fffffffdb30 0x7fffffffe1a0 0x55555556a029
-READY [1] 0x7ffff6afb340 0x7ffff6afb1b0 0x7ffff6afb1d0 0x5555555696e0
-SLEEP [2] 0x5555558c0740 0x5555558c0310 0x5555558c0310 0x5555558c0740
-SLEEP [3] 0x7ffff6165b40 0x7ffff6165690 0x7ffff6165690 0x7ffff6165b40
+  Thread 0, 0xffffad92cf80 (CURRENT) vCPU 1 (0xaaab0e9b4e00)
+      at photon::vcpu_ctx::run () at thread/thread.cpp:1295
+  Thread 1, 0xaaab0eb78030 (STANDBY) vCPU 1 (0xaaab0e9b4e00)
+      at photon::thread_stub () at thread/thread.cpp:502
+  Thread 2, 0xaaab0ec98030 (SLEEP) vCPU 1 (0xaaab0e9b4e00)
+      at photon::thread_usleep_defer () at thread/thread.cpp:952
+* Thread 3, 0xaaab0ed44030 (SLEEP) vCPU 1 (0xaaab0e9b4e00)
+      at photon::mutex::lock () at thread/thread.cpp:1605
 ```
 
-:::info
-There are two situations:
-1. You have set a `breakpoint` in a specific line of your code.
-2. You suspend the `gdb` by `ctrl + C`, and the program halts inside libc or syscall.
+The `*` marks the currently selected thread (via `photon_fr`).
+
+#### `photon_fr`
 
-For situation 2, you MUST first switch to the Photon code, for instance, by the command of `frame 3`.
-You should make sure the current stack has the `photon::CURRENT` symbol when initializing.
+Select a Photon thread for subsequent `photon_bt` and `photon_current` commands.
 
-After init, you MUST go back to the top frame by the command of `frame 0`.
-:::
+```gdb
+(gdb) photon_fr 3
+[Switching to Thread 3, 0xaaab0ed44030 (SLEEP) vCPU 1 (0xaaab0e9b4e00)]
 
+(gdb) photon_fr
+Current selected thread: 3
+```
 
-#### `photon_current`
+#### `photon_bt`
 
-Print out `CURRENT` running photon thread struct. No side effects, can be called any time.
+Show backtrace of the selected thread (or specify a thread index). Output format is similar to GDB's `backtrace`.
 
 ```gdb
-(gdb) photon_current
-CURRENT {<intrusive_list_node<photon::thread>> = {<__intrusive_list_node> = {__prev_ptr = 0x7ffff2bf9bc0, __next_ptr = 0x7ffff2bf9bc0}, <No data fields>}, state = photon::RUNNING, error_number = 0, idx = -172836528, flags = 0, reserved = 7564776, joinable = false, shutting_down = false, lock = {_lock = {<std::__atomic_flag_base> = {_M_i = false}, <No data fields>}}, waitq = 0x0, vcpu = 0x7ffff7db5600 <photon::vcpus>, start = 0x736de8, arg = 0x0, retval = 0x736fe8, buf = 0x7ffff7dd46c0 <(anonymous namespace)::c_locale_impl> "\020", stack = {_ptr = 0x7fffffffd0c8}, ts_wakeup = 0, cond = {<photon::waitq> = {q = {th = 0x0, lock = {_lock = {<std::__atomic_flag_base> = {_M_i = false}, <No data fields>}}}}, <No data fields>}}
+(gdb) photon_bt
+#0  0x0000ffffaf79bde0 in photon::thread_usleep_defer ()
+#1  0x0000ffffaf79b410 in photon::mutex::lock ()
+#2  0x0000aaab0e9f6a48 in TestFunc () at test.cpp:42
+
+(gdb) photon_bt 0
+#0  0x0000ffffaf7a9e58 in photon::vcpu_ctx::run () at thread/thread.cpp:1295
+#1  0x0000ffffaf7aa0c4 in photon::vcpu_task () at thread/thread.cpp:1342
 ```
 
-#### `photon_ls`
+#### `photon_ps`
 
-List all photon threads on current vCPU. No side effects, can be called any time.
+Show all Photon threads with their backtraces.
 
 ```gdb
-(gdb) photon_ls
-CURRENT [0] 0x5555558a9e20 0x7fffffffdb30 0x7fffffffe1a0 0x55555556a029
-READY [1] 0x7ffff6afb340 0x7ffff6afb1b0 0x7ffff6afb1d0 0x5555555696e0
-SLEEP [2] 0x5555558c0740 0x5555558c0310 0x5555558c0310 0x5555558c0740
-SLEEP [3] 0x7ffff6165b40 0x7ffff6165690 0x7ffff6165690 0x7ffff6165b40
-```
+(gdb) photon_ps
+Thread 0, 0xffffad92cf80 (CURRENT) vCPU 1 (0xaaab0e9b4e00)
+#0  0x0000ffffaf7a9e58 in photon::vcpu_ctx::run ()
+#1  0x0000ffffaf7aa0c4 in photon::vcpu_task ()
 
-:::info
-This command will only work after `photon_init`
-:::
+Thread 1, 0xaaab0eb78030 (STANDBY) vCPU 1 (0xaaab0e9b4e00)
+#0  0x0000ffffaf79b7f4 in photon::thread_stub ()
 
-#### `photon_fr`
+Thread 2, 0xaaab0ec98030 (SLEEP) vCPU 1 (0xaaab0e9b4e00)
+#0  0x0000ffffaf79bde0 in photon::thread_usleep_defer ()
+#1  0x0000aaab0e9f5c20 in main ()
+```
 
-Look into any photon thread stack. Use with gdb `bt`.
+#### `photon_current`
+
+Show the currently selected Photon thread info.
 
 ```gdb
-(gdb) photon_fr 1
-SWITCH to 0x7ffff2bf9ac8 0x7ffff2bf9ae0 0x7ffff5014ceb
-(gdb) bt
-#0  photon::switch_context (from=0x7ffff2bf9bc0, to=0x736c50) at photon/thread.cpp:478
-#1  0x00007ffff5014d22 in photon::switch_context (from=0x7ffff2bf9bc0, new_state=photon::READY, to=0x736c50) at photon/thread.cpp:482
-#2  0x00007ffff5010b51 in photon::thread_yield_to (th=0x736c50) at photon/thread.cpp:575
-#3  0x00007ffff5010465 in photon::thread_stub () at photon/thread.cpp:386
-#4  0x0000000000000000 in ?? ()
-(gdb) photon_fr 0
-SWITCH to 0x7fffffffd000 0x7fffffffd000 0x4282e0
-(gdb) bt
-#0  0x00000000004282e0 in <lambda(ILogOutput*)>::operator()(ILogOutput *) const (__closure=0x7fffffffd044, __output___LINE__=0x706280 <_log_output_null>)
-    at test/test.cpp:132
-#1  0x00000000004488ba in LogBuilder<log_format()::<lambda(ILogOutput*)> >::~LogBuilder(void) (this=0x7fffffffd040, __in_chrg=<optimized out>)
-    at test/../alog.h:519
-#2  0x0000000000428398 in log_format () at test/test.cpp:133
-#3  0x00000000004283c9 in ALog_fmt_perf_1m_Test::TestBody (this=0x736c00) at test/test.cpp:140
-#4  0x00000000004b6d13 in void testing::internal::HandleExceptionsInMethodIfSupported<testing::Test, void>(testing::Test*, void (testing::Test::*)(), char const*) ()
-#5  0x00000000004abeaa in testing::Test::Run() ()
-#6  0x00000000004abff8 in testing::TestInfo::Run() ()
-#7  0x00000000004ac0d5 in testing::TestCase::Run() ()
-#8  0x00000000004ac3c0 in testing::internal::UnitTestImpl::RunAllTests() ()
-#9  0x00000000004b7223 in bool testing::internal::HandleExceptionsInMethodIfSupported<testing::internal::UnitTestImpl, bool>(testing::internal::UnitTestImpl*, bool (testing::internal::UnitTestImpl::*)(), char const*) ()
-#10 0x00000000004ac6a3 in testing::UnitTest::Run() ()
-#11 0x0000000000457f24 in RUN_ALL_TESTS () at ../../.dep_create_cache/var/alicpp/apsara/alicpp/built/gcc-4.9.2/gtest-1.7.0/include/gtest/gtest.h:2288
-#12 0x0000000000447737 in main (argc=1, argv=0x7fffffffd4d8) at test/test.cpp:1761
+(gdb) photon_current
+SLEEP [3] 0xaaab0ed44030 vCPU 1 (0xaaab0e9b4e00)
 ```
 
-:::info
-This command will only work after `photon_init`
-:::
+### Coredump Debugging
 
-#### `photon_fini`
+The extension fully supports coredump debugging. Simply load the script and use the same commands:
 
-Finish photon thread lookup mode, restore registers
+```bash
+gdb /path/to/executable /path/to/core.12345
+(gdb) source /path/to/photongdb.py
+(gdb) photon_ls
+(gdb) photon_ps
+```
 
-This will restore registers, exit photon thread lookup mode, so it is able to continue running after `photon_init` called.
+### Notes
 
-```gdb
-(gdb) photon_fini
-WARNING Finished photon thread lookup mode.
-```
+- For best stack unwinding results, compile with `-fno-omit-frame-pointer`
+- CURRENT threads show the actual OS thread stack from GDB (live debugging)
+- RUNNING state is shown for coredump analysis where GDB context is unavailable
+- Works with multiple vCPUs in multi-threaded applications