Add Pull Request Workflow

.github/scripts/file_hash.sh

@@ -0,0 +1,67 @@
+#!/bin/bash
+# SPDX-License-Identifier: Apache-2.0
+# 
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# DESCRIPTION:
+# ====================================
+# This tool is used to generate a hash over the Caliptra source code files
+# This can be used to verify the hash of the code for which internal workflows were
+# run prior to submission to the caliptra-rtl repo.
+# 
+# Usage: file_hash.sh <path_to_rtl_src_dir> <file_list>
+#   path_to_rtl_src_dir     Path to the root directory of the caliptra RTL repo.
+#   file_list               This list of all the files that should be included in the hash
+#                           is generated
+#
+# Exit and report failure if anything fails
+set -euo pipefail
+
+# Check arg count
+if [ $# -ne 2 ]
+  then
+    echo "Usage: $(basename $0) <path_to_caliptra_root> <file_list>"
+	exit -1
+fi
+
+# Get args
+rtl_path=$1
+
+# Read expected file list, prepend rtl path, and store in array
+IFS=$'\n' expected_file_list=($(cat "$2" | sed "s@^@""$rtl_path""/@"))
+
+# Make sure all files exist
+missing_files=0
+for file in "${expected_file_list[@]}"
+do
+	# Check if the file is missing
+	if ! test -f "$file"; then
+		# Report any missing files (and keep count)
+		if [ "$missing_files" -eq 0 ]; then
+			echo "Missing expected files: "
+		fi
+		missing_files=$(($missing_files + 1))
+		echo "  $file"
+	fi
+done
+
+# Calculate the hash (only if no files were missing)
+if [ "$missing_files" -eq 0 ]; then
+	hash=$(cat "${expected_file_list[@]}" | sha384sum | tr -d "\n *-")
+	echo "$hash"
+else
+	echo "Failed to generate code hash"
+	exit -1
+fi
+

.github/scripts/license_header_check.sh

@@ -0,0 +1,99 @@
+#!/usr/bin/env bash
+# SPDX-License-Identifier: Apache-2.0
+# 
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+function show_usage() {
+    printf "Usage: $0 [optional [parameters]]\n"
+    printf "\n"
+    printf "Options:\n"
+    printf " -i|--insertHeader\tInsert license header in files missing it (Currently unavailable) \n"
+    printf " -h|--help\tShow usage information\n"
+
+    return 0
+}
+
+set -euo pipefail
+
+apacheLicenseHeader="# SPDX-License-Identifier: Apache-2.0
+# 
+#
+# Licensed under the Apache License, Version 2.0 (the \"License\");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an \"AS IS\" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License."
+
+apacheLicenseHeader_v_c="//********************************************************************************
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2020 Western Digital Corporation or its affiliates.
+//
+// Licensed under the Apache License, Version 2.0 (the \"License\");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an \"AS IS\" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//********************************************************************************"
+
+while [[ ! -z "${1:+empty}" ]]; do
+    if [[ "$1" == "--help" ]] || [[ "$1" == "-h" ]]; then
+        show_usage 
+    #elif [[ "$1" == "-i" ]] || [[ "$1" == "--insertHeader"]]; then
+    #    insHeader=1
+    #    shift
+    fi
+    shift
+done
+
+if [[ -z ${CALIPTRA_ROOT:+"empty"} ]]; then
+    echo "Must set CALIPTRA_ROOT prior to running script"
+    exit 1
+fi
+
+exclude_dir='{uvmf*,.git,cmark,caliptra_reg_html,caliptra_top_reg_html,sha256,sha512,sha512_masked,doe,fw_test_*,__pycache__,templates,docs}'
+exclude_suffix='*.{tcl,txt,js,htm,html,json,vf,yml,woff,rsp,rdl,bashrc,waiver,cfg,hex,rc,exe,pdf,png,hvp,svg,log}'
+exclude_regs='*_reg*.{sv,rdl}'
+exclude_csr='*_csr*.*'
+exclude_file='{sglint_waivers,pr_hash,pr_timestamp,.git-comodules,.gitignore,spyglass_lint.policy,ascent.ctl,clp_mapfile,readme.md,README.md,SECURITY.md,c_sample.c}'
+apache_patn='Licensed under the Apache License'
+
+# Recursive find through repository with some major exclusions
+# 'eval' is used to expand exclude vars into a usable glob pattern
+files_missing_header=$(eval grep -r -L -i  --exclude-dir=${exclude_dir} --exclude=${exclude_suffix} --exclude=${exclude_regs} --exclude=${exclude_csr} --exclude=${exclude_file} \"${apache_patn}\" "${CALIPTRA_ROOT}")
+
+# After excluding some crypto directories, re-scan specific directories therein
+# (can't specificy exclude-dir using '<patn>/<patn>' to catch nested directories)
+files_missing_header="${files_missing_header:+$files_missing_header }$(eval grep -r -L -i  --exclude-dir={rtl,uvmf_*} --exclude={aes_tb.v,doe_tb.v,sha256_tb.v} --exclude=${exclude_suffix} --exclude=${exclude_regs} --exclude=${exclude_csr} --exclude=${exclude_file} \"${apache_patn}\" \"${CALIPTRA_ROOT}/src/sha256\" \"${CALIPTRA_ROOT}/src/sha512\" \"${CALIPTRA_ROOT}/src/sha512_masked\" \"${CALIPTRA_ROOT}/src/doe\")"
+
+if [[ $files_missing_header != "" ]]; then
+    echo -e "\n\n\tPlease add Apache license header to the following files and try again. \n"
+    for file in $files_missing_header; do
+        echo -e "\t\e[1;31m $file \e[0m\n"
+    done
+    exit 1
+fi
+echo "Apache license header check completed successfully"

.github/scripts/pr_rdl_check.sh

@@ -0,0 +1,72 @@
+# SPDX-License-Identifier: Apache-2.0
+# 
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+set -euo pipefail
+
+if [[ $# -ne 1 ]]; then
+    echo "Error, requires branch name argument"
+    exit 1
+else
+    merge_dest=$1
+fi
+
+if ! git show-ref --quiet "${merge_dest}"; then
+    echo "Could not find ref named [${merge_dest}]"
+    exit 1
+fi
+
+if [[ -z "${CALIPTRA_ROOT:+"empty"}" ]]; then
+    echo "Error, must set CALIPTRA_ROOT"
+    exit 1
+fi
+cd "${CALIPTRA_ROOT}"
+
+# Find all RTL files that are generated from RDL
+declare -a gen_rtl_list
+for rdl_file in $(find "${CALIPTRA_ROOT}/src" -name "*.rdl"); do 
+    rtl_file=$(sed 's,\.rdl,.sv,' <<< $(basename $rdl_file));
+    if [[ $(find $(dirname $(dirname $rdl_file)) -name "$rtl_file" | wc -l) -eq 1 ]]; then
+        gen_rtl_list+=("${rtl_file}")
+    else
+        echo "Did not find any file named [$rtl_file] that would be generated from [$rdl_file]";
+    fi;
+done
+args=$(for fname in "${gen_rtl_list[@]}"; do echo -n " -e '$fname'"; done)
+
+# Find file modifications
+rdl_mod_count=$(git diff --merge-base "${merge_dest}" --name-only | eval grep -c -e '\.rdl$\|tools\/templates\/rdl\|reg_gen.sh\|reg_gen.py\|reg_doc_gen.sh\|reg_doc_gen.py' $args || exit 0)
+if [[ "${rdl_mod_count}" -gt 0 ]]; then
+    # Run the HTML Doc generator script (to update the REG macro header files)
+    # and the individual reg generator script but then remove the docs directories
+    bash "${CALIPTRA_ROOT}/tools/scripts/reg_gen.sh"
+    bash "${CALIPTRA_ROOT}/tools/scripts/reg_doc_gen.sh"
+    rm -rf "${CALIPTRA_ROOT}/src/integration/docs"
+    rm -rf "${CALIPTRA_ROOT}/src/soc_ifc/docs"
+
+    # Check for any file changes
+    if [[ $(git status -s --untracked-files=all --ignored=traditional -- "${CALIPTRA_ROOT}/src/" | wc -l) -gt 0 ]]; then
+      echo "Regenerating reg RDL outputs produced some file changes:";
+      git status -s --untracked-files=all --ignored=traditional;
+      git diff;
+      echo "*****************************************";
+      echo "Review above changes locally and resubmit pipeline";
+      echo "(Hint: Check ${CALIPTRA_ROOT} for the above changes)";
+      echo "*****************************************";
+      exit 1;
+    fi
+else
+    echo "skipping RDL check since no RDL files were modified"
+fi

.github/scripts/stamp_repo.sh

@@ -0,0 +1,76 @@
+#!/usr/bin/bash
+# SPDX-License-Identifier: Apache-2.0
+# 
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+# ENV Check
+if [[ -z "${CALIPTRA_ROOT:+"empty"}" ]]; then
+    echo "Error, must set CALIPTRA_ROOT"
+    exit 1
+fi
+
+# Create file list
+find "$CALIPTRA_ROOT" -type f -name "*.sv" \
+                           -o -name "*.svh" \
+                           -o -name "*.rdl" \
+                           -o -name "*.json" \
+                           -o -name "*.v" \
+                           -o -name "*.vh" \
+                           -o -name "*.rsp" \
+                           -o -name "*.s" \
+                           -o -name "*.c" \
+                           -o -name "*.cpp" \
+                           -o -name "*.h" \
+                           -o -name "*.hex" \
+                           -o -name "*.ld" \
+                           -o -name "*.gdb" \
+                           -o -name "*.yml" \
+                           -o -name "*.sh" \
+                           -o -name "*.py" \
+                           -o -name "*.md" \
+                           -o -name "pr_timestamp" \
+                           ! -path "*.git/*" | LC_COLLATE=C sort -o $CALIPTRA_ROOT/.github/workflow_metadata/file_list.txt
+sed -i "s,^$CALIPTRA_ROOT/,," $CALIPTRA_ROOT/.github/workflow_metadata/file_list.txt
+echo "Found $(wc -l $CALIPTRA_ROOT/.github/workflow_metadata/file_list.txt) source code files to hash"
+echo -e "First five files:\n>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>"
+head -5 $CALIPTRA_ROOT/.github/workflow_metadata/file_list.txt
+echo -e ">>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>"
+
+# Create timestamp
+if [[ ! -f $CALIPTRA_ROOT/.github/workflow_metadata/pr_timestamp ]]; then
+    echo "Error, file not found: $CALIPTRA_ROOT/.github/workflow_metadata/pr_timestamp"
+    exit 1
+fi
+timestamp=$(date +%s)
+echo "Submitting timestamp [${timestamp}]"
+echo -n ${timestamp} > $CALIPTRA_ROOT/.github/workflow_metadata/pr_timestamp
+
+# Create hash
+hash=$($CALIPTRA_ROOT/.github/scripts/file_hash.sh $CALIPTRA_ROOT $CALIPTRA_ROOT/.github/workflow_metadata/file_list.txt)
+if [[ -z ${hash:+"empty"} ]]; then
+    echo "Failed to run hash script"
+    echo $hash
+    exit 1;
+fi
+echo "RTL hash is $hash"
+if [[ ! -f $CALIPTRA_ROOT/.github/workflow_metadata/pr_hash ]]; then
+    echo "Error, file not found: $CALIPTRA_ROOT/.github/workflow_metadata/pr_hash"
+    exit 1
+fi
+echo "Submitting hash [${hash}]"
+echo -n ${hash} > $CALIPTRA_ROOT/.github/workflow_metadata/pr_hash
+
+# Clean up
+rm $CALIPTRA_ROOT/.github/workflow_metadata/file_list.txt

.github/workflow_metadata/README.md

@@ -0,0 +1,20 @@
+Files in this directory are used to support workflow checks that run on the caliptra-rtl repository using GitHub actions.
+
+pr\_\* objects are used to validate a Pull Request run. This is in support of an honor based system that allows contributors to create internal pipelines (for example, to run tests with proprietary toolchains). The suggested procedure here is:
+  1. Contributor develops a new feature and pushes a branch to the caliptra-rtl GitHub repository
+  1. Contributor runs an internal workflow on a branch that contains the merge of the feature branch into main. This workflow includes the complete test-suite and (possibly) some additional checks required by the company policy of that contributor
+    - All contributors MUST perform the following checks in their development pipeline:
+      - VCS test of the complete L0 regression suite (smoke tests)
+      - Lint check run against caliptra_top
+  1. Upon successfully completing, the internal workflow runs the script [stamp_repo.sh](../scripts/stamp_repo.sh). This script:
+    - Updates the pr\_timestamp file to the current date
+    - Runs the hash script [file_hash.sh](../scripts/file_hash.sh) to measure the code that the workflow ran on (including the pr\_timestamp file)
+    - Writes the hash to the pr\_hash file
+  1. The internal workflow should commit the updates to pr\_timestamp and pr\_hash as the final commit to the feature branch
+    - Note that the workflow should be run upon a branch containing the MERGE of the feature branch into main, but the updated stamp files should be committed directly to the feature branch
+  1. Contributor creates a Pull Request to submit the feature branch to the GitHub `main` branch
+  1. Pull Request triggers GitHub Actions to run
+    - Verilator, etc
+    - Check on the timestamp. If the timestamp is sufficiently outdated (predates the final commit to the branch by more than 1 hour) the feature branch is considered to have failed the internal workflow
+    - Pull Request runs a hash on the branch fileset (including the timestamp), compares with the contents of pr\_hash. If the hash mismatches, the feature branch is considered to have failed the internal workflow
+  1. Pull Request is allowed to be merged only once all Actions complete successfully

.github/workflow_metadata/pr_hash

@@ -0,0 +1 @@
+2770b6550eaed38a4ebcccc9a2724c5287d0bcad6de93d88bbd9441ff818dd8438a4979ff1999e920065b3e97f09fb07

.github/workflow_metadata/pr_timestamp

@@ -0,0 +1 @@
+1712005695

.github/workflows/build-test-verilator.yml

@@ -5,8 +5,7 @@ name: Verilator
 on:
   push:
     branches: ["main", "dev-goog", "dev-msft"]
-  pull_request:
-
+  workflow_call:
   workflow_dispatch:
 
 env:

.github/workflows/doc-gen.yml

@@ -4,7 +4,7 @@ name: Register Documentation
 
 on:
   workflow_dispatch:
-  pull_request:
+  workflow_call:
   push:
     branches: ["main"]
 
@@ -17,13 +17,17 @@ jobs:
     steps:
       - uses: actions/checkout@v3
 
-      - name: Install peakrd-uvm
+      - name: Install peakrdl
         run: |
           python3 -m pip install \
-              peakrdl-uvm==2.2.0 \
-              peakrdl-regblock==0.10.0 \
-              peakrdl-html==2.9.0 \
-              peakrdl-ipxact==3.3.0
+              systemrdl-compiler==1.27.3 \
+              peakrdl-systemrdl==0.3.0 \
+              peakrdl-regblock==0.21.0 \
+              peakrdl-uvm==2.3.0 \
+              peakrdl-ipxact==3.4.3 \
+              peakrdl-html==2.10.1 \
+              peakrdl-cheader==1.0.0 \
+              peakrdl==1.1.0
 
       - name: Generate docs
         run: |

.github/workflows/interactive-debugging.yml

@@ -5,8 +5,7 @@ name: Interactive debugging
 on:
   push:
     branches: ["main", "dev-goog", "dev-msft", "dev-public"]
-  pull_request:
-
+  workflow_call:
   workflow_dispatch:
 
 jobs: