[doc] Update lint documentation
Signed-off-by: Michael Schaffner <msf@opentitan.org>
diff --git a/doc/ug/design.md b/doc/ug/design.md
index d6389d2..d4e537c 100644
--- a/doc/ug/design.md
+++ b/doc/ug/design.md
@@ -69,9 +69,11 @@
Running lint is especially useful with SystemVerilog, a weakly-typed language, unlike more modern hardware description languages.
Running lint is faster than running a simulation.
-We have standardized on the [AscentLint](https://www.realintent.com/rtl-linting-ascent-lint/) tool from RealIntent for this task due to its fast run-times and comprehensive set of rules that provide concise error and warning messages.
+### Sign-off Linting using AscentLint
-The lint flow leverages a new lint rule policy named _"lowRISC Lint Rules"_ that has been tailored towards our [Verilog Style Guide](https://github.com/lowRISC/style-guides/blob/master/VerilogCodingStyle.md).
+For sign-off we have standardized on the [AscentLint](https://www.realintent.com/rtl-linting-ascent-lint/) tool from RealIntent for this task due to its fast run-times and comprehensive set of rules that provide concise error and warning messages.
+
+The sign-off lint flow leverages a new lint rule policy named _"lowRISC Lint Rules"_ that has been tailored towards our [Verilog Style Guide](https://github.com/lowRISC/style-guides/blob/master/VerilogCodingStyle.md).
The lint flow run scripts and waiver files are available in the GitHub repository of this project, but due to the proprietary nature of the lint rules and their configuration, the _"lowRISC Lint Rules"_ lint policy file can not be publicly provided.
However, the _"lowRISC Lint Rules"_ are available as part of the default policies in AscentLint release 2019.A.p3 or newer (as `LRLR-v1.0.policy`).
This enables designers that have access to this tool to run the lint flow provided locally on their premises.
@@ -87,6 +89,18 @@
Goals for linting closure per design milestone are given in the [OpenTitan Development Stages]({{< relref "doc/project/development_stages" >}}) document.
+### Style Linting using Verible
+
+In order to complement the sign-off lint flow explained above, we also leverage the Verible style linter, which captures different aspects of the code and detects style elements that are in violation with our [Verilog Style Guide](https://github.com/lowRISC/style-guides/blob/master/VerilogCodingStyle.md).
+
+The tool is open source and freely available on the [Verible GitHub page](https://github.com/google/verible/).
+Hence, the recommendation for IP designers is to install the tool as described [here]({{< relref "doc/ug/install_instructions" >}}) and in the [Lint Flow README]({{< relref "hw/lint/doc/README.md" >}}), and use the flow locally to close the errors and warnings.
+
+Note, however, that we do not have a waiver strategy in place yet.
+Until that is the case, the recommendation is to use good judgment and fix all violations that can be addressed without too much effort.
+
+Similarly to the sign-off flow, all designs with enabled Verible lint targets will be run through the tool in eight-hour intervals and the results are published as part of the tool dashboards on the [hardware IP overview page](https://docs.opentitan.org/hw), enabling designers to close the lint errors and warnings even if they cannot run the sign-off tool locally.
+
## Assertion Methodology
The creation and maintenance of assertions within RTL design code is an essential way to get feedback if a design is being used improperly.
diff --git a/doc/ug/install_instructions/index.md b/doc/ug/install_instructions/index.md
index d0d3188..c062c62 100644
--- a/doc/ug/install_instructions/index.md
+++ b/doc/ug/install_instructions/index.md
@@ -148,6 +148,34 @@
After installation you need to add `/tools/verilator/$VERILATOR_VERSION/bin` to your `PATH` environment variable.
+## Verible
+
+Verible is an open source SystemVerilog style linter and formatting tool.
+The style linter is relatively mature and we use it as part of our [RTL design flow]({{< relref "doc/ug/design" >}}).
+The formatter is still under active development, and hence its usage is more experimental in OpenTitan.
+
+You can download and build Verible from scratch as explained on the [Verible GitHub page](https://github.com/google/verible/).
+But since this requires the Bazel build system the recommendation is to download and install a pre-built binary as described below.
+
+### Install Verible
+
+Go to [this page](https://github.com/google/verible/releases) and download the correct binary archive for your machine.
+The example below is for Ubuntu-16.04:
+
+```console
+$ export VERIBLE_VERSION={{< tool_version "verible" >}}
+
+$ wget https://github.com/google/verible/releases/download/v${VERIBLE_VERSION}/verible-v${VERIBLE_VERSION}-Ubuntu-16.04-xenial-x86_64.tar.gz
+$ tar -xf verible-v${VERIBLE_VERSION}-Ubuntu-16.04-xenial-x86_64.tar.gz
+
+$ sudo mkdir -p /tools/verible/${VERIBLE_VERSION}/
+$ sudo mv verible-v${VERIBLE_VERSION}/* /tools/verible/${VERIBLE_VERSION}/
+```
+
+After installation you need to add `/tools/verible/$VERIBLE_VERSION/bin` to your `PATH` environment variable.
+
+Note that we currently use version {{< tool_version "verible" >}}, but it is expected that this version is going to be updated frequently, since the tool is under active develpment.
+
## Xilinx Vivado
### About Xilinx Vivado
diff --git a/hw/lint/doc/README.md b/hw/lint/doc/README.md
index a656e4e..9d5acc7 100644
--- a/hw/lint/doc/README.md
+++ b/hw/lint/doc/README.md
@@ -37,13 +37,19 @@
- lint/aes.waiver
file_type: waiver
+ files_veriblelint_waiver:
+ depend:
+ # common waivers
+ - lowrisc:lint:common
+ - lowrisc:lint:comportable
[...]
targets:
default: &default_target
filesets:
- - tool_verilator ? (files_verilator_waiver)
- - tool_ascentlint ? (files_ascentlint_waiver)
+ - tool_verilator ? (files_verilator_waiver)
+ - tool_ascentlint ? (files_ascentlint_waiver)
+ - tool_veriblelint ? (files_veriblelint_waiver)
- files_rtl
toplevel: aes
@@ -58,8 +64,10 @@
verilator_options:
- "-Wall"
```
-Note that the setup shown above also supports Verilator lint as a fall-back option that is open source.
-The same lint target is reused however for both AscentLint and Verilator (we override the tool selection when invoking FuseSoC).
+Note that the setup shown above also supports RTL style linting with the open source tool [Verible](https://github.com/google/verible/) and RTL linting with [Verilator](https://www.veripool.org/wiki/verilator) in order to complement the sign-off lint flow with AscentLint.
+In particular, Verible lint focuses on different aspects of the code, and detects style elements that are in violation with our [Verilog Style Guide](https://github.com/lowRISC/style-guides/blob/master/VerilogCodingStyle.md).
+
+The same lint target is reused for all three tools (we override the tool selection when invoking FuseSoC).
Lint waivers can be added to the flow by placing them in the corresponding waiver file.
In this example this would be `lint/aes.waiver` for AscentLint and `lint/aes.vlt` for Verilator.
@@ -79,8 +87,8 @@
In order to build all lint targets and produce a summary report, the `make all` target can be invoked.
For more detailed information on a particular lint run you can inspect the tool output inside the build folder that is created by FuseSoC.
-Note that all AscentLint targets have a Verilator counterpart that is suffixed with `_vlint` instead of `_lint`.
-This enables designers without access to AscentLint to iterate with an open-source tool before making their first Pull Request.
+Note that all AscentLint targets have a Verilator and Verible counterparts that are suffixed with `_vlint` and `_slint`, respectively.
+This enables designers without access to AscentLint to iterate with open-source tools before making their first Pull Request.
For batch regressions we have integrated this flow into the `dvsim` tool, which can be invoked as follows from the root of the project repository:
```
diff --git a/tool_requirements.py b/tool_requirements.py
index 7777c6e..4a1a0f2 100644
--- a/tool_requirements.py
+++ b/tool_requirements.py
@@ -6,4 +6,5 @@
# and inserted into the documentation.
__TOOL_REQUIREMENTS__ = {
'verilator': '4.028',
+ 'verible': '0.0-375-g7d55b5b',
}
diff --git a/util/build-verible.sh b/util/build-verible.sh
deleted file mode 100755
index a85435b..0000000
--- a/util/build-verible.sh
+++ /dev/null
@@ -1,64 +0,0 @@
-#!/bin/bash
-# Copyright lowRISC contributors.
-# Licensed under the Apache License, Version 2.0, see LICENSE for details.
-# SPDX-License-Identifier: Apache-2.0
-#
-# This script installs Verible, an open-source style lint and code
-# formatting tool: https://github.com/google/verible
-# Note that this tool is still experimental. Especially the formatting
-# part is still under active development, and hence not production ready.
-#
-
-VERIBLE_VERSION=e654c18e4e712285757f9667f737a73f88f71c01
-INSTALL_DIR=/tools/verible
-
-# this requires the bazel build system and GCC7
-# see https://docs.bazel.build/versions/master/install-ubuntu.html
-
-echo "checking whether bazel is installed..."
-if which bazel; then
- echo "OK"
-else
- echo "bazel is not installed. installing bazel..."
- sudo apt install curl -y
- curl https://bazel.build/bazel-release.pub.gpg | sudo apt-key add -
- echo "deb [arch=amd64] https://storage.googleapis.com/bazel-apt stable jdk1.8" \
- | sudo tee /etc/apt/sources.list.d/bazel.list
- sudo apt update && sudo apt install bazel -y
-fi
-
-# upgrade to GCC7
-# TODO: check whether we need to maintain the default symlinks here
-# for gcc -> GCC-5* such that other tools still work.
-echo "checking whether GCC7 is installed..."
-if which gcc-7; then
- echo "OK"
-else
- echo "GCC7 is not installed. installing GCC7..."
- sudo add-apt-repository ppa:ubuntu-toolchain-r/test
- sudo apt update
- sudo apt install g++-7 -y
-fi
-
-# get verible and install under /tools/verible
-# note: you may add $INSTALL_DIR to the PATH, but it is not
-# required for the run scripts to work.
-echo "Installing Verible ($VERIBLE_VERSION)..."
-
-mkdir -p build && cd build
-git clone https://github.com/google/verible.git
-cd verible
-git checkout $VERIBLE_VERSION
-
-bazel build --cxxopt='-std=c++17' //...
-bazel test --cxxopt='-std=c++17' //...
-
-sudo mkdir -p $INSTALL_DIR
-
-sudo install bazel-bin/verilog/tools/syntax/verilog_syntax $INSTALL_DIR
-sudo install bazel-bin/verilog/tools/formatter/verilog_format $INSTALL_DIR
-sudo install bazel-bin/verilog/tools/lint/verilog_lint $INSTALL_DIR
-
-echo "done"
-
-
