Merged chips/cwhitehead-msft-gen2-axi-modules branch and resolved con…

…flicts
chipsalliance · Aug 6, 2024 · 424c705 · 424c705
2 parents c33f2f9 + 0f3e910
commit 424c705
Show file tree

Hide file tree

Showing 313 changed files with 13,827 additions and 5,199 deletions.
diff --git a/.github/scripts/stamp_repo.sh b/.github/scripts/stamp_repo.sh
@@ -39,7 +39,6 @@ find "$CALIPTRA_ROOT" -type f -name "*.sv" \
                            -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

diff --git a/.github/workflow_metadata/README.md b/.github/workflow_metadata/README.md
@@ -3,18 +3,20 @@ Files in this directory are used to support workflow checks that run on the cali
 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
+      - 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
+      - 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
+      - ⚠️  IMPORTANT! The workflow should be run upon a branch containing the MERGE of the feature branch into main, and this merge branch should be used to calculate the file hash. 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
+      - 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
+
+The Pull Request run ignores updates to documentation files. That is, commits containing only markdown (.md) or image (.png) files are not required to pass the timestamp/hash check.
diff --git a/.github/workflow_metadata/pr_hash b/.github/workflow_metadata/pr_hash
@@ -1 +1 @@
-bb9b6ce589cb68131b3e0ce41458413628b5147fa58aef11d079e36b1053944ac65c092e4fcfe7c2b90031ee115d0d84
+fde9d1079e553c77020a67730f8725c220f1dd5d6d8d9ec3c1d6415f79ea7573075c3787c14674c943c9b93d45866199
diff --git a/.github/workflow_metadata/pr_timestamp b/.github/workflow_metadata/pr_timestamp
@@ -1 +1 @@
-1716926355
+1719520371
diff --git a/.github/workflows/pre-run-check.yml b/.github/workflows/pre-run-check.yml
@@ -74,6 +74,8 @@ jobs:
     steps:
       - name: Checkout RTL repo
         uses: actions/checkout@v4
+        with:
+            fetch-depth: 0
 
       - name: Gen File List
         run: |
@@ -94,7 +96,6 @@ jobs:
                                           -o -name "*.yml" \
                                           -o -name "*.sh" \
                                           -o -name "*.py" \
-                                          -o -name "*.md" \
                                           -o -name "pr_timestamp" \
                                           ! -path "*.git/*" | LC_COLLATE=C sort -o $GITHUB_WORKSPACE/.github/workflow_metadata/file_list.txt
             sed -i "s,^$GITHUB_WORKSPACE/,," $GITHUB_WORKSPACE/.github/workflow_metadata/file_list.txt
@@ -105,19 +106,36 @@ jobs:
 
       - name: Check Timestamp
         run: |
