Merge upstream OpenSTA 08/24

.github/workflows/ci.yml

@@ -43,6 +43,26 @@ jobs:
           cmake --install .
           tar -zcvf build.tar.gz -Cinstall .
 
+      - name: Upload generated docs
+        uses: actions/upload-artifact@v7
+        with:
+          name: generated-docs
+          path: |
+            doc/Commands.md
+            doc/Variables.md
+            doc/CommandLine.md
+            doc/Messages.md
+          if-no-files-found: error
+          retention-days: 1
+
+      - name: Check command help
+        run: |
+          test -s doc/Commands.md
+          test -s doc/Variables.md
+          test -s doc/CommandLine.md
+          test -s doc/Messages.md
+          ./build/sta -no_splash -no_init -exit etc/CheckCmdHelp.tcl
+
       - name: Test
         run: |
           cd test
@@ -106,3 +126,34 @@ jobs:
           name: result-macos
           path: |
             test/results/*
+
+  docs:
+    needs: linux-ubuntu
+    if: ${{ !cancelled() && needs.linux-ubuntu.result != 'skipped' }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Download generated docs
+        uses: actions/download-artifact@v8
+        with:
+          name: generated-docs
+          path: doc
+
+      - name: Check generated docs
+        run: |
+          test -s doc/Commands.md
+          test -s doc/Variables.md
+          test -s doc/CommandLine.md
+
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+
+      - name: Install MkDocs
+        run: pip install -r doc/requirements.txt
+
+      - name: Build docs
+        run: mkdocs build --strict

.gitignore

@@ -19,14 +19,21 @@ pvt
 # iverilog turd
 examples/gcd_tb
 
-doc/._Sta.docx
+# Generated by building sta (etc/WriteCmdDocs.tcl, etc/FindMessages.tcl).
+doc/Commands.md
+doc/Variables.md
+doc/CommandLine.md
+doc/Messages.md
 
 test/results
 */test/results
+
 # ngspice turd
 test/b3v3_1check.log
 
-doc/messages.txt
+# MkDocs
+site/
+.venv/
 
 # clangd turds
 .cache/

.readthedocs.yaml

@@ -0,0 +1,30 @@
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+  apt_packages:
+    - bison
+    - build-essential
+    - cmake
+    - flex
+    - libeigen3-dev
+    - libfl-dev
+    - ninja-build
+    - pkg-config
+    - swig
+    - tcl-dev
+    - wget
+    - zlib1g-dev
+  jobs:
+    # Commands.md / Variables.md / CommandLine.md come from a live sta binary.
+    pre_build:
+      - bash etc/build_sta.sh
+
+mkdocs:
+  configuration: mkdocs.yml
+
+python:
+  install:
+    - requirements: doc/requirements.txt

CMakeLists.txt

