Merge pull request #2560 from w0lek/ipa_end_user_doc

End user documentation for Interactive Path Analysis Tool (VPR server mode)

Author: vaughnbetz

doc/src/api/vpr/contexts.rst

@@ -43,3 +43,7 @@ Structures
 .. doxygenstruct:: TimingContext
    :project: vpr
    :members:
+
+.. doxygenstruct:: ServerContext
+   :project: vpr
+   :members:

doc/src/api/vpr/index.rst

@@ -11,3 +11,4 @@ VPR API
    netlist
    route_tree
    rr_graph
+   server

doc/src/api/vpr/server.rst

@@ -0,0 +1,83 @@
+========
+Server
+========
+
+server::update
+--------------
+
+.. doxygenfunction:: server::update
+   :project: vpr
+
+server::GateIO
+--------------
+
+.. doxygenclass:: server::GateIO
+   :project: vpr
+   :members:
+
+server::Task
+------------
+
+.. doxygenfile:: commcmd.h
+   :project: vpr
+
+.. doxygenclass:: server::Task
+   :project: vpr
+   :members:
+
+server::TaskResolver
+--------------------
+
+.. doxygenclass:: server::TaskResolver
+   :project: vpr
+   :members:
+
+.. doxygenstruct:: server::CritPathsResult 
+   :project: vpr
+   :members:
+
+.. doxygenfunction:: server::calc_critical_path
+   :project: vpr
+
+.. doxygenenum:: e_timing_report_detail
+   :project: vpr
+
+comm::Telegram
+--------------
+
+.. doxygenclass:: comm::TelegramHeader
+   :project: vpr
+   :members:
+
+.. doxygenstruct:: comm::TelegramFrame
+   :project: vpr
+   :members:
+
+.. doxygenclass:: comm::TelegramBuffer
+   :project: vpr
+   :members:
+
+.. doxygenclass:: comm::ByteArray
+   :project: vpr
+   :members:
+
+Parsers
+-------
+
+.. doxygenclass:: server::TelegramOptions
+   :project: vpr
+   :members:
+
+.. doxygenclass:: comm::TelegramParser
+   :project: vpr
+   :members:
+
+
+Compression utils
+-----------------
+
+.. doxygenfunction:: try_compress
+   :project: vpr
+
+.. doxygenfunction:: try_decompress
+   :project: vpr

doc/src/vpr/command_line_usage.rst

@@ -1824,6 +1824,27 @@ The following options are used to enable power estimation in VPR.
 
     Instructions on generating this file are provided in :ref:`power_estimation`.
 
+Server Mode Options
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+If VPR is in server mode, it listens on a socket for commands from a client. Currently, this is used to enable interactive timing analysis and visualization of timing paths in the VPR UI under the control of a separate client.
+
+The following options are used to enable server mode in VPR.
+
+.. seealso:: :ref:`server_mode` for more details.
+
+.. option:: --server
+
+    Run in server mode. Accept single client application connection and respond to client requests
+
+    **Default:** ``off``
+
+.. option:: --port PORT
+
+    Server port number.
+
+    **Default:** ``60555``
+
 Command-line Auto Completion
 ----------------------------
 

doc/src/vtr/index.rst

@@ -43,6 +43,7 @@ VTR also includes a set of benchmark designs known to work with the design flow.
    running_vtr
    benchmarks
    power_estimation/index.rst
+   server_mode/index.rst
    tasks
    run_vtr_flow
    run_vtr_task

doc/src/vtr/server_mode/comm_telegram_body_structure.odg

