Add debugging doc (#173)

doc/README.md

@@ -39,7 +39,7 @@ $ USE_SSH=true yarn deploy
 Not using SSH:
 
 ```
-$ GIT_USER=<Your GitHub username> yarn deploy
+$ GIT_USER=photonlibos yarn deploy
 ```
 
 Will push to the `main` branch and use the GitHub pages for hosting

doc/docs/introduction/how-to-build.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 3
+sidebar_position: 2
 toc_max_heading_level: 4
 ---
 

doc/docs/introduction/how-to-integrate.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 4
+sidebar_position: 3
 toc_max_heading_level: 4
 ---
 

doc/docs/introduction/write-first-example.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 5
+sidebar_position: 4
 toc_max_heading_level: 4
 ---
 

doc/docs/miscellaneous/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Miscellaneous",
+  "position": 4,
+  "link": {
+    "type": "generated-index",
+    "description": "Miscellaneous"
+  }
+}

tools/photongdb.md → doc/docs/miscellaneous/debugging.md

@@ -1,21 +1,34 @@
-# Photon-GDB-Extension
+---
+sidebar_position: 1
+toc_max_heading_level: 5
+---
+
+# Debugging
 
 `photongdb.py` is a gdb extension to help debugging running process with photon threads.
 
-It provides a group of extra gdb command to inspect photon thread status, even able to switch to backgroud photon
-stack to inspect stack frames and variables if needes.
+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.
+
+## Build
+
+Build with `-D CMAKE_BUILD_TYPE=Debug`
 
 ## Usage
 
 When using GDB to debugging (debug running or attaching), load the script to enable this extension
 
 ```gdb
-(gdb) source thread/tools/photongdb.py 
+(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
@@ -25,69 +38,79 @@ photon_rst
 photon_fr
 ```
 
-### General Commands
-
-General commands have no side affects, can be called any time.
-
-#### `photon_current` print current photon thread structure
-
-Print out `CURRENT` running photon thread struct
-
-```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>}}
-```
-
-#### `photon_ls` list all photon threads
+### Commands
 
-List all photon threads on current vcpu (or said system thread)
+#### `photon_init`
 
-```gdb
-(gdb) photon_ls
-CURRENT [0] 0x736c50 0x7fffffffd000 0x7fffffffd000 0x4282e0
-READY [1] 0x7ffff2bf9bc0 0x7ffff2bf9ac8 0x7ffff2bf9ae0 0x7ffff5014ceb
-```
-Results will mark as selecting index (which may be useful )
+Initializing photon thread lookup mode.
 
-### Photon Thread Lookup Mode Commands
+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 regsitrers.
-All commands in this group should called only after entered photon debugging 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.
 
-During photon debugging mode, user should NEVER trying to continue running (even step in) before exit the mode, or
+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.
 
-#### `photon_init` initializing photon thread lookup mode
-
-This command will stores current stack registers in gdb value `$saved_rsp`, `$saved_rbp`, `$saved_rip`, and enabling
-commands in photon thread lookup mode.
-
 ```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
 ```
 
-#### `photon_fr` look into certian photon thread stack
+:::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.
+
+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.
+
+After init, you MUST go back to the top frame by the command of `frame 0`.
+:::
+
+
+#### `photon_current`
+
+Print out `CURRENT` running photon thread struct. No side effects, can be called any time.
 
-This command will only able to work after `photon_init`, and able to simulating stack switch to a background photon thread.
+```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_init
-WARNING Entered photon thread lookup mode. PLEASE do not trying step-in or continue before `photon_fini`
+
+#### `photon_ls`
+
+List all photon threads on current vCPU. No side effects, can be called any time.
+
+```gdb
 (gdb) photon_ls
-CURRENT [0] 0x736c50 0x7fffffffd000 0x7fffffffd000 0x4282e0
-READY [1] 0x7ffff2bf9bc0 0x7ffff2bf9ac8 0x7ffff2bf9ae0 0x7ffff5014ceb
-(gdb) photon_fr 1
-SWITCH to 0x7ffff2bf9ac8 0x7ffff2bf9ae0 0x7ffff5014ceb
+CURRENT [0] 0x5555558a9e20 0x7fffffffdb30 0x7fffffffe1a0 0x55555556a029
+READY [1] 0x7ffff6afb340 0x7ffff6afb1b0 0x7ffff6afb1d0 0x5555555696e0
+SLEEP [2] 0x5555558c0740 0x5555558c0310 0x5555558c0310 0x5555558c0740
+SLEEP [3] 0x7ffff6165b40 0x7ffff6165690 0x7ffff6165690 0x7ffff6165b40
 ```
 
-Normally, using `photon_ls` to list all photon threads, then call photon_fr to switch to certian photon stack.
-After this, you can now using gdb frame commands to see and switch stack frames, or print variables
+:::info
+This command will only work after `photon_init`
+:::
+
+#### `photon_fr`
+
+Look into any photon thread stack. Use with gdb `bt`.
 
 ```gdb
 (gdb) photon_fr 1
@@ -118,9 +141,15 @@ SWITCH to 0x7fffffffd000 0x7fffffffd000 0x4282e0
 #12 0x0000000000447737 in main (argc=1, argv=0x7fffffffd4d8) at test/test.cpp:1761
 ```
 
-#### `photon_fini` finish photon thread lookup mode, restore registers
+:::info
+This command will only work after `photon_init`
+:::
+
+#### `photon_fini`
+
+Finish photon thread lookup mode, restore registers
 
-This will restore registers, exit photon thread lookup mode, so it is able to continue running after `photon_init` calleds.
+This will restore registers, exit photon thread lookup mode, so it is able to continue running after `photon_init` called.
 
 ```gdb
 (gdb) photon_fini