[ot] script/opentitan: ot_tidy: create new ot_tidy.py script

This script is intended to replace the `ot-tidy.sh` script for running
clang-tidy on our part of the codebase.

A `-j` flag is added to run clang-tidy jobs in parallel, using the
run-clang-tidy script that comes with it. On my machine this speeds
up checking files for CI from >3 minutes to ~30 seconds.

The script also checks for some configuration issues, such as the C
compiler not being set to clang when configuring QEMU - this causes some
warnings to be enabled that are not recognised by clang and will show up
as errors.

Signed-off-by: Alice Ziuziakowska <[email protected]>

Author: ziuziakowska

scripts/opentitan/ot_tidy.py

@@ -0,0 +1,206 @@
+#!/usr/bin/env python3
+
+# Copyright (c) 2025 lowRISC contributors.
+# SPDX-License-Identifier: Apache2
+
+"""
+'clang-tidy' wrapper script
+"""
+
+import argparse
+import re
+import subprocess
+import sys
+from glob import glob
+from multiprocessing import cpu_count
+from os import chdir, execvp, scandir
+from os.path import abspath, dirname, isfile, join, relpath, splitext
+from shutil import which
+
+# clang major version to check for
+CLANG_MAJOR = 20
+
+# Directory we are in
+ot_scripts = dirname(abspath(__file__))
+
+# QEMU root directory
+qemu_root = dirname(dirname(ot_scripts))
+
+# Default build directory is 'build' in QEMU root
+default_build_dir = join(qemu_root, 'build')
+
+# clang-tidy config file path
+clang_tidy_yml = join(ot_scripts, "clang-tidy.yml")
+
+def ci_files():
+    """Get list of files that are checked in CI"""
+    lst_files_list = []
+    ci_files_list = []
+    directory = join(ot_scripts, 'clang-tidy.d')
+    for entry in scandir(directory):
+        if entry.is_file() and splitext(entry)[1] == '.lst':
+            lst_files_list.append(entry)
+    for entry in lst_files_list:
+        with open(entry, "r") as f:
+            patterns = f.readlines()
+            for pattern in patterns:
+                ci_files_list += glob(pattern.strip(), root_dir=qemu_root)
+    return ci_files_list
+
+def uint(value):
+    """Argparse function to parse integer greater than 0"""
+    value = int(value)
+    if value <= 0:
+        raise argparse.ArgumentTypeError(f"{value} is not an integer greater than 0.")
+    return value
+
+def eprint(*args, **kwargs):
+    """Wrapper for print to stderr with colour"""
+    col = "\x1b[33m"
+    reset = "\x1b[0m"
+    print(col, end='', file=sys.stderr)
+    print(*args, *kwargs, end='', file=sys.stderr)
+    print(reset, file=sys.stderr)
+
+
+def check_compile_commands(build_dir):
+    """
+    Check for 'compile_commands.json' in given build directory
+    """
+    if not isfile(join(build_dir, "compile_commands.json")):
+        eprint(f"compile_commands.json not found in directory '{build_dir}',")
+        eprint("specify your build directory with '--build-dir', or make sure to run configure.")
+        sys.exit(1)
+
+def check_cc(build_dir):
+    """ Check that the configured C compiler for the build is clang"""
+    cc_found = False
+    # look in <build_dir>/config.status and try to find CC variable
+    with open(join(build_dir, "config.status"), "r") as f:
+        lines = f.readlines()
+        for line in lines:
+            m = re.match("^CC='(.*)'$", line)
+            if m is not None:
+                ccs = [f"clang-{CLANG_MAJOR}", "clang"]
+                if m.group(1) not in ccs:
+                    eprint(f"QEMU build was configured with CC '{m.group(1)}', not 'clang',")
+                    eprint("Unknown warning and argument errors may appear.")
+                cc_found = True
+                break
+    if not cc_found:
+        # no CC option in config.status
+        eprint("No CC argument given to configure, re-configure with '--cc=...' and rebuild.")
+        eprint("If host toolchain is not clang, unknown warning and argument errors may appear.")
+
+def check_and_get_clang_tidy() -> str:
+    """Check for and return an appropriate 'clang-tidy'"""
+    # Check for 'clang-tidy-{VERSION}' first and return if found
+    if which(f"clang-tidy-{CLANG_MAJOR}"):
+        return f"clang-tidy-{CLANG_MAJOR}"
+    # Otherwise, look for 'clang-tidy' and check its version
+    elif which("clang-tidy"):
+        p = subprocess.run(["clang-tidy", "--version"], capture_output=True)
+        if p.returncode != 0:
+            eprint("'clang-tidy --version' failed.")
+            sys.exit(1)
+        version_line = p.stdout.decode().split("\n")[0]
+        m = re.match("^.*LLVM version ([0-9]*)\\..*$", version_line)
+        if m is None:
+            eprint("Could not parse 'clang-tidy' version string.")
+            sys.exit(1)
+        if m.group(1) != str(CLANG_MAJOR):
+            eprint(f"'clang-tidy' is major version {m.group(1)}, expected {CLANG_MAJOR}.")
+            sys.exit(1)
+        return "clang-tidy"
+    else:
+        eprint(f"No 'clang-tidy-{CLANG_MAJOR}' or suitable 'clang-tidy' in PATH.")
+        sys.exit(1)
+
+def check_and_get_run_clang_tidy() -> str:
+    """Check for and return an appropriate 'run-clang-tidy'"""
+    # Check for 'run clang-tidy-{VERSION}' first and return if found
+    if which(f"run-clang-tidy-{CLANG_MAJOR}"):
+        return f"run-clang-tidy-{CLANG_MAJOR}"
+    # 'run-clang-tidy' does not have a version flag, so return it if it exists
+    elif which("run-clang-tidy"):
+        return "run-clang-tidy"
+    else:
+        eprint(f"No 'run-clang-tidy-{CLANG_MAJOR}' or suitable 'run-clang-tidy' in PATH.")
+        sys.exit(1)
+
+def main():
+    """Parser and wrapper main"""
+
+    parser = argparse.ArgumentParser()
+
+    parser.add_argument('--build-dir', required=False, default=default_build_dir,
+        help="""
+        QEMU build directory.
+        Defaults to 'build' in QEMU root
+        """
+    )
+
+    parser.add_argument('-j', '--jobs', required=False, type=uint, nargs='?',
+        default=1, const=cpu_count(),
+        help="""
+        Number of tidy jobs to run in parallel.
+        Defaults to 1 if not specified, and all cores if -j is given with no number.
+        """
+    )
+
+    parser.add_argument('--ci-files', required=False, action='store_true',
+        help="Run on all files checked by CI")
+
+    parser.add_argument('-f', '--files', required=False, nargs="+", action='extend', default=[],
+        help="Files to run tidy on")
+
+    args = parser.parse_args()
+
+    # resolve build dir to absolute path
+    args.build_dir = abspath(args.build_dir)
+
+    # filter anything that could be interpreted as a flag by clang-tidy
+    args.files = [f for f in args.files if not f.startswith('-')]
+
+    # change provided relative paths to be relative to QEMU root
+    # (CI file paths are already relative to root)
+    args.files = [relpath(abspath(f), start=qemu_root) for f in args.files]
+
+    # append ci files
+    if args.ci_files:
+        args.files += ci_files()
+
+    if len(args.files) == 0:
+        eprint("No input files provided")
+        sys.exit(1)
+
+    check_compile_commands(args.build_dir)
+    check_cc(args.build_dir)
+
+    cmd = ""
+    cmd_args = []
+    # use a 'run-clang-tidy' if running in parallel.
+    # the wrapper has slightly different commandline arguments
+    if args.jobs == 1:
+        cmd = check_and_get_clang_tidy()
+        cmd_args = [
+            cmd,
+            "-p", args.build_dir,
+            "--config-file", clang_tidy_yml
+        ]
+    else:
+        cmd = check_and_get_run_clang_tidy()
+        cmd_args = [
+            cmd,
+            "-p", args.build_dir,
+            "-config-file", clang_tidy_yml,
+            "-j", str(args.jobs),
+            "-quiet"
+        ]
+
+    cmd_args += args.files
+    chdir(qemu_root)
+    execvp(cmd, cmd_args)
+
+if __name__ == '__main__':
+    main()