add documentation

.github/workflows/auto-update-caravel-lite.yml

@@ -48,10 +48,10 @@ jobs:
           git config --global init.defaultBranch main
           git init
           git checkout -b main
-          git remote add parent https://github.com/efabless/caravel_openframe
+          git remote add parent https://github.com/efabless/caravel
           git pull parent main
           git fetch --all --tags
           git filter-repo --path openlane/user_project_wrapper_empty --path openlane/user_analog_project_wrapper_empty --path openlane/Makefile --path gds/user_project_wrapper_empty.gds.gz --path gds/user_analog_project_wrapper_empty.gds.gz --path mag/user_project_wrapper_empty.mag --path mag/user_analog_project_wrapper_empty.mag --path lef/user_project_wrapper_empty.lef --path lef/user_analog_project_wrapper_empty.lef --path verilog/ --path Makefile --path scripts/ --path LICENSE --path manifest --path spi/lvs/run_lvs.sh --path gds/gds2mag-all.sh --path gds/drc_on_gds.tcl --path gds/antenna_on_gds.tcl --path spi/lvs/caravel.spice --path spi/lvs/caravan.spice --force
-          git remote add caravel_lite https://x-access-token:${{ secrets.EFSTAFF_TOKEN }}@github.com/efabless/caravel_openframe-lite
+          git remote add caravel_lite https://x-access-token:${{ secrets.EFSTAFF_TOKEN }}@github.com/efabless/caravel-lite
           git push --force caravel_lite main
           git push -f --tags caravel_lite main

.readthedocs.yml

@@ -0,0 +1,28 @@
+# SPDX-FileCopyrightText: 2020 Efabless Corporation
+#
+# 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.
+#
+# SPDX-License-Identifier: Apache-2.0
+# .readthedocs.yml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  configuration: docs/source/conf.py
+
+conda:
+  environment: docs/environment.yml

.travis.yml

@@ -0,0 +1,109 @@
+# SPDX-FileCopyrightText: 2020 Efabless Corporation
+#
+# 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.
+# SPDX-License-Identifier: Apache-2.0
+
+language: python
+
+branches:
+  only:
+    - develop
+    - master
+    - fix_gpio
+    - /^(?i:develop)-.*$/
+
+services:
+    - docker
+
+os:
+  - linux
+
+notifications:
+  slack: efabless-team:XAEJOuCet9xQ14EEIO0nNufd
+
+env:
+  global:
+    - OPENLANE_TAG=v0.20
+stages:
+  - commit-compliance
+  - test
+
+jobs:
+  include:
+    - name: "The README.rst Consistency Test"
+      stage: commit-compliance
+      script: bash .travisCI/base_checks/git-check.sh
+    - name: "The Manifest Test"
+      stage: commit-compliance
+      script: bash .travisCI/base_checks/manifest-check.sh
+    - name: "The Caravel LVS Test"
+      stage: test
+      install: bash .travisCI/utils/bash_run_wrapper.sh .travisCI/utils/pdkBuild.sh
+      script: bash .travisCI/utils/bash_run_wrapper.sh ".travisCI/lvs/lvs-check.sh caravel"
+    - name: "The Caravan LVS Test"
+      stage: test
+      install: bash .travisCI/utils/bash_run_wrapper.sh .travisCI/utils/pdkBuild.sh
+      script: bash .travisCI/utils/bash_run_wrapper.sh ".travisCI/lvs/lvs-check.sh caravan"
+    - name: "The chio_io LVS Test"
+      stage: test
+      install: bash .travisCI/utils/bash_run_wrapper.sh .travisCI/utils/pdkBuild.sh
+      script: bash .travisCI/utils/bash_run_wrapper.sh ".travisCI/lvs/lvs-check.sh chip_io"
+    - name: "The chip_io_alt LVS Test"
+      stage: test
+      install: bash .travisCI/utils/bash_run_wrapper.sh .travisCI/utils/pdkBuild.sh
+      script: bash .travisCI/utils/bash_run_wrapper.sh ".travisCI/lvs/lvs-check.sh chip_io_alt"
+    - name: "The mgmt_core LVS Test"
+      stage: test
+      install: bash .travisCI/utils/bash_run_wrapper.sh .travisCI/utils/pdkBuild.sh
+      script: bash .travisCI/utils/bash_run_wrapper.sh ".travisCI/lvs/lvs-check.sh mgmt_core"
+    - name: "The Rest of the Blocks LVS Test"
+      stage: test
+      install: bash .travisCI/utils/bash_run_wrapper.sh .travisCI/utils/pdkBuild.sh
+      script: bash .travisCI/utils/bash_run_wrapper.sh ".travisCI/lvs/lvs-check.sh all"
+    # - name: "The Caravel MAGLEF LVS Test"
+    #   stage: test
+    #   install: sh .travisCI/utils/bash_run_wrapper.sh .travisCI/utils/pdkBuild.sh
+    #   script: bash .travisCI/lvs/maglef-lvs-check.sh
+    - name: "The GDS Pointers Test"
+      stage: test
+      script: bash .travisCI/base_checks/gds-pointers.sh
+    - name: "The mgmt_soc DV Test: Set 1"
+      stage: test
+      if: branch = master OR type=cron
+      install: bash .travisCI/utils/bash_run_wrapper.sh .travisCI/utils/pdkBuild.sh
+      script: bash .travisCI/dv/dv-check-wrapper.sh mgmt_soc 1
+    - name: "The mgmt_soc DV Test: Set 2"
+      stage: test
+      if: branch = master OR type=cron
+      install: bash .travisCI/utils/bash_run_wrapper.sh .travisCI/utils/pdkBuild.sh
+      script: bash .travisCI/dv/dv-check-wrapper.sh mgmt_soc 2
+    - name: "The mgmt_soc DV Test: Set 3"
+      stage: test
+      if: branch = master OR type=cron
+      install: bash .travisCI/utils/bash_run_wrapper.sh .travisCI/utils/pdkBuild.sh
+      script: bash .travisCI/dv/dv-check-wrapper.sh mgmt_soc 3
+    - name: "The mgmt_soc DV Test: Set 4"
+      stage: test
+      if: branch = master OR type=cron
+      install: bash .travisCI/utils/bash_run_wrapper.sh .travisCI/utils/pdkBuild.sh
+      script: bash .travisCI/dv/dv-check-wrapper.sh mgmt_soc 4
+    - name: "The mgmt_soc DV Test: Set 5"
+      stage: test
+      if: branch = master OR type=cron
+      install: bash .travisCI/utils/bash_run_wrapper.sh .travisCI/utils/pdkBuild.sh
+      script: bash .travisCI/dv/dv-check-wrapper.sh mgmt_soc 5
+    - name: "The wb_utests DV Test"
+      stage: test
+      if: branch = master OR type=cron
+      install: bash .travisCI/utils/bash_run_wrapper.sh .travisCI/utils/pdkBuild.sh
+      script: bash .travisCI/dv/dv-check-wrapper.sh wb_utests 1

