Merge pull request #11 from w0lek/ipa_end_user_doc_develop

update calc_critical_path doc

Author: w0lek

doc/src/api/vpr/server.rst

@@ -39,6 +39,9 @@ server::TaskResolver
 .. doxygenfunction:: server::calc_critical_path
    :project: vpr
 
+.. doxygenenum:: e_timing_report_detail
+   :project: vpr
+
 comm::Telegram
 --------------
 
@@ -77,4 +80,4 @@ Compression utils
    :project: vpr
 
 .. doxygenfunction:: try_decompress
-   :project: vpr
+   :project: vpr

doc/src/vpr/command_line_usage.rst

@@ -1826,6 +1826,9 @@ The following options are used to enable power estimation in VPR.
 
 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.

doc/src/vtr/server_mode/comm_telegram_body_structure.odg

@@ -3,7 +3,8 @@
 Server Mode
 ================
 
-VTR provides the ability to run in server mode using the following command-line arguments.
+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
 
@@ -23,7 +24,14 @@ The telegram header contains helper information required to properly extract the
 
     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.*
@@ -37,11 +45,8 @@ The telegram header contains helper information required to properly extract the
     - 0 - command id for **get critical path**
     - 1 - command id for **highlight selected path elements**
 
-    JOB_ID - is unique id for a task.
+    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.
 
-    .. 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.
 
 Get critical path timing report example
 ---------------------------------------
@@ -58,8 +63,8 @@ Get critical path timing report example
       :linenos:
 
       {
-        "CMD": "0",
         "JOB_ID": "1",
+        "CMD": "0",
         "OPTIONS": "int:path_num:1;string:path_type:setup;string:details_level:netlist;bool:is_flat_routing:0"
       }
 
@@ -169,8 +174,8 @@ Draw selected critical path elements example
       :linenos:
 
       {
-        "CMD": "1",
         "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"
       }
 

doc/src/vtr/server_mode/comm_telegram_body_structure.svg

@@ -568,7 +568,7 @@ struct NocContext : public Context {
  * @brief State relating to server mode
  *
  * This should contain only data structures that
- * related to server state.
+ * relate to the vpr server state.
  */
 struct ServerContext : public Context {
     /**
@@ -601,7 +601,8 @@ struct ServerContext : public Context {
     /**
      * @brief Stores the flag indicating whether to draw the critical path contour.
      *
-     * If the flag is set to true, the non-selected critical path elements will be drawn as a contour, while selected elements will be drawn as usual.
+     * If True, the entire path will be rendered with some level of transparency, regardless of the selection of path elements. However, selected path elements will be drawn in full color.
+     * This feature is helpful in visual debugging, to see how the separate path elements are mapped into the whole path.
      */
     bool draw_crit_path_contour = false;
 

doc/src/vtr/server_mode/index.rst

@@ -113,7 +113,7 @@ void draw_crit_path(ezgl::renderer* g);
  * and indexes map. It is primarily used in server mode, where items are drawn upon request.
  *
  * @param paths The vector of TimingPath objects representing the critical paths.
- * @param indexes The map of sets, where map keys are path indices and each set contains the indices of sub-path elements to draw.
+ * @param indexes The map of sets, where the map keys are path indices in std::vector<tatum::TimingPath>, and each set contains the indices of the data_arrival_path elements ( @ref tatum::TimingPath ) to draw.
  * @param g Pointer to the ezgl::renderer object on which the elements will be drawn.
  */
 void draw_crit_path_elements(const std::vector<tatum::TimingPath>& paths, const std::map<std::size_t, std::set<std::size_t>>& indexes, bool draw_crit_path_contour, ezgl::renderer* g);

vpr/src/base/vpr_context.h

@@ -10,7 +10,7 @@
 namespace comm {
 
 /**
- * @brief ByteArray as a simple wrapper over std::vector<char>
+ * @brief ByteArray is a simple wrapper over std::vector<char> that provides a user-friendly interface for manipulating array data..
 */
 class ByteArray : public std::vector<char> {
 public:

vpr/src/draw/draw_basic.h

@@ -27,9 +27,9 @@ namespace server {
  * Operable only with a single client. As soon as client connection is detected
  * it begins listening on the specified port number for incoming client requests,
  * collects and encapsulates them into tasks (see @ref Task).
- * The incoming tasks are extracted and handled by the top-level logic @ref TaskResolver in main thread.
+ * The incoming tasks are extracted and handled by the top-level logic @ref TaskResolver in the main thread.
  * Once the tasks are resolved by the @ref TaskResolver, they are returned to be sent back to the client app as a response.
- * Extraction and puting @ref Task is taken from main thread inside @ref server::update.
+ * Moving @ref Task across threads happens in @ref server::update.
  * 
  * @note
  * - The GateIO instance should be created and managed from the main thread, while its internal processing 
@@ -154,9 +154,7 @@ class GateIO
     GateIO& operator=(GateIO&&) = delete;
 
     /**
-    * @brief Checks if the port listening process is currently running.
-    *
-    * This method returns a boolean indicating whether the port listening process is currently running.
+    * @brief Returns a bool indicating whether or not the port listening process is currently running.
     *
     * @return True if the port listening process is running, false otherwise.
     */
@@ -186,7 +184,7 @@ class GateIO
     /**
      * @brief Prints log messages for the GateIO.
      * 
-     * @note Must be called from main thread since it's invoke std::cout.
+     * @note Must be called from the main thread since it's invoke std::cout.
      * Calling this method from other threads may result in unexpected behavior.
      */
     void print_logs(); 

vpr/src/server/bytearray.h

@@ -40,9 +40,9 @@ using CritPathsResultPtr = std::shared_ptr<CritPathsResult>;
 * @brief Calculates the critical path.
 
 * This function calculates the critical path based on the provided parameters.
-* @param type The type of the critical path.
-* @param crit_path_num The max number of the critical path.
-* @param details_level The level of detail for the timing report.
+* @param type The type of the critical path. Must be either "setup" or "hold".
+* @param crit_path_num The max number of critical paths to record.
+* @param details_level The level of detail for the timing report. See @ref e_timing_report_detail.
 * @param is_flat_routing Indicates whether flat routing should be used.
 * @return A `CritPathsResultPtr` which is a pointer to the result of the critical path calculation (see @ref CritPathsResult).
 */