Streamline the local hardening instructions

[ccattuto]

Added documentation on using volare to install the Sky130 PDK and re-organized the flow of the document.

[urish]

@htfab can you please review?

[ccattuto]

PS: if you're OK with this revised structure, then we should also document the need to set up GITHUB_TOKEN, and the need to have a container manager running (e.g., Docker).

[dlmiles]

Thanks @ccattuto

FWIW the PDK version hash is probably out of date now (if copied from discord). Probably wants a link on where to look in the action for the current recommended PDK version, like there the other items on the page..

[ccattuto]

FWIW the PDK version hash is probably out of date now (if copied from discord). Probably wants a link on where to look in the action for the current recommended PDK version, like there the other items on the page..

Done. And added info about the GitHub token and Docker. Also updated to tt09.

[htfab]

@htfab can you please review?

I like the general reorganization and updating to tt09, and mentioning Docker is a good idea, but the volare part doesn't correspond to what we do in the action.

In the action (and in the current version of this local hardening document) we install a specific version of the openlane2 python package and run it with the --dockerized option (from within ./tt/tt_tool.py --harden --openlane2). This fetches the openlane2 docker package and runs openlane2 inside it, with access to some host directories.

Openlane2 calls volare (which is already installed in the container so we don't need to install it on the host) and asks for a version of the pdk specified by the file openlane/open_pdks_rev in the openlane2 sources (which is thus pinned to the particular openlane version). It is installed in your host's ~/.volare directory so it persists between hardening runs, but it's not set as the default so it shouldn't affect the PDK configuration you might have set up on your host independently.

Running the local flow should work without installing volare and setting PDK_VERSION or GITHUB_TOKEN. I just tested it on a new machine. Did you get some errors while trying to run the flow without them?

[ccattuto]

@htfab can you please review?

I like the general reorganization and updating to tt09, and mentioning Docker is a good idea, but the volare part doesn't correspond to what we do in the action.

In the action (and in the current version of this local hardening document) we install a specific version of the openlane2 python package and run it with the --dockerized option (from within ./tt/tt_tool.py --harden --openlane2). This fetches the openlane2 docker package and runs openlane2 inside it, with access to some host directories.

Openlane2 calls volare (which is already installed in the container so we don't need to install it on the host) and asks for a version of the pdk specified by the file openlane/open_pdks_rev in the openlane2 sources (which is thus pinned to the particular openlane version). It is installed in your host's ~/.volare directory so it persists between hardening runs, but it's not set as the default so it shouldn't affect the PDK configuration you might have set up on your host independently.

Running the local flow should work without installing volare and setting PDK_VERSION or GITHUB_TOKEN. I just tested it on a new machine. Did you get some errors while trying to run the flow without them?

I can't run the local flow - as described in the original documentation - without installing a PDK first, and running volare locally requires a GITHUB_TOKEN. I followed the pointers I received on Discord until things worked for me, but I do not know whether that's the way they're meant to work. For sure the original documentation was incomplete and not usable, at least for me. So this might be just a starting point to maybe improve it.

[htfab]

Ah ok, so the error doesn't happen when hardening but when running the GL tests. And the reason for that is that the dockerized version of openlane2 installs the PDK into ~/.volare/volare/sky130/ and not into $PDK_ROOT, i.e. ~/ttsetup/pdk/. And we didn't catch it because if you ever did a local hardening with openlane1 you still have the PDK under ~/ttsetup/pdk. So this is either a bug with tt-support-tools or with openlane2, I'll figure it out. In the short term symlinking ~/.volare/volare/sky130/versions/bdc9412b3e468c102d01b7cf6337be06ec6e9c9a to ~/ttsetup/pdk should be enough to make everything in the current version of the document work.

[urish]

I just encountered a similar issue with tinytapeout-08-sources, and used the following workaround (after running OL2 for the first time):

export PDK_VERSION=$(cat runs/wokwi/PDK_SOURCES | awk '{print $2}')
volare enable $PDK_VERSION

It creates the require symlink (without reinstalling the PDK), assuming PDK_ROOT is unset (or set to ~/.volare).

[ccattuto]

Ah ok, so the error doesn't happen when hardening but when running the GL tests.

Indeed.

In the short term symlinking ~/.volare/volare/sky130/versions/bdc9412b3e468c102d01b7cf6337be06ec6e9c9a to ~/ttsetup/pdk should be enough to make everything in the current version of the document work.

I'll try that and update the PR accordingly.

[htfab]

Ok, so openlane2 doesn't respect PDK_ROOT in the environment but has a --pdk-root switch. Adding it to the command line in project.py makes it install the PDK in the expected place. We still need a volare enable to have the symlink from $PDK_ROOT/sky130A to $PDK_ROOT/volare/sky130/versions/$PDK_VERSION/sky130A. Apparently volare is already installed on the host as well as it's a dependency of openlane so we can just add another line to project.py.

[htfab]

Pushed an update to tt-support-tools and tested the flow on a fresh machine, it should now work including the GL tests. (Make sure you use the tt09 branch.)

[urish]

Thanks!