Update debug_aids.rst

added documentation on using the new debugger. (Images have yet to be added)

Author: MahshadJ

doc/src/vpr/debug_aids.rst

@@ -24,3 +24,70 @@ Finally, if you need to route an FPGA whose routing architecture cannot be descr
 The router, graphics, sanity checker, and statistics routines all work only with a graph that defines all the available routing resources in the FPGA and the permissible connections between them.
 If you change the routines that build this graph (in ``rr_graph*.c``) so that they create a graph describing your FPGA, you should be able to route your FPGA.
 If you want to read a text file describing the entire routing resource graph, call the ``dump_rr_graph`` subroutine.
+
+Placer and Router Debugger
+==========================
+Adding a breakpoint
+~~~~~~~~~~~~~~~~~~~
+
+Currently the user is required to have graphics on in order to set breakpoints. By clocking the “Debug” button, the debugger window opens up and from there the user can enter integer values in the entry fields and set breakpoints. A more advanced option is using expressions which allows a wider variety of settings since the user can incorporate multiple variables and use boolean operators. This option is found by clicking the “Advanced” button in the debugger window. Using an expression is more accurate than the entry fields when setting multiple breakpoints.
+
+Enabling/Disabling a breakpoint
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Enabling and disabling breakpoints are done using the checkboxes in front of each breakpoint in the breakpoint list. The breakpoint is enabled when the box is checked and disabled otherwise.
+
+Deleting a breakpoint
+~~~~~~~~~~~~~~~~~~~~~
+
+Deleting a breakpoint is done using the trash can button in front of each breakpoint in the breakpoint list.
+
+Reaching a breakpoint
+~~~~~~~~~~~~~~~~~~~~~
+
+Upon reaching a breakpoint, the program will stop, notify the user which breakpoint was encountered, and give a summary of the current variable values. This information is presented through a pop-up window and printed to the terminal as well.
+
+Available Variables
+~~~~~~~~~~~~~~~~~~~
+
+You can also find the variables’ list in the Advanced Settings Window, on the left.
+
+**Placer Variables**
+
+  * move_num: every placer iteration counts as a move, so the user can stop the program after a certain number of moves. This breakpoint can be enabled through the entry field on the main debugger window or using an expression. It should be noted however, that using the entry field would proceed the specified number of moves. (as in the second example)
+    * Ex. move _num == 33
+    * Ex. move_num += 4
+  * temp_count: every time the temperature is updated it counts as an increase to temp_count. This breakpoint can be enabled through the entry field on the main debugger window or using an expression. It should be noted however, that using the entry field would proceed the specified number of temperatures. (as in the second example)
+    * Ex. temp_count == 5
+    * Ex. temp_count += 5
+  * from_block:  in every placer move one or more blocks are relocated. From_block specifies the first block that is relocated in every move. This breakpoint can be enabled through the entry field on the main debugger window or using an expression.
+    * Ex. from_block == 83
+  * in_blocks_affected: this variable allows you to stop whenever your specified block was moved. Unlike from_block which only checks the first block moved in every move, in_blocks_affected looks through all the replicated blocks in that move. This breakpoint can only be enabled through the use of an expression.
+    * Ex. in_blocks_affected == 1
+    
+**Router Variables**
+
+  * router_iter: every router iteration, whether failed or succeeded, counts as a router iteration. This breakpoint can be enabled through the entry field on the main debugger window or using an expression.
+    * Ex. router_iter == 2
+  * route_net_id: stops when the specified net is rerouted. This breakpoint can be enabled through the entry field on the main debugger window or using an expression.
+    * route_net_id == 12
+    
+Available Operators
+~~~~~~~~~~~~~~~~~~~
+
+  * ==
+    * Ex. temp_count == 2
+  * >
+    * Ex. move_num > 94
+  * <
+    * Ex. move_num < 94
+  * >=
+    * Ex. router_iter >=2
+  * <=
+    * Ex. router_iter <=2
+  * &&
+    * Ex. from_block == 83 && move_num > 72
+  * ||
+    * Ex. in_blocks_affected == 11 || temp_count == 9
+  * +=
+    * Ex. move_num += 8