Initial Pre0p8 release from dev-msft (#9)

* Doc file updates, no source code/scripts yet

* Remove MSFT copyright

* Remove Coming_soon.txt

* Delete VERSION.txt

* Dev msft 03022023 (#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:/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:/secworks/sha512
+ - Deobfuscation block – Built on https:/secworks/aes but NOT ROM/FW accessible
+ - SHA256 – https:/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:/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:/secworks/sha512
+ - Deobfuscation block – Built on https:/secworks/aes but NOT ROM/FW accessible
+ - SHA256 – https:/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
+