.travisCI/base_checks/gds-pointers.sh

@@ -0,0 +1,23 @@
+#!/bin/bash
+# SPDX-FileCopyrightText: 2020 Efabless Corporation
+#
+# 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.
+# SPDX-License-Identifier: Apache-2.0
+
+set -e
+
+cnt=$(grep -L "string GDS_FILE ../gds/" maglef/*.mag | wc -l)
+echo "count of maglef files without gds pointer: $cnt"
+
+if [ $cnt -eq 0 ]; then exit 0; fi
+exit 2

.travisCI/base_checks/git-check.sh

@@ -0,0 +1,43 @@
+#!/bin/bash
+# SPDX-FileCopyrightText: 2020 Efabless Corporation
+#
+# 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.
+# SPDX-License-Identifier: Apache-2.0
+
+set -e
+
+echo "Current git status"
+
+git status
+
+echo "Deleting README.rst & openlane/README.rst"
+rm -rf README.rst
+rm -rf openlane/README.rst
+
+echo "Running make README.rst"
+make README.rst -B
+
+echo "New git status"
+TMP_FILE=git_dif_tmp_file
+git diff > $TMP_FILE
+
+git status
+
+echo "git diff:"
+cat $TMP_FILE
+
+cnt=$(cat $TMP_FILE | wc -l)
+echo $cnt
+rm -f $TMP_FILE
+if [[ $cnt -gt 1 ]]; then exit 2; fi
+exit 0

.travisCI/base_checks/manifest-check.sh

@@ -0,0 +1,32 @@
+#!/bin/bash
+# SPDX-FileCopyrightText: 2020 Efabless Corporation
+#
+# 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.
+# SPDX-License-Identifier: Apache-2.0
+
+TARGET_PATH=$(pwd)/
+OUT_FILE=tmp_manifest_output_file
+echo "Going into $TARGET_PATH"
+cd $TARGET_PATH
+if [[ -f "manifest" ]]; then
+    echo "Running shasum checks"
+    shasum -c manifest > $OUT_FILE
+    cat $OUT_FILE
+    cnt=$(grep "FAILED" $OUT_FILE | wc -l)
+    rm -f $OUT_FILE
+    if [[ $cnt -eq 0 ]]; then exit 0; fi
+    exit 2;
+else
+    echo "manifest file doesn't exist"
+    exit 2 
+fi

.travisCI/dv/dv-check-wrapper.sh

@@ -0,0 +1,52 @@
+#!/bin/bash
+# SPDX-FileCopyrightText: 2020 Efabless Corporation
+#
+# 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.
+# SPDX-License-Identifier: Apache-2.0
+export TARGET_PATH=$(pwd)
+cd ../
+export PDK_PATH=$(pwd)/pdks/sky130A
+export PDK_ROOT=$(pwd)/pdks
+export GCC_PATH=/opt/riscv32i/bin
+export GCC_PREFIX=riscv32-unknown-elf
+
+cd $TARGET_PATH
+
+export RUN_WRAPPER=$TARGET_PATH/.travisCI/utils/run_wrapper.sh
+
+target_dv=$1
+target_id=$2
+
+bash $RUN_WRAPPER "docker pull efabless/dv_setup:latest"
+
+docker run -it -v $TARGET_PATH:$TARGET_PATH -v $PDK_PATH:$PDK_PATH -v $PDK_ROOT:$PDK_ROOT\
+            -e TARGET_PATH=$TARGET_PATH -e PDK_PATH=$PDK_PATH -e PDK_ROOT=$PDK_ROOT -e GCC_PATH=$GCC_PATH -e GCC_PREFIX=$GCC_PREFIX  \
+            -u $(id -u $USER):$(id -g $USER) efabless/dv_setup:latest \
+            bash -c "bash $TARGET_PATH/.travisCI/dv/run-dv-$target_dv.sh $PDK_PATH $TARGET_PATH $target_id"
+
+echo "DONE!"
+
+VERDICT_FILE=$TARGET_PATH/$target_dv\_verdict.out
+cat $VERDICT_FILE
+if [ -f $VERDICT_FILE ]; then
+        cnt=$(grep "PASS" $VERDICT_FILE -s | wc -l)
+        if ! [[ $cnt ]]; then cnt = 0; fi
+else
+        echo "DV check failed due to subscript failure. Please review the logs";
+        exit 2;
+fi
+
+echo "Verdict: $cnt"
+
+if [[ $cnt -eq 1 ]]; then exit 0; fi
+exit 2;

.travisCI/dv/run-dv-mgmt_soc.sh

@@ -0,0 +1,80 @@
+#!/bin/bash
+# SPDX-FileCopyrightText: 2020 Efabless Corporation
+#
+# 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.
+# SPDX-License-Identifier: Apache-2.0
+
+PDK_PATH=$1
+TARGET_PATH=$2
+ID=$3
+MGMT_SOC_PATTERNS_1=(gpio perf hkspi sysctrl)
+MGMT_SOC_PATTERNS_2=(mprj_ctrl pass_thru user_pass_thru storage)
+MGMT_SOC_PATTERNS_3=(uart irq)
+MGMT_SOC_PATTERNS_4=(timer timer2 caravan)
+MGMT_SOC_PATTERNS_5=(mem pll qspi)
+
+VERDICT_FILE=$TARGET_PATH/mgmt_soc_verdict.out
+OUT_FILE=$TARGET_PATH/mgmt_soc_dv.$ID.out
+
+case $ID in
+
+  1)
+    bash $TARGET_PATH/.travisCI/dv/run-dv-set.sh $PDK_PATH "${MGMT_SOC_PATTERNS_1[@]}" caravel mgmt_soc 1 $TARGET_PATH
+    len=${#MGMT_SOC_PATTERNS_1[@]}
+    export TOTAL=$(( 2*len ))
+    ;;
+
+  2)
+    bash $TARGET_PATH/.travisCI/dv/run-dv-set.sh $PDK_PATH "${MGMT_SOC_PATTERNS_2[@]}" caravel mgmt_soc 2 $TARGET_PATH
+    len=${#MGMT_SOC_PATTERNS_2[@]}
+    export TOTAL=18
+    ;;
+
+  3)
+    bash $TARGET_PATH/.travisCI/dv/run-dv-set.sh $PDK_PATH "${MGMT_SOC_PATTERNS_3[@]}" caravel mgmt_soc 3 $TARGET_PATH
+    len=${#MGMT_SOC_PATTERNS_3[@]}
+    export TOTAL=$(( 2*len ))
+    ;;
+
+  4)
+    bash $TARGET_PATH/.travisCI/dv/run-dv-set.sh $PDK_PATH "${MGMT_SOC_PATTERNS_4[@]}" caravel mgmt_soc 4 $TARGET_PATH
+    len=${#MGMT_SOC_PATTERNS_4[@]}
+    export TOTAL=$(( 2*len ))
+    ;;
+
+  5)
+    bash $TARGET_PATH/.travisCI/dv/run-dv-set.sh $PDK_PATH "${MGMT_SOC_PATTERNS_5[@]}" caravel mgmt_soc 5 $TARGET_PATH
+    len=${#MGMT_SOC_PATTERNS_5[@]}
+    export TOTAL=10
+    ;;
+
+  *)
+    echo -n "unknown ID $ID"
+    exit 2
+    ;;
+esac
+
+cnt=$(grep -i "Passed" $OUT_FILE | wc -l)
+
+
+echo "total passed expected: $TOTAL"
+echo "passed found: $cnt"
+if [[ $cnt -eq $TOTAL ]]; then echo "PASS" > $VERDICT_FILE; exit 0; fi
+
+echo "FAIL" > $VERDICT_FILE
+
+
+echo "Total Verdict File:"
+cat $VERDICT_FILE
+
+exit 0