Start of public OpenTitan development history
Code contributors:
Alex Bradbury <asb@lowrisc.org>
Cindy Chen <chencindy@google.com>
Eunchan Kim <eunchan@google.com>
Gaurang Chitroda <gaurangg@google.com>
Mark Hayter <mark.hayter@gmail.com>
Michael Schaffner <msf@google.com>
Miguel Osorio <miguelosorio@google.com>
Nils Graf <nilsg@google.com>
Philipp Wagner <phw@lowrisc.org>
Pirmin Vogel <vogelpi@lowrisc.org>
Ram Babu Penugonda <rampenugonda@google.com>
Scott Johnson <scottdj@google.com>
Shail Kushwah <kushwahs@google.com>
Srikrishna Iyer <sriyer@google.com>
Steve Nelson <Steve.Nelson@wdc.com>
Tao Liu <taliu@google.com>
Timothy Chen <timothytim@google.com>
Tobias Wölfel <tobias.woelfel@mailbox.org>
Weicai Yang <weicai@google.com>
diff --git a/hw/lint/README.md b/hw/lint/README.md
new file mode 100644
index 0000000..53fa84c
--- /dev/null
+++ b/hw/lint/README.md
@@ -0,0 +1,56 @@
+# RTL Linting
+
+Linting is a productivity tool for designers to quickly find typos and
+bugs at the time when the RTL is written. Running lint is important
+when using SystemVerilog, a weakly-typed language, unlike other hardware
+description languages. We consider linting to be critical for conformance
+to our goals of high quality designs.
+
+We have chosen [Ascent
+Lint](https://www.realintent.com/rtl-linting-ascent-lint/) by Real Intent
+as our linter of choice for hardware design collateral.
+In the current state of the project, the lint policy file and waiver
+files are **not** checked into the repo, but are being kept
+privately. The lint scripts in this repo don't need a policy file and
+waiver files, you can still run lint without them.
+
+See below instructions on how lint is executed on a design. The goal
+is zero Errors for each design either through code fixing
+(preferred) or lint waivers (where justified).
+
+## Setup
+
+1. Install the latest fusesoc version needed for lint:
+
+ cd <the-root-directory-which-contains-the-hw-directory>
+ pip3 install -U -r python-requirements.txt --user
+
+1. Install and load ascentlint: version
+ `2018.A.p10G.2020_07_31` of ascentlint is being used.
+ In case you use `module load`, make sure to load the correct version.
+
+## Running Lint
+
+**Example 1**: To run lint on module `gpio.sv`, type:
+
+ cd hw/lint
+ lint gpio
+
+Above generates the lint report file `lint.rpt`, which details all lint errors
+and warning.
+
+**Example 2**: You can also run lint on any submodule of the design, not
+ just the ones that have a `.core` file. For example, to run lint on submodule
+ `gpio_reg_top.sv`, tye:
+
+ cd hw/lint
+ lint gpio_reg_top
+
+## Running Lint on the Entire Design
+
+To run lint on all blocks and the toplevel, type:
+
+ cd hw/lint
+ lint_all | tee lint_all.std
+
+The script `lint_all` can be used for continuous integration.
diff --git a/hw/lint/cdc_lint b/hw/lint/cdc_lint
new file mode 100755
index 0000000..bc15877
--- /dev/null
+++ b/hw/lint/cdc_lint
@@ -0,0 +1,31 @@
+#!/bin/bash
+
+# Copyright lowRISC contributors.
+# Licensed under the Apache License, Version 2.0, see LICENSE for details.
+# SPDX-License-Identifier: Apache-2.0
+
+# CDC stands for clock domain crossing. This script uses Meridian CDC,
+# which is a CDC linting tool.
+#
+# Usage: To run cdc_lint on module foo, type
+# cdc_lint foo
+#
+# Here are three examples:
+# cdc_lint gpio
+# cdc_lint prim_fifo_async
+# cdc_lint top_earlgrey
+
+#-------------------------------------------------------------------------
+# set LINT_TOP env variable
+#-------------------------------------------------------------------------
+export LINT_TOP=$1
+
+#-------------------------------------------------------------------------
+# use fusesoc to generate file list
+#-------------------------------------------------------------------------
+fusesoc --cores-root .. sim --build-only formal > /dev/null 2>&1
+
+#-------------------------------------------------------------------------
+# run meridian CDC lint
+#-------------------------------------------------------------------------
+mcdc -i cdc_lint.tcl -wait -log cdc.log
diff --git a/hw/lint/cdc_lint.tcl b/hw/lint/cdc_lint.tcl
new file mode 100644
index 0000000..0e32925
--- /dev/null
+++ b/hw/lint/cdc_lint.tcl
@@ -0,0 +1,17 @@
+# Copyright lowRISC contributors.
+# Licensed under the Apache License, Version 2.0, see LICENSE for details.
+# SPDX-License-Identifier: Apache-2.0
+
+analyze +define+ASIC_SYNTHESIS+SYNTHESIS -F [glob build/formal_0/sim-icarus/*.scr] -sv
+
+elaborate $env(LINT_TOP)
+
+# read_sdc design.sdc
+# TODO: add SDC file above
+
+analyze_intent
+verify_cdc
+
+report_policy ALL -all_runs -verbose -output cdc.rpt
+
+exit
diff --git a/hw/lint/cdc_lint_all b/hw/lint/cdc_lint_all
new file mode 100755
index 0000000..27adf36
--- /dev/null
+++ b/hw/lint/cdc_lint_all
@@ -0,0 +1,74 @@
+#!/bin/bash
+
+# Copyright lowRISC contributors.
+# Licensed under the Apache License, Version 2.0, see LICENSE for details.
+# SPDX-License-Identifier: Apache-2.0
+
+# to run cdc-lint on all modules, type
+# cdc_lint_all
+
+#-------------------------------------------------------------------------
+# list all blocks
+#-------------------------------------------------------------------------
+declare -a blocks=(
+ "prim_fifo_async"
+ "prim_pulse_sync"
+ "gpio"
+ "rv_core_ibex"
+ "rv_dm"
+ "rv_plic"
+ "spi_device"
+ "rv_timer"
+ "uart"
+ "hmac"
+ "flash_ctrl"
+ "usbuart"
+ "usbdev"
+ "usb_fs_nb_pe"
+ "tlul_adapter_sram"
+ "tlul_socket_1n"
+ "tlul_socket_m1"
+ "sram2tlul"
+ "xbar_main"
+ "top_earlgrey"
+)
+
+#-------------------------------------------------------------------------
+# print header
+#-------------------------------------------------------------------------
+printf "CDC LINT REPORT:\n\n"
+format="%20s %10s %10s %10s \n"
+printf "${format}" "Block" "Clocks" "Crossings" "Warnings"
+echo "------------------------------------------------------"
+
+#-------------------------------------------------------------------------
+# run cdc-lint (meridian) and summarize results
+#-------------------------------------------------------------------------
+\rm -Rf build meridian_project cdc*.log cdc*.rpt
+
+for block in "${blocks[@]}" ; do
+
+ cdc_lint $block > /dev/null 2>&1
+ cp cdc.rpt cdc_${block}.rpt
+ cp cdc.log cdc_${block}.log
+
+ # summarize results
+ crash=`grep "^ ERR" cdc.log`
+ if [ $? -eq 0 ]; then
+ printf "${format}" $block "CRASH"
+ else
+ clocks=`grep "Total Async" cdc.log | cut -d":" -f2`
+ cross=`grep "Total crossings detected" cdc.log | cut -d" " -f4 | cut -d"," -f1`
+ warns=`grep "Total warnings found" cdc.log | cut -d":" -f2`
+ printf "${format}" $block $clocks $cross $warns
+ fi
+done
+
+#-------------------------------------------------------------------------
+# generate detailed reports
+#-------------------------------------------------------------------------
+printf "\n\nLIST OF WARNINGS FOR EACH BLOCK:"
+for block in "${blocks[@]}" ; do
+ printf "\n\n${block}\n"
+ grep "^W_" cdc_${block}.rpt | cut -d";" -f1
+done
diff --git a/hw/lint/lint b/hw/lint/lint
new file mode 100755
index 0000000..d549bb1
--- /dev/null
+++ b/hw/lint/lint
@@ -0,0 +1,30 @@
+#!/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 uses AscentLint from Real Intent.
+#
+# Usage: To run lint on module foo, type
+# lint foo
+#
+# Here are three examples:
+# lint gpio
+# lint prim_fifo_async
+# lint top_earlgrey
+
+#-------------------------------------------------------------------------
+# set LINT_TOP env variable
+#-------------------------------------------------------------------------
+export LINT_TOP=$1
+
+#-------------------------------------------------------------------------
+# use fusesoc to generate file list
+#-------------------------------------------------------------------------
+fusesoc --cores-root .. sim --build-only formal > /dev/null 2>&1
+
+#-------------------------------------------------------------------------
+# run meridian CDC lint
+#-------------------------------------------------------------------------
+ascentlint -i lint.tcl -wait -log lint.log
diff --git a/hw/lint/lint.tcl b/hw/lint/lint.tcl
new file mode 100644
index 0000000..0fa5adf
--- /dev/null
+++ b/hw/lint/lint.tcl
@@ -0,0 +1,15 @@
+# Copyright lowRISC contributors.
+# Licensed under the Apache License, Version 2.0, see LICENSE for details.
+# SPDX-License-Identifier: Apache-2.0
+
+foreach script_file [glob -nocomplain ascentlint.policy *.waiver] {
+ source $script_file
+}
+
+analyze +define+ASIC_SYNTHESIS+SYNTHESIS -F [glob build/formal_0/sim-icarus/*.scr] -sv
+
+elaborate $env(LINT_TOP)
+
+report_policy -skip_empty_summary_status -compat -output lint.rpt NEW
+
+exit
diff --git a/hw/lint/lint_all b/hw/lint/lint_all
new file mode 100755
index 0000000..9fc4f17
--- /dev/null
+++ b/hw/lint/lint_all
@@ -0,0 +1,74 @@
+#!/bin/bash
+
+# to run lint on all modules, type
+# lint_all | tee lint_all.std
+
+#-------------------------------------------------------------------------
+# list all blocks
+#-------------------------------------------------------------------------
+declare -a blocks=(
+ "gpio"
+ "rv_core_ibex"
+ "rv_dm"
+ "rv_plic"
+ "spi_device"
+ "rv_timer"
+ "uart"
+ "hmac"
+ "flash_ctrl"
+ "usbuart"
+ "usbdev"
+ "usb_fs_nb_pe"
+ "tlul_adapter_sram"
+ "tlul_socket_1n"
+ "tlul_socket_m1"
+ "sram2tlul"
+ "xbar_main"
+ "top_earlgrey"
+)
+
+#-------------------------------------------------------------------------
+# print header
+#-------------------------------------------------------------------------
+printf "NUMBER OF LINT ERRORS PER BLOCK:\n\n"
+format="%20s %10s %10s \n"
+printf "${format}" "Block" "Errors" "Warnings"
+echo "-------------------------------------------"
+
+#-------------------------------------------------------------------------
+# run lint and summarize results
+#-------------------------------------------------------------------------
+\rm -Rf build ascent_project lint_*.log lint_*.rpt
+
+for block in "${blocks[@]}" ; do
+
+ lint $block > /dev/null 2>&1
+ cp lint.log lint_${block}.log
+ cp lint.rpt lint_${block}.rpt
+
+ # summarize results
+ crash=`grep "^ ERR" lint.log`
+ if [ $? -eq 0 ]; then
+ error_cnt="CRASH"
+ warni_cnt="CRASH"
+ else
+ error_cnt=`grep "^E " lint.rpt | wc -l`
+ warni_cnt=`grep "^W " lint.rpt | wc -l`
+ fi
+ printf "${format}" `echo $block | rev | cut -d"/" -f2 | rev` $error_cnt $warni_cnt
+done
+
+#-------------------------------------------------------------------------
+# generate detailed reports
+#-------------------------------------------------------------------------
+printf "\n\nLIST OF ERRORS (E) AND WARNINGS (W) FOR EACH BLOCK:"
+for block in "${blocks[@]}" ; do
+
+ printf "\n\n${block}\n"
+
+ # grep for lint crashes and lint errors, and limit line length
+ grep "^ ERR" -A 2 lint_${block}.log | cut -c -200
+ grep "^E " lint_${block}.rpt | cut -c -200
+ grep "^W " lint_${block}.rpt | cut -c -200
+
+done
diff --git a/hw/lint/rdc_lint b/hw/lint/rdc_lint
new file mode 100755
index 0000000..b7fd42a
--- /dev/null
+++ b/hw/lint/rdc_lint
@@ -0,0 +1,31 @@
+#!/bin/bash
+
+# Copyright lowRISC contributors.
+# Licensed under the Apache License, Version 2.0, see LICENSE for details.
+# SPDX-License-Identifier: Apache-2.0
+
+# RDC stands for reset domain crossing. This script uses Meridian RDC,
+# which is an RDC linting tool.
+#
+# Usage: To run rdc_lint on module foo, type
+# rdc_lint foo
+#
+# Here are three examples:
+# rdc_lint gpio
+# rdc_lint prim_fifo_async
+# rdc_lint top_earlgrey
+
+#-------------------------------------------------------------------------
+# set LINT_TOP env variable
+#-------------------------------------------------------------------------
+export LINT_TOP=$1
+
+#-------------------------------------------------------------------------
+# use fusesoc to generate file list
+#-------------------------------------------------------------------------
+fusesoc --cores-root .. sim --build-only formal > /dev/null 2>&1
+
+#-------------------------------------------------------------------------
+# run meridian CDC lint
+#-------------------------------------------------------------------------
+mrdc -i rdc_lint.tcl -wait -log rdc.log
diff --git a/hw/lint/rdc_lint.tcl b/hw/lint/rdc_lint.tcl
new file mode 100644
index 0000000..516fa29
--- /dev/null
+++ b/hw/lint/rdc_lint.tcl
@@ -0,0 +1,17 @@
+# Copyright lowRISC contributors.
+# Licensed under the Apache License, Version 2.0, see LICENSE for details.
+# SPDX-License-Identifier: Apache-2.0
+
+analyze +define+ASIC_SYNTHESIS+SYNTHESIS -F [glob build/formal_0/sim-icarus/*.scr] -sv
+
+elaborate $env(LINT_TOP)
+
+# read_sdc design.sdc
+# TODO: add SDC file above
+
+analyze_intent
+verify_rdc
+
+report_policy ALL -all_runs -verbose -output rdc.rpt
+
+exit
diff --git a/hw/lint/rdc_lint_all b/hw/lint/rdc_lint_all
new file mode 100755
index 0000000..fdbef51
--- /dev/null
+++ b/hw/lint/rdc_lint_all
@@ -0,0 +1,74 @@
+#!/bin/bash
+
+# Copyright lowRISC contributors.
+# Licensed under the Apache License, Version 2.0, see LICENSE for details.
+# SPDX-License-Identifier: Apache-2.0
+
+# to run rdc-lint on all modules, type
+# rdc_lint_all
+
+#-------------------------------------------------------------------------
+# list all blocks
+#-------------------------------------------------------------------------
+declare -a blocks=(
+ "prim_fifo_async"
+ "prim_pulse_sync"
+ "gpio"
+ "rv_core_ibex"
+ "rv_dm"
+ "rv_plic"
+ "spi_device"
+ "rv_timer"
+ "uart"
+ "hmac"
+ "flash_ctrl"
+ "usbuart"
+ "usbdev"
+ "usb_fs_nb_pe"
+ "tlul_adapter_sram"
+ "tlul_socket_1n"
+ "tlul_socket_m1"
+ "sram2tlul"
+ "xbar_main"
+ "top_earlgrey"
+)
+
+#-------------------------------------------------------------------------
+# print header
+#-------------------------------------------------------------------------
+printf "RDC LINT REPORT:\n\n"
+format="%20s %10s %10s %10s \n"
+printf "${format}" "Block" "Clocks" "Resets" "Warnings"
+echo "------------------------------------------------------"
+
+#-------------------------------------------------------------------------
+# run rdc-lint (meridian) and summarize results
+#-------------------------------------------------------------------------
+\rm -Rf build meridian_project rdc*.log rdc*.rpt
+
+for block in "${blocks[@]}" ; do
+
+ rdc_lint $block > /dev/null 2>&1
+ cp rdc.rpt rdc_${block}.rpt
+ cp rdc.log rdc_${block}.log
+
+ # summarize results
+ crash=`grep "^ ERR" rdc.log`
+ if [ $? -eq 0 ]; then
+ printf "${format}" $block "CRASH"
+ else
+ clocks=`grep "Total Async" rdc.log | cut -d":" -f2`
+ resets=`grep "Total Reset signals" rdc.log | cut -d":" -f2 | cut -d"(" -f1`
+ warns=`grep "Total warnings found" rdc.log | cut -d":" -f2`
+ printf "${format}" $block $clocks $resets $warns
+ fi
+done
+
+#-------------------------------------------------------------------------
+# generate detailed reports
+#-------------------------------------------------------------------------
+printf "\n\nLIST OF WARNINGS FOR EACH BLOCK:"
+for block in "${blocks[@]}" ; do
+ printf "\n\n${block}\n"
+ grep "^W_" rdc_${block}.rpt | cut -d";" -f1
+done
