diff --git a/Jenkinsfile b/Jenkinsfile index fafbc59de6..e8b9f45569 100644 --- a/Jenkinsfile +++ b/Jenkinsfile @@ -1,5 +1,5 @@ -@Library('utils@main') _ +@Library('utils@orfs-error-steps') _ node { - pipelineORFS(maxTimeout: 180) + pipelineORFS(maxTimeout: 180, filter: 'nangate45/gcd,sky130hd/gcd,ihp-sg13g2/gcd') } diff --git a/build_openroad.sh b/build_openroad.sh index 9d6ee14c3f..0dbd16c2b5 100755 --- a/build_openroad.sh +++ b/build_openroad.sh @@ -39,6 +39,7 @@ function usage() { Usage: $0 [-h|--help] [-o|--local] [-l|--latest] [--or_branch BRANCH_NAME] [--or_repo REPO_URL] [--no_init] + [-s|--skip_openroad] [--openroad_only] [-n|--nice] [-t|--threads N] [--yosys-args-overwrite] [--yosys-args STRING] [--with-verific PATH] @@ -57,6 +58,9 @@ Options: -s, --skip_openroad Skip building and all git operations on OpenROAD. + --openroad_only Build only OpenROAD; skip Yosys, Verific and + kepler-formal. Requires --local. + --or_branch BRANCH_NAME Use the head of branch BRANCH for tools/OpenROAD. --or_repo REPO_URL Use a fork at REPO-URL (https/ssh) for tools/OpenROAD. @@ -165,6 +169,9 @@ while (( "$#" )); do -s|--skip_openroad) SKIP_OPENROAD=1 ;; + --openroad_only) + OPENROAD_ONLY=1 + ;; --or_branch) OPENROAD_APP_BRANCH="$2" shift @@ -233,6 +240,17 @@ while (( "$#" )); do shift done +if [ ! -z "${OPENROAD_ONLY+x}" ]; then + if [ -z "${LOCAL_BUILD+x}" ]; then + echo "[ERROR FLW-0033] --openroad_only requires --local." >&2 + exit 1 + fi + if [ ! -z "${SKIP_OPENROAD+x}" ]; then + echo "[ERROR FLW-0033] --openroad_only and --skip_openroad are mutually exclusive." >&2 + exit 1 + fi +fi + if [[ "$PROC" == "-1" ]]; then if [[ "$OSTYPE" == "linux-gnu"* ]]; then PROC=$(nproc --all) @@ -373,6 +391,10 @@ __local_build() ${NICE} ./tools/OpenROAD/etc/Build.sh "${OPENROAD_APP_ARGS[@]}" fi + if [ ! -z "${OPENROAD_ONLY+x}" ]; then + return + fi + YOSYS_ABC_PATH=tools/yosys/abc if [[ -d "${YOSYS_ABC_PATH}/.git" ]]; then # update indexes to make sure git diff-index uses correct data diff --git a/docker/Dockerfile.builder b/docker/Dockerfile.builder index 25ce8ae7db..93ef32bec6 100644 --- a/docker/Dockerfile.builder +++ b/docker/Dockerfile.builder @@ -6,6 +6,9 @@ # instead use etc/DockerHelper.sh ARG fromImage=openroad/flow-ubuntu22.04-dev:latest +# Image holding the prebuilt tools/install of every tool except OpenROAD +# (a build of the orfs-tools target). By default they are built here. +ARG toolsImage=orfs-tools FROM $fromImage AS orfs-base @@ -22,7 +25,11 @@ RUN sh /tmp/setup_compiler_wrappers.sh && rm /tmp/setup_compiler_wrappers.sh # Prepend wrapper directory to PATH so they override system compilers ENV PATH="/usr/local/bin/wrapped-cc:$PATH" -COPY --link tools tools +FROM orfs-builder-base AS orfs-tools-builder + +# Exclude install so a local build's output (e.g. tools/install/OpenROAD) +# cannot leak into the image; the build below starts from an empty install. +COPY --link --exclude=OpenROAD --exclude=AutoTuner --exclude=install tools tools ARG numThreads=$(nproc) ARG verificPath="" @@ -36,23 +43,17 @@ else fi ./build_openroad.sh --no_init \ --local \ + --skip_openroad \ --threads ${numThreads} \ ${verificArgs} -if [ ! -x tools/install/OpenROAD/bin/openroad ]; then - echo "Error: tools/install/OpenROAD/bin/openroad is missing or not executable." >&2 - exit 1 -fi if [ -n "${verificPath}" ]; then rm -rf "${verificPath}" fi EOF # Collect LICENSE files from tool source trees into the install directory so -# they are available in the final image. tools/OpenROAD/src/sta is excluded -# because it is covered by a separate commercial license agreement. +# they are available in the final image. RUN find /OpenROAD-flow-scripts/tools \( -name "*LICENSE*" -o -name "*LICENSES*" \) \ - | grep -v '/OpenROAD/src/sta/' \ - | grep -v '/AutoTuner/' \ | grep -v '^/OpenROAD-flow-scripts/tools/install/' \ | while IFS= read -r f; do \ rel="${f#/OpenROAD-flow-scripts/tools/}"; \ @@ -60,6 +61,41 @@ RUN find /OpenROAD-flow-scripts/tools \( -name "*LICENSE*" -o -name "*LICENSES*" cp -r "$f" "/OpenROAD-flow-scripts/tools/install/licenses/$rel"; \ done +# Yosys, kepler-formal and their licenses, without sources or build trees. +FROM orfs-base AS orfs-tools + +COPY --link --from=orfs-tools-builder /OpenROAD-flow-scripts/tools/install tools/install + +FROM $toolsImage AS tools + +FROM orfs-builder-base AS orfs-openroad-builder + +COPY --link --from=tools /OpenROAD-flow-scripts/tools/install tools/install +COPY --link tools/OpenROAD tools/OpenROAD +ARG numThreads=$(nproc) + +RUN <&2 + exit 1 +fi +EOF + +# tools/OpenROAD/src/sta is excluded because it is covered by a separate +# commercial license agreement. +RUN find /OpenROAD-flow-scripts/tools/OpenROAD \( -name "*LICENSE*" -o -name "*LICENSES*" \) \ + | grep -v '/OpenROAD/src/sta/' \ + | while IFS= read -r f; do \ + rel="${f#/OpenROAD-flow-scripts/tools/}"; \ + mkdir -p "/OpenROAD-flow-scripts/tools/install/licenses/$(dirname "$rel")"; \ + cp -r "$f" "/OpenROAD-flow-scripts/tools/install/licenses/$rel"; \ + done + FROM orfs-base # The order for copying the directories is based on the frequency of changes (ascending order), @@ -74,7 +110,7 @@ COPY --link flow/scripts flow/scripts COPY --link flow/designs flow/designs COPY --link tools/AutoTuner tools/AutoTuner -COPY --link --from=orfs-builder-base /OpenROAD-flow-scripts/tools/install tools/install +COPY --link --from=orfs-openroad-builder /OpenROAD-flow-scripts/tools/install tools/install COPY --link \ --exclude=.git* --exclude=tools/ --exclude=docs/ --exclude=docker/ \ --exclude=flow/designs --exclude=flow/platforms --exclude=flow/scripts \ diff --git a/docker/Dockerfile.dev b/docker/Dockerfile.dev index f5cee7f3bd..b92bec521d 100644 --- a/docker/Dockerfile.dev +++ b/docker/Dockerfile.dev @@ -23,9 +23,14 @@ RUN sh /tmp/setup_compiler_wrappers.sh && rm /tmp/setup_compiler_wrappers.sh ENV PATH="/usr/local/bin/wrapped-cc:$PATH" +# The last rm drops the unused net-imap default gem bundled with Ubuntu 22.04's +# Ruby 3.0 (flagged by CVE scanners, never used by the flow). It is chained here +# so the files don't persist in an earlier layer. No-op if not present. RUN ./DependencyInstaller.sh -base $options $constantBuildDir -save-deps-prefixes=/etc/openroad_deps_prefixes.txt \ && ./DependencyInstaller.sh -common $options $constantBuildDir -save-deps-prefixes=/etc/openroad_deps_prefixes.txt \ - && rm -rf /tmp/installer /tmp/* /var/tmp/* /var/lib/apt/lists/* + && rm -rf /tmp/installer /tmp/* /var/tmp/* /var/lib/apt/lists/* \ + && rm -rf /usr/lib/ruby/gems/*/gems/net-imap-0.1.1 \ + /usr/lib/ruby/gems/*/specifications/default/net-imap-0.1.1.gemspec ARG fromImage diff --git a/docs/contrib/EndpointSlackTracking.md b/docs/contrib/EndpointSlackTracking.md new file mode 100644 index 0000000000..ef9a30a27e --- /dev/null +++ b/docs/contrib/EndpointSlackTracking.md @@ -0,0 +1,162 @@ +# Tracking Endpoint Slack Across Flow Steps + +When working on an optimization (resizing, buffering, CTS, repair timing, +...) it is useful to see how the slack of each timing endpoint moves from +one flow step to the next, not just how WNS/TNS change. ORFS can record the +setup and hold slack of every endpoint at the end of every flow step +(`1_synth`, `2_1_floorplan`, ..., `3_3_place_gp`, ..., `6_final`) and compare +any two steps, including a scatter plot of slack (x: earlier step, y: later +step). + +## Recording + +Set `REPORT_ENDPOINT_SLACK=1`: + +``` shell +cd flow +make DESIGN_CONFIG=designs/nangate45/gcd/config.mk REPORT_ENDPOINT_SLACK=1 +``` + +Every step then writes `$(REPORTS_DIR)/_endpoint_slack.json`, e.g. +`3_3_place_gp_endpoint_slack.json`. The snapshot is taken by +`write_endpoint_slack` in `flow/scripts/util.tcl`, called from +`orfs_write_db` so the step name is the name of the `.odb` the step writes. +It works in the single-process `flow/scripts/flow.tcl` flow as well. Steps +that just copy their input (`orfs_copy_db`, e.g. `5_3_fillcell` without fill +cells) re-time the design if it is loaded, or else copy the previous step's +snapshot. Intermediate `.odb` files written through `orfs_write_db` (e.g. CTS +`save_progress`) also get a snapshot; `*-failed` ones don't. + +So that all steps are timed the same way, parasitics are estimated before +reporting as in `open.tcl`, based on the step number: + +| Steps | Parasitics | +| --- | --- | +| 1, 2 | none (cells are not placed) | +| 3, 4 | `estimate_parasitics -placement` | +| 5, `6_1_fill` | `estimate_parasitics -global_routing` if global routes exist | +| `6_final` | `rcx`: the extracted `6_final.spef`, as in `6_finish.rpt` (`global_routing` on platforms without `RCX_RULES`) | + +The parasitics model is recorded in each snapshot and shown by +`endpointSlack.py`. Slack changes between steps with different models (e.g. +`2_4_floorplan_pdn` to `3_1_place_gp_skip_io`, `4_1_cts` to `5_1_grt`, or +`6_1_fill` to `6_final`) include the change of model. Detailed routing is +only extracted in `6_final`, so `5_2_route` to `6_1_fill` show global routing +estimates. + +Each file contains `design`, `step`, `parasitics`, `time_unit` (seconds per +time unit of the values) and `endpoints`: a map from every endpoint pin +(`sta::endpoints`) to `[setup slack, hold slack]`, `null` where the endpoint +is unconstrained. The slack is the pin's worst slack over all path groups +and clocks (`get_property $pin slack_max|slack_min`). On asap7/swerv_wrapper +(about 30k endpoints) a snapshot is about 1 MB and takes about 10 s, mostly +the timing update. + +## Analysis + +`flow/util/endpointSlack.py` only uses the Python standard library. + +``` shell +R=reports/nangate45/gcd/base + +# Steps in execution order with parasitics, WNS, TNS and violation counts +python3 util/endpointSlack.py list $R + +# Compare consecutive steps across the whole run; --html also writes a +# scatter for every step vs. its successor and an index.html to a directory +python3 util/endpointSlack.py track $R --html track + +# Compare two steps; -o writes an interactive HTML scatter +python3 util/endpointSlack.py compare \ + $R/3_5_place_dp_endpoint_slack.json $R/4_1_cts_endpoint_slack.json \ + --unit ps -o compare.html + +# Flatten all snapshots into one CSV (one row per endpoint per step) +python3 util/endpointSlack.py export $R -o slack.csv +``` + +For setup and hold, `compare` reports: + +- endpoints in both steps, and how many improved, degraded, stayed the + same, became violating (`newly failing`) or stopped violating + (`newly passing`), with statistics of the slack change (B - A). + Improved, degraded and unchanged exclude endpoints with positive slack in + both steps, which are not being optimized; +- endpoints only in A or only in B, i.e. added or removed from the netlist; +- endpoints in both netlists but constrained in only one of them; +- how well the two steps agree on the critical endpoints (see below). + +Unconstrained endpoints, such as the outputs of CTS dummy load cells, are +ignored. + +### Agreement metrics + +Correlation over all endpoints is dominated by endpoints with large positive +slack and is close to 1 even when the critical endpoints change a lot (0.9997 +for setup on asap7/swerv_wrapper from `3_5_place_dp` to `4_1_cts`). The +metrics are therefore measured on a critical set: the worst K endpoints of A +or of B (`--critical K`, default 1000), excluding endpoints with positive +slack in both steps, which are not being optimized. When fewer than K +endpoints violate, the critical set is the endpoints violating in either +step; when nothing violates (often hold) it is empty and the metrics are +reported as `-`. + +| Metric | Meaning | +| --- | --- | +| `spearman` | Spearman rank correlation of A and B slack (ties get average ranks): is the order of the critical endpoints preserved? | +| `top agreement` | Fraction of the critical set that is in the worst K of both steps. | +| `bias`, `MAE`, `RMSE`, `max\|delta\|` | Mean, mean absolute, root mean square and maximum absolute slack change B - A, i.e. distance from the y = x line. | +| `violator recall` | Of the endpoints violating in B, the fraction already violating in A (over all endpoints). | +| `violator precision` | Of the endpoints violating in A, the fraction still violating in B (over all endpoints). | + +They are printed by `compare` and `track`, shown in the HTML stats, and +the `track` index has Spearman, top agreement and MAE columns for every step +transition. + +Times are shown in `--unit` (default ns) with a fixed number of digits after +the decimal point (3 for ns, 1 for ps, or `--digits`), in a fixed-width font +in the HTML. +Slack changes smaller than half the last displayed digit (0.5 ps with the +default ns and 3 digits), or `--tolerance` in `--unit`, count as unchanged +for the improved/degraded counts, the tables of most degraded and improved +endpoints and the `track` row colors. Otherwise numerical noise, e.g. a few +femtoseconds between `5_1_grt` and `5_2_route`, shows up as changes that +display as 0. + +`--worst N` restricts the endpoints in both to the union of the worst N +endpoints of A and of B, to focus on the critical part of the design. + +The HTML is self-contained (no network access needed). It has: + +- WNS, TNS and violation counts of both steps; +- a scatter of endpoint slack with a y = x line, where above the line means + the endpoint improved. It is drawn on a canvas so it handles hundreds of + thousands of endpoints. Drag to zoom, double-click to reset, hover for + the endpoint name; +- a setup/hold toggle; +- tables of the most degraded and most improved endpoints, excluding + endpoints with positive slack in both steps, and of the endpoints only in + one step. + +`track --html DIR` writes the same page for every step and its successor +(`__.html`, with previous/next links) and `DIR/index.html`, +a table of every transition with WNS/TNS and the improved, degraded, newly +failing and newly passing counts for setup and hold. Endpoints with positive +slack in both steps are not considered. Transitions where no considered +endpoint changed (e.g. `2_2_floorplan_macro` to `2_3_floorplan_tapcell`) are +greyed out, and transitions where every considered endpoint improved, for +setup and hold, are green. + +For other analyses, import the module (e.g. from a notebook): +`load_snapshot()`, `load_dir()`, `summary()`, `compare()`, `movement()`, +`metrics()` and `spearman()` +return plain Python dicts and lists. + +## Testing + +`flow/test/test_endpointSlack.py` covers loading and comparison with +synthetic snapshots and runs in the util CI job: + +``` shell +python3 flow/test/test_endpointSlack.py +``` diff --git a/docs/contrib/Metrics.md b/docs/contrib/Metrics.md index 5bef0658d8..bd045aa56d 100644 --- a/docs/contrib/Metrics.md +++ b/docs/contrib/Metrics.md @@ -47,12 +47,28 @@ check did not run. Read the `[WARN]` lines to see which. Pass `--strict` to `checkQorMetrics.py` to get distinct exit codes instead (2 inconclusive, 3 unreachable). -Two environment variables shape the comparison: +The check runs as the commit `metadata.json` records. The dashboard searches +its default baseline pipelines in order and takes a `master` build that has the +design: the one at the commit's merge base with `master`, otherwise the latest +one before the commit. A commit on `master` is its own merge base, so a run of +a `master` commit, such as a downloaded CI artifact, is compared against that +commit's own build. A commit not yet pushed has no merge base on GitHub, so it +is compared against the latest `master` build before it. Without a commit the +run is compared against the latest `master` build. + +These environment variables shape the comparison: - `DASHBOARD_API_KEY` grants access to private platforms. Without it, a - private design reports as inconclusive, not as an authentication error. -- `DASHBOARD_JOB_NAME` names the Jenkins pipeline whose `master` builds are the - baseline. The default is `OpenROAD-flow-scripts-Public`. + private design has no baseline and reports as inconclusive, not as an + authentication error. +- `DASHBOARD_JOB_NAME` checks the run as a build of that CI pipeline instead, + with the pipeline's rules for the branch checked out in this repository: the + previous build on a trunk branch such as `master`, the merge base on any + other branch. A CI job, whose checkout has no branch, also sets + `DASHBOARD_BRANCH` and `DASHBOARD_COMMIT` (or passes `--branch` and + `--commit`). +- `DASHBOARD_API_URL` (`--api-url`) points the check at another deployment and + takes precedence over `--beta`. If you only changed synthesis, you can gate a synthesis-only run, without running the rest of the flow. Only the `synth__` and `constraints__` metrics diff --git a/docs/toc.yml b/docs/toc.yml index 18baefd3fd..92b208b6b0 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -45,6 +45,8 @@ entries: title: Guide to Integrate a New Platform into the OpenROAD Flow - file: contrib/CI.md title: CI Guide + - file: contrib/EndpointSlackTracking.md + title: Tracking Endpoint Slack Across Flow Steps - file: contrib/CODE_OF_CONDUCT.md title: Code of Conduct diff --git a/docs/user/FlowVariables.md b/docs/user/FlowVariables.md index c575653135..dfb6ab40f2 100644 --- a/docs/user/FlowVariables.md +++ b/docs/user/FlowVariables.md @@ -247,6 +247,7 @@ configuration file. | REMOVE_CELLS_FOR_LEC| String patterns directly passed to write_verilog -remove_cells <> for lec checks.| | | REPAIR_PDN_VIA_LAYER| Remove power grid vias which generate DRC violations after detailed routing.| | | REPORT_CLOCK_SKEW| Report clock skew as part of reporting metrics, starting at CTS, before which there is no clock skew. This metric can be quite time-consuming, so it can be useful to disable.| 1| +| REPORT_ENDPOINT_SLACK| If set to 1, write the setup and hold slack of every timing endpoint at the end of every flow step (e.g. 3_3_place_gp) to $REPORTS_DIR/_endpoint_slack.json. These snapshots can be compared across steps with flow/util/endpointSlack.py. See docs/contrib/EndpointSlackTracking.md.| 0| | ROUTING_LAYER_ADJUSTMENT| Adjusts routing layer capacities to manage congestion and improve detailed routing. High values ease detailed routing but risk excessive detours and long global routing times, while low values reduce global routing failure but can complicate detailed routing. The global routing running time normally reduces dramatically (entirely design specific, but going from hours to minutes has been observed) when the value is low (such as 0.10). Sometimes, global routing will succeed with lower values and fail with higher values. Exploring results with different values can help shed light on the problem. Start with a too low value, such as 0.10, and bisect to value that works by doing multiple global routing runs. As a last resort, `make global_route_issue` and using the tools/OpenROAD/etc/whittle.py can be useful to debug global routing errors. If there is something specific that is impossible to route, such as a clock line over a macro, global routing will terminate with DRC errors routes that could have been routed were it not for the specific impossible routes. whittle.py should weed out the possible routes and leave a minimal failing case that pinpoints the problem.| 0.5| | RTLMP_AREA_WT| Weight for the area of the current floorplan.| 0.1| | RTLMP_ARGS| Overrides all other RTL macro placer arguments.| | @@ -354,6 +355,7 @@ configuration file. - [POST_SYNTH_TCL](#POST_SYNTH_TCL) - [POS_CLKGATE_AND_PORTS](#POS_CLKGATE_AND_PORTS) - [PRE_SYNTH_TCL](#PRE_SYNTH_TCL) +- [REPORT_ENDPOINT_SLACK](#REPORT_ENDPOINT_SLACK) - [SDC_FILE](#SDC_FILE) - [SEC_CHECK](#SEC_CHECK) - [SKIP_REPORT_METRICS](#SKIP_REPORT_METRICS) @@ -425,6 +427,7 @@ configuration file. - [PRE_PDN_TCL](#PRE_PDN_TCL) - [PRE_TAPCELL_TCL](#PRE_TAPCELL_TCL) - [REMOVE_ABC_BUFFERS](#REMOVE_ABC_BUFFERS) +- [REPORT_ENDPOINT_SLACK](#REPORT_ENDPOINT_SLACK) - [ROUTING_LAYER_ADJUSTMENT](#ROUTING_LAYER_ADJUSTMENT) - [RTLMP_AREA_WT](#RTLMP_AREA_WT) - [RTLMP_ARGS](#RTLMP_ARGS) @@ -502,6 +505,7 @@ configuration file. - [PRE_GLOBAL_PLACE_TCL](#PRE_GLOBAL_PLACE_TCL) - [PRE_IO_PLACEMENT_TCL](#PRE_IO_PLACEMENT_TCL) - [PRE_RESIZE_TCL](#PRE_RESIZE_TCL) +- [REPORT_ENDPOINT_SLACK](#REPORT_ENDPOINT_SLACK) - [ROUTING_LAYER_ADJUSTMENT](#ROUTING_LAYER_ADJUSTMENT) - [SKIP_REPORT_METRICS](#SKIP_REPORT_METRICS) - [TNS_END_PERCENT](#TNS_END_PERCENT) @@ -525,6 +529,7 @@ configuration file. - [POST_CTS_TCL](#POST_CTS_TCL) - [PRE_CTS_TCL](#PRE_CTS_TCL) - [REPORT_CLOCK_SKEW](#REPORT_CLOCK_SKEW) +- [REPORT_ENDPOINT_SLACK](#REPORT_ENDPOINT_SLACK) - [SETUP_MOVE_SEQUENCE](#SETUP_MOVE_SEQUENCE) - [SETUP_SLACK_MARGIN](#SETUP_SLACK_MARGIN) - [SKIP_BUFFER_REMOVAL](#SKIP_BUFFER_REMOVAL) @@ -554,6 +559,7 @@ configuration file. - [POST_GLOBAL_ROUTE_TCL](#POST_GLOBAL_ROUTE_TCL) - [PRE_GLOBAL_ROUTE_TCL](#PRE_GLOBAL_ROUTE_TCL) - [REPORT_CLOCK_SKEW](#REPORT_CLOCK_SKEW) +- [REPORT_ENDPOINT_SLACK](#REPORT_ENDPOINT_SLACK) - [ROUTING_LAYER_ADJUSTMENT](#ROUTING_LAYER_ADJUSTMENT) - [SETUP_MOVE_SEQUENCE](#SETUP_MOVE_SEQUENCE) - [SETUP_SLACK_MARGIN](#SETUP_SLACK_MARGIN) @@ -587,6 +593,7 @@ configuration file. - [PRE_DETAIL_ROUTE_TCL](#PRE_DETAIL_ROUTE_TCL) - [PRE_FILLCELL_TCL](#PRE_FILLCELL_TCL) - [REPORT_CLOCK_SKEW](#REPORT_CLOCK_SKEW) +- [REPORT_ENDPOINT_SLACK](#REPORT_ENDPOINT_SLACK) - [ROUTING_LAYER_ADJUSTMENT](#ROUTING_LAYER_ADJUSTMENT) - [SKIP_ANTENNA_REPAIR_POST_DRT](#SKIP_ANTENNA_REPAIR_POST_DRT) - [SKIP_DETAILED_ROUTE](#SKIP_DETAILED_ROUTE) @@ -610,6 +617,7 @@ configuration file. - [PRE_FINAL_REPORT_TCL](#PRE_FINAL_REPORT_TCL) - [PWR_NETS_VOLTAGES](#PWR_NETS_VOLTAGES) - [REPORT_CLOCK_SKEW](#REPORT_CLOCK_SKEW) +- [REPORT_ENDPOINT_SLACK](#REPORT_ENDPOINT_SLACK) - [ROUTING_LAYER_ADJUSTMENT](#ROUTING_LAYER_ADJUSTMENT) - [SEC_CHECK](#SEC_CHECK) - [SKIP_DETAILED_ROUTE](#SKIP_DETAILED_ROUTE) diff --git a/etc/DockerTag.sh b/etc/DockerTag.sh index 3234061637..315392c44d 100755 --- a/etc/DockerTag.sh +++ b/etc/DockerTag.sh @@ -13,6 +13,23 @@ if [[ "$@" == "-dev" ]]; then "./tools/OpenROAD/etc/DependencyInstaller.sh" ) cat "${file_list[@]}" | sha256sum | awk '{print substr($1, 1, 6)}' +elif [[ "$@" == "-tools" ]]; then + # Everything the orfs-tools target of Dockerfile.builder depends on: + # the dev image, the build scripts, the ignore file that filters the + # build context, and the checked-out tools except OpenROAD. + ignore_file=./docker/Dockerfile.builder.dockerignore + if [[ ! -f "${ignore_file}" ]]; then + ignore_file=./.dockerignore + fi + { + ./etc/DockerTag.sh -dev + cat ./build_openroad.sh ./dev_env.sh ./etc/setup_compiler_wrappers.sh + cat "${ignore_file}" + # Drop the trailing describe output, which depends on fetched tags. + git submodule status tools/yosys tools/kepler-formal | awk '{print $1, $2}' + git ls-tree HEAD tools/ | grep -v -e 'tools/OpenROAD$' -e 'tools/AutoTuner$' \ + -e 'tools/yosys$' -e 'tools/kepler-formal$' + } | sha256sum | awk '{print substr($1, 1, 6)}' elif [[ "$@" == "-master" ]]; then git fetch --tags >&2 git -C tools/OpenROAD fetch --tags >&2 @@ -21,6 +38,8 @@ else echo "Usage:" echo " To generate a tag for images that only have dev dependencies:" echo " $0 -dev" + echo " To generate a tag for the image with the prebuilt tools other than OpenROAD:" + echo " $0 -tools" echo " To generate a tag for full releases based on master branch" echo " $0 -master" exit 1 diff --git a/flow/designs/asap7/chi_async_bridge/README.md b/flow/designs/asap7/chi_async_bridge/README.md new file mode 100644 index 0000000000..af19367d79 --- /dev/null +++ b/flow/designs/asap7/chi_async_bridge/README.md @@ -0,0 +1,236 @@ +# chi_async_bridge + +The asynchronous bridge that carries XiangShan's CHI link between the +core's clock and the network-on-chip's. Six flit channels, each an +asynchronous queue, cross from one clock domain to the other, with their +link credits and handshakes. Both halves of the bridge are in this one +block, so timing analysis sees both ends of every crossing. + +The design exists to measure one thing: whether the flow implements an +asynchronous crossing the way its constraints describe it. Every path +from one clock to the other meets its budget, nothing tries to fix hold +across the asynchronous boundary, each synchroniser's flops stay +together, and what is left to fail is the logic inside each domain. + +## What it tests that no other design here does + +It is an integration test: one small block that takes a combination of +the flow's features through every stage together. Among the designs in +`flow/designs`, it is the only one with all of them, and the only one +with some of them at all: + +| feature | where | elsewhere in `flow/designs` | +|---|---|---| +| an asynchronous crossing that is timed: `set_clock_groups -asynchronous -allow_paths`, bounded by `set_max_delay -ignore_clock_latency` between the clocks, no hold check across | `constraint.sdc` | only `asap7/mock-cpu`; the other multi-clock designs declare their clocks exclusive or time only virtual IO clocks | +| a constraint file that checks the netlist it names and stops the flow if synthesis renamed, merged or restructured what it constrains | `constraint.sdc`, the synchronisers | none | +| the slang frontend, the hierarchy kept by name with `SYNTH_KEEP_MODULES` on slang's uniquified, parameterised modules, and linked with `OPENROAD_HIERARCHICAL` (`-hier`) | `config.mk` | none together; `asap7/mock-cpu` keeps its hierarchy with an RTL attribute and reads its Verilog with yosys | +| instance names in the constraints resolved through that hierarchy (`get_cells -hierarchical`) and written back by hierarchical name for every later stage | `constraint.sdc` | none | +| three threshold voltages, RVT, LVT and SLVT, on a multi-clock design | `ASAP7_USE_VT` | `asap7/cva6`, single-clock; the `_lvt` designs use LVT alone | +| the top's parameters set from the flow, one RTL for every variant | `VERILOG_TOP_PARAMS` | `asap7/uart` | + +A change to any of these shows up here first, in a design small enough +to run in minutes (`FLOW_VARIANT=small`). + +## The crossing + +```mermaid +flowchart LR + subgraph T[core clock: the tile half, in XSTileWrap] + L2[tile's CHI port] --> SB[shadow buffer] + SB --> MEM[queue memory] + SB --> WP[write pointer, Gray] + RS[read pointer synchroniser] + TS[rx queue sink] --> L2 + end + subgraph N[NoC clock: the NoC half, in XSNoCTop] + WS[write pointer synchroniser] --> MUX[read mux] + MUX --> DQ[deq_bits_reg] + RP[read pointer, Gray] + DQ --> NOC[NoC's CHI port] + end + WP -->|crosses| WS + MEM -->|crosses| MUX + RP -->|crosses| RS +``` + +That is one tx channel; the rx channels are the mirror image, and every +link credit is a queue of its own with no memory, only pointers. + +Three kinds of path cross: + +| path | from | to | what it must do | +|---|---|---|---| +| a pointer | a Gray-coded pointer flop | the first flop of a synchroniser | all its bits arrive within one period of the writing clock, so the reader never sees a code that was never written | +| the data | the queue memory, written on one clock | `deq_bits_reg`, through the read mux, on the other | arrive before the pointer that announces it has been synchronised | +| a handshake | a link-level signal | the first flop of a synchroniser | arrive; it is a level | + +None of them can be timed against the other clock's edges, because the +clocks have no phase relation. Each is bounded instead by a delay +measured from its first flop's clock pin to its last flop's data pin. + +## Constraints + +`constraint.sdc` sets the two clocks and says, in order: + +- the clocks are asynchronous to each other, and paths between them are + still timed (`set_clock_groups -asynchronous -allow_paths`); +- a path from one clock to the other must take less than one period of + the clock it starts on, ignoring clock latency + (`set_max_delay -ignore_clock_latency`): the Gray-code bound, which + also covers the data; +- there is no hold check between the clocks (`set_false_path -hold`); +- each domain's ports are budgeted with `set_max_delay`, in the shape of + `$PLATFORM_DIR/constraints.sdc` but at 80 % of that domain's period + rather than that file's fixed 80 ps; +- the step from one synchroniser flop to the next is short. This is the + only constraint that has to name instances. + +The last one is why the file checks itself. A name in an SDC is +written against the RTL and read against the synthesised netlist, and +OpenSTA treats a name that matches nothing as a warning and drops the +whole constraint. So `constraint.sdc` counts the flops it names and +checks that each synchroniser flop drives the next one and nothing +else; if synthesis has renamed or restructured them, the flow stops at +the synthesis stage with an error saying which. + +The design is linked hierarchically (`OPENROAD_HIERARCHICAL`), the way +a clock-crossing bridge is usually kept: its two clock-domain halves, +their asynchronous queues and their shadow buffers stay modules, and +everything inside them is flattened. The check looks for the +synchronisers at every level of that hierarchy. + +What synthesis does to the names, on this design: + +| in the RTL | in the netlist | +|---|---| +| `sync_shift_reg ridx_gray`, its `bit_[2]`, flop `sync[1]` | `sink/asyncQSource_dat_flit/ridx_gray.bit_[2].sync[1]$_DFF_PP0_`: the kept modules (`SYNTH_KEEP_MODULES`) joined with `/`, the hierarchy inside them flattened with `.`, yosys's cell type appended | +| the register `ridx_gray` that drives the output `async_ridx` | `...async_ridx[0]$_DFF_PP0_`: a flop takes the name of the net it drives, not of the variable that holds it | +| the same flop, in the database and in timing analysis | `bit_\[2\].sync\[1\]` in ODB, `bit_[2].sync[1]` from `get_full_name` | +| one flop driving the next | a flop, an inverter, a flop: asap7's flop with asynchronous set and reset, `DFFASRHQNx1`, has only an inverted output | + +The check is written against the right-hand column, and fails the +build when it stops being true. + +It runs once. `constraint.sdc` is read only at synthesis, against the +netlist yosys wrote; from there on every stage reads the constraints as +OpenROAD wrote them back out (`1_synth.sdc` and its successors), with +the names already resolved, one `set_max_delay` per hop. So the check +guards against what synthesis does to a synchroniser. A buffer that +resizing or hold repair later puts inside a hop is still held to the +hop's budget, but nothing checks the hop again. + +## Where it comes from + +XiangShan's tile is wrapped in `XSTileWrap` (`xiangshan/XSTileWrap.scala`), +which puts the tile half of the bridge, XSCache's `CHIAsyncBridgeSource`, +beside it on the core clock. The NoC half, `CHIAsyncBridgeSink`, is in +`XSNoCTop` on the NoC clock. Both are in XSCache's +`xscache/chi/AsyncBridge.scala`, built from rocket-chip's `AsyncQueue` +and `AsyncResetSynchronizerShiftReg`; the source files cite the lines +each piece models. The queue parameters are XiangShan's own +(`AsyncQueueParams(depth = 16, sync = 3, safe = false)`), and the flit +widths are those of its default CHI configuration: 125 bits for a +request, 51 for a response, 385 for data, 88 for a snoop. + +Everything a hardened XSTile sees at its CHI pins is this bridge: every +signal the tile sends ends at a flop in it, and every signal the tile +receives leaves from one (one handshake through a gate after it). That +is why +a block like XSTile is constrained with `set_max_delay` budgets on its +ports rather than with input and output delays, and why only its +register-to-register paths can fail timing closure. + +The SystemVerilog is rewritten from that Chisel, not generated from it, +and keeps its licenses: rocket-chip's Apache-2.0 for the async queue +and synchroniser, XiangShan's Mulan PSL v2 for the rest. +`src/chi_async_bridge/SOURCE.md` says which file comes from where, at +which commit, and `src/chi_async_bridge/LICENSES/` holds both texts. + +Not modelled: the NoC's CHI link layer beyond the bridge (link-state +machines and the credit managers), which is logic of the NoC's own +domain. Its ready signals and credits are ports here. + +## Results + +The core clock is 290 ps, a little below what the flow closes, so the +worst slack stays negative through global route and repair keeps +working rather than stopping at zero: + +| base, core clock 290 ps | worst slack | +|---|---| +| CTS | -35.8 ps | +| global route | -35.5 ps | +| final | -30.1 ps | + +The worst path is the core half's async queue sink, from the read +pointer through the read-mux select, buffered out to every bit of a +385-bit data flit, into `deq_bits_reg`: the queue's own logic, as in +XiangShan. Detailed routing leaves 113 max-slew violations, all in the +NoC half's data flit channel: 57 in its shadow buffer, 56 in its async +queue sink. + +This design reproduces XiangShan's bridge. Both were run through the +same flow and constraints at the same targets, to global route, with +the netlist flattened; the XiangShan side is XiangShan's own +`CHIAsyncBridgeSource` and `CHIAsyncBridgeSink`, elaborated from its +Chisel with its parameters and hardened alone. Given 420, 380 or 340 ps +both close, each time within a few picoseconds of the target; given +300 ps, both just fail, on the same path. + +| at global route, flat | target | this design | XiangShan's bridge | +|---|---|---|---| +| core clock, min period | 340 ps | 339.7 ps | 340.0 ps | +| core clock, min period | 300 ps | 305.9 ps | 301.4 ps | +| worst path, at 300 ps | | async queue sink read, rx dat | the same | +| its logic / inserted buffers / wire | | 163 / 80 / 22 ps | 159 / 76 / 22 ps | +| flops | | 35,106 | 35,043 | + +The NoC half is not calibrated: XiangShan's NoC link layer, left out +here, is in its NoC domain's worst path. Both NoC domains keep more than +200 ps of slack at the NoC period, so neither limits the design. + +The clock trees are the ones OpenROAD's CTS builds: clusters of sinks +under an H-tree, no mesh, and no on-chip-variation derates in this flow. +At final the core tree is about 260 ps deep, most of the period. That is +an ordinary tree at a 1,000 ps period and not what a core aimed at +300 ps would get, which is a clock mesh or a multi-source tree that +keeps paths diverging late. It does not touch what this design tests: +the crossing is timed without clock latency and without a hold check, +so the depth of either tree does not enter it. What the tree does move +is the same-clock paths, the synchroniser hops among them, and with them +the period; XiangShan's bridge was measured through the same trees. + +## Variants + +| FLOW_VARIANT | flits (req/rsp/dat/snp bits) | queue depth | flops | core clock min period at 300 ps, global route, flat | to global route | +|---|---|---|---|---|---| +| base | 125 / 51 / 385 / 88, XiangShan's | 16 | 35,106 | 305.9 ps, fails | 30 min | +| medium | 125 / 51 / 385 / 88 | 4 | 21,846 | 299.5 ps, closes | 20 min | +| small | 32 / 16 / 64 / 24 | 4 | 4,621 | 298.5 ps, closes | 5 min | + +The worst core-clock path is the same on every rung, the async queue +sink's read; only base, with XiangShan's sixteen entries behind the +read mux, reproduces XiangShan's period. The smaller rungs keep the +structure for iterating on a change in minutes. + +## Try this + +```sh +make DESIGN_CONFIG=./designs/asap7/chi_async_bridge/config.mk +make DESIGN_CONFIG=./designs/asap7/chi_async_bridge/config.mk FLOW_VARIANT=small +make DESIGN_CONFIG=./designs/asap7/chi_async_bridge/config.mk gui_grt +``` + +To see the constraints check themselves, change a synchroniser in +`src/chi_async_bridge/sync_shift_reg.sv` and run synthesis. Rename its +`sync` register and it stops with + +``` +constraint.sdc: synchronisers: unexpected cell name sink.asyncQSink_dat_flit.widx_gray.bit_[0].stage[0]$_DFF_PP0_ +``` + +or put a gate between two of its flops and it stops with + +``` +constraint.sdc: synchronisers: sink.asyncQSink_dat_flit.widx_gray.bit_[0].sync[2]$_DFF_PP0_ does not drive sink.asyncQSink_dat_flit.widx_gray.bit_[0].sync[1]$_DFF_PP0_ alone +``` diff --git a/flow/designs/asap7/chi_async_bridge/config.mk b/flow/designs/asap7/chi_async_bridge/config.mk new file mode 100644 index 0000000000..1f9e2cda64 --- /dev/null +++ b/flow/designs/asap7/chi_async_bridge/config.mk @@ -0,0 +1,39 @@ +# chi_async_bridge: XiangShan's asynchronous CHI bridge between its tile +# and its network-on-chip. README.md says what it is for and where it +# comes from. +export PLATFORM = asap7 +export DESIGN_NAME = chi_async_bridge +export DESIGN_NICKNAME = chi_async_bridge + +export VERILOG_FILES = $(sort $(wildcard $(DESIGN_HOME)/src/$(DESIGN_NICKNAME)/*.sv)) +export SDC_FILE = $(DESIGN_HOME)/$(PLATFORM)/$(DESIGN_NICKNAME)/constraint.sdc + +# Readable, parameterised SystemVerilog, read by slang. +export SYNTH_HDL_FRONTEND = slang + +# OpenROAD links the netlist hierarchically (-hier), the mode that is to +# become the default, so this design tests it. A clock-crossing bridge +# keeps its structure by name: the two clock-domain halves, their +# asynchronous queues and their shadow buffers stay modules, so the +# crossing is visible in the hierarchy -hier links. +export OPENROAD_HIERARCHICAL = 1 +export SYNTH_KEEP_MODULES = chi_async_bridge_source chi_async_bridge_sink \ + async_queue_source async_queue_sink shadow_buffer + +# All three threshold voltages, as for the core this bridge serves. +export ASAP7_USE_VT = RVT LVT SLVT + +export CORE_UTILIZATION = 40 +export CORE_MARGIN = 2 + +# A ladder, FLOW_VARIANT=small|medium. base, ORFS's default variant, is +# XiangShan's bridge as it is: its flit widths and its queue depth of 16 +# (system/SoC.scala:127), the only rung that reproduces XiangShan's +# period. medium keeps the flit widths at a depth of 4, small also +# narrows the flits; both are for iterating, in minutes. +export VERILOG_TOP_PARAMS = DEPTH 16 +ifeq ($(FLOW_VARIANT),small) +export VERILOG_TOP_PARAMS = REQ_W 32 RSP_W 16 DAT_W 64 SNP_W 24 DEPTH 4 +else ifeq ($(FLOW_VARIANT),medium) +export VERILOG_TOP_PARAMS = DEPTH 4 +endif diff --git a/flow/designs/asap7/chi_async_bridge/constraint.sdc b/flow/designs/asap7/chi_async_bridge/constraint.sdc new file mode 100644 index 0000000000..b229bf12f3 --- /dev/null +++ b/flow/designs/asap7/chi_async_bridge/constraint.sdc @@ -0,0 +1,173 @@ +# chi_async_bridge: two clocks with no phase relation, and the bridge +# between them. README.md says what each constraint is for. +set sdc_version 2.0 + +# The core clock: a little below what the flow can close, so the worst +# slack stays negative through global route and repair keeps working +# instead of stopping at zero. XiangShan's own bridge, hardened alone +# through this flow, just fails at 300 ps on the core half's async queue +# sink read path, and so does this design (README.md, Results). +set clk_period 290 +# The NoC clock: an unrelated period, about 0.3 times the core's frequency. +# The two never align, and nothing here depends on the ratio. +set noc_clk_period 1021 + +create_clock -name clk -period $clk_period [get_ports clock] +create_clock -name noc_clk -period $noc_clk_period [get_ports noc_clock] + +# ---- The crossing ---------------------------------------------------- +# The clocks are asynchronous, but the paths between them are still +# timed: each must take less than one period of the clock it starts on, +# measured from its first flop's clock pin, without the clock tree. For +# a Gray-coded pointer that keeps every bit within one write of the +# others; the data, read only after its pointer has been synchronised, +# meets it with room to spare. No hold check between the clocks: there +# is no edge to hold against. +set_clock_groups -asynchronous -allow_paths -group clk -group noc_clk +set_max_delay -ignore_clock_latency $clk_period \ + -from [get_clocks clk] -to [get_clocks noc_clk] +set_max_delay -ignore_clock_latency $noc_clk_period \ + -from [get_clocks noc_clk] -to [get_clocks clk] +set_false_path -hold -from [get_clocks clk] -to [get_clocks noc_clk] +set_false_path -hold -from [get_clocks noc_clk] -to [get_clocks clk] + +# noc_reset is asynchronous; each half releases it through its own +# reset synchroniser (reset_gen.sv), whose flops it sets directly. +set_false_path -from [get_ports noc_reset] + +# ---- The ports ------------------------------------------------------- +# Budgeted with set_max_delay, in the shape of $PLATFORM_DIR/constraints.sdc +# but not with its numbers: that file gives a single-clock macro a fixed +# 80 ps per port path, sized for a small macro. Here each domain's ports +# get 80 % of that domain's period, a choice of this file: the tile's +# ports at the core period, the NoC's (noc_*) at the NoC period. That +# file creates one clock, so it is not sourced here. +set tile_in {} +set noc_in {} +foreach p [all_inputs -no_clocks] { + set name [get_full_name $p] + if { $name eq "noc_reset" } { + continue + } elseif { [string match noc_* $name] } { + lappend noc_in $p + } else { + lappend tile_in $p + } +} +set tile_out {} +set noc_out {} +foreach p [all_outputs] { + if { [string match noc_* [get_full_name $p]] } { + lappend noc_out $p + } else { + lappend tile_out $p + } +} +foreach {ins outs period} [list $tile_in $tile_out $clk_period \ + $noc_in $noc_out $noc_clk_period] { + set_max_delay -ignore_clock_latency [expr { $period * 0.8 }] \ + -from $ins -to [all_registers] + set_max_delay -ignore_clock_latency [expr { $period * 0.8 }] \ + -from [all_registers] -to $outs + # Through a domain without a flop: the NoC's ready reaches its flitv + # through one gate (chi_async_bridge_sink.sv, tx_flitv). + set_max_delay [expr { $period * 0.8 }] -from $ins -to $outs +} + +group_path -name in2reg -from [all_inputs -no_clocks] -to [all_registers] +group_path -name reg2out -from [all_registers] -to [all_outputs] +group_path -name reg2reg -from [all_registers] -to [all_registers] +group_path -name in2out -from [all_inputs -no_clocks] -to [all_outputs] + +# ---- The synchronisers ------------------------------------------------ +# A synchroniser's flops resolve metastability in the time a period +# leaves them, so the step from one to the next is kept short: a +# clock-to-output, one inverter (asap7's flop with asynchronous set and +# reset has only an inverted output) and a setup, about four FO4 at this +# flow's 14.37 ps. Five FO4 is the budget. +set sync_hop_max 72 + +# This is the one constraint that names instances, and a name that +# matches nothing would make OpenSTA warn and drop it (STA-0101, +# STA-0471). So the names are checked first, against the netlist this +# file is read with, which is the synthesised one: the flow stops here +# if synthesis has renamed, merged or restructured a synchroniser. +# +# In that netlist a chain flop is named, as timing analysis spells it, +# .bit_[].sync[]$_DFF_PP_ +# (the kept modules (config.mk) joined with '/', the hierarchy inside +# each flattened with '.', yosys's cell type appended; the database +# escapes the brackets, timing analysis does not); sync[SYNC-1] takes +# the asynchronous input, sync[0] is the output. The chains sit inside +# kept modules, so they are found at every level of the hierarchy. +# +# The defaults are chi_async_bridge.sv's; VERILOG_TOP_PARAMS overrides +# them as it overrides the RTL's. +set sync_stages 3 +set depth 16 +if { [info exists ::env(VERILOG_TOP_PARAMS)] } { + foreach {k v} $::env(VERILOG_TOP_PARAMS) { + if { $k eq "DEPTH" } { set depth $v } + if { $k eq "SYNC" } { set sync_stages $v } + } +} +# 6 flit queues and 6 credit queues, each with a pointer synchroniser in +# both halves, of log2(DEPTH)+1 bits; and 7 handshakes into each half. +set pointer_bits [expr { int(round(log($depth) / log(2))) + 1 }] +set expect_chains [expr { 2 * 12 * $pointer_bits + 2 * 7 }] + +proc sync_check_fail { msg } { + error "constraint.sdc: synchronisers: $msg" +} + +# The one input pin an output pin's net drives, or {} if it drives more. +proc sync_only_load { pin } { + set loads [get_pins -quiet -of_objects [get_nets -of_objects $pin] \ + -filter "direction == input"] + if { [llength $loads] != 1 } { return {} } + return $loads +} + +proc sync_output { cell } { + return [get_pins -of_objects $cell -filter "direction == output"] +} + +set chains [dict create] +foreach cell [get_cells -quiet -hierarchical {*_gray.bit_* *sync_link.bit_*}] { + set name [get_full_name $cell] + if { ![regexp {^(.*)\.sync\[([0-9]+)\]} $name -> chain stage] } { + sync_check_fail "unexpected cell name $name" + } + dict set chains $chain $stage $cell +} +if { [dict size $chains] != $expect_chains } { + sync_check_fail "expected $expect_chains chains, found [dict size $chains]" +} +set sync_hops {} +dict for {chain stages} $chains { + if { [dict size $stages] != $sync_stages } { + sync_check_fail "$chain has [dict size $stages] stages, not $sync_stages" + } + for { set s [expr { $sync_stages - 1 }] } { $s > 0 } { incr s -1 } { + set from [dict get $stages $s] + set to [get_full_name [dict get $stages [expr { $s - 1 }]]] + # The output, at most one single-input cell, then the next flop, + # and nothing else on the way. + set load [sync_only_load [sync_output $from]] + if { $load ne {} && [get_full_name [get_cells -of_objects $load]] ne $to } { + set inv [get_cells -of_objects $load] + if { [llength [get_pins -of_objects $inv -filter "direction == input"]] == 1 } { + set load [sync_only_load [sync_output $inv]] + } else { + set load {} + } + } + if { $load eq {} || [get_full_name [get_cells -of_objects $load]] ne $to } { + sync_check_fail "[get_full_name $from] does not drive $to alone" + } + lappend sync_hops $from [dict get $stages [expr { $s - 1 }]] + } +} +foreach {from to} $sync_hops { + set_max_delay -ignore_clock_latency $sync_hop_max -from $from -to $to +} diff --git a/flow/designs/nangate45/gcd/constraint.sdc b/flow/designs/nangate45/gcd/constraint.sdc index cb90dd0090..3cf9c033a9 100644 --- a/flow/designs/nangate45/gcd/constraint.sdc +++ b/flow/designs/nangate45/gcd/constraint.sdc @@ -2,7 +2,7 @@ current_design gcd set clk_name core_clock set clk_port_name clk -set clk_period 0.25 +set clk_period 0.15 set clk_io_pct 0.2 set clk_port [get_ports $clk_port_name] diff --git a/flow/designs/sky130hd/gcd/config.mk b/flow/designs/sky130hd/gcd/config.mk index 40784a9535..887d300926 100644 --- a/flow/designs/sky130hd/gcd/config.mk +++ b/flow/designs/sky130hd/gcd/config.mk @@ -1,7 +1,7 @@ export DESIGN_NAME = gcd export PLATFORM = sky130hd -export VERILOG_FILES = $(DESIGN_HOME)/src/$(DESIGN_NICKNAME)/gcd.v +export VERILOG_FILES = $(DESIGN_HOME)/src/$(DESIGN_NICKNAME)/missing.v export SDC_FILE = $(DESIGN_HOME)/$(PLATFORM)/$(DESIGN_NICKNAME)/constraint.sdc # Adders degrade GCD diff --git a/flow/designs/src/chi_async_bridge/LICENSES/XiangShan-MulanPSL-2.0.txt b/flow/designs/src/chi_async_bridge/LICENSES/XiangShan-MulanPSL-2.0.txt new file mode 100644 index 0000000000..68d8753110 --- /dev/null +++ b/flow/designs/src/chi_async_bridge/LICENSES/XiangShan-MulanPSL-2.0.txt @@ -0,0 +1,132 @@ + + 木兰宽松许可证, 第2版 + + 木兰宽松许可证, 第2版 + 2020年1月 http://license.coscl.org.cn/MulanPSL2 + + + 您对“软件”的复制、使用、修改及分发受木兰宽松许可证,第2版(“本许可证”)的如下条款的约束: + + 0. 定义 + + “软件”是指由“贡献”构成的许可在“本许可证”下的程序和相关文档的集合。 + + “贡献”是指由任一“贡献者”许可在“本许可证”下的受版权法保护的作品。 + + “贡献者”是指将受版权法保护的作品许可在“本许可证”下的自然人或“法人实体”。 + + “法人实体”是指提交贡献的机构及其“关联实体”。 + + “关联实体”是指,对“本许可证”下的行为方而言,控制、受控制或与其共同受控制的机构,此处的控制是指有受控方或共同受控方至少50%直接或间接的投票权、资金或其他有价证券。 + + 1. 授予版权许可 + + 每个“贡献者”根据“本许可证”授予您永久性的、全球性的、免费的、非独占的、不可撤销的版权许可,您可以复制、使用、修改、分发其“贡献”,不论修改与否。 + + 2. 授予专利许可 + + 每个“贡献者”根据“本许可证”授予您永久性的、全球性的、免费的、非独占的、不可撤销的(根据本条规定撤销除外)专利许可,供您制造、委托制造、使用、许诺销售、销售、进口其“贡献”或以其他方式转移其“贡献”。前述专利许可仅限于“贡献者”现在或将来拥有或控制的其“贡献”本身或其“贡献”与许可“贡献”时的“软件”结合而将必然会侵犯的专利权利要求,不包括对“贡献”的修改或包含“贡献”的其他结合。如果您或您的“关联实体”直接或间接地,就“软件”或其中的“贡献”对任何人发起专利侵权诉讼(包括反诉或交叉诉讼)或其他专利维权行动,指控其侵犯专利权,则“本许可证”授予您对“软件”的专利许可自您提起诉讼或发起维权行动之日终止。 + + 3. 无商标许可 + + “本许可证”不提供对“贡献者”的商品名称、商标、服务标志或产品名称的商标许可,但您为满足第4条规定的声明义务而必须使用除外。 + + 4. 分发限制 + + 您可以在任何媒介中将“软件”以源程序形式或可执行形式重新分发,不论修改与否,但您必须向接收者提供“本许可证”的副本,并保留“软件”中的版权、商标、专利及免责声明。 + + 5. 免责声明与责任限制 + + “软件”及其中的“贡献”在提供时不带任何明示或默示的担保。在任何情况下,“贡献者”或版权所有者不对任何人因使用“软件”或其中的“贡献”而引发的任何直接或间接损失承担责任,不论因何种原因导致或者基于何种法律理论,即使其曾被建议有此种损失的可能性。 + + 6. 语言 + “本许可证”以中英文双语表述,中英文版本具有同等法律效力。如果中英文版本存在任何冲突不一致,以中文版为准。 + + 条款结束 + + 如何将木兰宽松许可证,第2版,应用到您的软件 + + 如果您希望将木兰宽松许可证,第2版,应用到您的新软件,为了方便接收者查阅,建议您完成如下三步: + + 1, 请您补充如下声明中的空白,包括软件名、软件的首次发表年份以及您作为版权人的名字; + + 2, 请您在软件包的一级目录下创建以“LICENSE”为名的文件,将整个许可证文本放入该文件中; + + 3, 请将如下声明文本放入每个源文件的头部注释中。 + + Copyright (c) 2020-2021 Institute of Computing Technology, Chinese Academy of Sciences + Copyright (c) 2020-2021 Peng Cheng Laboratory + + XiangShan is licensed under Mulan PSL v2. + You can use this software according to the terms and conditions of the Mulan PSL v2. + You may obtain a copy of Mulan PSL v2 at: + http://license.coscl.org.cn/MulanPSL2 + THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT, MERCHANTABILITY OR FIT FOR A PARTICULAR PURPOSE. + See the Mulan PSL v2 for more details. + + + Mulan Permissive Software License,Version 2 + + Mulan Permissive Software License,Version 2 (Mulan PSL v2) + January 2020 http://license.coscl.org.cn/MulanPSL2 + + Your reproduction, use, modification and distribution of the Software shall be subject to Mulan PSL v2 (this License) with the following terms and conditions: + + 0. Definition + + Software means the program and related documents which are licensed under this License and comprise all Contribution(s). + + Contribution means the copyrightable work licensed by a particular Contributor under this License. + + Contributor means the Individual or Legal Entity who licenses its copyrightable work under this License. + + Legal Entity means the entity making a Contribution and all its Affiliates. + + Affiliates means entities that control, are controlled by, or are under common control with the acting entity under this License, ‘control’ means direct or indirect ownership of at least fifty percent (50%) of the voting power, capital or other securities of controlled or commonly controlled entity. + + 1. Grant of Copyright License + + Subject to the terms and conditions of this License, each Contributor hereby grants to you a perpetual, worldwide, royalty-free, non-exclusive, irrevocable copyright license to reproduce, use, modify, or distribute its Contribution, with modification or not. + + 2. Grant of Patent License + + Subject to the terms and conditions of this License, each Contributor hereby grants to you a perpetual, worldwide, royalty-free, non-exclusive, irrevocable (except for revocation under this Section) patent license to make, have made, use, offer for sale, sell, import or otherwise transfer its Contribution, where such patent license is only limited to the patent claims owned or controlled by such Contributor now or in future which will be necessarily infringed by its Contribution alone, or by combination of the Contribution with the Software to which the Contribution was contributed. The patent license shall not apply to any modification of the Contribution, and any other combination which includes the Contribution. If you or your Affiliates directly or indirectly institute patent litigation (including a cross claim or counterclaim in a litigation) or other patent enforcement activities against any individual or entity by alleging that the Software or any Contribution in it infringes patents, then any patent license granted to you under this License for the Software shall terminate as of the date such litigation or activity is filed or taken. + + 3. No Trademark License + + No trademark license is granted to use the trade names, trademarks, service marks, or product names of Contributor, except as required to fulfill notice requirements in Section 4. + + 4. Distribution Restriction + + You may distribute the Software in any medium with or without modification, whether in source or executable forms, provided that you provide recipients with a copy of this License and retain copyright, patent, trademark and disclaimer statements in the Software. + + 5. Disclaimer of Warranty and Limitation of Liability + + THE SOFTWARE AND CONTRIBUTION IN IT ARE PROVIDED WITHOUT WARRANTIES OF ANY KIND, EITHER EXPRESS OR IMPLIED. IN NO EVENT SHALL ANY CONTRIBUTOR OR COPYRIGHT HOLDER BE LIABLE TO YOU FOR ANY DAMAGES, INCLUDING, BUT NOT LIMITED TO ANY DIRECT, OR INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING FROM YOUR USE OR INABILITY TO USE THE SOFTWARE OR THE CONTRIBUTION IN IT, NO MATTER HOW IT’S CAUSED OR BASED ON WHICH LEGAL THEORY, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. + + 6. Language + + THIS LICENSE IS WRITTEN IN BOTH CHINESE AND ENGLISH, AND THE CHINESE VERSION AND ENGLISH VERSION SHALL HAVE THE SAME LEGAL EFFECT. IN THE CASE OF DIVERGENCE BETWEEN THE CHINESE AND ENGLISH VERSIONS, THE CHINESE VERSION SHALL PREVAIL. + + END OF THE TERMS AND CONDITIONS + + How to Apply the Mulan Permissive Software License,Version 2 (Mulan PSL v2) to Your Software + + To apply the Mulan PSL v2 to your work, for easy identification by recipients, you are suggested to complete following three steps: + + i Fill in the blanks in following statement, including insert your software name, the year of the first publication of your software, and your name identified as the copyright owner; + + ii Create a file named “LICENSE” which contains the whole context of this License in the first directory of your software package; + + iii Attach the statement to the appropriate annotated syntax at the beginning of each source file. + + + Copyright (c) 2020-2021 Institute of Computing Technology, Chinese Academy of Sciences + Copyright (c) 2020-2021 Peng Cheng Laboratory + + XiangShan is licensed under Mulan PSL v2. + You can use this software according to the terms and conditions of the Mulan PSL v2. + You may obtain a copy of Mulan PSL v2 at: + http://license.coscl.org.cn/MulanPSL2 + THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT, MERCHANTABILITY OR FIT FOR A PARTICULAR PURPOSE. + See the Mulan PSL v2 for more details. \ No newline at end of file diff --git a/flow/designs/src/chi_async_bridge/LICENSES/rocket-chip-Apache-2.0.txt b/flow/designs/src/chi_async_bridge/LICENSES/rocket-chip-Apache-2.0.txt new file mode 100644 index 0000000000..7e70933754 --- /dev/null +++ b/flow/designs/src/chi_async_bridge/LICENSES/rocket-chip-Apache-2.0.txt @@ -0,0 +1,202 @@ + + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright 2016-2017 SiFive, Inc. + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/flow/designs/src/chi_async_bridge/SOURCE.md b/flow/designs/src/chi_async_bridge/SOURCE.md new file mode 100644 index 0000000000..5ce56a8493 --- /dev/null +++ b/flow/designs/src/chi_async_bridge/SOURCE.md @@ -0,0 +1,31 @@ +# chi_async_bridge source + +- Top: `chi_async_bridge` +- Upstream sources, as XiangShan pins them: + - `OpenXiangShan/XiangShan`, commit + `aa6b52033add528a504bdb2c2b726100d89f070a` + - `OpenXiangShan/XSCache`, commit + `300515bc7b2f65ca988041a984204489d80ec2fb` + - `OpenXiangShan/Utility`, commit + `eb8e12b00a33e4716e7778175f6dd45b7a3a9ede` + - `OpenXiangShan/rocket-chip`, commit + `a2df1a42399cfe2b343eeb5293796268dc2bc211` + +The upstream RTL is Chisel. These files are not the Verilog it +generates: they were rewritten as readable SystemVerilog, module by +module, from that Chisel, and each file's header names the Scala source +and lines it models. They are derived from that source and keep its +license: + +| file | derived from | license | +|---|---|---| +| `async_queue_source.sv`, `async_queue_sink.sv` | rocket-chip `src/main/scala/util/AsyncQueue.scala` | Apache-2.0, `LICENSES/rocket-chip-Apache-2.0.txt` | +| `sync_shift_reg.sv` | rocket-chip `src/main/scala/util/SynchronizerReg.scala` | Apache-2.0, `LICENSES/rocket-chip-Apache-2.0.txt` | +| `chi_async_bridge_source.sv`, `chi_async_bridge_sink.sv`, `shadow_buffer.sv` | XSCache `src/main/scala/xscache/chi/AsyncBridge.scala` | Mulan PSL v2, `LICENSES/XiangShan-MulanPSL-2.0.txt` | +| `reset_gen.sv` | Utility `src/main/scala/utility/ResetGen.scala` | Mulan PSL v2, `LICENSES/XiangShan-MulanPSL-2.0.txt` | +| `chi_async_bridge.sv` | XiangShan `XSTileWrap.scala` and `XSNoCTop.scala`, which place the two halves | Mulan PSL v2, `LICENSES/XiangShan-MulanPSL-2.0.txt` | + +`LICENSES/rocket-chip-Apache-2.0.txt` is rocket-chip's `LICENSE.SiFive`, +to which those Scala files refer. `LICENSES/XiangShan-MulanPSL-2.0.txt` +is XSCache's `LICENSE`; the Utility and XiangShan sources carry the same +Mulan PSL v2 header. diff --git a/flow/designs/src/chi_async_bridge/async_queue_sink.sv b/flow/designs/src/chi_async_bridge/async_queue_sink.sv new file mode 100644 index 0000000000..084672dcd4 --- /dev/null +++ b/flow/designs/src/chi_async_bridge/async_queue_sink.sv @@ -0,0 +1,94 @@ +// SPDX-License-Identifier: Apache-2.0 +// Copyright 2016-2017 SiFive, Inc. +// Changed from the original: rewritten as readable SystemVerilog from +// rocket-chip's Chisel. SOURCE.md names the source and its license. +// +// The reading half of an asynchronous queue: rocket-chip's AsyncQueueSink +// (util/AsyncQueue.scala:148-179 at a2df1a4), safe = false, narrow = false. +// +// The source's write pointer arrives through a SYNC-deep synchroniser +// (widx_gray). Once it says an entry is there, the entry is read with a +// mux over all DEPTH entries of the source's memory, straight into +// deq_bits_reg. That mux is the data crossing: it starts at flops on the +// source's clock and ends at a flop on this one. Rocket-chip's comment +// states the contract: "the mux is safe because timing analysis ensures +// ridx has reached the register". constraint.sdc is that timing analysis. +module async_queue_sink #( + parameter int WIDTH = 8, + parameter int DEPTH = 16, + parameter int SYNC = 3, + parameter bit PULSE = 1'b0, + localparam int BITS = $clog2(DEPTH) +) ( + input logic clock, + input logic reset, + output logic deq_valid, + input logic deq_ready, + output logic [ WIDTH-1:0] deq_bits, + input logic [DEPTH*WIDTH-1:0] async_mem, + output logic [ BITS:0] async_ridx, + input logic [ BITS:0] async_widx +); + // AsyncQueueParams requires a power-of-two depth (util/AsyncQueue.scala:19); + // the Gray pointers and the read index assume it. + if (DEPTH < 2 || (DEPTH & (DEPTH - 1)) != 0) begin : depth_check + $error("async_queue_sink: DEPTH must be a power of 2 and at least 2"); + end + + logic fire; + assign fire = deq_valid && deq_ready; + + logic [BITS:0] ridx_bin, ridx_inc, ridx; + assign ridx_inc = ridx_bin + (BITS + 1)'(fire); + assign ridx = ridx_inc ^ (ridx_inc >> 1); + always_ff @(posedge clock or posedge reset) begin + if (reset) ridx_bin <= '0; + else ridx_bin <= ridx_inc; + end + + logic [BITS:0] widx; + sync_shift_reg #( + .WIDTH(BITS + 1), + .SYNC (SYNC) + ) widx_gray ( + .clock(clock), + .reset(reset), + .d (async_widx), + .q (widx) + ); + + logic valid; + assign valid = ridx != widx; + + logic valid_reg; + always_ff @(posedge clock or posedge reset) begin + if (reset) valid_reg <= 1'b0; + else valid_reg <= valid; + end + assign deq_valid = valid_reg; + + logic [BITS:0] ridx_gray; + always_ff @(posedge clock or posedge reset) begin + if (reset) ridx_gray <= '0; + else ridx_gray <= ridx; + end + assign async_ridx = ridx_gray; + + if (PULSE) begin : no_mem + assign deq_bits = '0; + end else begin : mem_ + logic [BITS-1:0] index; + if (BITS == 1) begin : one + assign index = ridx[0] ^ ridx[1]; + end else begin : many + assign index = ridx[BITS-1:0] ^ {ridx[BITS], {(BITS - 1) {1'b0}}}; + end + // ClockCrossingReg (util/SynchronizerReg.scala): not reset, loads + // only when the entry it selects is valid. + logic [WIDTH-1:0] deq_bits_reg; + always_ff @(posedge clock) begin + if (valid) deq_bits_reg <= async_mem[index*WIDTH+:WIDTH]; + end + assign deq_bits = deq_bits_reg; + end +endmodule diff --git a/flow/designs/src/chi_async_bridge/async_queue_source.sv b/flow/designs/src/chi_async_bridge/async_queue_source.sv new file mode 100644 index 0000000000..1bd30fb46e --- /dev/null +++ b/flow/designs/src/chi_async_bridge/async_queue_source.sv @@ -0,0 +1,104 @@ +// SPDX-License-Identifier: Apache-2.0 +// Copyright 2016-2017 SiFive, Inc. +// Changed from the original: rewritten as readable SystemVerilog from +// rocket-chip's Chisel. SOURCE.md names the source and its license. +// +// The writing half of an asynchronous queue: rocket-chip's +// AsyncQueueSource (util/AsyncQueue.scala:70-104 at a2df1a4) with +// safe = false and narrow = false, which is how XiangShan's CHI bridge +// configures it (AsyncQueueParams(depth = 16, sync = 3, safe = false), +// system/SoC.scala:127). +// +// What crosses to the reading domain, all of it straight from a flop: +// mem DEPTH entries of WIDTH bits, written in this domain, never reset; +// widx the write pointer in Gray code (widx_gray). +// What comes back: ridx, the reader's Gray pointer, through a SYNC-deep +// synchroniser (ridx_gray). +// +// PULSE = 1 is rocket-chip's AsyncQueueSource(UInt(0.W)): no data, the +// queue only counts events. The CHI bridge returns link credits this way. +module async_queue_source #( + parameter int WIDTH = 8, + parameter int DEPTH = 16, + parameter int SYNC = 3, + parameter bit PULSE = 1'b0, + localparam int BITS = $clog2(DEPTH) +) ( + input logic clock, + input logic reset, + input logic enq_valid, + output logic enq_ready, + input logic [ WIDTH-1:0] enq_bits, + output logic [DEPTH*WIDTH-1:0] async_mem, + input logic [ BITS:0] async_ridx, + output logic [ BITS:0] async_widx +); + // AsyncQueueParams requires a power-of-two depth (util/AsyncQueue.scala:19); + // the Gray pointers and the full test assume it. + if (DEPTH < 2 || (DEPTH & (DEPTH - 1)) != 0) begin : depth_check + $error("async_queue_source: DEPTH must be a power of 2 and at least 2"); + end + + logic fire; + assign fire = enq_valid && enq_ready; + + // GrayCounter (AsyncQueue.scala:49-56): a binary register, and the Gray + // code of the value it is about to take. + logic [BITS:0] widx_bin, widx_inc, widx; + assign widx_inc = widx_bin + (BITS + 1)'(fire); + assign widx = widx_inc ^ (widx_inc >> 1); + always_ff @(posedge clock or posedge reset) begin + if (reset) widx_bin <= '0; + else widx_bin <= widx_inc; + end + + logic [BITS:0] ridx; + sync_shift_reg #( + .WIDTH(BITS + 1), + .SYNC (SYNC) + ) ridx_gray ( + .clock(clock), + .reset(reset), + .d (async_ridx), + .q (ridx) + ); + + // Full when the write pointer is one lap ahead of the read pointer: in + // Gray code, the top two bits inverted. + logic ready; + assign ready = widx != (ridx ^ (BITS + 1)'(DEPTH | (DEPTH >> 1))); + + logic ready_reg; + always_ff @(posedge clock or posedge reset) begin + if (reset) ready_reg <= 1'b0; + else ready_reg <= ready; + end + assign enq_ready = ready_reg; + + logic [BITS:0] widx_gray; + always_ff @(posedge clock or posedge reset) begin + if (reset) widx_gray <= '0; + else widx_gray <= widx; + end + assign async_widx = widx_gray; + + if (PULSE) begin : no_mem + assign async_mem = '0; + end else begin : mem_ + // The entry being written, from the registered Gray pointer. + logic [BITS-1:0] index; + if (BITS == 1) begin : one + assign index = widx_gray[0] ^ widx_gray[1]; + end else begin : many + assign index = widx_gray[BITS-1:0] ^ {widx_gray[BITS], {(BITS - 1) {1'b0}}}; + end + // Reg(Vec(depth, gen)): one register per entry, as firtool emits it. + for (genvar i = 0; i < DEPTH; i++) begin : mem + logic [WIDTH-1:0] entry; + always_ff @(posedge clock) begin + if (fire && index == BITS'(i)) entry <= enq_bits; + end + assign async_mem[i*WIDTH+:WIDTH] = entry; + end + end +endmodule diff --git a/flow/designs/src/chi_async_bridge/chi_async_bridge.sv b/flow/designs/src/chi_async_bridge/chi_async_bridge.sv new file mode 100644 index 0000000000..2cf6796c7c --- /dev/null +++ b/flow/designs/src/chi_async_bridge/chi_async_bridge.sv @@ -0,0 +1,186 @@ +// SPDX-License-Identifier: MulanPSL-2.0 +// Copyright (c) 2024-2025 Beijing Institute of Open Source Chip (BOSC) +// Copyright (c) 2024-2025 Institute of Computing Technology, Chinese Academy of Sciences +// Changed from the original: rewritten as readable SystemVerilog from +// XiangShan's Chisel. SOURCE.md names the source and its license. +// +// chi_async_bridge: the asynchronous CHI bridge between XiangShan's tile +// and its network-on-chip, both halves in one block. README.md (beside +// config.mk) tells the story; this file only wires the halves together. +// +// clock the core clock: the tile half, chi_async_bridge_source.sv, +// which XiangShan puts in XSTileWrap beside XSTile. +// noc_clock the NoC clock: the NoC half, chi_async_bridge_sink.sv, +// which XiangShan puts in XSNoCTop. +// +// Every wire between the halves, the a_* signals below, crosses from one +// clock domain to the other. In XiangShan they are the pins between two +// separately built blocks; here they are nets inside one, so timing +// analysis sees both ends of every crossing. +// +// The tile side's ports keep the halves' own names; the NoC side's are +// prefixed noc_. Both halves are reset by noc_reset, each through its own +// reset synchroniser (XSTileWrap.scala:112, XSNoCTop.scala:84). +module chi_async_bridge #( + parameter int REQ_W = 125, + parameter int RSP_W = 51, + parameter int DAT_W = 385, + parameter int SNP_W = 88, + parameter int DEPTH = 16, + parameter int SYNC = 3, + localparam int B = $clog2(DEPTH) +) ( + input logic clock, + input logic noc_clock, + input logic noc_reset, + input logic tx_req_flitv, + input logic [REQ_W-1:0] tx_req_flit, + output logic tx_req_lcrdv, + input logic tx_rsp_flitv, + input logic [RSP_W-1:0] tx_rsp_flit, + output logic tx_rsp_lcrdv, + input logic tx_dat_flitv, + input logic [DAT_W-1:0] tx_dat_flit, + output logic tx_dat_lcrdv, + output logic rx_rsp_flitv, + output logic [RSP_W-1:0] rx_rsp_flit, + input logic rx_rsp_lcrdv, + output logic rx_dat_flitv, + output logic [DAT_W-1:0] rx_dat_flit, + input logic rx_dat_lcrdv, + output logic rx_snp_flitv, + output logic [SNP_W-1:0] rx_snp_flit, + input logic rx_snp_lcrdv, + input logic [2:0] tx_flitpend, + output logic [2:0] rx_flitpend, + input logic tx_linkactivereq, + output logic tx_linkactiveack, + output logic rx_linkactivereq, + input logic rx_linkactiveack, + input logic txsactive, + output logic rxsactive, + input logic syscoreq, + output logic syscoack, + output logic noc_tx_req_flitv, + output logic [REQ_W-1:0] noc_tx_req_flit, + input logic noc_tx_req_ready, + input logic noc_tx_req_lcrdv, + output logic noc_tx_rsp_flitv, + output logic [RSP_W-1:0] noc_tx_rsp_flit, + input logic noc_tx_rsp_ready, + input logic noc_tx_rsp_lcrdv, + output logic noc_tx_dat_flitv, + output logic [DAT_W-1:0] noc_tx_dat_flit, + input logic noc_tx_dat_ready, + input logic noc_tx_dat_lcrdv, + input logic noc_rx_rsp_flitv, + input logic [RSP_W-1:0] noc_rx_rsp_flit, + output logic noc_rx_rsp_lcrdv, + input logic noc_rx_dat_flitv, + input logic [DAT_W-1:0] noc_rx_dat_flit, + output logic noc_rx_dat_lcrdv, + input logic noc_rx_snp_flitv, + input logic [SNP_W-1:0] noc_rx_snp_flit, + output logic noc_rx_snp_lcrdv, + output logic [2:0] noc_tx_flitpend, + input logic [2:0] noc_rx_flitpend, + output logic noc_tx_linkactivereq, + input logic noc_tx_linkactiveack, + input logic noc_rx_linkactivereq, + output logic noc_rx_linkactiveack, + output logic noc_txsactive, + input logic noc_rxsactive, + output logic noc_syscoreq, + input logic noc_syscoack +); + logic tile_reset, noc_side_reset; + reset_gen tile_reset_sync ( + .clock(clock), .reset(noc_reset), .o_reset(tile_reset)); + reset_gen noc_reset_sync ( + .clock(noc_clock), .reset(noc_reset), .o_reset(noc_side_reset)); + + // The crossing. + logic [DEPTH*REQ_W-1:0] a_tx_req_mem; + logic [B:0] a_tx_req_widx; + logic [B:0] a_tx_req_ridx; + logic [DEPTH*RSP_W-1:0] a_tx_rsp_mem; + logic [B:0] a_tx_rsp_widx; + logic [B:0] a_tx_rsp_ridx; + logic [DEPTH*DAT_W-1:0] a_tx_dat_mem; + logic [B:0] a_tx_dat_widx; + logic [B:0] a_tx_dat_ridx; + logic [DEPTH*RSP_W-1:0] a_rx_rsp_mem; + logic [B:0] a_rx_rsp_widx; + logic [B:0] a_rx_rsp_ridx; + logic [DEPTH*DAT_W-1:0] a_rx_dat_mem; + logic [B:0] a_rx_dat_widx; + logic [B:0] a_rx_dat_ridx; + logic [DEPTH*SNP_W-1:0] a_rx_snp_mem; + logic [B:0] a_rx_snp_widx; + logic [B:0] a_rx_snp_ridx; + logic [2:0][B:0] a_tx_lcrdv_widx; + logic [2:0][B:0] a_tx_lcrdv_ridx; + logic [2:0][B:0] a_rx_lcrdv_widx; + logic [2:0][B:0] a_rx_lcrdv_ridx; + logic [2:0] a_tx_flitpend; + logic [2:0] a_rx_flitpend; + logic a_tx_linkactivereq; + logic a_tx_linkactiveack; + logic a_rx_linkactivereq; + logic a_rx_linkactiveack; + logic a_txsactive; + logic a_rxsactive; + logic a_syscoreq; + logic a_syscoack; + + chi_async_bridge_source #( + .REQ_W(REQ_W), .RSP_W(RSP_W), .DAT_W(DAT_W), .SNP_W(SNP_W), + .DEPTH(DEPTH), .SYNC(SYNC) + ) source ( + .clock(clock), + .reset(tile_reset), + .reset_finish(), + .* + ); + + chi_async_bridge_sink #( + .REQ_W(REQ_W), .RSP_W(RSP_W), .DAT_W(DAT_W), .SNP_W(SNP_W), + .DEPTH(DEPTH), .SYNC(SYNC) + ) sink ( + .clock(noc_clock), + .reset(noc_side_reset), + .tx_req_flitv(noc_tx_req_flitv), + .tx_req_flit(noc_tx_req_flit), + .tx_req_ready(noc_tx_req_ready), + .tx_req_lcrdv(noc_tx_req_lcrdv), + .tx_rsp_flitv(noc_tx_rsp_flitv), + .tx_rsp_flit(noc_tx_rsp_flit), + .tx_rsp_ready(noc_tx_rsp_ready), + .tx_rsp_lcrdv(noc_tx_rsp_lcrdv), + .tx_dat_flitv(noc_tx_dat_flitv), + .tx_dat_flit(noc_tx_dat_flit), + .tx_dat_ready(noc_tx_dat_ready), + .tx_dat_lcrdv(noc_tx_dat_lcrdv), + .rx_rsp_flitv(noc_rx_rsp_flitv), + .rx_rsp_flit(noc_rx_rsp_flit), + .rx_rsp_lcrdv(noc_rx_rsp_lcrdv), + .rx_dat_flitv(noc_rx_dat_flitv), + .rx_dat_flit(noc_rx_dat_flit), + .rx_dat_lcrdv(noc_rx_dat_lcrdv), + .rx_snp_flitv(noc_rx_snp_flitv), + .rx_snp_flit(noc_rx_snp_flit), + .rx_snp_lcrdv(noc_rx_snp_lcrdv), + .tx_flitpend(noc_tx_flitpend), + .rx_flitpend(noc_rx_flitpend), + .tx_linkactivereq(noc_tx_linkactivereq), + .tx_linkactiveack(noc_tx_linkactiveack), + .rx_linkactivereq(noc_rx_linkactivereq), + .rx_linkactiveack(noc_rx_linkactiveack), + .txsactive(noc_txsactive), + .rxsactive(noc_rxsactive), + .syscoreq(noc_syscoreq), + .syscoack(noc_syscoack), + .reset_finish(), + .* + ); +endmodule diff --git a/flow/designs/src/chi_async_bridge/chi_async_bridge_sink.sv b/flow/designs/src/chi_async_bridge/chi_async_bridge_sink.sv new file mode 100644 index 0000000000..b4ff26530a --- /dev/null +++ b/flow/designs/src/chi_async_bridge/chi_async_bridge_sink.sv @@ -0,0 +1,188 @@ +// SPDX-License-Identifier: MulanPSL-2.0 +// Copyright (c) 2020-2021 Institute of Computing Technology, Chinese Academy of Sciences +// Copyright (c) 2020-2021 Peng Cheng Laboratory +// Changed from the original: rewritten as readable SystemVerilog from +// XiangShan's Chisel. SOURCE.md names the source and its license. +// +// The NoC's half of the bridge, on the NoC clock: XSCache's +// CHIAsyncBridgeSink (xscache/chi/AsyncBridge.scala:227-341 at 300515b), +// which XSNoCTop instantiates (XSNoCTop.scala:275-276). The mirror image +// of chi_async_bridge_source.sv: tx flits arrive through async queue +// sinks, rx rsp and dat leave through shadow buffers and async queue +// sources, rx snp through an async queue source alone. +// +// Not modelled: the NoC link layer at AsyncBridge.scala:297-339 (the +// link-state machines and the L-credit managers that return rx credits +// early and hold tx flits back). It is logic of the NoC's own clock +// domain on the far side of the crossing; here its ready and credits are +// ports, and rx credits cross back the way snp's always do. +module chi_async_bridge_sink #( + parameter int REQ_W = 125, + parameter int RSP_W = 51, + parameter int DAT_W = 385, + parameter int SNP_W = 88, + parameter int DEPTH = 16, + parameter int SYNC = 3, + localparam int B = $clog2(DEPTH) +) ( + input logic clock, + input logic reset, + + // The NoC's CHI port. + output logic tx_req_flitv, + output logic [REQ_W-1:0] tx_req_flit, + input logic tx_req_ready, + input logic tx_req_lcrdv, + output logic tx_rsp_flitv, + output logic [RSP_W-1:0] tx_rsp_flit, + input logic tx_rsp_ready, + input logic tx_rsp_lcrdv, + output logic tx_dat_flitv, + output logic [DAT_W-1:0] tx_dat_flit, + input logic tx_dat_ready, + input logic tx_dat_lcrdv, + input logic rx_rsp_flitv, + input logic [RSP_W-1:0] rx_rsp_flit, + output logic rx_rsp_lcrdv, + input logic rx_dat_flitv, + input logic [DAT_W-1:0] rx_dat_flit, + output logic rx_dat_lcrdv, + input logic rx_snp_flitv, + input logic [SNP_W-1:0] rx_snp_flit, + output logic rx_snp_lcrdv, + output logic [ 2:0] tx_flitpend, // req, rsp, dat + input logic [ 2:0] rx_flitpend, // rsp, dat, snp + output logic tx_linkactivereq, + input logic tx_linkactiveack, + input logic rx_linkactivereq, + output logic rx_linkactiveack, + output logic txsactive, + input logic rxsactive, + output logic syscoreq, + input logic syscoack, + output logic reset_finish, + + // The asynchronous side, to the tile half. + input logic [DEPTH*REQ_W-1:0] a_tx_req_mem, + input logic [ B:0] a_tx_req_widx, + output logic [ B:0] a_tx_req_ridx, + input logic [DEPTH*RSP_W-1:0] a_tx_rsp_mem, + input logic [ B:0] a_tx_rsp_widx, + output logic [ B:0] a_tx_rsp_ridx, + input logic [DEPTH*DAT_W-1:0] a_tx_dat_mem, + input logic [ B:0] a_tx_dat_widx, + output logic [ B:0] a_tx_dat_ridx, + output logic [DEPTH*RSP_W-1:0] a_rx_rsp_mem, + output logic [ B:0] a_rx_rsp_widx, + input logic [ B:0] a_rx_rsp_ridx, + output logic [DEPTH*DAT_W-1:0] a_rx_dat_mem, + output logic [ B:0] a_rx_dat_widx, + input logic [ B:0] a_rx_dat_ridx, + output logic [DEPTH*SNP_W-1:0] a_rx_snp_mem, + output logic [ B:0] a_rx_snp_widx, + input logic [ B:0] a_rx_snp_ridx, + output logic [ 2:0][B:0] a_tx_lcrdv_widx, + input logic [ 2:0][B:0] a_tx_lcrdv_ridx, + input logic [ 2:0][B:0] a_rx_lcrdv_widx, + output logic [ 2:0][B:0] a_rx_lcrdv_ridx, + input logic [ 2:0] a_tx_flitpend, + output logic [ 2:0] a_rx_flitpend, + input logic a_tx_linkactivereq, + output logic a_tx_linkactiveack, + output logic a_rx_linkactivereq, + input logic a_rx_linkactiveack, + input logic a_txsactive, + output logic a_rxsactive, + input logic a_syscoreq, + output logic a_syscoack +); + // ---- tx: async queue sink, held back by the NoC's ready ------------- + `define CHI_TX(ch, W) \ + logic ch``_valid; \ + async_queue_sink #(.WIDTH(W), .DEPTH(DEPTH), .SYNC(SYNC)) \ + asyncQSink_``ch``_flit ( \ + .clock(clock), .reset(reset), \ + .deq_valid(ch``_valid), .deq_ready(tx_``ch``_ready), \ + .deq_bits(tx_``ch``_flit), .async_mem(a_tx_``ch``_mem), \ + .async_ridx(a_tx_``ch``_ridx), .async_widx(a_tx_``ch``_widx)); \ + assign tx_``ch``_flitv = ch``_valid && tx_``ch``_ready; + `CHI_TX(req, REQ_W) + `CHI_TX(rsp, RSP_W) + `CHI_TX(dat, DAT_W) + `undef CHI_TX + + // ---- rx: shadow buffer and async queue source (snp: no buffer) ------ + `define CHI_RX_BUF(ch, W) \ + logic ch``_sb_valid, ch``_sb_ready; \ + logic [W-1:0] ch``_sb_bits; \ + shadow_buffer #(.WIDTH(W)) shadowBuffer_``ch``_flit ( \ + .clock(clock), .reset(reset), \ + .enq_valid(rx_``ch``_flitv), .enq_ready(), .enq_bits(rx_``ch``_flit), \ + .deq_valid(ch``_sb_valid), .deq_ready(ch``_sb_ready), \ + .deq_bits(ch``_sb_bits)); \ + async_queue_source #(.WIDTH(W), .DEPTH(DEPTH), .SYNC(SYNC)) \ + asyncQSource_``ch``_flit ( \ + .clock(clock), .reset(reset), \ + .enq_valid(ch``_sb_valid), .enq_ready(ch``_sb_ready), \ + .enq_bits(ch``_sb_bits), .async_mem(a_rx_``ch``_mem), \ + .async_ridx(a_rx_``ch``_ridx), .async_widx(a_rx_``ch``_widx)); + `CHI_RX_BUF(rsp, RSP_W) + `CHI_RX_BUF(dat, DAT_W) + `undef CHI_RX_BUF + async_queue_source #(.WIDTH(SNP_W), .DEPTH(DEPTH), .SYNC(SYNC)) + asyncQSource_snp_flit ( + .clock(clock), .reset(reset), + .enq_valid(rx_snp_flitv), .enq_ready(), .enq_bits(rx_snp_flit), + .async_mem(a_rx_snp_mem), .async_ridx(a_rx_snp_ridx), + .async_widx(a_rx_snp_widx)); + + // ---- link credits, as pulse queues ---------------------------------- + logic [2:0] tx_lcrdv, rx_lcrdv; + assign tx_lcrdv = {tx_dat_lcrdv, tx_rsp_lcrdv, tx_req_lcrdv}; + for (genvar c = 0; c < 3; c++) begin : lcrdv + async_queue_source #(.WIDTH(1), .DEPTH(DEPTH), .SYNC(SYNC), .PULSE(1'b1)) + asyncQBitSource_tx_lcrdv ( + .clock(clock), .reset(reset), + .enq_valid(tx_lcrdv[c]), .enq_ready(), .enq_bits(1'b0), + .async_mem(), .async_ridx(a_tx_lcrdv_ridx[c]), + .async_widx(a_tx_lcrdv_widx[c])); + async_queue_sink #(.WIDTH(1), .DEPTH(DEPTH), .SYNC(SYNC), .PULSE(1'b1)) + asyncQBitSink_rx_lcrdv ( + .clock(clock), .reset(reset), + .deq_valid(rx_lcrdv[c]), .deq_ready(1'b1), .deq_bits(), + .async_mem('0), .async_ridx(a_rx_lcrdv_ridx[c]), + .async_widx(a_rx_lcrdv_widx[c])); + end + assign {rx_snp_lcrdv, rx_dat_lcrdv, rx_rsp_lcrdv} = rx_lcrdv; + + // ---- link handshakes ------------------------------------------------ + // Out: straight through (AsyncBridge.scala:258-264). + assign a_rxsactive = rxsactive; + assign a_tx_linkactiveack = tx_linkactiveack; + assign a_rx_linkactivereq = rx_linkactivereq; + assign a_syscoack = syscoack; + assign a_rx_flitpend = rx_flitpend; + + // In: synchronised (AsyncBridge.scala:277-284). + logic [6:0] in_sync; + sync_shift_reg #(.WIDTH(7), .SYNC(SYNC)) sync_link ( + .clock(clock), .reset(reset), + .d({a_tx_flitpend, a_syscoreq, a_tx_linkactivereq, a_rx_linkactiveack, + a_txsactive}), + .q(in_sync)); + assign txsactive = in_sync[0]; + assign rx_linkactiveack = in_sync[1] && reset_finish; + assign tx_linkactivereq = in_sync[2] && reset_finish; + assign syscoreq = in_sync[3]; + assign tx_flitpend = in_sync[6:4]; + + // resetFinish: 100 cycles after reset (AsyncBridge.scala:286-292). + localparam int RESET_FINISH_MAX = 100; + logic [7:0] reset_finish_counter; + always_ff @(posedge clock or posedge reset) begin + if (reset) reset_finish_counter <= '0; + else if (reset_finish_counter < 8'(RESET_FINISH_MAX)) + reset_finish_counter <= reset_finish_counter + 1'b1; + end + assign reset_finish = reset_finish_counter >= 8'(RESET_FINISH_MAX); +endmodule diff --git a/flow/designs/src/chi_async_bridge/chi_async_bridge_source.sv b/flow/designs/src/chi_async_bridge/chi_async_bridge_source.sv new file mode 100644 index 0000000000..c9c1f88a58 --- /dev/null +++ b/flow/designs/src/chi_async_bridge/chi_async_bridge_source.sv @@ -0,0 +1,182 @@ +// SPDX-License-Identifier: MulanPSL-2.0 +// Copyright (c) 2020-2021 Institute of Computing Technology, Chinese Academy of Sciences +// Copyright (c) 2020-2021 Peng Cheng Laboratory +// Changed from the original: rewritten as readable SystemVerilog from +// XiangShan's Chisel. SOURCE.md names the source and its license. +// +// The tile's half of the bridge, on the core clock: XSCache's +// CHIAsyncBridgeSource (xscache/chi/AsyncBridge.scala:157-225 at +// 300515b), which XSTileWrap instantiates beside XSTile +// (XSTileWrap.scala:190-196). +// +// tx req, rsp, dat: flits from the tile's L2 enter a shadow buffer and +// an async queue source; the NoC half returns a link credit for +// each through a pulse queue. +// rx rsp, dat, snp: flits from the NoC leave an async queue sink; the +// tile's link credits go back through pulse queues. +// link handshakes from the NoC half cross through SYNC-deep +// synchronisers; those going out pass straight through. +module chi_async_bridge_source #( + parameter int REQ_W = 125, + parameter int RSP_W = 51, + parameter int DAT_W = 385, + parameter int SNP_W = 88, + parameter int DEPTH = 16, + parameter int SYNC = 3, + localparam int B = $clog2(DEPTH) +) ( + input logic clock, + input logic reset, + + // The tile's CHI port (CoupledL2's link layer, registered outside). + input logic tx_req_flitv, + input logic [REQ_W-1:0] tx_req_flit, + output logic tx_req_lcrdv, + input logic tx_rsp_flitv, + input logic [RSP_W-1:0] tx_rsp_flit, + output logic tx_rsp_lcrdv, + input logic tx_dat_flitv, + input logic [DAT_W-1:0] tx_dat_flit, + output logic tx_dat_lcrdv, + output logic rx_rsp_flitv, + output logic [RSP_W-1:0] rx_rsp_flit, + input logic rx_rsp_lcrdv, + output logic rx_dat_flitv, + output logic [DAT_W-1:0] rx_dat_flit, + input logic rx_dat_lcrdv, + output logic rx_snp_flitv, + output logic [SNP_W-1:0] rx_snp_flit, + input logic rx_snp_lcrdv, + input logic [ 2:0] tx_flitpend, // req, rsp, dat + output logic [ 2:0] rx_flitpend, // rsp, dat, snp + input logic tx_linkactivereq, + output logic tx_linkactiveack, + output logic rx_linkactivereq, + input logic rx_linkactiveack, + input logic txsactive, + output logic rxsactive, + input logic syscoreq, + output logic syscoack, + output logic reset_finish, + + // The asynchronous side, to the NoC half. + output logic [DEPTH*REQ_W-1:0] a_tx_req_mem, + output logic [ B:0] a_tx_req_widx, + input logic [ B:0] a_tx_req_ridx, + output logic [DEPTH*RSP_W-1:0] a_tx_rsp_mem, + output logic [ B:0] a_tx_rsp_widx, + input logic [ B:0] a_tx_rsp_ridx, + output logic [DEPTH*DAT_W-1:0] a_tx_dat_mem, + output logic [ B:0] a_tx_dat_widx, + input logic [ B:0] a_tx_dat_ridx, + input logic [DEPTH*RSP_W-1:0] a_rx_rsp_mem, + input logic [ B:0] a_rx_rsp_widx, + output logic [ B:0] a_rx_rsp_ridx, + input logic [DEPTH*DAT_W-1:0] a_rx_dat_mem, + input logic [ B:0] a_rx_dat_widx, + output logic [ B:0] a_rx_dat_ridx, + input logic [DEPTH*SNP_W-1:0] a_rx_snp_mem, + input logic [ B:0] a_rx_snp_widx, + output logic [ B:0] a_rx_snp_ridx, + // Link credits: tx credits arrive, rx credits leave. + input logic [ 2:0][B:0] a_tx_lcrdv_widx, + output logic [ 2:0][B:0] a_tx_lcrdv_ridx, + output logic [ 2:0][B:0] a_rx_lcrdv_widx, + input logic [ 2:0][B:0] a_rx_lcrdv_ridx, + output logic [ 2:0] a_tx_flitpend, + input logic [ 2:0] a_rx_flitpend, + output logic a_tx_linkactivereq, + input logic a_tx_linkactiveack, + input logic a_rx_linkactivereq, + output logic a_rx_linkactiveack, + output logic a_txsactive, + input logic a_rxsactive, + output logic a_syscoreq, + input logic a_syscoack +); + // ---- tx: shadow buffer, then async queue source --------------------- + `define CHI_TX(ch, W) \ + logic ch``_sb_valid, ch``_sb_ready; \ + logic [W-1:0] ch``_sb_bits; \ + shadow_buffer #(.WIDTH(W)) shadowBuffer_``ch``_flit ( \ + .clock(clock), .reset(reset), \ + .enq_valid(tx_``ch``_flitv), .enq_ready(), .enq_bits(tx_``ch``_flit), \ + .deq_valid(ch``_sb_valid), .deq_ready(ch``_sb_ready), \ + .deq_bits(ch``_sb_bits)); \ + async_queue_source #(.WIDTH(W), .DEPTH(DEPTH), .SYNC(SYNC)) \ + asyncQSource_``ch``_flit ( \ + .clock(clock), .reset(reset), \ + .enq_valid(ch``_sb_valid), .enq_ready(ch``_sb_ready), \ + .enq_bits(ch``_sb_bits), .async_mem(a_tx_``ch``_mem), \ + .async_ridx(a_tx_``ch``_ridx), .async_widx(a_tx_``ch``_widx)); + `CHI_TX(req, REQ_W) + `CHI_TX(rsp, RSP_W) + `CHI_TX(dat, DAT_W) + `undef CHI_TX + + // ---- rx: async queue sink, always ready ----------------------------- + `define CHI_RX(ch, W) \ + logic ch``_valid; \ + async_queue_sink #(.WIDTH(W), .DEPTH(DEPTH), .SYNC(SYNC)) \ + asyncQSink_``ch``_flit ( \ + .clock(clock), .reset(reset), \ + .deq_valid(ch``_valid), .deq_ready(1'b1), .deq_bits(rx_``ch``_flit), \ + .async_mem(a_rx_``ch``_mem), .async_ridx(a_rx_``ch``_ridx), \ + .async_widx(a_rx_``ch``_widx)); \ + assign rx_``ch``_flitv = ch``_valid; + `CHI_RX(rsp, RSP_W) + `CHI_RX(dat, DAT_W) + `CHI_RX(snp, SNP_W) + `undef CHI_RX + + // ---- link credits, as pulse queues ---------------------------------- + logic [2:0] tx_lcrdv, rx_lcrdv; + assign rx_lcrdv = {rx_snp_lcrdv, rx_dat_lcrdv, rx_rsp_lcrdv}; + for (genvar c = 0; c < 3; c++) begin : lcrdv + async_queue_sink #(.WIDTH(1), .DEPTH(DEPTH), .SYNC(SYNC), .PULSE(1'b1)) + asyncQBitSink_tx_lcrdv ( + .clock(clock), .reset(reset), + .deq_valid(tx_lcrdv[c]), .deq_ready(1'b1), .deq_bits(), + .async_mem('0), .async_ridx(a_tx_lcrdv_ridx[c]), + .async_widx(a_tx_lcrdv_widx[c])); + async_queue_source #(.WIDTH(1), .DEPTH(DEPTH), .SYNC(SYNC), .PULSE(1'b1)) + asyncQBitSource_rx_lcrdv ( + .clock(clock), .reset(reset), + .enq_valid(rx_lcrdv[c]), .enq_ready(), .enq_bits(1'b0), + .async_mem(), .async_ridx(a_rx_lcrdv_ridx[c]), + .async_widx(a_rx_lcrdv_widx[c])); + end + assign {tx_dat_lcrdv, tx_rsp_lcrdv, tx_req_lcrdv} = tx_lcrdv; + + // ---- link handshakes ------------------------------------------------ + // Out: straight through (AsyncBridge.scala:187-193). + assign a_txsactive = txsactive; + assign a_rx_linkactiveack = rx_linkactiveack; + assign a_tx_linkactivereq = tx_linkactivereq; + assign a_syscoreq = syscoreq; + assign a_tx_flitpend = tx_flitpend; + + // In: synchronised (AsyncBridge.scala:206-213). The NoC may only bring + // the receive link up once this half has been out of reset a while. + logic [6:0] in_sync; + sync_shift_reg #(.WIDTH(7), .SYNC(SYNC)) sync_link ( + .clock(clock), .reset(reset), + .d({a_rx_flitpend, a_syscoack, a_rx_linkactivereq, a_tx_linkactiveack, + a_rxsactive}), + .q(in_sync)); + assign rxsactive = in_sync[0]; + assign tx_linkactiveack = in_sync[1]; + assign rx_linkactivereq = in_sync[2] && reset_finish; + assign syscoack = in_sync[3]; + assign rx_flitpend = in_sync[6:4]; + + // resetFinish: 100 cycles after reset (AsyncBridge.scala:215-221). + localparam int RESET_FINISH_MAX = 100; + logic [7:0] reset_finish_counter; + always_ff @(posedge clock or posedge reset) begin + if (reset) reset_finish_counter <= '0; + else if (reset_finish_counter < 8'(RESET_FINISH_MAX)) + reset_finish_counter <= reset_finish_counter + 1'b1; + end + assign reset_finish = reset_finish_counter >= 8'(RESET_FINISH_MAX); +endmodule diff --git a/flow/designs/src/chi_async_bridge/reset_gen.sv b/flow/designs/src/chi_async_bridge/reset_gen.sv new file mode 100644 index 0000000000..4533a2b2fd --- /dev/null +++ b/flow/designs/src/chi_async_bridge/reset_gen.sv @@ -0,0 +1,33 @@ +// SPDX-License-Identifier: MulanPSL-2.0 +// Copyright (c) 2020-2021 Institute of Computing Technology, Chinese Academy of Sciences +// Copyright (c) 2020-2021 Peng Cheng Laboratory +// Changed from the original: rewritten as readable SystemVerilog from +// XiangShan's Chisel. SOURCE.md names the source and its license. +// +// A reset synchroniser: asserts asynchronously, releases SYNC clocks +// later on this domain's clock. XiangShan's ResetGen +// (utility/ResetGen.scala at eb8e12b), without its DFT muxes. +// +// XSTileWrap gives the bridge's tile half a ResetGen of noc_reset on the +// core clock (XSTileWrap.scala:112) and XSNoCTop gives the NoC half one +// on the NoC clock (XSNoCTop.scala:84), so each half leaves reset on its +// own clock. +module reset_gen #( + parameter int SYNC = 3 +) ( + input logic clock, + input logic reset, + output logic o_reset +); + // A reset synchroniser has at least two flops. + if (SYNC < 2) begin : sync_check + $error("reset_gen: SYNC must be at least 2"); + end + + logic [SYNC-1:0] pipe_reset; + always_ff @(posedge clock or posedge reset) begin + if (reset) pipe_reset <= {SYNC{1'b1}}; + else pipe_reset <= {pipe_reset[SYNC-2:0], 1'b0}; + end + assign o_reset = pipe_reset[SYNC-1]; +endmodule diff --git a/flow/designs/src/chi_async_bridge/shadow_buffer.sv b/flow/designs/src/chi_async_bridge/shadow_buffer.sv new file mode 100644 index 0000000000..c76d9cbed4 --- /dev/null +++ b/flow/designs/src/chi_async_bridge/shadow_buffer.sv @@ -0,0 +1,69 @@ +// SPDX-License-Identifier: MulanPSL-2.0 +// Copyright (c) 2020-2021 Institute of Computing Technology, Chinese Academy of Sciences +// Copyright (c) 2020-2021 Peng Cheng Laboratory +// Changed from the original: rewritten as readable SystemVerilog from +// XiangShan's Chisel. SOURCE.md names the source and its license. +// +// The bridge's shadow buffer: a Chisel Queue(entries = 16, flow = true, +// pipe = false) in front of each outgoing CHI flit channel's async queue +// (ToAsyncBundleWithBuf, xscache/chi/AsyncBridge.scala:67-94 at XSCache +// 300515b). It accepts every flit the link layer sends -- CHI's link +// credits guarantee room -- and, being a flow queue, passes a flit +// through in the same cycle when it is empty. +module shadow_buffer #( + parameter int WIDTH = 8, + parameter int ENTRIES = 16, + localparam int PW = $clog2(ENTRIES) +) ( + input logic clock, + input logic reset, + input logic enq_valid, + output logic enq_ready, + input logic [WIDTH-1:0] enq_bits, + output logic deq_valid, + input logic deq_ready, + output logic [WIDTH-1:0] deq_bits +); + // The pointers wrap by overflowing PW bits, which is only right for a + // power-of-two depth; Chisel's Queue wraps explicitly instead. + if (ENTRIES < 2 || (ENTRIES & (ENTRIES - 1)) != 0) begin : entries_check + $error("shadow_buffer: ENTRIES must be a power of 2 and at least 2"); + end + + // Chisel's Queue keeps its entries in a Mem with a combinational read, + // which firtool emits as one register per entry. + logic [ENTRIES-1:0][WIDTH-1:0] ram; + logic [PW-1:0] enq_ptr, deq_ptr; + logic maybe_full; + + logic ptr_match, empty, full; + assign ptr_match = enq_ptr == deq_ptr; + assign empty = ptr_match && !maybe_full; + assign full = ptr_match && maybe_full; + + assign enq_ready = !full; + assign deq_valid = !empty || enq_valid; + assign deq_bits = empty ? enq_bits : ram[deq_ptr]; + + // In flow, a flit taken while the queue is empty never enters it. + logic do_enq, do_deq; + assign do_enq = enq_valid && enq_ready && !(empty && deq_ready); + assign do_deq = deq_valid && deq_ready && !empty; + + for (genvar i = 0; i < ENTRIES; i++) begin : entry + always_ff @(posedge clock) begin + if (do_enq && enq_ptr == PW'(i)) ram[i] <= enq_bits; + end + end + always_ff @(posedge clock or posedge reset) begin + if (reset) begin + enq_ptr <= '0; + deq_ptr <= '0; + maybe_full <= 1'b0; + end else begin + if (do_enq) enq_ptr <= enq_ptr + 1'b1; + if (do_deq) deq_ptr <= deq_ptr + 1'b1; + if (do_enq != do_deq) maybe_full <= do_enq; + end + end +endmodule diff --git a/flow/designs/src/chi_async_bridge/sync_shift_reg.sv b/flow/designs/src/chi_async_bridge/sync_shift_reg.sv new file mode 100644 index 0000000000..b544fbdb26 --- /dev/null +++ b/flow/designs/src/chi_async_bridge/sync_shift_reg.sv @@ -0,0 +1,39 @@ +// SPDX-License-Identifier: Apache-2.0 +// Copyright 2016-2017 SiFive, Inc. +// Changed from the original: rewritten as readable SystemVerilog from +// rocket-chip's Chisel. SOURCE.md names the source and its license. +// +// A synchroniser: WIDTH independent chains of SYNC flops, each bit +// clocked into the destination domain. Rocket-chip's +// AsyncResetSynchronizerShiftReg (util/SynchronizerReg.scala at a2df1a4, +// the commit XiangShan pins), which wraps its chains in their own module +// "to allow for backend flows to replace or constrain them properly when +// used for CDC synchronization, rather than buffering". constraint.sdc +// does exactly that, by these names. +// +// The chain is rocket-chip's: sync[SYNC-1] takes the asynchronous input, +// sync[0] is the output, every flop is asynchronously reset to INIT. +module sync_shift_reg #( + parameter int WIDTH = 1, + parameter int SYNC = 3, + parameter bit INIT = 1'b0 +) ( + input logic clock, + input logic reset, + input logic [WIDTH-1:0] d, + output logic [WIDTH-1:0] q +); + // A synchroniser has at least two flops (util/SynchronizerReg.scala:82). + if (SYNC < 2) begin : sync_check + $error("sync_shift_reg: SYNC must be at least 2"); + end + + for (genvar i = 0; i < WIDTH; i++) begin : bit_ + logic [SYNC-1:0] sync; + always_ff @(posedge clock or posedge reset) begin + if (reset) sync <= {SYNC{INIT}}; + else sync <= {d[i], sync[SYNC-1:1]}; + end + assign q[i] = sync[0]; + end +endmodule diff --git a/flow/platforms/asap7/liberty_suppressions.tcl b/flow/platforms/asap7/liberty_suppressions.tcl index c1526671c0..06c8902733 100644 --- a/flow/platforms/asap7/liberty_suppressions.tcl +++ b/flow/platforms/asap7/liberty_suppressions.tcl @@ -1,5 +1,23 @@ -# To remove [WARNING STA-1212] from the logs for ASAP7. -# /OpenROAD-flow-scripts/flow/platforms/asap7/lib/asap7sc7p5t_SIMPLE_RVT_TT_nldm_211120.lib.gz -# line 13178, timing group from output port. -# Added following suppress_message +# Suppress [WARNING STA-1212] "timing group from output port." for ASAP7. +# (This warning was numbered STA-0164 before OpenSTA renumbered its messages.) +# +# The asap7sc7p5t_SIMPLE_* libraries (all VT and corner variants) contain +# intentional output-to-output timing arcs from CON to SN in FAx1 and HAxp5. +# These cells use a mirror-adder topology: the inverted carry node (CON) is +# also an internal input to the sum stage, e.g. for HAxp5 +# SN = !((A + B) * CON). The CON->SN arcs model how CON's load delays SN. +# They are correct and must not be removed from the Liberty files. +# Removing them makes SN timing optimistic, because SN delay would no longer +# depend on CON's load. +# +# OpenSTA builds and uses these arcs whether or not the warning is +# suppressed, so this suppression only affects log output. +# +# Note that this applies to every Liberty file read in an ASAP7 flow, +# including user-added ones (e.g. ADDITIONAL_LIBS). Elsewhere, STA-1212 +# usually means a real library bug, such as a related_pin typo or wrong pin +# direction. +# +# See https://github.com/The-OpenROAD-Project/OpenROAD/discussions/3291 and +# https://github.com/The-OpenROAD-Project/OpenROAD-flow-scripts/pull/1056 suppress_message STA 1212 diff --git a/flow/scripts/final_outputs.tcl b/flow/scripts/final_outputs.tcl index 2cb34a0039..520b9d0374 100644 --- a/flow/scripts/final_outputs.tcl +++ b/flow/scripts/final_outputs.tcl @@ -35,6 +35,7 @@ if { # Read Spef for OpenSTA read_spef $::env(RESULTS_DIR)/6_final.spef + set final_parasitics rcx # Static IR drop analysis if { [env_var_exists_and_non_empty PWR_NETS_VOLTAGES] } { @@ -59,7 +60,9 @@ if { puts "OpenRCX is not enabled for this platform." puts "Falling back to global route-based estimates." log_cmd estimate_parasitics -global_routing + set final_parasitics global_routing } +write_endpoint_slack 6_final $final_parasitics report_cell_usage diff --git a/flow/scripts/final_report.tcl b/flow/scripts/final_report.tcl index 279dfdd891..2916f2f473 100644 --- a/flow/scripts/final_report.tcl +++ b/flow/scripts/final_report.tcl @@ -2,6 +2,7 @@ # (scripts/flow.tcl) can source the parts and perform the write itself # at the same point. source $::env(SCRIPTS_DIR)/final_connect.tcl -orfs_write_db $::env(RESULTS_DIR)/6_final.odb +# final_outputs.tcl writes the endpoint slack after parasitic extraction +orfs_write_db $::env(RESULTS_DIR)/6_final.odb 0 orfs_write_sdc $::env(RESULTS_DIR)/6_final.sdc source $::env(SCRIPTS_DIR)/final_outputs.tcl diff --git a/flow/scripts/formal_check.tcl b/flow/scripts/formal_check.tcl index 930b59b00d..10c3187c20 100644 --- a/flow/scripts/formal_check.tcl +++ b/flow/scripts/formal_check.tcl @@ -90,11 +90,27 @@ proc formal_check_label { step } { return "Global output" } +# Run kepler-formal through run_command.py, as the flow runs yosys and +# openroad, so its stdout and elapsed time/peak memory land in +# $LOG_DIR/${step}_${kind}.log. kepler-formal still writes its detailed +# log to the ${step}_${kind}_check.log named in its config. +proc run_kepler_formal { step kind } { + if { [env_var_exists_and_non_empty RUN_CMD] } { + set run_cmd $::env(RUN_CMD) + } else { + set run_cmd [list $::env(PYTHON_EXE) $::env(SCRIPTS_DIR)/run_command.py] + } + # run_command.py reports the elapsed time on stderr, which exec would + # otherwise treat as an error. + exec {*}$run_cmd --log $::env(LOG_DIR)/${step}_${kind}.log -- \ + {*}$::env(KEPLER_FORMAL_EXE) --config $::env(OBJECTS_DIR)/${step}_${kind}_test.yml \ + 2>@ stderr +} + proc run_lec_test { step file1 file2 } { check_kepler_formal write_lec_script $step $file1 $file2 - # tclint-disable-next-line command-args - eval exec $::env(KEPLER_FORMAL_EXE) --config $::env(OBJECTS_DIR)/${step}_lec_test.yml + run_kepler_formal $step lec try { set count [exec grep -c "Found difference" $::env(LOG_DIR)/${step}_lec_check.log] } trap CHILDSTATUS {results options} { @@ -112,8 +128,7 @@ proc run_lec_test { step file1 file2 } { proc run_sec_test { step file1 file2 } { check_kepler_formal write_sec_script $step $file1 $file2 - # tclint-disable-next-line command-args - eval exec $::env(KEPLER_FORMAL_EXE) --config $::env(OBJECTS_DIR)/${step}_sec_test.yml + run_kepler_formal $step sec try { set count [exec grep -c "SEC found a counterexample" $::env(LOG_DIR)/${step}_sec_check.log] } trap CHILDSTATUS {results options} { diff --git a/flow/scripts/load.tcl b/flow/scripts/load.tcl index 1b3a6c4632..7d70b67769 100644 --- a/flow/scripts/load.tcl +++ b/flow/scripts/load.tcl @@ -51,6 +51,11 @@ proc load_design { design_file sdc_file } { log_cmd source $::env(PLATFORM_DIR)/setRC.tcl } + if { [env_var_exists_and_non_empty WIRE_LOAD_MODEL] } { + # OpenSTA applies a wire-load model only to nets without parasitics. + log_cmd set_wire_load_model -name $::env(WIRE_LOAD_MODEL) + } + if { [env_var_equals LIB_MODEL CCS] } { puts "Using CCS delay calculation" log_cmd set_delay_calculator prima diff --git a/flow/scripts/memories/detect.py b/flow/scripts/memories/detect.py index 0e486d9b39..d2b7364529 100644 --- a/flow/scripts/memories/detect.py +++ b/flow/scripts/memories/detect.py @@ -10,6 +10,7 @@ from __future__ import annotations import json +import re from pathlib import Path import schema @@ -29,6 +30,88 @@ def parse_param_int(val) -> int: return int(val) +# firtool names a memory module's ports by port and function -- R0_addr, +# W1_mask, RW0_wmode -- and this is the one convention read here. A module +# whose every port fits it is a memory at the module boundary, and three +# things follow that the yosys view alone gets wrong: the pins the macro +# must expose are the module's own ports, not names synthesized from port +# indices; a read-write port is one port, where yosys reports a read plus +# a write; and the write mask is as wide as the port says, not the per-bit +# enable yosys expands it into. +_FIRTOOL_PORT = re.compile( + r"^(RW|R|W)(\d+)_(addr|en|clk|data|rdata|wdata|wmode|wmask|mask)$" +) +_FIRTOOL_FUNCTION = { + "addr": "addr", + "en": "en", + "clk": "clk", + "wmode": "wmode", + "wmask": "mask", + "mask": "mask", + "wdata": "data_in", + "rdata": "data_out", +} + + +def firtool_pins(mod_info: dict): + """Pins of a module whose ports all follow firtool's memory convention. + + Returns (pins, read_ports, write_ports, rw_ports, mask_lanes), or None + when the module has no ports or any port does not fit the convention. + """ + ports = mod_info.get("ports", {}) + if not ports: + return None + pins: list[schema.Pin] = [] + kinds: dict[str, str] = {} + mask_lanes = 0 + for name, info in ports.items(): + clean = name[1:] if name.startswith("\\") else name + m = _FIRTOOL_PORT.match(clean) + if not m: + return None + kind, index, field = m.groups() + port_id = kind + index + kinds[port_id] = kind + direction = info.get("direction", "input") + if field == "data": + function = "data_out" if direction == "output" else "data_in" + else: + function = _FIRTOOL_FUNCTION[field] + width = len(info.get("bits", [])) or 1 + if function == "mask": + mask_lanes = max(mask_lanes, width) + pins.append( + schema.Pin( + name=clean, + direction=direction, + width=width, + port_id=port_id, + function=function, + ) + ) + found = list(kinds.values()) + return pins, found.count("R"), found.count("W"), found.count("RW"), mask_lanes + + +def _clock_enable_bits(val, ports: int) -> str: + """RD_CLK_ENABLE as a string of `ports` bits, most significant first. + + yosys writes it as a binary string of exactly RD_PORTS digits. Anything + else is refused rather than padded, truncated or read as decimal: a + miscounted bit is a combinational read let through as a macro. + """ + if isinstance(val, int): + if not 0 <= val < 1 << ports: + raise ValueError(f"RD_CLK_ENABLE {val} does not fit {ports} read ports") + return format(val, f"0{ports}b") + if not isinstance(val, str) or len(val) != ports or set(val) - {"0", "1"}: + raise ValueError( + f"RD_CLK_ENABLE {val!r} is not {ports} binary digits, one per read port" + ) + return val + + def scan_yosys_json(data: dict | str | Path) -> list[schema.Memory]: """Extract memory modules from a Yosys netlist JSON output ($mem_v2 cells).""" if isinstance(data, (str, Path)): @@ -40,6 +123,9 @@ def scan_yosys_json(data: dict | str | Path) -> list[schema.Memory]: for mod_name, mod_info in modules.items(): clean_mod_name = mod_name[1:] if mod_name.startswith("\\") else mod_name cells = mod_info.get("cells", {}) + mem_cells = [ + n for n, c in cells.items() if c.get("type", "") in ("$mem_v2", "$mem") + ] for cell_name, cell_info in cells.items(): cell_type = cell_info.get("type", "") if cell_type not in ("$mem_v2", "$mem"): @@ -71,6 +157,12 @@ def scan_yosys_json(data: dict | str | Path) -> list[schema.Memory]: mask_lanes = 0 if wr_ports > 0 and len(wr_en_bits) > wr_ports: mask_lanes = len(wr_en_bits) // wr_ports + # A read port without a clock is a combinational read. An + # absent parameter is yosys saying every read is clocked. + rd_clk_enable = params.get("RD_CLK_ENABLE") + comb_read_ports = 0 + if rd_ports and rd_clk_enable is not None: + comb_read_ports = _clock_enable_bits(rd_clk_enable, rd_ports).count("0") pins: list[schema.Pin] = [] @@ -154,8 +246,31 @@ def scan_yosys_json(data: dict | str | Path) -> list[schema.Memory]: ) ) + # The module's own ports beat the synthesized pin list when + # they follow firtool's convention: those are the names the + # generated liberty view has to carry for the blackboxed + # module to link at all. + rw_ports = 0 + port_convention = "" + convention = firtool_pins(mod_info) + if convention is not None: + pins, rd_ports, wr_ports, rw_ports, mask_lanes = convention + port_convention = "firtool" + # A module that holds nothing but one memory *is* that memory + # and takes the module's name -- which is the name the flow + # blackboxes. So does a firtool memory module, whatever glue + # surrounds its array: its ports say what it is, and every one + # calls its array `Memory`, so naming by cell would fold them + # all into one entry. Any other memory is named per cell, + # qualified so the names stay distinct across modules: an + # array inside a module that also does something else is the + # design asking for flip-flops, and idiomatic.judge refuses a + # memory that is not named for its module. clean_cell = cell_name[1:] if cell_name.startswith("\\") else cell_name - mem_name = clean_mod_name if len(cells) == 1 else clean_cell + if len(mem_cells) == 1 and (port_convention or len(cells) == 1): + mem_name = clean_mod_name + else: + mem_name = f"{clean_mod_name}.{clean_cell}" mem = schema.Memory( name=mem_name, @@ -164,8 +279,10 @@ def scan_yosys_json(data: dict | str | Path) -> list[schema.Memory]: addr_w=addr_w, read_ports=rd_ports, write_ports=wr_ports, - rw_ports=0, + rw_ports=rw_ports, mask_lanes=mask_lanes, + comb_read_ports=comb_read_ports, + port_convention=port_convention, pins=pins, behavioral_model={"module": clean_mod_name}, reason=f"Yosys inferred $mem_v2 ({'single-clock' if single_clock else 'multi-clock'})", diff --git a/flow/scripts/memories/detect_test.py b/flow/scripts/memories/detect_test.py index d378d11de1..9965ea9f4f 100644 --- a/flow/scripts/memories/detect_test.py +++ b/flow/scripts/memories/detect_test.py @@ -99,5 +99,138 @@ def test_scan_yosys_json_empty_or_non_memory(self): self.assertEqual(detect.scan_yosys_json(yosys_json), []) +def _mem_cell(size, width, rd_clk_enable="1", wr_en_bits=None): + return { + "type": "$mem_v2", + "parameters": { + "SIZE": size, + "WIDTH": width, + "RD_PORTS": 1, + "WR_PORTS": 1, + "RD_CLK_ENABLE": rd_clk_enable, + }, + "connections": { + "RD_CLK": [2], + "WR_CLK": [2], + "RD_EN": [3], + "WR_EN": wr_en_bits if wr_en_bits is not None else [4], + "RD_ADDR": list(range(10, 16)), + "WR_ADDR": list(range(10, 16)), + "RD_DATA": list(range(100, 100 + width)), + "WR_DATA": list(range(300, 300 + width)), + }, + } + + +def _firtool_rw_module(size=64, width=114, lanes=2, rd_clk_enable="1"): + """A module shaped like firtool's array_x: one RW port.""" + addr_w = (size - 1).bit_length() + ports = { + "RW0_addr": {"direction": "input", "bits": list(range(1, 1 + addr_w))}, + "RW0_en": {"direction": "input", "bits": [20]}, + "RW0_clk": {"direction": "input", "bits": [2]}, + "RW0_wmode": {"direction": "input", "bits": [21]}, + "RW0_wdata": {"direction": "input", "bits": list(range(300, 300 + width))}, + "RW0_rdata": {"direction": "output", "bits": list(range(500, 500 + width))}, + "RW0_wmask": {"direction": "input", "bits": list(range(30, 30 + lanes))}, + } + cells = { + "\\Memory": _mem_cell( + size, width, rd_clk_enable, list(range(700, 700 + width)) + ), + "$and$1": {"type": "$and", "parameters": {}, "connections": {}}, + "$mux$2": {"type": "$mux", "parameters": {}, "connections": {}}, + } + return {"ports": ports, "cells": cells} + + +class FirtoolConventionTest(unittest.TestCase): + def test_one_memory_per_module_is_named_after_the_module(self): + # firtool calls every array `Memory`; two modules with glue around + # theirs must come out as two entries, named for the modules. + yosys_json = { + "modules": { + "\\array_64x114": _firtool_rw_module(), + "\\array_256x66": _firtool_rw_module(256, 66, 1), + } + } + mems = detect.scan_yosys_json(yosys_json) + self.assertEqual(sorted(m.name for m in mems), ["array_256x66", "array_64x114"]) + + def test_rw_port_pins_are_the_module_ports(self): + (m,) = detect.scan_yosys_json( + {"modules": {"\\array_64x114": _firtool_rw_module()}} + ) + self.assertEqual(m.port_convention, "firtool") + self.assertEqual((m.read_ports, m.write_ports, m.rw_ports), (0, 0, 1)) + self.assertEqual(m.mask_lanes, 2) + self.assertEqual(m.comb_read_ports, 0) + by_name = {p.name: p for p in m.pins} + self.assertEqual( + sorted(by_name), + [ + "RW0_addr", + "RW0_clk", + "RW0_en", + "RW0_rdata", + "RW0_wdata", + "RW0_wmask", + "RW0_wmode", + ], + ) + self.assertEqual(by_name["RW0_rdata"].function, "data_out") + self.assertEqual(by_name["RW0_rdata"].direction, "output") + self.assertEqual(by_name["RW0_wdata"].function, "data_in") + self.assertEqual(by_name["RW0_wmask"].function, "mask") + self.assertEqual(by_name["RW0_wmask"].width, 2) + self.assertEqual(by_name["RW0_wmode"].function, "wmode") + self.assertTrue(all(p.port_id == "RW0" for p in m.pins)) + + def test_combinational_read_is_counted(self): + (m,) = detect.scan_yosys_json( + {"modules": {"\\bank": _firtool_rw_module(rd_clk_enable="0")}} + ) + self.assertEqual(m.comb_read_ports, 1) + + def test_clock_enable_as_integer(self): + self.assertEqual(detect._clock_enable_bits(1, 1), "1") + self.assertEqual(detect._clock_enable_bits(2, 2), "10") + self.assertEqual(detect._clock_enable_bits("0", 1), "0") + + def test_clock_enable_that_is_not_one_bit_per_port_is_refused(self): + # yosys writes exactly RD_PORTS binary digits; padding a short value + # or reading "2" as decimal would miscount combinational reads. + for val, ports in (("0", 2), ("011", 2), ("2", 2), (4, 2), (-1, 1)): + with self.assertRaises(ValueError, msg=(val, ports)): + detect._clock_enable_bits(val, ports) + + def test_ports_outside_the_convention_keep_synthesized_pins(self): + module = _firtool_rw_module() + module["ports"]["ce_in"] = {"direction": "input", "bits": [40]} + (m,) = detect.scan_yosys_json({"modules": {"\\other": module}}) + self.assertEqual(m.port_convention, "") + self.assertEqual((m.read_ports, m.write_ports, m.rw_ports), (1, 1, 0)) + self.assertIn("R0_addr", [p.name for p in m.pins]) + + def test_second_memory_in_a_module_gets_a_qualified_name(self): + module = _firtool_rw_module() + module["cells"]["\\Other"] = _mem_cell(64, 8) + names = sorted( + m.name for m in detect.scan_yosys_json({"modules": {"\\m": module}}) + ) + self.assertEqual(names, ["m.Memory", "m.Other"]) + + def test_inline_array_with_other_logic_is_named_per_cell(self): + # One memory among other logic, ports not firtool's: the module is + # not a memory, so the entry must not take its name. + mod = _firtool_rw_module() + mod["ports"] = { + "clk": {"direction": "input", "bits": [2]}, + "parity": {"direction": "output", "bits": [3]}, + } + mems = detect.scan_yosys_json({"modules": {"\\am_regs": mod}}) + self.assertEqual([m.name for m in mems], ["am_regs.Memory"]) + + if __name__ == "__main__": unittest.main() diff --git a/flow/scripts/memories/extract_memories.tcl b/flow/scripts/memories/extract_memories.tcl index 18e5c23717..478f0e2426 100644 --- a/flow/scripts/memories/extract_memories.tcl +++ b/flow/scripts/memories/extract_memories.tcl @@ -23,11 +23,42 @@ hierarchy -top $::env(DESIGN_NAME) # bare `proc`: yosys -import cannot shadow Tcl's proc keyword, so the # bare word would define a procedure instead of running the pass. yosys proc -memory -nomap -# Write netlist JSON containing inferred $mem_v2 primitives +# The memory passes, on the modules that hold memory cells only. Every +# pass in `memory -nomap` walks every selected module, and memory_dff +# builds its per-bit driver and consumer index (ModWalker) for a module +# before it asks whether the module has a memory at all; opt_mem_priority +# and opt_mem_feedback scan every module's cells the same way. On a design +# whose memories sit in small generated modules and whose logic sits in +# large ones -- a firtool core keeps every memory in its own ram_* module +# -- that index over the memory-less modules is nearly the whole cost of +# this step. Scoping the passes to the modules with memory cells changes +# nothing in the result: a pass finds nothing to do in a module without +# them. memory_bmux2rom runs first and unscoped, since it is what turns a +# module's constant muxes into a memory. t:$mem* takes every memory cell +# type: read_verilog leaves reads as $memrd until memory_collect. `%m` +# then selects every module that holds one, whole, without going through +# its name: an escaped module or memory name may carry a slash, a `$` or a +# glob character, and none of those survives being cut out of a +# `select -list` line and handed back to `select`. +memory_bmux2rom +set n_mem_cells [lindex [tee -q -s result.string select -count t:\$mem*] 0] set out_json "$::env(RESULTS_DIR)/memories_inferred.json" file mkdir [file dirname $out_json] -write_json $out_json +if { $n_mem_cells > 0 } { + yosys select t:\$mem* %m + set mem_modules [tee -q -s result.string select -list-mod %] + set n_mem_modules [llength [split [string trim $mem_modules] "\n"]] + log "extract_memories: $n_mem_modules modules hold $n_mem_cells memory cells" + memory -nomap + # The JSON is read by gen_memories.py's detector, which looks at the + # $mem_v2 cells of each module and nothing across modules, so the + # memory modules are all it needs; the rest of the design is most of + # the bytes. + write_json -selected $out_json + select -clear +} else { + write_json $out_json +} exit diff --git a/flow/scripts/memories/idiomatic.py b/flow/scripts/memories/idiomatic.py index e32221eaf4..7109892a7b 100644 --- a/flow/scripts/memories/idiomatic.py +++ b/flow/scripts/memories/idiomatic.py @@ -23,8 +23,49 @@ MAX_TOTAL_PORTS = 4 +def enclosing_module(mem: schema.Memory) -> str | None: + """The module whose body simulates this memory, demangled. + + yosys writes a parameterized module as "$paramod$\\" or + "$paramod\\\\="; the module is the component after + the first backslash in both forms. + """ + model = mem.behavioral_model or {} + module = model.get("module") + if not module: + return None + if module.startswith("$paramod"): + parts = module.split("\\") + return parts[1] if len(parts) > 1 else None + return module.lstrip("\\") + + def judge(mem: schema.Memory) -> tuple[bool, str]: """Return (idiomatic, reason).""" + # Only a memory that *is* a module can be converted: conversion works + # by blackboxing the module so the generated liberty view replaces its + # behavioral body. A memory inferred inside a larger module has no + # module to blackbox, so converting it would generate a macro nothing + # instantiates and report a conversion that did not happen. + enclosing = enclosing_module(mem) + if enclosing is not None and enclosing != mem.name: + return ( + False, + f"inferred inside module {enclosing} rather than being one; " + "an inline array is the design asking for flip-flops. " + "Instantiate the memory as its own module to convert it", + ) + # An SRAM macro reads on a clock edge. A memory the design reads + # combinationally is a register array in its own words -- a lookup + # table, a bypass structure -- and converting it would move every + # read a cycle later. Flops are the only faithful implementation. + if mem.comb_read_ports: + return ( + False, + f"{mem.comb_read_ports} combinational read port(s): an SRAM macro " + "reads on a clock edge; a register array is what the design " + "asked for", + ) if mem.bits < 1: return False, "no data pins" if mem.rows < MIN_ROWS: @@ -41,6 +82,21 @@ def judge(mem: schema.Memory) -> tuple[bool, str]: f"{mem.total_ports()} ports exceeds single-macro " f"limit {MAX_TOTAL_PORTS}", ) + # What the FakeRAM asap7 backend emits today is a single read-write + # port. When the pins are the module's own, the port configuration is + # known exactly and anything else would generate a macro whose pins do + # not match the module it replaces. + if mem.port_convention == "firtool" and ( + mem.rw_ports, + mem.read_ports, + mem.write_ports, + ) != (1, 0, 0): + return ( + False, + f"R={mem.read_ports} W={mem.write_ports} RW={mem.rw_ports}: the " + "asap7 backend emits a single read-write port; a separate-port " + "macro is not emitted yet", + ) return True, "meets ASAP7 macro floors" diff --git a/flow/scripts/memories/idiomatic_test.py b/flow/scripts/memories/idiomatic_test.py index d26fbfc040..489754b03d 100644 --- a/flow/scripts/memories/idiomatic_test.py +++ b/flow/scripts/memories/idiomatic_test.py @@ -21,6 +21,22 @@ def mem(rows, bits, read_ports=1, write_ports=1, rw_ports=0): class IdiomaticTest(unittest.TestCase): + def test_rejects_memory_inside_a_larger_module(self): + # An inline array has no module of its own to blackbox: converting + # it would generate a macro nothing instantiates. + m = mem(64, 32) + m.behavioral_model = {"module": "picorv32"} + ok, reason = idiomatic.judge(m) + self.assertFalse(ok) + self.assertIn("inside module picorv32", reason) + + def test_accepts_memory_that_is_its_module(self): + m = mem(64, 32) + m.name = "ram_64x32" + m.behavioral_model = {"module": "$paramod$abc123\\ram_64x32"} + ok, reason = idiomatic.judge(m) + self.assertTrue(ok, reason) + def test_accepts_macro_sized_memory(self): ok, reason = idiomatic.judge(mem(64, 32)) self.assertTrue(ok, reason) @@ -49,5 +65,31 @@ def test_apply_sets_fields(self): self.assertTrue(memories[1].reason) +class BackendShapeTest(unittest.TestCase): + def test_rejects_combinational_read(self): + m = mem(704, 776) + m.comb_read_ports = 1 + ok, reason = idiomatic.judge(m) + self.assertFalse(ok) + self.assertIn("combinational read", reason) + + def test_accepts_single_rw_port_under_firtool_convention(self): + m = mem(64, 114, read_ports=0, write_ports=0, rw_ports=1) + m.port_convention = "firtool" + ok, reason = idiomatic.judge(m) + self.assertTrue(ok, reason) + + def test_rejects_separate_ports_under_firtool_convention(self): + m = mem(64, 114, read_ports=1, write_ports=1) + m.port_convention = "firtool" + ok, reason = idiomatic.judge(m) + self.assertFalse(ok) + self.assertIn("single read-write port", reason) + + def test_synthesized_pins_keep_the_old_acceptance(self): + ok, reason = idiomatic.judge(mem(64, 32)) + self.assertTrue(ok, reason) + + if __name__ == "__main__": unittest.main() diff --git a/flow/scripts/memories/schema.py b/flow/scripts/memories/schema.py index 060cf277c8..754ae8373c 100644 --- a/flow/scripts/memories/schema.py +++ b/flow/scripts/memories/schema.py @@ -49,6 +49,15 @@ class Memory: # Total width of the per-port write mask, 0 if unmasked. Subword-split # mask pins (`W0_mask_0..3`) contribute one lane each. mask_lanes: int = 0 + # Read ports yosys inferred without a clock ($mem_v2 RD_CLK_ENABLE=0). + # An SRAM macro reads on a clock edge, so one of these rules the memory + # out of conversion; see idiomatic.py. + comb_read_ports: int = 0 + # Where the pin list came from. "firtool" when every port of the + # behavioral module follows firtool's _ naming and + # the pins are the module's own ports; "" when they were synthesized + # from the yosys port counts. + port_convention: str = "" pins: list[Pin] = field(default_factory=list) # The module whose RTL body simulates this memory: {"file", "module"}. behavioral_model: dict | None = None @@ -106,9 +115,12 @@ def memory_from_dict(d: dict) -> Memory: "write_ports", "rw_ports", "mask_lanes", + "comb_read_ports", ): if key in d: setattr(mem, key, int(d[key])) + if "port_convention" in d: + mem.port_convention = str(d["port_convention"]) if "pins" in d: mem.pins = [_pin_from_dict(p) for p in d["pins"]] if "behavioral_model" in d: @@ -170,10 +182,13 @@ def merge(detected: list[Memory], overrides: list[Memory]) -> list[Memory]: "write_ports", "rw_ports", "mask_lanes", + "comb_read_ports", ): value = getattr(o, key) if value: setattr(base, key, value) + if o.port_convention: + base.port_convention = o.port_convention if o.behavioral_model is not None: base.behavioral_model = o.behavioral_model if o.idiomatic: diff --git a/flow/scripts/util.tcl b/flow/scripts/util.tcl index 912762199a..49ab5fd80f 100644 --- a/flow/scripts/util.tcl +++ b/flow/scripts/util.tcl @@ -302,7 +302,101 @@ proc find_physical_only_masters { } { return $physical_only_masters } -proc orfs_write_db { output_file } { +proc endpoint_slack_file { step } { + return $::env(REPORTS_DIR)/${step}_endpoint_slack.json +} + +# Write the setup and hold slack of every endpoint at the end of a flow +# step so they can be compared across steps with +# flow/util/endpointSlack.py. Parasitics are estimated the same way as +# open.tcl so that every step is timed consistently, unless the caller +# has already loaded parasitics (e.g. extracted ones) and passes their +# name as parasitics. +proc write_endpoint_slack { step { parasitics "" } } { + if { !$::env(REPORT_ENDPOINT_SLACK) || [string match "*-failed" $step] } { + return + } + set filename [endpoint_slack_file $step] + puts "Writing endpoint slack to $filename" + + if { $parasitics == "" } { + set design_stage [lindex [split $step _] 0] + set parasitics none + if { $design_stage >= 5 } { + if { [grt::have_routes] } { + set parasitics global_routing + } + } elseif { $design_stage >= 3 } { + set parasitics placement + } + if { $parasitics != "none" } { + estimate_parasitics -$parasitics + } + } + # Update timing before sta::endpoints: the endpoint set is cached the + # first time it is requested and misses gated clock enable checks if the + # clock network has not been found yet. + sta::find_timing + + set fileId [open $filename w] + puts $fileId "{" + puts $fileId "\"design\": \"$::env(DESIGN_NAME)\"," + puts $fileId "\"step\": \"$step\"," + puts $fileId "\"parasitics\": \"$parasitics\"," + # Seconds per reported time unit + puts $fileId "\"time_unit\": [sta::time_ui_sta 1]," + # endpoint: [setup slack, hold slack], null if unconstrained + puts $fileId "\"endpoints\": {" + set sep "" + foreach pin [sta::endpoints] { + set name [string map {\\ \\\\ \" \\\"} [get_full_name $pin]] + set slacks {} + foreach min_max {max min} { + set slack [get_property $pin slack_$min_max] + if { $slack eq "INF" || $slack eq "-INF" } { + set slack null + } + lappend slacks $slack + } + puts -nonewline $fileId "$sep\"$name\": \[[join $slacks ,]\]" + set sep ",\n" + } + puts $fileId "\n}" + puts $fileId "}" + close $fileId +} + +# A step that copies its input .odb leaves the design unchanged, so +# re-time it if it is loaded, otherwise copy the input step's snapshot. +proc copy_endpoint_slack { input_file output_file } { + if { !$::env(REPORT_ENDPOINT_SLACK) } { + return + } + set step [file rootname [file tail $output_file]] + set chip [[ord::get_db] getChip] + if { $chip != "NULL" && [$chip getBlock] != "NULL" } { + write_endpoint_slack $step + return + } + set input [endpoint_slack_file [file rootname [file tail $input_file]]] + if { ![file exists $input] } { + return + } + set fileId [open $input r] + set json [read $fileId] + close $fileId + regsub {"step": "[^"]*"} $json "\"step\": \"$step\"" json + set fileId [open [endpoint_slack_file $step] w] + puts -nonewline $fileId $json + close $fileId +} + +# endpoint_slack 0 is for callers that write the endpoint slack snapshot +# themselves, e.g. 6_final after parasitic extraction. +proc orfs_write_db { output_file { endpoint_slack 1 } } { + if { $endpoint_slack } { + write_endpoint_slack [file rootname [file tail $output_file]] + } if { !$::env(WRITE_ODB_AND_SDC_EACH_STAGE) } { return } @@ -326,6 +420,7 @@ proc orfs_write_sdc { output_file } { # mtime with second resolution, which breaks make's timestamp-based # up-to-date checks for fast builds. proc orfs_copy_db { input_file output_file } { + copy_endpoint_slack $input_file $output_file if { !$::env(WRITE_ODB_AND_SDC_EACH_STAGE) } { return } diff --git a/flow/scripts/variables.json b/flow/scripts/variables.json index 36a165116c..61a7b8b8e7 100644 --- a/flow/scripts/variables.json +++ b/flow/scripts/variables.json @@ -954,6 +954,19 @@ "final" ] }, + "REPORT_ENDPOINT_SLACK": { + "default": 0, + "description": "If set to 1, write the setup and hold slack of every timing endpoint at the end of every flow step (e.g. 3_3_place_gp) to $REPORTS_DIR/_endpoint_slack.json. These snapshots can be compared across steps with flow/util/endpointSlack.py. See docs/contrib/EndpointSlackTracking.md.\n", + "stages": [ + "synth", + "floorplan", + "place", + "cts", + "grt", + "route", + "final" + ] + }, "ROUTING_LAYER_ADJUSTMENT": { "default": 0.5, "description": "Adjusts routing layer capacities to manage congestion and improve detailed routing. High values ease detailed routing but risk excessive detours and long global routing times, while low values reduce global routing failure but can complicate detailed routing. The global routing running time normally reduces dramatically (entirely design specific, but going from hours to minutes has been observed) when the value is low (such as 0.10). Sometimes, global routing will succeed with lower values and fail with higher values. Exploring results with different values can help shed light on the problem. Start with a too low value, such as 0.10, and bisect to value that works by doing multiple global routing runs. As a last resort, `make global_route_issue` and using the tools/OpenROAD/etc/whittle.py can be useful to debug global routing errors. If there is something specific that is impossible to route, such as a clock line over a macro, global routing will terminate with DRC errors routes that could have been routed were it not for the specific impossible routes. whittle.py should weed out the possible routes and leave a minimal failing case that pinpoints the problem.\n", diff --git a/flow/scripts/variables.yaml b/flow/scripts/variables.yaml index 644427f34c..2052bd468d 100644 --- a/flow/scripts/variables.yaml +++ b/flow/scripts/variables.yaml @@ -110,6 +110,22 @@ REPORT_CLOCK_SKEW: - route - final default: 1 +REPORT_ENDPOINT_SLACK: + description: > + If set to 1, write the setup and hold slack of every timing endpoint at + the end of every flow step (e.g. 3_3_place_gp) to + $REPORTS_DIR/_endpoint_slack.json. These snapshots can be compared + across steps with flow/util/endpointSlack.py. See + docs/contrib/EndpointSlackTracking.md. + stages: + - synth + - floorplan + - place + - cts + - grt + - route + - final + default: 0 SKIP_REPORT_METRICS: description: > If set to 1, then metrics, report_metrics does nothing. Useful to speed up diff --git a/flow/test/test_endpointSlack.py b/flow/test/test_endpointSlack.py new file mode 100644 index 0000000000..6ed498d590 --- /dev/null +++ b/flow/test/test_endpointSlack.py @@ -0,0 +1,191 @@ +#!/usr/bin/env python3 + +import json +import os +import sys +import tempfile +import unittest +from io import StringIO +from unittest.mock import patch + +sys.path.append(os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "util")) + +import endpointSlack + + +def snapshot(step, endpoints): + return { + "design": "test", + "step": step, + "parasitics": "placement", + "time_unit": 1e-12, + "endpoints": endpoints, + } + + +class TestEndpointSlack(unittest.TestCase): + def setUp(self): + self.tmp_dir = tempfile.TemporaryDirectory() + # slacks in ps: [setup, hold] + self.a_file = self.write( + "3_5_place_dp", + { + "r1/D": [-10.0, 5.0], # improves to passing + "r2/D": [20.0, 5.0], # degrades to failing + "r3/D": [30.0, 5.0], # unchanged + "r4/D": [40.0, 5.0], # removed in B + "out": [None, None], # unconstrained + }, + ) + self.b_file = self.write( + "4_1_cts", + { + "r1/D": [15.0, 4.0], + "r2/D": [-5.0, 6.0], + "r3/D": [30.0, None], # hold constrained only in A + "r5/D": [50.0, 5.0], # new in B + "out": [None, None], + "clkload0/Y": [None, None], # new but unconstrained + }, + ) + os.utime(self.a_file, (1, 1)) + os.utime(self.b_file, (2, 2)) + + def tearDown(self): + self.tmp_dir.cleanup() + + def write(self, step, endpoints): + f = os.path.join(self.tmp_dir.name, step + endpointSlack.SUFFIX) + with open(f, "w") as fh: + json.dump(snapshot(step, endpoints), fh) + return f + + def test_load(self): + a = endpointSlack.load_snapshot(self.a_file) + self.assertEqual(a["name"], "3_5_place_dp") + self.assertEqual(len(a["endpoints"]), 5) + self.assertNotIn("out", a["setup"]) + self.assertAlmostEqual(a["setup"]["r1/D"], -10e-12) + s = endpointSlack.summary(a["setup"]) + self.assertEqual(s["violations"], 1) + self.assertAlmostEqual(s["wns"], -10e-12) + self.assertAlmostEqual(s["tns"], -10e-12) + + def test_compare(self): + a = endpointSlack.load_snapshot(self.a_file) + b = endpointSlack.load_snapshot(self.b_file) + setup = endpointSlack.compare(a, b, "setup") + self.assertEqual([ep for ep, _ in setup["only_a"]], ["r4/D"]) + self.assertEqual([ep for ep, _ in setup["only_b"]], ["r5/D"]) + self.assertEqual(len(setup["both"]), 3) + m = endpointSlack.movement(setup["both"]) + self.assertEqual( + m, + { + "improved": 1, + "degraded": 1, + # r3/D is unchanged but positive in both, so not counted + "unchanged": 0, + "newly_failing": 1, + "newly_passing": 1, + }, + ) + hold = endpointSlack.compare(a, b, "hold") + self.assertEqual([ep for ep, _ in hold["constrained_only_a"]], ["r3/D"]) + self.assertEqual(len(hold["both"]), 2) + + def test_tolerance(self): + both = [("r1/D", -10e-12, -9.9e-12), ("r2/D", -10e-12, -12e-12)] + m = endpointSlack.movement(both, tolerance=0.5e-12) + self.assertEqual((m["improved"], m["degraded"], m["unchanged"]), (0, 1, 1)) + m = endpointSlack.movement(both) + self.assertEqual((m["improved"], m["degraded"], m["unchanged"]), (1, 1, 0)) + + def test_worst(self): + a = endpointSlack.load_snapshot(self.a_file) + b = endpointSlack.load_snapshot(self.b_file) + setup = endpointSlack.compare(a, b, "setup", worst=1) + # worst of A is r1/D, worst of B is r2/D + self.assertEqual(sorted(ep for ep, _, _ in setup["both"]), ["r1/D", "r2/D"]) + + def test_spearman(self): + self.assertAlmostEqual(endpointSlack.spearman([1, 2, 3], [10, 20, 30]), 1.0) + self.assertAlmostEqual(endpointSlack.spearman([1, 2, 3], [3, 2, 1]), -1.0) + self.assertEqual(endpointSlack._ranks([5, 1, 5, 3]), [3.5, 1.0, 3.5, 2.0]) + self.assertIsNone(endpointSlack.spearman([1], [1])) + self.assertIsNone(endpointSlack.spearman([1, 1], [1, 2])) + + def test_metrics(self): + a = endpointSlack.load_snapshot(self.a_file) + b = endpointSlack.load_snapshot(self.b_file) + m = endpointSlack.compare(a, b, "setup")["metrics"] + # r3/D is positive in both and excluded; r1/D: -10 -> 15, r2/D: 20 -> -5 + self.assertEqual(m["n"], 2) + self.assertAlmostEqual(m["spearman"], -1.0) + self.assertAlmostEqual(m["bias"], 0.0) + self.assertAlmostEqual(m["mae"], 25e-12) + self.assertAlmostEqual(m["max_abs"], 25e-12) + self.assertAlmostEqual(m["top_agreement"], 1.0) + self.assertEqual(m["violator_recall"], 0.0) + self.assertEqual(m["violator_precision"], 0.0) + # With K=1 the worst of A (r1/D) and of B (r2/D) differ + m = endpointSlack.compare(a, b, "setup", critical=1)["metrics"] + self.assertEqual(m["n"], 2) + self.assertAlmostEqual(m["top_agreement"], 0.0) + # No hold violations: nothing critical + m = endpointSlack.compare(a, b, "hold")["metrics"] + self.assertEqual(m["n"], 0) + self.assertIsNone(m["spearman"]) + self.assertIsNone(m["violator_recall"]) + + def test_index_row_class(self): + def row_class(a_eps, b_eps): + a = endpointSlack.load_snapshot(self.write("3_3_place_gp", a_eps)) + b = endpointSlack.load_snapshot(self.write("3_4_place_resized", b_eps)) + cmps = {c: endpointSlack.compare(a, b, c) for c in endpointSlack.CHECKS} + page = endpointSlack.track_index_html([(a, b, cmps)], 1e9, "ns", None) + body = page[page.index(" 4_1_cts", out) + with open(html_file) as f: + content = f.read() + self.assertIn("const DATA = {", content) + self.assertNotIn("__DATA__", content) + with open(csv_file) as f: + self.assertEqual(len(f.readlines()), 1 + 5 + 6) + self.assertEqual( + sorted(os.listdir(track_dir)), + ["3_5_place_dp__4_1_cts.html", "index.html"], + ) + with open(os.path.join(track_dir, "index.html")) as f: + self.assertIn("3_5_place_dp__4_1_cts.html", f.read()) + + +if __name__ == "__main__": + unittest.main() diff --git a/flow/test/test_genElapsedTime.py b/flow/test/test_genElapsedTime.py index 33a06dbd64..ae96ee6d6b 100755 --- a/flow/test/test_genElapsedTime.py +++ b/flow/test/test_genElapsedTime.py @@ -30,7 +30,8 @@ def test_elapsed_time(self, mock_stdout): genElapsedTime.scan_logs(["--logDir", str(self.tmp_dir.name), "--noHeader"]) # check if output is correct expected_output = ( - self.tmp_dir.name + "\n1_test 5400 9440 N/A\nTotal 5400 9440\n" + self.tmp_dir.name + + "\n1_test 5400 N/A N/A 9440 N/A\nTotal 5400 0 N/A 9440\n" ).split() actual_output = mock_stdout.getvalue().split() self.assertEqual(actual_output, expected_output) @@ -44,7 +45,7 @@ def test_zero_time(self, mock_stdout): # call the script with the test log file genElapsedTime.scan_logs(["--logDir", str(self.tmp_dir.name), "--noHeader"]) expected_output = ( - self.tmp_dir.name + "\n1_test 74 9440 N/A\nTotal 74 9440\n" + self.tmp_dir.name + "\n1_test 74 N/A N/A 9440 N/A\nTotal 74 0 N/A 9440\n" ).split() actual_output = mock_stdout.getvalue().split() self.assertEqual(actual_output, expected_output) @@ -61,7 +62,8 @@ def test_elapsed_time_longer_duration(self, mock_stdout): genElapsedTime.scan_logs(["--logDir", str(self.tmp_dir.name), "--noHeader"]) # check if output is correct expected_output = ( - self.tmp_dir.name + "\n1_test 744 9440 N/A Total 744 9440" + self.tmp_dir.name + + "\n1_test 744 5252 7.06 9440 N/A Total 744 5252 7.06 9440" ).split() actual_output = mock_stdout.getvalue().split() self.assertEqual(actual_output, expected_output) diff --git a/flow/test/test_run_command.py b/flow/test/test_run_command.py index 149940afa2..b4a4588ed5 100644 --- a/flow/test/test_run_command.py +++ b/flow/test/test_run_command.py @@ -309,9 +309,9 @@ def test_genElapsedTime_parses_prefixed_output(self): with patch("sys.stdout", new_callable=StringIO) as mock_out: genElapsedTime.scan_logs(["--logDir", log_dir, "--noHeader"]) output = mock_out.getvalue() - # 0:04.26 is 4 seconds, and 671508KB is 655MB; the prefix is not - # part of either. - self.assertRegex(output, r"1_test\s+\S*\s+4\s+655") + # 0:04.26 is 4 seconds, 4.08 + 0.17 is 4 CPU seconds at a 1.00 + # ratio, and 671508KB is 655MB; the prefix is not part of any. + self.assertRegex(output, r"1_test\s+\S*\s+4\s+4\s+1\.00\s+655") def test_genElapsedTime_parses_hours(self): """Verify genElapsedTime.py understands the optional hours field.""" @@ -332,7 +332,7 @@ def test_genElapsedTime_parses_hours(self): with patch("sys.stdout", new_callable=StringIO) as mock_out: genElapsedTime.scan_logs(["--logDir", log_dir, "--noHeader"]) output = mock_out.getvalue() - self.assertRegex(output, r"1_test\s+\S*\s+3661\s+655") + self.assertRegex(output, r"1_test\s+\S*\s+3661\s+4\s+0\.00\s+655") if __name__ == "__main__": diff --git a/flow/test/test_uploadMetadata.py b/flow/test/test_uploadMetadata.py new file mode 100755 index 0000000000..59f4ee57b1 --- /dev/null +++ b/flow/test/test_uploadMetadata.py @@ -0,0 +1,275 @@ +#!/usr/bin/env python3 + +"""Tests for the Pub/Sub payload that uploadMetadata.py publishes. + +uploadMetadata.py does its work at import time (it parses arguments, changes +to flow/ and walks reports/), so it runs here as a subprocess. The script is +copied into a temporary util/ directory next to a temporary reports/ tree, +which makes that tree the one it walks, and stub google.cloud modules on +PYTHONPATH record every published message instead of sending it. +""" + +import json +import os +import re +import shutil +import subprocess +import sys +import tempfile +import unittest +from datetime import datetime, timezone + +SCRIPT = os.path.join( + os.path.dirname(os.path.abspath(__file__)), "..", "util", "uploadMetadata.py" +) + +STUB_PUBSUB = """ +import json +import os + + +class _Future: + def __init__(self, message_id): + self._message_id = message_id + + def result(self): + if os.environ.get("STUB_PUBSUB_FAIL"): + raise RuntimeError("stub publish failure") + return self._message_id + + +class PublisherClient: + def __init__(self, credentials=None): + pass + + def topic_path(self, project, topic): + return f"projects/{project}/topics/{topic}" + + def publish(self, topic_path, data, **attributes): + with open(os.environ["STUB_PUBSUB_OUT"], "a") as f: + record = {"data": json.loads(data), "attributes": attributes} + f.write(json.dumps(record) + "\\n") + return _Future("stub-id") +""" + +STUB_SERVICE_ACCOUNT = """ +class Credentials: + @staticmethod + def from_service_account_file(path): + return None +""" + +BUILD_TIME_FORMAT = re.compile(r"^\d{4}-\d{2}-\d{2} \d{2}:\d{2}$") + + +class TestUploadMetadata(unittest.TestCase): + def setUp(self): + self.tmp = tempfile.TemporaryDirectory() + root = self.tmp.name + self.flow = os.path.join(root, "flow") + os.makedirs(os.path.join(self.flow, "util")) + os.makedirs(os.path.join(self.flow, "reports")) + shutil.copy(SCRIPT, os.path.join(self.flow, "util")) + + stubs = os.path.join(root, "stubs") + files = { + "google/__init__.py": "", + "google/cloud/__init__.py": "", + "google/cloud/pubsub_v1.py": STUB_PUBSUB, + "google/oauth2/__init__.py": "", + "google/oauth2/service_account.py": STUB_SERVICE_ACCOUNT, + } + for rel, content in files.items(): + path = os.path.join(stubs, rel) + os.makedirs(os.path.dirname(path), exist_ok=True) + with open(path, "w") as f: + f.write(content) + self.stubs = stubs + self.out = os.path.join(root, "published.jsonl") + + def tearDown(self): + self.tmp.cleanup() + + def add_design(self, platform, design, variant="base", metrics=None): + report_dir = os.path.join(self.flow, "reports", platform, design, variant) + os.makedirs(report_dir) + with open(os.path.join(report_dir, "metadata.json"), "w") as f: + json.dump(metrics or {"finish:area": 1.0}, f) + + def run_script(self, *extra, fail=False, tz=None): + env = dict(os.environ) + if tz: + env["TZ"] = tz + env["PYTHONPATH"] = self.stubs + env["STUB_PUBSUB_OUT"] = self.out + if fail: + env["STUB_PUBSUB_FAIL"] = "1" + cmd = [ + sys.executable, + os.path.join(self.flow, "util", "uploadMetadata.py"), + "--buildID", + "42", + "--branchName", + "master", + "--pipelineID", + "jenkins-ORFS-master-42", + "--commitSHA", + "abc123", + "--jenkinsURL", + "http://jenkins/job/ORFS/42/", + "--jenkinsEnv", + "public", + "--pubsubProjectID", + "test-project", + *extra, + ] + result = subprocess.run(cmd, env=env, capture_output=True, text=True) + messages = [] + if os.path.exists(self.out): + with open(self.out) as f: + messages = [json.loads(line) for line in f] + return result, messages + + def test_empty_designs_publishes_report(self): + result, messages = self.run_script( + "--jobName", + "ORFS", + "--buildTime", + "2026-10-05 12:34", + "--expectedDesigns", + "12", + "--noMetricsReason", + " flow failed before metrics ", + ) + self.assertEqual(result.returncode, 0, result.stdout + result.stderr) + self.assertEqual(len(messages), 1) + payload = messages[0]["data"] + self.assertEqual(payload["designs"], []) + self.assertEqual(payload["payload_schema_version"], 3) + self.assertEqual(payload["build_time"], "2026-10-05 12:34") + self.assertEqual(payload["design_count"], 12) + self.assertEqual(payload["no_metrics_reason"], "flow failed before metrics") + self.assertEqual(messages[0]["attributes"]["payload_schema_version"], "3") + self.assertIn("empty (no-metrics)", result.stdout) + + def test_empty_designs_without_new_flags(self): + result, messages = self.run_script() + self.assertEqual(result.returncode, 0, result.stdout + result.stderr) + self.assertEqual(len(messages), 1) + payload = messages[0]["data"] + self.assertEqual(payload["designs"], []) + self.assertEqual(payload["payload_schema_version"], 2) + self.assertRegex(payload["build_time"], BUILD_TIME_FORMAT) + self.assertNotIn("design_count", payload) + self.assertNotIn("no_metrics_reason", payload) + + def test_blank_reason_is_omitted(self): + result, messages = self.run_script("--noMetricsReason", " ") + self.assertEqual(result.returncode, 0, result.stdout + result.stderr) + self.assertNotIn("no_metrics_reason", messages[0]["data"]) + + def test_empty_designs_failed_publish_exits_nonzero(self): + result, _ = self.run_script(fail=True) + self.assertEqual(result.returncode, 1, result.stdout + result.stderr) + self.assertIn("[ERROR] Pub/Sub publish failed", result.stdout) + + def test_default_build_time_is_utc(self): + # Far from UTC, so a local-time default could not pass by accident. + before = datetime.now(timezone.utc).replace(second=0, microsecond=0) + result, messages = self.run_script(tz="Pacific/Kiritimati") + after = datetime.now(timezone.utc) + self.assertEqual(result.returncode, 0, result.stdout + result.stderr) + build_time = datetime.strptime( + messages[0]["data"]["build_time"], "%Y-%m-%d %H:%M" + ).replace(tzinfo=timezone.utc) + self.assertTrue(before <= build_time <= after, build_time) + + def test_designs_payload_gains_build_time_only(self): + self.add_design("nangate45", "gcd", metrics={"finish:area": 5.0}) + result, messages = self.run_script( + "--jobName", "ORFS", "--noMetricsReason", "ignored" + ) + self.assertEqual(result.returncode, 0, result.stdout + result.stderr) + self.assertEqual(len(messages), 1) + payload = messages[0]["data"] + self.assertRegex(payload.pop("build_time"), BUILD_TIME_FORMAT) + self.assertEqual( + payload, + { + "payload_schema_version": 3, + "jenkins_env": "public", + "build_id": "42", + "branch_name": "master", + "pipeline_id": "jenkins-ORFS-master-42", + "change_branch": None, + "commit_sha": "abc123", + "jenkins_url": "http://jenkins/job/ORFS/42/", + "job_name": "ORFS", + "designs": [ + { + "platform": "nangate45", + "design": "gcd", + "variant": "base", + "metrics": {"finish__area": 5.0}, + } + ], + }, + ) + self.assertNotIn("empty (no-metrics)", result.stdout) + + def test_design_count_with_designs(self): + self.add_design("nangate45", "gcd") + result, messages = self.run_script("--expectedDesigns", "3") + self.assertEqual(result.returncode, 0, result.stdout + result.stderr) + payload = messages[0]["data"] + self.assertEqual(payload["design_count"], 3) + self.assertEqual(len(payload["designs"]), 1) + + def test_empty_designs_invalid_provenance_falls_back_to_v3(self): + bad = os.path.join(self.tmp.name, "provenance.json") + with open(bad, "w") as f: + f.write("[]") + result, messages = self.run_script("--jobName", "ORFS", "--provenanceFile", bad) + self.assertEqual(result.returncode, 0, result.stdout + result.stderr) + payload = messages[0]["data"] + self.assertEqual(payload["payload_schema_version"], 3) + self.assertEqual(payload["designs"], []) + self.assertNotIn("submodules", payload) + + def test_empty_designs_valid_provenance_is_v4(self): + good = os.path.join(self.tmp.name, "provenance.json") + with open(good, "w") as f: + json.dump( + { + "jenkins_library": {"ref": "v1.0.0"}, + "submodules": [ + {"path": "tools/OpenROAD", "sha": "def456", "overridden": False} + ], + }, + f, + ) + result, messages = self.run_script( + "--jobName", "ORFS", "--provenanceFile", good + ) + self.assertEqual(result.returncode, 0, result.stdout + result.stderr) + payload = messages[0]["data"] + self.assertEqual(payload["payload_schema_version"], 4) + self.assertEqual(payload["designs"], []) + self.assertEqual(payload["jenkins_library"], {"ref": "v1.0.0"}) + + def test_no_publisher_publishes_nothing(self): + env = dict(os.environ) + env["PYTHONPATH"] = self.stubs + env["STUB_PUBSUB_OUT"] = self.out + result = subprocess.run( + [sys.executable, os.path.join(self.flow, "util", "uploadMetadata.py")], + env=env, + capture_output=True, + text=True, + ) + self.assertEqual(result.returncode, 0, result.stdout + result.stderr) + self.assertFalse(os.path.exists(self.out)) + + +if __name__ == "__main__": + unittest.main() diff --git a/flow/util/checkQorMetrics.py b/flow/util/checkQorMetrics.py index 7146c53e50..f7e6c4d434 100755 --- a/flow/util/checkQorMetrics.py +++ b/flow/util/checkQorMetrics.py @@ -4,8 +4,8 @@ (https://dashboard.precisioninno.com). The check POSTs a run's numeric metrics from metadata.json to the dashboard, -which compares them against a real baseline build -- the latest master build -by default -- using the thresholds it stores in rule_configs. This is the QoR +which compares them against a real baseline build -- the master build at the +run's merge base, by default -- using the thresholds it stores in rule_configs. This is the QoR gate behind `make metadata`. Rule tolerances live in the dashboard, not in this repository, and the baseline moves with master, so a merged change becomes the new baseline without a file update. @@ -21,6 +21,19 @@ export DASHBOARD_API_KEY=plt_... # optional; needed for private platforms ./util/checkQorMetrics.py +Each run is checked as the commit metadata.json records (--commit overrides +it). The dashboard searches its default baseline pipelines in order and takes +a master build that has the design: the one at the commit's merge base with +master, else the latest one before the commit. A commit on master is its own +merge base, so a master run is compared against that commit's own build. +Without a commit the run is compared against the latest master build. + +--job-name (DASHBOARD_JOB_NAME) checks as a build of that pipeline instead, with +its CI rules for the branch checked out here (--branch overrides it): the +previous build on a trunk branch, the merge base on any other branch. CI +passes --branch and --commit (or DASHBOARD_BRANCH and DASHBOARD_COMMIT), since +its checkout has no branch. + Exit status: 1 when the dashboard reports a failed rule for any checked run, or when a metadata.json is missing, malformed, or holds no numeric metric. 0 otherwise. A run the dashboard could not judge -- no baseline, nothing @@ -34,8 +47,10 @@ import argparse import concurrent.futures import json +import math import os import re +import subprocess import sys import time import urllib.error @@ -65,8 +80,6 @@ RETRY_BACKOFF_SECONDS = 1.0 RETRYABLE_STATUS = frozenset({429, 500, 502, 503, 504}) -DEFAULT_JOB_NAME = "OpenROAD-flow-scripts-Public" - # metadata.json records the ORFS commit, but genMetrics.py writes the strings # "git not on PATH" / "not a git repo" / "N/A" there when it cannot resolve one. SHA_RE = re.compile(r"^[0-9a-f]{40}$") @@ -148,7 +161,9 @@ class MetadataError(Exception): def load_metadata(path, only_prefix=None): - """Returns (metrics, commit_sha). Raises MetadataError if the file is unusable. + """Returns (metrics, commit_sha, dropped). Raises MetadataError if the file is unusable. + + dropped names the metrics left out because their value is not finite. only_prefix keeps just the metrics whose name starts with one of the given prefixes. The dashboard evaluates only the metrics it receives, so sending @@ -180,6 +195,14 @@ def load_metadata(path, only_prefix=None): # reported metric count honest. metrics = {key: value for key, value in metrics.items() if "__iter__" not in key} + # ORFS writes inf/-inf/NaN for a metric it could not compute (an unconstrained + # timing path reports -inf TNS). json.dumps renders those as bare Infinity/NaN + # tokens, which are not JSON: the dashboard rejects the whole request with + # HTTP 400, so one unusable metric would cost the run its verdict. A value + # that is not finite has nothing to compare against, so leave it out. + dropped = sorted(key for key, value in metrics.items() if not math.isfinite(value)) + metrics = {key: value for key, value in metrics.items() if key not in dropped} + if only_prefix: metrics = { key: value @@ -191,7 +214,27 @@ def load_metadata(path, only_prefix=None): raise MetadataError(f"no numeric metrics in {path}") commit = str(raw.get(COMMIT_KEY, "")) - return metrics, commit if SHA_RE.match(commit) else "" + return metrics, commit if SHA_RE.match(commit) else "", dropped + + +def current_branch(): + """The branch checked out in this repository, or "" when git cannot say. + + A detached HEAD reads as "HEAD", which the dashboard treats as any other + non-trunk branch: it compares against the merge base, which is the right + baseline for a detached checkout too. + """ + try: + output = subprocess.run( + ["git", "rev-parse", "--abbrev-ref", "HEAD"], + capture_output=True, + text=True, + timeout=10, + check=True, + ).stdout + except (OSError, subprocess.SubprocessError): + return "" + return output.strip() def post_check(endpoint, api_key, payload): @@ -234,8 +277,22 @@ def post_check(endpoint, api_key, payload): return None, f"{error_message} (after {RETRY_ATTEMPTS} attempts)" -def check_run(run, endpoint, api_key, base_commit, job_name, only_prefix=None): - """Checks one (platform, design, variant) and returns a result dict.""" +def check_run( + run, + endpoint, + api_key, + base_commit, + job_name, + only_prefix=None, + commit="", + branch="", +): + """Checks one (platform, design, variant) and returns a result dict. + + commit replaces the one metadata.json records. branch is sent only with a + job_name: without one the dashboard ignores it and resolves the baseline + from the commit alone. + """ platform, design, variant, metadata_path = run result = { "platform": platform, @@ -245,6 +302,7 @@ def check_run(run, endpoint, api_key, base_commit, job_name, only_prefix=None): "response": None, "error": None, "metric_count": 0, + "dropped": [], } # One run's surprise must not take down the sweep: this is called from a @@ -255,24 +313,33 @@ def check_run(run, endpoint, api_key, base_commit, job_name, only_prefix=None): # A bad local file is the caller's problem, not the service's: it gets # its own status so it exits 1 instead of passing as inconclusive. try: - metrics, commit = load_metadata(metadata_path, only_prefix) + metrics, recorded_commit, dropped = load_metadata( + metadata_path, only_prefix + ) except MetadataError as error: result["status"] = "invalid" result["error"] = str(error) return result result["metric_count"] = len(metrics) - + result["dropped"] = dropped + commit = commit or recorded_commit + result["commit"] = commit + + # No JobName and no PipelineId makes this a checkout to the dashboard: + # it picks the pipeline itself, the first of its default baseline + # pipelines with a build of this design. A JobName makes it a build of + # that pipeline, resolved by that pipeline's rules for BranchName. payload = { "CommitSha": commit, - "BranchName": "", + "BranchName": branch if job_name else "", "PipelineId": "", - "JobName": job_name, "PlatformName": platform, "DesignName": design, "VariantName": variant, "Metrics": metrics, - "IsLocal": True, } + if job_name: + payload["JobName"] = job_name if base_commit: payload["BaseCommitSha"] = base_commit @@ -334,10 +401,22 @@ def render_run(result, verbose): f"{passed} passed, {failed} failed, {missing} missing " f"({result['metric_count']} metrics sent)" ) + pipeline = response.get("baselinePipeline") lines.append( f"[INFO] baseline build {response.get('baseBuildId')} " - f"({(response.get('baseCommitSha') or '?')[:12]}, {strategy})" + f"({(response.get('baseCommitSha') or '?')[:12]}, {strategy}" + f"{', ' + pipeline if pipeline else ''})" ) + if not result.get("commit") and strategy == "latest-master": + lines.append( + "[WARN] metadata.json records no commit, so this was compared " + "against the latest master build." + ) + if result["dropped"]: + lines.append( + f"[WARN] Left out {len(result['dropped'])} non-finite metric(s): " + + ", ".join(result["dropped"]) + ) if result["status"] == "inconclusive": lines.append( @@ -501,15 +580,34 @@ def parse_args(argv): ) parser.add_argument( "--base-commit", - help="Pin the baseline to this commit's build instead of latest master.", + help="Pin the baseline to this commit's build instead of resolving one.", + ) + parser.add_argument( + "--api-url", + default=os.environ.get("DASHBOARD_API_URL") or None, + help="Dashboard API base URL, e.g. a staging deployment. Takes " + "precedence over --beta. Env: DASHBOARD_API_URL.", + ) + parser.add_argument( + "--commit", + default=os.environ.get("DASHBOARD_COMMIT", ""), + help="Full commit SHA to check as, instead of the one metadata.json " + "records. Env: DASHBOARD_COMMIT.", + ) + parser.add_argument( + "--branch", + default=os.environ.get("DASHBOARD_BRANCH") or None, + help="With --job-name: the branch to check as, instead of the one " + "checked out here, e.g. the PR branch in CI. " + "Env: DASHBOARD_BRANCH.", ) parser.add_argument( "--job-name", - default=os.environ.get("DASHBOARD_JOB_NAME", DEFAULT_JOB_NAME), - help="Canonical Jenkins job-folder name the dashboard uses to scope the master " - f"baseline to a pipeline. Default: {DEFAULT_JOB_NAME}. Override for a " - "secure/private branch whose master-equivalent builds elsewhere, e.g. " - "OpenROAD-flow-scripts-Private.", + default=os.environ.get("DASHBOARD_JOB_NAME") or None, + help="Check as a build of this CI pipeline, with its rules for the " + "branch. Default: the dashboard searches its default baseline " + "pipelines and takes the first with a build of the design. " + "Env: DASHBOARD_JOB_NAME.", ) parser.add_argument( "--metadata", @@ -612,8 +710,21 @@ def selected(entry): def run_check(argv=None): args = parse_args(argv) - endpoint = (BETA_API_URL if args.beta else API_URL) + CHECK_PATH + api_url = args.api_url or (BETA_API_URL if args.beta else API_URL) + endpoint = api_url.rstrip("/") + CHECK_PATH api_key = os.environ.get("DASHBOARD_API_KEY", "") + # The dashboard matches the commit exactly and silently falls back to the + # latest master build on a miss, so anything but a full SHA is an error. + commit = args.commit.strip().lower() + if commit and not SHA_RE.match(commit): + print( + f"[ERROR] --commit {args.commit.strip()!r} is not a full 40-character SHA." + ) + return 1 + # Only a pipeline run uses the branch; a checkout is resolved from the commit. + branch = "" + if args.job_name: + branch = (args.branch if args.branch is not None else current_branch()).strip() if args.metadata: # Single-run mode: the caller (make metadata-check) names the run and @@ -642,6 +753,21 @@ def run_check(argv=None): ) if args.base_commit: header.append(f"[INFO] Baseline pinned to commit {args.base_commit}") + elif args.job_name and branch: + header.append( + f"[INFO] Checking as a build of {args.job_name}, branch {branch}" + + (f", commit {commit}" if commit else "") + ) + elif args.job_name: + header.append( + f"[WARN] Checking as a build of {args.job_name} with no branch (git " + "could not name one, and no --branch): resolved as a feature branch." + ) + else: + header.append( + "[INFO] Baseline from the dashboard's default pipelines, resolved " + "from " + (f"commit {commit}" if commit else "each run's recorded commit") + ) if args.only_prefix: prefixes = " ".join(args.only_prefix) header.append(f"[INFO] Sending only metrics prefixed {prefixes}") @@ -661,6 +787,8 @@ def run_check(argv=None): args.base_commit, args.job_name, args.only_prefix, + commit, + branch, ), runs, ) diff --git a/flow/util/endpointSlack.py b/flow/util/endpointSlack.py new file mode 100755 index 0000000000..3297d2825f --- /dev/null +++ b/flow/util/endpointSlack.py @@ -0,0 +1,961 @@ +#!/usr/bin/env python3 +"""Compare endpoint slack across flow steps. + +Snapshots are written at the end of every flow step (e.g. 3_3_place_gp) when +REPORT_ENDPOINT_SLACK=1, as $REPORTS_DIR/_endpoint_slack.json, with the +setup and hold slack of every timing endpoint. + +Examples: + endpointSlack.py list reports/nangate45/gcd/base + endpointSlack.py track reports/nangate45/gcd/base + endpointSlack.py compare A_endpoint_slack.json B_endpoint_slack.json -o cmp.html + endpointSlack.py export reports/nangate45/gcd/base -o slack.csv +""" + +import argparse +import csv +import glob +import html +import json +import os +import statistics +import sys + +CHECKS = ("setup", "hold") +UNITS = {"s": 1.0, "ns": 1e9, "ps": 1e12} +SUFFIX = "_endpoint_slack.json" + + +def load_snapshot(path): + """Load a snapshot file. + + Returns a dict with metadata, "endpoints" (all endpoint names) and per + check a dict endpoint -> slack in seconds for constrained endpoints. + """ + with open(path) as f: + data = json.load(f) + unit = data.get("time_unit", 1.0) + name = os.path.basename(path) + if name.endswith(SUFFIX): + name = name[: -len(SUFFIX)] + snapshot = { + "file": path, + "name": name, + "design": data.get("design", ""), + "step": data.get("step", name), + "parasitics": data.get("parasitics", ""), + "endpoints": set(data["endpoints"]), + } + for i, check in enumerate(CHECKS): + snapshot[check] = { + ep: slacks[i] * unit + for ep, slacks in data["endpoints"].items() + if slacks[i] is not None + } + return snapshot + + +def find_snapshots(reports_dir): + """Snapshot files in execution (modification time) order.""" + files = glob.glob(os.path.join(reports_dir, "*" + SUFFIX)) + return sorted(files, key=lambda f: (os.path.getmtime(f), f)) + + +def load_dir(reports_dir): + return [load_snapshot(f) for f in find_snapshots(reports_dir)] + + +def summary(slacks): + """WNS, TNS and number of violating endpoints of a slack dict.""" + values = list(slacks.values()) + negative = [s for s in values if s < 0] + return { + "count": len(values), + "wns": min(values) if values else None, + "tns": sum(negative), + "violations": len(negative), + } + + +def worst_endpoints(slacks, n): + return set(sorted(slacks, key=slacks.get)[:n]) + + +def _ranks(values): + """Ranks starting at 1, with tied values given their average rank.""" + order = sorted(range(len(values)), key=values.__getitem__) + ranks = [0.0] * len(values) + i = 0 + while i < len(order): + j = i + while j + 1 < len(order) and values[order[j + 1]] == values[order[i]]: + j += 1 + for k in range(i, j + 1): + ranks[order[k]] = (i + j) / 2 + 1 + i = j + 1 + return ranks + + +def spearman(x, y): + """Spearman rank correlation, None if undefined (n < 2 or constant).""" + if len(x) < 2: + return None + try: + return statistics.correlation(_ranks(x), _ranks(y)) + except statistics.StatisticsError: + return None + + +def _ratio(num, den): + return num / den if den else None + + +def metrics(sa, sb, critical=1000): + """Agreement between the slacks of two steps for one check. + + sa, sb: endpoint -> slack of the endpoints constrained in both steps. + The critical set is the union of the worst `critical` endpoints of A and + of B, excluding endpoints with positive slack in both steps, which are + not being optimized. Correlation and error are measured on it. + """ + top_a = worst_endpoints(sa, critical) + top_b = worst_endpoints(sb, critical) + crit = [ep for ep in top_a | top_b if sa[ep] <= 0 or sb[ep] <= 0] + x = [sa[ep] for ep in crit] + y = [sb[ep] for ep in crit] + deltas = [b - a for a, b in zip(x, y)] + viol_a = {ep for ep, s in sa.items() if s < 0} + viol_b = {ep for ep, s in sb.items() if s < 0} + return { + "critical": critical, + "n": len(crit), + "spearman": spearman(x, y), + "bias": statistics.mean(deltas) if deltas else None, + "mae": statistics.mean(abs(d) for d in deltas) if deltas else None, + "rmse": (statistics.mean(d * d for d in deltas) ** 0.5 if deltas else None), + "max_abs": max(abs(d) for d in deltas) if deltas else None, + # Fraction of the critical set in the worst `critical` of both steps + "top_agreement": _ratio( + sum(ep in top_a and ep in top_b for ep in crit), len(crit) + ), + # Of B's violators, the fraction already violating in A + "violator_recall": _ratio(len(viol_a & viol_b), len(viol_b)), + # Of A's violators, the fraction still violating in B + "violator_precision": _ratio(len(viol_a & viol_b), len(viol_a)), + } + + +def compare(a, b, check, worst=None, critical=1000): + """Compare one check (setup or hold) of two snapshots. + + Unconstrained endpoints (e.g. outputs of CTS dummy loads) are ignored. + Returns a dict with: + only_a / only_b: constrained endpoints in only one netlist, + [(endpoint, slack)] + constrained_only_a / constrained_only_b: endpoints in both netlists + but constrained in only one, [(endpoint, slack)] + both: [(endpoint, slack_a, slack_b)], restricted to the union of the + worst `worst` endpoints of A and of B if `worst` is given + metrics: metrics() of all endpoints constrained in both + """ + sa, sb = a[check], b[check] + both = [ep for ep in sa if ep in sb] + m = metrics({ep: sa[ep] for ep in both}, {ep: sb[ep] for ep in both}, critical) + if worst: + keep = worst_endpoints(sa, worst) | worst_endpoints(sb, worst) + both = [ep for ep in both if ep in keep] + return { + "only_a": [(ep, sa[ep]) for ep in sa if ep not in b["endpoints"]], + "only_b": [(ep, sb[ep]) for ep in sb if ep not in a["endpoints"]], + "constrained_only_a": [ + (ep, sa[ep]) for ep in sa if ep not in sb and ep in b["endpoints"] + ], + "constrained_only_b": [ + (ep, sb[ep]) for ep in sb if ep not in sa and ep in a["endpoints"] + ], + "both": [(ep, sa[ep], sb[ep]) for ep in both], + "metrics": m, + } + + +def movement(both, tolerance=0.0): + """Counts of how endpoint slack changed between A and B. + + improved/degraded/unchanged exclude endpoints with positive slack in + both steps, which are not being optimized. Changes of at most + `tolerance` (seconds) count as unchanged. + """ + crit = [(s_a, s_b) for _, s_a, s_b in both if s_a <= 0 or s_b <= 0] + return { + "improved": sum(s_b - s_a > tolerance for s_a, s_b in crit), + "degraded": sum(s_a - s_b > tolerance for s_a, s_b in crit), + "unchanged": sum(abs(s_b - s_a) <= tolerance for s_a, s_b in crit), + "newly_failing": sum(s_a >= 0 > s_b for _, s_a, s_b in both), + "newly_passing": sum(s_b >= 0 > s_a for _, s_a, s_b in both), + } + + +# Digits after the decimal point for each time unit +DIGITS = {"s": 12, "ns": 3, "ps": 1} + + +def _fmt(value, scale, digits): + return "-" if value is None else f"{value * scale:.{digits}f}" + + +def _num(value, scale): + return None if value is None else float(f"{value * scale:.6g}") + + +def _label(snapshot): + """Step name, with the parasitics model the step was timed with.""" + if snapshot["parasitics"]: + return f"{snapshot['name']} ({snapshot['parasitics']} parasitics)" + return snapshot["name"] + + +def _summary_lines(cmp, check, scale, unit, digits, tolerance=0.0): + m = movement(cmp["both"], tolerance) + lines = [ + f"{check:5s} both={len(cmp['both'])} onlyA={len(cmp['only_a'])}" + f" onlyB={len(cmp['only_b'])}" + f" constrained only in A={len(cmp['constrained_only_a'])}" + f" only in B={len(cmp['constrained_only_b'])}", + f" not positive in both: improved={m['improved']}" + f" degraded={m['degraded']} unchanged={m['unchanged']}" + f" newly failing={m['newly_failing']}" + f" newly passing={m['newly_passing']}", + ] + if cmp["both"]: + deltas = [(s_b - s_a) * scale for _, s_a, s_b in cmp["both"]] + lines.append( + f" slack delta (B-A) {unit}:" + f" mean={statistics.mean(deltas):.{digits}f}" + f" median={statistics.median(deltas):.{digits}f}" + f" min={min(deltas):.{digits}f} max={max(deltas):.{digits}f}" + ) + mt = cmp["metrics"] + lines.append( + f" critical (worst {mt['critical']} of A or B, not positive in" + f" both): n={mt['n']} spearman={_fmt_num(mt['spearman'])}" + f" top agreement={_fmt_num(mt['top_agreement'])}" + ) + lines.append( + f" {unit}: bias={_fmt(mt['bias'], scale, digits)}" + f" MAE={_fmt(mt['mae'], scale, digits)}" + f" RMSE={_fmt(mt['rmse'], scale, digits)}" + f" max|delta|={_fmt(mt['max_abs'], scale, digits)}" + ) + lines.append( + f" violators: recall={_fmt_num(mt['violator_recall'])}" + f" precision={_fmt_num(mt['violator_precision'])}" + ) + return lines + + +def _fmt_num(value): + return "-" if value is None else f"{value:.3f}" + + +def cmd_list(args): + scale = UNITS[args.unit] + header = f"{'step':32s} {'parasitics':14s} {'endpoints':>9s}" + for check in CHECKS: + header += f" {check + ' WNS':>10s} {check + ' TNS':>10s} {'#viol':>6s}" + print(header + f" ({args.unit})") + for s in load_dir(args.reports_dir): + line = f"{s['name']:32s} {s['parasitics']:14s} {len(s['endpoints']):9d}" + for check in CHECKS: + sm = summary(s[check]) + line += ( + f" {_fmt(sm['wns'], scale, args.digits):>10s}" + f" {_fmt(sm['tns'], scale, args.digits):>10s}" + f" {sm['violations']:6d}" + ) + print(line) + + +def _pair_file(a, b): + return f"{a['name']}__{b['name']}.html" + + +def cmd_track(args): + scale = UNITS[args.unit] + snaps = load_dir(args.reports_dir) + pairs = list(zip(snaps, snaps[1:])) + if args.html: + os.makedirs(args.html, exist_ok=True) + rows = [] + for i, (a, b) in enumerate(pairs): + print(f"{_label(a)} -> {_label(b)}") + cmps = { + check: compare(a, b, check, args.worst, args.critical) for check in CHECKS + } + for check in CHECKS: + for line in _summary_lines( + cmps[check], check, scale, args.unit, args.digits, args.tolerance + ): + print(" " + line) + rows.append((a, b, cmps)) + if args.html: + links = [("index", "index.html")] + if i > 0: + links.insert(0, ("previous", _pair_file(*pairs[i - 1]))) + if i + 1 < len(pairs): + links.append(("next", _pair_file(*pairs[i + 1]))) + page = compare_html( + a, + b, + cmps, + scale, + args.unit, + args.worst, + links, + args.digits, + args.tolerance, + ) + with open(os.path.join(args.html, _pair_file(a, b)), "w") as f: + f.write(page) + if args.html: + index = os.path.join(args.html, "index.html") + with open(index, "w") as f: + f.write( + track_index_html( + rows, + scale, + args.unit, + args.worst, + args.critical, + args.digits, + args.tolerance, + ) + ) + print(f"Wrote {len(pairs)} comparisons to {args.html}, see {index}") + + +def track_index_html(rows, scale, unit, worst, critical=1000, digits=3, tolerance=0.0): + """Index of step-to-step comparisons with a summary of each.""" + design = rows[0][0]["design"] if rows else "" + + # Cells are strings, or (before, after) pairs shown as "before -> after" + table = [] + for a, b, cmps in rows: + # Endpoints with positive slack in both steps are not considered + changed = considered = improved = 0 + cells = [] + for check in CHECKS: + cmp = cmps[check] + m = movement(cmp["both"], tolerance) + sa, sb = summary(a[check]), summary(b[check]) + added_removed = sum( + s <= 0 + for key in ( + "only_a", + "only_b", + "constrained_only_a", + "constrained_only_b", + ) + for _, s in cmp[key] + ) + changed += m["improved"] + m["degraded"] + added_removed + considered += m["improved"] + m["degraded"] + m["unchanged"] + considered += added_removed + improved += m["improved"] + cells += [ + (_fmt(sa["wns"], scale, digits), _fmt(sb["wns"], scale, digits)), + (_fmt(sa["tns"], scale, digits), _fmt(sb["tns"], scale, digits)), + str(m["improved"]), + str(m["degraded"]), + str(m["newly_failing"]), + str(m["newly_passing"]), + _fmt_num(cmp["metrics"]["spearman"]), + _fmt_num(cmp["metrics"]["top_agreement"]), + _fmt(cmp["metrics"]["mae"], scale, digits), + ] + if not changed: + row_class = "same" + elif improved == considered: + row_class = "better" + else: + row_class = "" + table.append((a, b, row_class, cells)) + + # Pad both sides of the pairs to the column width so they line up + widths = {} + for _, _, _, cells in table: + for i, c in enumerate(cells): + if isinstance(c, tuple): + w = widths.get(i, (0, 0)) + widths[i] = (max(w[0], len(c[0])), max(w[1], len(c[1]))) + + def cell(i, c): + if isinstance(c, tuple): + wa, wb = widths[i] + c = ( + f"{html.escape(c[0])}" + f" → " + f"{html.escape(c[1])}" + ) + else: + c = html.escape(c) + return f"{c}" + + body = "" + for a, b, row_class, cells in table: + link = ( + f"" + f"{html.escape(a['name'])} → {html.escape(b['name'])}" + ) + parasitics = a["parasitics"] + if b["parasitics"] != a["parasitics"]: + parasitics += " → " + b["parasitics"] + cls = f" class='{row_class}'" if row_class else "" + tds = "".join(cell(i, c) for i, c in enumerate(cells)) + body += f"{link}{parasitics}{tds}\n" + head = "".join(f"{check}" for check in CHECKS) + sub = "".join( + "WNSTNSimproveddegraded" + "newly failingnewly passing" + "Spearmantop agreementMAE" + for _ in CHECKS + ) + note = ( + f" Only the worst {worst} endpoints of each pair are compared." if worst else "" + ) + return ( + TRACK_INDEX_TEMPLATE.replace( + "__TITLE__", html.escape(f"{design} endpoint slack by step") + ) + .replace("__UNIT__", unit) + .replace("__NOTE__", html.escape(note)) + .replace("__CRITICAL__", str(critical)) + .replace("__TOL__", f"{tolerance * scale:g} {unit}") + .replace("__HEAD__", head) + .replace("__SUB__", sub) + .replace("__BODY__", body) + ) + + +TRACK_INDEX_TEMPLATE = """ +__TITLE__ + +

