Merge remote-tracking branch 'lnis_origin/dev' into ganesh_dev

.travis.yml

@@ -14,105 +14,99 @@ cache:
 # Currently sudo is not required, NO ENV is used
 
 # Supported Operating systems
-#os:
-#  - linux
-#  - osx
-# Create a matrix to branch the building environment
-matrix:
-  include:
-    - os: linux
-    # Compiler is specified in ./travis/common.sh
-      sudo: false
-      dist: bionic
-      compiler: g++-8
-      addons:
-        apt:
-          sources:
-          - ubuntu-toolchain-r-test # For newer GCC
-          - llvm_toolchain-trusty-7
-          packages:
-          - autoconf
-          - automake
-          - bash
-          - bison
-          - build-essential
-          - cmake
-          - ctags
-          - curl
-          - doxygen
-          - flex
-          - fontconfig
-          - g++-8
-          - gcc-8
-          - gdb
-          - git
-          - gperf
-          - iverilog
-          - libcairo2-dev
-          - libevent-dev
-          - libfontconfig1-dev
-          - liblist-moreutils-perl
-          - libncurses5-dev
-          - libx11-dev
-          - libxft-dev
-          - libxml++2.6-dev
-          - perl
-          - python
-          - python-lxml
-          - texinfo
-          - time
-          - valgrind
-          - zip
-          - qt5-default
-          - clang-format-7
-#    - os: osx
-#      osx_image: xcode10.2 # we target latest MacOS Mojave
-#      sudo: true
-#      compiler: gcc-4.9 # Use clang instead of gcc in MacOS
-#      addons:
-#        homebrew:
-#          packages:
-#          - bison
-#          - cmake
-#          - ctags
-#          - flex
-#          - fontconfig
-#          - git
-#          - gcc@6
-#          - gcc@4.9
-#          - gawk
-#          - icarus-verilog
-#          - libxml++
-#          - qt5
+dist: bionic
+compiler: g++-8
+addons:
+  apt:
+    sources:
+    - ubuntu-toolchain-r-test # For newer GCC
+    - llvm_toolchain-trusty-7
+    packages:
+    - autoconf
+    - automake
+    - bash
+    - bison
+    - build-essential
+    - cmake
+    - ctags
+    - curl
+    - doxygen
+    - flex
+    - fontconfig
+    - g++-8
+    - gcc-8
+    - gdb
+    - git
+    - gperf
+    - iverilog
+    - libcairo2-dev
+    - libevent-dev
+    - libfontconfig1-dev
+    - liblist-moreutils-perl
+    - libncurses5-dev
+    - libx11-dev
+    - libxft-dev
+    - libxml++2.6-dev
+    - perl
+    - python
+    - python-lxml
+    - texinfo
+    - time
+    - valgrind
+    - zip
+    - qt5-default
+    - clang-format-7
+#- os: osx
+#  osx_image: xcode10.2 # we target latest MacOS Mojave
+#  sudo: true
+#  compiler: gcc-4.9 # Use clang instead of gcc in MacOS
+#  addons:
+#    homebrew:
+#      packages:
+#      - bison
+#      - cmake
+#      - ctags
+#      - flex
+#      - fontconfig
+#      - git
+#      - gcc@6
+#      - gcc@4.9
+#      - gawk
+#      - icarus-verilog
+#      - libxml++
+#      - qt5
 
-before_install:
+before_script:
   - source .travis/common.sh
-
-install:
-  - DEPS_DIR="${HOME}/deps"
-  - mkdir -p ${DEPS_DIR} && cd ${DEPS_DIR}
-  - |
-    if [[ "${TRAVIS_OS_NAME}" == "linux" ]]; then
-      CMAKE_URL="https://cmake.org/files/v3.16/cmake-3.16.3-Linux-x86_64.tar.gz"
-      mkdir -p cmake && travis_retry wget --no-clobber --no-check-certificate --quiet -O - ${CMAKE_URL} | tar --strip-components=1 -xz -C cmake
-      export PATH=${DEPS_DIR}/cmake/bin:${PATH}
-      echo ${PATH}
-    else
-      brew install cmake || brew upgrade cmake
-    fi
-  - cmake --version
-  - cd -
   - source .travis/install.sh
 
+stages:
+  - name: Test
+    if: type != cron
+
+jobs:
+  include:
+    - stage: Test
+      name: "OpenFPGA + VPR7 regression tests"
+      script:
+        - source .travis/build.sh
+        - source .travis/openfpga_vpr7_reg_test.sh
+
+    - stage: Test
+      name: "OpenFPGA + VPR8 regression tests"
+      script:
+        - source .travis/build.sh
+        - source .travis/openfpga_vpr8_reg_test.sh
+
+#after_failure:
+#  - .travis/after_failure.sh
+
+#after_success:
+#  - .travis/after_success.sh
+
 script:
-  - .travis/script.sh
-  #- .travis/regression.sh
+  - true
 
-after_failure:
-  - .travis/after_failure.sh
-
-after_success:
-  - .travis/after_success.sh
 notifications:
   slack:
     secure: L8tzicFh+EKcK21GBA2m3rQ3jmnDdqiRXIZcb0iqYlhT0V5asYvCqwlpPDUDV1wmBXqPgRJBI/jitAJlKFWu74pLTVc6FscUIDYM7S0DJfHEcufLknZx88lMmmV0IsYLQe3/s89tWoudMf1bNBo/8YWzLDffqUQ7s/rTPD9SWLppb01X0Xm158oDlA0rWETs35nuNFgJxWcSyIyIvnRNE3dHjzmBETUR9mYDsUSYlcOI44FMD8rE6emicdkqdn1zVxScobrl4Dt2bPsMfKopgIKK1x+38AuaqQa7t5F5ICnF0WfxmQ6/TcRNwIij0fDu68w/fcU8SyV+Ex5aZBKYUU7PG7ELTOq+q1geDoTlbguvFSIT4EzqErc4hbJmcUn79BKLhdjshZtGihKatntJx2faXYNYGFjwmnPFRYpqsozydztgMjzv4prZ5yoh7jhoDiGj44QcpXlQ9otM17JdfqveowMLHBYzATsxIRG93irZfXG/E3S8FvXg8mYOIEn8UK7H6i8VWL3JHlw8RbpLdNLswZOUlpEaDAeTm5tvYcw7FGH2nlZ2e5aXLxN6dTovSSRztQHbWdJTGG0N+xldBXcCiChmok4nXGReIkMc+99nZjRsiCB0R16tCNb25/p7NAVkItfVe1qRTzdnhi1hdE7LPURK4kxoFRJ6sFVuYjw=

.travis/build.sh

@@ -0,0 +1,21 @@
+#!/bin/bash
+
+source .travis/common.sh
+set -e
+
+start_section "OpenFPGA.build" "${GREEN}Building..${NC}"
+cd ${TRAVIS_BUILD_DIR}
+mkdir build
+cd build
+
+if [[ $TRAVIS_OS_NAME == 'osx' ]]; then
+  cmake .. -DCMAKE_BUILD_TYPE=debug -DENABLE_VPR_GRAPHICS=off
+else
+  cmake .. -DCMAKE_BUILD_TYPE=debug
+fi
+make -j16
+
+# Return to upper directory
+cd ${TRAVIS_BUILD_DIR}
+
+end_section "OpenFPGA.build"

.travis/install.sh

@@ -4,18 +4,19 @@ source .travis/common.sh
 set -e
 
 ## Install necessary package which is not available on Travis CI 
-#export DEPS_DIR="${HOME}/deps"
-#mkdir -p ${DEPS_DIR} && cd ${DEPS_DIR}
-## Install CMake
-#if [[ "${TRAVIS_OS_NAME}" == "linux" ]]; then
-#  export CMAKE_URL="https://cmake.org/files/v3.13/cmake-3.13.0-rc3-Linux-x86_64.tar.gz"
-#  mkdir -p cmake && travis_retry wget --no-check-certificate --quiet -O - ${CMAKE_URL} | tar --strip-components=1 -xz -C cmake
-#  export PATH=${DEPS_DIR}/cmake/bin:${PATH}
-#  echo ${PATH}
-#else
-#  brew install cmake || brew upgrade cmake
-#fi
-#  cmake --version
+export DEPS_DIR="${HOME}/deps"
+mkdir -p ${DEPS_DIR} && cd ${DEPS_DIR}
+# Install CMake
+if [[ "${TRAVIS_OS_NAME}" == "linux" ]]; then
+  export CMAKE_URL="https://cmake.org/files/v3.16/cmake-3.16.3-Linux-x86_64.tar.gz"
+  mkdir -p cmake && travis_retry wget --no-check-certificate --quiet -O - ${CMAKE_URL} | tar --strip-components=1 -xz -C cmake
+  export PATH=${DEPS_DIR}/cmake/bin:${PATH}
+  echo ${PATH}
+else
+  brew install cmake || brew upgrade cmake
+fi
+cmake --version
+cd -
 #
 ## Install latest iVerilog. Since no deb is provided, compile from source codes
 #if [[ "${TRAVIS_OS_NAME}" == "linux" ]]; then
@@ -32,7 +33,8 @@ set -e
 #  export PATH=${DEPS_DIR}/iverilog-10_3/bin:${PATH}
 #  echo ${PATH}
 #fi
-#iverilog -V
+iverilog -V
+vvp -V
 #cd -
 
 

.travis/openfpga_vpr7_reg_test.sh

@@ -0,0 +1,30 @@
+#!/bin/bash
+set -e
+
+start_section "OpenFPGA+VPR7.TaskTun" "${GREEN}..Running_Regression..${NC}"
+cd ${TRAVIS_BUILD_DIR}
+
+###############################################
+# OpenFPGA with VPR7
+# TO BE DEPRECATED
+##############################################
+echo -e "Testing single-mode architectures";
+python3 openfpga_flow/scripts/run_fpga_task.py single_mode --debug --show_thread_logs
+#python3 openfpga_flow/scripts/run_fpga_task.py s298 
+
+echo -e "Testing multi-mode architectures";
+python3 openfpga_flow/scripts/run_fpga_task.py multi_mode --maxthreads 4 --debug --show_thread_logs
+
+echo -e "Testing compact routing techniques";
+python3 openfpga_flow/scripts/run_fpga_task.py compact_routing --debug --show_thread_logs
+
+echo -e "Testing tileable architectures";
+python3 openfpga_flow/scripts/run_fpga_task.py tileable_routing --debug --show_thread_logs
+
+echo -e "Testing Verilog generation with explicit port mapping ";
+python3 openfpga_flow/scripts/run_fpga_task.py explicit_verilog --debug --show_thread_logs
+
+echo -e "Testing Verilog generation with grid pin duplication ";
+python3 openfpga_flow/scripts/run_fpga_task.py duplicate_grid_pin --debug --show_thread_logs
+
+end_section "OpenFPGA+VPR7.TaskTun"

.travis/openfpga_vpr8_reg_test.sh

@@ -0,0 +1,115 @@
+#!/bin/bash
+
+set -e
+
+start_section "OpenFPGA.TaskTun" "${GREEN}..Running_Regression..${NC}"
+cd ${TRAVIS_BUILD_DIR}
+
+###############################################
+# OpenFPGA Shell with VPR8
+# (Will replace all the old tests)
+##############################################
+echo -e "Testing OpenFPGA Shell";
+
+echo -e "Testing configuration chain of a K4N4 FPGA";
+python3 openfpga_flow/scripts/run_fpga_task.py openfpga_shell/full_testbench/configuration_chain --debug --show_thread_logs
+python3 openfpga_flow/scripts/run_fpga_task.py openfpga_shell/preconfig_testbench/configuration_chain --debug --show_thread_logs
+
+echo -e "Testing fram-based configuration protocol of a K4N4 FPGA";
+python3 openfpga_flow/scripts/run_fpga_task.py openfpga_shell/full_testbench/configuration_frame --debug --show_thread_logs
+python3 openfpga_flow/scripts/run_fpga_task.py openfpga_shell/full_testbench/fast_configuration_frame --debug --show_thread_logs
+python3 openfpga_flow/scripts/run_fpga_task.py openfpga_shell/preconfig_testbench/configuration_frame --debug --show_thread_logs
+
+echo -e "Testing memory bank configuration protocol of a K4N4 FPGA";
+python3 openfpga_flow/scripts/run_fpga_task.py openfpga_shell/full_testbench/memory_bank --debug --show_thread_logs
+python3 openfpga_flow/scripts/run_fpga_task.py openfpga_shell/full_testbench/fast_memory_bank --debug --show_thread_logs
+python3 openfpga_flow/scripts/run_fpga_task.py openfpga_shell/preconfig_testbench/memory_bank --debug --show_thread_logs
+
+
+echo -e "Testing standalone (flatten memory) configuration protocol of a K4N4 FPGA";
+python3 openfpga_flow/scripts/run_fpga_task.py openfpga_shell/full_testbench/flatten_memory --debug --show_thread_logs
+python3 openfpga_flow/scripts/run_fpga_task.py openfpga_shell/preconfig_testbench/flatten_memory --debug --show_thread_logs
+
+echo -e "Testing user-defined simulation settings: clock frequency and number of cycles";
+python3 openfpga_flow/scripts/run_fpga_task.py openfpga_shell/fixed_simulation_settings --debug --show_thread_logs
+
+echo -e "Testing Verilog generation for LUTs: a single mode LUT6 FPGA using micro benchmarks";
+python3 openfpga_flow/scripts/run_fpga_task.py openfpga_shell/lut_design/single_mode --debug --show_thread_logs
+
+echo -e "Testing Verilog generation for LUTs: simple fracturable LUT6 ";
+python3 openfpga_flow/scripts/run_fpga_task.py openfpga_shell/lut_design/frac_lut --debug --show_thread_logs
+
+echo -e "Testing Verilog generation for LUTs: LUT6 with intermediate buffers";
+python3 openfpga_flow/scripts/run_fpga_task.py openfpga_shell/lut_design/intermediate_buffer --debug --show_thread_logs
+
+echo -e "Testing Verilog generation with VPR's untileable routing architecture ";
+python3 openfpga_flow/scripts/run_fpga_task.py openfpga_shell/untileable --debug --show_thread_logs
+
+echo -e "Testing Verilog generation with hard adder chain in CLBs ";
+python3 openfpga_flow/scripts/run_fpga_task.py openfpga_shell/hard_adder --debug --show_thread_logs
+
+echo -e "Testing Verilog generation with 16k block RAMs ";
+python3 openfpga_flow/scripts/run_fpga_task.py openfpga_shell/bram/dpram16k --debug --show_thread_logs
+
+echo -e "Testing Verilog generation with 16k block RAMs spanning two columns ";
+python3 openfpga_flow/scripts/run_fpga_task.py openfpga_shell/bram/wide_dpram16k --debug --show_thread_logs
+
+echo -e "Testing Verilog generation with different I/O capacities on each side of an FPGA ";
+python3 openfpga_flow/scripts/run_fpga_task.py openfpga_shell/io/multi_io_capacity --debug --show_thread_logs
+
+echo -e "Testing Verilog generation with I/Os only on left and right sides of an FPGA ";
+python3 openfpga_flow/scripts/run_fpga_task.py openfpga_shell/io/reduced_io --debug --show_thread_logs
+
+echo -e "Testing Verilog generation with adder chain across an FPGA";
+python3 openfpga_flow/scripts/run_fpga_task.py openfpga_shell/fabric_chain/adder_chain --debug --show_thread_logs
+
+echo -e "Testing Verilog generation with shift register chain across an FPGA";
+python3 openfpga_flow/scripts/run_fpga_task.py openfpga_shell/fabric_chain/register_chain --debug --show_thread_logs
+
+echo -e "Testing Verilog generation with scan chain across an FPGA";
+python3 openfpga_flow/scripts/run_fpga_task.py openfpga_shell/fabric_chain/scan_chain --debug --show_thread_logs
+
+echo -e "Testing Verilog generation with routing mutliplexers implemented by tree structure";
+python3 openfpga_flow/scripts/run_fpga_task.py openfpga_shell/mux_design/tree_structure --debug --show_thread_logs
+
+echo -e "Testing Verilog generation with routing mutliplexers implemented by standard cell MUX2";
+python3 openfpga_flow/scripts/run_fpga_task.py openfpga_shell/mux_design/stdcell_mux2 --debug --show_thread_logs
+
+echo -e "Testing Verilog generation with routing mutliplexers implemented by local encoders";
+python3 openfpga_flow/scripts/run_fpga_task.py openfpga_shell/mux_design/local_encoder --debug --show_thread_logs
+
+echo -e "Testing Verilog generation with behavioral description";
+python3 openfpga_flow/scripts/run_fpga_task.py openfpga_shell/behavioral_verilog --debug --show_thread_logs
+
+echo -e "Testing implicit Verilog generation";
+python3 openfpga_flow/scripts/run_fpga_task.py openfpga_shell/implicit_verilog --debug --show_thread_logs
+
+echo -e "Testing Verilog generation with flatten routing modules";
+python3 openfpga_flow/scripts/run_fpga_task.py openfpga_shell/flatten_routing --debug --show_thread_logs
+
+echo -e "Testing Verilog generation with duplicated grid output pins";
+python3 openfpga_flow/scripts/run_fpga_task.py openfpga_shell/duplicated_grid_pin --debug --show_thread_logs
+
+echo -e "Testing Verilog generation with spy output pads";
+python3 openfpga_flow/scripts/run_fpga_task.py openfpga_shell/spypad --debug --show_thread_logs
+
+echo -e "Testing fabric Verilog generation only";
+python3 openfpga_flow/scripts/run_fpga_task.py openfpga_shell/generate_fabric --debug --show_thread_logs
+
+echo -e "Testing Verilog testbench generation only";
+python3 openfpga_flow/scripts/run_fpga_task.py openfpga_shell/generate_testbench --debug --show_thread_logs
+
+echo -e "Testing SDC generation with time units";
+python3 openfpga_flow/scripts/run_fpga_task.py openfpga_shell/sdc_time_unit --debug --show_thread_logs
+
+echo -e "Testing Secured FPGA fabrics";
+python3 openfpga_flow/scripts/run_fpga_task.py openfpga_shell/fabric_key/generate_vanilla_key --debug --show_thread_logs
+python3 openfpga_flow/scripts/run_fpga_task.py openfpga_shell/fabric_key/generate_random_key --debug --show_thread_logs
+
+# Verify MCNC big20 benchmark suite with ModelSim 
+# Please make sure you have ModelSim installed in the environment
+# Otherwise, it will fail
+#python3 openfpga_flow/scripts/run_fpga_task.py openfpga_shell/mcnc_big20 --debug --show_thread_logs --maxthreads 20
+#python3 openfpga_flow/scripts/run_modelsim.py openfpga_shell/mcnc_big20 --run_sim 
+
+end_section "OpenFPGA.TaskTun"

