riscv
/
OpenFPGA
mirror of https://github.com/lnis-uofu/OpenFPGA.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Merge pull request #53 from LNIS-Projects/dev 

Porting Dev branch to master
This commit is contained in:
Laboratory for Nano Integrated Systems (LNIS) 2020-06-11 20:06:58 -06:00 committed by GitHub
parent 0cfb88a49f aaa52b6e89
commit 618c7d44c5
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
755 changed files with 106013 additions and 5925 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

67
.travis.yml
View File

@ -14,22 +14,12 @@ 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:
dist: bionic
compiler: g++-8
addons:
apt:
sources:
- ubuntu-toolchain-r-test # For newer GCC
- george-edison55-precise-backports # For cmake
- llvm_toolchain-trusty-7
packages:
- autoconf
@ -66,7 +56,7 @@ matrix:
- zip
- qt5-default
- clang-format-7
# - os: osx
#- os: osx
# osx_image: xcode10.2 # we target latest MacOS Mojave
# sudo: true
# compiler: gcc-4.9 # Use clang instead of gcc in MacOS
@ -86,34 +76,37 @@ matrix:
# - 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=

21
.travis/build.sh Normal file
View File

@ -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"

28
.travis/install.sh
View File

@ -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 -

24
.travis/script.sh → .travis/openfpga_vpr7_reg_test.sh
View File

@ -1,23 +1,13 @@
#!/bin/bash
source .travis/common.sh
set -e
start_section "OpenFPGA.build" "${GREEN}Building..${NC}"
mkdir build
cd build
start_section "OpenFPGA+VPR7.TaskTun" "${GREEN}..Running_Regression..${NC}"
cd ${TRAVIS_BUILD_DIR}
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
@ -37,4 +27,4 @@ python3 openfpga_flow/scripts/run_fpga_task.py explicit_verilog --debug --show_t
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.TaskTun"
end_section "OpenFPGA+VPR7.TaskTun"

111
.travis/openfpga_vpr8_reg_test.sh Executable file
View File

@ -0,0 +1,111 @@
#!/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
# 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"

31
CMakeLists.txt
View File

@ -46,6 +46,10 @@ project("OPENFPGA" C CXX)
option(ENABLE_VPR_GRAPHICS "Enables VPR graphics" ON)
option(ENABLE_VPR_GRAPHICS "Enables build with librtlnumber" OFF)
#Allow the user to decide weather to compile the graphics library
set(VPR_USE_EZGL "auto" CACHE STRING "Specify whether vpr uses the graphics library")
set_property(CACHE VPR_USE_EZGL PROPERTY STRINGS auto off on)
# Version number
set(OPENFPGA_VERSION_MAJOR 1)
set(OPENFPGA_VERSION_MINOR 0)
@ -154,6 +158,27 @@ message(STATUS "CMAKE_CXX_FLAGS: ${CMAKE_CXX_FLAGS}")
#
enable_testing()
# set VPR_USE_EZGL in the root of VTR to decide whether to add
# subdirectory of graphics library, which prevents users
# without gtk/x11 libraries installed to build. VPR_USE_EZGL is
# being used in both the vpr CMakeLists and libs/EXTERNAL CMakeLists.
#
# check if GTK and X11 are installed and turn on/off graphics
if (VPR_USE_EZGL STREQUAL "auto")
find_package(PkgConfig REQUIRED)
pkg_check_modules(GTK3 QUIET gtk+-3.0)
pkg_check_modules(X11 QUIET x11)
if(GTK3_FOUND AND X11_FOUND)
set(VPR_USE_EZGL "on")
message(STATUS "VPR Graphics: Enabled")
else()
set(VPR_USE_EZGL "off")
message(STATUS "VPR Graphics: Disabled (required libraries missing, on debia/ubuntu try: sudo apt install libgtk-3 libx11-dev")
endif()
endif()
#
# Sub-projects
#
@ -233,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"

10
README.md
View File

