Skip to content

Commit

Permalink
README: Update the usage instructions
Browse files Browse the repository at this point in the history 
Signed-off-by: Pawel Czarnecki <[email protected]>
  • Loading branch information
@lpawelcz
lpawelcz committed Apr 17, 2024
1 parent 074deb0 commit 12e3ae2
Showing 1 changed file with 163 additions and 82 deletions.
245 changes: 163 additions & 82 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@ Challenges with large designs and ORFS that Bazel helps address

- **Long build times**; hours, days.
- **Artifacts** are needed. Synthesis, for instance, can
be very time consuming and and it is useful to share synthesis artifacts
be very time consuming and it is useful to share synthesis artifacts
between developers and CI servers. On a large design with multiple
developers and many pull requests in flight, it can become error
prone to manually track exactly what version of built stages that
Expand All @@ -61,7 +61,7 @@ Challenges with large designs and ORFS that Bazel helps address
always existed for detailed routing: detailed routing succeeds, has exit code 0,
even if there are DRC errors.
- **Mocking abstracts** when doing initial top-level floorplanning is needed to
seperate concerns. It can be useful to skip one of place, cts, route for
separate concerns. It can be useful to skip one of place, cts, route for
the macros until one starts to converge on a workable
top level floorplan. This is supported via `mock_abstract` in `openroad.bzl`
- **Efficient local storage of build artifacts** are needed as .odb files are
Expand All @@ -86,13 +86,53 @@ Challenges with large designs and ORFS that Bazel helps address
Setup
-----

This setup intentionally does not treat ORFS as a installable versioned tool,
but prefers to rely on ~/OpenROAD-flow-scripts such that it is easy to hack
ORFS and OpenROAD.