.travis/script.sh

@@ -1,108 +0,0 @@
-#!/bin/bash
-
-source .travis/common.sh
-set -e
-
-start_section "OpenFPGA.build" "${GREEN}Building..${NC}"
-mkdir build
-cd build
-
-if [[ $TRAVIS_OS_NAME == 'osx' ]]; then
-  cmake .. -DCMAKE_BUILD_TYPE=debug -DENABLE_VPR_GRAPHICS=off
-else
-  cmake .. -DCMAKE_BUILD_TYPE=debug
-fi
- make -j16
-end_section "OpenFPGA.build"
-
-
-start_section "OpenFPGA.TaskTun" "${GREEN}..Running_Regression..${NC}"
-cd -
-
-###############################################
-# OpenFPGA with VPR7
-# TO BE DEPRECATED
-##############################################
-echo -e "Testing single-mode architectures";
-python3 openfpga_flow/scripts/run_fpga_task.py single_mode --debug --show_thread_logs
-#python3 openfpga_flow/scripts/run_fpga_task.py s298 
-
-echo -e "Testing multi-mode architectures";
-python3 openfpga_flow/scripts/run_fpga_task.py multi_mode --maxthreads 4 --debug --show_thread_logs
-
-echo -e "Testing compact routing techniques";
-python3 openfpga_flow/scripts/run_fpga_task.py compact_routing --debug --show_thread_logs
-
-echo -e "Testing tileable architectures";
-python3 openfpga_flow/scripts/run_fpga_task.py tileable_routing --debug --show_thread_logs
-
-echo -e "Testing Verilog generation with explicit port mapping ";
-python3 openfpga_flow/scripts/run_fpga_task.py explicit_verilog --debug --show_thread_logs
-
-echo -e "Testing Verilog generation with grid pin duplication ";
-python3 openfpga_flow/scripts/run_fpga_task.py duplicate_grid_pin --debug --show_thread_logs
-
-###############################################
-# OpenFPGA Shell with VPR8
-# (Will replace all the old tests)
-##############################################
-echo -e "Testing OpenFPGA Shell";
-
-echo -e "Testing configuration chain of a K4N4 FPGA";
-python3 openfpga_flow/scripts/run_fpga_task.py openfpga_shell/configuration_chain --debug --show_thread_logs
-
-echo -e "Testing Verilog generation for a single mode LUT6 FPGA using micro benchmarks";
-python3 openfpga_flow/scripts/run_fpga_task.py openfpga_shell/single_mode --debug --show_thread_logs
-
-echo -e "Testing Verilog generation with simple fracturable LUT6 ";
-python3 openfpga_flow/scripts/run_fpga_task.py openfpga_shell/frac_lut --debug --show_thread_logs
-
-echo -e "Testing Verilog generation with VPR's untileable routing architecture ";
-python3 openfpga_flow/scripts/run_fpga_task.py openfpga_shell/untileable --debug --show_thread_logs
-
-echo -e "Testing Verilog generation with hard adder chain in CLBs ";
-python3 openfpga_flow/scripts/run_fpga_task.py openfpga_shell/hard_adder --debug --show_thread_logs
-
-echo -e "Testing Verilog generation with 16k block RAMs ";
-python3 openfpga_flow/scripts/run_fpga_task.py openfpga_shell/bram/dpram16k --debug --show_thread_logs
-
-echo -e "Testing Verilog generation with 16k block RAMs spanning two columns ";
-python3 openfpga_flow/scripts/run_fpga_task.py openfpga_shell/bram/wide_dpram16k --debug --show_thread_logs
-
-echo -e "Testing Verilog generation with different I/O capacities on each side of an FPGA ";
-python3 openfpga_flow/scripts/run_fpga_task.py openfpga_shell/io/multi_io_capacity --debug --show_thread_logs
-
-echo -e "Testing Verilog generation with I/Os only on left and right sides of an FPGA ";
-python3 openfpga_flow/scripts/run_fpga_task.py openfpga_shell/io/reduced_io --debug --show_thread_logs
-
-echo -e "Testing Verilog generation with adder chain across an FPGA";
-python3 openfpga_flow/scripts/run_fpga_task.py openfpga_shell/fabric_chain/adder_chain --debug --show_thread_logs
-
-echo -e "Testing Verilog generation with shift register chain across an FPGA";
-python3 openfpga_flow/scripts/run_fpga_task.py openfpga_shell/fabric_chain/register_chain --debug --show_thread_logs
-
-echo -e "Testing Verilog generation with scan chain across an FPGA";
-python3 openfpga_flow/scripts/run_fpga_task.py openfpga_shell/fabric_chain/scan_chain --debug --show_thread_logs
-
-echo -e "Testing Verilog generation with routing mutliplexers implemented by tree structure";
-python3 openfpga_flow/scripts/run_fpga_task.py openfpga_shell/mux_design/tree_structure --debug --show_thread_logs
-
-echo -e "Testing Verilog generation with routing mutliplexers implemented by standard cell MUX2";
-python3 openfpga_flow/scripts/run_fpga_task.py openfpga_shell/mux_design/stdcell_mux2 --debug --show_thread_logs
-
-echo -e "Testing Verilog generation with behavioral description";
-python3 openfpga_flow/scripts/run_fpga_task.py openfpga_shell/behavioral_verilog --debug --show_thread_logs
-
-echo -e "Testing implicit Verilog generation";
-python3 openfpga_flow/scripts/run_fpga_task.py openfpga_shell/implicit_verilog --debug --show_thread_logs
-
-echo -e "Testing Verilog generation with flatten routing modules";
-python3 openfpga_flow/scripts/run_fpga_task.py openfpga_shell/flatten_routing --debug --show_thread_logs
-
-echo -e "Testing Verilog generation with duplicated grid output pins";
-python3 openfpga_flow/scripts/run_fpga_task.py openfpga_shell/duplicated_grid_pin --debug --show_thread_logs
-
-echo -e "Testing Verilog generation with spy output pads";
-python3 openfpga_flow/scripts/run_fpga_task.py openfpga_shell/spypad --debug --show_thread_logs
-
-end_section "OpenFPGA.TaskTun"

CMakeLists.txt