@@ -685,7 +685,14 @@ add_custom_target(sta_tags
 add_custom_command(
   TARGET OpenSTA
   POST_BUILD
-  COMMAND ${STA_HOME}/etc/FindMessages.tcl > ${STA_HOME}/doc/messages.txt || true
+  COMMAND ${STA_HOME}/etc/FindMessages.tcl ${STA_HOME}/doc/Messages.md
+  WORKING_DIRECTORY ${STA_HOME}
+)
+
+add_custom_command(
+  TARGET sta
+  POST_BUILD
+  COMMAND $<TARGET_FILE:sta> -no_splash -no_init -exit ${STA_HOME}/etc/WriteCmdDocs.tcl
   WORKING_DIRECTORY ${STA_HOME}
 )
 

README.md

@@ -50,9 +50,15 @@ netlist data structures without duplicating them.
 * Query based incremental update of delays, arrival and required times
 * Simulator to propagate constants from constraints and netlist tie high/low
 
-See doc/OpenSTA.pdf for command documentation.
-See doc/ChangeLog.txt for changes to commands.
-See doc/StaApi.txt for timing engine API documentation.
+Documentation is published at
+https://opensta.readthedocs.io/en/latest/
+
+See the [command reference](https://opensta.readthedocs.io/en/latest/Commands/)
+for command documentation. That page is generated from the live `sta`
+help registry when the binary is built (CMake and Read the Docs run
+`etc/WriteCmdDocs.tcl`).
+See [doc/ChangeLog.md](doc/ChangeLog.md) for changes to commands.
+See [doc/StaApi.md](doc/StaApi.md) for timing engine API documentation.
 
 OpenSTA is dual licensed. It is released under GPL v3 as OpenSTA and
 is also licensed for commerical applications by Parallax Software without
@@ -273,10 +279,13 @@ tarfile.
 
 ## Contributions
 
-Contributors must sign the Contributor License Agreement (doc/CLA.txt)
+Contributors must sign the Contributor License Agreement
+([doc/CLA.txt](doc/CLA.txt))
 when submitting pull requests.
 
-All contributors should read doc/CodingGuidelines.txt for notes on
+All contributors should read
+[doc/CodingGuidelines.md](doc/CodingGuidelines.md)
+for notes on
 making code that adheres to the existing naming and formatting style.
 
 Contributions that claim 4% performance improvements in OpenROAD flow

app/Main.cc

@@ -202,7 +202,9 @@ static void
 showUsage(std::string_view prog,
           std::string_view init_filename)
 {
-  sta::print(stdout, "Usage: {} [-help] [-version] [-no_init] [-exit] cmd_file\n",
+  sta::print(stdout,
+             "Usage: {} [-help] [-version] [-no_init] [-no_splash] "
+             "[-threads count|max] [-exit] cmd_file\n",
              prog);
   sta::print(stdout, "  -help              show help and exit\n");
   sta::print(stdout, "  -version           show version and exit\n");

dcalc/DelayCalc.tcl

@@ -25,7 +25,13 @@
 namespace eval sta {
 
 define_cmd_args "report_dcalc" \
-  {[-from from_pin] [-to to_pin] [-scene scene] [-min] [-max] [-digits digits]}
+  {[-from from_pin] [-to to_pin] [-scene scene] [-min] [-max] [-digits digits]} \
+  -help {The `report_dcalc` command shows how the delays between instance pins are calculated. It is useful for debugging problems with delay calculation.} \
+  -arg_help {
+    -from {Report delay calculations for timing arcs from instance input pin from_pin.}
+    -to {Report delay calculations for timing arcs to instance output pin to_pin.}
+    -scene {Report delay calculations for this scene. Required if more than one scene is defined.}
+  }
 
 proc_redirect report_dcalc {
   report_dcalc_cmd "report_dcalc" $args "-digits"
@@ -139,7 +145,16 @@ proc set_delay_calculator { alg } {
 
 define_cmd_args "set_assigned_delay" \
   {-cell|-net [-rise] [-fall] [-scene scene] [-min] [-max]\
-     [-from from_pins] [-to to_pins] delay}
+     [-from from_pins] [-to to_pins] delay} \
+  -help {The `set_assigned_delay` command is used to annotate the delays between two pins on an instance or net. The annotated delay overrides the calculated delay. This command is an interactive way to back-annotate delays like an SDF file.} \
+  -arg_help {
+    -cell {Annotate the delays between two pins on an instance.}
+    -net {Annotate the delays between two pins on a net.}
+    -scene {The name of a scene. The `-scene` keyword is required if more than one scene is defined.}
+    -from {A list of pins.}
+    -to {A list of pins.}
+    delay {The delay between from_pins and to_pins.}
+  }
 
 # Change the delay for timing arcs between from_pins and to_pins matching
 # on cell (instance) or net.
@@ -239,7 +254,18 @@ define_cmd_args "set_assigned_check" \
   {-setup|-hold|-recovery|-removal [-rise] [-fall]\
      [-scene scene] [-min] [-max]\
      [-from from_pins] [-to to_pins] [-clock rise|fall]\
-     [-cond sdf_cond] check_value}
+     [-cond sdf_cond] check_value} \
+  -help {The `set_assigned_check` command is used to annotate the timing checks between two pins on an instance. The annotated delay overrides the calculated delay. This command is an interactive way to back-annotate delays like an SDF file.} \
+  -arg_help {
+    -recovery {Annotate recovery timing checks.}
+    -removal {Annotate removal timing checks.}
+    -scene {The name of a scene. The `-scene` keyword is required if more than one scene  is defined.}
+    -from {A list of pins for the clock.}
+    -to {A list of pins for the data.}
+    -clock {`rise|fall`: The timing check clock pin transition.}
+    -cond {SDF condition string for the annotated check.}
+    margin {The timing check margin.}
+  }
 
 proc set_assigned_check { args } {
   parse_key_args "set_assigned_check" args \
@@ -348,7 +374,13 @@ proc set_assigned_check2 { from_vertex from_rf to_vertex to_rf \
 ################################################################a
 
 define_cmd_args "set_assigned_transition" \
-  {[-rise] [-fall] [-scene scene] [-min] [-max] slew pins}
+  {[-rise] [-fall] [-scene scene] [-min] [-max] slew pins} \
+  -help {The `set_assigned_transition` command is used to annotate the transition time (slew) of a pin. The annotated transition time overrides the calculated transition time.} \
+  -arg_help {
+    -scene {Annotate delays for scene.}
+    slew {The pin transition time.}
+    pin_list {A list of pins.}
+  }
 
 # Change the slew on a list of ports.
 proc set_assigned_transition { args } {
@@ -381,7 +413,13 @@ proc set_assigned_transition { args } {
 ################################################################
 
 define_cmd_args "report_slews" {[-scenes scenes] [-digits digits]\
-                                  [-report_variance] pin}
+                                  [-report_variance] pin} \
+  -help {Report the slews at a pin.} \
+  -arg_help {
+    -scenes {Report slews for these scenes. The default is all scenes.}
+    -report_variance {Report SSTA distribution parameters.}
+    pin {A pin or port.}
+  }
 
 proc report_slews { args } {
   global sta_report_default_digits