__TITLE__

+
Each row compares a step with the next one (__UNIT__). +Endpoints with positive slack in both steps are not considered, and slack +changes of at most __TOL__ count as unchanged. Grey rows: +no considered endpoint changed. Green rows: every considered endpoint +improved (setup and hold). Spearman, top agreement and MAE are +measured on the critical set: the worst __CRITICAL__ endpoints of either step, +excluding those with positive slack in both.__NOTE__
+
+__HEAD__ +__SUB__ +__BODY__
stepsparasitics
+ +""" + + +def cmd_compare(args): + scale = UNITS[args.unit] + a = load_snapshot(args.a) + b = load_snapshot(args.b) + print(f"A: {_label(a)}\nB: {_label(b)}") + if args.worst: + print(f"Endpoints in both restricted to the worst {args.worst} of A or B") + cmps = {check: compare(a, b, check, args.worst, args.critical) for check in CHECKS} + for check in CHECKS: + for line in _summary_lines( + cmps[check], check, scale, args.unit, args.digits, args.tolerance + ): + print(line) + if args.output: + with open(args.output, "w") as f: + f.write( + compare_html( + a, + b, + cmps, + scale, + args.unit, + args.worst, + digits=args.digits, + tolerance=args.tolerance, + ) + ) + print(f"Wrote {args.output}") + + +def cmd_export(args): + scale = UNITS[args.unit] + out = open(args.output, "w", newline="") if args.output else sys.stdout + writer = csv.writer(out) + writer.writerow( + [ + "order", + "step", + "parasitics", + "endpoint", + f"setup_{args.unit}", + f"hold_{args.unit}", + ] + ) + for order, s in enumerate(load_dir(args.reports_dir)): + for ep in sorted(s["endpoints"]): + writer.writerow( + [ + order, + s["step"], + s["parasitics"], + ep, + _num(s["setup"].get(ep), scale), + _num(s["hold"].get(ep), scale), + ] + ) + if args.output: + out.close() + + +def compare_html(a, b, cmps, scale, unit, worst, links=(), digits=3, tolerance=0.0): + """Self-contained interactive HTML for a two-snapshot comparison. + + links: optional (label, href) navigation links shown above the title. + """ + data = {} + for check, cmp in cmps.items(): + data[check] = { + "both": [ + [ep, _num(s_a, scale), _num(s_b, scale)] for ep, s_a, s_b in cmp["both"] + ], + "only_a": sorted( + ([ep, _num(s, scale)] for ep, s in cmp["only_a"]), key=lambda r: r[0] + ), + "only_b": sorted( + ([ep, _num(s, scale)] for ep, s in cmp["only_b"]), key=lambda r: r[0] + ), + "constrained_only_a": len(cmp["constrained_only_a"]), + "constrained_only_b": len(cmp["constrained_only_b"]), + "summary_a": { + k: _num(v, scale) if k in ("wns", "tns") else v + for k, v in summary(a[check]).items() + }, + "summary_b": { + k: _num(v, scale) if k in ("wns", "tns") else v + for k, v in summary(b[check]).items() + }, + "metrics": { + k: _num(v, scale) if k in ("bias", "mae", "rmse", "max_abs") else v + for k, v in cmp["metrics"].items() + }, + } + title = f"{a['design']} {a['name']} vs {b['name']}" + note = f" Only the worst {worst} endpoints of A or B are plotted." if worst else "" + return ( + HTML_TEMPLATE.replace("__TITLE__", html.escape(title)) + .replace("__A__", html.escape(a["name"])) + .replace("__B__", html.escape(b["name"])) + .replace("__PAR_A__", html.escape(a["parasitics"] or "unknown")) + .replace("__PAR_B__", html.escape(b["parasitics"] or "unknown")) + .replace("__NOTE__", html.escape(note)) + .replace( + "__NAV__", + " | ".join( + f"{html.escape(label)}" + for label, href in links + ), + ) + .replace("__UNIT__", unit) + .replace("__DIGITS__", str(digits)) + .replace("__TOL__", repr(tolerance * scale)) + .replace("__DATA__", json.dumps(data).replace(" +__TITLE__ + + +

__TITLE__

+
Endpoint slack: x = A (__A__), y = B (__B__), __UNIT__. +Parasitics: A __PAR_A__, B __PAR_B__.__NOTE__ +Drag to zoom, double-click to reset.
+
+ +
+
+
Improved and degraded exclude endpoints with positive +slack in both steps.
+
+
+
+
+

Most degraded

+
Excluding endpoints with positive slack in both
+
+

Most improved

+
Excluding endpoints with positive slack in both
+
+
+
+

Endpoints only in A (__A__)

+

Endpoints only in B (__B__)

+
+ + +""" + + +def main(argv=None): + parser = argparse.ArgumentParser( + description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter + ) + sub = parser.add_subparsers(dest="cmd", required=True) + + def common(p, worst=True): + p.add_argument("--unit", choices=UNITS, default="ns") + p.add_argument( + "--digits", + type=int, + help="digits after the decimal point for times" + " (default: 3 for ns, 1 for ps)", + ) + p.add_argument( + "--tolerance", + type=float, + help="slack changes of at most this much (in --unit) count as" + " unchanged (default: half the last displayed digit, so a change" + " shown as 0 is unchanged)", + ) + if worst: + p.add_argument( + "--worst", + type=int, + metavar="N", + help="only compare the worst N endpoints of A or B", + ) + p.add_argument( + "--critical", + type=int, + default=1000, + metavar="K", + help="correlation and error are measured on the worst K" + " endpoints of A or B, excluding those with positive slack in" + " both (default 1000)", + ) + + p = sub.add_parser("list", help="list snapshots with WNS/TNS per step") + p.add_argument("reports_dir") + common(p, worst=False) + p.set_defaults(func=cmd_list) + + p = sub.add_parser("track", help="compare consecutive snapshots") + p.add_argument("reports_dir") + p.add_argument( + "--html", + metavar="DIR", + help="write an HTML scatter for every step vs. its successor and an" + " index.html to DIR", + ) + common(p) + p.set_defaults(func=cmd_track) + + p = sub.add_parser("compare", help="compare two snapshots") + p.add_argument("a", help="earlier snapshot (x axis)") + p.add_argument("b", help="later snapshot (y axis)") + p.add_argument("-o", "--output", help="write interactive HTML scatter") + common(p) + p.set_defaults(func=cmd_compare) + + p = sub.add_parser("export", help="flatten all snapshots to CSV") + p.add_argument("reports_dir") + p.add_argument("-o", "--output", help="CSV file (default stdout)") + common(p, worst=False) + p.set_defaults(func=cmd_export) + + args = parser.parse_args(argv) + if args.digits is None: + args.digits = DIGITS[args.unit] + if args.tolerance is None: + args.tolerance = 0.5 * 10**-args.digits + # Internally slack is in seconds + args.tolerance /= UNITS[args.unit] + args.func(args) + + +if __name__ == "__main__": + main() diff --git a/flow/util/genElapsedTime.py b/flow/util/genElapsedTime.py index 3336b651ea..8866fa1c70 100755 --- a/flow/util/genElapsedTime.py +++ b/flow/util/genElapsedTime.py @@ -27,8 +27,13 @@ # prefix every log line -- a per-line elapsed stamp, "[ 123.45] " -- # and such a prefix must not change what this reports. Hours are # optional, as _format_elapsed only emits them past an hour, and the -# fraction of a second is matched so it can be discarded. -ELAPSED_RE = re.compile(r"Elapsed time: (?:(\d+):)?(\d+):(\d+)(?:\.\d+)?\[h:\]min:sec") +# fraction of a second is matched so it can be discarded from the +# reported seconds, but kept for the CPU/elapsed ratio. +ELAPSED_RE = re.compile(r"Elapsed time: (?:(\d+):)?(\d+):(\d+)(\.\d+)?\[h:\]min:sec") + +# The CPU time run_command.py emits on the same line, as user and sys +# seconds; reported as their sum. +CPU_RE = re.compile(r"CPU time: user (\d+(?:\.\d+)?) sys (\d+(?:\.\d+)?)") def get_hashes(f): @@ -65,13 +70,18 @@ def get_hashes(f): def print_log_dir_times(logdir, args): first = True totalElapsed = 0 + totalCpu = 0.0 + # Elapsed time of only the steps that report CPU time, so the total + # CPU/elapsed ratio isn't diluted by steps without it. + totalCpuElapsed = 0.0 total_max_memory = 0 if not args.match: print(logdir) # Loop on all log files in the directory for f in sorted(pathlib.Path(logdir).glob("**/*.log")): - if any(x in str(f) for x in ["eqy_output", "rsz_lec_check"]): + # kepler-formal's own logs; its timing is in ${step}_lec/_sec.log + if any(x in str(f) for x in ["eqy_output", "_lec_check", "_sec_check"]): continue # Extract Elapsed Time line from log file stem = os.path.splitext(os.path.basename(str(f)))[0] @@ -81,6 +91,8 @@ def print_log_dir_times(logdir, args): found = False for line in logfile: elapsedTime = None + elapsedFraction = 0.0 + cpuTime = None peak_memory = None # Example line: @@ -91,8 +103,10 @@ def print_log_dir_times(logdir, args): # so anything the line is prefixed with is ignored. timeMatch = ELAPSED_RE.search(line) if timeMatch: - hours, minutes, seconds = timeMatch.groups() + hours, minutes, seconds, fraction = timeMatch.groups() # Any fraction of a second is dropped. + if fraction: + elapsedFraction = float(fraction) elapsedTime = int(minutes) * 60 + int(seconds) if hours is not None: elapsedTime += int(hours) * 3600 @@ -100,6 +114,9 @@ def print_log_dir_times(logdir, args): print( "Elapsed time not understood in", str(line), file=sys.stderr ) + cpuMatch = CPU_RE.search(line) + if cpuMatch: + cpuTime = float(cpuMatch.group(1)) + float(cpuMatch.group(2)) # Find Peak Memory peak_memory = int( int(line.split("Peak memory: ")[1].split("KB")[0]) / 1024 @@ -114,41 +131,64 @@ def print_log_dir_times(logdir, args): # Print the name of the step and the corresponding elapsed time. # One row per (stage, result-file-ext); only the first row of a - # stage shows elapsed/peak. - format_str = "%-25s %-6s %10s %14s %20s" + # stage shows elapsed/cpu/peak. if elapsedTime is not None and peak_memory is not None: if first and not args.noHeader: - print( - format_str - % ( - "Log", - "Ext", - "Elapsed/s", - "Peak Memory/MB", - "sha1sum result [0:20)", - ) - ) + print_header() first = False stage_first = True for ext, h in hashes: - print( - format_str - % ( - stem, - ext, - elapsedTime if stage_first else "", - peak_memory if stage_first else "", - h[0:20], - ) - ) + if stage_first: + if cpuTime is None: + cpu = "N/A" + else: + cpu = round(cpuTime) + ratio = cpu_ratio(cpuTime, elapsedTime + elapsedFraction) + print_row(stem, ext, elapsedTime, cpu, ratio, peak_memory, h[0:10]) + else: + print_row(stem, ext, "", "", "", "", h[0:10]) stage_first = False - if elapsedTime is not None: + # LEC/SEC run inside another step (e.g. 6_report), which already + # counts their time. + nested = stem.endswith(("_lec", "_sec")) + if elapsedTime is not None and not nested: totalElapsed += elapsedTime + if cpuTime is not None and elapsedTime is not None and not nested: + totalCpu += cpuTime + totalCpuElapsed += elapsedTime + elapsedFraction if peak_memory is not None: total_max_memory = max(total_max_memory, int(peak_memory)) if totalElapsed != 0 and not args.match: - print(format_str % ("Total", "", totalElapsed, total_max_memory, "")) + print_row( + "Total", + "", + totalElapsed, + round(totalCpu), + cpu_ratio(totalCpu, totalCpuElapsed), + total_max_memory, + "", + ) + + +def cpu_ratio(cpu, elapsed): + """CPU time over elapsed time: roughly the number of busy threads.""" + if cpu is None or not elapsed: + return "N/A" + return "%.2f" % (cpu / elapsed) + + +def print_header(): + """Print the column headers, split over two lines to keep the + columns narrow.""" + print_row("Log", "Ext", "Elapsed", "CPU", "CPU/", "Peak Mem", "sha1sum") + print_row("", "", "s", "s", "Elapsed", "MB", "[0:10)") + + +def print_row(log, ext, elapsed, cpu, ratio, memory, sha): + fmt = "%-22s %-6s %8s %8s %8s %8s %s" + row = fmt % (log, ext, elapsed, cpu, ratio, memory, sha) + print(row.rstrip()) def scan_logs(args): diff --git a/flow/util/uploadMetadata.py b/flow/util/uploadMetadata.py index b7a49c27f3..cafb806554 100755 --- a/flow/util/uploadMetadata.py +++ b/flow/util/uploadMetadata.py @@ -4,6 +4,7 @@ import argparse import os import sys +from datetime import datetime, timezone # --- PUBSUB --- from google.cloud import pubsub_v1 @@ -52,6 +53,45 @@ "pinned commit rather than the built one. When supplied alongside " "--jobName the payload is emitted as schema v4.", ) +parser.add_argument( + "--buildTime", + type=str, + default=None, + help="When the build ran, emitted as build_time on the pipeline payload. " + "Defaults to now in UTC, in the format genMetrics.py uses for " + "run__flow__generate_date (%%Y-%%m-%%d %%H:%%M). The backend reads it " + "as UTC.", +) +parser.add_argument( + "--expectedDesigns", + type=int, + default=None, + help="Number of designs the pipeline set out to build. When set, emitted " + "as design_count on the pipeline payload so the backend can tell a build " + "that produced fewer (or no) metrics from one that built fewer designs.", +) +parser.add_argument( + "--noMetricsReason", + type=str, + default=None, + help="Why no design produced metrics. Emitted as no_metrics_reason only " + "on a payload with no designs.", +) +parser.add_argument( + "--buildUserEmail", + type=str, + default=None, + help="Email of the Jenkins user who started the build by hand " + "(BUILD_USER_EMAIL). Omitted for SCM, timer and branch-scan triggers. " + "The dashboard attributes the build to this user.", +) +parser.add_argument( + "--changeAuthorEmail", + type=str, + default=None, + help="Email of the pull request's author on a PR build " + "(CHANGE_AUTHOR_EMAIL). Empty when the author's GitHub email is private.", +) # --- PUBSUB args --- parser.add_argument( @@ -194,6 +234,34 @@ def resolve_schema_version(args, provenance): return 4 if provenance else 3 +def resolve_build_time(args): + """The build time to report, defaulting to now in genMetrics.py's format. + + The default is UTC because the backend reads the value as UTC; local time + would shift the build by the agent's offset wherever that is not UTC. + """ + if args.buildTime and args.buildTime.strip(): + return args.buildTime.strip() + return datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M") + + +def resolve_requester(args): + """Who asked for the build, as the payload keys the backend reads. + + Blank values are left out rather than sent empty. The keys ride on every + schema version: the backend reads them by presence, and they describe the + build rather than the payload's shape, so they do not bump the version. + """ + requester = {} + for key, value in ( + ("build_user_email", args.buildUserEmail), + ("change_author_email", args.changeAuthorEmail), + ): + if value and value.strip(): + requester[key] = value.strip() + return requester + + def build_pipeline_payload(design_records, args, provenance=None): """Return the pipeline-level payload dict. @@ -211,16 +279,25 @@ def build_pipeline_payload(design_records, args, provenance=None): "change_branch": args.changeBranch, "commit_sha": args.commitSHA, "jenkins_url": args.jenkinsURL, + "build_time": resolve_build_time(args), "designs": design_records, } if job_name: payload["job_name"] = job_name + if args.expectedDesigns is not None: + payload["design_count"] = args.expectedDesigns + # A reason only describes a build that produced nothing; on a payload with + # designs it would contradict the metrics it carries. + reason = args.noMetricsReason.strip() if args.noMetricsReason else "" + if not design_records and reason: + payload["no_metrics_reason"] = reason # Only a v4 payload carries provenance. Provenance without a job name cannot # be v4 (the backend requires job_name from v3 up), and attaching v4 keys to # a message labelled v2 would make payload_schema_version stop describing # the payload. if schema_version == 4: payload.update(provenance) + payload.update(resolve_requester(args)) return payload @@ -260,8 +337,14 @@ def publish_v1_per_design(publisher, topic_path, design_records, args, provenanc requirement: a v1 message declares no schema version, so there is nothing for the extra keys to contradict, and the backend reads provenance here by key presence rather than by version. + + build_time, design_count and no_metrics_reason are left off: the backend + reads every v1 root key it does not list as metadata as a metric, so new + root keys here would surface as bogus metrics. An empty build never gets + here anyway; its payload is far below the size cap. """ futures = [] + requester = resolve_requester(args) failed = 0 for d in design_records: payload = { @@ -275,6 +358,7 @@ def publish_v1_per_design(publisher, topic_path, design_records, args, provenanc } if provenance: payload.update(provenance) + payload.update(requester) payload.update(d["metrics"]) message_data = json.dumps(payload, default=str).encode("utf-8") @@ -361,7 +445,16 @@ def publish_v1_per_design(publisher, topic_path, design_records, args, provenanc # A failed publish exits non-zero. A warning alone let CI builds pass while the # QoR dashboard stopped receiving results, which froze the baseline that later # builds are compared against. -if publisher and design_records: +# +# A build where no design produced metrics still publishes, with an empty +# designs list, so the dashboard lists it as a build without metrics instead of +# leaving it out. +if publisher: + if not design_records: + print( + "[INFO] No design records were collected. Publishing an empty " + "(no-metrics) pipeline report." + ) provenance = load_provenance(args.provenanceFile) payload = build_pipeline_payload(design_records, args, provenance) message_data = json.dumps(payload, default=str).encode("utf-8") @@ -393,6 +486,6 @@ def publish_v1_per_design(publisher, topic_path, design_records, args, provenanc except Exception as e: print(f"[ERROR] Pub/Sub publish failed for pipeline report: {e}") sys.exit(1) -elif publisher and not design_records: - print("[WARN] Pub/Sub publisher initialized but no design records were collected.") + if not design_records: + print("[INFO] Published an empty (no-metrics) pipeline report.") # --- END PUBSUB --- diff --git a/flow/util/utils.mk b/flow/util/utils.mk index 195db144af..ca3865e2b0 100644 --- a/flow/util/utils.mk +++ b/flow/util/utils.mk @@ -27,11 +27,13 @@ metadata-generate: -o $(REPORTS_DIR)/metadata.json 2>&1 \ | tee $(abspath $(REPORTS_DIR)/metadata-generate.log) -# The QoR gate: metadata.json against the latest master build on the QoR -# dashboard, using the dashboard's rule configs. Set DASHBOARD_API_KEY for -# a private platform and DASHBOARD_JOB_NAME when the baseline pipeline is -# not OpenROAD-flow-scripts-Public. A failed rule fails the target; an -# unreachable dashboard or a design without a baseline only warns. +# The QoR gate: metadata.json against the QoR dashboard's baseline for the +# commit it records (the master build at its merge base, from the first of +# the dashboard's default pipelines that has the design), using the +# dashboard's rule configs. Set DASHBOARD_API_KEY for a private platform and +# DASHBOARD_JOB_NAME to check as a build of one pipeline instead. A failed +# rule fails the target; an unreachable dashboard or a design without a +# baseline only warns. .PHONY: metadata-check metadata-check: $(PYTHON_EXE) $(UTILS_DIR)/checkQorMetrics.py \ diff --git a/jenkins/public_tests_all.Jenkinsfile b/jenkins/public_tests_all.Jenkinsfile deleted file mode 120000 index 46074c1231..0000000000 --- a/jenkins/public_tests_all.Jenkinsfile +++ /dev/null @@ -1 +0,0 @@ -../Jenkinsfile \ No newline at end of file