@@ -258,12 +258,6 @@ set_target_properties(libvpr vpr_shell
   LIBRARY_OUTPUT_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/vpr7_x2p/vpr"
   RUNTIME_OUTPUT_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/vpr7_x2p/vpr")
 
-set_target_properties(libarchopenfpga read_arch_openfpga
-  PROPERTIES
-  ARCHIVE_OUTPUT_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/libopenfpga/libarchopenfpga"
-  LIBRARY_OUTPUT_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/libopenfpga/libarchopenfpga"
-  RUNTIME_OUTPUT_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/libopenfpga/libarchopenfpga")
-
 set_target_properties(libvpr8 vpr8
   PROPERTIES
   ARCHIVE_OUTPUT_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/vpr"

docs/Makefile

@@ -3,7 +3,7 @@
 
 # You can set these variables from the command line.
 SPHINXOPTS    =
-SPHINXBUILD   = sphinx-build-3.6
+SPHINXBUILD   = sphinx-build
 SOURCEDIR     = source
 BUILDDIR      = build
 

docs/source/fpga_verilog/file_organization.rst

@@ -1,20 +0,0 @@
-Hierarchy of Verilog Output Files
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-All the generated Verilog Netlists are located in the <verilog_dir>/SRC as you specify in the command-line options. Under the <verilog_dir>/SRC, FPGA-Verilog creates the top file name_top.v and some folders: lb (logic blocks), routing and sub_modules. 
-
-.. csv-table:: Folder hierarchy of FPGA-Verilog
-   :header: "File/Folder", "Content" 
-   :widths: 10, 20
-        
-   "name_top.v", "Contains the top module and calls all the other .v files"   
-   "name.bitstream", "Only if --fpga_verilog_print_top_testbench or --fpga_verilog_print_top_auto_testbench is chosen. Contains the bitstream programming the generated FPGA."
-   "name_top_tb.v", "Only if --fpga_verilog_print_top_testbench. Contains a testbench used for the simulation."
-   "name_autocheck_top_tb.v", "Only if --fpga_verilog_print_autocheck_top_testbench is chosen. Contains a testbench used for the simulation."
-   "name_formal_random_top_tb.v", "Only if --fpga_verilog_print_formal_verification_top_netlist is chosen. Contains a testbench used for the simulation."
-   "name_top_formal_verification.v", "Only if --fpga_verilog_print_formal_verification_top_netlist is chosen. Contains a top fil used for formal verification and by name_formal_random_top_tb.v."
-   "fpga_defines.v", "Contains all the defines set as 'include_timing'"
-   "name_include_netlists.v", "Contains all the netlists and defines paths used for the simulation."
-   "lb", "Logic Block. Contains all the CLBs. The logic_block.v includes all the CLB and is called by the top module afterward."
-   "routing", "Contains all the routing in the circuit. You can find in it the Switch Boxes, the Connection Blocks and the routing needed to connect the different blocks. The routing.v file packs them all and is called by the top module."
-   "sub_modules", "Contains the modules generated by the flow to build the CLBs."

docs/source/fpga_verilog/func_verify.rst

@@ -1,12 +0,0 @@
-Perform Functionality Verification
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-If the --fpga_verilog_print_modelsim_autodeck option is selected, it is possible to directly generate scripts for Modelsim. Inside of the Verilog directory specified with --fpga_verilog_dir can be found name_runsim.tcl scripts which perform the functional verification onto the FPGA generated. 
-
-The point of the verification step is to check that the FPGA reproduces the right function. As illustrated in :numref:`fig_ModelSim`, inside of the red rectangle is the programming of the FPGA. Each prog clock cycle corresponds to one bit added to the scan-chain. Inside of the blue rectangle, we see that the prog clock is set to 0 and the operating clock is toggled. Two outputs are shown, benchmark and FPGA, and by checking the value on both of them, we know if the functionality is respected.
-
-.. _fig_ModelSim:
-
-.. figure:: figures/verification_step.png
-   :scale: 50%
-   :alt: Functional Verification using ModelSim

docs/source/index.rst

@@ -13,27 +13,15 @@ Welcome to OpenFPGA's documentation!
 
 .. toctree::
    :maxdepth: 2
-   :caption: Getting Started
+   :caption: Tutorials
 
    tutorials/index
 
 .. toctree::
    :maxdepth: 2
-   :caption: Architecture Description Language
+   :caption: User Manual
 
-   arch_lang/index
-
-.. toctree::
-   :maxdepth: 2
-   :caption: OpenFPGA Tools
-
-   openfpga_shell/index
-
-   fpga_spice/index
-
-   fpga_verilog/index
-
-   fpga_bitstream/index
+   manual/index
 
 .. toctree::
    :maxdepth: 2

docs/source/manual/arch_lang/annotate_vpr_arch.rst

@@ -4,86 +4,6 @@ Bind circuit modules to VPR architecture
 ----------------------------------------
 Each defined circuit model should be linked to an FPGA module defined in the original part of architecture descriptions. It helps FPGA-circuit creating the circuit netlists for logic/routing blocks. Since the original part lacks such support, we create a few XML properties to link to Circuit models.
 
-Configuration Protocol
-~~~~~~~~~~~~~~~~~~~~~~
-
-Configuration protocol is the circuitry designed to program an FPGA.
-As an interface, configuration protocol could be really different in FPGAs, depending on the application context.
-
-Template
-````````
-
-.. code-block:: xml
-
-  <configuration_protocol>
-    <organization type="<string>" circuit_model_name="<string>"/>
-  </configuration_protocol>
-
-.. option:: type="scan_chain|memory_bank|standalone"
-
-  Specify the type of configuration circuits.
-
-  OpenFPGA supports different types of configuration protocols to program FPGA fabrics:
-    - ``scan_chain``: configurable memories are connected in a chain. Bitstream is loaded serially to program a FPGA
-    - ``memory_bank``: configurable memories are organized in an array, where each element can be accessed by an unique address to the BL/WL decoders
-    - ``standalone``: configurable memories are directly accessed through ports of FPGA fabrics. In other words, there are no protocol to control the memories. This allows full customization on the configuration protocol for hardware engineers.
-
-  .. note:: Avoid to use ``standalone`` when designing an FPGA chip. It will causes a huge number of I/Os required, far beyond any package size. It is well applicable to eFPGAs, where designers do need customized protocols between FPGA and processors. 
-
-.. warning:: Currently FPGA-SPICE only supports standalone memory organization.
-
-.. warning:: Currently RRAM-based FPGA only supports memory-bank organization for Verilog Generator.
-
-.. option:: circuit_model_name="<string>"
-
-  Specify the name of circuit model to be used as configurable memory.
-  - ``scan_chain`` requires a circuit model type of ``ccff``
-  - ``memory_bank`` requires a circuit model type of ``sram``
-  - ``standalone`` requires a circuit model type of ``sram``
-
-Configuration Chain Example
-```````````````````````````
-The following XML code describes a scan-chain circuitry to configure the core logic of FPGA, as illustrated in :numref:`fig_ccff_fpga`.
-It will use the circuit model defined in :ref:`circuit_model_examples`.
-
-.. code-block:: xml
-
-  <configuration_protocol>
-    <organization type="scan_chain" circuit_model_name="ccff"/>
-  </configuration_protocol>
-
-.. _fig_ccff_fpga:
-
-.. figure:: figures/ccff_fpga.png
-   :scale: 60%
-   :alt: map to buried treasure
- 
-   Example of a configuration chain to program core logic of a FPGA 
-
-Memory bank Example
-```````````````````
-The following XML code describes a memory-bank circuitry to configure the core logic of FPGA, as illustrated in :numref:`fig_sram`.
-It will use the circuit model defined in :ref:`circuit_model_examples`.
-
-.. code-block:: xml
-
-  <configuration_protocol>
-    <organization type="memory_bank" circuit_model_name="sram"/>
-  </configuration_protocol>
-
-.. _fig_sram:
-
-.. figure:: figures/sram.png
-   :scale: 60%
-   :alt: map to buried treasure
- 
-   Example of a memory organization using memory decoders 
-
-Standalone SRAM Example
-```````````````````````
-
-.. warning:: TO BE CONSTRUCTED
-
 Switch Blocks
 ~~~~~~~~~~~~~
 

docs/source/manual/arch_lang/circuit_library.rst

@@ -339,7 +339,7 @@ These inputs are widely seen in FPGAs, such as clock ports, which are shared bet
 
 The global inouts are short wired across different instances. 
 
-:numref:`fig_global_ioput_ports` shows an example on how the global inouts are wired inside FPGA fabric.
+:numref:`fig_global_inout_ports` shows an example on how the global inouts are wired inside FPGA fabric.
 
 .. _fig_global_inout_ports:
 

docs/source/manual/arch_lang/circuit_model_examples.rst

@@ -240,7 +240,62 @@ Template
 
 .. note:: The information of input and output buffer should be clearly specified according to the customized Verilog/SPICE netlist! The existence of input/output buffers will influence the decision in creating testbenches, which may leads to larger errors in power analysis.
 
-.. note:: The support SRAM modules should have a BL and a WL when the memory-bank-style configuration circuit is declared. Note that the WL should be the write/read enable signal, while BL is the data input.
+SRAM with BL/WL
+```````````````
+.. _fig_sram_blwl:
+
+.. figure:: ./figures/sram_blwl.png
+   :scale: 100%
+
+   An example of a SRAM with Bit-Line (BL) and Word-Line (WL) control signals
+
+The following XML codes describes the SRAM cell shown in :numref:`fig_sram_blwl`.
+
+.. code-block:: xml
+
+  <circuit_model type="sram" name="sram_blwl" prefix="sram_blwl" verilog_netlist="sram.v" spice_netlist="sram.sp"/>
+    <design_technology type="cmos"/>
+    <input_buffer exist="false"/>
+    <output_buffer exist="false"/>
+    <port type="bl" prefix="bl" size="1"/>
+    <port type="blb" prefix="blb" size="1"/>
+    <port type="wl" prefix="wl" size="1"/>
+    <port type="output" prefix="out" size="1"/>
+    <port type="output" prefix="outb" size="1"/>
+  </circuit_model>
+
+.. note:: OpenFPGA always assume that a ``WL`` port should be the write/read enable signal, while a ``BL`` port is the data input.
+
+.. note:: When the ``memory_bank`` type of configuration procotol is specified, SRAM modules should have a BL and a WL.
+
+Configurable Latch
+``````````````````
+
+.. _fig_config_latch:
+
+.. figure:: ./figures/config_latch.png
+   :scale: 100%
+
+   An example of a SRAM-based configurable latch with Bit-Line (BL) and Word-Line (WL) control signals
+
+The following XML codes describes the configurable latch shown in :numref:`fig_config_latch`.
+
+.. code-block:: xml
+
+  <circuit_model type="sram" name="config_latch" prefix="config_latch" verilog_netlist="sram.v" spice_netlist="sram.sp"/>
+    <design_technology type="cmos"/>
+    <input_buffer exist="false"/>
+    <output_buffer exist="false"/>
+    <port type="clock" prefix="clk" size="1"/>
+    <port type="bl" prefix="bl" size="1"/>
+    <port type="wl" prefix="wl" size="1"/>
+    <port type="output" prefix="out" size="1"/>
+    <port type="output" prefix="outb" size="1"/>
+  </circuit_model>
+
+.. note:: OpenFPGA always assume that a ``WL`` port should be the write/read enable signal, while a ``BL`` port is the data input.
+
+.. note:: When the ``frame_based`` type of configuration procotol is specified, the configurable latch or a SRAM with ``BL`` and ``WL`` should be specified.
 
 Logic gates
 ~~~~~~~~~~~

docs/source/manual/arch_lang/config_protocol.rst

@@ -0,0 +1,161 @@
+.. _config_protocol:
+
+Configuration Protocol
+----------------------
+
+Configuration protocol is the circuitry designed to program an FPGA.
+As an interface, configuration protocol could be really different in FPGAs, depending on the application context.
+OpenFPGA supports versatile configuration protocol, providing different trade-offs between speed and area. 
+
+Template
+~~~~~~~~
+
+.. code-block:: xml
+
+  <configuration_protocol>
+    <organization type="<string>" circuit_model_name="<string>"/>
+  </configuration_protocol>
+
+.. option:: type="scan_chain|memory_bank|standalone"
+
+  Specify the type of configuration circuits.
+
+  OpenFPGA supports different types of configuration protocols to program FPGA fabrics:
+    - ``scan_chain``: configurable memories are connected in a chain. Bitstream is loaded serially to program a FPGA
+    - ``frame_based``: configurable memories are organized by frames. Each module of a FPGA fabric, e.g., Configurable Logic Block (CLB), Switch Block (SB) and Connection Block (CB), is considered as a frame of configurable memories. Inside each frame, all the memory banks are accessed through an address decoder. Users can write each memory cell with a specific address. Note that the frame-based memory organization is applid hierarchically. Each frame may consists of a number of sub frames, each of which follows the similar organization.
+    - ``memory_bank``: configurable memories are organized in an array, where each element can be accessed by an unique address to the BL/WL decoders
+    - ``standalone``: configurable memories are directly accessed through ports of FPGA fabrics. In other words, there are no protocol to control the memories. This allows full customization on the configuration protocol for hardware engineers.
+
+  .. note:: Avoid to use ``standalone`` when designing an FPGA chip. It will causes a huge number of I/Os required, far beyond any package size. It is well applicable to eFPGAs, where designers do need customized protocols between FPGA and processors. 
+
+.. warning:: Currently FPGA-SPICE only supports standalone memory organization.
+
+.. warning:: Currently RRAM-based FPGA only supports memory-bank organization for Verilog Generator.
+
+.. option:: circuit_model_name="<string>"
+
+  Specify the name of circuit model to be used as configurable memory.
+
+  - ``scan_chain`` requires a circuit model type of ``ccff``
+  - ``frame_based`` requires a circuit model type of ``sram``
+  - ``memory_bank`` requires a circuit model type of ``sram``
+  - ``standalone`` requires a circuit model type of ``sram``
+
+Configuration Chain Example
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The following XML code describes a scan-chain circuitry to configure the core logic of FPGA, as illustrated in :numref:`fig_ccff_fpga`.
+It will use the circuit model defined in :numref:`fig_ccff`.
+
+.. code-block:: xml
+
+  <configuration_protocol>
+    <organization type="scan_chain" circuit_model_name="ccff"/>
+  </configuration_protocol>
+
+.. _fig_ccff_fpga:
+
+.. figure:: figures/ccff_fpga.png
+   :scale: 60%
+   :alt: map to buried treasure
+ 
+   Example of a configuration chain to program core logic of a FPGA 
+
+Frame-based Example
+~~~~~~~~~~~~~~~~~~~
+The following XML code describes frame-based memory banks to configure the core logic of FPGA.
+It will use the circuit model defined in :numref:`fig_config_latch`.
+
+.. code-block:: xml
+
+  <configuration_protocol>
+    <organization type="frame_based" circuit_model_name="config_latch"/>
+  </configuration_protocol>
+
+Through frame-based configuration protocol, each memory cell can be accessed with an unique address given to decoders.
+:numref:`fig_frame_config_protocol_example` illustrates an example about how the configurable memories are organizaed inside a Logic Element (LE) shown in :numref:`fig_k4n4_arch`.
+The decoder inside the LE will enable the decoders of the Look-Up Table (LUT) and the routing multiplexer, based on the given address at ``address[2:2]``.
+When the decoder of sub block, e.g., the LUT, is enabled, each memory cells can be accessed throught the ``address[1:0]`` and the data to write is provided at ``data_in``.
+
+.. _fig_frame_config_protocol_example:
+
+.. figure:: figures/frame_config_protocol_example.png
+   :scale: 25%
+   :alt: map to buried treasure
+ 
+   Example of a frame-based memory organization inside a Logic Element
+
+:numref:`fig_frame_config_protocol` shows a hierarchical view on how the frame-based decoders across a FPGA fabric. 
+
+.. _fig_frame_config_protocol:
+
+.. figure:: figures/frame_config_protocol.png
+   :scale: 60%
+   :alt: map to buried treasure
+ 
+   Frame-based memory organization in a hierarchical view
+
+.. note:: Frame-based decoders does require a memory cell to have 
+
+  -  two outputs (one regular and another inverted)
+  -  a Bit-Line input to load the data
+  -  a Word-Line input to enable data write 
+
+.. warning:: Please do NOT add inverted Bit-Line and Word-Line inputs. It is not supported yet!
+
+Memory bank Example
+~~~~~~~~~~~~~~~~~~~
+The following XML code describes a memory-bank circuitry to configure the core logic of FPGA, as illustrated in :numref:`fig_sram`.
+It will use the circuit model defined in :numref:`fig_sram_blwl`.
+
+.. code-block:: xml
+
+  <configuration_protocol>
+    <organization type="memory_bank" circuit_model_name="sram_blwl"/>
+  </configuration_protocol>
+
+.. _fig_sram:
+
+.. figure:: figures/sram.png
+   :scale: 60%
+   :alt: map to buried treasure
+ 
+   Example of a memory organization using memory decoders 
+
+.. note:: Memory-bank decoders does require a memory cell to have 
+
+  -  two outputs (one regular and another inverted)
+  -  a Bit-Line input to load the data
+  -  a Word-Line input to enable data write 
+
+.. warning:: Please do NOT add inverted Bit-Line and Word-Line inputs. It is not supported yet!
+
+Standalone SRAM Example
+~~~~~~~~~~~~~~~~~~~~~~~
+In the standalone configuration protocol, every memory cell of the core logic of a FPGA fabric can be directly accessed at the top-level module, as illustrated in :numref:`fig_vanilla_config_protocol`.
+
+.. _fig_vanilla_config_protocol:
+
+.. figure:: figures/vanilla_config_protocol.png
+   :scale: 30%
+   :alt: map to buried treasure
+ 
+   Vanilla (standalone) memory organization in a hierarchical view
+
+The following XML code shows an example where we use the circuit model defined in :numref:`fig_sram_blwl`.
+
+.. code-block:: xml
+
+  <configuration_protocol>
+    <organization type="standalone" circuit_model_name="sram_blwl"/>
+  </configuration_protocol>
+
+.. note:: The standalone protocol does require a memory cell to have 
+
+  -  two outputs (one regular and another inverted)
+  -  a Bit-Line input to load the data
+  -  a Word-Line input to enable data write 
+
+.. warning:: Please do NOT add inverted Bit-Line and Word-Line inputs. It is not supported yet!
+
+.. warning:: This is a vanilla configuration method, which allow users to build their own configuration protocol on top of it. 
+

docs/source/manual/arch_lang/fabric_key.rst

@@ -0,0 +1,69 @@
+Fabric Key
+~~~~~~~~~~
+
+Fabric key is a secure key for users to generate bitstream for a specific FPGA fabric. 
+With this key, OpenFPGA can generate correct bitstreams for the FPGA.
+Using a wrong key, OpenFPGA may error out or generate wrong bitstreams.
+The fabric key support allows users to build secured/classified FPGA chips even with an open-source tool.
+
+.. note:: Users are the only owner of the key. OpenFPGA will not store or replicate the key.
+
+Key Generation
+``````````````
+A fabric key can be achieved in the following ways:
+
+- OpenFPGA can auto-generate a fabric key using random algorithms (see detail in :ref:`cmd_build_fabric`)
+
+- Users can craft a fabric key based on auto-generated file by following the file format description.
+
+File Format
+```````````
+
+A fabric key follows an XML format. As shown in the following XML code, the key file includes the organization of configurable memory blocks in the top-level FPGA fabric: 
+
+  - ``id`` indicates the sequence of the configurable memory block in the top-level FPGA fabric.
+
+  - ``name`` indicates the module name of the configurable memory block.
+
+  - ``value`` indicates the instance id of the configurable memory block in the top-level FPGA fabric.
+
+The following is an example of a fabric key generate by OpenFPGA for a 2 :math:`\times` 2 FPGA.
+
+.. code-block:: xml
+
+  <fabric_key>
+      <key id="0" name="sb_2__2_" value="0"/>
+      <key id="1" name="grid_clb" value="3"/>
+      <key id="2" name="sb_0__1_" value="0"/>
+      <key id="3" name="cby_0__1_" value="0"/>
+      <key id="4" name="grid_clb" value="2"/>
+      <key id="5" name="grid_io_left" value="0"/>
+      <key id="6" name="sb_1__0_" value="0"/>
+      <key id="7" name="sb_1__1_" value="0"/>
+      <key id="8" name="cbx_1__1_" value="1"/>
+      <key id="9" name="cby_1__1_" value="1"/>
+      <key id="10" name="grid_io_right" value="1"/>
+      <key id="11" name="cbx_1__0_" value="1"/>
+      <key id="12" name="cby_1__1_" value="0"/>
+      <key id="13" name="grid_io_right" value="0"/>
+      <key id="14" name="grid_io_bottom" value="0"/>
+      <key id="15" name="cby_2__1_" value="0"/>
+      <key id="16" name="sb_2__1_" value="0"/>
+      <key id="17" name="cbx_1__0_" value="0"/>
+      <key id="18" name="grid_clb" value="1"/>
+      <key id="19" name="cbx_1__2_" value="0"/>
+      <key id="20" name="cbx_1__2_" value="1"/>
+      <key id="21" name="sb_2__0_" value="0"/>
+      <key id="22" name="sb_1__2_" value="0"/>
+      <key id="23" name="cby_0__1_" value="1"/>
+      <key id="24" name="sb_0__0_" value="0"/>
+      <key id="25" name="grid_clb" value="0"/>
+      <key id="26" name="cby_2__1_" value="1"/>
+      <key id="27" name="grid_io_top" value="1"/>
+      <key id="28" name="sb_0__2_" value="0"/>
+      <key id="29" name="grid_io_bottom" value="1"/>
+      <key id="30" name="cbx_1__1_" value="0"/>
+      <key id="31" name="grid_io_top" value="0"/>
+      <key id="32" name="grid_io_left" value="1"/>
+      <key id="33" name="decoder6to33" value="0"/>
+  </fabric_key>

docs/source/manual/arch_lang/generality.rst

@@ -1,4 +1,4 @@
-.. _generality:
+.. _arch_generality:
 
 General Hierarchy
 -----------------
@@ -13,34 +13,49 @@ In the following sub-sections, we will introduce the structures of these XML nod
 For OpenFPGA using VPR8
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-OpenFPGA uses a separated XML file other than the VPR8 architecture description file.
+OpenFPGA uses separated XMLs file other than the VPR8 architecture description file.
 This is to keep a loose integration to VPR8 so that OpenFPGA can easily integrate any future version of VPR with least engineering effort.
 However, to implement a physical FPGA, OpenFPGA requires the original VPR XML to include full physical design details.
 Full syntax can be found in :ref:`addon_vpr_syntax`.
 
-The OpenFPGA architecture description XML file consisting of the following parts:
+The OpenFPGA requires two XML files: an architecture description file and a simulation setting description file.
 
-  - ``<openfpga_architecture>`` contains architecture-level information, such as device-level description, circuit-level and architecture annotations to original VPR architecture XML. It consists of the following code blocks
+OpenFPGA Architecture Description File
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This file contains device-level and circuit-level details as well as annotations to the original VPR architecture.
+It contains a root node called ``<openfpga_architecture>`` under which architecture-level information, such as device-level description, circuit-level and architecture annotations to original VPR architecture XML are defined.
+
+It consists of the following code blocks
 
     - ``<circuit_library>`` includes a number of ``circuit_model``, each of which describe a primitive block in FPGA architecture, such as Look-Up Tables and multiplexers. Full syntax can be found in :ref:`circuit_library`.
-    - ``<technology_library>`` includes transistor-level parameters, where users can specify which transistor models are going to be used when building the ``circuit models``. 
-    - ``<configuration_protocol>`` includes detailed description on the configuration protocols to be used in FPGA fabric.
-    - ``<connection_block>`` includes annotation on the connection block definition ``<connection_block>`` in original VPR XML
-    - ``<switch_block>`` includes annotation on the switch block definition ``<switchlist>`` in original VPR XML
-    - ``<routing_segment>`` includes annotation on the routing segment definition ``<segmentlist>`` in original VPR XML
-    - ``<direct_connection>`` includes annotation on the inter-tile direct connection definitioin ``<directlist>`` in original VPR XML
-    - ``<pb_type_annotation>`` includes annotation on the programmable block architecture ``<complexblocklist>`` in original VPR XML
-
-  - ``<openfpga_simulation_setting>`` includes all the parameters to be used in generate testbenches in simulation purpose. Full syntax can be found in :ref:`simulation_setting`.
-
-    - ``<clock_setting>`` defines the clock-related settings in simulation, such as clock frequency and number of clock cycles to be used
-    - ``<simulator_option>`` defines universal options available in both HDL and SPICE simulators. This is mainly used by FPGA-SPICE
-    - ``<monte_carlo>`` defines critical parameters to be used in monte-carlo simulations. This is used by FPGA-SPICE
-    - ``<measurement_setting>`` defines the parameters used to measure signal slew and delays. This is used by FPGA-SPICE
-    - ``<stimulus>`` defines the parameters used to generate voltage stimuli in testbenches. This is used by FPGA-SPICE
+    - ``<technology_library>`` includes transistor-level parameters, where users can specify which transistor models are going to be used when building the ``circuit models``.  Full syntax can be found in :ref:`technology_library`.
+    - ``<configuration_protocol>`` includes detailed description on the configuration protocols to be used in FPGA fabric. Full syntax can be found in :ref:`config_protocol`.
+    - ``<connection_block>`` includes annotation on the connection block definition ``<connection_block>`` in original VPR XML. Full syntax can be found in :ref:`annotate_vpr_arch`.
+    - ``<switch_block>`` includes annotation on the switch block definition ``<switchlist>`` in original VPR XML. Full syntax can be found in :ref:`annotate_vpr_arch`.
+    - ``<routing_segment>`` includes annotation on the routing segment definition ``<segmentlist>`` in original VPR XML. Full syntax can be found in :ref:`annotate_vpr_arch`.
+    - ``<direct_connection>`` includes annotation on the inter-tile direct connection definitioin ``<directlist>`` in original VPR XML. Full syntax can be found in :ref:`direct_interconnect`.
+    - ``<pb_type_annotation>`` includes annotation on the programmable block architecture ``<complexblocklist>`` in original VPR XML. Full syntax can be found in :ref:`annotate_vpr_arch`.
 
 .. note:: ``<technology_library>`` will be applied to ``circuit_model`` when running FPGA-SPICE. It will not impact FPGA-Verilog, FPGA-Bitstream, FPGA-SDC.
 
+
+OpenFPGA Simulation Setting File
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This file contains parameters required by testbench generators.
+It contains a root node ``<openfpga_simulation_setting>``, under which all the parameters to be used in generate testbenches in simulation purpose are defined.
+
+It consists of the following code blocks
+
+    - ``<clock_setting>`` defines the clock-related settings in simulation, such as clock frequency and number of clock cycles to be used.
+    - ``<simulator_option>`` defines universal options available in both HDL and SPICE simulators. This is mainly used by :ref:`fpga_spice`.
+    - ``<monte_carlo>`` defines critical parameters to be used in monte-carlo simulations. This is used by  :ref:`fpga_spice`.
+    - ``<measurement_setting>`` defines the parameters used to measure signal slew and delays. This is used by :ref:`fpga_spice`.
+    - ``<stimulus>`` defines the parameters used to generate voltage stimuli in testbenches. This is used by :ref:`fpga_spice`.
+
+Full syntax can be found in :ref:`simulation_setting`.
+
 .. note:: the parameters in ``<clock_setting>`` will be applied to both FPGA-Verilog and FPGA-SPICE simulations
 
 

docs/source/manual/arch_lang/index.rst

@@ -1,5 +1,8 @@
+OpenFPGA Architecture Description
+---------------------------------
+
 .. _arch_lang:
-   Extended FPGA Architecture Description Language
+   OpenFPGA Architecture Description
  
 .. toctree::
    :maxdepth: 2
@@ -8,6 +11,8 @@
 
    addon_vpr_syntax
 
+   config_protocol
+
    direct_interconnect 
    
    simulation_setting
@@ -20,4 +25,4 @@
   
    annotate_vpr_arch
 
-   
+   fabric_key 

docs/source/manual/fpga_spice/index.rst

@@ -1,11 +1,10 @@
+.. _fpga_spice:
+
 FPGA-SPICE
 ----------
 
 .. warning:: FPGA-SPICE has not been integrated to VPR8 version yet. Please the following tool guide is for VPR7 version now
 
-.. _fpga_spice:
-   FPGA-SPICE
- 
 .. toctree::
    :maxdepth: 2
   

docs/source/manual/fpga_verilog/fabric_netlist.rst

@@ -0,0 +1,132 @@
+.. _fabric_netlists:
+
+Fabric Netlists
+---------------
+
+In this part, we will introduce the hierarchy, dependency and functionality of each Verilog netlist, which are generated to model the FPGA fabric.
+
+.. note:: These netlists are automatically generated by the OpenFPGA command ``write_fabric_verilog``. See :ref:`openfpga_verilog_commands` for its detailed usage. 
+
+All the generated Verilog netlists are located in the directory as you specify in the OpenFPGA command ``write_fabric_verilog``.
+Inside the directory, the Verilog netlists are organized as illustrated in :numref:`fig_fabric_netlist_hierarchy`.
+
+.. _fig_fabric_netlist_hierarchy:
+
+.. figure:: ./figures/fabric_netlist_hierarchy.png
+   :scale: 90%
+
+   Hierarchy of Verilog netlists modeling a FPGA fabric
+
+.. _fig_generic_fabric:
+
+.. figure:: ./figures/generic_fabric.png
+   :scale: 80%
+
+   An illustrative FPGA fabric modelled by the Verilog netlists
+
+Top-level Netlists
+~~~~~~~~~~~~~~~~~~
+
+.. option:: fabric_netlists.v
+
+   This file includes all the related Verilog netlists that are used by the ``fpga_top.v``.
+   This file is created to simplify the netlist addition for HDL simulator and backend tools.
+   This is the only file you need to add to a simulator or backend project.
+
+   .. note:: User-defined (external) Verilog netlists are included in this file.
+
+.. option:: fpga_top.v
+
+   This netlist contains the top-level module of the fpga fabric, corresponding to the fabric shown in :numref:`fig_generic_fabric`.
+
+.. option:: fpga_defines.v
+
+   This file includes pre-processing flags required by the ``fpga_top.v``, to smooth HDL simulation.
+   It will include the folliwng pre-procesing flags:
+   
+   - ```define ENABLE_TIMING`` When enabled, all the delay values defined in primitive Verilog modules will be considered in compilation. This flag is added when ``--include_timing`` option is enabled when calling the ``write_fabric_verilog`` command. 
+
+   .. note:: We strongly recommend users to turn on this flag as it can help simulators to converge quickly.
+
+   - ```define ENABLE_SIGNAL_INITIALIZATION`` When enabled, all the outputs of primitive Verilog modules will be initialized with a random value. This flag is added when ``--include_signal_init`` option is enabled when calling the ``write_fabric_verilog`` command. 
+
+   .. note:: We strongly recommend users to turn on this flag as it can help simulators to converge quickly.
+   
+   - ```define ICARUS_SIMULATOR`` When enabled, Verilog netlists are generated to be compatible with the syntax required by `icarus iVerilog simulator`__. This flag is added when ``--support_icarus_simulator`` option is enabled when calling the ``write_fabric_verilog`` command. 
+
+   .. warning:: Please disable this flag if you are not using icarus iVerilog simulator.
+
+__ iverilog_website_
+
+.. _iverilog_website: http://iverilog.icarus.com/
+
+Logic Blocks
+~~~~~~~~~~~~
+This sub-directory contains all the Verilog modules modeling configurable logic blocks, heterogeneous blocks as well as I/O blocks.
+Take the example in :numref:`fig_generic_fabric`, the modules are CLBs, DSP blocks, I/Os and Block RAMs.
+
+.. option:: <physical_tile_name>.v
+
+   For each ``<physical_tile>`` defined in the VPR architecture description, a Verilog netlist will be generated to model its internal structure.
+
+   .. note:: For I/O blocks, separated ``<physical_tile_name>.v`` will be generated for each side of a FPGA fabric.
+
+.. option:: <logical_tile_name>.v
+
+   For each root ``pb_type`` defined in the ``<complexblock>`` of VPR architecture description, a Verilog netlist will be generated to model its internal structure.
+
+Routing Blocks
+~~~~~~~~~~~~~~
+This sub-directory contains all the Verilog modules modeling Switch Blocks (SBs) and Connection Blocks (CBs).
+Take the example in :numref:`fig_generic_fabric`, the modules are the Switch Blocks, X- and Y- Connection Blocks of a tile.
+
+.. option:: sb_<x>_<y>.v
+
+  For each unique Switch Block (SB) created by VPR routing resource graph generator, a Verilog netlist will be generated. The ``<x>`` and ``<y>`` denote the coordinate of the Switch Block in the FPGA fabric.
+
+.. option:: cbx_<x>_<y>.v
+
+  For each unique X-direction Connection Block (CBX) created by VPR routing resource graph generator, a Verilog netlist will be generated. The ``<x>`` and ``<y>`` denote the coordinate of the Connection Block in the FPGA fabric.
+
+.. option:: cby_<x>_<y>.v
+
+  For each unique Y-direction Connection Block (CBY) created by VPR routing resource graph generator, a Verilog netlist will be generated. The ``<x>`` and ``<y>`` denote the coordinate of the Connection Block in the FPGA fabric.
+
+Primitive Modules
+~~~~~~~~~~~~~~~~~
+This sub-directory contains all the primitive Verilog modules, which are used to build the logic blocks and routing blocks.
+
+.. option:: luts.v
+
+  Verilog modules for all the Look-Up Tables (LUTs), which are defined as ``<circuit_model name="lut">`` of OpenFPGA architecture description. See details in :ref:`circuit_library`.
+
+.. option:: wires.v
+
+  Verilog modules for all the routing wires, which are defined as ``<circuit_model name="wire|chan_wire">`` of OpenFPGA architecture description. See details in :ref:`circuit_library`.
+
+.. option:: memories.v
+
+  Verilog modules for all the configurable memories, which are defined as ``<circuit_model name="ccff|sram">`` of OpenFPGA architecture description. See details in :ref:`circuit_library`.
+
+.. option:: muxes.v
+
+  Verilog modules for all the routing multiplexers, which are defined as ``<circuit_model name="mux">`` of OpenFPGA architecture description. See details in :ref:`circuit_library`.
+
+  .. note:: multiplexers used in Look-Up Tables are also defined in this netlist.
+
+.. option:: inv_buf_passgate.v
+
+  Verilog modules for all the inverters, buffers and pass-gate logics, which are defined as ``<circuit_model name="inv_buf|pass_gate">`` of OpenFPGA architecture description. See details in :ref:`circuit_library`.
+
+.. option:: local_encoder.v
+
+  Verilog modules for all the encoders and decoders, which are created when routing multiplexers are defined to include local encoders. See details in :ref:`circuit_model_examples`.
+
+.. option:: user_defined_templates.v
+
+  This is a template netlist, which users can refer to when writing up their user-defined Verilog modules.
+  The user-defined Verilog modules are those ``<circuit_model>`` in the OpenFPGA architecture description with a specific ``verilog_netlist`` path.
+  It contains Verilog modules with ports declaration (compatible to other netlists that are auto-generated by OpenFPGA) but without any functionality.
+  This file is created only when the option ``--print_user_defined_template`` is enabled when calling the ``write_fabric_verilog`` command. 
+
+  .. warning:: Do not include this netlist in simulation without any modification to its content!

docs/source/manual/fpga_verilog/index.rst

@@ -7,10 +7,6 @@ FPGA-Verilog
 .. toctree::
    :maxdepth: 2
   
-   file_organization
- 
-   func_verify
-
-   sc_flow
-   
+   fabric_netlist
  
+   testbench

docs/source/manual/fpga_verilog/testbench.rst

@@ -0,0 +1,94 @@
+.. _fpga_verilog_testbench:
+
+Testbench
+---------
+
+In this part, we will introduce the hierarchy, dependency and functionality of each Verilog testbench, which are generated to verify a FPGA fabric implemented with an application.
+
+OpenFPGA can auto-generate two types of Verilog testbenches to validate the correctness of the fabric: full and formal-oriented.
+Both testbenches share the same organization, as depicted in :numref:`fig_verilog_testbench_organization` (a).
+To enable self-testing, the FPGA and user's RTL design (simulate using an HDL simulator) are driven by the same input stimuli, and any mismatch on their outputs will raise an error flag.
+
+.. _fig_verilog_testbench_organization:
+
+.. figure:: figures/verilog_testbench_organization.png
+   :scale: 50%
+   :alt: Functional Verification using ModelSim
+
+   Principles of Verilog testbenches organization: (a) block diagram and (b) waveforms. 
+
+Full Testbench
+~~~~~~~~~~~~~~
+Full testbench aims at simulating an entire FPGA operating period, consisting of two phases: 
+
+  - the **Configuration Phase**, where the synthesized design bitstream is loaded to the programmable fabric, as highlighted by the green rectangle of :numref:`fig_verilog_testbench_organization` (b);
+
+  - the **Operating Phase**, where random input vectors are auto-generated to drive both Devices Under Test (DUTs), as highlighted by the red rectangle of :numref:`fig_verilog_testbench_organization` (b). Using the full testbench, users can validate both the configuration circuits and programming fabric of an FPGA.
+
+Formal-oriented Testbench
+~~~~~~~~~~~~~~~~~~~~~~~~~
+The formal-oriented testbench aims to test a programmed FPGA is instantiated with the user's bitstream.
+The module of the programmed FPGA is encapsulated with the same port mapping as the user's RTL design and thus can be fed to a formal tool for a 100% coverage formal verification. Compared to the full testbench, this skips the time-consuming configuration phase, reducing the simulation time, potentially also significantly accelerating the functional verification, especially for large FPGAs.
+
+.. warning:: Formal-oriented testbenches do not validate the configuration protocol of FPGAs. It is used to  validate FPGA with a wide range of benchmarks.
+
+General Usage
+~~~~~~~~~~~~~
+
+All the generated Verilog testbenches are located in the directory as you specify in the OpenFPGA command ``write_fabric_verilog``.
+Inside the directory, the Verilog testbenches are organized as illustrated in :numref:`fig_verilog_testbench_hierarchy`.
+
+.. _fig_verilog_testbench_hierarchy:
+
+.. figure:: ./figures/verilog_testbench_hierarchy.png
+   :scale: 90%
+
+   Hierarchy of Verilog testbenches for a FPGA fabric implemented with an application
+
+.. note:: ``<bench_name>`` is the module name of users' RTL design. 
+
+.. option:: <bench_name>_include_netlist.v
+
+   This file includes all the related Verilog netlists that are used by the testbenches, including both full and formal oriented testbenches.
+   This file is created to simplify the netlist addition for HDL simulator.
+   This is the only file you need to add to a simulator.
+
+   .. note:: Fabric Verilog netlists are included in this file.
+
+.. option:: define_simulation.v
+
+   This file includes pre-processing flags required by the testbenches, to smooth HDL simulation.
+   It will include the folliwng pre-procesing flags:
+  
+   - ```define AUTOCHECK_SIMULATION`` When enabled, testbench will include self-testing features. The FPGA and user's RTL design (simulate using an HDL simulator) are driven by the same input stimuli, and any mismatch on their outputs will raise an error flag.
+
+   .. note:: OpenFPGA always enable the self-testing feature. Users can disable it by commenting out the associated line in the ``define_simulation.v``.
+
+   - ```define ENABLE_FORMAL_VERFICATION`` When enabled, the ``<bench_name>_include_netlist.v`` will include the pre-configured FPGA netlist for formal verification usage. This flag is added when ``--print_formal_verification_top_netlist`` option is enabled when calling the ``write_verilog_testbench`` command. 
+
+   - ```define ENABLE_FORMAL_SIMULATION`` When enabled, the ``<bench_name>_include_netlist.v`` will include the testbench netlist for formal-oriented simulation. This flag is added when ``--print_preconfig_top_testbench`` option is enabled when calling the ``write_verilog_testbench`` command. 
+
+   .. note:: To run full testbenches, both flags ``ENABLE_FORMAL_VERIFICATION`` and ``ENABLE_FORMAL_SIMULATION`` must be disabled!
+
+.. option:: <bench_name>_autocheck_top_tb.v
+
+  This is the netlist for full testbench.
+
+.. option:: <bench_name>_formal_random_top_tb.v
+
+  This is the netlist for formal-oriented testbench.
+
+.. option:: <bench_name>_top_formal_verification.v
+
+  This netlist includes a Verilog module of a pre-configured FPGA fabric, which is a wrapper on top of the ``fpga_top.v`` netlist.
+  The wrapper module has the same port map as the top-level module of user's RTL design, which be directly def to formal verification tools to validate FPGA's functional equivalence. 
+  :numref:`fig_preconfig_module` illustrates the organization of a pre-configured module, which consists of a FPGA fabric (see :ref:`fabric_netlists`) and a hard-coded bitstream.
+  Only used I/Os of FPGA fabric will appear in the port list of the pre-configured module. 
+
+.. _fig_preconfig_module:
+
+.. figure:: ./figures/preconfig_module.png
+   :scale: 100%
+
+   Internal structure of a pre-configured FPGA module
+

docs/source/manual/index.rst

@@ -0,0 +1,18 @@
+.. _tools:
+   OpenFPGA tools
+ 
+.. toctree::
+   :maxdepth: 2
+
+   openfpga_flow/index
+
+   arch_lang/index
+
+   openfpga_shell/index
+
+   fpga_spice/index
+
+   fpga_verilog/index
+
+   fpga_bitstream/index
+

docs/source/manual/openfpga_flow/index.rst

@@ -0,0 +1,12 @@
+OpenFPGA Flow
+-------------
+
+.. _openfpga_flow:
+   OpenFPGA Flow
+ 
+.. toctree::
+   :maxdepth: 2
+
+   run_fpga_flow
+
+   run_fpga_task

docs/source/manual/openfpga_shell/index.rst

@@ -1,5 +1,5 @@
-OpenFPGA Interface
-------------------
+OpenFPGA Shell
+--------------
 
 .. _openfpga_shell:
    OpenFPGA Shell
@@ -11,4 +11,4 @@ OpenFPGA Interface
 
    openfpga_script
   
-   openfpga_commands
+   openfpga_commands/index

docs/source/manual/openfpga_shell/openfpga_commands/basic_commands.rst

@@ -0,0 +1,15 @@
+.. _openfpga_basic_commands:
+
+Basic Commands
+--------------
+
+help
+~~~~
+
+  Show help desk to list all the available commands
+
+exit
+~~~~
+
+  Exit OpenFPGA shell
+

docs/source/manual/openfpga_shell/openfpga_commands/fpga_bitstream_commands.rst

@@ -0,0 +1,31 @@
+.. _openfpga_bitstream_commands:
+
+FPGA-Bitstream
+--------------
+
+repack
+~~~~~~
+
+  Repack the netlist to physical pbs
+  This must be done before bitstream generator and testbench generation
+  Strongly recommend it is done after all the fix-up have been applied
+   
+  - ``--verbose`` Show verbose log
+
+build_architecture_bitstream
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+  Decode VPR implementing results to an fabric-independent bitstream database 
+  
+  - ``--file`` or ``-f`` Output the fabric-independent bitstream to an XML file
+  
+  - ``--verbose`` Show verbose log
+
+build_fabric_bitstream
+~~~~~~~~~~~~~~~~~~~~~~
+
+  Build a sequence for every configuration bits in the bitstream database for a specific FPGA fabric
+
+  - ``--file`` or ``-f`` Output the fabric bitstream to an plain text file (only 0 or 1)
+
+  - ``--verbose`` Show verbose log

docs/source/manual/openfpga_shell/openfpga_commands/fpga_sdc_commands.rst

@@ -0,0 +1,84 @@
+.. _openfpga_sdc_commands:
+
+FPGA-SDC
+--------
+
+write_pnr_sdc
+~~~~~~~~~~~~~
+ 
+  Write the SDC files for PnR backend
+  
+  - ``--file`` or ``-f`` Specify the output directory for SDC files
+
+  - ``--hierarchical`` Output SDC files without full path in hierarchy
+
+  - ``--flatten_names`` Use flatten names (no wildcards) in SDC files
+
+  - ``--time_unit`` Specify a time unit to be used in SDC files. Acceptable values are string: ``as`` | ``fs`` | ``ps`` | ``ns`` | ``us`` | ``ms`` | ``ks`` | ``Ms``. By default, we will consider second (``s``).
+
+  - ``--output_hierarchy`` Output hierarchy of Multiple-Instance-Blocks(MIBs) to plain text file. This is applied to constrain timing for grids, Switch Blocks and Connection Blocks. 
+
+    .. note:: Valid only when ``compress_routing`` is enabled in ``build_fabric``
+
+  - ``--constrain_global_port`` Constrain all the global ports of FPGA fabric.
+
+  - ``--constrain_non_clock_global_port`` Constrain all the non-clock global ports as clocks ports of FPGA fabric
+
+    .. note:: ``constrain_global_port`` will treat these global ports in Clock Tree Synthesis (CTS), in purpose of balancing the delay to each sink. Be carefull to enable ``constrain_non_clock_global_port``, this may significanly increase the runtime of CTS as it is supposed to be routed before any other nets. This may cause routing congestion as well.
+
+  - ``--constrain_grid`` Constrain all the grids of FPGA fabric
+
+  - ``--constrain_sb`` Constrain all the switch blocks of FPGA fabric
+
+  - ``--constrain_cb`` Constrain all the connection blocks of FPGA fabric
+
+  - ``--constrain_configurable_memory_outputs`` Constrain all the outputs of configurable memories of FPGA fabric
+
+  - ``--constrain_routing_multiplexer_outputs`` Constrain all the outputs of routing multiplexer of FPGA fabric
+
+  - ``--constrain_switch_block_outputs`` Constrain all the outputs of switch blocks of FPGA fabric
+
+  - ``--constrain_zero_delay_paths`` Constrain all the zero-delay paths in FPGA fabric
+
+    .. note:: Zero-delay path may cause errors in some PnR tools as it is considered illegal
+  
+  - ``--verbose`` Enable verbose output
+
+write_configuration_chain_sdc
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ 
+  Write the SDC file to constrain the timing for configuration chain. The timing constraints will always start from the first output (Q) of a Configuration Chain Flip-flop (CCFF) and ends at the inputs of the next CCFF in the chain. Note that Qb of CCFF will not be constrained!
+
+  - ``--file`` or ``-f`` Specify the output SDC file
+
+  - ``--time_unit`` Specify a time unit to be used in SDC files. Acceptable values are string: ``as`` | ``fs`` | ``ps`` | ``ns`` | ``us`` | ``ms`` | ``ks`` | ``Ms``. By default, we will consider second (``s``).
+
+  
+  - ``--max_delay`` Specify the maximum delay to be used. The timing value should follow the time unit defined in this command.
+
+  - ``--min_delay`` Specify the minimum delay to be used. The timing value should follow the time unit defined in this command.
+
+  .. note::
+     Only applicable when configuration chain is used as configuration protocol
+
+write_sdc_disable_timing_configure_ports
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+  Write the SDC file to disable timing for configure ports of programmable modules. The SDC aims to break the combinational loops across FPGAs and avoid false path timing to be visible to timing analyzers
+
+  - ``--file`` or ``-f`` Specify the output SDC file
+
+  - ``--flatten_names`` Use flatten names (no wildcards) in SDC files
+
+  - ``--verbose`` Show verbose log
+
+write_analysis_sdc
+~~~~~~~~~~~~~~~~~~
+
+  Write the SDC to run timing analysis for a mapped FPGA fabric
+
+  - ``--file`` or ``-f`` Specify the output directory for SDC files
+  
+  - ``--flatten_names`` Use flatten names (no wildcards) in SDC files
+
+  - ``--time_unit`` Specify a time unit to be used in SDC files. Acceptable values are string: ``as`` | ``fs`` | ``ps`` | ``ns`` | ``us`` | ``ms`` | ``ks`` | ``Ms``. By default, we will consider second (``s``).

docs/source/manual/openfpga_shell/openfpga_commands/fpga_verilog_commands.rst

@@ -0,0 +1,44 @@
+.. _openfpga_verilog_commands:
+
+FPGA-Verilog
+------------
+
+write_fabric_verilog
+~~~~~~~~~~~~~~~~~~~~
+
+  Write the Verilog netlist for FPGA fabric based on module graph
+
+  - ``--file`` or ``-f`` Specify the output directory for the Verilog netlists
+
+  - ``--explicit_port_mapping`` Use explicit port mapping when writing the Verilog netlists
+
+  - ``--include_timing`` Output timing information to Verilog netlists for primitive modules
+ 
+  - ``--include_signal_init`` Output signal initialization to Verilog netlists for primitive modules
+
+  - ``--support_icarus_simulator`` Output Verilog netlists with syntax that iVerilog simulatorcan accept
+
+  - ``--print_user_defined_template`` Output a template Verilog netlist for all the user-defined ``circuit models`` in :ref:`circuit_library`. This aims to help engineers to check what is the port sequence required by top-level Verilog netlists
+
+  - ``--verbose`` Show verbose log
+
+write_verilog_testbench
+~~~~~~~~~~~~~~~~~~~~~~~
+ 
+  Write the Verilog testbench for FPGA fabric
+
+  - ``--file`` or ``-f`` The output directory for all the testbench netlists. We suggest the use of same output directory as fabric Verilog netlists
+
+  - ``--reference_benchmark_file_path`` Must specify the reference benchmark Verilog file if you want to output any testbenches
+
+  - ``--fast_configuration`` Enable fast configuration phase for the top-level testbench in order to reduce runtime of simulations. It is applicable to memory bank and frame-based configuration protocols. When enabled, all the zero configuration bits will be skipped. So ensure that your memory cells can be correctly reset to zero with a reset signal. 
+
+  - ``--print_top_testbench`` Enable top-level testbench which is a full verification including programming circuit and core logic of FPGA
+
+  - ``--print_formal_verification_top_netlist`` Generate a top-level module which can be used in formal verification
+
+  - ``--print_preconfig_top_testbench`` Enable pre-configured top-level testbench which is a fast verification skipping programming phase
+
+  - ``--print_simulation_ini`` Output an exchangeable simulation ini file, which is needed only when you need to interface different HDL simulators using openfpga flow-run scripts
+
+  - ``--explicit_port_mapping`` Use explicit port mapping when writing the Verilog netlists

docs/source/manual/openfpga_shell/openfpga_commands/index.rst

@@ -0,0 +1,21 @@
+Commands
+--------
+
+As OpenFPGA integrates various tools, the commands are categorized into different classes:
+
+.. _openfpga_commands:
+ 
+.. toctree::
+   :maxdepth: 2
+
+   basic_commands
+
+   vpr_commands
+
+   setup_commands
+
+   fpga_bitstream_commands
+
+   fpga_verilog_commands
+
+   fpga_sdc_commands

docs/source/manual/openfpga_shell/openfpga_commands/setup_commands.rst

@@ -0,0 +1,127 @@
+.. _openfpga_setup_commands:
+
+Setup OpenFPGA
+--------------
+
+read_openfpga_arch
+~~~~~~~~~~~~~~~~~~
+
+  Read the XML file about architecture description (see details in :ref:`arch_generality`)
+
+  - ``--file`` or ``-f`` Specify the file name 
+
+  - ``--verbose`` Show verbose log
+
+write_openfpga_arch
+~~~~~~~~~~~~~~~~~~~
+
+  Write the OpenFPGA XML architecture file to a file
+
+  - ``--file`` or ``-f`` Specify the file name 
+
+  - ``--verbose`` Show verbose log
+
+read_openfpga_simulation_setting
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+  Read the XML file about simulation settings (see details in :ref:`simulation_setting`)
+
+  - ``--file`` or ``-f`` Specify the file name 
+
+  - ``--verbose`` Show verbose log
+
+write_openfpga_simulation_setting
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+  Write the OpenFPGA XML simulation settings to a file
+
+  - ``--file`` or ``-f`` Specify the file name 
+
+  - ``--verbose`` Show verbose log
+
+link_openfpga_arch
+~~~~~~~~~~~~~~~~~~
+
+  Annotate the OpenFPGA architecture to VPR data base
+
+  - ``--activity_file`` Specify the signal activity file
+
+  - ``--sort_gsb_chan_node_in_edges`` Sort the edges for the routing tracks in General Switch Blocks (GSBs). Strongly recommand to turn this on for uniquifying the routing modules
+
+  - ``--verbose`` Show verbose log
+
+write_gsb_to_xml
+~~~~~~~~~~~~~~~~
+
+  Write the internal structure of General Switch Blocks (GSBs) across a FPGA fabric, including the interconnection between the nodes and node-level details, to XML files
+
+  - ``--file`` or ``-f`` Specify the output directory of the XML files. Each GSB will be written to an indepedent XML file
+
+  - ``--verbose`` Show verbose log
+
+  .. note:: This command is used to help users to study the difference between GSBs
+
+check_netlist_naming_conflict 
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+  Check and correct any naming conflicts in the BLIF netlist
+  This is strongly recommended. Otherwise, the outputted Verilog netlists may not be compiled successfully.
+
+  .. warning:: This command may be deprecated in future when it is merged to VPR upstream
+  
+  - ``--fix`` Apply fix-up to the names that violate the syntax
+
+  - ``--report <.xml>`` Report the naming fix-up to a log file
+
+pb_pin_fixup
+~~~~~~~~~~~~
+
+  Apply fix-up to clustering nets based on routing results
+  This is strongly recommended. Otherwise, the bitstream generation may be wrong
+
+  .. warning:: This command may be deprecated in future when it is merged to VPR upstream
+  
+  - ``--verbose`` Show verbose log
+   
+lut_truth_table_fixup
+~~~~~~~~~~~~~~~~~~~~~
+
+  Apply fix-up to Look-Up Table truth tables based on packing results
+
+  .. warning:: This command may be deprecated in future when it is merged to VPR upstream
+
+  - ``--verbose`` Show verbose log
+
+.. _cmd_build_fabric:
+  
+build_fabric
+~~~~~~~~~~~~
+
+  Build the module graph.
+
+  - ``--compress_routing`` Enable compression on routing architecture modules. Strongly recommend this as it will minimize the number of routing modules to be outputted. It can reduce the netlist size significantly.
+  
+  - ``--duplicate_grid_pin`` Enable pin duplication on grid modules. This is optional unless ultra-dense layout generation is needed
+
+  - ``--load_fabric_key <xml_file>`` Load an external fabric key from an XML file.
+
+  - ``--generate_fabric_key`` Generate a fabric key in a random way
+
+  - ``--write_fabric_key <xml_file>`` Output current fabric key to an XML file
+
+  - ``--verbose`` Show verbose log
+
+  .. note:: This is a must-run command before launching FPGA-Verilog, FPGA-Bitstream, FPGA-SDC and FPGA-SPICE
+
+write_fabric_hierarchy
+~~~~~~~~~~~~~~~~~~~~~~
+
+  Write the hierarchy of FPGA fabric graph to a plain-text file
+  
+  - ``--file`` or ``-f`` Specify the file name to write the hierarchy. 
+
+  - ``--depth`` Specify at which depth of the fabric module graph should the writer stop outputting. The root module start from depth 0. For example, if you want a two-level hierarchy, you should specify depth as 1. 
+
+  - ``--verbose`` Show verbose log
+
+  .. note:: This file is designed for hierarchical PnR flow, which requires the tree of Multiple-Instanced-Blocks (MIBs).

docs/source/manual/openfpga_shell/openfpga_commands/vpr_commands.rst

@@ -0,0 +1,11 @@
+.. _openfpga_vpr_commands:
+
+VPR Commands
+------------
+
+vpr
+~~~
+  
+  OpenFPGA allows users to call ``vpr`` in the standard way as documented in the vtr_project_.
+
+.. _vtr_project: https://github.com/verilog-to-routing/vtr-verilog-to-routing

docs/source/openfpga_shell/openfpga_commands.rst

@@ -1,207 +0,0 @@
-.. _openfpga_commands:
-
-Commands
---------
-
-As OpenFPGA integrates various tools, the commands are categorized into different classes:
-
-Basic Commands
-~~~~~~~~~~~~~~
-
-.. option:: help
-
-  Show help desk to list all the available commands
-
-.. option:: exit
-
-  Exit OpenFPGA shell
-
-VPR
-~~~
-
-.. option:: vpr
-  
-  OpenFPGA allows users to call ``vpr`` in the standard way as documented in vtr project.
-
-Setup OpenFPGA
-~~~~~~~~~~~~~~
-
-.. option:: read_openfpga_arch
-
-  Read the XML architecture file required by OpenFPGA
-
-  - ``--file`` or ``-f`` Specify the file name 
-
-  - ``--verbose`` Show verbose log
-
-.. option:: write_openfpga_arch
-
-  Write the OpenFPGA XML architecture file to a file
-
-  - ``--file`` or ``-f`` Specify the file name 
-
-  - ``--verbose`` Show verbose log
-
-.. option:: link_openfpga_arch
-
-  Annotate the OpenFPGA architecture to VPR data base
-
-  - ``--activity_file`` Specify the signal activity file
-
-  - ``--sort_gsb_chan_node_in_edges`` Sort the edges for the routing tracks in General Switch Blocks (GSBs). Strongly recommand to turn this on for uniquifying the routing modules
-
-  - ``--verbose`` Show verbose log
-
-.. option:: write_gsb_to_xml
-
-  Write the internal structure of General Switch Blocks (GSBs) across a FPGA fabric, including the interconnection between the nodes and node-level details, to XML files
-
-  - ``--file`` or ``-f`` Specify the output directory of the XML files. Each GSB will be written to an indepedent XML file
-
-  - ``--verbose`` Show verbose log
-
-  .. note:: This command is used to help users to study the difference between GSBs
-
-.. option:: check_netlist_naming_conflict 
-
-  Check and correct any naming conflicts in the BLIF netlist
-  This is strongly recommended. Otherwise, the outputted Verilog netlists may not be compiled successfully.
-
-  .. warning:: This command may be deprecated in future when it is merged to VPR upstream
-  
-  - ``--fix`` Apply fix-up to the names that violate the syntax
-
-  - ``--report <.xml>`` Report the naming fix-up to a log file
-
-.. option:: pb_pin_fixup
-
-  Apply fix-up to clustering nets based on routing results
-  This is strongly recommended. Otherwise, the bitstream generation may be wrong
-
-  .. warning:: This command may be deprecated in future when it is merged to VPR upstream
-  
-  - ``--verbose`` Show verbose log
-   
-.. option:: lut_truth_table_fixup
-
-  Apply fix-up to Look-Up Table truth tables based on packing results
-
-  .. warning:: This command may be deprecated in future when it is merged to VPR upstream
-
-  - ``--verbose`` Show verbose log
-  
-.. option:: build_fabric
-
-  Build the module graph.
-
-  - ``--compress_routing`` Enable compression on routing architecture modules. Strongly recommend this as it will minimize the number of routing modules to be outputted. It can reduce the netlist size significantly.
-  
-  - ``--duplicate_grid_pin`` Enable pin duplication on grid modules. This is optional unless ultra-dense layout generation is needed
-
-  - ``--verbose`` Show verbose log
-
-  .. note:: This is a must-run command before launching FPGA-Verilog, FPGA-Bitstream, FPGA-SDC and FPGA-SPICE
-
-  
-FPGA-Bitstream
-~~~~~~~~~~~~~~
-
-.. option:: repack
-
-  Repack the netlist to physical pbs
-  This must be done before bitstream generator and testbench generation
-  Strongly recommend it is done after all the fix-up have been applied
-   
-  - ``--verbose`` Show verbose log
-
-.. option:: build_architecture_bitstream
-
-  Decode VPR implementing results to an fabric-independent bitstream database 
-  
-  - ``--file`` or ``-f`` Output the fabric-independent bitstream to an XML file
-  
-  - ``--verbose`` Show verbose log
-
-.. option:: build_fabric_bitstream
-
-  Build a sequence for every configuration bits in the bitstream database for a specific FPGA fabric
-
-  - ``--file`` or ``-f`` Output the fabric bitstream to an plain text file (only 0 or 1)
-
-  - ``--verbose`` Show verbose log
-  
-FPGA-Verilog
-~~~~~~~~~~~~
-
-.. option:: write_fabric_verilog
-
-  Write the Verilog netlist for FPGA fabric based on module graph
-
-  - ``--file`` or ``-f`` Specify the output directory for the Verilog netlists
-
-  - ``--explict_port_mapping`` Use explict port mapping when writing the Verilog netlists
-
-  - ``--include_timing`` Output timing information to Verilog netlists for primitive modules
- 
-  - ``--include_signal_init`` Output signal initialization to Verilog netlists for primitive modules
-
-  - ``--support_icarus_simulator`` Output Verilog netlists with syntax that iVerilog simulatorcan accept
-
-  - ``--print_user_defined_template`` Output a template Verilog netlist for all the user-defined ``circuit models`` in :ref:`circuit_library`. This aims to help engineers to check what is the port sequence required by top-level Verilog netlists
-
-  - ``--verbose`` Show verbose log
-
-.. option:: write_verilog_testbench
- 
-  Write the Verilog testbench for FPGA fabric
-
-  - ``--file`` or ``-f`` The output directory for all the testbench netlists. We suggest the use of same output directory as fabric Verilog netlists
-
-  - ``--reference_benchmark_file_path`` Must specify the reference benchmark Verilog file if you want to output any testbenches
-
-  - ``--print_top_testbench`` Enable top-level testbench which is a full verification including programming circuit and core logic of FPGA
-
-  - ``--print_formal_verification_top_netlist`` Generate a top-level module which can be used in formal verification
-
-  - ``--print_preconfig_top_testbench`` Enable pre-configured top-level testbench which is a fast verification skipping programming phase
-
-  - ``--print_simulation_ini`` Output an exchangeable simulation ini file, which is needed only when you need to interface different HDL simulators using openfpga flow-run scripts
-
-FPGA-SDC
-~~~~~~~~
-
-.. option:: write_pnr_sdc
- 
-  Write the SDC files for PnR backend
-  
-  - ``--file`` or ``-f`` Specify the output directory for SDC files
-
-  - ``--constrain_global_port`` Constrain all the global ports of FPGA fabric.
-
-  - ``--constrain_non_clock_global_port`` Constrain all the non-clock global ports as clocks ports of FPGA fabric
-
-    .. note:: ``constrain_global_port`` will treat these global ports in Clock Tree Synthesis (CTS), in purpose of balancing the delay to each sink. Be carefull to enable ``constrain_non_clock_global_port``, this may significanly increase the runtime of CTS as it is supposed to be routed before any other nets. This may cause routing congestion as well.
-
-  - ``--constrain_grid`` Constrain all the grids of FPGA fabric
-
-  - ``--constrain_sb`` Constrain all the switch blocks of FPGA fabric
-
-  - ``--constrain_cb`` Constrain all the connection blocks of FPGA fabric
-
-  - ``--constrain_configurable_memory_outputs`` Constrain all the outputs of configurable memories of FPGA fabric
-
-  - ``--constrain_routing_multiplexer_outputs`` Constrain all the outputs of routing multiplexer of FPGA fabric
-
-  - ``--constrain_switch_block_outputs`` Constrain all the outputs of switch blocks of FPGA fabric
-
-  - ``--constrain_zero_delay_paths`` Constrain all the zero-delay paths in FPGA fabric
-
-    .. note:: Zero-delay path may cause errors in some PnR tools as it is considered illegal
-  
-  - ``--verbose`` Enable verbose output
-
-.. option:: write_analysis_sdc
-
-  Write the SDC to run timing analysis for a mapped FPGA fabric
-
-  - ``--file`` or ``-f`` Specify the output directory for SDC files

docs/source/tutorials/arch_modeling/index.rst

@@ -0,0 +1,10 @@
+.. _design_flow_tutorials:
+   Design Flows
+
+Architecture Modeling
+---------------------
+ 
+.. toctree::
+   :maxdepth: 2
+
+   quick_start

docs/source/tutorials/arch_modeling/quick_start.rst

@@ -0,0 +1,549 @@
+.. _arch_quick_start:
+
+A Quick Start
+-------------
+
+In this tutorial, we will consider a simple but representative FPGA architecture to show you how to
+  - Adapt the VPR architecture XML file to OpenFPGA acceptable format
+  - Create the OpenFPGA architecture XMl file to customize the primitive circuits
+
+Through this quick example, we will introduce the key steps to build your own FPGA based on a VPR architecture template.
+
+.. note:: These tips are generic and fundamental to build any architecture file for OpenFPGA.
+
+Adapt VPR Architecture 
+~~~~~~~~~~~~~~~~~~~~~~
+We start with the VPR architecture `template
+<https://github.com/verilog-to-routing/vtr-verilog-to-routing/blob/master/vtr_flow/arch/timing/k4_N4_90nm.xml>`_.
+This file models a homogeneous FPGA, as illustrated in :numref:`fig_k4n4_arch`.
+
+.. _fig_k4n4_arch:
+
+.. figure:: ./figures/k4n4_arch.png
+   :scale: 100%
+
+   K4N4 FPGA architecture 
+
+A summary of the architectural features is as follows:
+  - An array of tiles surrounded by a ring of I/O blocks
+  - K4N4 Configurable Logic Block (CLB), which consists of four Basic Logic Elements (BLEs) and a fully-connected crossbar. Each BLE contains a 4-input Look-Up Table (LUT), a Flip-Flop (FF) and a 2:1 routing multiplexer
+  - Length-1 routing wires interconnected by Wilton-Style Switch Block (SB)
+
+The VPR architecture description is designed for EDA needs mainly, which lacks the details physical modelingrequired by OpenFPGA.
+Here, we show a step-by-step adaption on the architecture template.
+
+Physical I/O Modeling
+^^^^^^^^^^^^^^^^^^^^^
+OpenFPGA requires a physical I/O block rather the abstract I/O modeling of VPR.
+The ``<pb_type name="io">`` under the ``<complexblocklist>`` should be adapted to the following:
+
+.. code-block:: xml
+
+   <!-- Define I/O pads begin -->
+   <pb_type name="io">
+     <input name="outpad" num_pins="1"/>
+     <output name="inpad" num_pins="1"/>
+
+     <!-- A mode denotes the physical implementation of an I/O 
+           This mode will not be used by packer but is mainly used for fabric verilog generation   
+       -->
+     <mode name="physical" packable="false">
+       <pb_type name="iopad" blif_model=".subckt io" num_pb="1">
+         <input name="outpad" num_pins="1"/>
+         <output name="inpad" num_pins="1"/>
+       </pb_type>
+       <interconnect>
+         <direct name="outpad" input="io.outpad" output="iopad.outpad">
+           <delay_constant max="1.394e-11" in_port="io.outpad" out_port="iopad.outpad"/>
+         </direct>
+         <direct name="inpad" input="iopad.inpad" output="io.inpad">
+           <delay_constant max="4.243e-11" in_port="iopad.inpad" out_port="io.inpad"/>
+         </direct>
+       </interconnect>
+     </mode>
+
+     <!-- Operating modes of I/O used by VPR
+          IOs can operate as either inputs or outputs. -->
+     <mode name="inpad">
+       <pb_type name="inpad" blif_model=".input" num_pb="1">
+         <output name="inpad" num_pins="1"/>
+       </pb_type>
+       <interconnect>
+         <direct name="inpad" input="inpad.inpad" output="io.inpad">
+           <delay_constant max="9.492000e-11" in_port="inpad.inpad" out_port="io.inpad"/>
+         </direct>
+       </interconnect>
+     </mode>
+     <mode name="outpad">
+       <pb_type name="outpad" blif_model=".output" num_pb="1">
+         <input name="outpad" num_pins="1"/>
+       </pb_type>
+       <interconnect>
+         <direct name="outpad" input="io.outpad" output="outpad.outpad">
+           <delay_constant max="2.675000e-11" in_port="io.outpad" out_port="outpad.outpad"/>
+         </direct>
+       </interconnect>
+     </mode>
+  </pb_type>
+
+Note that, there are several major changes in the above codes, when compared to the original code.
+  - We added a physical ``mode`` of I/O in addition to the original VPR I/O modeling, which is close to the physical implementation of an I/O cell. OpenFPGA will output fabric netlists base on the physical implementation rather than the operating modes.
+  - We remove the ``clock`` port of I/O is actually a dangling port.
+  - We specify that the phyical ``mode`` to be disabled for VPR packer by using ``packable=false``. This can help reduce packer's runtime.
+
+Since, we have added a new BLIF model ``subckt io`` to the architecture modeling, we should update the ``<models>`` XML node by adding a new I/O model. 
+  
+.. code-block:: xml
+   
+  <models>
+    <!-- A virtual model for I/O to be used in the physical mode of io block -->
+    <model name="io">
+      <input_ports>
+        <port name="outpad"/>
+      </input_ports>
+      <output_ports>
+        <port name="inpad"/>
+      </output_ports>
+    </model>
+  </models>
+
+Tileable Architecture
+^^^^^^^^^^^^^^^^^^^^^
+OpenFPGA does support fine-grained tile-based architecture as shown in :numref:`fig_k4n4_arch`.
+The tileable architecture leads to fast netlist generation as well as enables highly optimized physical designs through backend flow.
+To turn on the tileable architecture, the ``tileable`` property should be added to ``<layout>`` node.
+
+.. code-block:: xml
+
+  <layout tileable="true">
+
+By enabling this, all the Switch Blocks and Connection Blocks will be generated as identical as possible.
+As a result, for any FPGA array size, there are only 9 unique tiles to be generated in netlists.
+See details in :cite:`XTang_FPT_2019`.
+
+Detailed guidelines can be found at :ref:`addon_vpr_syntax`.
+
+Craft OpenFPGA Architecture
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+OpenFPGA needs another XML file which contains detailed modeling on the physical design of FPGA architecture.
+This is designed to minimize the modification on the original VPR architecture file, so that it can be reused.
+
+Overview on the Structure
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+An OpenFPGA architecture including the following parts.
+  - Architecture modeling with a focus on circuit-level description
+  - Configuration protocol definition
+  - Annotation on the VPR architecture modules
+  - Simulation settings
+
+These parts are organized as follows in the XML file.
+
+.. code-block:: xml
+
+  <openfpga_architecture>
+    <!-- Technology-related (device/transistor-level) information
+    <technology_library>
+      ...
+    </technology_library>
+
+    <!-- Circuit-level description -->
+    <circuit_library>
+      ...
+    </circuit_library>
+
+    <!-- Configuration protocol definition --> 
+    <configuration_protocol>
+      ...
+    </configuration_protocol>
+
+    <!-- Annotation on VPR architecture modules -->
+    <connection_block>
+      ...
+    </connection_block>
+    <switch_block>
+      ...
+    </switch_block>
+    <routing_segment>
+      ...
+    </routing_segment>
+    <pb_type_annotations>
+      ...
+    </pb_type_annotations>
+  </openfpga_architecture>
+
+  <openfpga_simulation_setting>
+    ...
+  </openfpga_simulation_setting>
+
+Technology Library Definition
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Technology information are all stored under the ``<technology_library>`` node, which contains transistor-level information to build the FPGA.
+Here, we bind to the open-source ASU Predictive Technology Modeling (PTM) 45nm process library.
+See details in :ref:`technology_library`.
+
+.. code-block:: xml
+
+  <technology_library>
+    <device_library>
+      <device_model name="logic" type="transistor">
+        <lib type="industry" corner="TOP_TT" ref="M" path="${OPENFPGA_PATH}/openfpga_flow/tech/PTM_45nm/45nm.pm"/>
+        <design vdd="0.9" pn_ratio="2"/>
+        <pmos name="pch" chan_length="40e-9" min_width="140e-9" variation="logic_transistor_var"/>
+        <nmos name="nch" chan_length="40e-9" min_width="140e-9" variation="logic_transistor_var"/>
+      </device_model>
+      <device_model name="io" type="transistor">
+        <lib type="academia" ref="M" path="${OPENFPGA_PATH}/openfpga_flow/tech/PTM_45nm/45nm.pm"/>
+        <design vdd="2.5" pn_ratio="3"/>
+        <pmos name="pch_25" chan_length="270e-9" min_width="320e-9" variation="io_transistor_var"/>
+        <nmos name="nch_25" chan_length="270e-9" min_width="320e-9" variation="io_transistor_var"/>
+      </device_model>
+    </device_library>
+    <variation_library>
+      <variation name="logic_transistor_var" abs_deviation="0.1" num_sigma="3"/>
+      <variation name="io_transistor_var" abs_deviation="0.1" num_sigma="3"/>
+    </variation_library>
+  </technology_library>
+
+.. note:: These information are important for FPGA-SPICE to correctly generate netlists. If you are not using FPGA-SPICE, you may provide a dummy technology library.
+
+Circuit Library Definition
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Circuit library is the crucial component of the architecture description, which contains a list of ``<circuit_model>``, each of which describes how a circuit is implemented for a FPGA component.
+
+Typically, we will defined a few atom ``<circuit_model>`` which are used to build primitive ``<circuit_model>``.
+
+.. code-block:: xml
+
+  <circuit_library>
+    <!-- Atom circuit models begin-->
+    <circuit_model>
+      ...
+    </circuit_model>
+    <!-- Atom circuit models end-->
+
+    <!-- Primitive circuit models begin -->
+    <circuit_model>
+      ...
+    </circuit_model>
+    <!-- Primitive circuit models end -->
+  </circuit_library>
+
+.. note:: Primitive ``<circuit_model>`` are the circuits which are directly used to build a FPGA component, such as Look-Up Table (LUT). Atom ``<circuit_model>`` are the circuits which are only used inside primitive ``<circuit_model>``.
+
+In this tutorial, we need the following atom ``<circuit_model>``, which are inverters, buffers and pass-gate logics.
+
+.. code-block:: xml
+
+  <!-- Atom circuit models begin-->
+  <circuit_model type="inv_buf" name="INVTX1" prefix="INVTX1" is_default="true">
+    <design_technology type="cmos" topology="inverter" size="1"/>
+    <port type="input" prefix="in" size="1"/>
+    <port type="output" prefix="out" size="1"/>
+    <delay_matrix type="rise" in_port="in" out_port="out">
+      10e-12
+    </delay_matrix>
+    <delay_matrix type="fall" in_port="in" out_port="out">
+      10e-12
+    </delay_matrix>
+  </circuit_model>
+  <circuit_model type="inv_buf" name="buf4" prefix="buf4" is_default="false">
+    <design_technology type="cmos" topology="buffer" size="1" num_level="2" f_per_stage="4"/>
+    <port type="input" prefix="in" size="1"/>
+    <port type="output" prefix="out" size="1"/>
+    <delay_matrix type="rise" in_port="in" out_port="out">
+      10e-12
+    </delay_matrix>
+    <delay_matrix type="fall" in_port="in" out_port="out">
+      10e-12
+    </delay_matrix>
+  </circuit_model>
+  <circuit_model type="inv_buf" name="tap_buf4" prefix="tap_buf4" is_default="false">
+    <design_technology type="cmos" topology="buffer" size="1" num_level="3" f_per_stage="4"/>
+    <port type="input" prefix="in" size="1"/>
+    <port type="output" prefix="out" size="1"/>
+    <delay_matrix type="rise" in_port="in" out_port="out">
+      10e-12
+    </delay_matrix>
+    <delay_matrix type="fall" in_port="in" out_port="out">
+      10e-12
+    </delay_matrix>
+  </circuit_model>
+  <circuit_model type="pass_gate" name="TGATE" prefix="TGATE" is_default="true">
+    <design_technology type="cmos" topology="transmission_gate" nmos_size="1" pmos_size="2"/>
+    <input_buffer exist="false"/>
+    <output_buffer exist="false"/>
+    <port type="input" prefix="in" size="1"/>
+    <port type="input" prefix="sel" size="1"/>
+    <port type="input" prefix="selb" size="1"/>
+    <port type="output" prefix="out" size="1"/>
+    <delay_matrix type="rise" in_port="in sel selb" out_port="out">
+      10e-12 5e-12 5e-12
+    </delay_matrix>
+    <delay_matrix type="fall" in_port="in sel selb" out_port="out">
+      10e-12 5e-12 5e-12
+    </delay_matrix>
+  </circuit_model>
+  <circuit_model type="chan_wire" name="chan_segment" prefix="track_seg" is_default="true">
+    <design_technology type="cmos"/>
+    <input_buffer exist="false"/>
+    <output_buffer exist="false"/>
+    <port type="input" prefix="in" size="1"/>
+    <port type="output" prefix="out" size="1"/>
+    <wire_param model_type="pi" R="101" C="22.5e-15" num_level="1"/> <!-- model_type could be T, res_val and cap_val DON'T CARE -->
+  </circuit_model>
+  <circuit_model type="wire" name="direct_interc" prefix="direct_interc" is_default="true">
+    <design_technology type="cmos"/>
+    <input_buffer exist="false"/>
+    <output_buffer exist="false"/>
+    <port type="input" prefix="in" size="1"/>
+    <port type="output" prefix="out" size="1"/>
+    <wire_param model_type="pi" R="0" C="0" num_level="1"/> <!-- model_type could be T, res_val cap_val should be defined -->
+  </circuit_model>
+  <!-- Atom circuit models end-->
+
+In this tutorial, we require the following primitive ``<circuit_model>``, which are routing multiplexers, Look-Up Tables, I/O cells in FPGA architecture (see :numref:`fig_k4n4_arch`).
+
+.. note:: We use different routing multiplexer circuits to maximum the performance by considering it fan-in and fan-out in the architecture context.
+
+.. note:: We specify that external Verilog netlists will be used for the circuits of Flip-Flops (FFs) ``static_dff`` and ``sc_dff_compact``, as well as the circuit of I/O cell ``iopad``. Other circuit models will be auto-generated by OpenFPGA.
+
+.. code-block:: xml
+
+  <!-- Primitive circuit models begin -->
+  <circuit_model type="mux" name="mux_2level" prefix="mux_2level" dump_structural_verilog="true">
+    <design_technology type="cmos" structure="multi_level" num_level="2" add_const_input="true" const_input_val="1"/>
+    <input_buffer exist="true" circuit_model_name="INVTX1"/>
+    <output_buffer exist="true" circuit_model_name="INVTX1"/>
+    <pass_gate_logic circuit_model_name="TGATE"/>
+    <port type="input" prefix="in" size="1"/>
+    <port type="output" prefix="out" size="1"/>
+    <port type="sram" prefix="sram" size="1"/>
+  </circuit_model>
+  <circuit_model type="mux" name="mux_2level_tapbuf" prefix="mux_2level_tapbuf" dump_structural_verilog="true">
+    <design_technology type="cmos" structure="multi_level" num_level="2" add_const_input="true" const_input_val="1"/>
+    <input_buffer exist="true" circuit_model_name="INVTX1"/>
+    <output_buffer exist="true" circuit_model_name="tap_buf4"/>
+    <pass_gate_logic circuit_model_name="TGATE"/>
+    <port type="input" prefix="in" size="1"/>
+    <port type="output" prefix="out" size="1"/>
+    <port type="sram" prefix="sram" size="1"/>
+  </circuit_model>
+  <circuit_model type="mux" name="mux_1level_tapbuf" prefix="mux_1level_tapbuf" is_default="true" dump_structural_verilog="true">
+    <design_technology type="cmos" structure="one_level" add_const_input="true" const_input_val="1"/>
+    <input_buffer exist="true" circuit_model_name="INVTX1"/>
+    <output_buffer exist="true" circuit_model_name="tap_buf4"/>
+    <pass_gate_logic circuit_model_name="TGATE"/>
+    <port type="input" prefix="in" size="1"/>
+    <port type="output" prefix="out" size="1"/>
+    <port type="sram" prefix="sram" size="1"/>
+  </circuit_model>
+  <!--DFF subckt ports should be defined as <D> <Q> <CLK> <RESET> <SET>  -->
+  <circuit_model type="ff" name="static_dff" prefix="dff" spice_netlist="${OPENFPGA_PATH}/openfpga_flow/SpiceNetlists/ff.sp" verilog_netlist="${OPENFPGA_PATH}/openfpga_flow/VerilogNetlists/ff.v">
+     <design_technology type="cmos"/>
+     <input_buffer exist="true" circuit_model_name="INVTX1"/>
+     <output_buffer exist="true" circuit_model_name="INVTX1"/>
+     <port type="input" prefix="D" size="1"/>
+     <port type="input" prefix="set" size="1" is_global="true" default_val="0" is_set="true"/>
+     <port type="input" prefix="reset" size="1" is_global="true" default_val="0" is_reset="true"/>
+     <port type="output" prefix="Q" size="1"/>
+     <port type="clock" prefix="clk" size="1" is_global="true" default_val="0" />
+  </circuit_model>
+  <circuit_model type="lut" name="lut4" prefix="lut4" dump_structural_verilog="true">
+    <design_technology type="cmos"/>
+    <input_buffer exist="true" circuit_model_name="INVTX1"/>
+    <output_buffer exist="true" circuit_model_name="INVTX1"/>
+    <lut_input_inverter exist="true" circuit_model_name="INVTX1"/>
+    <lut_input_buffer exist="true" circuit_model_name="buf4"/>
+    <pass_gate_logic circuit_model_name="TGATE"/>
+    <port type="input" prefix="in" size="4"/>
+    <port type="output" prefix="out" size="1"/>
+    <port type="sram" prefix="sram" size="16"/>
+  </circuit_model>
+  <!--Scan-chain DFF subckt ports should be defined as <D> <Q> <Qb> <CLK> <RESET> <SET>  -->
+  <circuit_model type="ccff" name="sc_dff_compact" prefix="scff" spice_netlist="${OPENFPGA_PATH}/openfpga_flow/SpiceNetlists/ff.sp" verilog_netlist="${OPENFPGA_PATH}/openfpga_flow/VerilogNetlists/ff.v">
+     <design_technology type="cmos"/>
+     <input_buffer exist="true" circuit_model_name="INVTX1"/>
+     <output_buffer exist="true" circuit_model_name="INVTX1"/>
+     <port type="input" prefix="pReset" lib_name="reset" size="1" is_global="true" default_val="0" is_reset="true" is_prog="true"/>
+     <port type="input" prefix="D" size="1"/>
+     <port type="output" prefix="Q" size="1"/>
+     <port type="output" prefix="Qb" size="1"/>
+     <port type="clock" prefix="prog_clk" lib_name="clk" size="1" is_global="true" default_val="0" is_prog="true"/>
+  </circuit_model>
+  <circuit_model type="iopad" name="iopad" prefix="iopad" spice_netlist="${OPENFPGA_PATH}/openfpga_flow/SpiceNetlists/io.sp" verilog_netlist="${OPENFPGA_PATH}/openfpga_flow/VerilogNetlists/io.v">
+    <design_technology type="cmos"/>
+    <input_buffer exist="true" circuit_model_name="INVTX1"/>
+    <output_buffer exist="true" circuit_model_name="INVTX1"/>
+    <port type="inout" prefix="pad" size="1" is_global="true" is_io="true"/>
+    <port type="sram" prefix="en" size="1" mode_select="true" circuit_model_name="sc_dff_compact" default_val="1"/>
+    <port type="input" prefix="outpad" size="1"/>
+    <port type="output" prefix="inpad" size="1"/>
+  </circuit_model>
+  <!-- Primitive circuit models end -->
+
+See details in :ref:`circuit_library` and :ref:`circuit_model_examples`.
+
+Annotation on VPR Architecture
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+In this part, we bind the ``<circuit_model>`` defined in the circuit library to each FPGA component.
+
+We specify that the FPGA fabric will be configured through a chain of Flip-Flops (FFs), which is built with the ``<circuit_model name=sc_dff_compact>``.
+
+.. code-block:: xml
+
+  <configuration_protocol>
+    <organization type="scan_chain" circuit_model_name="sc_dff_compact"/>
+  </configuration_protocol>
+
+For the routing architecture, we specify the ``circuit_model`` to be used as routing multiplexers inside Connection Blocks (CBs), Switch Blocks (SBs), and also the routing wires.
+
+.. code-block:: xml
+
+  <connection_block>
+    <switch name="ipin_cblock" circuit_model_name="mux_2level_tapbuf"/>
+  </connection_block>
+  <switch_block>
+    <switch name="0" circuit_model_name="mux_2level_tapbuf"/>
+  </switch_block>
+  <routing_segment>
+    <segment name="L4" circuit_model_name="chan_segment"/>
+  </routing_segment>
+
+.. note:: For a correct binding, the name of connection block, switch block and routing segment should match the name definition in your VPR architecture description! 
+
+For each ``<pb_type>`` defined in the ``<complexblocklist>`` of VPR architecture, we need to specify
+
+- The physical mode for any ``<pb_type>`` that contains multiple ``<mode>``. The name of the physical mode  should match a mode name that is defined in the VPR architecture. For example:
+
+.. code-block:: xml
+
+  <pb_type name="io" physical_mode_name="physical"/>
+
+- The circuit model used to implement any primitive ``<pb_type>`` in physical modes. It is required to provide full hierarchy of the ``pb_type``. For example:
+
+.. code-block:: xml
+
+  <pb_type name="io[physical].iopad" circuit_model_name="iopad" mode_bits="1"/> 
+
+.. note:: Mode-selection bits should be provided as the default configuration for a configurable resource. In this example, an I/O cell has a configuration bit, as defined in the ``<circuit_model name="iopad">``. We specify that by default, the configuration memory will be set to logic ``1``.
+
+- The physical ``<pb_type>`` for any ``<pb_type>`` in the operating modes (mode other than the physical mode). This is required to translate mapping results from operating modes to their physical modes, in order to generate bitstreams. It is required to provide full hierarchy of the ``pb_type``. For example, 
+
+.. code-block:: xml
+
+  <pb_type name="io[inpad].inpad" physical_pb_type_name="io[physical].iopad" mode_bits="1"/> 
+
+.. note:: Mode-selection bits should be provided so as to configure the circuits to be functional as required by the operating mode. In this example, an I/O cell will be configured with a logic ``1`` when operating as an input pad.
+
+- The circuit model used to implement interconnecting modules. The interconnect name should match the definition in the VPR architecture file. For example, 
+
+.. code-block:: xml
+
+  <interconnect name="crossbar" circuit_model_name="mux_2level"/>
+
+.. note:: If not specified, each interconnect will be binded to its default ``circuit_model``. For example, the crossbar will be binded to the default multiplexer ``<circuit_model name="mux_1level_tapbuf">``, if not specified here. 
+
+.. note:: OpenFPGA automatically infers the type of circuit model required by each interconnect.
+
+The complete annotation is shown as follows:
+
+.. code-block:: xml
+
+  <pb_type_annotations>
+    <!-- physical pb_type binding in complex block IO -->
+    <pb_type name="io" physical_mode_name="physical"/>
+    <pb_type name="io[physical].iopad" circuit_model_name="iopad" mode_bits="1"/> 
+    <pb_type name="io[inpad].inpad" physical_pb_type_name="io[physical].iopad" mode_bits="1"/> 
+    <pb_type name="io[outpad].outpad" physical_pb_type_name="io[physical].iopad" mode_bits="0"/> 
+    <!-- End physical pb_type binding in complex block IO -->
+
+    <!-- physical pb_type binding in complex block CLB -->
+    <!-- physical mode will be the default mode if not specified -->
+    <pb_type name="clb">
+      <!-- Binding interconnect to circuit models as their physical implementation, if not defined, we use the default model -->
+      <interconnect name="crossbar" circuit_model_name="mux_2level"/>
+    </pb_type>
+    <pb_type name="clb.fle[n1_lut4].ble4.lut4" circuit_model_name="lut4"/>
+    <pb_type name="clb.fle[n1_lut4].ble4.ff" circuit_model_name="static_dff"/>
+    <!-- End physical pb_type binding in complex block IO -->
+  </pb_type_annotations>
+
+See details in :ref:`annotate_vpr_arch`.
+
+Simulation Settings
+^^^^^^^^^^^^^^^^^^^
+
+The simulation settings contain critical parameters to build testbenches for verify the FPGA fabric. 
+
+The complete annotation is shown as follows:
+
+.. code-block:: xml
+
+  <openfpga_simulation_setting>
+    <clock_setting>
+      <operating frequency="auto" num_cycles="auto" slack="0.2"/>
+      <programming frequency="100e6"/>
+    </clock_setting>
+    <simulator_option>
+      <operating_condition temperature="25"/>
+      <output_log verbose="false" captab="false"/>
+      <accuracy type="abs" value="1e-13"/>
+      <runtime fast_simulation="true"/>
+    </simulator_option>
+    <monte_carlo num_simulation_points="2"/>
+    <measurement_setting>
+      <slew>
+        <rise upper_thres_pct="0.95" lower_thres_pct="0.05"/>
+        <fall upper_thres_pct="0.05" lower_thres_pct="0.95"/>
+      </slew>
+      <delay>
+        <rise input_thres_pct="0.5" output_thres_pct="0.5"/>
+        <fall input_thres_pct="0.5" output_thres_pct="0.5"/>
+      </delay>
+    </measurement_setting>
+    <stimulus>
+      <clock>
+        <rise slew_type="abs" slew_time="20e-12" />
+        <fall slew_type="abs" slew_time="20e-12" />
+      </clock>
+      <input>
+        <rise slew_type="abs" slew_time="25e-12" />
+        <fall slew_type="abs" slew_time="25e-12" />
+      </input>
+    </stimulus>
+  </openfpga_simulation_setting>
+
+The ``<clock_setting>`` is crucial to create clock signals in testbenches.
+
+.. note:: FPGA has two types of clocks, one is the operating clock which controls applications that mapped to FPGA fabric, while the other is the programming clock which controls the configuration protocol.
+
+In this example, we specify 
+
+- the operating clock will follow the maximum frequency achieved by VPR routing results
+- the number of operating clock cycles to be used will follow the average signal activities of the RTL design that is mapped to the FPGA fabric.
+- the actual operating clock frequency will be relaxed (reduced) by 20% by considering the errors between VPR results and physical designs.
+- the programming clock frequency is fixed at 200MHz
+
+The ``<simulator_option>`` are the options for SPICE simulator.
+Here we specify
+
+- SPICE simulations will consider a 25 :math:`^\circ C` temperature.
+- SPICE simulation will output results in a compact way without details on node capacitances.
+- SPICE simulation will use ``0.1ps`` as the minimum time step.
+- SPICE simulation will consider fast algorithms to speed up runtime.
+
+The ``<monte_carlo num_simulation_points="2"/>`` are the options for SPICE simulator.
+Here we specify that for each testbench, we will consider two Monte-Carlo simulations to evaluate the impact of process variations.
+
+The ``<measurement_setting>`` specify how the output signals will be measured for delay and power evaluation.
+Here we specify that 
+
+- for slew calculation (used in power estimation), we consider from the 5% of the ``VDD`` to the 95% of the ``VDD`` for both rising and falling edges.
+- for delay calculation, we consider from the 50% of the ``VDD`` of input signal to the 50% of the ``VDD`` of output signals for both rising and falling edges.
+
+In the ``<stimulus>``, we specify that ``20ps`` slew time will be applied to built clock waverforms in SPICE simulations.
+
+See details in :ref:`simulation_setting`.

docs/source/tutorials/compile.rst

@@ -8,7 +8,7 @@ General Guidelines
 OpenFPGA uses CMake to generate the Makefile scripts
 In general, please follow the steps to compile
 
-::
+.. code-block:: shell
 
   git clone https://github.com/LNIS-Projects/OpenFPGA.git
   cd OpenFPGA
@@ -23,10 +23,11 @@ In general, please follow the steps to compile
 
 .. note:: recommand to use ``make -j`` to accelerate the compilation
 
-Quick Compilation Verification
+**Quick Compilation Verification**
+
 To quickly verify the tool is well compiled, user can run the following command from OpenFPGA root repository
 
-::
+.. code-block:: shell
 
   python3 openfpga_flow/scripts/run_fpga_task.py compilation_verification --debug --show_thread_logs
 
@@ -48,7 +49,7 @@ Docker
 If some of these dependencies are not installed on your machine, you can choose to use a Docker (the Docker tool needs to be installed).
 For the ease of the customer first experience, a Dockerfile is provided in the OpenFPGA folder. A container ready to use can be created with the following command
 
-::
+.. code-block:: shell
 
   docker run lnis/open_fpga:release
 
@@ -56,7 +57,7 @@ For the ease of the customer first experience, a Dockerfile is provided in the O
 
 Otherwise, a container where you can build OpenFPGA yourself can be created with the following commands
 
-::
+.. code-block:: shell
 
   docker build . -t open_fpga
   docker run -it --rm -v $PWD:/localfile/OpenFPGA -w="/localfile/OpenFPGA" open_fpga bash

docs/source/tutorials/design_flow/blif_to_verification.rst

@@ -0,0 +1,157 @@
+.. _from_blif_to_verification:
+
+From BLIF to Verification
+-------------------------
+
+This tutorial will show an example how to 
+  - generate Verilog netlists for a FPGA fabric
+  - generate Verilog testbenches for a RTL design
+  - run HDL simulation to verify the functional correctness of the implemented FPGA fabric
+
+Netlist Generation
+~~~~~~~~~~~~~~~~~~
+We will use the openfpga_flow scripts (see details in :ref:`run_fpga_task`) to generate the Verilog netlists and testbenches.
+Here, we consider a representative but fairly simple FPGA architecture, which is based on 4-input LUTs.
+We will map a 2-input AND gate to the FPGA fabric, and run a full testbench (see details in :ref:`fpga_verilog_testbench`)
+
+We will simply execute the following openfpga task-run by 
+
+.. code-block:: shell
+
+  python3 openfpga_flow/scripts/run_fpga_task.py openfpga_shell/configuration_chain
+
+Detailed settings, such as architecture XML files and RTL designs, can be found at ``${OPENFPGA_PATH}/openfpga_flow/tasks/openfpga_shell/configuration_chain/config/task.conf``.
+
+.. note:: ``${OPENFPGA_PATH}`` is the root directory of OpenFPGA 
+
+After this task-run, you can find all the generated netlists and testbenches at  
+
+.. code-block:: shell
+
+  ${OPENFPGA_PATH}/openfpga_flow/tasks/openfpga_shell/configuration_chain/latest/k4_N4_tileable_40nm/and2/MIN_ROUTE_CHAN_WIDTH/SRC/
+   
+.. note:: See :ref:`fabric_netlists` and :ref:`fpga_verilog_testbench` for the netlist details. 
+
+Run icarus iVerilog Simulation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Through OpenFPGA Scripts
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+By default, the ``configuration_chain`` task-run will execute iVerilog simulation automatically.
+The simulation results are logged in 
+
+.. code-block:: shell
+
+  ${OPENFPGA_PATH}/openfpga_flow/tasks/openfpga_shell/configuration_chain/latest/k4_N4_tileable_40nm/and2/MIN_ROUTE_CHAN_WIDTH/vvp_sim_output.txt
+
+If the verification passed, you should be able to see ``Simulation Succeed`` in the log file.
+
+All the waveforms are stored in the ``and2_formal.vcd`` file.
+To visualize the waveforms, you can use the `GTKWave
+<http://gtkwave.sourceforge.net/>`_.
+
+.. code-block:: shell
+
+  gtkwave ${OPENFPGA_PATH}/openfpga_flow/tasks/openfpga_shell/configuration_chain/latest/k4_N4_tileable_40nm/and2/MIN_ROUTE_CHAN_WIDTH/and2_formal.vcd &
+
+Manual Method
+^^^^^^^^^^^^^
+
+If you want to run iVerilog simulation manually, you can follow these steps:
+
+.. code-block:: shell
+
+  cd ${OPENFPGA_PATH}/openfpga_flow/tasks/openfpga_shell/configuration_chain/latest/k4_N4_tileable_40nm/and2/MIN_ROUTE_CHAN_WIDTH
+
+  source iverilog_output.txt
+  
+  vvp compiled_and2
+
+Debugging Tips
+^^^^^^^^^^^^^^
+
+If you want to apply full visibility to the signals, you need to change the following line in 
+
+   .. code-block:: shell 
+
+     ${OPENFPGA_PATH}/openfpga_flow/tasks/openfpga_shell/configuration_chain/latest/k4_N4_tileable_40nm/and2/MIN_ROUTE_CHAN_WIDTH/SRC/and2_autocheck_top_tb.v
+   
+from 
+
+.. code-block:: shell
+
+  $dumpvars (1, and2_autocheck_top_tb);
+
+to 
+
+.. code-block:: shell
+
+  $dumpvars (12, and2_autocheck_top_tb);
+   
+
+Run Modelsim Simulation
+~~~~~~~~~~~~~~~~~~~~~~~
+Alternatively, you can run Modelsim simulations through openfpga_flow scripts or manually.
+
+Through OpenFPGA Scripts
+^^^^^^^^^^^^^^^^^^^^^^^^
+You can simply call the python script in the following line:
+
+.. code-block:: shell
+
+  python3 openfpga_flow/scripts/run_modelsim.py openfpga_shell/configuration_chain --run_sim
+
+The script will automatically create a Modelsim project at  
+
+.. code-block:: shell
+
+  ${OPENFPGA_PATH}/openfpga_flow/tasks/openfpga_shell/configuration_chain/latest/k4_N4_tileable_40nm/and2/MIN_ROUTE_CHAN_WIDTH/MSIM2/
+
+and run the simulation.
+
+You may open the project and visualize the simulation results.
+
+Manual Method
+^^^^^^^^^^^^^
+
+Modify the ``fpga_defines.v`` (see details in :ref:`fabric_netlists`) at 
+
+.. code-block:: shell
+
+  ${OPENFPGA_PATH}/openfpga_flow/tasks/openfpga_shell/configuration_chain/latest/k4_N4_tileable_40nm/and2/MIN_ROUTE_CHAN_WIDTH/SRC/
+
+by **deleting** the line 
+
+.. code-block:: shell
+
+  `define ICARUS_SIMULATOR 1
+
+Create a folder ``MSIM`` under
+
+.. code-block:: shell
+
+  ${OPENFPGA_PATH}/openfpga_flow/tasks/openfpga_shell/configuration_chain/latest/k4_N4_tileable_40nm/and2/MIN_ROUTE_CHAN_WIDTH/
+
+Under the ``MSIM`` folder, create symbolic links to ``SRC`` folder and reference benchmarks by
+
+.. code-block:: shell
+
+  ln -s ../SRC ./ 
+
+  ln -s ../and2_output_verilog.v ./
+
+.. note:: Depending on the operating system, you may use other ways to create the symbolic links
+
+Launch ModelSim under the ``MSIM`` folder and create a project by following Modelsim user manuals.
+
+Add the following file to your project:
+
+.. code-block:: shell
+
+  ${OPENFPGA_PATH}/openfpga_flow/tasks/openfpga_shell/configuration_chain/latest/k4_N4_tileable_40nm/and2/MIN_ROUTE_CHAN_WIDTH/SRC/and2_include_netlists.v
+
+Compile the netlists, create a simulation configuration and specify ``and2_autocheck_top_tb`` at the top unit.
+
+Execute simulation with ``run -all``
+You should see ``Simulation Succeed`` in the output log.

docs/source/tutorials/design_flow/index.rst

@@ -0,0 +1,12 @@
+.. _design_flow_tutorials:
+   Design Flows
+
+Design Flows
+------------
+ 
+.. toctree::
+   :maxdepth: 2
+
+   blif_to_verification
+
+   verilog_to_gds2

docs/source/tutorials/design_flow/verilog_to_gds2.rst

@@ -1,4 +1,4 @@
-From Verilog to Layout
+From Verilog to GDSII
 ~~~~~~~~~~~~~~~~~~~~~~
 
 The generated Verilog code can be used through a semi-custom design flow to generate the layout.

docs/source/tutorials/index.rst

@@ -1,5 +1,5 @@
 .. _tutorials:
-   Getting Started
+   Tutorials
  
 .. toctree::
    :maxdepth: 2
@@ -8,11 +8,6 @@
 
    eda_flow
 
-   run_fpga_flow
-
-   run_fpga_task
-
-   
-  
-
+   design_flow/index
 
+   arch_modeling/index

libopenfpga/CMakeLists.txt

@@ -3,3 +3,4 @@ add_subdirectory(libini)
 add_subdirectory(libopenfpgashell)
 add_subdirectory(libarchopenfpga)
 add_subdirectory(libopenfpgautil)
+add_subdirectory(libfabrickey)

libopenfpga/libarchopenfpga/CMakeLists.txt

@@ -2,7 +2,7 @@ cmake_minimum_required(VERSION 3.9)
 
 project("libarchopenfpga")
 
-file(GLOB_RECURSE EXEC_SOURCES test/main.cpp)
+file(GLOB_RECURSE EXEC_SOURCES test/*.cpp)
 file(GLOB_RECURSE LIB_SOURCES src/*.cpp)
 file(GLOB_RECURSE LIB_HEADERS src/*.h)
 files_to_dirs(LIB_HEADERS LIB_INCLUDE_DIRS)
@@ -26,13 +26,10 @@ target_link_libraries(libarchopenfpga
                       libpugiutil)
 
 #Create the test executable
-add_executable(read_arch_openfpga ${EXEC_SOURCES})
-target_link_libraries(read_arch_openfpga libarchopenfpga)
-
-#Supress IPO link warnings if IPO is enabled
-get_target_property(READ_ARCH_USES_IPO read_arch_openfpga INTERPROCEDURAL_OPTIMIZATION)
-if (READ_ARCH_USES_IPO)
-    set_target_properties(read_arch_openfpga PROPERTIES LINK_FLAGS ${IPO_LINK_WARN_SUPRESS_FLAGS})
-endif()
-
-install(TARGETS libarchopenfpga read_arch_openfpga DESTINATION bin)
+foreach(testsourcefile ${EXEC_SOURCES})
+    # Use a simple string replace, to cut off .cpp.
+    get_filename_component(testname ${testsourcefile} NAME_WE)
+    add_executable(${testname} ${testsourcefile})
+    # Make sure the library is linked to each test executable
+    target_link_libraries(${testname} libarchopenfpga)
+endforeach(testsourcefile ${EXEC_SOURCES})

libopenfpga/libarchopenfpga/arch/sample_simulation_setting.xml

@@ -0,0 +1,36 @@
+<!-- An example of simulation settings, where we define the options 
+     and process variations to be considered in simulations
+  -->
+<openfpga_simulation_setting>
+  <clock_setting>
+    <operating frequency="200e6" num_cycles="auto" slack="0.2"/>
+    <programming frequency="10e6"/>
+  </clock_setting>
+  <simulator_option>
+    <operating_condition temperature="25"/>
+    <output_log verbose="false" captab="false"/>
+    <accuracy type="abs" value="1e-13"/>
+    <runtime fast_simulation="true"/>
+  </simulator_option>
+  <monte_carlo num_simulation_points="2"/>
+  <measurement_setting>
+    <slew>
+      <rise upper_thres_pct="0.95" lower_thres_pct="0.05"/>
+      <fall upper_thres_pct="0.05" lower_thres_pct="0.95"/>
+    </slew>
+    <delay>
+      <rise input_thres_pct="0.5" output_thres_pct="0.5"/>
+      <fall input_thres_pct="0.5" output_thres_pct="0.5"/>
+    </delay>
+  </measurement_setting>
+  <stimulus>
+    <clock>
+      <rise slew_type="abs" slew_time="20e-12" />
+      <fall slew_type="abs" slew_time="20e-12" />
+    </clock>
+    <input>
+      <rise slew_type="abs" slew_time="25e-12" />
+      <fall slew_type="abs" slew_time="25e-12" />
+    </input>
+  </stimulus>
+</openfpga_simulation_setting>

libopenfpga/libarchopenfpga/src/check_circuit_library.cpp

@@ -135,9 +135,11 @@ size_t check_one_circuit_model_port_size_required(const CircuitLibrary& circuit_
   size_t num_err = 0;
 
   if (port_size_to_check != circuit_lib.port_size(circuit_port)) {
-    VTR_LOG_ERROR(circuit_lib.model_name(circuit_model).c_str(), 
+    VTR_LOG_ERROR("Expect circuit model %s to have %d %s ports but only see %d!\n",
+                  circuit_lib.model_name(circuit_model).c_str(), 
+                  port_size_to_check,
                   CIRCUIT_MODEL_PORT_TYPE_STRING[size_t(circuit_lib.port_type(circuit_port))],
-                  port_size_to_check);
+                  circuit_lib.port_size(circuit_port));
     /* Incremental the counter for errors */
     num_err++;
   }
@@ -282,7 +284,7 @@ size_t check_sram_circuit_model_ports(const CircuitLibrary& circuit_lib,
   /* Check if we has 1 output with size 2 */
   num_err += check_one_circuit_model_port_type_and_size_required(circuit_lib, circuit_model, 
                                                                  CIRCUIT_MODEL_PORT_OUTPUT,
-                                                                 1, 2, false);
+                                                                 2, 1, false);
   /* basic check finished here */
   if (false == check_blwl) {
     return num_err;
@@ -447,7 +449,7 @@ size_t check_circuit_library_ports(const CircuitLibrary& circuit_lib) {
  * 9. LUT must have at least an input, an output and a SRAM ports
  * 10. We must have default circuit models for these types: MUX, channel wires and wires
  ***********************************************************************/
-void check_circuit_library(const CircuitLibrary& circuit_lib) {
+bool check_circuit_library(const CircuitLibrary& circuit_lib) {
   size_t num_err = 0;
 
   vtr::ScopedStartFinishTimer timer("Check circuit library");
@@ -506,7 +508,6 @@ void check_circuit_library(const CircuitLibrary& circuit_lib) {
 
   /* 6. SRAM must have at least an input and an output ports*/
   std::vector<enum e_circuit_model_port_type> sram_port_types_required;
-  sram_port_types_required.push_back(CIRCUIT_MODEL_PORT_INPUT);
   sram_port_types_required.push_back(CIRCUIT_MODEL_PORT_OUTPUT);
 
   num_err += check_circuit_model_port_required(circuit_lib, CIRCUIT_MODEL_SRAM, sram_port_types_required);
@@ -545,10 +546,11 @@ void check_circuit_library(const CircuitLibrary& circuit_lib) {
   if (0 < num_err) {
     VTR_LOG("Finished checking circuit library with %d errors!\n",
             num_err);
-    exit(1);
+    return false;
   }
 
   VTR_LOG("Checking circuit library passed.\n");
 
-  return;
+  return true;
 }
+

libopenfpga/libarchopenfpga/src/check_circuit_library.h

@@ -43,6 +43,6 @@ size_t check_sram_circuit_model_ports(const CircuitLibrary& circuit_lib,
                                       const CircuitModelId& circuit_model,
                                       const bool& check_blwl);
 
-void check_circuit_library(const CircuitLibrary& circuit_lib);
+bool check_circuit_library(const CircuitLibrary& circuit_lib);
 
 #endif