@ -3,10 +3,10 @@
[![Documentation Status](https://readthedocs.org/projects/openfpga/badge/?version=master)](https://openfpga.readthedocs.io/en/master/?badge=master)
## Introduction
The OpenFPGA framework is the **first open-source FPGA IP generator** supporting highly-customizable homogeneous FPGA architectures. OpenFPGA provides a full set of EDA support for customized FPGAs, including Verilog-to-bitstream generation and self-testing verification [testbenches/scripts](./testbenches/scripts) OpenFPGA opens the door to democratizing FPGA technology and EDA techniques, with agile prototyping approaches and constantly evolving EDA tools for chip designers and researchers.
The OpenFPGA framework is the **first open-source FPGA IP generator** supporting highly-customizable homogeneous FPGA architectures. OpenFPGA provides a full set of EDA support for customized FPGAs, including Verilog-to-bitstream generation and self-testing verification. OpenFPGA opens the door to democratizing FPGA technology and EDA techniques, with agile prototyping approaches and constantly evolving EDA tools for chip designers and researchers.
## Compilation
Dependencies and help using docker can be found at [**./tutorials/building.md**](./tutorials/building.md).
Dependencies and help using docker can be found [**here**](./docs/source/tutorials/compile.rst).
**Compilation Steps:**
```bash
@ -31,7 +31,6 @@ python3 openfpga_flow/scripts/run_fpga_task.py compilation_verification --debug
We currently target OpenFPGA for:
1. Ubuntu 18.04
2. Red Hat 7.5
3. MacOS Mojave 10.14.4
*The tool was tested with these operating systems. It might work with earlier versions and other distributions.*
@ -39,7 +38,4 @@ We currently target OpenFPGA for:
OpenFPGA's [full documentation](https://openfpga.readthedocs.io/en/master/) includes tutorials, descriptions of the design flow, and tool options.
## Tutorials
You can find some tutorials in the [**./tutorials**](./tutorials) folder. This will help you get more familiar with the tool and use OpenFPGA under different configurations.
Through those tutorials, users can learn how to use the flow and install the different dependencies.
The [tutorial index](./tutorials/tutorial_index.md) will guide you through training and explain the folder oraganization as well as introducing some tips and commonly used keywords.
You can find some tutorials in the [**./tutorials**](./docs/source/tutorials/) folder. This will help you get more familiar with the tool and use OpenFPGA under different configurations.

650
docs/source/arch_lang/circuit_model_examples.rst
View File

@ -1,650 +0,0 @@
Circuit model examples
======================
The next subsections are dedicated to detailed examples of each circuit model type. Through these examples, we give a global overview of the different implementations which are available for the user.
Inverters and Buffers
---------------------
.. code-block:: xml
<circuit_model type="inv_buf" name="string" prefix="string" netlist="string" is_default="int">
<design_technology type="cmos" topology="string" size="int" tapered="off"/>
<port type="input" prefix="string" size="int"/>
<port type="output" prefix="string" size="int"/>
</circuit_model>
.. note:: customized Verilog/SPICE netlists are not currently supported for inverters and buffers.
* design_technology:
* **topology:** [``inverter`` | ``buffer``]. Specify the type of this component, can be either an inverter or a buffer.
* **size:** Specify the driving strength of inverter/buffer. For a buffer, the size is the driving strength of the inverter at the second level. We consider a two-level structure for a buffer here. The support for multi-level structure of a buffer will be introduced in the tapered options.
* **tapered:** [``on`` | ``off``]. Define if the buffer is a tapered (multi-level) buffer. When ``on`` is defined, the following parameter are required.*
* **tap_drive_level:** Define the number of levels of a tapered buffer. This parameter is valid only when tapered is turned on.
* **f_per_stage:** Define the ratio of driving strength between the levels of a tapered driver. This parameter is valid only when tapered is turned on. Default value is 4.
**Inverter x1 example**
:numref:`fig_inv1` is the inverter symbol depicted in this example.
.. _fig_inv1:
.. figure:: ./figures/Inverter_1.png
:scale: 100%
:alt: classical inverter x1 symbol
Classical inverter x1 symbol.
The XML code describing this inverter is:
.. code-block:: xml
<circuit_model type="inv_buf" name="inv1x" prefix="inv1x">
<design_technology type="cmos" topology="inverter" size="1"/>
<port type="input" prefix="in" size="1"/>
<port type="output" prefix="out" size="1"/>
</circuit_model>
This example shows:
* The topology chosen as inverter
* Size of 1 for the output strength
* The tapered parameter is not declared and is off by default
**Power-gated Inverter x1 example**
The XML code describing an inverter which can be power-gated by the control signals ``EN`` and ``ENB`` :
.. code-block:: xml
<circuit_model type="inv_buf" name="INVTX1" prefix="INVTX1">
<design_technology type="cmos" topology="inverter" size="3" tapered="off" power_gated="true"/>
<port type="input" prefix="in" size="1" lib_name="I"/>
<port type="input" prefix="EN" size="1" lib_name="EN" is_global="true" default_val="0" is_config_enable="true"/>
<port type="input" prefix="ENB" size="1" lib_name="ENB" is_global="true" default_val="1" is_config_enable="true"/>
<port type="output" prefix="out" size="1" lib_name="Z"/>
</circuit_model>
.. note:: For power-gated inverters: all the control signals must be set as ``config_enable`` so that the testbench generation will generate testing waveforms. If the power-gated inverters are auto-generated , all the ``config_enable`` signals must be ``global`` signals as well. If the pwoer-gated inverters come from user-defined netlists, restrictions on ``global`` signals are free.
**Buffer x2 example**
:numref:`fig_buff` is the buffer symbol depicted in this example.
.. _fig_buff:
.. figure:: ./figures/Buffer.png
:scale: 100%
:alt: buffer symbol composed by 2 inverter, its output strength equal 2
Buffer made by two inverter, with an output strength of 2.
The XML code describing this buffer is:
.. code-block:: xml
<circuit_model type="inv_buf" name="buf2" prefix="buf2">
<design_technology type="cmos" topology="buffer" size="2"/>
<port type="input" prefix="in" size="1"/>
<port type="output" prefix="out" size="1"/>
</circuit_model>
This example shows:
* The topology chosen as buffer
* Size of 2 for the output strength
* The tapered parameter is not declared and is off by default
**Tapered inverter x16 example**
:numref:`fig_invtap4` is the tapered inverter symbol depicted this example.
.. _fig_invtap4:
.. figure:: ./figures/Tapered_inverter.png
:scale: 100%
:alt: tapered inverter composed by 3 inverter for an output strength = 16
Inverter with high output strength made by 3 stage of inverter.
The XML code describing this inverter is:
.. code-block:: xml
<circuit_model type="inv_buf" name="tapdrive4" prefix="tapdrive4">
<design_technology type="cmos" topology=”inverter" size="1" tapered="on" tap_drive_level="3"
f_per_stage="4"/>
<port type="input" prefix="in" size="1"/>
<port type="output" prefix="out" size="1"/>
</circuit_model>
This example shows:
* The topology chosen as inverter
* Size of 1 for the first stage output strength
* The tapered parameter is on. Then the required sub parameters are declared
* The number of stage is set to 3 by tap_drive_level
* f_per_stage is set to 4. Then 2nd stage output strength is 4* the 1st stage output strength (so 4*1 = 4) and the 3rd stage output strength is 4* the 2nd stage output strength (so 4*4 = 16).
Pass-gate Logic
---------------
.. code-block:: xml
<circuit_model type="pass_gate" name="string" prefix="string" netlist="string" is_default="int">
<design_technology type="cmos" topology="string" nmos_size="int" pmos_size="int"/>
<input_buffer exist="string" circuit_model_name="string" />
<output_buffer exist="string" circuit_model_name="string" />
<port type="input" prefix="string" size="int"/>
<port type="output" prefix="string" size="int"/>
</circuit_model>
.. note:: customized Verilog/SPICE netlists are not currently supported for pass-gate logics.
* design_technology:
* **topology:** [``transmission_gate`` | ``pass_transistor``]. The transmission gate consists of a NMOS transistor and a PMOS transistor. The pass transistor consists of a NMOS transistor.
* **nmos_size:** the size of NMOS transistor in a transmission gate or pass_transistor, expressed in terms of the min_width defined in XML node <transistors>.
* **pmos_size:** the size of PMOS transistor in a transmission gate, expressed in terms of the min_width defined in XML node <transistors>.
**Transmission-gate example**
:numref:`fig_passgate` is the pass-gate symbol depicted in this example.
.. _fig_passgate:
.. figure:: ./figures/pass-gate.png
:scale: 60%
:alt: pmos and nmos transistortors forming a pass-gate
Pass-gate made by pmos ans nmos association.
The XML code describing this pass-gate is:
.. code-block:: xml
<circuit_model type="pass_gate" name="tgate" prefix="tgate">
<design_technology type="cmos" topology="transmission_gate"/>
<port type="input" prefix="in" size="1"/>
<port type="input" prefix="sram" size="1"/>
<port type="input" prefix="sramb" size="1"/>
<port type="output" prefix="out" size="1"/>
</circuit_model>
This example shows:
* Topology is ``transmission_gate``, which means the component need entries for each transistor gate (pmos and nmos)
* 3 inputs considered, 1 for signal and 2 to control the transistors gates
* No input or output buffer used, these parameters can be uninitialized
**Pass-transistor example**
:numref:`fig_passtran` is the pass-gate symbol depicted in this example.
.. _fig_passtran:
.. figure:: ./figures/pass_transistor.png
:scale: 50%
:alt: nmos transistortor forming a pass-gate
Pass-gate made by a nmos transistor.
The XML code describing this pass-gate is:
.. code-block:: xml
<circuit_model type="pass_gate" name="t_pass" prefix="t_pass">
<design_technology type="cmos" topology="pass_transistor"/>
<port type="input" prefix="in" size="1"/>
<port type="input" prefix="sram" size="1"/>
<port type="output" prefix="out" size="1"/>
</circuit_model>
This example shows:
* Topology is ``pass_transistor``, which means the component need an entry for the transistor gate (nmos)
* 2 inputs considered, 1 for signal and 1 to control the transistor gate
* No input or output buffer used, these parameters can be uninitialized
SRAMs
-----
.. code-block:: xml
<circuit_model type="sram" name="string" prefix="string" netlist="string"/>
<design_technology type="cmos"/>
<input_buffer exist="string" circuit_model_name="string"/>
<output_buffer exist="string" circuit_model_name="string"/>
<port type="input" prefix="string" size="int"/>
<port type="output" prefix="string" size="int"/>
</circuit_model>
.. note:: The circuit designs of SRAMs are highly dependent on the technology node and well optimized by engineers. Therefore, FPGA-Verilog/SPICE requires users to provide their customized SRAM Verilog/SPICE/Verilog netlists. A sample Verilog/SPICE netlist of SRAM can be found in the directory SpiceNetlists in the released package. FPGA-Verilog/SPICE assumes that all the LUTs and MUXes employ the SRAM circuit design. Therefore, currently only one SRAM type is allowed to be defined.
.. 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.
Logic gates
-----------
.. code-block:: xml
<circuit_model type="gate" name="string" prefix="string" netlist="string" dump_explicit_port_map="true|false"/>
<design_technology type="cmos" topology="string"/>
<input_buffer exist="string" circuit_model_name="string"/>
<output_buffer exist="string" circuit_model_name="string"/>
<port type="input" prefix="string" lib_name="string" size="int"/>
<port type="output" prefix="string" lib_name="string" size="int"/>
</circuit_model>
.. note:: The circuit model in the type of gate aims to support direct mapping to standard cells or customized cells provided by technology vendors or users.
.. note:: The logic functionality of a gate can be defined through the XML keyword ``topology``. Currently, OpenFPGA supports AND, OR and MUX2 gates. As for standard cells, the size of each port is limited to 1. Currently, only 2-input and single-output logic gates are supported.
.. note:: It may happen that the port sequence in generated Verilog netlists has conflicts with the port sequence in standard and customized cells. To avoid this, users can set the XML keyword ``dump_explicit_port_map`` to be true, which enables explicit port mapping are dumped. Users can specify the pin/port name in the standard cell library using the XML keyword ``lib_name``.
Multiplexers
------------
.. code-block:: xml
<circuit_model type="mux" name="string" prefix="string" is_default="int">
<design_technology type="string" structure="string" num_level="int" add_const_input="string" const_input_val="int" local_encoder="string" ron="float" roff="float" prog_transistor_size="float"/>
<input_buffer exist="string" circuit_model_name="string"/>
<output_buffer exist="string" circuit_model_name="string"/>
<pass_gate_logic type="string" circuit_model_name="string"/>
<port type="input" prefix="string" size="int"/>
<port type="output" prefix="string" size="int"/>
<port type="sram" prefix="string" size="int"/>
</circuit_model>
.. note:: customized Verilog/SPICE netlists are not currently supported for multiplexers.
* design_technology:
* **structure:** can be [``tree`` \| ``multi-level`` \| ``one-level``]. The structure options are valid for SRAM-based multiplexers. For RRAM-based multiplexers, currently we only support the circuit design in [5]. If ``multi-level`` the following parameter is required:
* **num_level:** specify the number of levels when multi-level structure is selected, only.
* **add_const_input:** can be [``true`` \| ``false``]. When enabled, an extra input will be added to the multiplexer circuits defined in this ``circuit_model``. For example, an 4-input multiplexer will be turned to a 5-input multiplexer. The extra input will be wired to a constant value, which can be specified through the XML syntax ``const_input_val``. The constant value can be either 0 or 1 (By default it is 0). Note that adding such input will help reducing the leakage power of FPGA and parasitic signal activities, with a limited area overhead.
* **const_input_val:** specify the constant value, to which the extra input will be connected. This syntax is only valid when the ``add_const_input`` is set to true.
* **local_encoder:** can be [``true`` \| ``false``]. When enabled, an local encoder will be added to the multiplexer circuits defined in this ``circuit_model``. The local encoder will be interface the SRAM inputs of multiplexing structure and SRAMs. It can encode the one-hot codes (that drive the select port of multiplexing structure) to a binary code. For example, 8-bit ``00000001`` will be encoded to 3-bit ``000``. This will help reduce the number of SRAM cells used in FPGAs as well as configuration time (especially for scan-chain configuration protocols). But it may cost an area overhead.
.. note:: Local encoders are only applicable for one-level and multi-level multiplexers. Tree-like multiplexers are already encoded in their nature.
* **prog_transistor_size:** valid only when the type of design technology is ``rram``. Specify the size of programming transistors used in the RRAM-based multiplexer, we use only n-type transistor and the size should be expressed in terms of the min_width defined in XML node ``transistors``. If type of design technology is ``rram``, then the following parameters are required:
* **ron:** valid only when the type of design technology is rram. Specify the on-resistance of the RRAM device used in the RRAM-based multiplexer.
* **roff:** valid only when the type of design technology is rram. Specify the off-resistance of the RRAM device used in the RRAM-based multiplexer.
* port: for a multiplexer, the three types of ports, ``input``, ``output`` and ``sram`` should be defined.
.. note:: For tree-like multiplexers, they can be built with standard cell MUX2. To enable this, users should define a ``circuit_model``, which describes a 2-input multiplexer (See details and examples in how to define a logic gate using ``circuit_model``. In this case, the ``circuit_model_name`` in the ``pass_gate_logic`` should be the name of MUX2 ``circuit_model``.
**Mux 1 level example**
:numref:`fig_mux1` illustrates an example of multiplexer modelling, which consists of input/output buffers and a transmission-gate-based tree structure.
.. _fig_mux1:
.. figure:: ./figures/mux1lvl.png
:scale: 60%
:alt: Detailed one level Multiplexer
An example of a one level multiplexer with transistor-level design parameters
The code describing this Multiplexer is:
.. code-block:: xml
<circuit_model type="mux" name="mux_1level" prefix="mux_1level">
<design_technology type="cmos" structure="one-level"/>
<input_buffer exist="on" circuit_model_name="inv1x"/>
<output_buffer exist="on" circuit_model_name="tapbuf4"/>
<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="4"/>
</circuit_model>
**This example shows:**
* Each circuit model composing the Multiplexer
* The possibility to select the input or output buffers
* The possibility to select the pass-gate inside the Mux.
**Mux-tree example**
:numref:`fig_mux` illustrates an example of multiplexer modelling, which consists of input/output buffers and a transmission-gate-based tree structure.
.. _fig_mux:
.. figure:: ./figures/mux.png
:scale: 100%
:alt: Examples of Mux-tree
An example of a tree-like multiplexer with transistor-level design parameters
If we arbitrarily fix the number of Mux entries at 4, the following code could illustrate (a):
.. code-block:: xml
<circuit_model type="mux" name="mux_tree" prefix="mux_tree">
<design_technology type="cmos" structure="tree"/>
<input_buffer exist="on" circuit_model_name="inv1x"/>
<output_buffer exist="on" circuit_model_name="tapdrive4"/>
<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="3"/>
</circuit_model>
**This example shows:**
* The tree topology, 4 entries split in 2 2-to-1 Muxes then another one make the final selection.
* The possibility to select the input or output buffers
* The number of entries parametrized by ``size`` in input port-type.
Look-Up Tables
--------------
.. code-block:: xml
<circuit_model type="lut" name="string" prefix="string" is_default="int" netlist="string"/>
<design_technology type="cmos" fracturable_lut="true|false"/>
<input_buffer exist="string" circuit_model_name="string"/>
<output_buffer exist="string" circuit_model_name="string"/>
<lut_input_buffer exist="string" circuit_model_name="string"/>
<lut_intermediate_buffer exist="string" circuit_model_name="string" location_map="string"/>
<lut_input_inverter exist="string" circuit_model_name="string"/>
<pass_gate_logic type="string" circuit_model_name="string"/>
<port type="input" prefix="string" size="int" tri_state_map="----11" circuit_model_name="string"/>
<port type="output" prefix="string" size="int" lut_frac_level="int" lut_output_mask="int"/>
<port type="sram" prefix="string" size="int" mode_select="true|false" circuit_model_name="string" default_val="0|1"/>
</circuit_model>
.. note:: The Verilog/SPICE netlists of LUT can be auto-generated or customized.
The auto-generated LUTs are based on a tree-like multiplexer, whose gates of the transistors are used as the inputs of LUTs and the drains/sources of the transistors are used for configurable memories (SRAMs).
The LUT provided in customized Verilog/SPICE netlist should have the same decoding methodology as the traditional LUT.
Additional design parameters for LUTs:
* **lut_input_buffer:** Define transistor-level description for the buffer for the inputs of a LUT (gates of the internal multiplexer). Use keyword circuit_model_name to specify the circuit_model that containing details of the circuit.
* **lut_input_inverter:** Define transistor-level description for the inverter for the inputs of a LUT (gates of the internal multiplexer). Use keyword circuit_model_name to specify the circuit_model that containing details of the circuit.
* **lut_intermediate_buffer:** Define transistor-level description for the buffer locating at intermediate stages of internal multiplexer of a LUT. Use keyword circuit_model_name to specify the circuit_model that containing details of the circuit. To customize the location, users can define an integer array in the XML keyword location_map. For example, "-1-1-" indicates buffer inseration to every two stages of the LUT multiplexer tree, considering a 6-input LUT.
Instructions of defining design parameters:
* **input_buffer:** Specify the buffer/inverter that connects the SRAM outputs to the inputs of multiplexer.
* **pass_gate_logic:** Specify the pass-gates of the internal multiplexer, the same as the multiplexers.
* **port:** three types of ports (input, output and sram) should be defined. If the user provides an customized Verilog/SPICE netlist, the bandwidth of ports should be defined to the same as the Verilog/SPICE netlist. To support customizable LUTs, each type of port contain special keywords. For input ports, the keyword tri_state_map aims to customize which inputs are fixed to constant values when the LUT is in fracturable modes. For example, ``tri_state_map`` ="----11" indicates that the last two inputs will be fixed to be logic '1' when a 6-input LUT is in fracturable modes. The circuit_model_name of input port is used to specify which logic gates will be used to tri-state the inputs in fracturable LUT modes. It is required to use an AND gate to force logic '0' or an OR gate to force logic '1' for the input ports. For output ports, the keyword lut_frac_level is used to specify the level in LUT multiplexer tree where the output port are wired to. For example, lut_frac_level="4" in a fracturable LUT6 means that the output are potentially wired to the 4th stage of a LUT multiplexer and it is an output of a LUT4. The keyword lut_output_mask describes which fracturable outputs are used. For instance, in a 6-LUT, there are potentially four LUT4 outputs can be wired out. lut_output_mask="0,2" indicates that only the first and the thrid LUT4 outputs will be used in fracturable mode. Note that the size of the output port should be consistent to the length of lut_output_mask.
* **SRAM port for mode selection:** To enable switch between different operating modes, the SRAM bits of a fracturable LUT consists of two parts: configuration memory and mode selecting. The SRAM port for mode selection is specified through the XML keyword mode_select. Note that the size of such SRAM port should be consistent to the number of 1s or 0s in the ``tri_state_map``.
**LUT example**
:numref:`fig_lut` illustrates an example of LUT modeling, which consists of input/output buffers and a transmission-gate-based tree structure.
.. _fig_lut:
.. figure:: ./figures/lut.png
:scale: 100%
:alt: Detailed LUT composition
An example of a LUT with transistor-level design parameters.
The code describing this LUT is:
.. code-block:: xml
<circuit_model type="lut" name="lut6" prefix="lut6">
<input_buffer exist="on" circuit_model="inv1x"/>
<output_buffer exist="on" circuit_model_name="inv1x"/>
<lut_input_buffer exist="on" circuit_model_name="buf2"/>
<pass_gate_logic circuit_model_name="tgate"/>
<port type="input" prefix="in" size="6"/>
<port type="output" prefix="out" size="1"/>
<port type="sram" prefix="sram" size="64"/>
</circuit_model>
**This example shows:**
* The difference between ``input_buffer`` and ``lut_input_buffer`` and that they are independent.
* How each blocks is defined
Flip-Flops
----------
.. code-block:: xml
<circuit_model type="ff" name="string" prefix="string" netlist="string"/>
<design_technology type="cmos"/>
<input_buffer exist="string" circuit_model_name="string"/>
<output_buffer exist="string" circuit_model_name="string"/>
<port type="input" prefix="string" size="int"/>
<port type="output" prefix="string" size="int"/>
<port type="clock" prefix="string" size="int"/>
</circuit_model>
.. note:: The circuit designs of flip-flops are highly dependent on the technology node and well optimized by engineers. Therefore, FPGA-Verilog/SPICE requires users to provide their customized FF Verilog/SPICE/Verilog netlists. A sample Verilog/SPICE netlist of FF can be found in the directory SpiceNetlists in the released package.
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.
FPGA-Verilog/SPICE currently support only one clock domain in the FPGA. Therefore there should be only one clock port to be defined and the size of the clock port should be 1.
Instructions of defining design parameters:
* **circuit_model type:** can be ``ff`` or ``scff``. FF is typical Flip-Flop, SCFF is Scan-Chain Flip-Flop
* **port:** three types of ports (``input``, ``output`` and ``clock``) should be defined. If the user provides a customized Verilog/SPICE netlist, the bandwidth of ports should be defined to the same as the Verilog/SPICE netlist.
.. note:: In a valid FPGA architecture, users should provide at least either a SCFF or a SRAM, so that the configurations can loaded to core logic.
**FF example**
:numref:`fig_ff` illustrates an example of LUT modeling, which consists of input/output buffers and a transmission-gate-based tree structure.
.. _fig_ff:
.. figure:: ./figures/FF.png
:scale: 100%
:alt: FF symbol
An example of classical Flip-Flop.
The code describing this FF is:
.. code-block:: xml
<circuit_model type="ff" name="dff" prefix="dff" verilog_netlist="ff.v">
<port type="input" prefix="D" size="1"/>
<port type="input" prefix="Set" size="1" is_global="true"/>
<port type="input" prefix="Reset" size="1" is_global="true"/>
<port type="output" prefix="Q" size="1"/>
<port type="clock" prefix="clk" size="1" is_global="true"/>
</circuit_model>
**This example shows:**
* Circuit model type as ``ff``
* The verilog netlist file associated to this component ``ff.v``
* 3 ports, ``Set``, ``Reset`` and ``clk``, defined as global
**SCFF example**
:numref:`fig_scff` illustrates an example of LUT modeling, which consists of input/output buffers and a transmission-gate-based tree structure.
.. _fig_scff:
.. figure:: ./figures/scff.png
:scale: 100%
:alt: SCFF symbol
An example of a Scan-Chain Flip-Flop.
The code describing this FF is:
.. code-block:: xml
<circuit_model type="scff" name="scff" prefix="scff" verilog_netlist="scff.v">
<port type="input" prefix="D" size="1"/>
<port type="output" prefix="Q" size="2"/>
<port type="clock" prefix="clk" size="1" is_global="true"/>
</circuit_model>
**This example shows:**
* Circuit model type as ``scff``
* The verilog netlist file associated to this component ``scff.v``
* 1 port, ``clk``, defined as global
Hard Logics
-----------
.. code-block:: xml
<circuit_model type="hardlogic" name="string" prefix="string" netlist="string"/>
<design_technology type="cmos"/>
<input_buffer exist="string" circuit_model_name="string"/>
<output_buffer exist="string" circuit_model_name="string"/>
<port type="input" prefix="string" size="int"/>
<port type="output" prefix="string" size="int"/>
</circuit_model>
.. note:: Hard logics are defined for non-configurable resources in FPGA architectures, such as adders, multipliers and RAM blocks.
Their circuit designs are highly dependent on the technology node and well optimized by engineers.
As more functional units are included in FPGA architecture, it is impossible to auto-generate these functional units [3].
Therefore, FPGA-Verilog/SPICE requires users to provide their customized Verilog/SPICE netlists. A sample Verilog/SPICE netlist of a 1-bit adder can be found in the directory SpiceNetlists in the released package.
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.
Instructions of defining design parameters:
* **port:** two types of ports (``input`` and ``output``) should be defined. If the user provides a user-defined Verilog/SPICE netlist, the bandwidth of ports should be defined to the same as the Verilog/SPICE netlist.
Routing Wire Segments
---------------------
FPGA-Verilog/SPICE provides two types of Verilog/SPICE models for the wire segments in FPGA architecture:
* One type is called ``wire``, which targets the local wires inside the logic blocks. The wire has one input and one output, directly connecting the output of a driver and the input of the downstream unit, respectively
* The other type is called ``chan_wire``, especially targeting the channel wires. The channel wires have one input and two outputs, one of which is connected to the inputs of Connection Boxes while the other is connected to the inputs of Switch Boxes. Two outputs are created because from the view of layout, the inputs of Connection Boxes are typically connected to the middle point of channel wires, which has less parasitic resistances and capacitances than connected to the ending point.
.. code-block:: xml
<circuit_model type="string" name="string" prefix="string" netlist="string"/>
<design_technology type="cmos"/>
<input_buffer exist="string" circuit_model_name="string"/>
<output_buffer exist="string" circuit_model_name="string"/>
<port type="input" prefix="string" size="int"/>
<port type="output" prefix="string" size="int"/>
<wire_param model_type="string" res_val="float" cap_val="float" level="int"/>
</circuit_model>
.. note:: FPGA-Verilog/SPICE can auto-generate the Verilog/SPICE model for wires while also allows users to provide their customized Verilog/SPICE netlists.
The information of input and output buffer should be clearly specified according to the customized netlist! The existence of input/output buffers will influence the decision in creating testbenches, which may leads to larger errors in power analysis.
Instructions of defining design parameters:
* **type:** can be [``wire`` | ``chan_wire``]. The Verilog/SPICE model wire targets the local wire inside the logic block while the chan_wire targets the channel wires in global routing.
* **port:** two types of ports (``input`` and ``output``) should be defined. If the user provides an customized Verilog/SPICE netlist, the bandwidth of ports should be defined to the same as the Verilog/SPICE netlist.
* **wire_param:**
* **model_type:** can be [``pi`` | ``T``], corresponding to the π-type and T-type RC wire models.
* **res_val:** specify the total resistance of the wire
* **cap_val:** specify the total capacitance of the wire.
* **level:** specify the number of levels of the RC wire model.
**Chan-Wire example**
:numref:`fig_wire` depicts the modeling for a length-2 channel wire.
.. _fig_wire:
.. figure:: ./figures/wire.png
:scale: 100%
:alt: map to buried treasure
An example of a length-2 channel wire modeling
The code describing this wire is:
.. code-block:: xml
<circuit_model type="chan_wire" name="segment0" prefix="chan_wire"/>
<design_technology type="cmos"/>
<port type="input" prefix="mux_out" size="1"/>
<port type="output" prefix="cb_sb" size="2"/>
<wire_param model_type="pi" res_val="103.84" cap_val="13.80e-15" level="1"/>
</circuit_model>
**This example shows**
* How to use the ``wire_param`` for a π-type RC wire model
* How to use this circuit_model to auto-generate the Verilog/SPICE netlist
I/O pads
--------
.. code-block:: xml
<circuit_model type="iopads" name="string" prefix="string" netlist="string"/>
<design_technology type="cmos"/>
<input_buffer exist="string" circuit_model_name="string"/>
<output_buffer exist="string" circuit_model_name="string"/>
<port type="input" prefix="string" size="int"/>
<port type="output" prefix="string" size="int"/>
<port type="sram" prefix="string" size="int" mode_select="true|false"
circuit_model_name="string" default_val="int"/>
</circuit_model>
.. note:: The circuit designs of I/O pads are highly dependent on the technology node and well optimized by engineers.
Therefore, FPGA-Verilog/SPICE requires users to provide their customized Verilog/SPICE/Verilog netlists. A sample Verilog/SPICE netlist of an I/O pad can be found in the directory SpiceNetlists in the released package.
The information of input and output buffer should be clearly specified according to the customized netlist! The existence of input/output buffers will influence the decision in creating testbenches, which may leads to larger errors in power analysis.
Instructions of defining design parameters:
* **port:** four types of ports (``input``, ``output``, ``inout`` and ``sram``) should be defined. If the user provides a user-defined Verilog/SPICE netlist, the bandwidth of ports should be defined to the same as the Verilog/SPICE netlist.
**IO-pad example**
:numref:`fig_iopad` depicts an IO-Pad.
.. _fig_iopad:
.. figure:: ./figures/iopad.png
:scale: 100%
:alt: IO-Pad symbol
An example of an IO-Pad
The code describing this IO-Pad is:
.. code-block:: xml
<circuit_model type="iopad" name="iopad" prefix="iopad" verilog_netlist="io.v">
<port type="inout" prefix="pad" size="1"/>
<port type="sram" prefix="dir" size="1" circuit_model_name="scff"/>
<port type="input" prefix="data_in" size="1"/>
<port type="input" prefix="zin" size="1" is_global="true"/>
<port type="output" prefix="data out" size="1"/>
</circuit_model>
**This example shows**
* The association of the verilog netlist file ``io.v``
* The inout pad port_type, which means as inout as output.
* The instantiation of a SCFF as sram

104
docs/source/arch_lang/circuit_modules.rst
View File

@ -1,104 +0,0 @@
Define Circuit-level Modules
============================
To support FPGA Verilog/SPICE, Verily and Bitstream Generator, physical modules containing gate-level and transistor-level features are required for FPGA primitive blocks.
The physical modules are defined in XML syntax, similar to the original VPR FPGA architecture description language.
For each module that appears in the FPGA architecture, a circuit model should be defined. In the definition of a circuit model, the user can specify if the Verilog/SPICE netlist of the module is either auto-generated or user-defined.
Define circuit_models
---------------------
.. code-block:: xml
<module_circuit_models>
<circuit_model type="string" name="string" prefix="string" is_default="int"
circuit_netlist="string" verilog_netlist="string" dump_structural_verilog="string">
<transistor-level circuit_design_features="developped_further" />
</circuit_model>
</module_circuit_models>
* **module_circuit_models**: the father node for all the circuit models. All the circuit models should be defined under this XML node.
* **circuit_model**: the child node defining transistor-level modeling parameters.
* **type**: can be [ ``inv_buf`` | ``pass_gate`` | ``gate`` | ``mux`` | ``wire`` | ``chan_wire`` | ``sram`` | ``lut`` | ``ff`` | ``scff`` | ``hard_logic`` | ``iopad`` ]. Specify the type of circuit model. The provided types cover all the modules in FPGAs. For the circuit models in the type of mux/wire/chan_wire/lut, FPGA-Verilog/SPICE can auto-generate Verilog/SPICE netlists. For the rest, FPGA-Verilog/SPICE requires a user-defined Verilog/SPICE netlist.
* **name**: define the name of this circuit model. The name should be unique and will be used to create the sub-circuit of the circuit model in Verilog/SPICE netlists. Note that for a customized Verilog/SPICE netlist, the name defined here should be the name of the top-level sub-circuit in the customized Verilog/SPICE netlist. FPGA-Verilog/SPICE will check if the given name is conflicted with any reserved words.
* **prefix**: specify the name of the circuit_model to shown in the auto-generated Verilog/SPICE netlists. The prefix can be the same as the name defined above. And again, the prefix should be unique.
* **is_default**: can be [``1`` | ``0``], corresponding to [``true`` | ``false``] respectively. Specify this circuit model is the default one for some modules, such as multiplexers. If a module is not linked to any circuit model by users, FPGA-Verilog/SPICE will find the default circuit model defined in the same type and link. For a circuit model type, only one circuit model can be set as default.
* **circuit_netlist**: specify the path and file name of a customized Verilog/SPICE netlist. For some modules such as SRAMs, FFs, inpads, and outpads, FPGA-Verilog/SPICE does not support auto-generation of the transistor-level sub-circuits because their circuit design is highly dependent on the technology nodes. These circuit designs should be specified by users. For the other modules that can be auto-generated by FPGA-Verilog/SPICE, the user can also define a custom netlist. Multiplexers cannot be user-defined.
* **verilog_netlist**: specify the path and file name of a customized Verilog netlist. For some modules such as SRAMs, FFs, inpad and outpads, FPGA-Verilog/SPICE does not support auto-generation of the transistor-level sub-circuits because their circuit design is highly dependent on the technology nodes. These circuit designs should be specified by users. For the other modules that can be auto-generated by FPGA-Verilog/SPICE, the user can also define a custom netlist. Multiplexers cannot be user-defined.
* **dump_structural_verilog**: when the value of this keyword is set to be true, Verilog generator will output gate-level netlists of this module, instead of behavior-level. Gate-level netlists bring more opportunities in layout-level optimization while behavior-level is more suitable for high-speed formal verification and easier in debugging with HDL simulators.
.. note:: If netlist is not specified, FPGA-Verilog/SPICE auto-generates the Verilog/SPICE netlists for multiplexers, wires, and LUTs.
.. note:: The user-defined netlists, such as LUTs, the decoding methodology should comply with the auto-generated LUTs (See Section 4.5)
.. note:: Under the XML node circuit_model, the features of transistor-level designs can be defined. In the following table, we show the common features supported for all the modules. Then, we will introduce unique features supported only for some circuit models types.
Transistor level
----------------
.. code-block:: xml
<circuit_model type="string" name="string" prefix="string" is_default="int" netlist="string"
dump_structural_verilog="string">
<design_technology type="string"/>
<input_buffer exist="string" circuit_model_name="string"/>
<output_buffer exist="string" circuit_model_name="string"/>
<pass_gate_logic type="string" circuit_model_name="string"/>
<port type="string" prefix="string" lib_name="string" size="int" default_val="int" circuit_model_name="string"
mode_select="boolean" is_global="boolean" is_set="boolean" is_reset="boolean"
is_config_enable="boolean"/>
</circuit_model>
* design_technology :
* **type:** [cmos|rram]. Specify the type of design technology of the circuit_model.
.. note:: Currently, the RRAM-based designs are only supported for multiplexers.
* input_buffer and output_buffer:
* **exist:** [on|off]. Define the existence of the input_buffer or output_buffer. Note that the existence is valid for all the inputs and outputs. Note that if users want only part of the inputs (or outputs) to be buffered, this is not supported here. A solution can be building a user-defined Verilog/SPICE netlist.
* **circuit_model_name:** Specify the name of circuit model which is used to implement input/output buffer, the type of specified circuit model should be inv_buf.
* pass_gate_logic: defined the parameters in pass-gates, which are used in building multiplexers and LUTs.
* **circuit_model_name:** Specify the name of the circuit model which is used to implement transmission gate, the type of specified circuit model should be pass_gate.
* port: define the port list of a circuit model.
* **type:** can be [input|output|sram|clock]. For programmable modules, such as multiplexers and LUTs, SRAM ports should be defined. For registers, such as FFs and memory banks, clock ports should be defined.
* **prefix:** the name of the port to appear in the autogenerated netlists. Each port will be shown as ``<prefix>[i]`` in Verilog/SPICE netlists.
* **lib_name:** the name of the port defined in standard cells or customized cells. If not specified, this attribute will be the same as ``prefix``.
* **size:** bandwidth of the port.
* **default_val:** default logic value of a port, which is used as the initial logic value of this port in testbench generation. Can be either 0 or 1. We assume each pin of this port has the same default value.
* **circuit_model_name:** only valid when the type of port is sram. Specify the name of the circuit model which is connected to this port.
* **mode_select:** can be either ``true`` or ``false``. Specify if this port controls the mode switching in a configurable logic block. Only valid when the type of this port is sram. (A configurable logic block can operate in different modes, which is controlled by SRAM bits.)
* **is_global:** can be either ``true`` or ``false``. Specify if this port is a global port, which will be routed globally. Note that when multiple global ports are defined with the same name, these global ports will be short-wired together.
* **is_set:** can be either ``true`` or ``false``. Specify if this port controls a set signal. Only valid when ``is_global`` is true. All the set ports are connected to global set voltage stimuli in testbenches.
* **is_reset:** can be either ``true`` or ``false``. Specify if this port controls a reset signal. Only valid when ``is_global`` is true. All the reset ports are connected to a global reset voltage stimuli in testbenches.
* **is_config_enable:** can be either ``true`` or ``false``. Only valid when ``is_global`` is true. Specify if this port controls a configuration-enable signal. This port is only enabled during FPGA configuration, and always disabled during FPGA operation. All the ``config_enable`` ports are connected to global configuration-enable voltage stimuli in testbenches.
.. note:: Different types of ``circuit_model`` have different XML syntax, with which users can highly customize their circuit topologies. See refer to examples of ``circuit_model`` for more details.
.. note:: Note that we have a list of reserved port names, which indicate the usage of these ports when building FPGA fabrics. Please do not use ``mem_out``, ``mem_inv``, ``bl``, ``wl``, ``blb``, ``wlb``, ``ccff_head`` and ``ccff_tail``.

BIN
docs/source/arch_lang/figures/.DS_Store vendored
View File

Binary file not shown.

8
docs/source/arch_lang/generality.rst
View File

@ -1,8 +0,0 @@
General Hierarchy
=================
The extension of the VPR architectural description language is developed as an independent branch of the original one. Most of the FPGA-SPICE descriptions are located under a XML node called <spice_settings>, which is a child node under the root node <architecture>.
Under the <spice_settings>, some child node is created for describing SPICE simulation settings, technology library and transistor-level modeling of circuit modules.
In the following sub-sections, we will introduce the structures of these XML nodes and the parameters provided.

24
docs/source/arch_lang/index.rst
View File

@ -1,24 +0,0 @@
Extended Architecture Description Language
==========================================
.. _arch_lang:
Extended FPGA Architecture Description Language
.. toctree::
:maxdepth: 2
generality
interconnect
spice_sim_setting
tech_lib
circuit_modules
circuit_model_examples
link_circuit_modules

184
docs/source/arch_lang/link_circuit_modules.rst
View File

@ -1,184 +0,0 @@
Link circuit modules
--------------------
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.
SRAM
====
To link the defined circuit model of SRAM into the FPGA architecture description, a new line in XML format should be added under the XML node device. The new XML node is named as sram, which defines the area of an SRAM and the name of the circuit model to be linked. An example is shown as follows:
.. code-block:: xml
<sram area=”int” circuit_model_name=”string”>
<sram>
<spice organization="string" circuit_model_name="scff"/>
<verilog organization="string" circuit_model_name="scff"/>
</sram>
* **area:** is expressed in terms of the number of minimum width transistors. The SRAM area defined in this line is used in the area estimation of global routing multiplexers. circuit_model_name should match the name of the circuit model that has been defined under XML node module_circuit_model. The type of the linked circuit model should be sram.
* **organization:** [scan-chain|memory_bank|standalone], is the type of configuration circuits.
:numref:`fig_sram` illustrates an example where a memory organization using memory decoders and 6-transistor SRAMs.
.. _fig_sram:
.. figure:: figures/sram.png
:scale: 100%
:alt: map to buried treasure
Example of a memory organization using memory decoders
.. note:: Currently circuit only supports standalone memory organization.
.. note:: Currently RRAM-based FPGA only supports memory-bank organization for Verilog Generator.
Here is an example.
.. code-block:: xml
<sram area=”4” circuit_model_name=”sram6T”>
Switch Boxes
=============
Original VPR architecture description contains an XML node called switchlist under which all the multiplexers of switch blocks are described.
To link a defined circuit model to a multiplexer in the switch blocks, a new XML property circuit_model_name should be added to the descriptions.
Here is an example:
.. code-block:: xml
<switchlist>
<switch type=”mux” name=”string” R=”float” Cin=”float” Cout=”float” Tdel=”float” mux_trans_size=”float” buf_size=”float” circuit_model_name=”string”/>
</switchlist>
* **circuit_model_name:** should match a circuit model whose type is mux defined under module_circuit_models.
Connection Blocks
==================
To link the defined circuit model of the multiplexer to the Connection Blocks, a circuit_model_name should be added to the definition of Connection Blocks switches. However, the original architecture descriptions do not offer a switch description for connection boxes as they do for the switch blocks.
Therefore, FPGA-circuit requires a new XML node called **cblock** under the root XML node architecture, where a switch for connection blocks can be defined.
Here is the example:
.. code-block:: xml
<cblock>
<switch type=”mux” name=”string” R=”float” Cin=”float” Cout=”float” Tdel=”float” mux_trans_size=”float” buf_size=”float” circuit_model_name=”string”/>
</cblock>
* **circuit_model_name:** should match a circuit model whose type is mux defined under module_circuit_models.
Channel Wire Segments
=====================
Similar to the Switch Boxes and Connection Blocks, the channel wire segments in the original architecture descriptions can be adapted to provide a link to the defined circuit model.
.. code-block:: xml
<segmentlist>
<segment freq=”float” length=”int” type=”string” Rmetal=”float” Cmetal=”float” circuit_model_name=”string”/>
</segmentlist>
* circuit_model_name: should match a circuit model whose type is chan_wire defined under module_circuit_models.
Primitive Blocks inside Multi-mode Configurable Logic Blocks
=============================================================
The architecture description employs a hierarchy of ``pb_types`` to depict the sub-modules and complex interconnections inside logic blocks. Each leaf node and interconnection in the pb_type hierarchy should be linked to a circuit model.
Each primitive block, i.e., the leaf ``pb_types``, should be linked to a valid circuit model, using the XML syntax ``circuit_model_name``.
The ``circuit_model_name`` should match the given name of a ``circuit_model`` defined by users.
.. code-block:: xml
<!-- Multi-mode BLE -->
<pb_type name="ble" num_pb="10" physical_mode_name="ble_phy"/>
<!-- Physical implementation of BLE shown in Fig. :ref:`` -->
<mode name="ble_phy" disabled_in_packing="true"/>
<!-- Define a 6-input LUT in BLE and link it to circuit model -->
<pb_type name="flut6_phy" circuit_model_name="frac_lut6">
<input name="in" num_pins="6"/>
<output name="lut4_out" num_pins="4"/>
<output name="lut5_out" num_pins="2"/>
<output name="lut6_out" num_pins="1"/>
</pb_type>
<pb_type name="lut4_phy" circuit_model_name="lut4">
<input name="in" num_pins="4"/>
<output name="out" num_pins="1"/>
</pb_type>
<pb_type name="adder_phy" num_pb="2" circuit_model_name="adder">
<input name="a" num_pins="1"/>
<input name="b" num_pins="1"/>
<input name="cin" num_pins="1"/>
<output name="cout" num_pins="1"/>
<output name="sumout" num_pins="1"/>
</pb_type>
<pb_type name="ff_phy" num_pb="2" circuit_model_name="dff">
<input name="D" num_pins="1"/>
<output name="Q" num_pins="1"/>
<clock name="clk" num_pins="1"/>
</pb_type>
<interconnect>
<!-- Routing multiplexers are omitted in this example. -->
</interconnect>
</mode>
<!-- Arithmetic mode of BLE shown in Fig. 2(b)-->
<mode name="flut4_arithmetic"/>
<pb_type name="flut4_arith" num_pb="4"/>
<!-- Define a virtual 4-input LUT in BLE and link it to physical 6-input LUT defined at LINE 6 -->
<pb_type name="lut4" mode_bits="01" physical_pb_type_name="flut6_phy">
<!-- Define an input port and link it to its physical port defined at LINE 7 -->
<input name="in" num_pins="4" physical_mode_pin="in[3:0]"/>
<!-- Define an output port and link it to its physical port defined at LINE 8 -->
<output name="out" num_pins="1" physical_mode_pin="lut4_out"/>
</pb_type>
<pb_type name="adder" num_pb="2" physical_pb_type_name="adder_phy">
<input name="a" num_pins="1" physical_mode_pin="a"/>
<input name="b" num_pins="1" physical_mode_pin="b"/>
<input name="cin" num_pins="1" physical_mode_pin="cin"/>
<output name="cout" num_pins="1" physical_mode_pin="cout"/>
<output name="sumout" num_pins="1" physical_mode_pin="sumout"/>
</pb_type>
<pb_type name="ff" num_pb="2" physical_pb_type_name="ff_phy">
<input name="D" num_pins="1" physical_mode_pin="D"/>
<output name="Q" num_pins="1" physical_mode_pin="Q"/>
<clock name="clk" num_pins="1" physical_mode_pin="clk"/>
</pb_type>
<interconnect>
<!-- Routing multiplexers are omitted in this example. Full details can be found in [21] -->
</interconnect>
</pb_type>
</mode>
<!-- More operating modes can be defined -->
</pb_type>
* **physical_mode_name:** tell the name of the mode that describes the physical implementation of the configurable block. This is critical in modeling actual circuit designs and architecture of an FPGA. Typically, only one physical_mode should be specified for each multi-mode ``pb_type``.
* **idle_mode_name:** tell the name of the mode that the ``pb_type`` is configured to be by default. This is critical in building circuit netlists for unused logic blocks.
* **circuit_model_name:** should match a circuit model defined under ``module_circuit_models``. The ``circuit_model_name`` is mandatory for every leaf ``pb_type`` in a physical_mode ``pb_type``. For the interconnection type direct, the type of the linked circuit model should be wire. For multiplexers, the type of linked circuit model should be ``mux``. For complete, the type of the linked circuit model can be either ``mux`` or ``wire``, depending on the case.
* **mode_bits** specifies the configuration bits for the ``circuit_model`` when operating at an operating mode. The length of ``mode_bits`` should match the ``port`` size defined in ``circuit_model``. The ``mode_bits`` should be derived from circuit designs while users are responsible for its correctness. FPGA-Bitstreamm will add the ``mode_bits`` during bitstream generation.
* **physical_pb_type_name** creates the link on ``pb_type`` between operating and physical modes. This syntax is mandatory for every leaf ``pb_type`` in an operating mode ``pb_type``. It should be a valid name of leaf ``pb_type`` in physical mode.
* **physical_pb_type_index_factor** aims to align the indices for ``pb_type`` between operating and physical modes, especially when an operating mode contains multiple ``pb_type`` (``num_pb``>1) that are linked to the same physical ``pb_type``. When ``physical_pb_type_name`` is larger than 1, the index of ``pb_type`` will be multipled by the given factor.
* **physical_pb_type_index_offset** aims to align the indices for ``pb_type`` between operating and physical modes, especially when an operating mode contains multiple ``pb_type`` (``num_pb``>1) that are linked to the same physical ``pb_type``. When ``physical_pb_type_name`` is larger than 1, the index of ``pb_type`` will be shifted by the given factor.
* **physical_mode_pin** creates the linke on ``port`` of ``pb_type`` between operating and physical modes. This syntax is mandatory for every leaf ``pb_type`` in an operating mode ``pb_type``. It should be a valid ``port`` name of leaf ``pb_type`` in physical mode and the port size should also match.
* **physical_mode_pin_rotate_offset** aims to align the pin indices for ``port`` of ``pb_type`` between operating and physical modes, especially when an operating mode contains multiple ``pb_type`` (``num_pb``>1) that are linked to the same physical ``pb_type``. When ``physical_mode_pin_rotate_offset`` is larger than zero, the pin index of ``pb_type`` (whose index is large than 1) will be shifted by the given offset.
.. note::
It is highly recommended that only one physical mode is defined for a multi-mode configurable block. Try not to use nested physical mode definition. This will ease the debugging and lead to clean XML description.
.. note::
Be careful in using ``physical_pb_type_index_factor``, ``physical_pb_type_index_offset`` and ``physical_mode_pin_rotate_offset``! Try to avoid using them unless for highly complex configuration blocks with very deep hierarchy.

134
docs/source/arch_lang/spice_sim_setting.rst
View File

@ -1,134 +0,0 @@
Parameters for SPICE simulation settings
========================================
All the parameters that need to be defined in the HSPICE simulations are located under a child node called <parameters>, which is under its father node <spice_settings>.
The parameters are divided into three categories and can be defined in three XML nodes, <options>, <measure> and <stimulate>, respectively.
* The XML node <options>
.. code-block:: xml
<options sim_temp=”int” post=”string”captab=”string” fast=”string”/>
These properties define the options that will be printed in the top SPICE netlists.
* **sim_temp:** specify the temperature which will be defined in SPICE netlists. In the top SPICE netlists, it will show as .temp <int>.
* **post:** [on|off]. Specify if the simulation waveforms should be printed out after SPICE simulations. In all the SPICE netlists, it will show as .option POST when turned on.
.. note:: when the SPICE netlists are large or a long simulation duration is defined, the post option is recommended to be off. If not, huge disk space will be occupied by the waveform files.
* **captab:** [on|off]. Specify if the capacitances of all the nodes in the SPICE netlists will be printed out. In the top SPICE netlists, it will show as .option CAPTAB when turned on. When turned on, the SPICE simulation runtime may increase.
* The XML node <stimulate>
.. code-block:: xml
<stimulate>
<clock op_freq=”auto|float” sim_slack=”float” prog_freq=”float”>
<rise slew_time=”float” slew_type=”string”/>
<fall slew_time=”float” slew_type=”string”/>
</clock>
</stimulate>
Define stimulates for the clock signal.
* **op_freq:** either auto or a float number (unit:[Hz]) Specify the operation clock frequency that is used in SPICE simulations. This frequency is used in testbenches for operation phase simulation. Note that this is a mandatory option. Users have to specify either this frequency is automatically determined by assigning “auto” or give an exact number. If this clock frequency is specified, the sim_slack option is disregarded.
* **sim_slack:** add slack to the critical path delay in the SPICE simulation. For example, sim_slack=0.2 implies that the clock period in SPICE simulations is 1.2 of the critical path delay reported by VPR. **Only valid when option op_freq is not specified.**
* **prog_freq:** Specify the programming clock frequency that is used in SPICE simulations. This frequency is used in testbenches for programming phase simulation.
* **slew_type & slew_time:** define the slew of clock signals at the rising/falling edge. Property slew_type can be either absolute or fractional [abs|frac].
* The type of **absolute** implies that the slew time is the absolute value. For example, slew_time=20e-12, slew_type=abs means that the slew of a clock signal is 20ps.
* The type of **fractional** means that the slew time is related to the period (frequency) of the clock signal. For example, slew_time=0.05, slew_type=frac means that the slew of a clock signal takes 5% of the period of the clock.
:numref:`fig_meas_edge` depicts the definition of the slew and delays of signals and the parameters that can be supported by FPGA-SPICE.
.. code-block:: xml
<stimulate>
<input>
<rise slew_time=”float” slew_type=”string”/>
<fall slew_time=”float” slew_type=”string”/>
</input>
</stimulate>
Define the slew of input signals at the rising/falling edge.
* **slew_type & slew_time:** define the slew of all the input signals at the rising/falling edge. Property slew_type can be either absolute or fractional [abs|frac].
* The type of **absolute** implies that the slew time is the absolute value. For example, slew_time=20e-12, slew_type=abs means that the slew of a clock signal is 20ps.
* The type of **fractional** means that the slew time is related to the period (frequency) of the clock signal. For example, slew_time=0.05, slew_type=frac means that the slew of a clock signal takes 5% of the period of the clock.
.. note:: These slew settings are valid for all the input signals of the testbenches in different complexity levels.
.. _fig_meas_edge:
.. figure:: figures/meas_edge.png
:scale: 100%
:alt: map to buried traesure
Parameters in measuring the slew and delay of signals
* The XML node <measure>
.. code-block:: xml
<measure sim_num_clock_cycle=”int”accuracy=”float”accuracy_type=”string”/>
* **sim_num_clock_cycle:** can be either “auto” or an integer. By setting to “auto”, FPGA-SPICE automatically determines the number of clock cycles to simulate, which is related to the average of all the signal density in ACE2 results. When set to an integer, FPGA-SPICE will use the given number of clock cycles in the SPICE netlists.
* **accuracy_type:** [abs|frac]. Specify the type of transient step in SPICE simulation.
* When **abs** is selected, the accuracy should be the absolute value, such as 1e-12.
* When **frac** is selected, the accuracy is the number of simulation points in a clock cycle period, for example, 100.
* **accuracy:** specify the transient step in SPICE simulation. Typically, the smaller the step is, the higher the accuracy that can be reached while the long simulation runtime is. The recommended accuracy is between 0.1ps and 0.01ps, which generates good accuracy and runtime is not significantly long.
.. note:: Users can define the parameters in measuring the slew of signals, under a child node <slew> of the node <measure>.
.. code-block:: xml
<rise upper_thres_pct=”float” lower_thres_pct=”float”/>
Define the starting and ending point in measuring the slew of a rising edge of a signal.
* **upper_thres_pct:** the ending point in measuring the slew of a rising edge. It is expressed as a percentage of the maximum voltage of a signal. For example, the meaning of upper_thres_pct=0.95 is depicted in Figure 2.
* **lower_thres_pct:** the starting point in measuring the slew of a rising edge. It is expressed as a percentage of the maximum voltage of a signal. For example, the meaning of lower_thres_pct=0.05 is depicted in Figure 2.
.. code-block:: xml
<fall upper_thres_pct=”float” lower_thres_pct=”float”/>
* **upper_thres_pct:** the ending point in measuring the slew of a falling edge. It is expressed as a percentage of the maximum voltage of a signal. For example, the meaning of upper_thres_pct=0.05 is depicted in Figure 2.
* **lower_thres_pct:** the starting point in measuring the slew of a falling edge. It is expressed as a percentage of the maximum voltage of a signal. For example, the meaning of lower_thres_pct=0.95 is depicted in Figure 2.
.. note:: Users can define the parameters related to measurements of delays between signals, under a child node <delay> of the node <measure>.
.. code-block:: xml
<rise input_thres_pct=”float” output_thres_pct=”float”/>
Define the starting and ending point in measuring the delay between two signals when they are both at a rising edge.
* **input_thres_pct:** the starting point in measuring the delay of a rising edge. It is expressed as a percentage of the maximum voltage of a signal. For example, the meaning of input_thres_pct=0.5 is depicted in Figure 2.
* **output_thres_pct:** the ending point in measuring the delay of a rising edge. It is expressed as a percentage of the maximum voltage of a signal. For example, the meaning of output_thres_pct=0.5 is depicted in Figure 2.
.. code-block:: xml
<fall input_thres_pct=”float” output_thres_pct=”float”/>
Define the starting and ending point in measuring the delay between two signals when they are both at a falling edge.
* **input_thres_pct:** the starting point in measuring the delay of a falling edge. It is expressed as a percentage of the maximum voltage of a signal. For example, upper_thres_pct=0.5 is depicted in :numref:`fig_meas_edge`.
* **output_thres_pct:** the ending point in measuring the delay of a falling edge. It is expressed as a percentage of the maximum voltage of a signal. For example, lower_thres_pct=0. 5 is depicted in :numref:`fig_meas_edge`.

34
docs/source/arch_lang/tech_lib.rst
View File

@ -1,34 +0,0 @@
Technology library Declaration
==============================
.. code-block:: xml
<tech_lib lib_type=”string” transistor_type=”string” lib_path=”string” nominal_vdd=”float”/>
* **lib_type:** can be either industry or academia [industry|academia]. For the industry library, some transistor types are available, and the type of transistor should be declared in the property transistor_type.
* **transistor_type:** This XML property specify the transistors to be used in the industry library. For example, the type of transistors can be “TT”, “FF” etc.
* **lib_path:** specify the path of the library. For example: lib_path=/home/tech/45nm.pm.
* **nominal_vdd:** specify the working voltage for the technology. The voltage will be used as the supply voltage in all the SPICE netlist.
.. code-block:: xml
<transistors pn_ratio=”float” model_ref=”string”/>
* **pn_ratio:** specify the ratio between p-type transistors and n-type transistors. The ratio will be used when building circuit structures such as inverters, buffers, etc.
* **model_ref:** specify the reference of in calling a transistor model. In SPICE netlist, define a transistor follows the convention: <model_ref><trans_name> <ports> <model_name>. The reference depends on the technology and the type of library. For example, the PTM bulk model uses “M” as the reference while the PTM FinFET model uses “X” as the reference.
.. code-block:: xml
<nmos model_name=”string” chan_length=”float” min_width=”float”/>
<pmos model_name=”string” chan_length=”float” min_width=”float”/>
* **model_name:** specify the name of the p/n type transistor, which can be found in the manual of the technology provider.
* **chan_length:** specify the channel length of p/n type transistor.
* **min_width:** specify the minimum width of p/n type transistor. This parameter will be used in building inverter, buffer, etc. as a base number for transistor sizing.

4
docs/source/contact.rst
View File

@ -1,7 +1,7 @@
.. _contact:
Contact
=======
~~~~~~~
General questions:
@ -9,7 +9,7 @@ Prof. Pierre-Emmanuel Gaillardon
pierre-emmanuel.gaillardon@utah.edu
Technical Details about FPGA-SPICE/Verilog/Bitstream:
Technical Details about FPGA-SPICE/Verilog/Bitstream/SDC:
Dr. Xifan Tang

BIN
docs/source/figures/openfpga_flow.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 171 KiB

BIN
docs/source/figures/openfpga_motivation.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 273 KiB

14
docs/source/fpga_bitstream/command_line_usage.rst
View File

@ -1,14 +0,0 @@
Command-line Options for FPGA Bitstream Generator
=================================================
All the command line options of FPGA-Bitstream can be shown by calling the help menu of VPR. Here are all the FPGA-Verilog-related options that you can find:
FPGA-Verilog Supported Option::
--fpga_bitstream_generator
.. csv-table:: Commmand-line Option of FPGA-Bitstream
:header: "Command Options", "Description"
:widths: 15, 30
"--fpga_bitstream_generator", "Turn on the FPGA-Bitstream and output a .bitstream file containing FPGA configuration."

14
docs/source/fpga_bitstream/index.rst
View File

@ -1,14 +0,0 @@
FPGA-Bitstream
==============
.. _fpga_bitstream:
User Manual for FPGA Bitstream Generator
.. toctree::
:maxdepth: 2
command_line_usage
file_organization

16
docs/source/fpga_spice/index.rst
View File

@ -1,16 +0,0 @@
FPGA-SPICE: SPICE Auto-Generation
====================================
.. _fpga_spice:
User Manual for FPGA-SPICE support
.. toctree::
command_line_usage
file_organization
spice_simulation
customize_subckt

55
docs/source/fpga_verilog/command_line_usage.rst
View File

@ -1,55 +0,0 @@
Command-line Options for FPGA-Verilog Generator
=================================================
All the command line options of FPGA-Verilog can be shown by calling the help menu of VPR. Here are all the FPGA-Verilog-related options that you can find:
FPGA-Verilog Supported Options::
--fpga_verilog
--fpga_verilog_dir <directory_path_of_dumped_verilog_files>
--fpga_verilog_include_timing
--fpga_verilog_include_signal_init
--fpga_verilog_print_modelsim_autodeck <modelsim_ini_path>
--fpga_verilog_print_top_testbench
--fpga_verilog_print_autocheck_top_testbench <reference_verilog_file_path>
--fpga_verilog_print_formal_verification_top_netlist
--fpga_verilog_include_icarus_simulator
.. csv-table:: Commmand-line Options of FPGA-Verilog
:header: "Command Options", "Description"
:widths: 15, 30
"--fpga_verilog", "Turn on the FPGA-Verilog."
"--fpga_verilog_dir <dir_path>", "Specify the directory that all the Verilog files will be outputted to <dir_path> is the destination directory."
"--fpga_verilog_include_timing", "Includes the timings found in the XML file."
"--fpga_verilog_init_sim", "Initializes the simulation for ModelSim."
"--fpga_verilog_print_modelsim_autodeck", "Generates the scripts necessary to the ModelSim simulation."
"--fpga_verilog_modelsim_ini_path <string>", "Gives the path for the .ini necessary to ModelSim."
"--fpga_verilog_print_top_testbench", "Print the full-chip-level testbench for the FPGA. Determines the type of autodeck."
"--fpga_verilog_print_top_auto_testbench \
<path_to_the_verilog_benchmark>", "Prints the testbench associated with the given benchmark. Determines the type of autodeck."
"--fpga_verilog_dir <dir_path>", "Specify the directory where all the Verilog files will be outputted to. <dir_path> is the destination directory."
"--fpga_verilog_include_timing", "Includes the timings found in the XML architecture description file."
"--fpga_verilog_include_signal_init", "Set all nets to random value to be close of a real power-on case"
"--fpga_verilog_print_modelsim_autodeck <modelsim_ini_path>", "Generates the scripts necessary to the ModelSim simulation and specify the path to modelsim.ini file."
"--fpga_verilog_print_top_testbench", "Prints the full-chip-level testbench for the FPGA, which includes programming phase and operationg phase (random patterns)."
"--fpga_verilog_print_autocheck_top_testbench \
<reference_verilog_file_path>", "Prints a testbench stimulating the generated FPGA and the initial benchmark to compare stimuli responses, which includes programming phase and operationg phase (random patterns)"
"--fpga_verilog_print_formal_verification_top_netlist", "Prints a Verilog top file compliant with formal verification tools. With this top file the FPGA is initialy programmed. It also prints a testbench with random patterns, which can be manually or automatically check regarding previous options."
"--fpga_verilog_include_icarus_simulator", "Activates waveforms .vcd file generation and simulation timeout, which are required for Icarus Verilog simulator"
"--fpga_verilog_print_input_blif_testbench", "Generates a Verilog test-bench to use with input blif file"
"--fpga_verilog_print_report_timing_tcl", "Generates tcl commands to run STA analysis with TO COMPLETE TOOL"
"--fpga_verilog_report_timing_rpt_path <path_to_generate_reports>", "Specifies path where report timing are written"
"--fpga_verilog_print_sdc_pnr", "Generates SDC constraints to PNR"
"--fpga_verilog_print_sdc_analysis", "Generates SDC to run timing analysis in PNR tool"
"--fpga_verilog_print_user_defined_template", "Generates a template of hierarchy modules and their port mapping"
.. note:: The selected directory will contain the *Verilog top file* and three other folders. The folders are:
* **sub_module:** contains each module verilog file and is more detailed in the next part *Verilog Output File Format*.
* **routing:** contains the Verilog for the connection blocks and the switch boxes.
* **lb:** contains the grids Verilog files.

1300
docs/source/fpga_verilog/figures/Verification_step.pdf
View File

File diff suppressed because one or more lines are too long

20
docs/source/fpga_verilog/file_organization.rst
View File

@ -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."

12
docs/source/fpga_verilog/func_verify.rst
View File

@ -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.pdf
:scale: 100%
:alt: Functional Verification using ModelSim

18
docs/source/fpga_verilog/index.rst
View File

@ -1,18 +0,0 @@
FPGA-Verilog: Verilog Auto-Generation
-------------------------------------
.. _fpga_verilog:
User Manual for FPGA Verilog Generator
.. toctree::
:maxdepth: 2
command_line_usage
file_organization
func_verify
sc_flow

32
docs/source/index.rst
View File

@ -11,34 +11,18 @@ Welcome to OpenFPGA's documentation!
motivation
.. toctree::
:caption: Getting Started
eda_flow
run_fpga_flow
run_fpga_task
.. toctree::
:maxdepth: 2
:caption: Tools Guide
arch_lang/index
fpga_spice/index
fpga_verilog/index
fpga_bitstream/index
.. toctree::
:maxdepth: 2
:caption: User Guide
:caption: Tutorials
tutorials/index
.. toctree::
:maxdepth: 2
:caption: User Manual
manual/index
.. toctree::
:maxdepth: 2
:caption: Appendix
@ -52,8 +36,6 @@ For more information on the Yosys see yosys_doc_ or yosys_github_
For more information on the original FPGA architecture description language see xml_vtr_
Indices and tables
==================

108
docs/source/manual/arch_lang/addon_vpr_syntax.rst Normal file
View File

@ -0,0 +1,108 @@
.. _addon_vpr_syntax:
Additional Syntax to Original VPR XML
-------------------------------------
.. warning:: Note this is only applicable to VPR8!
Models, Complex blocks and Physical Tiles
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Each ``<pb_type>`` should contain a ``<mode>`` that describe the physical implementation of the ``<pb_type>``. Note that this is fully compatible to the VPR architecture XML syntax.
.. note:: ``<model>`` should include the models that describe the primitive ``<pb_type>`` in physical mode.
.. note:: Currently, OpenFPGA only supports 1 ``<equivalent_sites>`` to be defined under each ``<tile>``
.. option:: <mode packable="<bool">/>
OpenFPGA allows users to define it a mode is packable for VPR.
By default, the packable is set to ``true``.
This is mainly used for the mode that describes the physical implementation, which is typically not packable. Disable it in the packing and signficantly accelerate the packing runtime.
.. note:: Once a mode is set to unpackable, its child modes will be unpackable as well.
Layout
~~~~~~
``<layout>`` may include additioinal syntax to enable tileable routing resource graph generation
.. option:: tileable="<bool>"
Turn ``on``/``off`` tileable routing resource graph generator.
Tileable routing architecture can minimize the number of unique modules in FPGA fabric to be physically implemented.
Technical details can be found in :cite:`XTang_FPT_2019`.
.. note:: Strongly recommend to enable the tileable routing architecture when you want to PnR large FPGA fabrics, which can effectively reduce the runtime.
.. option:: through_channel="<bool>"
Allow routing channels to pass through multi-width and multi-height programable blocks. This is mainly used in heterogeneous FPGAs to increase routability, as illustrated in :numref:`fig_thru_channel`.
By default, it is ``off``.
.. _fig_thru_channel:
.. figure:: ./figures/thru_channel.png
:scale: 80%
:alt: Impact of through channel
Impact on routing architecture when through channel in multi-width and multi-height programmable blocks: (a) disabled; (b) enabled.
.. warning:: Do NOT enable ``through_channel`` if you are not using the tileable routing resource graph generator!
.. warning:: Currently ``through_channel`` supports only a fixed routing channel width!
A quick example to show tileable routing is enabled and through channels are disabled:
.. code-block:: xml
<layout tileable="true" through_channel="false">
</layout>
Switch Block
~~~~~~~~~~~~
``<switch_block>`` may include addition syntax to enable different connectivity for pass tracks
.. option:: sub_type="<string>"
Connecting type for pass tracks in each switch block
The supported connecting patterns are ``subset``, ``universal`` and ``wilton``, being the same as VPR capability
If not specified, the pass tracks will the same connecting patterns as start/end tracks, which are defined in ``type``
.. option:: sub_Fs="<int>"
Connectivity parameter for pass tracks in each switch block. Must be a multiple of 3.
If not specified, the pass tracks will the same connectivity as start/end tracks, which are defined in ``fs``
A quick example which defines a switch block
- Starting/ending routing tracks are connected in the ``wilton`` pattern
- Each starting/ending routing track can drive 3 other starting/ending routing tracks
- Passing routing tracks are connected in the ``subset`` pattern
- Each passing routing track can drive 6 other starting/ending routing tracks
.. code-block:: xml
<device>
<switch_block type="wilton" fs="3" sub_type="subset" sub_fs="6"/>
</device>
Routing Segments
~~~~~~~~~~~~~~~~
OpenFPGA suggests users to give explicit names for each routing segement in ``<segmentlist>``
This is used to link ``circuit_model`` to routing segments.
A quick example which defines a length-4 uni-directional routing segment called ``L4`` :
.. code-block:: xml
<segmentlist>
<segment name="L4" freq="1" length="4" type="undir"/>
</segmentlist>
.. note:: Currently, OpenFPGA only supports uni-directional routing architectures

147
docs/source/manual/arch_lang/annotate_vpr_arch.rst Normal file
View File

@ -0,0 +1,147 @@
.. _annotate_vpr_arch:
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.
Switch Blocks
~~~~~~~~~~~~~
Original VPR architecture description contains an XML node called switchlist under which all the multiplexers of switch blocks are described.
To link a defined circuit model to a multiplexer in the switch blocks, a new XML property circuit_model_name should be added to the descriptions.
Here is an example:
.. code-block:: xml
<switch_block>
<switch type="mux" name="<string>" circuit_model_name="<string>"/>
</switch_block>
- ``circuit_model_name="<string>"`` should match a circuit model whose type is ``mux`` defined in :ref:`circuit_library`.
Connection Blocks
~~~~~~~~~~~~~~~~~
To link the defined circuit model of the multiplexer to the Connection Blocks, a ``circuit_model_name`` should be annotated to the definition of Connection Blocks switches.
Here is the example:
.. code-block:: xml
<connection_block>
<switch type="ipin_cblock" name="<string>" circuit_model_name="<string>"/>
</connection_block>
- ``circuit_model_name="<string>"`` should match a circuit model whose type is ``mux`` defined in :ref:`circuit_library`.
Channel Wire Segments
~~~~~~~~~~~~~~~~~~~~~
Similar to the Switch Boxes and Connection Blocks, the channel wire segments in the original architecture descriptions can be adapted to provide a link to the defined circuit model.
.. code-block:: xml
<segmentlist>
<segment name="<string>" circuit_model_name="<string>"/>
</segmentlist>
- ``circuit_model_name="<string>"`` should match a circuit model whose type is ``chan_wire`` defined in :ref:`circuit_library`.
Primitive Blocks inside Multi-mode Configurable Logic Blocks
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The architecture description employs a hierarchy of ``pb_types`` to depict the sub-modules and complex interconnections inside logic blocks. Each leaf node and interconnection in the pb_type hierarchy should be linked to a circuit model.
Each primitive block, i.e., the leaf ``pb_types``, should be linked to a valid circuit model, using the XML syntax ``circuit_model_name``.
The ``circuit_model_name`` should match the given name of a ``circuit_model`` defined by users.
.. 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" physical_mode_name="physical"/>
<pb_type name="clb.fle[physical].fabric.frac_logic.frac_lut6" circuit_model_name="frac_lut6" mode_bits="0"/>
<pb_type name="clb.fle[physical].fabric.ff" circuit_model_name="static_dff"/>
<!-- Binding operating pb_type to physical pb_type -->
<pb_type name="clb.fle[n2_lut5].lut5inter.ble5.lut5" physical_pb_type_name="clb.fle[physical].fabric.frac_logic.frac_lut6" mode_bits="1" physical_pb_type_index_factor="0.5">
<!-- Binding the lut5 to the first 5 inputs of fracturable lut6 -->
<port name="in" physical_mode_port="in[0:4]"/>
<port name="out" physical_mode_port="lut5_out" physical_mode_pin_rotate_offset="1"/>
</pb_type>
<pb_type name="clb.fle[n2_lut5].lut5inter.ble5.ff" physical_pb_type_name="clb.fle[physical].fabric.ff"/>
<pb_type name="clb.fle[n1_lut6].ble6.lut6" physical_pb_type_name="clb.fle[physical].fabric.frac_logic.frac_lut6" mode_bits="0">
<!-- Binding the lut6 to the first 6 inputs of fracturable lut6 -->
<port name="in" physical_mode_port="in[0:5]"/>
<port name="out" physical_mode_port="lut6_out"/>
</pb_type>
<pb_type name="clb.fle[n1_lut6].ble6.ff" physical_pb_type_name="clb.fle[physical].fabric.ff" physical_pb_type_index_factor="2" physical_pb_type_index_offset="0"/>
<!-- End physical pb_type binding in complex block IO -->
</pb_type_annotations>
.. option:: <pb_type name="<string>" physical_mode_name="<string>">
Specify a physical mode for multi-mode ``pb_type`` defined in VPR architecture.
.. note:: This should be applied to non-primitive ``pb_type``, i.e., ``pb_type`` have child ``pb_type``.
- ``name="<string>"`` specifiy the full name of a ``pb_type`` in the hierarchy of VPR architecture.
- ``physical_mode_name="<string>"`` Specify the name of the mode that describes the physical implementation of the configurable block. This is critical in modeling actual circuit designs and architecture of an FPGA. Typically, only one ``physical_mode`` should be specified for each multi-mode ``pb_type``.
.. note:: OpenFPGA will infer the physical mode for a single-mode ``pb_type`` defined in VPR architecture
.. option:: <pb_type name="<string>" physical_pb_type_name="<string>" circuit_model_name="<string>"
mode_bits="<int>" physical_pb_type_index_factor="<float>" physical_pb_type_index_offset="<int>">
Specify the physical implementation for a primitive ``pb_type`` in VPR architecture
.. note:: This should be applied to primitive ``pb_type``, i.e., ``pb_type`` have no children.
- ``name="<string>"`` specifiy the full name of a ``pb_type`` in the hierarchy of VPR architecture.
- ``physical_pb_type_name=<string>`` creates the link on ``pb_type`` between operating and physical modes. This syntax is mandatory for every primitive ``pb_type`` in an operating mode ``pb_type``. It should be a valid name of primitive ``pb_type`` in physical mode.
- ``circuit_model_name="<string>"`` Specify a circuit model to implement a ``pb_type`` in VPR architecture. The ``circuit_model_name`` is mandatory for every primitive``pb_type`` in a physical_mode ``pb_type``.
- ``mode_bits="<int>"`` Specify the configuration bits for the ``circuit_model`` when operating at an operating mode. The length of ``mode_bits`` should match the ``port`` size defined in ``circuit_model``. The ``mode_bits`` should be derived from circuit designs while users are responsible for its correctness. FPGA-Bitstreamm will add the ``mode_bits`` during bitstream generation.
- ``physical_pb_type_index_factor="<float>"`` aims to align the indices for ``pb_type`` between operating and physical modes, especially when an operating mode contains multiple ``pb_type`` (``num_pb``>1) that are linked to the same physical ``pb_type``. When ``physical_pb_type_name`` is larger than 1, the index of ``pb_type`` will be multipled by the given factor.
- ``physical_pb_type_index_offset=<int>`` aims to align the indices for ``pb_type`` between operating and physical modes, especially when an operating mode contains multiple ``pb_type`` (``num_pb``>1) that are linked to the same physical ``pb_type``. When ``physical_pb_type_name`` is larger than 1, the index of ``pb_type`` will be shifted by the given factor.
.. option:: <interconnect name="<string>" circuit_model_name="<string>">
- ``name="<string>"`` specifiy the name of a ``interconnect`` in VPR architecture. Different from ``pb_type``, hierarchical name is not required here.
- ``circuit_model_name="<string>"`` For the interconnection type direct, the type of the linked circuit model should be wire. For multiplexers, the type of linked circuit model should be ``mux``. For complete, the type of the linked circuit model can be either ``mux`` or ``wire``, depending on the case.
.. option:: <port name="<string>" physical_mode_port="<string>" physical_mode_pin_rotate_offset="<int>"/>
Link a port of an operating ``pb_type`` to a port of a physical ``pb_type``
- ``name="<string>"`` specifiy the name of a ``port`` in VPR architecture. Different from ``pb_type``, hierarchical name is not required here.
- ``physical_mode_pin="<string>" creates the link of ``port`` of ``pb_type`` between operating and physical modes. This syntax is mandatory for every primitive ``pb_type`` in an operating mode ``pb_type``. It should be a valid ``port`` name of leaf ``pb_type`` in physical mode and the port size should also match.
- ``physical_mode_pin_rotate_offset="<int>"`` aims to align the pin indices for ``port`` of ``pb_type`` between operating and physical modes, especially when an operating mode contains multiple ``pb_type`` (``num_pb``>1) that are linked to the same physical ``pb_type``. When ``physical_mode_pin_rotate_offset`` is larger than zero, the pin index of ``pb_type`` (whose index is large than 1) will be shifted by the given offset.
.. note::
It is highly recommended that only one physical mode is defined for a multi-mode configurable block. Try not to use nested physical mode definition. This will ease the debugging and lead to clean XML description.
.. note::
Be careful in using ``physical_pb_type_index_factor``, ``physical_pb_type_index_offset`` and ``physical_mode_pin_rotate_offset``! Try to avoid using them unless for highly complex configuration blocks with very deep hierarchy.

412
docs/source/manual/arch_lang/circuit_library.rst Normal file
View File

@ -0,0 +1,412 @@
.. _circuit_library:
Circuit Library
---------------
For OpenFPGA using VPR7
~~~~~~~~~~~~~~~~~~~~~~~
To support FPGA Verilog/SPICE, Verily and Bitstream Generator, physical modules containing gate-level and transistor-level features are required for FPGA primitive blocks.
The physical modules are defined in XML syntax, similar to the original VPR FPGA architecture description language.
For each module that appears in the FPGA architecture, a circuit model should be defined. In the definition of a circuit model, the user can specify if the Verilog/SPICE netlist of the module is either auto-generated or user-defined.
Circuit Model Attributes
^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: xml
<module_circuit_models>
<circuit_model type="string" name="string" prefix="string" is_default="int"
circuit_netlist="string" verilog_netlist="string" dump_structural_verilog="string">
<transistor-level circuit_design_features="developped_further" />
</circuit_model>
</module_circuit_models>
* **module_circuit_models**: the father node for all the circuit models. All the circuit models should be defined under this XML node.
* **circuit_model**: the child node defining transistor-level modeling parameters.
* **type**: can be [ ``inv_buf`` | ``pass_gate`` | ``gate`` | ``mux`` | ``wire`` | ``chan_wire`` | ``sram`` | ``lut`` | ``ff`` | ``scff`` | ``hard_logic`` | ``iopad`` ]. Specify the type of circuit model. The provided types cover all the modules in FPGAs. For the circuit models in the type of mux/wire/chan_wire/lut, FPGA-Verilog/SPICE can auto-generate Verilog/SPICE netlists. For the rest, FPGA-Verilog/SPICE requires a user-defined Verilog/SPICE netlist.
* **name**: define the name of this circuit model. The name should be unique and will be used to create the sub-circuit of the circuit model in Verilog/SPICE netlists. Note that for a customized Verilog/SPICE netlist, the name defined here should be the name of the top-level sub-circuit in the customized Verilog/SPICE netlist. FPGA-Verilog/SPICE will check if the given name is conflicted with any reserved words.
* **prefix**: specify the name of the circuit_model to shown in the auto-generated Verilog/SPICE netlists. The prefix can be the same as the name defined above. And again, the prefix should be unique.
* **is_default**: can be [``1`` | ``0``], corresponding to [``true`` | ``false``] respectively. Specify this circuit model is the default one for some modules, such as multiplexers. If a module is not linked to any circuit model by users, FPGA-Verilog/SPICE will find the default circuit model defined in the same type and link. For a circuit model type, only one circuit model can be set as default.
* **circuit_netlist**: specify the path and file name of a customized Verilog/SPICE netlist. For some modules such as SRAMs, FFs, inpads, and outpads, FPGA-Verilog/SPICE does not support auto-generation of the transistor-level sub-circuits because their circuit design is highly dependent on the technology nodes. These circuit designs should be specified by users. For the other modules that can be auto-generated by FPGA-Verilog/SPICE, the user can also define a custom netlist. Multiplexers cannot be user-defined.
* **verilog_netlist**: specify the path and file name of a customized Verilog netlist. For some modules such as SRAMs, FFs, inpad and outpads, FPGA-Verilog/SPICE does not support auto-generation of the transistor-level sub-circuits because their circuit design is highly dependent on the technology nodes. These circuit designs should be specified by users. For the other modules that can be auto-generated by FPGA-Verilog/SPICE, the user can also define a custom netlist. Multiplexers cannot be user-defined.
* **dump_structural_verilog**: when the value of this keyword is set to be true, Verilog generator will output gate-level netlists of this module, instead of behavior-level. Gate-level netlists bring more opportunities in layout-level optimization while behavior-level is more suitable for high-speed formal verification and easier in debugging with HDL simulators.
.. note:: If netlist is not specified, FPGA-Verilog/SPICE auto-generates the Verilog/SPICE netlists for multiplexers, wires, and LUTs.
.. note:: The user-defined netlists, such as LUTs, the decoding methodology should comply with the auto-generated LUTs (See Section 4.5)
.. note:: Under the XML node circuit_model, the features of transistor-level designs can be defined. In the following table, we show the common features supported for all the modules. Then, we will introduce unique features supported only for some circuit models types.
Design Technology-related Attributes
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: xml
<circuit_model type="string" name="string" prefix="string" is_default="int" netlist="string"
dump_structural_verilog="string">
<design_technology type="string"/>
<input_buffer exist="string" circuit_model_name="string"/>
<output_buffer exist="string" circuit_model_name="string"/>
<pass_gate_logic type="string" circuit_model_name="string"/>
<port type="string" prefix="string" lib_name="string" size="int" default_val="int" circuit_model_name="string"
mode_select="boolean" is_global="boolean" is_set="boolean" is_reset="boolean"
is_config_enable="boolean"/>
</circuit_model>
* design_technology :
* **type:** [cmos|rram]. Specify the type of design technology of the circuit_model.
.. note:: Currently, the RRAM-based designs are only supported for multiplexers.
Circuit Port Attributes
^^^^^^^^^^^^^^^^^^^^^^^
* input_buffer and output_buffer:
* **exist:** [on|off]. Define the existence of the input_buffer or output_buffer. Note that the existence is valid for all the inputs and outputs. Note that if users want only part of the inputs (or outputs) to be buffered, this is not supported here. A solution can be building a user-defined Verilog/SPICE netlist.
* **circuit_model_name:** Specify the name of circuit model which is used to implement input/output buffer, the type of specified circuit model should be inv_buf.
* pass_gate_logic: defined the parameters in pass-gates, which are used in building multiplexers and LUTs.
* **circuit_model_name:** Specify the name of the circuit model which is used to implement transmission gate, the type of specified circuit model should be pass_gate.
* port: define the port list of a circuit model.
* **type:** can be [input|output|sram|clock]. For programmable modules, such as multiplexers and LUTs, SRAM ports should be defined. For registers, such as FFs and memory banks, clock ports should be defined.
* **prefix:** the name of the port to appear in the autogenerated netlists. Each port will be shown as ``<prefix>[i]`` in Verilog/SPICE netlists.
* **lib_name:** the name of the port defined in standard cells or customized cells. If not specified, this attribute will be the same as ``prefix``.
* **size:** bandwidth of the port.
* **default_val:** default logic value of a port, which is used as the initial logic value of this port in testbench generation. Can be either 0 or 1. We assume each pin of this port has the same default value.
* **circuit_model_name:** only valid when the type of port is sram. Specify the name of the circuit model which is connected to this port.
* **mode_select:** can be either ``true`` or ``false``. Specify if this port controls the mode switching in a configurable logic block. Only valid when the type of this port is sram. (A configurable logic block can operate in different modes, which is controlled by SRAM bits.)
* **is_global:** can be either ``true`` or ``false``. Specify if this port is a global port, which will be routed globally. Note that when multiple global ports are defined with the same name, these global ports will be short-wired together.
* **is_set:** can be either ``true`` or ``false``. Specify if this port controls a set signal. Only valid when ``is_global`` is true. All the set ports are connected to global set voltage stimuli in testbenches.
* **is_reset:** can be either ``true`` or ``false``. Specify if this port controls a reset signal. Only valid when ``is_global`` is true. All the reset ports are connected to a global reset voltage stimuli in testbenches.
* **is_config_enable:** can be either ``true`` or ``false``. Only valid when ``is_global`` is true. Specify if this port controls a configuration-enable signal. This port is only enabled during FPGA configuration, and always disabled during FPGA operation. All the ``config_enable`` ports are connected to global configuration-enable voltage stimuli in testbenches.
.. note:: Different types of ``circuit_model`` have different XML syntax, with which users can highly customize their circuit topologies. See refer to examples of ``circuit_model`` for more details.
.. note:: Note that we have a list of reserved port names, which indicate the usage of these ports when building FPGA fabrics. Please do not use ``mem_out``, ``mem_inv``, ``bl``, ``wl``, ``blb``, ``wlb``, ``ccff_head`` and ``ccff_tail``.
For OpenFPGA using VPR8
~~~~~~~~~~~~~~~~~~~~~~~
Circuit design is a dominant factor in Power, Performance, Area (P.P.A.) of FPGA fabrics.
Upon practical applications, the hardware engineers may select various circuits to implement their FPGA fabrics.
For instance, a ultra-low-power FPGA may be built with ulta-low-power circuit cells while a high-performance FPGA may use absolutely different circuit cells.
OpenFPGA provide enriched XML syntax for users to highly customize their circuits in FPGA fabric.
In the XML file, users can define a library of circuits, each of which corresponds to a primitive module required in the FPGA architecture.
Users can specify if the Verilog/SPICE netlist of the module is either auto-generated by OpenFPGA or provided by themselves.
As such, OpenFPGA can support any circuit design, leading to high flexibility in building FPGA fabrics.
In principle, a circuit library consists of a number of ``<circuit_model>``, each of which correspond to a circuit design.
OpenFPGA supports a wide range of circuit designs.
The ``<circuit_model>`` could be as small as a cornerstone cell, such as inverter, buffer *etc*., or as large as a hardware IP, such as Block RAM.
.. code-block:: xml
<circuit_library>
<circuit_model type="<string>" name="<string>">
<!-- Detailed circuit-level design parameters -->
</circuit_model>
<!-- More circuit models -->
</circuit_library>
Currently, OpenFPGA supports the following categories of circuits:
- inverters/buffers
- pass-gate logic, including transmission gates and pass transistors
- standard cell logic gates, including AND, OR and MUX2
- metal wires
- multiplexers
- flip-flops
- Look-Up Tables, including single-output and multi-output fracturable LUTs
- Statis Random Access Memory (SRAM)
- scan-chain flip-flops
- I/O pad
- hardware IPs
Circuit Model
^^^^^^^^^^^^^
As OpenFPGA supports many types of circuit models and their circuit-level implementation could be really different, each type of circuit model has special syntax to customize their designs.
However, most circuit models share the common generality in XML language.
Here, we focus these common syntax and we will detail special syntax in :ref:`circuit_model_examples`
.. code-block:: xml
<circuit_model type="<string>" name="<string>" prefix="<string>" is_default="<bool>" spice_netlist="<string>" verilog_netlist="<string>" dump_structural_verilog="<bool>">
<design_technology type="<string>"/>
<input_buffer exist="<string>" circuit_model_name="<string>"/>
<output_buffer exist="<string>" circuit_model_name="<string>"/>
<pass_gate_logic type="<string>" circuit_model_name="<string>"/>
<port type="<string>" prefix="<string>" lib_name="<string>" size="<int>" default_val="<int>" circuit_model_name="<string>" mode_select="<bool>" is_global="<bool>" is_set="<bool>" is_reset="<bool>" is_config_enable="<bool>"/>
<!-- more ports -->
</circuit_model>
.. option:: <circuit_model type="<string>" name="<string>" prefix="<string>" is_default="<bool>"
spice_netlist="<string>" verilog_netlist="<string>" dump_structural_verilog="<bool>">
Specify the general attributes for a circuit model
- ``type="inv_buf|pass_gate|gate|mux|wire|chan_wire|sram|lut|ff|ccff|hard_logic|iopad"`` Specify the type of circuit model. For the circuit models in the type of mux/wire/chan_wire/lut, FPGA-Verilog/SPICE can auto-generate Verilog/SPICE netlists. For the rest, FPGA-Verilog/SPICE requires a user-defined Verilog/SPICE netlist.
- ``name="<string>"`` Specify the name of this circuit model. The name should be unique and will be used to create the Verilog/SPICE module in Verilog/SPICE netlists. Note that for a customized Verilog/SPICE netlist, the name defined here MUST be the name in the customized Verilog/SPICE netlist. FPGA-Verilog/SPICE will check if the given name is conflicted with any reserved words.
- ``prefix="<string>"`` Specify the name of the ``<circuit_model>`` to shown in the auto-generated Verilog/SPICE netlists. The prefix can be the same as the name defined above. And again, the prefix should be unique
- ``is_default="true|false"`` Specify this circuit model is the default one for those in the same types. If a primitive module in VPR architecture is not linked to any circuit model by users, FPGA-Verilog/SPICE will find the default circuit model defined in the same type.
- ``spice_netlist="<string>"`` Specify the path and file name of a customized SPICE netlist. For some modules such as SRAMs, FFs, I/O pads, FPGA-SPICE does not support auto-generation of the transistor-level sub-circuits because their circuit design is highly dependent on the technology nodes. These circuit designs should be specified by users. For the other modules that can be auto-generated by FPGA-SPICE, the user can also define a custom netlist.
- ``verilog_netlist="<string>"`` Specify the path and file name of a customized Verilog netlist. For some modules such as SRAMs, FFs, I/O pads, FPGA-Verilog does not support auto-generation of the transistor-level sub-circuits because their circuit design is highly dependent on the technology nodes. These circuit designs should be specified by users. For the other modules that can be auto-generated by FPGA-Verilog, the user can also define a custom netlist.
- ``dump_structural_verilog="true|false"`` When the value of this keyword is set to be true, Verilog generator will output gate-level netlists of this module, instead of behavior-level. Gate-level netlists bring more opportunities in layout-level optimization while behavior-level is more suitable for high-speed formal verification and easier in debugging with HDL simulators.
.. warning:: ``prefix`` may be deprecated soon
.. note:: Multiplexers cannot be user-defined.
.. note:: For a circuit model type, only one circuit model can be set as default.
.. note:: If ``<spice_netlist>`` or ``<verilog_netlist>`` are not specified, FPGA-Verilog/SPICE auto-generates the Verilog/SPICE netlists for multiplexers, wires, and LUTs.
.. note:: The user-defined netlists, such as LUTs, the decoding methodology should comply with the auto-generated LUTs!!!
Design Technology
^^^^^^^^^^^^^^^^^
.. option:: <design_technology type="string"/>
Specify the design technology applied to a ``<circuit_model>``
- ``type="cmos|rram"`` Specify the type of design technology of the ``<circuit_model>``. Currently, OpenFPGA supports CMOS and RRAM technology for circuit models.
CMOS technology can be applied to any types of ``<circuit_model>``, while RRAM technology is only applicable to multiplexers and SRAMs
.. note:: Each ``<circuit_model>`` may have different technologies
Input and Output Buffers
^^^^^^^^^^^^^^^^^^^^^^^^
.. option:: <input_buffer exist="<string>" circuit_model_name="<string>"/>
- ``exist="true|false"`` Define the existence of the input buffer. Note that the existence is valid for all the inputs.
- ``circuit_model_name="<string>"`` Specify the name of circuit model which is used to implement input buffer, the type of specified circuit model should be ``inv_buf``.
.. option:: <output_buffer exist="<string>" circuit_model_name="<string>"/>
- ``exist="true|false"`` Define the existence of the output buffer. Note that the existence is valid for all the outputs. Note that if users want only part of the inputs (or outputs) to be buffered, this is not supported here. A solution can be building a user-defined Verilog/SPICE netlist.
- ``circuit_model_name="<string>"`` Specify the name of circuit model which is used to implement the output buffer, the type of specified circuit model should be ``inv_buf``.
.. note:: If users want only part of the inputs (or outputs) to be buffered, this is not supported here. A solution can be building a user-defined Verilog/SPICE netlist.
Pass Gate Logic
^^^^^^^^^^^^^^^
.. option:: <pass_gate_logic circuit_model_name="<string>"/>
- ``circuit_model_name="<string>"`` Specify the name of the circuit model which is used to implement pass-gate logic, the type of specified circuit model should be ``pass_gate``.
.. note:: pass-gate logic are used in building multiplexers and LUTs.
Circuit Port
^^^^^^^^^^^^
A circuit model may consist of a number of ports. The port list is mandatory in any ``circuit_model`` and must be consistent to any user-defined netlists.
.. option:: <port type="<string>" prefix="<string>" lib_name="<string>" size="<int>"
default_val="<int>" circuit_model_name="<string>" mode_select="<bool>"
is_global="<bool>" is_set="<bool>" is_reset="<bool>" is_config_enable="<bool>"/>
Define the attributes for a port of a circuit model.
- ``type="input|output|sram|clock"`` Specify the type of the port, i.e., the directionality and usage. For programmable modules, such as multiplexers and LUTs, SRAM ports MUST be defined. For registers, such as FFs and memory banks, clock ports MUST be defined.
.. note:: ``sram`` and ``clock`` ports are considered as inputs in terms of directionality
- ``prefix="<string>"`` the name of the port to appear in the autogenerated netlists. Each port will be shown as ``<prefix>[i]`` in Verilog/SPICE netlists.
.. note:: if the circuit model is binded to a ``pb_type`` in VPR architecture, ``prefix`` must match the port name defined in ``pb_type``
- ``lib_name="<string>"`` the name of the port defined in standard cells or customized cells. If not specified, this attribute will be the same as ``prefix``.
.. note:: if the circuit model comes from a standard cell library, using ``lib_name`` is recommended. This is because
- the port names defined in ``pb_type`` are very diffrerent from the standard cells
- the port sequence is very different
- ``size="<int>"`` bandwidth of the port. MUST be larger than zero.
- ``default_val="<int>"`` Specify default logic value for a port, which is used as the initial logic value of this port in testbench generation. Can be either 0 or 1. We assume each pin of this port has the same default value.
- ``circuit_model_name="<string>"`` Specify the name of the circuit model which is connected to this port.
.. note:: ``circuit_model_name`` is only valid when the type of this port is ``sram``.
- ``io="true|false"`` Specify if this port should be treated as an I/O port of an FPGA fabric. When this is enabled, this port of each circuit model instanciated in FPGA will be added as an I/O of an FPGA.
.. note:: global ``output`` ports must be ``io`` ports
- ``mode_select="true|false"`` Specify if this port controls the mode switching in a configurable logic block. This is due to that a configurable logic block can operate in different modes, which is controlled by SRAM bits.
.. note:: ``mode_select`` is only valid when the type of this port is ``sram``.
- ``is_global="true|false"`` can be either ``true`` or ``false``. Specify if this port is a global port, which will be routed globally.
.. note:: For input ports, when multiple global input ports are defined with the same name, by default, these global ports will be short-wired together. When ``io`` is turned on for this port, these global ports will be independent in the FPGA fabric.
.. note:: For output ports, the global ports will be independent in the FPGA fabric
- ``is_set="true|false"`` Specify if this port controls a set signal. All the set ports are connected to global set voltage stimuli in testbenches.
- ``is_reset="true|false"`` Specify if this port controls a reset signal. All the reset ports are connected to a global reset voltage stimuli in testbenches.
- ``is_config_enable="true|false"`` Specify if this port controls a configuration-enable signal. Only valid when ``is_global`` is ``true``. This port is only enabled during FPGA configuration, and always disabled during FPGA operation. All the ``config_enable`` ports are connected to global configuration-enable voltage stimuli in testbenches.
.. note:: ``is_set``, ``is_reset`` and ``is_config_enable`` are only valid when ``is_global`` is ``true``.
.. note:: Different types of ``circuit_model`` have different XML syntax, with which users can highly customize their circuit topologies. See refer to examples of :ref:``circuit_model_example`` for more details.
.. note:: Note that we have a list of reserved port names, which indicate the usage of these ports when building FPGA fabrics. Please do not use ``mem_out``, ``mem_inv``, ``bl``, ``wl``, ``blb``, ``wlb``, ``ccff_head`` and ``ccff_tail``.
FPGA I/O Port
^^^^^^^^^^^^^
The ``circuit_model`` support not only highly customizable circuit-level modeling but also flexible I/O connection in the FPGA fabric.
Typically, circuit ports appear in the primitive modules of a FPGA fabric.
However, it is also very common that some circuit ports should be I/O of a FPGA fabric.
Using syntax ``is_global`` and ``is_io``, users can freely define how these ports are connected as FPGA I/Os.
In principle, when ``is_global`` is set ``true``, the port will appear as an FPGA I/O.
The syntax ``is_io`` is applicable when ``is_global`` is ``true``.
When ``is_io`` is ``true``, the port from different instances will be treated as independent I/Os.
When ``is_io`` is ``false``, the port from different instances will be treated as the same I/Os, which are short-wired.
To beef up, the following examples will explain how to use ``is_global`` and ``is_io`` to achieve different types of connections to FPGA I/Os.
.. option:: Global short-wired inputs
.. code-block:: xml
<port type="input" is_global="true" is_io="false"/>
The global inputs are short wired across different instances.
These inputs are widely seen in FPGAs, such as clock ports, which are shared between sequential elements.
:numref:`fig_global_input_ports` shows an example on how the global inputs are wired inside FPGA fabric.
.. _fig_global_input_ports:
.. figure:: ./figures/global_input_ports.png
:scale: 100%
:alt: classical inverter 1x symbol
Short-wired global inputs as an FPGA I/O
.. option:: Global short-wired inouts
.. code-block:: xml
<port type="inout" is_global="true" is_io="false"/>
The global inouts are short wired across different instances.
:numref:`fig_global_inout_ports` shows an example on how the global inouts are wired inside FPGA fabric.
.. _fig_global_inout_ports:
.. figure:: ./figures/global_inout_ports.png
:scale: 100%
:alt: classical inverter 1x symbol
Short-wired global inouts as an FPGA I/O
.. option:: General-purpose inputs
.. code-block:: xml
<port type="input" is_global="true" is_io="true"/>
The general-purpose inputs are independent wired from different instances to separated FPGA I/Os.
For example, power-gating signals can be applied to each tile of a FPGA.
:numref:`fig_gpin_ports` shows an example on how the general-purpose inputs are wired inside FPGA fabric.
.. _fig_gpin_ports:
.. figure:: ./figures/gpin_ports.png
:scale: 100%
:alt: classical inverter 1x symbol
General-purpose inputs as separated FPGA I/Os
.. option:: General-purpose I/O
.. code-block:: xml
<port type="inout" is_global="true" is_io="true"/>
The general-purpose I/O are independent wired from different instances to separated FPGA I/Os.
In practice, inout of GPIO cell is typically wired like this.
:numref:`fig_gpin_ports` shows an example on how the general-purpose inouts are wired inside FPGA fabric.
.. _fig_gpio_ports:
.. figure:: ./figures/gpio_ports.png
:scale: 100%
:alt: classical inverter 1x symbol
General-purpose inouts as separated FPGA I/Os
.. option:: General-purpose outputs
.. code-block:: xml
<port type="output" is_global="true" is_io="true"/>
The general-purpose outputs are independent wired from different instances to separated FPGA outputs.
In practice, these outputs are typically spypads to probe internal signals of a FPGA.
:numref:`fig_gpout_ports` shows an example on how the general-purpose outputs are wired inside FPGA fabric.
.. _fig_gpout_ports:
.. figure:: ./figures/gpout_ports.png
:scale: 100%
:alt: classical inverter 1x symbol
General-purpose outputs as separated FPGA I/Os
.. warning:: The general-purpose inputs/inouts/outputs are not applicable to routing multiplexer outputs

892
docs/source/manual/arch_lang/circuit_model_examples.rst Normal file
View File

@ -0,0 +1,892 @@
.. _circuit_model_examples:
Circuit model examples
----------------------
As circuit model in different types have various special syntax.
Here, we will provide detailed examples on each type of ``circuit_model``.
These examples may be considered as template for users to craft their own ``circuit_model``.
Inverters and Buffers
~~~~~~~~~~~~~~~~~~~~~
Template
````````
.. code-block:: xml
<circuit_model type="inv_buf" name="<string>" prefix="<string>" netlist="<string>" is_default="<int>">
<design_technology type="cmos" topology="<string>" size="<int>" num_level="<int>" f_per_stage="<float>"/>
<port type="input" prefix="<string>" size="<int>"/>
<port type="output" prefix="<string>" size="<int>"/>
</circuit_model>
.. option:: <design_technology type="cmos" topology="<string>" size="<int>" num_level="<int>" f_per_stage="<float>"/>
- ``topology="inverter|buffer"`` Specify the type of this component, can be either an inverter or a buffer.
- ``size="<int>"`` Specify the driving strength of inverter/buffer. For a buffer, the size is the driving strength of the inverter at the second level. Note that we consider a two-level structure for a buffer here.
- ``num_level="<int>"`` Define the number of levels of a tapered inverter/buffer. This is required when users need an inverter or a buffer consisting of >2 stages
- ``f_per_stage="<float>"`` Define the ratio of driving strength between the levels of a tapered inverter/buffer. Default value is 4.
Inverter 1x Example
```````````````````
:numref:`fig_inv1` is the inverter symbol depicted in this example.
.. _fig_inv1:
.. figure:: ./figures/Inverter_1.png
:scale: 100%
:alt: classical inverter 1x symbol
Classical inverter 1x symbol.
The XML code describing this inverter is:
.. code-block:: xml
<circuit_model type="inv_buf" name="inv1x" prefix="inv1x">
<design_technology type="cmos" topology="inverter" size="1"/>
<port type="input" prefix="in" size="1"/>
<port type="output" prefix="out" size="1"/>
</circuit_model>
This example shows:
- The topology chosen as inverter
- Size of 1 for the output strength
- The tapered parameter is not declared and is ``false`` by default
Power-gated Inverter 1x example
```````````````````````````````
The XML code describing an inverter which can be power-gated by the control signals ``EN`` and ``ENB`` :
.. code-block:: xml
<circuit_model type="inv_buf" name="INVTX1" prefix="INVTX1">
<design_technology type="cmos" topology="inverter" size="3" power_gated="true"/>
<port type="input" prefix="in" size="1" lib_name="I"/>
<port type="input" prefix="EN" size="1" lib_name="EN" is_global="true" default_val="0" is_config_enable="true"/>
<port type="input" prefix="ENB" size="1" lib_name="ENB" is_global="true" default_val="1" is_config_enable="true"/>
<port type="output" prefix="out" size="1" lib_name="Z"/>
</circuit_model>
.. note:: For power-gated inverters: all the control signals must be set as ``config_enable`` so that the testbench generation will generate testing waveforms. If the power-gated inverters are auto-generated , all the ``config_enable`` signals must be ``global`` signals as well. If the pwoer-gated inverters come from user-defined netlists, restrictions on ``global`` signals are free.
Buffer 2x example
`````````````````
:numref:`fig_buff` is the buffer symbol depicted in this example.
.. _fig_buff:
.. figure:: ./figures/Buffer.png
:scale: 50%
:alt: buffer symbol composed by 2 inverter, its output strength equals to 2
Buffer made by two inverter, with an output strength of 2.
The XML code describing this buffer is:
.. code-block:: xml
<circuit_model type="inv_buf" name="buf2" prefix="buf2">
<design_technology type="cmos" topology="buffer" size="2"/>
<port type="input" prefix="in" size="1"/>
<port type="output" prefix="out" size="1"/>
</circuit_model>
This example shows:
- The topology chosen as buffer
- Size of 2 for the output strength
- The tapered parameter is not declared and is ``false`` by default
Tapered inverter 16x example
````````````````````````````
:numref:`fig_invtap4` is the tapered inverter symbol depicted this example.
.. _fig_invtap4:
.. figure:: ./figures/Tapered_inverter.png
:scale: 50%
:alt: tapered inverter composed by 3 inverter for an output strength = 16
Inverter with high output strength made by 3 stage of inverter.
The XML code describing this inverter is:
.. code-block:: xml
<circuit_model type="inv_buf" name="tapdrive4" prefix="tapdrive4">
<design_technology type="cmos" topology=”inverter" size="1" num_level="3" f_per_stage="4"/>
<port type="input" prefix="in" size="1"/>
<port type="output" prefix="out" size="1"/>
</circuit_model>
This example shows:
- The topology chosen as inverter
- Size of 1 for the first stage output strength
- The number of stage is set to 3 by
- f_per_stage is set to 4. Then 2nd stage output strength is 4* the 1st stage output strength (so 4*1 = 4) and the 3rd stage output strength is 4* the 2nd stage output strength (so 4*4 = 16).
Pass-gate Logic
~~~~~~~~~~~~~~~
Template
````````
.. code-block:: xml
<circuit_model type="pass_gate" name="<string>" prefix="<string>" netlist="<string>" is_default="<int>">
<design_technology type="cmos" topology="<string>" nmos_size="<float>" pmos_size="<float>"/>
<input_buffer exist="false"/>
<output_buffer exist="false"/>
<port type="input" prefix="<string>" size="<int>"/>
<port type="output" prefix="<string>" size="<int>"/>
</circuit_model>
.. note:: Please do not add input and output buffers to pass-gate logic.
.. option:: <design_technology type="cmos" topology="<string>" nmos_size="<float>" pmos_size="<float>"/>
- ``topology="transmission_gate|pass_transistor"`` Specify the circuit topology for the pass-gate logic. A transmission gate consists of a *n*-type transistor and a *p*-type transistor. The pass transistor consists of only a *n*-type transistor.
- ``nmos_size="<float>"`` the size of *n*-type transistor in a transmission gate or pass_transistor, expressed in terms of the minimum width ``min_width`` defined in the transistor model in :ref:`technology_library`.
- ``pmos_size="<float>"`` the size of *p*-type transistor in a transmission gate, expressed in terms of the minimum width ``min_width`` defined in the transistor model in :ref:`technology_library`.
.. note:: ``nmos_size`` and ``pmos_size`` are required for FPGA-SPICE
Transmission-gate Example
`````````````````````````
:numref:`fig_passgate` is the pass-gate symbol depicted in this example.
.. _fig_passgate:
.. figure:: ./figures/pass-gate.png
:scale: 30%
:alt: pmos and nmos transistortors forming a pass-gate
Pass-gate made by a *p*-type and a *n*-type transistors.
The XML code describing this pass-gate is:
.. code-block:: xml
<circuit_model type="pass_gate" name="tgate" prefix="tgate">
<design_technology type="cmos" topology="transmission_gate" nmos_size="1" pmos_size="2"/>
<port type="input" prefix="in" size="1"/>
<port type="input" prefix="sram" size="1"/>
<port type="input" prefix="sramb" size="1"/>
<port type="output" prefix="out" size="1"/>
</circuit_model>
This example shows:
- A ``transmission_gate`` built with a *n*-type transistor in the size of 1 and a *p*-type transistor in the size of 2.
- 3 inputs considered, 1 for datapath signal and 2 to turn on/off the transistors gates
Pass-transistor Example
```````````````````````
:numref:`fig_passtran` is the pass-gate symbol depicted in this example.
.. _fig_passtran:
.. figure:: ./figures/pass_transistor.png
:scale: 30%
:alt: nmos transistortor forming a pass-gate
Pass-gate made by a nmos transistor.
The XML code describing this pass-gate is:
.. code-block:: xml
<circuit_model type="pass_gate" name="t_pass" prefix="t_pass">
<design_technology type="cmos" topology="pass_transistor"/>
<port type="input" prefix="in" size="1"/>
<port type="input" prefix="sram" size="1"/>
<port type="output" prefix="out" size="1"/>
</circuit_model>
This example shows:
- A ``pass_transistor`` build with a *n*-type transistor in the size of 1
- 2 inputs considered, 1 for datapath signal and 1 to turn on/off the transistor gate
SRAMs
~~~~~
Template
````````
.. code-block:: xml
<circuit_model type="sram" name="<string>" prefix="<string>" verilog_netlist="<string>" spice_netlist="<string>"/>
<design_technology type="cmos"/>
<input_buffer exist="<string>" circuit_model_name="<string>"/>
<output_buffer exist="<string>" circuit_model_name="<string>"/>
<port type="input" prefix="<string>" size="<int>"/>
<port type="output" prefix="<string>" size="<int>"/>
</circuit_model>
.. note:: The circuit designs of SRAMs are highly dependent on the technology node and well optimized by engineers. Therefore, FPGA-Verilog/SPICE requires users to provide their customized SRAM Verilog/SPICE/Verilog netlists. A sample Verilog/SPICE netlist of SRAM can be found in the directory SpiceNetlists in the released package. FPGA-Verilog/SPICE assumes that all the LUTs and MUXes employ the SRAM circuit design. Therefore, currently only one SRAM type is allowed to be defined.
.. 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.
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
~~~~~~~~~~~
The circuit model in the type of ``gate`` aims to support direct mapping to standard cells or customized cells provided by technology vendors or users.
Template
````````
.. code-block:: xml
<circuit_model type="gate" name="<string>" prefix="<string>" spice_netlist="<string>" verilog_netlist="<string>"/>
<design_technology type="cmos" topology="<string>"/>
<input_buffer exist="<string>" circuit_model_name="<string>"/>
<output_buffer exist="<string>" circuit_model_name="<string>"/>
<port type="input" prefix="<string>" lib_name="<string>" size="<int>"/>
<port type="output" prefix="<string>" lib_name="<string>" size="<int>"/>
</circuit_model>
.. option:: <design_technology type="cmos" topology="<string>"/>
- ``topology="AND|OR|MUX2"`` Specify the logic functionality of a gate. As for standard cells, the size of each port is limited to 1. Currently, only 2-input and single-output logic gates are supported.
2-input OR Gate Example
```````````````````````
.. code-block:: xml
<circuit_model type="gate" name="OR2" prefix="OR2" is_default="true">
<design_technology type="cmos" topology="OR"/>
<input_buffer exist="false"/>
<output_buffer exist="false"/>
<port type="input" prefix="a" size="1"/>
<port type="input" prefix="b" size="1"/>
<port type="output" prefix="out" size="1"/>
<delay_matrix type="rise" in_port="a b" out_port="out">
10e-12 8e-12
</delay_matrix>
<delay_matrix type="fall" in_port="a b" out_port="out">
10e-12 7e-12
</delay_matrix>
</circuit_model>
This example shows:
- A 2-input OR gate without any input and output buffers
- Propagation delay from input ``a`` to ``out`` is 10ps in rising edge and and 8ps in falling edge
- Propagation delay from input ``b`` to ``out`` is 10ps in rising edge and 7ps in falling edge
MUX2 Gate Example
```````````````````````
.. code-block:: xml
<circuit_model type="gate" name="MUX2" prefix="MUX2" is_default="true" verilog_netlist="sc_mux.v">
<design_technology type="cmos" topology="MUX2"/>
<input_buffer exist="false"/>
<output_buffer exist="false"/>
<port type="input" prefix="in0" lib_name="B" size="1"/>
<port type="input" prefix="in1" lib_name="A" size="1"/>
<port type="input" prefix="sel" lib_name="S" size="1"/>
<port type="output" prefix="out" lib_name="Y" size="1"/>
</circuit_model>
This example shows:
- A 2-input MUX gate with two inputs ``in0`` and ``in1``, a select port ``sel`` and an output port ``out``
- The Verilog of MUX2 gate is provided by the user in the netlist ``sc_mux.v``
- The use of ``lib_name`` to bind to a Verilog module with different port names.
- When binding to the Verilog module, the inputs will be swapped. In other words, ``in0`` of the circuit model will be wired to the input ``B`` of the MUX2 cell, while ``in1`` of the circuit model will be wired to the input ``A`` of the MUX2 cell.
.. note:: OpenFPGA requires a fixed truth table for the ``MUX2`` gate. When the select signal sel is enabled, the first input, i.e., ``in0``, will be propagated to the output, i.e., ``out``. If your standard cell provider does not offer the exact truth table, you can simply swap the inputs as shown in the example.
Multiplexers
~~~~~~~~~~~~
Template
````````
.. code-block:: xml
<circuit_model type="mux" name="<string>" prefix="<string>">
<design_technology type="<string>" structure="<string>" num_level="<int>" add_const_input="<bool>" const_input_val="<int>" local_encoder="<bool>"/>
<input_buffer exist="<string>" circuit_model_name="<string>"/>
<output_buffer exist="<string>" circuit_model_name="<string>"/>
<pass_gate_logic type="<string>" circuit_model_name="<string>"/>
<port type="input" prefix="<string>" size="<int>"/>
<port type="output" prefix="<string>" size="<int>"/>
<port type="sram" prefix="<string>" size="<int>"/>
</circuit_model>
.. note:: user-defined Verilog/SPICE netlists are not currently supported for multiplexers.
.. option:: <design_technology type="<string>" structure="<string>" num_level="<int>" add_const_input="<bool>" const_input_val="<int>" local_encoder="<bool>"/>
- ``structure="tree|multi-level|one-level"`` Specify the multiplexer structure for a multiplexer. The structure option is only valid for SRAM-based multiplexers. For RRAM-based multiplexers, currently we only support the one-level structure
- ``num_level="<int>"`` Specify the number of levels when ``multi-level`` structure is selected.
- ``add_const_input="true|false"`` Specify if an extra input should be added to the multiplexer circuits. For example, an 4-input multiplexer will be turned to a 5-input multiplexer. The extra input will be wired to a constant value, which can be specified through the XML syntax ``const_input_val``.
.. note:: Adding an extra constant input will help reducing the leakage power of FPGA and parasitic signal activities, with a limited area overhead.
- ``const_input_val="0|1"`` Specify the constant value, to which the extra input will be connected. By default it is 0. This syntax is only valid when the ``add_const_input`` is set to true.
- ``local_encoder="true|false"``. Specify if a local encoder should be added to the multiplexer circuits. The local encoder will interface the SRAM inputs of multiplexing structure and SRAMs. It can encode the one-hot codes (that drive the select port of multiplexing structure) to a binary code. For example, 8-bit ``00000001`` will be encoded to 3-bit ``000``. This will help reduce the number of SRAM cells used in FPGAs as well as configuration time (especially for scan-chain configuration protocols). But it may cost an area overhead.
.. note:: Local encoders are only applicable for one-level and multi-level multiplexers. Tree-like multiplexers are already encoded in their nature.
.. note:: A multiplexer should have only three types of ports, ``input``, ``output`` and ``sram``, which are all mandatory.
.. note:: For tree-like multiplexers, they can be built with standard cell MUX2. To enable this, users should define a ``circuit_model``, which describes a 2-input multiplexer (See details and examples in how to define a logic gate using ``circuit_model``. In this case, the ``circuit_model_name`` in the ``pass_gate_logic`` should be the name of MUX2 ``circuit_model``.
.. note:: When multiplexers are not provided by users, the size of ports do not have to be consistent with actual numbers in the architecture.
One-level Mux Example
`````````````````````
:numref:`fig_mux1` illustrates an example of multiplexer modelling, which consists of input/output buffers and a transmission-gate-based tree structure.
.. _fig_mux1:
.. figure:: ./figures/mux1lvl.png
:scale: 60%
:alt: Detailed one level Multiplexer
An example of a one level multiplexer with transistor-level design parameters
The code describing this Multiplexer is:
.. code-block:: xml
<circuit_model type="mux" name="mux_1level" prefix="mux_1level">
<design_technology type="cmos" structure="one-level"/>
<input_buffer exist="on" circuit_model_name="inv1x"/>
<output_buffer exist="on" circuit_model_name="tapbuf4"/>
<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="4"/>
</circuit_model>
This example shows:
- A one-level 4-input CMOS multiplexer
- All the inputs will be buffered using the circuit model ``inv1x``
- All the outputs will be buffered using the circuit model ``tapbuf4``
- The multiplexer will be built by transmission gate using the circuit model ``tgate``
- The multiplexer will have 4 inputs and 4 SRAMs to control which datapath to propagate
Tree-like Multiplexer Example
`````````````````````````````
:numref:`fig_mux` illustrates an example of multiplexer modelling, which consists of input/output buffers and a transmission-gate-based tree structure.
.. _fig_mux:
.. figure:: ./figures/mux.png
:scale: 100%
:alt: Examples of Mux-tree
An example of a tree-like multiplexer with transistor-level design parameters
If we arbitrarily fix the number of Mux entries at 4, the following code could illustrate (a):
.. code-block:: xml
<circuit_model type="mux" name="mux_tree" prefix="mux_tree">
<design_technology type="cmos" structure="tree"/>
<input_buffer exist="on" circuit_model_name="inv1x"/>
<output_buffer exist="on" circuit_model_name="tapdrive4"/>
<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="3"/>
</circuit_model>
This example shows:
- A tree-like 4-input CMOS multiplexer
- All the inputs will be buffered using the circuit model ``inv1x``
- All the outputs will be buffered using the circuit model ``tapbuf4``
- The multiplexer will be built by transmission gate using the circuit model ``tgate``
- The multiplexer will have 4 inputs and 3 SRAMs to control which datapath to propagate
Standard Cell Multiplexer Example
`````````````````````````````````
.. code-block:: xml
<circuit_model type="mux" name="mux_stdcell" prefix="mux_stdcell">
<design_technology type="cmos" structure="tree"/>
<input_buffer exist="on" circuit_model_name="inv1x"/>
<output_buffer exist="on" circuit_model_name="tapdrive4"/>
<pass_gate_logic circuit_model_name="MUX2"/>
<port type="input" prefix="in" size="4"/>
<port type="output" prefix="out" size="1"/>
<port type="sram" prefix="sram" size="3"/>
</circuit_model>
This example shows:
- A tree-like 4-input CMOS multiplexer built by the standard cell ``MUX2``
- All the inputs will be buffered using the circuit model ``inv1x``
- All the outputs will be buffered using the circuit model ``tapbuf4``
- The multiplexer will have 4 inputs and 3 SRAMs to control which datapath to propagate
Look-Up Tables
~~~~~~~~~~~~~~
Template
````````
.. code-block:: xml
<circuit_model type="lut" name="<string>" prefix="<string>" spice_netlist="<string>" verilog_netlist="<string>"/>
<design_technology type="cmos" fracturable_lut="<bool>"/>
<input_buffer exist="<string>" circuit_model_name="<string>"/>
<output_buffer exist="<string>" circuit_model_name="<string>"/>
<lut_input_buffer exist="<string>" circuit_model_name="<string>"/>
<lut_input_inverter exist="<string>" circuit_model_name="<string>"/>
<lut_intermediate_buffer exist="<string>" circuit_model_name="<string>" location_map="<string>"/>
<pass_gate_logic type="<string>" circuit_model_name="<string>"/>
<port type="input" prefix="<string>" size="<int>" tri_state_map="<string>" circuit_model_name="<string>"/>
<port type="output" prefix="<string>" size="<int>" lut_frac_level="<int>" lut_output_mask="<int>"/>
<port type="sram" prefix="<string>" size="<int>" mode_select="<bool>" circuit_model_name="<string>" default_val="<int>"/>
</circuit_model>
.. note:: The Verilog/SPICE netlists of LUT can be auto-generated or customized.
The auto-generated LUTs are based on a tree-like multiplexer, whose gates of the transistors are used as the inputs of LUTs and the drains/sources of the transistors are used for configurable memories (SRAMs).
The LUT provided in customized Verilog/SPICE netlist should have the same decoding methodology as the traditional LUT.
.. option:: <lut_input_buffer exist="<string>" circuit_model_name="<string>"/>
Define transistor-level description for the buffer for the inputs of a LUT (gates of the internal multiplexer).
- ``exist="true|false"`` Specify if the input buffer should exist for LUT inputs
- ``circuit_model_name="<string>"`` Specify the ``circuit_model`` that will be used to build the input buffers
.. note:: In the context of LUT, ``input_buffer`` corresponds to the buffer for the datapath inputs of multiplexers inside a LUT. ``lut_input_buffer`` corresponds to the buffer at the inputs of a LUT
.. option:: <lut_input_inverter exist="<string>" circuit_model_name="<string>"/>
Define transistor-level description for the inverter for the inputs of a LUT (gates of the internal multiplexer).
- ``exist="true|false"`` Specify if the input buffer should exist for LUT inputs
- ``circuit_model_name="<string>"`` Specify the ``circuit_model`` that will be used to build the input inverters
.. option:: <lut_intermediate_buffer exist="<string>" circuit_model_name="<string>" location_map="<string>"/>
Define transistor-level description for the buffer locating at intermediate stages of internal multiplexer of a LUT.
- ``exist="true|false"`` Specify if the input buffer should exist at intermediate stages
- ``circuit_model_name="<string>"`` Specify the ``circuit_model`` that will be used to build these buffers
- ``location_map="[1|-]"`` Customize the location of buffers in intermediate stages. Users can define an integer array consisting of '1' and '-'. For example, ``-1-1-`` indicates buffer inseration to every two stages of the LUT multiplexer tree, considering a 6-input LUT.
.. note:: For a LUT, three types of ports (``input``, ``output`` and ``sram``) should be defined. If the user provides an customized Verilog/SPICE netlist, the bandwidth of ports should be defined to the same as the Verilog/SPICE netlist. To support customizable LUTs, each type of port contain special keywords.
.. option:: <port type="input" prefix="<string>" size="<int>" tri_state_map="<string>" circuit_model_name="<string>"/>
- ``tri_state_map="[-|1]"`` Customize which inputs are fixed to constant values when the LUT is in fracturable modes. For example, ``tri_state_map="----11"`` indicates that the last two inputs will be fixed to be logic '1' when a 6-input LUT is in fracturable modes.
- ``circuit_model_name="<string>"`` Specify the circuit model to build logic gates in order to tri-state the inputs in fracturable LUT modes. It is required to use an ``AND`` gate to force logic '0' or an ``OR`` gate to force logic '1' for the input ports.
.. option:: <port type="output" prefix="<string>" size="<int>" lut_frac_level="<int>" lut_output_mask="<int>"/>
- ``lut_frac_level="<int>"`` Specify the level in LUT multiplexer tree where the output port are wired to. For example, ``lut_frac_level="4"`` in a fracturable LUT6 means that the output are potentially wired to the 4th stage of a LUT multiplexer and it is an output of a LUT4.
- ``lut_output_mask="<int>"`` Describe which fracturable outputs are used. For instance, in a 6-LUT, there are potentially four LUT4 outputs can be wired out. ``lut_output_mask="0,2"`` indicates that only the first and the thrid LUT4 outputs will be used in fracturable mode.
.. note:: The size of the output port should be consistent to the length of ``lut_output_mask``.
.. option:: <port type="sram" prefix="<string>" size="<int>" mode_select="<bool>" circuit_model_name="<string>" default_val="<int>"/>
- ``mode_select="true|false"`` Specify if this port is used to switch the LUT between different operating modes, the SRAM bits of a fracturable LUT consists of two parts: configuration memory and mode selecting.
- ``circuit_model_name="<string>"`` Specify the circuit model to be drive the SRAM port. Typically, the circuit model should be in the type of ``ccff`` or ``sram``.
- ``default_val="0|1"`` Specify the default value for the SRAM port. The default value will be used in generating testbenches for unused LUTs
.. note:: The size of a mode-selection SRAM port should be consistent to the number of '1s' or '0s' in the ``tri_state_map``.
Single-Output LUT Example
`````````````````````````
:numref:`fig_lut` illustrates an example of LUT modeling, which consists of input/output buffers and a transmission-gate-based tree structure.
.. _fig_lut:
.. figure:: ./figures/lut.png
:scale: 80%
:alt: Detailed LUT composition
An example of a LUT with transistor-level design parameters.
The code describing this LUT is:
.. code-block:: xml
<circuit_model type="lut" name="lut6" prefix="lut6">
<input_buffer exist="on" circuit_model="inv1x"/>
<output_buffer exist="on" circuit_model_name="inv1x"/>
<lut_input_buffer exist="on" circuit_model_name="buf2"/>
<lut_input_inverter exist="on" circuit_model_name="inv1x"/>
<pass_gate_logic circuit_model_name="tgate"/>
<port type="input" prefix="in" size="6"/>
<port type="output" prefix="out" size="1"/>
<port type="sram" prefix="sram" size="64"/>
</circuit_model>
This example shows:
- A 6-input LUT which is configurable by 64 SRAM cells.
- The multiplexer inside LUT will be built with transmission gate using circuuit model ``inv1x``
- There are no internal buffered inserted to any intermediate stage of a LUT
Fracturable LUT Example
`````````````````````````
.. code-block:: xml
<circuit_model type="lut" name="frac_lut6" prefix="frac_lut6" dump_structural_verilog="true">
<design_technology type="cmos" fracturable_lut="true"/>
<input_buffer exist="true" circuit_model_name="inv1x"/>
<output_buffer exist="true" circuit_model_name="inv1x"/>
<lut_input_inverter exist="true" circuit_model_name="inv1x"/>
<lut_input_buffer exist="true" circuit_model_name="buf4"/>
<lut_intermediate_buffer exist="true" circuit_model_name="buf4" location_map="-1-1-"/>
<pass_gate_logic circuit_model_name="tgate"/>
<port type="input" prefix="in" size="6" tri_state_map="-----1" circuit_model_name="OR2"/>
<port type="output" prefix="lut5_out" size="2" lut_frac_level="5" lut_output_mask="0,1"/>
<port type="output" prefix="lut6_out" size="1" lut_output_mask="0"/>
<port type="sram" prefix="sram" size="64"/>
<port type="sram" prefix="mode" size="1" mode_select="true" circuit_model_name="ccff" default_val="1"/>
</circuit_model>
This example shows:
- Fracturable 6-input LUT which is configurable by 65 SRAM cells.
- Intermedate buffers are added to every two stages of the internal multiplexer
- There is a SRAM cell to switch the operating mode of this LUT, configured by a configuration-chain flip-flop ``ccff``
- The last input ``in[5]`` of LUT will be tri-stated in dual-LUT5 mode.
- An 2-input OR gate will be wired to the last input ``in[5]`` to tri-state the input. The mode-select SRAM will be wired to an input of the OR gate.
It means that when the mode-selection bit is '1', the LUT will operate in dual-LUT5 mode.
- There will be two outputs wired to the 5th stage of routing multiplexer (the outputs of dual 5-input LUTs)
- By default, the mode-selection configuration bit will be '1', indicating that by default the LUT will operate in dual-LUT5 mode.
Flip-Flops
~~~~~~~~~~
Template
````````
.. code-block:: xml
<circuit_model type="ccff|ff" name="<string>" prefix="<string>" spice_netlist="<string>" verilog_netlist="<string>"/>
<design_technology type="cmos"/>
<input_buffer exist="<string>" circuit_model_name="<string>"/>
<output_buffer exist="<string>" circuit_model_name="<string>"/>
<port type="input" prefix="<string>" size="<int>"/>
<port type="output" prefix="<string>" size="<int>"/>
<port type="clock" prefix="<string>" size="<int>"/>
</circuit_model>
.. note:: The circuit designs of flip-flops are highly dependent on the technology node and well optimized by engineers. Therefore, FPGA-Verilog/SPICE requires users to provide their customized FF Verilog/SPICE/Verilog netlists. A sample Verilog/SPICE netlist of FF can be found in the directory SpiceNetlists in the released package.
The information of input and output buffer should be clearly specified according to the customized SPICE netlist! The existence of input/output buffers will influence the decision in creating SPICE testbenches, which may leads to larger errors in power analysis.
.. note:: FPGA-Verilog/SPICE currently support only one clock domain in the FPGA. Therefore there should be only one clock port to be defined and the size of the clock port should be 1.
.. option:: <circuit_model type="ccff|ff" name="<string>" prefix="<string>" spice_netlist="<string>" verilog_netlist="<string>"/>
- ``type="ccff|ff"`` Specify the type of a flip-flop. ``ff`` is a regular flip-flop while ``ccff`` denotes a configuration-chain flip-flop
.. note:: A flip-flop should have three types of ports, ``input``, ``output`` and ``clock``.
.. note:: If the user provides a customized Verilog/SPICE netlist, the bandwidth of ports should be defined to the same as the Verilog/SPICE netlist.
.. note:: In a valid FPGA architecture, users should provide at least either a ``ccff`` or ``sram`` circuit model, so that the configurations can loaded to core logic.
Flip-Flop example
`````````````````
:numref:`fig_ff` illustrates an example of regular flip-flop.
.. _fig_ff:
.. figure:: ./figures/FF.png
:scale: 50%
:alt: FF symbol
An example of classical Flip-Flop.
The code describing this FF is:
.. code-block:: xml
<circuit_model type="ff" name="dff" prefix="dff" verilog_netlist="ff.v" spice_netlist="ff.sp">
<port type="input" prefix="D" lib_name="D" size="1"/>
<port type="input" prefix="Set" lib_name="S" size="1" is_global="true"/>
<port type="input" prefix="Reset" lib_name="R" size="1" is_global="true"/>
<port type="output" prefix="Q" lib_name="Q" size="1"/>
<port type="clock" prefix="clk" lib_name="CK" size="1" is_global="true"/>
</circuit_model>
This example shows:
- A regular flip-flop which is defined in a Verilog netlist ``ff.v`` and a SPICE netlist ``ff.sp``
- The flip-flop has ``set`` and ``reset`` functionalities
- The flip-flop port names defined differently in standard cell library and VPR architecture. The ``lib_name`` capture the port name defined in standard cells, while ``prefix`` capture the port name defined in ``pb_type`` of VPR architecture file
Configuration-chain Flip-flop Example
`````````````````````````````````````
:numref:`fig_ccff` illustrates an example of scan-chain flop-flop used to build a configuration chain.
.. _fig_ccff:
.. figure:: ./figures/scff.png
:scale: 50%
:alt: SCFF symbol
An example of a Scan-Chain Flip-Flop.
The code describing this FF is:
.. code-block:: xml
<circuit_model type="ccff" name="ccff" prefix="ccff" verilog_netlist="ccff.v" spice_netlist="ccff.sp">
<port type="input" prefix="D" size="1"/>
<port type="output" prefix="Q" size="2"/>
<port type="clock" prefix="CK" size="1" is_global="true"/>
</circuit_model>
This example shows:
- A configuration-chain flip-flop which is defined in a Verilog netlist ``ccff.v`` and a SPICE netlist ``ccff.sp``
- The flip-flop has a global clock port, ``CK``, which will be wired a global programming clock
Hard Logics
~~~~~~~~~~~
Template
````````
.. code-block:: xml
<circuit_model type="hardlogic" name="<string>" prefix="<string>" verilog_netlist="<string>" spice_netlist="<string>"/>
<design_technology type="cmos"/>
<input_buffer exist="<string>" circuit_model_name="<string>"/>
<output_buffer exist="<string>" circuit_model_name="<string>"/>
<port type="input" prefix="<string>" size="<int>"/>
<port type="output" prefix="<string>" size="<int>"/>
</circuit_model>
.. note:: Hard logics are defined for non-configurable resources in FPGA architectures, such as adders, multipliers and RAM blocks.
Their circuit designs are highly dependent on the technology node and well optimized by engineers.
As more functional units are included in FPGA architecture, it is impossible to auto-generate these functional units.
Therefore, FPGA-Verilog/SPICE requires users to provide their customized Verilog/SPICE netlists.
.. note:: Examples can be found in hard_logic_example_link_
.. _hard_logic_example_link: https://github.com/LNIS-Projects/OpenFPGA/tree/master/openfpga_flow/VerilogNetlists
.. 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 SPICE testbenches, which may leads to larger errors in power analysis.
1-bit Full Adder Example
````````````````````````
.. code-block:: xml
<circuit_model type="hard_logic" name="adder" prefix="adder" spice_netlist="adder.sp" verilog_netlist="adder.v">
<design_technology type="cmos"/>
<input_buffer exist="true" circuit_model_name="inv1x"/>
<output_buffer exist="true" circuit_model_name="inv1x"/>
<port type="input" prefix="a" size="1"/>
<port type="input" prefix="b" size="1"/>
<port type="input" prefix="cin" size="1"/>
<port type="output" prefix="cout" size="1"/>
<port type="output" prefix="sumout" size="1"/>
</circuit_model>
Routing Wire Segments
~~~~~~~~~~~~~~~~~~~~~
FPGA architecture requires two type of wire segments:
- ``wire``, which targets the local wires inside the logic blocks. The wire has one input and one output, directly connecting the output of a driver and the input of the downstream unit, respectively
- ``chan_wire``, especially targeting the channel wires. The channel wires have one input and two outputs, one of which is connected to the inputs of Connection Boxes while the other is connected to the inputs of Switch Boxes. Two outputs are created because from the view of layout, the inputs of Connection Boxes are typically connected to the middle point of channel wires, which has less parasitic resistances and capacitances than connected to the ending point.
Template
````````
.. code-block:: xml
<circuit_model type="wire|cham_wire" name="<string>" prefix="<string>" spice_netlist="<string>" verilog_netlist="<string>"/>
<design_technology type="cmos"/>
<input_buffer exist="<string>" circuit_model_name="<string>"/>
<output_buffer exist="<string>" circuit_model_name="<string>"/>
<port type="input" prefix="<string>" size="<int>"/>
<port type="output" prefix="<string>" size="<int>"/>
<wire_param model_type="<string>" R="<float>" C="<float>" num_level="<int>"/>
</circuit_model>
.. note:: FPGA-Verilog/SPICE can auto-generate the Verilog/SPICE model for wires while also allows users to provide their customized Verilog/SPICE netlists.
.. note:: The information of input and output buffer should be clearly specified according to the customized netlist! The existence of input/output buffers will influence the decision in creating testbenches, which may leads to larger errors in power analysis.
.. option:: <wire_param model_type="<string>" R="<float>" C="<float>" num_level="<int>"/>
- ``model_type="pi|T"`` Specify the type of RC models for this wire segement. Currently, OpenFPGA supports the π-type and T-type multi-level RC models.
- ``R="<float>"`` Specify the total resistance of the wire
- ``C="<float>"`` Specify the total capacitance of the wire.
- ``num_level="<int>"`` Specify the number of levels of the RC wire model.
.. note:: wire parameters are essential for FPGA-SPICE to accurately model wire parasitics
Routing Track Wire Example
``````````````````````````
:numref:`fig_wire` depicts the modeling for a length-2 channel wire.
.. _fig_wire:
.. figure:: ./figures/wire.png
:scale: 80%
:alt: map to buried treasure
An example of a length-2 channel wire modeling
The code describing this wire is:
.. code-block:: xml
<circuit_model type="chan_wire" name="segment0" prefix="chan_wire"/>
<design_technology type="cmos"/>
<port type="input" prefix="mux_out" size="1"/>
<port type="output" prefix="cb_sb" size="1"/>
<wire_param model_type="pi" res_val="103.84" cap_val="13.80e-15" level="1"/>
</circuit_model>
This example shows
- A routing track wire has 1 input and output
- The routing wire will be modelled as a 1-level π-type RC wire model with a total resistance of :math:`103.84\Omega` and a total capacitance of :math:`13.89fF`
I/O pads
~~~~~~~~
Template
````````
.. code-block:: xml
<circuit_model type="iopad" name="<string>" prefix="<string>" spice_netlist="<string>" verilog_netlist="<string>"/>
<design_technology type="cmos"/>
<input_buffer exist="<string>" circuit_model_name="<string>"/>
<output_buffer exist="<string>" circuit_model_name="<string>"/>
<port type="input" prefix="<string>" size="<int>"/>
<port type="output" prefix="<string>" size="<int>"/>
<port type="sram" prefix="<string>" size="<int>" mode_select="<bool>" circuit_model_name="<string>" default_val="<int>"/>
</circuit_model>
.. note:: The circuit designs of I/O pads are highly dependent on the technology node and well optimized by engineers.
Therefore, FPGA-Verilog/SPICE requires users to provide their customized Verilog/SPICE/Verilog netlists. A sample Verilog/SPICE netlist of an I/O pad can be found in the directory SpiceNetlists in the released package.
.. note:: The information of input and output buffer should be clearly specified according to the customized netlist! The existence of input/output buffers will influence the decision in creating testbenches, which may leads to larger errors in power analysis.
I/O Pad Example
```````````````
:numref:`fig_iopad` depicts an I/O pad.
.. _fig_iopad:
.. figure:: ./figures/iopad.png
:scale: 50%
:alt: IO-Pad symbol
An example of an IO-Pad
The code describing this IO-Pad is:
.. code-block:: xml
<circuit_model type="iopad" name="iopad" prefix="iopad" spice_netlist="io.sp" verilog_netlist="io.v">
<design_technology type="cmos"/>
<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="inout" prefix="pad" size="1"/>
<port type="sram" prefix="en" size="1" mode_select="true" circuit_model_name="ccff" default_val="1"/>
<port type="input" prefix="outpad" size="1"/>
<port type="output" prefix="inpad" size="1"/>
</circuit_model>
This example shows
- A general purpose I/O cell defined in Verilog netlist ``io.sp`` and SPICE netlist ``io.sp``
- The I/O cell has an ``inout`` port as the bi-directional port
- The directionality of I/O can be controlled by a configuration-chain flip-flop defined in circuit model ``ccff``
- If unused, the I/O cell will be configured to ``1``

161
docs/source/manual/arch_lang/config_protocol.rst Normal file
View File

@ -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.

53
docs/source/arch_lang/interconnect.rst → docs/source/manual/arch_lang/direct_interconnect.rst
View File

@ -1,10 +1,12 @@
Interconnection extensions
==========================
.. _direct_interconnect:
Inter-Tile Direct Interconnection extensions
--------------------------------------------
This section introduces extensions on the architecture description file about existing interconnection description.
Directlist
----------
~~~~~~~~~~
The original direct connections in the directlist section are documented here_. Its description is given below:
@ -26,40 +28,49 @@ Our extension include three more options:
<direct name="string" from_pin="string" to_pin="string" x_offset="int" y_offset="int" z_offset="int" switch_name="string" interconnection_type="string" x_dir="string" y_dir="string"/>
</directlist>
.. note:: these options are optional. However, if *interconnection_type* is set *x_dir* and *y_dir* are required.
.. note:: these options are optional. However, if `interconnection_type` is set `x_dir` and `y_dir` are required.
* **interconnection_type**: [``NONE`` | ``column`` | ``row``], specifies if it applies on a column or a row ot if it doesn't apply.
.. option:: interconnection_type="<string>"
* **x_dir**: [``positive`` | ``negative``], specifies if the next cell to connect has a bigger or lower x value. Considering a coordinate system where (0,0) is the origin at the bottom left and *x* and *y* are positives:
the type of interconnection should be a string.
Available types are ``NONE`` | ``column`` | ``row``, specifies if it applies on a column or a row ot if it doesn't apply.
* x_dir="positive":
.. option:: x_dir="<string>"
* interconnection_type="column": a column will be connected to a column on the **right**, if it exists.
Available directionalities are ``positive`` | ``negative``, specifies if the next cell to connect has a bigger or lower ``x`` value.
Considering a coordinate system where (0,0) is the origin at the bottom left and ``x`` and ``y`` are positives:
* interconnection_type="row": the most on the **right** cell from a row connection will connect the most on the **left** cell of next row, if it exists.
- x_dir="positive":
* x_dir="negative":
- interconnection_type="column": a column will be connected to a column on the ``right``, if it exists.
* interconnection_type="column": a column will be connected to a column on the **left**, if it exists.
- interconnection_type="row": the most on the ``right`` cell from a row connection will connect the most on the ``left`` cell of next row, if it exists.
* interconnection_type="row": the most on the **left** cell from a row connection will connect the most on the **right** cell of next row, if it exists.
- x_dir="negative":
* **y_dir**: [``positive`` | ``negative``], specifies if the next cell to connect has a bigger or lower x value. Considering a coordinate system where (0,0) is the origin at the bottom left and *x* and *y* are positives:
- interconnection_type="column": a column will be connected to a column on the ``left``, if it exists.
* y_dir="positive":
- interconnection_type="row": the most on the ``left`` cell from a row connection will connect the most on the ``right`` cell of next row, if it exists.
* interconnection_type="column": the **bottom** cell of a column will be connected to the next column **top** cell, if it exists.
.. option:: y_dir="<string>"
* interconnection_type="row": a row will be connected on an **above** row, if it exists.
Available directionalities are ``positive`` | ``negative``, specifies if the next cell to connect has a bigger or lower x value.
Considering a coordinate system where (0,0) is the origin at the bottom left and `x` and `y` are positives:
* y_dir="negative":
- y_dir="positive":
* interconnection_type="column": the **top** cell of a column will be connected to the next column **bottom** cell, if it exists.
- interconnection_type="column": the ``bottom`` cell of a column will be connected to the next column ``top`` cell, if it exists.
* interconnection_type="row": a row will be connected on a row **below**, if it exists.
- interconnection_type="row": a row will be connected on an ``above`` row, if it exists.
- y_dir="negative":
- interconnection_type="column": the ``top`` cell of a column will be connected to the next column ``bottom`` cell, if it exists.
- interconnection_type="row": a row will be connected on a row ``below``, if it exists.
Example
-------
~~~~~~~
For this example, we will study a scan-chain implementation. The description could be:
@ -81,7 +92,7 @@ For this example, we will study a scan-chain implementation. The description cou
In this figure, the red arrows represent the initial direct connection. The green arrows represent the point to point connection to connect all the columns of CLB.
Truth table
-----------
~~~~~~~~~~~
A point to point connection can be applied in different ways than showed in the example section. To help the designer implement his point to point connection, a truth table with our new parameters id provided below.

0
docs/source/arch_lang/figures/Buffer.png → docs/source/manual/arch_lang/figures/Buffer.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 28 KiB

After

Width:  |  Height:  |  Size: 28 KiB

0
docs/source/arch_lang/figures/FF.png → docs/source/manual/arch_lang/figures/FF.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 32 KiB

After

Width:  |  Height:  |  Size: 32 KiB

0
docs/source/arch_lang/figures/Inverter_1.png → docs/source/manual/arch_lang/figures/Inverter_1.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 15 KiB

After

Width:  |  Height:  |  Size: 15 KiB

0
docs/source/arch_lang/figures/Tapered_inverter.png → docs/source/manual/arch_lang/figures/Tapered_inverter.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 34 KiB

After

Width:  |  Height:  |  Size: 34 KiB

BIN
docs/source/manual/arch_lang/figures/ccff_fpga.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 77 KiB

BIN
docs/source/manual/arch_lang/figures/config_latch.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 16 KiB

BIN
docs/source/manual/arch_lang/figures/frame_config_protocol.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 84 KiB

BIN
docs/source/manual/arch_lang/figures/frame_config_protocol_example.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 257 KiB

BIN
docs/source/manual/arch_lang/figures/global_inout_ports.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 16 KiB

BIN
docs/source/manual/arch_lang/figures/global_input_ports.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 16 KiB

BIN
docs/source/manual/arch_lang/figures/gpin_ports.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 16 KiB

BIN
docs/source/manual/arch_lang/figures/gpio_ports.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 16 KiB

BIN
docs/source/manual/arch_lang/figures/gpout_ports.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 16 KiB

0
docs/source/arch_lang/figures/iopad.png → docs/source/manual/arch_lang/figures/iopad.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 33 KiB

After

Width:  |  Height:  |  Size: 33 KiB

0
docs/source/arch_lang/figures/lut.png → docs/source/manual/arch_lang/figures/lut.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 124 KiB

After

Width:  |  Height:  |  Size: 124 KiB

0
docs/source/arch_lang/figures/meas_edge.png → docs/source/manual/arch_lang/figures/meas_edge.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 116 KiB

After

Width:  |  Height:  |  Size: 116 KiB

0
docs/source/arch_lang/figures/mux.png → docs/source/manual/arch_lang/figures/mux.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 161 KiB

After

Width:  |  Height:  |  Size: 161 KiB

0
docs/source/arch_lang/figures/mux1lvl.png → docs/source/manual/arch_lang/figures/mux1lvl.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 558 KiB

After

Width:  |  Height:  |  Size: 558 KiB

0
docs/source/arch_lang/figures/pass-gate.png → docs/source/manual/arch_lang/figures/pass-gate.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 303 KiB

After

Width:  |  Height:  |  Size: 303 KiB

0
docs/source/arch_lang/figures/pass_transistor.png → docs/source/manual/arch_lang/figures/pass_transistor.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 4.6 KiB

After

Width:  |  Height:  |  Size: 4.6 KiB

0
docs/source/arch_lang/figures/point2point_example.png → docs/source/manual/arch_lang/figures/point2point_example.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 59 KiB

After

Width:  |  Height:  |  Size: 59 KiB

0
docs/source/arch_lang/figures/point2point_truthtable.png → docs/source/manual/arch_lang/figures/point2point_truthtable.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 90 KiB

After

Width:  |  Height:  |  Size: 90 KiB

0
docs/source/arch_lang/figures/scff.png → docs/source/manual/arch_lang/figures/scff.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 25 KiB

After

Width:  |  Height:  |  Size: 25 KiB

0
docs/source/arch_lang/figures/sram.png → docs/source/manual/arch_lang/figures/sram.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 76 KiB

After

Width:  |  Height:  |  Size: 76 KiB

BIN
docs/source/manual/arch_lang/figures/sram_blwl.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 40 KiB

BIN
docs/source/manual/arch_lang/figures/thru_channel.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 28 KiB

BIN
docs/source/manual/arch_lang/figures/vanilla_config_protocol.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 181 KiB

0
docs/source/arch_lang/figures/wire.png → docs/source/manual/arch_lang/figures/wire.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 103 KiB

After

Width:  |  Height:  |  Size: 103 KiB

61
docs/source/manual/arch_lang/generality.rst Normal file
View File

@ -0,0 +1,61 @@
.. _arch_generality:
General Hierarchy
-----------------
For OpenFPGA using VPR7
~~~~~~~~~~~~~~~~~~~~~~~
The extension of the VPR architectural description language is developed as an independent branch of the original one. Most of the FPGA-SPICE descriptions are located under a XML node called <spice_settings>, which is a child node under the root node <architecture>.
Under the <spice_settings>, some child node is created for describing SPICE simulation settings, technology library and transistor-level modeling of circuit modules.
In the following sub-sections, we will introduce the structures of these XML nodes and the parameters provided.
For OpenFPGA using VPR8
~~~~~~~~~~~~~~~~~~~~~~~
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 requires two XML files: an architecture description file and a simulation setting description file.
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``. 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

28
docs/source/manual/arch_lang/index.rst Normal file
View File

@ -0,0 +1,28 @@
OpenFPGA Architecture Description
---------------------------------
.. _arch_lang:
OpenFPGA Architecture Description
.. toctree::
:maxdepth: 2
generality
addon_vpr_syntax
config_protocol
direct_interconnect
simulation_setting
technology_library
circuit_library
circuit_model_examples
annotate_vpr_arch

373
docs/source/manual/arch_lang/simulation_setting.rst Normal file
View File

@ -0,0 +1,373 @@
.. _simulation_setting:
Simulation settings
-------------------
For OpenFPGA using VPR7
~~~~~~~~~~~~~~~~~~~~~~~
All the parameters that need to be defined in the HSPICE simulations are located under a child node called <parameters>, which is under its father node <spice_settings>.
The parameters are divided into three categories and can be defined in three XML nodes, <options>, <measure> and <stimulate>, respectively.
* The XML node <options>
.. code-block:: xml
<options sim_temp=”int” post=”string”captab=”string” fast=”string”/>
These properties define the options that will be printed in the top SPICE netlists.
* **sim_temp:** specify the temperature which will be defined in SPICE netlists. In the top SPICE netlists, it will show as .temp <int>.
* **post:** [on|off]. Specify if the simulation waveforms should be printed out after SPICE simulations. In all the SPICE netlists, it will show as .option POST when turned on.
.. note:: when the SPICE netlists are large or a long simulation duration is defined, the post option is recommended to be off. If not, huge disk space will be occupied by the waveform files.
* **captab:** [on|off]. Specify if the capacitances of all the nodes in the SPICE netlists will be printed out. In the top SPICE netlists, it will show as .option CAPTAB when turned on. When turned on, the SPICE simulation runtime may increase.
* The XML node <stimulate>
.. code-block:: xml
<stimulate>
<clock op_freq=”auto|float” sim_slack=”float” prog_freq=”float”>
<rise slew_time=”float” slew_type=”string”/>
<fall slew_time=”float” slew_type=”string”/>
</clock>
</stimulate>
Define stimulates for the clock signal.
* **op_freq:** either auto or a float number (unit:[Hz]) Specify the operation clock frequency that is used in SPICE simulations. This frequency is used in testbenches for operation phase simulation. Note that this is a mandatory option. Users have to specify either this frequency is automatically determined by assigning “auto” or give an exact number. If this clock frequency is specified, the sim_slack option is disregarded.
* **sim_slack:** add slack to the critical path delay in the SPICE simulation. For example, sim_slack=0.2 implies that the clock period in SPICE simulations is 1.2 of the critical path delay reported by VPR. **Only valid when option op_freq is not specified.**
* **prog_freq:** Specify the programming clock frequency that is used in SPICE simulations. This frequency is used in testbenches for programming phase simulation.
* **slew_type & slew_time:** define the slew of clock signals at the rising/falling edge. Property slew_type can be either absolute or fractional [abs|frac].
* The type of **absolute** implies that the slew time is the absolute value. For example, slew_time=20e-12, slew_type=abs means that the slew of a clock signal is 20ps.
* The type of **fractional** means that the slew time is related to the period (frequency) of the clock signal. For example, slew_time=0.05, slew_type=frac means that the slew of a clock signal takes 5% of the period of the clock.
:numref:`fig_meas_edge` depicts the definition of the slew and delays of signals and the parameters that can be supported by FPGA-SPICE.
.. code-block:: xml
<stimulate>
<input>
<rise slew_time=”float” slew_type=”string”/>
<fall slew_time=”float” slew_type=”string”/>
</input>
</stimulate>
Define the slew of input signals at the rising/falling edge.
* **slew_type & slew_time:** define the slew of all the input signals at the rising/falling edge. Property slew_type can be either absolute or fractional [abs|frac].
* The type of **absolute** implies that the slew time is the absolute value. For example, slew_time=20e-12, slew_type=abs means that the slew of a clock signal is 20ps.
* The type of **fractional** means that the slew time is related to the period (frequency) of the clock signal. For example, slew_time=0.05, slew_type=frac means that the slew of a clock signal takes 5% of the period of the clock.
.. note:: These slew settings are valid for all the input signals of the testbenches in different complexity levels.
.. _fig_meas_edge:
.. figure:: figures/meas_edge.png
:scale: 100%
:alt: map to buried traesure
Parameters in measuring the slew and delay of signals
* The XML node <measure>
.. code-block:: xml
<measure sim_num_clock_cycle=”int”accuracy=”float”accuracy_type=”string”/>
* **sim_num_clock_cycle:** can be either “auto” or an integer. By setting to “auto”, FPGA-SPICE automatically determines the number of clock cycles to simulate, which is related to the average of all the signal density in ACE2 results. When set to an integer, FPGA-SPICE will use the given number of clock cycles in the SPICE netlists.
* **accuracy_type:** [abs|frac]. Specify the type of transient step in SPICE simulation.
* When **abs** is selected, the accuracy should be the absolute value, such as 1e-12.
* When **frac** is selected, the accuracy is the number of simulation points in a clock cycle period, for example, 100.
* **accuracy:** specify the transient step in SPICE simulation. Typically, the smaller the step is, the higher the accuracy that can be reached while the long simulation runtime is. The recommended accuracy is between 0.1ps and 0.01ps, which generates good accuracy and runtime is not significantly long.
.. note:: Users can define the parameters in measuring the slew of signals, under a child node <slew> of the node <measure>.
.. code-block:: xml
<rise upper_thres_pct=”float” lower_thres_pct=”float”/>
Define the starting and ending point in measuring the slew of a rising edge of a signal.
* **upper_thres_pct:** the ending point in measuring the slew of a rising edge. It is expressed as a percentage of the maximum voltage of a signal. For example, the meaning of upper_thres_pct=0.95 is depicted in Figure 2.
* **lower_thres_pct:** the starting point in measuring the slew of a rising edge. It is expressed as a percentage of the maximum voltage of a signal. For example, the meaning of lower_thres_pct=0.05 is depicted in Figure 2.
.. code-block:: xml
<fall upper_thres_pct=”float” lower_thres_pct=”float”/>
* **upper_thres_pct:** the ending point in measuring the slew of a falling edge. It is expressed as a percentage of the maximum voltage of a signal. For example, the meaning of upper_thres_pct=0.05 is depicted in Figure 2.
* **lower_thres_pct:** the starting point in measuring the slew of a falling edge. It is expressed as a percentage of the maximum voltage of a signal. For example, the meaning of lower_thres_pct=0.95 is depicted in Figure 2.
.. note:: Users can define the parameters related to measurements of delays between signals, under a child node <delay> of the node <measure>.
.. code-block:: xml
<rise input_thres_pct=”float” output_thres_pct=”float”/>
Define the starting and ending point in measuring the delay between two signals when they are both at a rising edge.
* **input_thres_pct:** the starting point in measuring the delay of a rising edge. It is expressed as a percentage of the maximum voltage of a signal. For example, the meaning of input_thres_pct=0.5 is depicted in Figure 2.
* **output_thres_pct:** the ending point in measuring the delay of a rising edge. It is expressed as a percentage of the maximum voltage of a signal. For example, the meaning of output_thres_pct=0.5 is depicted in Figure 2.
.. code-block:: xml
<fall input_thres_pct=”float” output_thres_pct=”float”/>
Define the starting and ending point in measuring the delay between two signals when they are both at a falling edge.
* **input_thres_pct:** the starting point in measuring the delay of a falling edge. It is expressed as a percentage of the maximum voltage of a signal. For example, upper_thres_pct=0.5 is depicted in :numref:`fig_meas_edge`.
* **output_thres_pct:** the ending point in measuring the delay of a falling edge. It is expressed as a percentage of the maximum voltage of a signal. For example, lower_thres_pct=0. 5 is depicted in :numref:`fig_meas_edge`.
For OpenFPGA using VPR8
~~~~~~~~~~~~~~~~~~~~~~~
All the simulation settings are stored under the XML node ``<openfpga_simulation_setting>``
General organization is as follows
.. code-block:: xml
<openfpga_simulation_setting>
<clock_setting>
<operating frequency="<int>|<string>" num_cycles="<int>|<string>" slack="<float>"/>
<programming frequency="<int>"/>
</clock_setting>
<simulator_option>
<operating_condition temperature="<int>"/>
<output_log verbose="<bool>" captab="<bool>"/>
<accuracy type="<string>" value="<float>"/>
<runtime fast_simulation="<bool>"/>
</simulator_option>
<monte_carlo num_simulation_points="<int>"/>
<measurement_setting>
<slew>
<rise upper_thres_pct="<float>" lower_thres_pct="<float>"/>
<fall upper_thres_pct="<float>" lower_thres_pct="<float>"/>
</slew>
<delay>
<rise input_thres_pct="<float>" output_thres_pct="<float>"/>
<fall input_thres_pct="<float>" output_thres_pct="<float>"/>
</delay>
</measurement_setting>
<stimulus>
<clock>
<rise slew_type="<string>" slew_time="<float>"/>
<fall slew_type="<string>" slew_time="<float>"/>
</clock>
<input>
<rise slew_type="<string>" slew_time="<float>"/>
<fall slew_type="<string>" slew_time="<float>"/>
</input>
</stimulus>
</openfpga_simulation_setting>
Clock Setting
^^^^^^^^^^^^^
Clock setting focuses on defining the clock periods to applied on FPGA fabrics
As a programmable device, an FPGA has two types of clocks.
The first is the operating clock, which is applied by users' implementations.
The second is the programming clock, which is applied on the configuration protocol to load users' implementation to FPGA fabric.
OpenFPGA allows users to freely define these clocks as well as the number of clock cycles.
We should the full syntax in the code block below and then provide details on each of them.
.. code-block:: xml
<clock_setting>
<operating frequency="<float>|<string>" num_cycles="<int>|<string>" slack="<float>"/>
<programming frequency="<float>"/>
</clock_setting>
Operating clock setting
```````````````````````
Operating clocks are defined under the XML node ``<operating>``
.. option:: <operating frequency="<float>|<string>" num_cycles="<int>|<string>" slack="<float>"/>
- ``frequency="<float|string>``
Specify frequency of the operating clock. OpenFPGA allows users to specify an absolute value in the unit of ``[Hz]``
Alternatively, users can bind the frequency to the maximum clock frequency analyzed by VPR STA engine.
This is very useful to validate the maximum operating frequency for users' implementations
In such case, the value of this attribute should be a reserved word ``auto``.
- ``num_cycles="<int>|<string>"``
can be either ``auto`` or an integer. When set to ``auto``, OpenFPGA will infer the number of clock cycles from the average/median of all the signal activities.
When set to an integer, OpenFPGA will use the given number of clock cycles in HDL and SPICE simulations.
- ``slack="<float>"``
add a margin to the critical path delay in the HDL and SPICE simulations.
This parameter is applied to the critical path delay provided by VPR STA engine.
So it is only valid when option ``frequency`` is set to ``auto``.
This aims to compensate any inaccuracy in STA results.
Typically, the slack value is between ``0`` and ``1``.
For example, ``slack=0.2`` implies that the actual clock period in simulations is 120% of the critical path delay reported by VPR.
.. note:: Only valid when option ``frequency`` is set to ``auto``
.. warning:: Avoid to use a negative slack! This may cause your simulation to fail!
Programming clock setting
`````````````````````````
Programming clocks are defined under the XML node ``<programming>``
.. option:: <programming frequency="<float>"/>
- ``frequency="<float>"``
Specify the frequency of the programming clock using an absolute value in the unit of ``[Hz]``
This frequency is used in testbenches for programming phase simulation.
.. note:: Programming clock frequency is typically much slower than the operating clock and strongly depends on the process technology. Suggest to characterize the speed of your configuration protocols before specifying a value!
Simulator Option
^^^^^^^^^^^^^^^^
This XML node includes universal options available in both HDL and SPICE simulators.
.. note:: This is mainly used by FPGA-SPICE
Operating condition
```````````````````
.. option:: <operating_condition temperature="<int>"/>``
- ``temperature="<int>"``
Specify the temperature which will be defined in SPICE netlists. In the top SPICE netlists, it will show as
.. code-block:: python
.temp <int>
Output logs
```````````
.. option:: <output_log verbose="<bool>" captab="<bool>"/>``
Specify the options in outputting simulation results to log files
- ``verbose="true|false"``
Specify if the simulation waveforms should be printed out after SPICE simulations. If turned on, it will show in all the SPICE netlists
.. code-block:: python
.option POST
.. note:: when the SPICE netlists are large or a long simulation duration is defined, the post option is recommended to be off. If not, huge disk space will be occupied by the waveform files.
- ``captab="true|false"``
Specify if the capacitances of all the nodes in the SPICE netlists will be printed out. If turned on, it will show in the top-level SPICE netlists
.. code-block:: python
.option CAPTAB
.. note:: When turned on, the SPICE simulation runtime may increase.
Simulation Accuracy
```````````````````
.. option:: <accuracy type="<string>" value="<float>"/>``
Specify the simulation steps (accuracy) to be used
- ``type="abs|frac"``
Specify the type of transient step in SPICE simulation.
* When ``abs`` is selected, the accuracy should be the absolute value, such as ``1e-12``.
* When ``frac`` is selected, the accuracy is the number of simulation points in a clock cycle period, for example, 100.
- ``value="<float>"``
Specify the transient step in SPICE simulation. Typically, the smaller the step is, the higher the accuracy that can be reached while the long simulation runtime is. The recommended accuracy is between 0.1ps and 0.01ps, which generates good accuracy and runtime is not significantly long.
Simulation Speed
````````````````
.. option:: <runtime fast_simulation="<bool>"/>
Specify if any runtime optimization will be applied to the simulator.
- ``fast_simulation="true|false"``
Specify if fast simulation is turned on for the simulator.
If turned on, it will show in the top-level SPICE netlists
.. code-block:: python
.option fast
Monte Carlo Simulation
``````````````````````
.. option:: <monte_carlo num_simulation_points="<int>"/>
Run SPICE simulations in monte carlo mode.
This is mainly for FPGA-SPICE
When turned on, FPGA-SPICE will apply the device variation defined in :ref:`technology_library` to monte carlo simulation
- ``num_simulation_points="<int>"``
Specify the number of simulation points to be considered in monte carlo.
The larger the number is, the longer simulation time will be but more accurate the results will be.
Measurement Setting
```````````````````
- Users can define the parameters in measuring the slew of signals, under XML node ``<slew>``
- Users can define the parameters in measuring the delay of signals, under XML node ``<delay>``
Both delay and slew measurement share the same syntax in defining the upper and lower voltage thresholds.
.. option:: <rise|fall upper_thres_pct="<float>" lower_thres_pct="<float>"/>
Define the starting and ending point in measuring the slew of a rising or a falling edge of a signal.
- ``upper_thres_pct="<float>"`` the ending point in measuring the slew of a rising edge. It is expressed as a percentage of the maximum voltage of a signal. For example, the meaning of upper_thres_pct=0.95 is depicted in :numref:`fig_measure_edge`.
- ``lower_thres_pct="<float>"`` the starting point in measuring the slew of a rising edge. It is expressed as a percentage of the maximum voltage of a signal. For example, the meaning of lower_thres_pct=0.05 is depicted in :numref:`fig_measure_edge`.
.. _fig_measure_edge:
.. figure:: figures/meas_edge.png
:scale: 80%
:alt: map to buried traesure
An illustrative example on measuring the slew and delay of signals
Stimulus Setting
````````````````
Users can define the slew time of input and clock signals to be applied to FPGA I/Os in testbenches under XML node ``<clock>`` and ``<input>`` respectively.
This is used by FPGA-SPICE in generating testbenches
.. option:: <rise|fall slew_type="<string>" slew_time="<float>"/>
Specify the slew rate of an input or clock signal at rising or falling edge
- ``slew_type="[abs|frac]"`` specify the type of slew time definition at the rising or falling edge of a lock/input port.
* The type of ``abs`` implies that the slew time is the absolute value. For example, ``slew_type="abs" slew_time="20e-12"`` means that the slew of a clock signal is 20ps.
* The type of ``frac`` means that the slew time is related to the period (frequency) of the clock signal. For example, ``slew_type="frac" slew_time="0.05"`` means that the slew of a clock signal takes 5% of the period of the clock.
- ``slew_time="<float>"`` specify the slew rate of an input or clock signal at the rising/falling edge.
:numref:`fig_measure_edge` depicts the definition of the slew and delays of signals and the parameters that can be supported by FPGA-SPICE.

146
docs/source/manual/arch_lang/technology_library.rst Normal file
View File

@ -0,0 +1,146 @@
.. _technology_library:
Technology library
------------------
For OpenFPGA using VPR7
~~~~~~~~~~~~~~~~~~~~~~~
.. code-block:: xml
<tech_lib lib_type=”string” transistor_type=”string” lib_path=”string” nominal_vdd=”float”/>
* **lib_type:** can be either industry or academia [industry|academia]. For the industry library, some transistor types are available, and the type of transistor should be declared in the property transistor_type.
* **transistor_type:** This XML property specify the transistors to be used in the industry library. For example, the type of transistors can be “TT”, “FF” etc.
* **lib_path:** specify the path of the library. For example: lib_path=/home/tech/45nm.pm.
* **nominal_vdd:** specify the working voltage for the technology. The voltage will be used as the supply voltage in all the SPICE netlist.
.. code-block:: xml
<transistors pn_ratio=”float” model_ref=”string”/>
* **pn_ratio:** specify the ratio between p-type transistors and n-type transistors. The ratio will be used when building circuit structures such as inverters, buffers, etc.
* **model_ref:** specify the reference of in calling a transistor model. In SPICE netlist, define a transistor follows the convention: <model_ref><trans_name> <ports> <model_name>. The reference depends on the technology and the type of library. For example, the PTM bulk model uses “M” as the reference while the PTM FinFET model uses “X” as the reference.
.. code-block:: xml
<nmos model_name=”string” chan_length=”float” min_width=”float”/>
<pmos model_name=”string” chan_length=”float” min_width=”float”/>
* **model_name:** specify the name of the p/n type transistor, which can be found in the manual of the technology provider.
* **chan_length:** specify the channel length of p/n type transistor.
* **min_width:** specify the minimum width of p/n type transistor. This parameter will be used in building inverter, buffer, etc. as a base number for transistor sizing.
For OpenFPGA using VPR8
~~~~~~~~~~~~~~~~~~~~~~~
Technology library aims to describe transistor-level parameters to be applied to the physical design of FPGAs. In addition to transistor models, technology library also supports the definition of process variations on any transistor models.
General organization is as follows.
.. code-block:: xml
<technology_library>
<device_library>
<device_model name="<string>" type="<string>">
<lib type="<string>" corner="<string>" ref="<string>" path="<string>"/>
<design vdd="<float>" pn_ratio="<float>"/>
<pmos name="<string>" chan_length="<float>" min_width="<float>" variation="<string>"/>
<nmos name="<string>" chan_length="<float>" min_width="<float>" variation="<string>"/>
<rram rlrs="<float>" rhrs="<float>" variation="<string>"/>
</device_model>
</device_library>
<variation_library>
<variation name="<string>" abs_deviation="<float>" num_sigma="<int>"/>
</variation_library>
</technology_library>
Device Library
^^^^^^^^^^^^^^
Device library contains detailed description on device models, such as transistors and Resistive Random Access Memories (RRAMs).
A device library may consist of a number of ``<device_model>`` and each of them denotes a different transistor model.
A device model represents a transistor/RRAM model available in users' technology library.
.. option:: <device_model name="<string>" type="<string>">
Specify the name and type of a device model
- ``name="<string>"`` is the unique name of the device model in the context of ``<device_library>``.
- ``type="transistor|rram"`` is the type of device model in terms of functionality
Currently, OpenFPGA supports two types: transistor and RRAM.
.. note:: the name of ``<device_model>`` may not be the name in users' technology library.
.. option:: <lib type="<string>" corner="<string>" ref="<string>" path="<string>"/>
Specify the technology library that defines the device model
- ``type="academia|industry"`` For the industry library, FPGA-SPICE will use ``.lib <lib_file_path>`` to include the library file in SPICE netlists. For academia library, FPGA-SPICE will use ``.include <lib_file_path>`` to include the library file in SPICE netlists
- ``corner="<string>"`` is the process corner name available in technology library.
For example, the type of transistors can be ``TT``, ``SS`` and ``FF`` *etc*.
- ``ref="<string>"`` specify the reference of in calling a transistor model. In SPICE netlists, define a transistor follows the convention:
.. code-block:: xml
<model_ref><trans_name> <ports> <model_name>
The reference depends on the technology and the type of library. For example, the PTM bulk model uses “M” as the reference while the PTM FinFET model uses “X” as the reference.
- ``path="<string>"`` specify the path of the technology library file. For example:
.. code-block:: xml
lib_path=/home/tech/45nm.pm.
.. option:: <design vdd="<float>" pn_ratio="<float>"/>
Specify transistor-level design parameters
- ``vdd="<float>"`` specify the working voltage for the technology. The voltage will be used as the supply voltage in all the SPICE netlists.
- ``pn_ratio="<float>"`` specify the ratio between *p*-type and *n*-type transistors. The ratio will be used when building circuit structures such as inverters, buffers, etc.
.. option:: <pmos|nmos name="<string>" chan_length="<float>" min_width="<float>" variation="<string>"/>
Specify device-level parameters for transistors
- ``name="<string>"`` specify the name of the p/n type transistor, which can be found in the manual of the technology provider.
- ``chan_length="<float>"`` specify the channel length of *p/n* type transistor.
- ``min_width="<float>"`` specify the minimum width of *p/n* type transistor. This parameter will be used in building inverter, buffer, *etc*. as a base number for transistor sizing.
- ``variation="<string>"`` specify the variation name defined in the ``<variation_library>``
.. option:: <rram rlrs="<float>" rhrs="<float>" variation="<string>"/>
Specify device-level parameters for RRAMs
- ``rlrs="<float>"`` specify the resistance of Low Resistance State (LRS) of a RRAM device
- ``rhrs="<float>"`` specify the resistance of High Resistance State (HRS) of a RRAM device
- ``variation="<string>"`` specify the variation name defined in the ``<variation_library>``
Variation Library
^^^^^^^^^^^^^^^^^
Variation library contains detailed description on device variations specified by users.
A variation library may consist of a number of ``<variation>`` and each of them denotes a different variation parameter.
.. option:: <variation name="<string>" abs_deviation="<float>" num_sigma="<int>"/>
Specify detail variation parameters
- ``name="<string>"`` is the unique name of the device variation in the context of ``<variation_library>``. The name will be used in ``<device_model>`` to bind variations
- ``abs_variation="<float>"`` is the absolute deviation of a variation
- ``num_sigma="<int>"`` is the standard deviation of a variation

7
docs/source/manual/fpga_bitstream/fabric_dependent_bitstream.rst Normal file
View File

@ -0,0 +1,7 @@
Fabric-dependent Bitstream
~~~~~~~~~~~~~~~~~~~~~~~~~~
Fabric-dependent bitstream is design to be loadable to the configuration protocols of FPGAs.
The bitstream just sets an order to the configuration bits in the database, without duplicating the database.
OpenFPGA framework provides a fabric-dependent bitstream generator which is aligned to our Verilog netlists.
The fabric-dependent bitstream can be found in autogenerated Verilog testbenches.

25
docs/source/fpga_bitstream/file_organization.rst → docs/source/manual/fpga_bitstream/generic_bitstream.rst
View File

@ -1,9 +1,24 @@
Bistream Output File Format
============================
Generic Bitstream
~~~~~~~~~~~~~~~~~
Usage
`````
Generic bitstream is a fabric-independent bitstream where configuration bits are organized out-of-order in a database.
This can be regarded as a raw bitstream used for
- ``debugging``: Hardware engineers can validate if their configuration memories across the FPGA fabric are assigned to expected values
- ``an exchangeable file format for bitstream assembler``: Software engineers can use the raw bitstream to build a bitstream assembler which organize the bitstream in the loadable formate to FPGA chips.
- ``creation of artificial bitstream``: Test engineers can craft artificial bitstreams to test each element of the FPGA fabric, which is typically not synthesizable by VPR.
.. note:: The fabric-independent bitstream cannot be directly loaded to FPGA fabrics
File Format
```````````
OpenFPGA can output the generic bitstream to an XML format, which is easy to debug. As shown in the following XML code, configuration bits are organized block by block, where each block could be a LUT, a routing multiplexer `etc`. Each ``bitstream_block`` includes two sets of information:
FPGA-Bitstream can generate two types of bitstreams:
* Generic bitstreams, where configuration bits are organized out-of-order in a database. We output the generic bitstream to a XML format, which is easy to debug. As shown in the following XML code, configuration bits are organized block by block, where each block could be a LUT, a routing multiplexer `etc`. Each ``bitstream_block`` includes two sets of information:
- ``hierarchy`` represents the location of this block in FPGA fabric.
- ``bitstream`` represents the configuration bits affiliated to this block.
.. code-block:: xml
@ -34,5 +49,3 @@ FPGA-Bitstream can generate two types of bitstreams:
<bit memory_port="mem_out[15]" value="0"/>
</bitstream>
</bitstream_block>
* Fabric-dependent bitstreams, where configuration bits are organized to be loadable to the configuration protocols of FPGAs. The bitstream just sets an order to the configuration bits in the database, without duplicating the database. OpenFPGA framework provides a fabric-dependent bitstream generator which is aligned to our Verilog netlists. The fabric-dependent bitstream can be found in autogenerated Verilog testbenches.

14
docs/source/manual/fpga_bitstream/index.rst Normal file
View File

@ -0,0 +1,14 @@
FPGA-Bitstream
--------------
FPGA-Bitstream can generate two types of bitstreams:
.. _fpga_bitstream:
FPGA-Bitstream
.. toctree::
:maxdepth: 2
generic_bitstream
fabric_dependent_bitstream

4
docs/source/fpga_spice/command_line_usage.rst → docs/source/manual/fpga_spice/command_line_usage.rst
View File

@ -1,5 +1,5 @@
Command-line Options for FPGA SPICE Generator
=================================================
Command-line Options
~~~~~~~~~~~~~~~~~~~~
All the command line options of FPGA-SPICE can be shown by calling the help menu of VPR. Here are all the FPGA-SPICE-related options that you can find:
FPGA-SPICE Supported Options::

2
docs/source/fpga_spice/customize_subckt.rst → docs/source/manual/fpga_spice/customize_subckt.rst
View File

@ -1,5 +1,5 @@
Create Customized SPICE Modules
===============================
-------------------------------
To make sure the customized SPICE netlists can be correctly included in FPGA-SPICE, the following rules should be fully respected:
1. The customized SPICE netlists could contain multiple sub-circuits but the names of these sub-circuits should not be conflicted with any reserved words.. Here is an example of defining a sub-circuit in SPICE netlists. The <subckt_name> should be a unique one, which should not be conflicted with any reserved words.

2
docs/source/fpga_spice/file_organization.rst → docs/source/manual/fpga_spice/file_organization.rst
View File

@ -1,5 +1,5 @@
Hierarchy of SPICE Output Files
===============================
-------------------------------
All the generated SPICE netlists are located in the <spice_dir> as you specify in the command-line options.
Under the <spice_dir>, FPGA-SPICE creates a number of folders: include, subckt, lut_tb, dff_tb, grid_tb, pb_mux_tb, cb_mux_tb, sb_mux_tb, top_tb, results. Under the <spice_dir>, FPGA-SPICE also creates a shell script called run_hspice_sim.sh, which run all the simulations for all the testbenches.

18
docs/source/manual/fpga_spice/index.rst Normal file
View File

@ -0,0 +1,18 @@
.. _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
.. toctree::
:maxdepth: 2
command_line_usage
file_organization
spice_simulation
customize_subckt

2
docs/source/fpga_spice/spice_simulation.rst → docs/source/manual/fpga_spice/spice_simulation.rst
View File

@ -1,5 +1,5 @@
Run SPICE simulation
====================
--------------------
* Simulation results

132
docs/source/manual/fpga_verilog/fabric_netlist.rst Normal file
View File

@ -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!

BIN
docs/source/manual/fpga_verilog/figures/fabric_netlist_hierarchy.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 48 KiB

BIN
docs/source/manual/fpga_verilog/figures/generic_fabric.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 118 KiB

BIN
docs/source/manual/fpga_verilog/figures/preconfig_module.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 26 KiB

BIN
docs/source/manual/fpga_verilog/figures/verilog_testbench_hierarchy.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 31 KiB

BIN
docs/source/manual/fpga_verilog/figures/verilog_testbench_organization.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 284 KiB

12
docs/source/manual/fpga_verilog/index.rst Normal file
View File

@ -0,0 +1,12 @@
FPGA-Verilog
------------
.. _fpga_verilog:
FPGA-Verilog
.. toctree::
:maxdepth: 2
fabric_netlist
testbench

94
docs/source/manual/fpga_verilog/testbench.rst Normal file
View File

@ -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

18
docs/source/manual/index.rst Normal file
View File

@ -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

12
docs/source/manual/openfpga_flow/index.rst Normal file
View File

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

0
docs/source/run_fpga_flow.rst → docs/source/manual/openfpga_flow/run_fpga_flow.rst
View File

0
docs/source/run_fpga_task.rst → docs/source/manual/openfpga_flow/run_fpga_task.rst
View File

14
docs/source/manual/openfpga_shell/index.rst Normal file
View File

@ -0,0 +1,14 @@
OpenFPGA Shell
--------------
.. _openfpga_shell:
OpenFPGA Shell
.. toctree::
:maxdepth: 2
launch_openfpga_shell
openfpga_script
openfpga_commands

23
docs/source/manual/openfpga_shell/launch_openfpga_shell.rst Normal file
View File

@ -0,0 +1,23 @@
.. _launch_openfpga_shell:
Launch OpenFPGA Shell
---------------------
OpenFPGA employs a shell-like user interface, in order to integrate all the tools in a well-modularized way.
Currently, OpenFPGA shell is an unified platform to call ``vpr``, ``FPGA-Verilog``, ``FPGA-Bitstream``, ``FPGA-SDC`` and ``FPGA-SPICE``.
To launch OpenFPGA shell, users can choose two modes.
.. option:: --interactive or -i
Launch OpenFPGA in interactive mode where users type-in command by command and get runtime results
.. warning:: Currently OpenFPGA does not support continued lines and comments
.. option:: --file or -f
Launch OpenFPGA in script mode where users write commands in scripts and FPGA will execute them
.. option:: --help or -h
Show the help desk

280
docs/source/manual/openfpga_shell/openfpga_commands.rst Normal file
View File

@ -0,0 +1,280 @@
.. _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 file about architecture description (see details in :ref:`arch_generality`)
- ``--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:: 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
.. option:: write_openfpga_simulation_setting
Write the OpenFPGA XML simulation settings 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
.. option:: 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).
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
.. _openfpga_verilog_commands:
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
- ``--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
.. 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
- ``--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
FPGA-SDC
~~~~~~~~
.. option:: 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
.. option:: 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
.. option:: 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
.. 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
- ``--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``).

97
docs/source/manual/openfpga_shell/openfpga_script.rst Normal file
View File

@ -0,0 +1,97 @@
.. _openfpga_script_format:
OpenFPGA Script Format
----------------------
OpenFPGA accepts a simplified tcl-like script format.
.. option:: Comments
Any content after a ``#`` will be treated as comments.
Comments will not be executed.
.. note:: comments can be added inline or as a new line. See the example below
.. option:: Continued line
Lines to be continued should be finished with ``\``.
Continued lines will be conjuncted and executed as one line
.. note:: please ensure necessary spaces. Otherwise it may cause command parser fail.
The following is an example.
.. code-block:: python
# Run VPR for the s298 design
vpr ./test_vpr_arch/k6_frac_N10_40nm.xml ./test_blif/and.blif --clock_modeling route #--write_rr_graph example_rr_graph.xml
# Read OpenFPGA architecture definition
read_openfpga_arch -f ./test_openfpga_arch/k6_frac_N10_40nm_openfpga.xml
# Write out the architecture XML as a proof
#write_openfpga_arch -f ./arch_echo.xml
# Annotate the OpenFPGA architecture to VPR data base
link_openfpga_arch --activity_file ./test_blif/and.act \
--sort_gsb_chan_node_in_edges #--verbose
# Check and correct any naming conflicts in the BLIF netlist
check_netlist_naming_conflict --fix --report ./netlist_renaming.xml
# Apply fix-up to clustering nets based on routing results
pb_pin_fixup --verbose
# Apply fix-up to Look-Up Table truth tables based on packing results
lut_truth_table_fixup #--verbose
# Build the module graph
# - Enabled compression on routing architecture modules
# - Enable pin duplication on grid modules
build_fabric --compress_routing \
--duplicate_grid_pin #--verbose
# 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
repack #--verbose
# Build the bitstream
# - Output the fabric-independent bitstream to a file
build_architecture_bitstream --verbose \
--file /var/tmp/xtang/openfpga_test_src/fabric_indepenent_bitstream.xml
# Build fabric-dependent bitstream
build_fabric_bitstream --verbose
# Write the Verilog netlist for FPGA fabric
# - Enable the use of explicit port mapping in Verilog netlist
write_fabric_verilog --file /var/tmp/xtang/openfpga_test_src/SRC \
--explicit_port_mapping \
--include_timing \
--include_signal_init \
--support_icarus_simulator \
--print_user_defined_template \
--verbose
# Write the Verilog testbench for FPGA fabric
# - We suggest the use of same output directory as fabric Verilog netlists
# - Must specify the reference benchmark file if you want to output any testbenches
# - Enable top-level testbench which is a full verification including programming circuit and core logic of FPGA
# - Enable pre-configured top-level testbench which is a fast verification skipping programming phase
# - Simulation ini file is optional and is needed only when you need to interface different HDL simulators using openfpga flow-run scripts
write_verilog_testbench --file /var/tmp/xtang/openfpga_test_src/SRC \
--reference_benchmark_file_path /var/tmp/xtang/and.v \
--print_top_testbench \
--print_preconfig_top_testbench \
--print_simulation_ini /var/tmp/xtang/openfpga_test_src/simulation_deck.ini
# Write the SDC files for PnR backend
# - Turn on every options here
write_pnr_sdc --file /var/tmp/xtang/openfpga_test_src/SDC
# Write the SDC to run timing analysis for a mapped FPGA fabric
write_analysis_sdc --file /var/tmp/xtang/openfpga_test_src/SDC_analysis
# Finish and exit OpenFPGA
exit

84
docs/source/motivation.rst
View File

@ -1,8 +1,62 @@
Motivation
==========
Why OpenFPGA?
-------------
OpenFPGA aims to be an open-source framework that enables rapid prototyping of customizable FPGA architectures. As shown in :numref:`fig_openfpga_motivation`, a conventional approach will take a large group of experienced engineers more than one year to achieve production-ready layout and assoicated CAD tools. In fact, most of the engineering efforts are spent on manual layouts and developing ad-hoc CAD support.
.. _fig_openfpga_motivation:
.. figure:: ./figures/openfpga_motivation.png
:scale: 50%
:alt: OpenFPGA: a fast prototyping framework for customizable FPGAs
Comparison on engineering time and effort to prototype an FPGA using OpenFPGA and conventional approaches
Using OpenFPGA, the development cycle in both hardware and software can be significantly accelerated. OpenFPGA can automatically generate Verilog netlists describing a full FPGA fabric based on an XML-based description file. Thanks to modern semi-custom design tools, production-ready layout generation can be achieved within 24 hours. To help sign-off, OpenFPGA can auto-generate Verilog testbenches to validate the correctness of FPGA fabric using modern verification tools.
OpenFPGA also provides native bitstream generation support based the same XML-based description file used in Verilog generation. This avoid the recurring engineering in developing CAD tools for different FPGAs. Once the FPGA architecture is finalized, the CAD tool is ready to use.
OpenFPGA can support any architecture that VPR can describe, covering most of the architecture enhancements available in modern FPGAs, and hence unlocks a large design space in prototyping customizable FPGAs. In addition, OpenFPGA provides enriched syntax which allows users to customized primitive circuit designed downto transistor-level parameters. This helps developers to customize the P.P.A. (Power, Performance and Area) to the best. All these features open the door of prototyping/studying flexible FPGAs to a small group of junior engineers or researchers.
In terms of tool functionality, OpenFPGA consists of the following parts: FPGA-Verilog, FPGA-SDC, FPGA-Bitstream and FPGA-SPICE.
The rest of this section will focus on detailed motivation on each of them, as depicted in :numref:`fig_openfpga_flow`.
.. _fig_openfpga_flow:
.. figure:: ./figures/openfpga_flow.png
:scale: 50%
:alt: Design flows avaiable in OpenFPGA
Design flows in different purposes using OpenFPGA
FPGA-Verilog
~~~~~~~~~~~~
Driven by the strong need in data processing applications, Field Programmable Gate Arrays (FPGAs) are playing an ever-increasing role as programmable accelerators in modern
computing systems. To fully unlock processing capabilities for domain-specific applications, FPGA architectures have to be tailored for seamless cooperation with other computing resources. However, prototyping and bringing to production a customized FPGA is a costly and complex endeavor even for industrial vendors. OpenFPGA, an opensource framework, aims to rapid prototype of customizable FPGA architectures through a semi-custom design approach. We propose an XML-to-Prototype design flow, where the Verilog netlists of a full FPGA fabric can be autogenerated using an extension of the XML language from the VTR framework and then fed into a back-end flow to generate production-ready layouts.
The technical details can be found in our TVLSI'19 paper :cite:`XTang_TVLSI_2019` and FPL'19 paper :cite:`XTang_FPL_2019`.
FPGA-SDC
~~~~~~~~
Design constraints are indepensible in modern ASIC design flows to guarantee the performance level.
OpenFPGA includes a rich SDC generator in the OpenFPGA framework to deal with both PnR constraints and sign-off timing analysis.
Our flow automatically generates two sets of SDC files. The first set of SDC is designed for the P&R flow, where all the combinational loops are broken to enable wellcontrolled timing-driven P&R. In addition, there are SDC files devoted to constrain pin-to-pin timing for all the resources in FPGAs, in order to obtain nicely constrained and homogeneous delays across the fabric. The second set of SDC is designed for the timing analysis of a benchmark at the post P&R stage.
The technical details can be found in our FPL'19 paper :cite:`XTang_FPL_2019`.
FPGA-Bitstream
~~~~~~~~~~~~~~
EDA support is essential for end-users to implement designs on a customized FPGA. OpenFPGA provides a general-purpose bitstream generator FPGA-Bitstream for any architecture that can be described by VPR. As the native CAD tool for any customized FPGA that is produced by FPGA-Verilog, FPGA-Bitstream is ready to use once users finalize the XML-based architecture description file. This eliminates the huge engineering efforts spent on developing bitstream generator for customized FPGAs.
Using FPGA-Bitstream, users can launch (1) Verilog-to-Bitstream flow. This is the typical implementation flow for end-users; (2) Verilog-to-Verification flow. OpenFPGA can output Verilog testbenches with self-testing features to validate users' implemetations on their customized FPGA fabrics.
The technical details can be found in our TVLSI'19 paper :cite:`XTang_TVLSI_2019` and FPL'19 paper :cite:`XTang_FPL_2019`.
FPGA-SPICE
----------
~~~~~~~~~~
The built-in timing and power analysis engines of VPR are based on analytical models :cite:`VBetz_Book_1999,JGoeders_FPT_2012`. Analytical model-based analysis can promise accuracy only on a limited number of circuit designs for which the model is valid. As the technology advancements create more opportunities on circuit designs and FPGA architectures, the analytical power model require to be updated to follow the new trends. However, without referring to simulation results, the analytical power models cannot prove their accuracy. SPICE simulators have the advantages of generality and accuracy over analytical models. For this reason, SPICE simulation results are often selected to check the accuracy of analytical models. Therefore, there is a strong need for a simulation-based power analysis approach for FPGAs, which can support general circuit designs.
@ -11,28 +65,4 @@ FPGA-SPICE aims at generating SPICE netlists and testbenches for the FPGA archit
SPICE modeling for FPGA architectures requires detailed transistor-level modeling for all the circuit elements within the considered FPGA architecture. However, current VPR architectural description language :cite:`JLuu_FPGA_2011` does not offer enough transistor-level parameters to model the most common circuit modules, such as multiplexers and LUTs. Therefore, we develop an extension on the VPR architectural description language to model the transistor-level circuit designs.
In this manual, we will introduce how to use FPGA-SPICE to conduct an accurate power analysis. First, we give an overview of the design flow of FPGA-SPICE-based tool suites. Then, we show the command-line options of FPGA-SPICE. Afterward, we introduce the extension of architectural language and the transistor-level design supports. Finally, we present how to simulate the generated SPICE netlists and testbenches.
In the appendix, we introduce the hierarchy of the generated SPICE netlists and testbenches, to help you customize the SPICE netlists. We also attach an example of an architecture XML file for your interest.
The technical details can be found in our ICCD’15 paper :cite:`XTang_ICCD_2015` and TVLSI'19 paper :cite:`XTang_TVLSI_2019`.
FPGA-Verilog
------------
On a second note, it is becoming more and more necessary to have fast access to the Verilog code of the structures and architectures researchers want to study. We think that some issues cannot be studies through VPR only and a complete overview is possible through a more extensive workflow. One of the prerequisites for this is the generation of the Verilog which enables Place & Route and Signoff analysis. While VPR allows the researcher to have access to fast results if the characteristics of the system are well known by the user, it is quite limited otherwise. In the same way, it is quite hard to study the same architecture across multiple technology nodes without substantial knowledge of it.
This motivates us to generate the Verilog code of the architecture to enable a second level of research concerning the architectures to be explored. This Verilog code encompasses the whole design and is divided into multiple sub-directories for targetted analysis or a global one. This is left to the choice of the user.
In this manual, we present FPGA-Verilog. This extension enables the generation of a fully functional Verilog code enabling a deeper understanding of the architectures of the FPGAs. We introduce different options to this module to do the verification of the system. This will be presented in more depth in the FPGA-Bitstream section.
The technical details can be found in our TVLSI'19 paper :cite:`XTang_TVLSI_2019` and FPL'19 paper :cite:`XTang_FPL_2019`.
FPGA-Bitstream
--------------
To have the right functionality on top of the FPGA generated, it is necessary to have a Bitstream generation which programs the FPGA. For this reason, we generate a Bitstream and some testbenches in parallel which allow the user to do some functional verification of the system to make sure that the functionality is respected. This includes three different testbenches. First, the FPGA is configured then the clock runs with random patterns are generated to test the functionality. Secondly, the FPGA can be configured in parallel to the testbench itself to do a comparison of the signals and check the validity. Finally, the configuration can be skipped to directly have access to the functioning of the system and reduce the processing time.
This will be explained in more depth in the FPGA-Bitstream section.
The technical details can be found in our TVLSI'19 paper :cite:`XTang_TVLSI_2019` and FPL'19 paper :cite:`XTang_FPL_2019`.

BIN
docs/source/tutorials/arch_modeling/figures/k4n4_arch.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 70 KiB

10
docs/source/tutorials/arch_modeling/index.rst Normal file
View File

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

549
docs/source/tutorials/arch_modeling/quick_start.rst Normal file
View File

@ -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`.

71
docs/source/tutorials/compile.rst Normal file
View File

@ -0,0 +1,71 @@
.. _compile:
How to Compile
--------------
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
mkdir build
cd build
cmake .. -DCMAKE_BUILD_TYPE=debug
make
.. note:: OpenFPGA requires gcc/g++ version >5
.. note:: cmake3.12+ is recommended to compile OpenFPGA with GUI
.. note:: recommand to use ``make -j`` to accelerate the compilation
**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
Dependencies
~~~~~~~~~~~~
Full list of dependencies can be found at travis_setup_link_
In particular, OpenFPGA requires specific versions for the following dependencies:
:cmake:
version >3.12 for graphical interface
:iverilog:
version 10.1+ is required to run Verilog-to-Verification flow
.. _travis_setup_link: https://github.com/LNIS-Projects/OpenFPGA/blob/0cfb88a49f152aab0a06f309ff160f222bb51ed7/.travis.yml#L34
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
.. note:: This command is for quick testing. If you want to conserve your work, you should certainly use other options, such as ``-v``.
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
For more information about dock, see dock_download_link_
.. _dock_download_link: https://www.docker.com/products/docker-desktop
To build the tool, go in the OpenFPGA folder and follow the compilation steps
.. note:: Using docker, you cannot use ``make -j``, errors will happen

157
docs/source/tutorials/design_flow/blif_to_verification.rst Normal file
View File

@ -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.

0
docs/source/fpga_verilog/figures/Layout_Diagram.png → docs/source/tutorials/design_flow/figures/Layout_Diagram.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 132 KiB

After

Width:  |  Height:  |  Size: 132 KiB

0
docs/source/fpga_verilog/figures/fpga_asap_10x10_final.png → docs/source/tutorials/design_flow/figures/fpga_asap_10x10_final.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 148 KiB

After

Width:  |  Height:  |  Size: 148 KiB

0
docs/source/fpga_verilog/figures/fpga_asap_10x10_floorplan.png → docs/source/tutorials/design_flow/figures/fpga_asap_10x10_floorplan.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 362 KiB

After

Width:  |  Height:  |  Size: 362 KiB

12
docs/source/tutorials/design_flow/index.rst Normal file
View File

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

4
docs/source/fpga_verilog/sc_flow.rst → docs/source/tutorials/design_flow/verilog_to_gds2.rst
View File

@ -1,5 +1,5 @@
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.

Some files were not shown because too many files have changed in this diff Show More