[doc] Can we publish a table with current using tools and their versions?

[cindychip]

I wonder if the policy allows us to publish the current tools and versions we are using, so others can use our chip with the supported tools and correct versions. I was thinking about publishing this in a table format on our website. For example:

1. VCS : Simulation: version
2. Xcelium: Simulation: version
3. JasperGold: Formal: version
4. Lint.... etc.

[tjaychen]

yeah that sounds really good to me. Even if others cant use the exact same version, they'll at least know what the project is running with if they observe differences.

[msfschaffner]

That's a great idea!

Should we place this onto our HW dashboard? https://docs.opentitan.org/hw/

Or should it go deeper in the docs? I remember we talk about tool selections somewhere in the design / dv methodology docs...

[cindychip]

That's a great idea!

Should we place this onto our HW dashboard? https://docs.opentitan.org/hw/

Or should it go deeper in the docs? I remember we talk about tool selections somewhere in the design / dv methodology docs...

I think a table on HW dashboard would be sufficient! Shall we also include SW tools?

[msfschaffner]

I think so. One other thing to note: we already have something like a versions file: https://github.com/lowRISC/opentitan/blob/master/tool_requirements.py

this is used by some fusesoc scripts, but not all of them.

I wonder whether we can consolidate this somehow - given that bazel is going to ensure certain versions of tools are being checked out.

What would be really confusing is if we had 3 or more different sources for tool versions in our public docs. Ideally it sould be one file (hjson or other machine readable format) that serves as the source of truth for all publicly visible docs / tool flows.

For some of the docs this is done with the file mentioned above, see for instance here: https://github.com/lowRISC/opentitan/blob/5b0733bf6688c70548a5ef9bf3bfeb16dc08aa36/doc/getting_started/_index.md?plain=1#L192-L195

CC @timothytrippel

[timothytrippel]

For the SW tools, the end goal is to be able to have Bazel manage all required tools. However, we are still not there yet, so right now there is a hybrid approach of how we install SW tools. Specifically:

1. some software dependencies are completely managed by Bazel, meaning Bazel will go out to the Internet and pull down a tarball from a specific URL and unpack it, etc. These software depedencies are described in .bzl files under third_party/. Some examples of such are the Python toolchain and pip packages (though Bazel loads these from the python-requirements.txt file we define), the Rust toolchain and Rust crates, etc.

2. other SW dependencies (that are not yet managed by Bazel) are required to be installed on your system, and Bazel just picks up whatever is installed. One example of such is the srec_cat tool we use to generate VMEM files of SW binaries for loading into simulations. These dependencies are described in the website here under steps 0--3 (and step 5 if you want to run tests on Verilator or FPGA). Some of these installation guide steps reference installing packages (with a package manager) we describe in apt-requirements.txt / yum-requirements.txt (depending if your system is Ubuntu/Debian or RHEL/CentOS). We currently don't pin versions for these packages, rather on the website we state: "Our continuous integration setup runs on Ubuntu 18.04 LTS, which gives us the most confidence that this distribution works out of the box. We do our best to support other distributions, but cannot guarantee they can be used “out of the box” and might require updates of packages." So basically, we officially support the default package versions for Ubuntu 18.04. Other installation guide steps reference installing software through other means, e.g., building from source (Verilator). For this SW we document versions in the installation guides themselves, or in the tool_requirements.py file.

Sorry for the long-winded response, but hopefully that sheds some light on the current state of things.

[timothytrippel]

Overall though, I think it is a great idea to have a table describing the exact versions for each package / SW tool to consolidate the information all in one place.

I also think it would be great if we pinned the versions of package manager installed packages the {apt,yum}-requirments.txt files, rather than just relying on the default versions for Ubuntu 18.04.

It's worth noting that in the SW WG this week @mundaym mentioned we might be moving CI to Ubuntu 20.XX. So perhaps we could pin package versions as a part of that update process (if the update is happening).

[tjaychen]

@timothytrippel this is a dumb question, but is it possible that some of partners may have systems where they don't allow bazel to out into the world and pull down the required tools? In that scenario, I guess similar to our ai-rgapped setup, wouldn't it still be good for them to know what to look for?

[timothytrippel]

Yeah thats right, in that scenario, the bazel configurations will tell you where to look, but it would still be better to have it documented in some place. Additionally, for the airgapped world, we do have a script util/prep-bazel-airgapped-build.sh that will automatically build a directory with all proper SW deps that can be moved directly to the airgapped machine, provided you have access to an internet-connected machine. Additionally there is documentation describing all of this that has been floating around it just needs to be moved to the website. I filed #13777 to track this.