@@ -0,0 +1,208 @@
+.. _server_mode:
+
+Server Mode
+================
+
+If VPR is in server mode, it listens on a socket for commands from a client. Currently, this is used to enable interactive timing analysis and visualization of timing paths in the VPR UI under the control of a separate client.
+VPR provides the ability to run in server mode using the following command-line arguments.
+
+.. code-block:: none
+
+  --server --port_num 60555
+
+Server mode may only accept a single client application connection and respond to two types of requests: **get critical path report** and **highlight selected critical path elements**.
+
+Communication telegram
+-------------------------
+
+Telegram consists of two parts: a fixed-size **telegram header** and a variable-size **telegram body**.
+The telegram header contains helper information required to properly extract the telegram body sequence from the data flow.
+
+.. _fig_comm_telegram_structure:
+
+.. figure:: comm_telegram_structure.*
+
+    Communication telegram structure.
+
+.. note:: The telegram body itself could be compressed with zlib to minimize the amount of data transferred over the socket.
+  This compression is applied to the response of the 'get critical path report' request. The compressor ID byte in the telegram header signals whether the telegram body is compressed.
+  When the compressor ID is null, the telegram body is not compressed. If the compressor ID is 'z', it means the body is compressed with zlib.
+
+.. note:: The checksum field contains the telegram body checksum. This checksum is used to validate the consistency of the telegram body during the dispatching phase.
+  If checksums are mismatched, the telegram is considered invalid and is skipped in processing.
+
+
+.. _fig_comm_telegram_body_structure:
+
+.. figure:: comm_telegram_body_structure.*
+
+    Communication telegram body structure.
+
+    **telegram body** is a flat **JSON** structure.
+
+    **CMD** could have following integer values:
+
+    - 0 - command id for **get critical path**
+    - 1 - command id for **highlight selected path elements**
+
+    JOB_ID is a unique ID for a task. It is used to associate the request with the response by matching the same JOB_ID. Each new client request should increment the JOB_ID value; otherwise, it will not be clear which request the current response belongs to.
+
+
+Get critical path timing report example
+---------------------------------------
+
+  Let's take a look at an example of a request timing report telegram body with the following options:
+
+  - path_num = 1
+  - path_type = "setup"
+  - details_level = "netlist"
+  - is_flat_routing = false
+
+  .. code-block:: json
+      :caption: telegram body **REQUEST** example
+      :linenos:
+
+      {
+        "JOB_ID": "1",
+        "CMD": "0",
+        "OPTIONS": "int:path_num:1;string:path_type:setup;string:details_level:netlist;bool:is_flat_routing:0"
+      }
+
+  **path_type** could have following string values:
+
+  - "setup"
+  - "hold"
+
+  **details_level** could have following string values:
+
+  - "netlist"
+  - "aggregated"
+  - "detailed"
+  - "debug"
+
+  Response will look like:
+
+  .. code-block:: json
+      :caption: telegram body **RESPONSE** example
+      :linenos:
+
+      {
+        "JOB_ID": "1",
+        "CMD": "0",
+        "OPTIONS": "int:path_num:1;string:path_type:setup;string:details_level:netlist;bool:is_flat_routing:0",
+        "DATA": "
+          #Timing report of worst 1 path(s)
+          # Unit scale: 1e-09 seconds
+          # Output precision: 3
+
+          #Path 1
+          Startpoint: count[1].Q[0] (dffsre clocked by clk)
+          Endpoint  : count[13].D[0] (dffsre clocked by clk)
+          Path Type : setup
+
+          Point                                                                       Incr      Path
+          ------------------------------------------------------------------------------------------
+          clock clk (rise edge)                                                      0.000     0.000
+          clock source latency                                                       0.000     0.000
+          clk.inpad[0] (.input)                                                      0.000     0.000
+          count[1].C[0] (dffsre)                                                     0.715     0.715
+          count[1].Q[0] (dffsre) [clock-to-output]                                   0.286     1.001
+          count_adder_carry_p_cout[2].p[0] (adder_carry)                             0.573     1.574
+          count_adder_carry_p_cout[2].cout[0] (adder_carry)                          0.068     1.642
+          count_adder_carry_p_cout[3].cin[0] (adder_carry)                           0.043     1.685
+          count_adder_carry_p_cout[3].cout[0] (adder_carry)                          0.070     1.755
+          count_adder_carry_p_cout[4].cin[0] (adder_carry)                           0.053     1.808
+          count_adder_carry_p_cout[4].cout[0] (adder_carry)                          0.070     1.877
+          count_adder_carry_p_cout[5].cin[0] (adder_carry)                           0.043     1.921
+          count_adder_carry_p_cout[5].cout[0] (adder_carry)                          0.070     1.990
+          count_adder_carry_p_cout[6].cin[0] (adder_carry)                           0.053     2.043
+          count_adder_carry_p_cout[6].cout[0] (adder_carry)                          0.070     2.113
+          count_adder_carry_p_cout[7].cin[0] (adder_carry)                           0.043     2.156
+          count_adder_carry_p_cout[7].cout[0] (adder_carry)                          0.070     2.226
+          count_adder_carry_p_cout[8].cin[0] (adder_carry)                           0.053     2.279
+          count_adder_carry_p_cout[8].cout[0] (adder_carry)                          0.070     2.348
+          count_adder_carry_p_cout[9].cin[0] (adder_carry)                           0.043     2.391
+          count_adder_carry_p_cout[9].cout[0] (adder_carry)                          0.070     2.461
+          count_adder_carry_p_cout[10].cin[0] (adder_carry)                          0.053     2.514
+          count_adder_carry_p_cout[10].cout[0] (adder_carry)                         0.070     2.584
+          count_adder_carry_p_cout[11].cin[0] (adder_carry)                          0.043     2.627
+          count_adder_carry_p_cout[11].cout[0] (adder_carry)                         0.070     2.696
+          count_adder_carry_p_cout[12].cin[0] (adder_carry)                          0.053     2.749
+          count_adder_carry_p_cout[12].cout[0] (adder_carry)                         0.070     2.819
+          count_adder_carry_p_cout[13].cin[0] (adder_carry)                          0.043     2.862
+          count_adder_carry_p_cout[13].cout[0] (adder_carry)                         0.070     2.932
+          count_adder_carry_p_cout[14].cin[0] (adder_carry)                          0.053     2.985
+          count_adder_carry_p_cout[14].sumout[0] (adder_carry)                       0.040     3.025
+          count_dffsre_Q_D[13].in[0] (.names)                                        0.564     3.589
+          count_dffsre_Q_D[13].out[0] (.names)                                       0.228     3.818
+          count[13].D[0] (dffsre)                                                    0.000     3.818
+          data arrival time                                                                    3.818
+
+          clock clk (rise edge)                                                      0.000     0.000
+          clock source latency                                                       0.000     0.000
+          clk.inpad[0] (.input)                                                      0.000     0.000
+          count[13].C[0] (dffsre)                                                    0.715     0.715
+          clock uncertainty                                                          0.000     0.715
+          cell setup time                                                           -0.057     0.659
+          data required time                                                                   0.659
+          ------------------------------------------------------------------------------------------
+          data required time                                                                   0.659
+          data arrival time                                                                   -3.818
+          ------------------------------------------------------------------------------------------
+          slack (VIOLATED)                                                                    -3.159
+
+
+          #End of timing report
+          #RPT METADATA:
+          path_index/clock_launch_path_elements_num/arrival_path_elements_num
+          0/2/30
+      ",
+        "STATUS": "1"
+      }
+
+Draw selected critical path elements example
+--------------------------------------------
+
+  Let's take a look at an example of a request timing report telegram body with the following options:
+
+  - path_elements = path 0 and it's sub-elements 10,11,12,13,14,15,20,21,22,23,24,25
+  - high_light_mode = "crit path flylines delays"
+  - draw_path_contour = 1
+
+  .. code-block:: json
+      :caption: telegram body **REQUEST** example
+      :linenos:
+
+      {
+        "JOB_ID": "2",
+        "CMD": "1",
+        "OPTIONS": "string:path_elements:0#10,11,12,13,14,15,20,21,22,23,24,25;string:high_light_mode:crit path flylines delays;bool:draw_path_contour:1"
+      }
+
+  **high_light_mode** could have following string values:
+
+  - "crit path flylines"
+  - "crit path flylines delays"
+  - "crit path routing"
+  - "crit path routing delays"
+
+  Response will look like:
+
+  .. code-block:: json
+      :caption: telegram body **RESPONSE** example
+      :linenos:
+
+      {
+        "JOB_ID": "2",
+        "CMD": "1",
+        "OPTIONS": "string:path_elements:0#10,11,12,13,14,15,20,21,22,23,24,25;string:high_light_mode:crit path flylines delays;bool:draw_path_contour:1",
+        "DATA": "",
+        "STATUS": "1"
+      }
+
+  .. note:: If status is not 1, the field ***DATA*** contains error string.
+
+
+
+
+