- Clone and build OpenROAD-flow-scripts into ~/OpenROAD-flow-scripts. The `./orfs`
script in this example assumes this location.
- Install Bazel and Bazelisk https://github.com/bazelbuild/bazelisk
For running bazel flow for the ORFS, megaboom uses [bazel-orfs](https://github.com/The-OpenROAD-Project/bazel-orfs).
It provides two different bazel flows for running Physical Design flow with [OpenROAD-flow-scripts](https://github.com/The-OpenROAD-Project/OpenROAD-flow-scripts).
For the installation and usage guide, please refer to [bazel-orfs's README](https://github.com/The-OpenROAD-Project/bazel-orfs/blob/main/README.md).

`bazel-orfs` must be specified in megaboom as the external dependency.
It can be pinned to a specific revision of [the upstream repository](https://github.com/The-OpenROAD-Project/bazel-orfs) or the dependency can point to a local bazel-orfs workspace available on disk.

### Upstream repository

In `MODULE.bazel` use [git_override](https://bazel.build/rules/lib/globals/module#git_override) to pin `bazel-orfs` version at specific commit:

```
git_override(
module_name = "bazel-orfs",
remote = "https://github.com/The-OpenROAD-Project/bazel-orfs.git",
commit = "<commit hash>",
)
```

### Local workspace

For testing changes made to `bazel-orfs` it is useful to set the dependency to a local bazel-orfs workspace.
In order to do that, in `MODULE.bazel` use [local_path_override](https://bazel.build/rules/lib/globals/module#local_path_override):

```
local_path_override(
module_name = "bazel-orfs", path = "<path to local bazel-orfs workspace>"
)
```

For the local `bazel-orfs` it is also required to mount the `bazel-orfs` workspace directory to the docker containers while using the `docker flow`.
In your local `bazel-orfs` apply the changes showcased by the diff:

```
diff --git a/docker_shell.sh b/docker_shell.sh
index db1673c..f933d6a 100755
--- a/docker_shell.sh
+++ b/docker_shell.sh
@@ -83,6 +83,7 @@ docker run --name "bazel-orfs-$uid" --rm \
-e WORK_HOME=$WORKSPACE_EXECROOT/$RULEDIR \
-v $WORKSPACE_ROOT:$WORKSPACE_ROOT \
-v $WORKSPACE_ORIGIN:$WORKSPACE_ORIGIN \
+ -v <path to local bazel-orfs directory>:<path to local bazel-orfs directory> \
--network host \
$DOCKER_INTERACTIVE \
$DOCKER_ARGS \
```

Example of using a Bazel artifact server
----------------------------------------
Expand All @@ -116,8 +156,8 @@ To use this feature, copy the snippet below into `.bazelrc` and specify your use
**NOTE:** To test the credential helper, make sure to restart Bazel to avoid using a previous
cached authorization:

bazelisk shutdown
bazelisk build ALUExeUnit_floorplan
bazel shutdown
bazel build ALUExeUnit_floorplan


To gain access to the https://storage.googleapis.com/megaboom-bazel-artifacts bucket,
Expand All @@ -126,16 +166,36 @@ reach out to Tom Spyrou, Precision Innovations (https://www.linkedin.com/in/toms
Tutorial
========

This tutorial uses the `docker flow` to run the physical design flow with ORFS.
Before starting, it is required to have available in your docker runtime a docker image with `OpenROAD-flow-scripts` installation.
For more information, please refer to the [Requirements](https://github.com/The-OpenROAD-Project/bazel-orfs?tab=readme-ov-file#requirements) chapter of `bazel-orfs`.

---

**Note:**
`orfs_env` rule for downloading and loading the docker image is defined in `bazel-orfs`.
In order to run it in the context of megaboom (the workspace that uses `bazel-orfs` as external dependency), it is required to use correct bazel label to this external target:

```
bazel run @bazel-orfs//:orfs_env
```

---

Hello world
-----------

A quick test-build of Bazel:

bazelisk build L1MetadataArray_test_generate_abstract
```
bazel build L1MetadataArray_test_cts
```

Viewing results from Bazel:

./orfs make DESIGN_NAME=L1MetadataArray gui_final
```
bazel run L1MetadataArray_test_cts_gui
```

Tweaking aspect ratio of a floorplan
------------------------------------
Expand All @@ -152,75 +212,76 @@ Also, notice that when the aspect ratio is changed back to
a value for which there exists artifacts, Bazel completes
instantaneously as the artifact already exists:

--- a/BUILD.bazel
+++ b/BUILD.bazel
@@ -165,7 +165,7 @@ exeunitsrc = [ "rtl/ALU.sv",
stage_args={
'floorplan': ['CORE_UTILIZATION=5',
- 'CORE_ASPECT_RATIO=8',
+ 'CORE_ASPECT_RATIO=6',
"RTLMP_FLOW=True"],
'place': ['PLACE_DENSITY=0.2000'],
```
diff --git a/BUILD.bazel b/BUILD.bazel
index 9e2e7b4..e8d5502 100644
--- a/BUILD.bazel
+++ b/BUILD.bazel
@@ -539,7 +539,7 @@ exeunitsrc = [ "rtl/ALU.sv",
sdc_constraints = ":constraints.sdc",
stage_args={
'floorplan': ['CORE_UTILIZATION=5',
- 'CORE_ASPECT_RATIO=8',
+ 'CORE_ASPECT_RATIO=6',
"RTLMP_FLOW=True"],
'place': ['PLACE_DENSITY=0.2000'],
'route': ['BLAH=6']
```

Then run a quick test-build Bazel:

bazelisk build ALUExeUnit_floorplan
```
bazel build ALUExeUnit_floorplan
```

Viewing final results from Bazel:

./orfs make DESIGN_NAME=ALUExeUnit gui_floorplan

Creating an issue report
------------------------

This is slightly tricky because we need find and use the variables Bazel passed to
ORFS on the command line.

The TL;DR to create a floorplan.tcl issue is:

bazelisk build L1MetadataArray_test_floorplan_orfs
cat bazel-bin/logs/asap7/L1MetadataArray/test/floorplan.txt

This shows the ORFS make command line, after which the normal make
targets for floorplanning is appended:

./orfs make DESIGN_NAME=L1MetadataArray RTLMP_FLOW=True ... DESIGN_CONFIG=config.mk

Next run:

./orfs make DESIGN_NAME=L1MetadataArray ... floorplan_issue
```
bazel build ALUExeUnit_floorplan_gui
```

Fast floorplanning and mock abstracts
-------------------------------------

Let's say we want to skip place, cts and route and create a mock abstract where
we can at least check that there is enough place for the macros at the top level.

Warning! Although mock abstracts can speed up turnaround times, skipping
place, cts or route can lead to errors and problems that don't exist when place, cts and route are not skipped.
---

**Warning:**
Although mock abstracts can speed up turnaround times, skipping place, cts or route can lead to errors and problems that don't exist when place, cts and route are not skipped.

To do so, we modify `BUILD.bzl`:
---

--- a/BUILD.bazel
+++ b/BUILD.bazel
@@ -566,7 +566,7 @@ build_openroad(
'place': ['PLACE_DENSITY=0.20', 'PLACE_PINS_ARGS=-annealing'],
},
mock_abstract=True,
- mock_stage="grt"
+ mock_stage="floorplan"
)
To do so, we modify in `BUILD.bazel` the `mock_stage` attribute of `build_openroad` macro to `floorplan` stage:

```
diff --git a/BUILD.bazel b/BUILD.bazel
index 9e2e7b4..f692f7f 100644
--- a/BUILD.bazel
+++ b/BUILD.bazel
@@ -860,7 +860,7 @@ build_openroad(
'place': ['PLACE_DENSITY=0.20', 'PLACE_PINS_ARGS=-annealing'],
},
mock_abstract=True,
- mock_stage='cts'
+ mock_stage='floorplan'
)
```

Then run:

bazelisk build L1MetadataArray_test_generate_abstract
```
bazel build L1MetadataArray_test_generate_abstract
```

This will cause the `mock area` targets to generate the abstracts for the design right after the `floorplan` stage.
For more information please refer to the description of [mock area targets](https://github.com/The-OpenROAD-Project/bazel-orfs?tab=readme-ov-file#mock-area-targets).


Tentative roadmap
=================

- Break out Bazel support into a orfs_rules project that can be imported from example
projects such as this megaboom example. Perhaps orfs_rules could be hosted inside the ORFS
repository, or perhaps it should be a standalone repository.
- ORFS and orfs_rules should be independently versioned dependencies
while it should still be easy to do local hacking of ORFS. There should be a version
number for the ORFS dependency and orfs_rules separately. It should be possible to
Expand All @@ -238,7 +299,9 @@ Bazel hacking
Run all synth targets
---------------------

bazelisk build $(bazelisk query '...:*' | grep '_synth$')
```
bazel build $(bazel query '...:*' | grep '_synth$')
```

Forcing a rebuild of a stage
----------------------------
Expand All @@ -247,53 +310,71 @@ Sometimes it is desirable, such as when hacking ORFS, to redo a build stage even
if none of the dependencies for that stage changed. This can be achieved by changing
a `PHONY` variable to that stage and bumping it:

--- a/BUILD.bazel
+++ b/BUILD.bazel
@@ -166,7 +166,8 @@ exeunitsrc = [ "rtl/ALU.sv",
stage_args={
'floorplan': ['CORE_UTILIZATION=5',
'CORE_ASPECT_RATIO=8',
- "RTLMP_FLOW=True"],
+ "RTLMP_FLOW=True",
+ 'PHONY=1'],
```
diff --git a/BUILD.bazel b/BUILD.bazel
index 9e2e7b4..6ea1f29 100644
--- a/BUILD.bazel
+++ b/BUILD.bazel
@@ -540,7 +540,8 @@ exeunitsrc = [ "rtl/ALU.sv",
stage_args={
'floorplan': ['CORE_UTILIZATION=5',
'CORE_ASPECT_RATIO=8',
- "RTLMP_FLOW=True"],
+ "RTLMP_FLOW=True",
+ 'PHONY=1'],
'place': ['PLACE_DENSITY=0.2000'],
'route': ['BLAH=6']
}
```

Staring at logs
---------------

This is surprisingly tricky, you have to go spelunking in ~/.cache/bazel/.

In ORFS it is oftentimes useful to view the tail of the single running
stage on a machine, `./out` is in this project to "stare at logs":

tail -f $(./out -t)
```
tail -f $(./out -t)
```

Currently, this script depends on bazel cache residing under `~/.cache/bazel/`.
This directory is scanned for the newest log file which name of gets printed to the standard output.

Downloading the immediate dependencies of a target
Building the immediate dependencies of a target
--------------------------------------------------

bazelisk build $(bazelisk query 'deps(ChipTop_synth, 1)' --noimplicit_deps)
```
bazel build $(bazel query 'deps(<target label e.g. ChipTop_synth>, 1)' --noimplicit_deps)
```

MegaBoom RTL code
=================

Based on: https://chipyard.readthedocs.io/en/stable/VLSI/Sky130-OpenROAD-Tutorial.html#initial-setup

NOTE! Chipyard main does not work smoothly with MegaBoom as of writing as
Chipyard is mixing SFC and MFC.
```
**Note:** Chipyard main does not work smoothly with MegaBoom as of writing as Chipyard is mixing SFC and MFC.
```

Follow https://github.com/ucb-bar/chipyard/issues/1623 for latest updates.

That said, the rtl/ folder was generated using latest Chipyard + some hacked
files locally:
That said, the `rtl/` folder was generated using latest Chipyard + some hacked files locally:

make tutorial=sky130-openroad CONFIG=MegaBoomMacroConfig verilog
```
make tutorial=sky130-openroad CONFIG=MegaBoomMacroConfig verilog
```

Hammer hacking with ASAP7
=========================

Build everything:

./build-setup.sh --skip-ctags --skip-conda --skip-toolchain --skip-firesim --skip-marshal --skip-clean
```
./build-setup.sh --skip-ctags --skip-conda --skip-toolchain --skip-firesim --skip-marshal --skip-clean
```

Create Verilog code:

make CONFIG=MegaBoomConfig tech_name=asap7 VLSI_TOP=ChipTop INPUT_CONFS=example-asap7.yml TOP_MACROCOMPILER_MODE='--mode synflops' verilog
```
make CONFIG=MegaBoomConfig tech_name=asap7 VLSI_TOP=ChipTop INPUT_CONFS=example-asap7.yml TOP_MACROCOMPILER_MODE='--mode synflops' verilog
```

0 comments on commit 12e3ae2

Please sign in to comment.