-            timestamp_exp=$(bc <<< "$(git log -n1 --pretty=tformat:'%ct')-3600")
-            if [[ ! -f $GITHUB_WORKSPACE/.github/workflow_metadata/pr_timestamp ]]; then
-                echo "Error, file not found: $GITHUB_WORKSPACE/.github/workflow_metadata/pr_timestamp"
-                exit 1
-            fi
-            timestamp=$(tail -1 $GITHUB_WORKSPACE/.github/workflow_metadata/pr_timestamp)
-            if [[ ${timestamp} -lt ${timestamp_exp} ]]; then
-                echo "Error, submitted timestamp [${timestamp}] is outdated: it precedes the latest commit to branch by more than an hour [${timestamp_exp}]"
-                echo "Please rerun any internal/company proprietary testcases, which should invoke .github/scripts/stamp_repo.sh to attest to successful completion"
-                echo "DO NOT manually run stamp_repo.sh on your branch to bypass this step - the output timestamp/hash is used to verify internal testcase sign-off is successful"
-                exit 1
+            # Find the last commit that modified any design file (not documentation)
+            # Start the search with the second parent of the PR merge commit
+            # in order to only traverse the feature branch commits
+            last_commit=$(git rev-parse HEAD^2)
+            until git diff --name-only "${last_commit}^..${last_commit}" | grep -v '\.md\|\.png' > /dev/null; do
+                last_commit="$(git rev-parse ${last_commit}^)"
+            done
+            echo "Latest non-doc hash is ${last_commit}"
+            # If the last non-doc commit is already contained in branch 'main', then skip the
+            # timestamp check -- as that commit would already be signed off through another PR.
+            # Otherwise, that commit would fail because it's part of a commit that was squashed into main
+            # much later than the original stamp commit.
+            if [[ $(git branch --remotes --list 'origin/main' --contains ${last_commit}) =~ 'origin/main' ]]; then
+                echo "Commit ${last_commit} is contained in branch 'main', skipping timestamp check"
+            else
+                # Compare the timestamp from the latest commit with the pr_timestamp file
+                timestamp_exp=$(bc <<< "$(git log -n1 --pretty=tformat:'%ct' ${last_commit})-3600")
+                if [[ ! -f $GITHUB_WORKSPACE/.github/workflow_metadata/pr_timestamp ]]; then
+                    echo "Error, file not found: $GITHUB_WORKSPACE/.github/workflow_metadata/pr_timestamp"
+                    exit 1
+                fi
+                timestamp=$(tail -1 $GITHUB_WORKSPACE/.github/workflow_metadata/pr_timestamp)
+                if [[ ${timestamp} -lt ${timestamp_exp} ]]; then
+                    echo "Error, submitted timestamp [${timestamp}] is outdated: it precedes the latest non-documentation commit to branch by more than an hour [${timestamp_exp}]"
+                    echo "Please rerun any internal/company proprietary testcases, which should invoke .github/scripts/stamp_repo.sh to attest to successful completion"
+                    echo "DO NOT manually run stamp_repo.sh on your branch to bypass this step - the output timestamp/hash is used to verify internal testcase sign-off is successful"
+                    exit 1
+                fi
+                echo "Submitted timestamp [${timestamp}] meets the recency requirement: [${timestamp_exp}]"
             fi
-            echo "Submitted timestamp [${timestamp}] meets the recency requirement: [${timestamp_exp}]"
 
       - name: Check Hash
         run: |

diff --git a/README.md b/README.md
@@ -14,7 +14,7 @@ See the License for the specific language governing permissions and<BR>
 limitations under the License.*_<BR>
 
 # **Caliptra Hands-On Guide** #
-_*Last Update: 2024/04/01*_
+_*Last Update: 2024/07/02*_
 
 
 ## **Tools Used** ##
@@ -51,6 +51,10 @@ GCC:
  - G++ Used to compile Verilator objects and test firmware
    - `g++ (GCC) 11.2.0`
 
+CDC:
+ - Questa CDC
+   - `2023.3 5624840 linux_x86_64 19-Jul-2023`
+
 RDC:
  - Real Intent Meridian
    - `2019.A.P16`
@@ -85,21 +89,24 @@ with the provided Makefile for compiling test C programs.
 ## **ENVIRONMENT VARIABLES** ##
 Required for simulation:<BR>
 `CALIPTRA_WORKSPACE`: Defines the absolute path to the directory where the Verilator "scratch" output directory will be created. Recommended to define as the absolute path to the directory that contains the Project repository root (called "Caliptra" or "caliptra-rtl")<BR>
-`CALIPTRA_ROOT`: Defines the absolute path to the Project repository root (called "Caliptra" or "caliptra-rtl"). Recommended to define as `${CALIPTRA_WORKSPACE}/Caliptra`.<BR>
+`CALIPTRA_ROOT`: Defines the absolute path to the Project repository root (called "Caliptra" or "caliptra-rtl"). Recommended to define as `${CALIPTRA_WORKSPACE}/caliptra-rtl`.<BR>
 
 Required for Firmware (i.e. Test suites) makefile:<BR>
   `TESTNAME`: Contains the name of one of the tests listed inside the `src/integration/test_suites` folder; only used for `caliptra_top_tb` tests<BR>
 
 ## **Repository Overview** ##
 ```
-Caliptra
+caliptra-rtl
 |-- LICENSE
 |-- README.md
 |-- Release_Notes.md
+|-- SECURITY.md
 |-- docs
-|   |-- Caliptra_Integration_Specification.pdf
-|   |-- Caliptra_Hardware_Specification.pdf
-|   `-- Caliptra_TestPlan.xlsx
+|   |-- CaliptraHardwareSpecification.md
+|   |-- CaliptraIntegrationSpecification.md
+|   |-- CaliptraReleaseChecklist.md
+|   |-- Caliptra_TestPlan.xlsx
+|   `-- images
 |-- src
 |   |-- aes
 |   |-- ahb_lite_bus
@@ -138,7 +145,7 @@ The "Integration" sub-component contains the top-level fileset for Caliptra. `sr
 
 
 ## **Verilog File Lists** ##