doc/src/vtr/server_mode/comm_telegram_body_structure.svg

@@ -828,9 +828,9 @@ RouteStatus vpr_route_flow(const Netlist<>& net_list,
             routing_delay_calc = std::make_shared<RoutingDelayCalculator>(atom_ctx.nlist, atom_ctx.lookup, net_delay, is_flat);
             timing_info = make_setup_hold_timing_info(routing_delay_calc, router_opts.timing_update_type);
 #ifndef NO_SERVER
-            if (g_vpr_ctx.server().gateIO().is_running()) {
-                g_vpr_ctx.mutable_server().set_timing_info(timing_info);
-                g_vpr_ctx.mutable_server().set_routing_delay_calc(routing_delay_calc);
+            if (g_vpr_ctx.server().gate_io.is_running()) {
+                g_vpr_ctx.mutable_server().timing_info = timing_info;
+                g_vpr_ctx.mutable_server().routing_delay_calc = routing_delay_calc;
             }
 #endif /* NO_SERVER */
         } else {
@@ -1080,7 +1080,7 @@ void vpr_init_server(const t_vpr_setup& vpr_setup) {
 #ifndef NO_SERVER
     if (vpr_setup.ServerOpts.is_server_mode_enabled) {
         /* Set up a server and its callback to be triggered at 100ms intervals by the timer's timeout event. */
-        server::GateIO& gate_io = g_vpr_ctx.mutable_server().mutable_gateIO();
+        server::GateIO& gate_io = g_vpr_ctx.mutable_server().gate_io;
         if (!gate_io.is_running()) {
             gate_io.start(vpr_setup.ServerOpts.port_num);
             g_timeout_add(/*interval_ms*/ 100, server::update, &application);