Initial Pre0p8 release from dev-msft (chipsalliance#9)

* Doc file updates, no source code/scripts yet

* Remove MSFT copyright

* Remove Coming_soon.txt

* Delete VERSION.txt

* Dev msft 03022023 (chipsalliance#2)

* Initial Pre0p8 release

* Fixed typos in release notes

* Delete autogenerated register doc HTML.

* Add a GitHub workflow to autogenerate the register docs.

* Adding updating README.md

* Rename 0.8 doc directory to main.

* Updated repo name to caliptra-rtl and set WORKSPACE env variable to point to caliptra-rtl directory

---------

Co-authored-by: Anjana Parthasarathy <[email protected]>
Co-authored-by: Kor Nielsen <[email protected]>
Co-authored-by: Kor Nielsen <[email protected]>

---------

Co-authored-by: Caleb Whitehead <[email protected]>
Co-authored-by: Anjana Parthasarathy <[email protected]>
Co-authored-by: Kor Nielsen <[email protected]>
Co-authored-by: Kor Nielsen <[email protected]>

.github/workflows/doc-gen.yml

@@ -0,0 +1,63 @@
+# docs: https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions
+
+name: Register Documentation
+
+on:
+  workflow_dispatch:
+  pull_request:
+  push:
+    branches: ["main"]
+
+jobs:
+  build:
+    name: Build
+
+    runs-on: ubuntu-22.04
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Install peakrd-uvm
+        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
+
+      - name: Generate docs
+        run: |
+          echo Running script
+          tools/scripts/reg_doc_gen.sh
+
+      - name: Stage documents
+        run: |
+          mkdir -p /tmp/pages-docs/main
+          cp -R src/integration/docs/caliptra_reg_html /tmp/pages-docs/main/internal-regs
+          cp -R src/soc_ifc/docs/caliptra_top_reg_html /tmp/pages-docs/main/external-regs
+          find /tmp/pages-docs
+
+      - name: Generate GitHub Pages artifacts
+        uses: actions/upload-pages-artifact@v1
+        with:
+          path: /tmp/pages-docs
+
+  deploy:
+    name: Deploy
+    needs: build
+    if: github.event_name == 'push'
+
+    permissions:
+      pages: write
+      id-token: write
+
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    runs-on: ubuntu-22.04
+
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v1

.gitignore

@@ -0,0 +1,2 @@
+src/integration/docs/caliptra_reg_html/
+src/soc_ifc/docs/caliptra_top_reg_html/

LICENSE

@@ -1,3 +1,4 @@
+
                                  Apache License
                            Version 2.0, January 2004
                         http://www.apache.org/licenses/

README.md

@@ -1,2 +1,161 @@
-# caliptra-fw
-RTL and verification for Caliptra RoT IP
+_*SPDX-License-Identifier: Apache-2.0<BR>
+<BR>
+<BR>
+Licensed under the Apache License, Version 2.0 (the "License");<BR>
+you may not use this file except in compliance with the License.<BR>
+You may obtain a copy of the License at<BR>
+<BR>
+http://www.apache.org/licenses/LICENSE-2.0 <BR>
+<BR>
+Unless required by applicable law or agreed to in writing, software<BR>
+distributed under the License is distributed on an "AS IS" BASIS,<BR>
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.<BR>
+See the License for the specific language governing permissions and<BR>
+limitations under the License.*_<BR>
+
+# **Caliptra Hands-On Guide** #
+_*Last Update: 2023/03/02*_
+
+[[_TOC_]]
+
+## **Tools Used** ##
+
+OS:
+ - Build instructions assume a Linux environment
+
+Lint:
+ - Synopsys Spyglass
+   - `Version S-2021.09-1`
+ - Real Intent AscentLint
+   - `Version 2019.A.p15 for RHEL 6.0-64, Rev 116515, Built On 12/18/2020`
+
+Simulation:
+ - Synopsys VCS with Verdi
+   - `Version R-2020.12-SP2-7_Full64`
+ - Verilator
+   - `Version 4.228`
+ - Mentor Graphics QVIP
+   - `Version 2021.2.1` of AHB/APB models
+ - UVM installation
+   - `Version 1.1d`
+
+Synthesis:
+ - Synopsys DC
+   - `Version 2020.09-SP1`
+
+GCC:
+ - RISCV Toolchain for generating memory initialization files
+   - `riscv64-unknown-elf-gcc-8.2.0-2019.02.0-x86_64-linux-centos6`
+ - G++ Used to compile Verilator objects
+   - `g++ (GCC) 8.2.0`
+
+Other:
+ - Playbook (Microsoft Internal workflow management tool)
+
+## **ENVIRONMENT VARIABLES** ##
+Required for simulation:<BR>
+`WORKSPACE`: Defines the absolute path to the directory that contains the Project repository root (called "Caliptra")<BR>
+
+Required for Firmware (i.e. Test suites) makefile:<BR>
+  `SIM_TOOLS_TOP_COMPILE_ROOT`: Absolute path pointing to the folder `src/integration` inside the repository<BR>
+  `TESTNAME`: Contains the name of one of the tests listed inside the `src/integration/test_suites` folder<BR>
+
+## **Repository Overview** ##
+```
+Caliptra
+|-- LICENSE
+|-- README.md
+|-- Release_notes.txt
+|-- docs
+|   |-- Caliptra_Integration_Specification.pdf
+|   |-- Caliptra_Hardware_Spec.pdf
+|   |-- Caliptra_TestPlan_L1.pdf
+|-- src
+|   |-- ahb_lite_bus
+|   |-- datavault
+|   |-- doe
+|   |-- ecc
+|   |-- hmac
+|   |-- hmac_drbg
+|   |-- integration
+|   |-- keyvault
+|   |-- libs
+|   |-- pcrvault
+|   |-- riscv_core
+|   |-- sha256
+|   |-- sha512
+|   |-- soc_ifc
+`-- tools
+    |-- config
+    |-- README
+    `-- scripts
+```
+The root of the repository is structured as shown above, to a depth of 2 layers.<BR>
+Each sub-component is accompanied by a file list summary (located in src/<component>/config/<name>.vf) that comprises all the filenames required to compile the component, and an optional testbench filelist for unit-level simulation. <BR>
+VF files provide absolute filepaths (prefixed by the WORKSPACE environment variable) to each compile target for the associated component.<BR>
+The "Integration" sub-component contains the top-level fileset for Caliptra. `src/integration/config/compile.yml` defines the required filesets and sub-component dependencies for this build target. All of the files/dependencies are explicitly listed in `src/integration/config/caliptra_top_tb.vf`. Users may compile the entire design using only this VF filelist.<BR>
+
+
+## **Scripts Description** ##
+
+`Makefile`: Makefile to generate SRAM initialization files from test firmware and to run Verilator simulation<BR>
+`run_test_makefile`: Wrapper used in Microsoft internal build flow to invoke Makefile for mem init file generation<BR>
+`reg_gen.py`: Used to compile/export RDL files to register source code<BR>
+`reg_gen.sh`: Wrapper used to call `reg_gen.py` for all IP cores in Caliptra<BR>
+`reg_doc_gen.py`: Used to compile/export top-level RDL address map to register source code, defining complete Caliptra address space, and produces HTML documentation<BR>
+`reg_doc_gen.sh`: Wrapper to invoke `reg_doc_gen.py`<BR>
+`rdl_post_process.py`: Post-processing functionality to make RDL generated SystemVerilog files compatible with lint/Verilator requirements<BR>
+`run_verilator_l0_regression.py`: Wrapper to run the L0 smoke test regression suite using the Makefile flow in Verilator<BR>
+`integration_vector_gen.py`: Generates test vectors for crypto core tests<BR>
+`veer_build_command.sh`: Shell script used to generate the VeeR-EL2 repository present in `src/riscv_core/veer_el2`<BR>
+
+## **Simulation Flow** ##
+VCS Steps:
+1. Setup tools, add to PATH (ensure riscv64-unknown-elf-gcc is also available)
+1. Define all environment variables above
+    - For the initial test run after downloading repository, `iccm_lock` is recommended for TESTNAME
+1. Create a run folder for build outputs (and cd to it)
+1. Invoke `${WORKSPACE}/Caliptra/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 ${WORKSPACE}/Caliptra/tools/scripts/Makefile 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.
+1. Simulate project with `caliptra_top_tb` as the top target
+
+Verilator Steps:
+1. Setup tools, add to PATH (ensure Verilator, GCC, and riscv64-unknown-elf-gcc are available)
+1. Define all environment variables above
+    - For the initial test run after downloading repository, `iccm_lock` is recommended for TESTNAME
+1. Create a run folder for build outputs
+    - Recommended to place run folder under `${WORKSPACE}/scratch/$USER/verilator/<date>`
+1. Run Caliptra/tools/scripts/Makefile, which provides steps to run a top-level simulation in Verilator
+    - Example command:
+        `make -C <path/to/run/folder> -f ${WORKSPACE}/Caliptra/tools/scripts/Makefile TESTNAME=${TESTNAME} debug=1 verilator`
+    - NOTE: `debug=1` is optional; if provided, the verilator run will produce a .vcd file with waveform information
+    - 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>/verilate.log`
+1. Users have the option to run the entire suite of smoke tests using the provided python script `run_verilator_l0_regression.py`
+    1. Ensure Python 3.9.2 is available by adding to the $PATH variable
+    1. Run the script with:
+        `python3 run_verilator_l0_regression.py`
+    1. NOTE: The script automatically creates run output folders at `${WORKSPACE}/scratch/$USER/verilator/<timestamp>/<testname>` for each test run
+    1. NOTE: The output folder is populated with a run log that reports the run results and pass/fail status
+
+UVM Testbench Steps for `caliptra_top`:<BR>
+Description:<BR>
+The UVM Framework generation tool was used to create the baseline UVM testbench for verification of the top-level Caliptra image. The top-level bench leverages the `soc_ifc_top` testbench as a subenvironment, to reuse environment level sequences, agents, register models, and predictors.
+
+Prerequisites:<BR>
+- QVIP 2021.2.1 for Mentor Graphics (provides the AHB/APB VIP)
+- UVM 1.1d installation
+
+Steps:<BR>
+1. Compile UVM 1.1d library
+1. Compile the AHB/APB QVIP source
+1. Compile the UVMF wrapper for APB/AHB in Caliptra/src/libs/uvmf
+1. Compile the `verification_ip` provided for `soc_ifc` found in `Caliptra/src/soc_ifc/uvmf_soc_ifc`
+1. Compile the `caliptra_top` testbench found in `Caliptra/src/integration/uvmf_caliptra_top`
+1. `Caliptra/src/integration/uvmf_caliptra_top/uvmf_template_output/project_benches/caliptra_top/tb/testbench/hdl_top.sv` is the top-level TB wrapper for the system
+1. Select a test to run from the set of tests in `Caliptra/src/integration/uvmf_caliptra_top/uvmf_template_output/project_benches/caliptra_top/tb/tests/src`
+1. Provide `+UVM_TESTNAME=<test>` argument to simulation
+
+## **NOTES** ##

Release_notes.txt

@@ -0,0 +1,83 @@
+_*Last Update: 2023/03/02*_
+
+# Release_notes.txt
+# Stores revision information for caliptra-rtl
+
+Pre0p8 release notes:
+-	DISCLAIMER: This is NOT A BUG-FREE MODEL. This is a pre-0p8 development model that will be sync’d every week. 
+    -   This model is released mainly for interface, floorplan planning purposes for consumers.
+    -   0p8 release date = 03-31-2023
+-	Caliptra Hardware Specification: see docs/ folder
+-	Caliptra Integration Specification: see docs/ folder
+-	Caliptra testplan: see docs/ folder
+-	CHIPALLIANCE RISC-V Core - https://github.com/chipsalliance/Cores-VeeR-EL2/
+    -   ICCM, DCCM enabled w/ 128KB each; Instruction Cache disabled; fast interrupt redirect enabled
+-	Cryptos (please see the spec for NIST compliance algorithms followed)
+    -   HMAC384 – Caliptra consortium provided (built based on SHA384 block below)
+    -   ECC384 – Based on secp384, Caliptra consortium provided
+    -   HMAC-DRBG – Caliptra consortium provided (but built using HMAC384 above)
+    -   Key Vault & PCR Vault – Caliptra consortium provided
+    -   SHA384/SHA512 – https://github.com/secworks/sha512
+    -   Deobfuscation block – Built on https://github.com/secworks/aes but NOT ROM/FW accessible
+    -   SHA256 – https://github.com/secworks/sha256
+    -   Side channel attack analysis and solutions where applicable  (Plz see Caliptra IP specification for details)
+-	AHB-lite internal fabric
+    -   Please see spec for decoding details of various blocks
+-	Key Vault, PCR Vault w/ HW PCR extension & Data Vault
+-	Interrupts from all peripherals (Cryptos, SOC mailbox, IOs, timers etc.)
+-	ICCM write locking
+-	TAP interface
+-	Idle Clock Gating
+-	Impactless update reset
+-	Mailbox SRAM ECC
+-	Security Assert Flushing in debug unlocked & scan modes
+-	SOC interface (APB, mailbox, architectural registers, fuse registers, external TRNG REQ, SHA384 acceleration) – Caliptra Consortium provided
+-	Lint clean to the rules published in the integration spec
+-	HTML (generated from RDLs) for all registers (internal registers, external facing architectural registers, fuse registers)
+-	RTL “Frozen” IP interface;  Frozen SOC facing registers.
+    -   All changes from hereon forth will require CHIPSALLIACE CALIPTRA WG approval
+-	Validation Notes:
+    -   DUT per crypto block and associated checkers
+    -   Nightly regression on crypto blocks on-going
+    -   Smoke tests for all of the above passing including bring up/boot of the caliptra IP (KV testing for ECC & SHA)
+    -   UVMF for multiple DUT blocks and SOC interface
+
+Rev rtl-caliptra_rtl_0.5.1
+-   Add missing printf/ and includes/ directories to src/integration/test_suites which are required to run the tests
+-   Updated Version.txt and tar.gz
+
+Rev rtl-caliptra_rtl_0.5rtl
+-	CHIPALLIANCE RISC-V Core - https://github.com/chipsalliance/Cores-VeeR-EL2
+    - ICCM, DCCM enabled w/ 128KB each; Instruction Cache disabled; fast interrupt redirect enabled
+-	Cryptos (please see the spec for NIST compliance algorithms followed)
+    - HMAC384 – Caliptra consortium provided (built based on SHA384 block below)
+    - ECC384 – Based on secp384, Caliptra consortium provided
+    - HMAC-DRBG – Caliptra consortium provided (but built using HMAC384 above)
+    - Key Vault & PCR Vault – Caliptra consortium provided
+    - SHA384/SHA512 – https://github.com/secworks/sha512
+    - Deobfuscation block – Built on https://github.com/secworks/aes but NOT ROM/FW accessible
+    - SHA256 – https://github.com/secworks/sha256
+    - Side channel attack analysis and solutions where applicable  (Plz see Caliptra IP specification for details)
+-	AHB-lite internal fabric
+    - Please see spec for decoding details of various blocks
+-   Interrupts from all peripherals (Cryptos, SOC mailbox, IOs, timers etc.)
+-	ICCM locking
+-	SOC interface (APB, mailbox, architectural registers, fuse registers, TRNG REQ protocol) – Caliptra Consortium provided
+-	Lint clean up is partially done
+-	HTML (generated from RDLs) for all registers (internal registers, external facing architectural registers, fuse registers)
+-	Stable IP interface (pending TRNG interface wires that is a new feature)
+-	Validation Notes:
+    - DUT per crypto block and associated checkers
+    - Nightly regression on crypto blocks on-going
+    - Smoke tests for all of the above passing including bring up/boot of the caliptra IP (KV testing for ECC & SHA are pending)
+    - UVMF for multiple DUT blocks and SOC interface
+    - NOTE: 0p8 release will have stress validation on SOC interface with random resets, clock gating, impactless update crossed with mailbox protocol etc.
+
+UPCOMGING CHANGES:
+
+RTL 0p8 Pending (Target):
+-	Timers, integrated-TRNG integration w/ Caliptra, Error domain logic
+-	Lots of bug fixes :-)
+-	DV complete of boot flow, reset flow, Fuses, SOC registers, Crypto blocks, Key vault, PCR Vault, Data Vault, TRNG REQ protocol, SHA384 acceleration
+
+

src/ahb_lite_bus/config/ahb_lite_bus.vf

@@ -0,0 +1,5 @@
++incdir+${WORKSPACE}/Caliptra/src/ahb_lite_bus/rtl
+${WORKSPACE}/Caliptra/src/ahb_lite_bus/rtl/ahb_lite_bus_inf.sv
+${WORKSPACE}/Caliptra/src/ahb_lite_bus/rtl/ahb_lite_address_decoder.sv
+${WORKSPACE}/Caliptra/src/ahb_lite_bus/rtl/ahb_lite_bus.sv
+${WORKSPACE}/Caliptra/src/ahb_lite_bus/rtl/ahb_lite_2to1_mux.sv

src/ahb_lite_bus/config/ahb_node_wrap.vf

@@ -0,0 +1,4 @@
++incdir+${WORKSPACE}/Caliptra/src/ahb_lite_bus/rtl
+${WORKSPACE}/Caliptra/src/ahb_lite_bus/rtl/ahb_bus.sv
+${WORKSPACE}/Caliptra/src/ahb_lite_bus/rtl/ahb_node.sv
+${WORKSPACE}/Caliptra/src/ahb_lite_bus/rtl/ahb_node_wrap.sv

src/ahb_lite_bus/config/compile.yml

@@ -0,0 +1,17 @@
+---
+provides: [ahb_lite_bus]
+schema_version: 2.4.0
+targets:
+  rtl:
+    directories: [$COMPILE_ROOT/rtl]
+    files:
+      - $COMPILE_ROOT/rtl/ahb_lite_bus_inf.sv
+      - $COMPILE_ROOT/rtl/ahb_lite_address_decoder.sv
+      - $COMPILE_ROOT/rtl/ahb_lite_bus.sv
+      - $COMPILE_ROOT/rtl/ahb_lite_2to1_mux.sv
+    tops: [ahb_lite_bus]
+  rtl_lint:
+    directories: []
+    waiver_files: 
+    - $COMPILE_ROOT/config/design_lint/ahb_lite_bus/sglint_waivers
+