-Verilog file lists are generated via VCS and included in the config directory for each unit. New files added to the design should be included in the vf list. They can be included manually or by using VCS to regenerate the vf file. File lists define the compilation sources (including all dependencies) required to build and simulate a given module or testbench, and should be used for simulation, lint, and synthesis.
+Verilog file lists are generated via VCS and included in the config directory for each unit. New files added to the design must be included in the vf list. They can be included manually or by using VCS to regenerate the vf file. File lists define the compilation sources (including all dependencies) required to build and simulate a given module or testbench, and should be used by integrators for simulation, lint, and synthesis.
 
 ## **Scripts Description** ##
 
@@ -159,24 +166,49 @@ Verilog file lists are generated via VCS and included in the config directory fo
 
 ### Caliptra Top VCS Steps: ###
 1. Setup tools, add to PATH (ensure RISC-V toolchain is also available)
-2. Define all environment variables above
+1. Define all environment variables above
     - For the initial test run after downloading repository, `iccm_lock` is recommended for TESTNAME
-    - See [Regression Tests](#Regression-Tests) for information about available tests.
-3. Create a run folder for build outputs (and cd to it)
-4. [OPTIONAL] By default, this run flow will use the RISC-V toolchain to compile test firmware (according to TESTNAME) into program.hex, iccm.hex, dccm.hex, and mailbox.hex. As a first pass, integrators may alternatively use the pre-built hexfiles for convenience (available for [iccm_lock](src/integration/test_suites/iccm_lock) test). To do this, copy [iccm_lock.hex](src/integration/test_suites/iccm_lock/iccm_lock.hex) to the run directory and rename to `program.hex`. [dccm.hex](src/integration/test_suites/iccm_lock/iccm_lock.hex) should also be copied to the run directory, as-is. Use `touch iccm.hex mailbox.hex` to create empty hex files, as these are unnecessary for `iccm_lock` test.
-5. Invoke `${CALIPTRA_ROOT}/tools/scripts/Makefile` with target 'program.hex' to produce SRAM initialization files from the firmware found in `src/integration/test_suites/${TESTNAME}`
+    - See [Regression Tests](#Regression-Tests) for information about available tests
+1. Create a run folder for build outputs (and cd to it)
+1. Either use the provided Makefile or execute each of the following steps manually to run VCS simulations
+1. Makefile usage:
+    - Example command:
+        `make -C <path/to/run/folder> -f ${CALIPTRA_ROOT}/tools/scripts/Makefile TESTNAME=${TESTNAME} vcs`
+    - NOTE: `TESTNAME=${TESTNAME}` is optional; if not provided, test defaults to value of TESTNAME environment variable, then to `iccm_lock`
+    - NOTE: Users may wish to produce a run log by piping the make command to a tee command, e.g.:
+        `make ... <args> ... | tee <path/to/run/folder>/vcs.log`
+    - NOTE: The following macro values may be overridden to define the hardware configuration that is built. Default values in the Makefile are shown with each macro:
+      - CALIPTRA_INTERNAL_QSPI=1
+      - CALIPTRA_INTERNAL_UART=1
+      - CALIPTRA_INTERNAL_I3C=0
+      - CALIPTRA_INTERNAL_TRNG=1
+      - E.g. `make -f ${CALIPTRA_ROOT}/tools/scripts/Makefile CALIPTRA_INTERNAL_QSPI=0 CALIPTRA_INTERNAL_UART=0 CALIPTRA_INTERNAL_I3C=0 CALIPTRA_INTERNAL_TRNG=1 vcs`
+1. Remaining steps describe how to manually run the individual steps for a VCS simulation
+1. [OPTIONAL] By default, this run flow will use the RISC-V toolchain to compile test firmware (according to TESTNAME) into program.hex, iccm.hex, dccm.hex, and mailbox.hex. As a first pass, integrators may alternatively use the pre-built hexfiles for convenience (available for [iccm_lock](src/integration/test_suites/iccm_lock) test). To do this, copy [iccm_lock.hex](src/integration/test_suites/iccm_lock/iccm_lock.hex) to the run directory and rename to `program.hex`. [dccm.hex](src/integration/test_suites/iccm_lock/iccm_lock.hex) should also be copied to the run directory, as-is. Use `touch iccm.hex mailbox.hex` to create empty hex files, as these are unnecessary for `iccm_lock` test.
+1. Invoke `${CALIPTRA_ROOT}/tools/scripts/Makefile` with target 'program.hex' to produce SRAM initialization files from the firmware found in `src/integration/test_suites/${TESTNAME}`
     - E.g.: `make -f ${CALIPTRA_ROOT}/tools/scripts/Makefile program.hex`
     - NOTE: TESTNAME may also be overridden in the makefile command line invocation, e.g. `make -f ${CALIPTRA_ROOT}/tools/scripts/Makefile TESTNAME=iccm_lock program.hex`
-6. Compile complete project using `src/integration/config/caliptra_top_tb.vf` as a compilation target in VCS. When running the `vcs` command to generate simv, users should ensure that `caliptra_top_tb` is explicitly specified as the top-level component in their command to ensure this is the sole "top" that gets simulated.
-7. Copy the test generator scripts to the run output directory:
+    - NOTE: The following macro values must be overridden to match the value provided (later) during hardware compilation. The full L0 regression suite includes tests that will fail if the firmware and hardware configuration has a discrepancy. Default values in the Makefile are shown with each macro:
+      - CALIPTRA_INTERNAL_QSPI=1
+      - CALIPTRA_INTERNAL_UART=1
+      - CALIPTRA_INTERNAL_I3C=0
+      - CALIPTRA_INTERNAL_TRNG=1
+      - E.g. `make -f ${CALIPTRA_ROOT}/tools/scripts/Makefile CALIPTRA_INTERNAL_QSPI=0 CALIPTRA_INTERNAL_UART=0 CALIPTRA_INTERNAL_I3C=0 CALIPTRA_INTERNAL_TRNG=1 program.hex`
+1. Compile complete project using `src/integration/config/caliptra_top_tb.vf` as a compilation target in VCS. When running the `vcs` command to generate simv, users should ensure that `caliptra_top_tb` is explicitly specified as the top-level component in their command to ensure this is the sole "top" that gets simulated.
+    - NOTE: The following macro values must be defined (or omitted) to match the value provided during firmware compilation. The full L0 regression suite includes tests that will fail if the firmware and hardware configuration has a discrepancy.
+      - CALIPTRA_INTERNAL_QSPI
+      - CALIPTRA_INTERNAL_UART
+      - CALIPTRA_INTERNAL_I3C
+      - CALIPTRA_INTERNAL_TRNG
+1. Copy the test generator scripts to the run output directory:
     - [src/ecc/tb/ecdsa_secp384r1.exe](src/ecc/tb/ecdsa_secp384r1.exe)
         * Necessary for [randomized_pcr_signing](src/integration/test_suites/randomized_pcr_signing)
         * OPTIONAL otherwise
     - [src/doe/tb/doe_test_gen.py](src/doe/tb/doe_test_gen.py)
         * Allows use of randomized secret field inputs during testing.
         * Required when using the `+RAND_DOE_VALUES` plusarg during simulation
         * Also required for several smoke tests that require randomized DOE IV, such as smoke_test_doe_scan, smoke_test_doe_rand, smoke_test_doe_cg
-8. Simulate project with `caliptra_top_tb` as the top target
+1. Simulate project with `caliptra_top_tb` as the top target
 
 ### Caliptra Top Verilator Steps: ###
 1. Setup tools, add to PATH (ensure Verilator, GCC, and RISC-V toolchain are available)
Original file line number	Diff line number	Diff line change
		@@ -1 +1 @@
		bb9b6ce589cb68131b3e0ce41458413628b5147fa58aef11d079e36b1053944ac65c092e4fcfe7c2b90031ee115d0d84
		fde9d1079e553c77020a67730f8725c220f1dd5d6d8d9ec3c1d6415f79ea7573075c3787c14674c943c9b93d45866199