From 1fe1daf87838c08136321c309edf457fc6222330 Mon Sep 17 00:00:00 2001 From: coolbreeze413 Date: Mon, 14 Dec 2020 12:30:44 +0530 Subject: [PATCH 1/8] replace markdown with rst readme --- README.md | 194 --------------------------------------- README.rst | 261 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 261 insertions(+), 194 deletions(-) delete mode 100644 README.md create mode 100644 README.rst diff --git a/README.md b/README.md deleted file mode 100644 index fd5ba0b..0000000 --- a/README.md +++ /dev/null @@ -1,194 +0,0 @@ -# Quicklogic FPGA Toolchain -Contains SymbiFlow toolchain release packages for Quicklogic FPGAs - -This guide describes everything you need to set up your system to develop for QuickLogic FPGA Toolchain. -Currently, the SymbiFlow Installer runs only on Linux 64bit. - -Below are some ways to run SymbiFlow: -1) Run an installer and follow the instructions to run an example -2) Compile from source code and run example -3) Run SymbiFlow in a container - -## 1) Run an installer and follow instructions to run example - -Download [Symbiflow_v1.3.0](https://github.com/QuickLogic-Corp/quicklogic-fpga-toolchain/releases/download/v1.3.0/Symbiflow_v1.3.0.gz.run) - -This package installs these toolchains : - -- Yosys -- Yosys-Plugins -- VTR -- iverilog -- Architecture definitions installation - - -```bash -#To Install -export INSTALL_DIR="specify the installpath" -bash Symbiflow_v1.3.0.gz.run - -#To Run example -export INSTALL_DIR="specify the installpath" -export PATH="$INSTALL_DIR/quicklogic-arch-defs/bin:$INSTALL_DIR/quicklogic-arch-defs/bin/python:$PATH" -source "$INSTALL_DIR/conda/etc/profile.d/conda.sh" -conda activate - -#Execute the help command to display the help -ql_symbiflow -h -``` - -## Run Example Design - -The example designs are provided in separate directories at $INSTALL_DIR/quicklogic-arch-defs/tests: - -1. `counter_16bit` - simple 16-bit up-counter. The design targets the the device ql-eos-s3 and package PD64. - -To run the examples, run following commands: -```bash -cd $INSTALL_DIR/quicklogic-arch-defs/tests/counter_16bit -ql_symbiflow -compile -d ql-eos-s3 -P pd64 -v counter_16bit.v -t top -p chandalar.pcf - -``` -For more details on the symbiflow options refer the tutorial guide: -[Symbiflow_Tutorial](https://quicklogic-fpga-tool-docs.readthedocs.io/en/latest/index.html) - -For details on the usage of RAM, FIFO and Multiplier blocks, refer to the following document: -[Ram_Fifo_Mult_User_Document](https://quicklogic-fpga-tool-docs.readthedocs.io/en/latest/ram/S3BDeviceHardmacroResources.html) - -## 2) Compile from source code and run example - -This release package contains the following GitHub repositories that are compiled to create this package. Note: Refer the repositories read.md pages for the prerequisites to build. - -You may use the following command to get the source, compile and install it: -```bash -#Checkout *yosys* repository (https://github.com/QuickLogic-Corp/yosys.git), branch: **quicklogic-rebased**. -git clone https://github.com/QuickLogic-Corp/yosys.git -b quicklogic-rebased quicklogic-yosys -cd quicklogic-yosys -#compiling using gcc -make config-gcc -make install PREFIX='specify installation path' -cd - - -#Checkout *yosys-symbiflow-plugins* (https://github.com/QuickLogic-Corp/yosys-symbiflow-plugins), branch: **ql-ios**. -git clone https://github.com/QuickLogic-Corp/yosys-symbiflow-plugins -b ql-ios -cd yosys-symbiflow-plugins -export PATH='specify Yosys installation path as specified in PREFIX in previous step':$PATH -make install -cd - - -#Checkout *vpr* repository (https://github.com/SymbiFlow/vtr-verilog-to-routing.git), branch: **master**. -git clone https://github.com/SymbiFlow/vtr-verilog-to-routing -b master -cd vtr-verilog-to-routing -make - -#Checkout *symbiflow-arch-defs* repository (https://github.com/QuickLogic-Corp/symbiflow-arch-defs.git), branch: **quicklogic-upstream-rebase**. -git clone https://github.com/QuickLogic-Corp/symbiflow-arch-defs.git -b quicklogic-upstream-rebase -export YOSYS='path to Yosys binary, installed in first step' -export VPR='path to vpr binary built' -export GENFASM='path to genfasm binary built' -cd symbiflow-arch-defs -make env -cd build -make all_conda - -#Run any test case in the current terminal window. For example, follow these steps to run a test case: -cd quicklogic/pp3/tests/quicklogic_testsuite/bin2seven -make bin2seven-ql-chandalar_fasm -``` -## 3) Run SymbiFlow in a container - -Containers provide isolated environments, similar to VMs, but lighter weight, and with performance closer to the native machine they run on. Containers start quickly from an efficient layered image which provides an identical environment each time the container starts. A great place to start is the Docker website, which provides links to tutorials and documentation: - -https://www.docker.com/why-docker - -This project uses containers to build Symbiflow automatically whenever a change is pushed to Quicklogic/quicklogic-fpga-toolchain. With each successful build, a container image is pushed as a github package, and may be pulled or run directly by a container runtime such as Docker. Such images are useful for developing continuous integration of FPGA projects. The act of building and testing them automatically through github actions also provides assurances that what is checked into the github source repositories can be built and executed. Below are some of the options for using containers to run or build SymbiFlow for Quicklogic development. - -### Option A) Build a container image locally from Dockerfile.use-installer - -The Dockerfile.use-installer in this repo builds a SymbiFlow container from a released installer. -You can build and tag the symbiflow-ql container with: -``` -docker build . -f Dockerfile.use-installer -t symbiflow-ql -``` -In order to view the gtkwave program, the easiest (but not the safest) thing to do is allow x connections: -``` -xhost + - -docker run -it -e DISPLAY=$DISPLAY -v "/tmp/.X11-unix:/tmp/.X11-unix" symbiflow-ql bash - -or run a prebuilt container automatically built from the installer by github actions: - -docker run -it -e DISPLAY=$DISPLAY -v "/tmp/.X11-unix:/tmp/.X11-unix" docker.pkg.github.com/thirsty2/quicklogic-fpga-toolchain/symbiflow-ql:1.2.0.0 bash -``` -Inside your running docker container, try some of the commands from the tutorial: -[Symbiflow_Tutorial](https://quicklogic-fpga-tool-docs.readthedocs.io/en/latest/index.html) -``` -source "$INSTALL_DIR/conda/etc/profile.d/conda.sh" -conda activate - -#Execute the help command to display the help -ql_symbiflow -h - -cd $INSTALL_DIR/quicklogic-arch-defs/tests/counter_16bit - -# Use iverilog to simulate the design -iverilog -o my_design counter_16bit.v counter_16bit_tb.v -vvp my_design - -# use gtkwave to view the results (assumes you have allowed x connections, and have an xserver running) -gtkwave counter_16bit_tb.vcd - -ql_symbiflow -compile -d ql-eos-s3 -P pd64 -v counter_16bit.v -t top -p chandalar.pcf - -``` - -When you are finished, it would be wise to disallow x connections: -``` -xhost - -``` - - -### Option B) Build a container image locally from Dockerfile - -The Dockerfile in this repo builds SymbiFlow from source. You can create and tag a local image with a Docker command like: -``` -docker build . -t symbiflow-ql-slim-buster -``` -Then you can run the container interactively with a docker command like: -``` -docker run -it symbiflow-ql-slim-buster bash -``` -From your bash session in the container, try: -``` -#Run any test case in the current terminal window. For example, follow these steps to run a test case: -cd /symbiflow-arch-defs/build/quicklogic/pp3/tests/quicklogic_testsuite/bin2seven -make bin2seven-ql-chandalar_fasm - -#Or try: -cd /symbiflow-arch-defs/build/quicklogic/pp3/tests -make all_quick_tests -``` - -### Option C) Use a container image that is built automatically by a github action workflow - -See the 'packages' links for the Docker command to pull a Symbiflow container image, or use it as the basis of a new container. - -You can run bash interactively inside of a prebuilt SymbiFlow container using a docker command like this: -``` -docker run -it docker.pkg.github.com/quicklogic-corp/quicklogic-fpga-toolchain/symbiflow-ql-src:latest bash -``` - -From your bash session in the container, try: -``` -#Run any test case in the current terminal window. For example, follow these steps to run a test case: -cd /symbiflow-arch-defs/build/quicklogic/pp3/tests/quicklogic_testsuite/bin2seven -make bin2seven-ql-chandalar_fasm - -#Or try: -cd /symbiflow-arch-defs/build/quicklogic/pp3/tests -make all_quick_tests -``` - - -## Hardware features that are not supported in this release -- IO registers: Usage of IO registers available in the IO block (Hardware) diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..e699c0a --- /dev/null +++ b/README.rst @@ -0,0 +1,261 @@ +Quicklogic FPGA Toolchain +========================= + +Contains SymbiFlow toolchain release packages for Quicklogic FPGAs + +This guide describes everything you need to set up your system to +develop for QuickLogic FPGA Toolchain. Currently, the SymbiFlow +Installer runs only on Linux 64bit. + +Below are some ways to run SymbiFlow: + +1) Run an installer and follow the instructions to run an example +2) Compile from source code and run example +3) Run SymbiFlow in a container + +.. _1-run-an-installer-and-follow-instructions-to-run-example: + +1) Run an installer and follow instructions to run example +---------------------------------------------------------- + +Download +`Symbiflow_v1.3.0 `__ + +This package installs these toolchains : + +- Yosys +- Yosys-Plugins +- VTR +- iverilog +- Architecture definitions installation + +Steps: + +- Install + +:: + + export INSTALL_DIR="specify the installpath" + bash Symbiflow_v1.3.0.gz.run + +- Initialize + +:: + + export INSTALL_DIR="specify the installpath" + export PATH="$INSTALL_DIR/quicklogic-arch-defs/bin:$INSTALL_DIR/quicklogic-arch-defs/bin/python:$PATH" + source "$INSTALL_DIR/conda/etc/profile.d/conda.sh" + conda activate + +- Run help command + +:: + + ql_symbiflow -h + +- Run Example Design + + The example designs are provided in separate directories at :code:`$INSTALL_DIR/quicklogic-arch-defs/tests` : + + 1. :code:`counter_16bit` - simple 16-bit up-counter. The design targets the device ql-eos-s3 and package PD64. + + To run this example, run following commands: + + :: + + cd $INSTALL_DIR/quicklogic-arch-defs/tests/counter_16bit + ql_symbiflow -compile -d ql-eos-s3 -P pd64 -v counter_16bit.v -t top -p chandalar.pcf + +For more details on the symbiflow options refer the tutorial guide: `Symbiflow_Tutorial `_ + +For details on the usage of RAM, FIFO and Multiplier blocks, refer to +the following document: +`Ram_Fifo_Mult_User_Document `_ + + +.. _2-compile-from-source-code-and-run-example: + +2) Compile from source code and run example +------------------------------------------- + +This release package contains the following GitHub repositories that are +compiled to create this package. Note: Refer the repositories read.md +pages for the prerequisites to build. + +You may use the following command to get the source, compile and install +it: + +:: + + #Checkout *yosys* repository (https://github.com/QuickLogic-Corp/yosys.git), branch: **quicklogic-rebased**. + git clone https://github.com/QuickLogic-Corp/yosys.git -b quicklogic-rebased quicklogic-yosys + cd quicklogic-yosys + #compiling using gcc + make config-gcc + make install PREFIX='specify installation path' + cd - + + #Checkout *yosys-symbiflow-plugins* (https://github.com/QuickLogic-Corp/yosys-symbiflow-plugins), branch: **ql-ios**. + git clone https://github.com/QuickLogic-Corp/yosys-symbiflow-plugins -b ql-ios + cd yosys-symbiflow-plugins + export PATH='specify Yosys installation path as specified in PREFIX in previous step':$PATH + make install + cd - + + #Checkout *vpr* repository (https://github.com/SymbiFlow/vtr-verilog-to-routing.git), branch: **master**. + git clone https://github.com/SymbiFlow/vtr-verilog-to-routing -b master + cd vtr-verilog-to-routing + make + + #Checkout *symbiflow-arch-defs* repository (https://github.com/QuickLogic-Corp/symbiflow-arch-defs.git), branch: **quicklogic-upstream-rebase**. + git clone https://github.com/QuickLogic-Corp/symbiflow-arch-defs.git -b quicklogic-upstream-rebase + export YOSYS='path to Yosys binary, installed in first step' + export VPR='path to vpr binary built' + export GENFASM='path to genfasm binary built' + cd symbiflow-arch-defs + make env + cd build + make all_conda + + #Run any test case in the current terminal window. For example, follow these steps to run a test case: + cd quicklogic/pp3/tests/quicklogic_testsuite/bin2seven + make bin2seven-ql-chandalar_fasm + +.. _3-run-symbiflow-in-a-container: + +3) Run SymbiFlow in a container +------------------------------- + +Containers provide isolated environments, similar to VMs, but lighter +weight, and with performance closer to the native machine they run on. +Containers start quickly from an efficient layered image which provides +an identical environment each time the container starts. A great place +to start is the Docker website, which provides links to tutorials and +documentation: + +https://www.docker.com/why-docker + +This project uses containers to build Symbiflow automatically whenever a +change is pushed to Quicklogic/quicklogic-fpga-toolchain. With each +successful build, a container image is pushed as a github package, and +may be pulled or run directly by a container runtime such as Docker. +Such images are useful for developing continuous integration of FPGA +projects. The act of building and testing them automatically through +github actions also provides assurances that what is checked into the +github source repositories can be built and executed. Below are some of +the options for using containers to run or build SymbiFlow for +Quicklogic development. + +.. _option-a-build-a-container-image-locally-from-dockerfileuse-installer: + +Option A) Build a container image locally from Dockerfile.use-installer +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +| The Dockerfile.use-installer in this repo builds a SymbiFlow container + from a released installer. +| You can build and tag the symbiflow-ql container with: + +:: + + docker build . -f Dockerfile.use-installer -t symbiflow-ql + +In order to view the gtkwave program, the easiest (but not the safest) +thing to do is allow x connections: + +:: + + xhost + + + docker run -it -e DISPLAY=$DISPLAY -v "/tmp/.X11-unix:/tmp/.X11-unix" symbiflow-ql bash + + or run a prebuilt container automatically built from the installer by github actions: + + docker run -it -e DISPLAY=$DISPLAY -v "/tmp/.X11-unix:/tmp/.X11-unix" docker.pkg.github.com/thirsty2/quicklogic-fpga-toolchain/symbiflow-ql:1.2.0.0 bash + +Inside your running docker container, try some of the commands from the +tutorial: +`Symbiflow_Tutorial `__ + +:: + + source "$INSTALL_DIR/conda/etc/profile.d/conda.sh" + conda activate + + #Execute the help command to display the help + ql_symbiflow -h + + cd $INSTALL_DIR/quicklogic-arch-defs/tests/counter_16bit + + # Use iverilog to simulate the design + iverilog -o my_design counter_16bit.v counter_16bit_tb.v + vvp my_design + + # use gtkwave to view the results (assumes you have allowed x connections, and have an xserver running) + gtkwave counter_16bit_tb.vcd + + ql_symbiflow -compile -d ql-eos-s3 -P pd64 -v counter_16bit.v -t top -p chandalar.pcf + +When you are finished, it would be wise to disallow x connections: + +:: + + xhost - + +Option B) Build a container image locally from Dockerfile +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The Dockerfile in this repo builds SymbiFlow from source. You can create +and tag a local image with a Docker command like: + +:: + + docker build . -t symbiflow-ql-slim-buster + +Then you can run the container interactively with a docker command like: + +:: + + docker run -it symbiflow-ql-slim-buster bash + +From your bash session in the container, try: + +:: + + #Run any test case in the current terminal window. For example, follow these steps to run a test case: + cd /symbiflow-arch-defs/build/quicklogic/pp3/tests/quicklogic_testsuite/bin2seven + make bin2seven-ql-chandalar_fasm + + #Or try: + cd /symbiflow-arch-defs/build/quicklogic/pp3/tests + make all_quick_tests + +Option C) Use a container image that is built automatically by a github action workflow +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +See the 'packages' links for the Docker command to pull a Symbiflow +container image, or use it as the basis of a new container. + +You can run bash interactively inside of a prebuilt SymbiFlow container +using a docker command like this: + +:: + + docker run -it docker.pkg.github.com/quicklogic-corp/quicklogic-fpga-toolchain/symbiflow-ql-src:latest bash + +From your bash session in the container, try: + +:: + + #Run any test case in the current terminal window. For example, follow these steps to run a test case: + cd /symbiflow-arch-defs/build/quicklogic/pp3/tests/quicklogic_testsuite/bin2seven + make bin2seven-ql-chandalar_fasm + + #Or try: + cd /symbiflow-arch-defs/build/quicklogic/pp3/tests + make all_quick_tests + +Hardware features that are not supported in this release +-------------------------------------------------------- + +- IO registers: Usage of IO registers available in the IO block + (Hardware) From 85e25c325251fdafe27be03594b1d855869cd9cb Mon Sep 17 00:00:00 2001 From: coolbreeze413 Date: Mon, 14 Dec 2020 14:15:27 +0530 Subject: [PATCH 2/8] add dailybuild instructions as a method to install and use the fpga toolchain --- README.rst | 92 ++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 79 insertions(+), 13 deletions(-) diff --git a/README.rst b/README.rst index e699c0a..8122fb7 100644 --- a/README.rst +++ b/README.rst @@ -9,13 +9,23 @@ Installer runs only on Linux 64bit. Below are some ways to run SymbiFlow: -1) Run an installer and follow the instructions to run an example -2) Compile from source code and run example -3) Run SymbiFlow in a container +1) Run an installer and run an example +2) Use the daily build and run an example +3) Compile from source code and run example +4) Run SymbiFlow in a container -.. _1-run-an-installer-and-follow-instructions-to-run-example: -1) Run an installer and follow instructions to run example +For more details on the symbiflow options refer the tutorial guide: `Symbiflow_Tutorial `_ + +For details on the usage of RAM, FIFO and Multiplier blocks, refer to +the following document: +`Ram_Fifo_Mult_User_Document `_ + + + +.. _1-run-an-installer-and-run-an-example: + +1) Run an installer and run an example ---------------------------------------------------------- Download @@ -66,16 +76,72 @@ Steps: cd $INSTALL_DIR/quicklogic-arch-defs/tests/counter_16bit ql_symbiflow -compile -d ql-eos-s3 -P pd64 -v counter_16bit.v -t top -p chandalar.pcf -For more details on the symbiflow options refer the tutorial guide: `Symbiflow_Tutorial `_ -For details on the usage of RAM, FIFO and Multiplier blocks, refer to -the following document: -`Ram_Fifo_Mult_User_Document `_ +.. _2-use-the-daily-build-and-run-an-example: + +2) Use the daily build and run an example +------------------------------------------ + +Steps: + +- Install + +:: + + export INSTALL_DIR="specify the installpath" + wget https://repo.continuum.io/miniconda/Miniconda3-latest-Linux-x86_64.sh -O conda_installer.sh + bash conda_installer.sh -b -p $INSTALL_DIR/conda && rm conda_installer.sh + source "$INSTALL_DIR/conda/etc/profile.d/conda.sh" + echo "include-system-site-packages=false" >> $INSTALL_DIR/conda/pyvenv.cfg + CONDA_FLAGS="-y --override-channels -c defaults -c conda-forge" + conda update $CONDA_FLAGS -q conda + curl $(curl https://storage.googleapis.com/symbiflow-arch-defs-install/latest) > arch.tar.gz + tar -C $INSTALL_DIR -xvf arch.tar.gz && rm arch.tar.gz + conda install $CONDA_FLAGS -c quicklogic-corp/label/ql yosys="0.8.0_0003_e80fb742f_20201208_122808 None" python=3.7 + conda install $CONDA_FLAGS -c quicklogic-corp/label/ql yosys-plugins="1.2.0_0011_g21045a9 None" + conda install $CONDA_FLAGS -c quicklogic-corp/label/ql vtr="v8.0.0_rc2_2894_gdadca7ecf 20201008_140004" + conda install $CONDA_FLAGS -c quicklogic-corp iverilog + conda install $CONDA_FLAGS -c tfors gtkwave + conda install $CONDA_FLAGS make lxml simplejson intervaltree git pip + conda activate + pip install python-constraint + pip install serial + pip install git+https://github.com/QuickLogic-Corp/quicklogic-fasm + conda deactivate + +- Initialize + +:: + + export INSTALL_DIR="specify the installpath" + export PATH="$INSTALL_DIR/quicklogic-arch-defs/bin:$INSTALL_DIR/quicklogic-arch-defs/bin/python:$PATH" + source "$INSTALL_DIR/conda/etc/profile.d/conda.sh" + conda activate + +- Run help command + +:: + + ql_symbiflow -h + +- Run Example Design + + The example designs are provided in separate directories at :code:`$INSTALL_DIR/quicklogic-arch-defs/tests` : + + 1. :code:`counter_16bit` - simple 16-bit up-counter. The design targets the device ql-eos-s3 and package PD64. + + To run this example, run following commands: + + :: + + cd $INSTALL_DIR/quicklogic-arch-defs/tests/counter_16bit + ql_symbiflow -compile -d ql-eos-s3 -P pd64 -v counter_16bit.v -t top -p chandalar.pcf + -.. _2-compile-from-source-code-and-run-example: +.. _3-compile-from-source-code-and-run-example: -2) Compile from source code and run example +3) Compile from source code and run example ------------------------------------------- This release package contains the following GitHub repositories that are @@ -121,9 +187,9 @@ it: cd quicklogic/pp3/tests/quicklogic_testsuite/bin2seven make bin2seven-ql-chandalar_fasm -.. _3-run-symbiflow-in-a-container: +.. _4-run-symbiflow-in-a-container: -3) Run SymbiFlow in a container +4) Run SymbiFlow in a container ------------------------------- Containers provide isolated environments, similar to VMs, but lighter From 3714e8ea9cf7c741012a5b975c777e41d5197ba5 Mon Sep 17 00:00:00 2001 From: coolbreeze413 Date: Tue, 15 Dec 2020 02:04:13 +0530 Subject: [PATCH 3/8] add details on fasm parser change to antlr --- README.rst | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) diff --git a/README.rst b/README.rst index 8122fb7..ed87539 100644 --- a/README.rst +++ b/README.rst @@ -22,6 +22,56 @@ the following document: `Ram_Fifo_Mult_User_Document `_ +**NOTE:** + +While running the compilation with the latest toolchain (v1.3.1 or the daily-build), the following warning would be seen: + +:: + + fasm/fasm/parser/__init__.py:27: RuntimeWarning: + Falling back on slower textX parser implementation: + ImportError: cannot import name 'tags' from 'fasm.parser' (/path/to/toolchain/install/quicklogic-arch-defs/tests/counter_16bit/fasm/fasm/parser/__init__.py) + Please install all dependencies and reinstall with: + pip uninstall + pip install -v fasm + ' pip install -v fasm'.format(e), RuntimeWarning) + ['textx'] + +| This is due to recent changes in the `Symbiflow fasm `_ which adds support for the :code:`antlr` parser in place of :code:`textx`. +| This is not a problem, and current installation will continue to use :code:`textx` as the parser, as with previous releases. +| :code:`antlr` installation requires a few extra steps, which needs to be integrated into the toolchain installation. +| This is not yet incorporated in the current install, and will be added in a future release. +| Manual Installation of :code:`antlr` can be done from the instructions at the `Symbiflow fasm `_ readme. +| +| A brief of the steps for manual installation (optional), after toolchain installation is completed: + +- Ensure :code:`conda activate` is executed + +- Execute the following sequence + + :: + + cd $INSTALL_DIR + git clone https://github.com/SymbiFlow/fasm.git + cd fasm + git submodule update --init + sudo apt install cmake default-jre-headless uuid-dev libantlr4-runtime-dev + make build + python setup.py test + +- If all goes well, run the below to test: + + :: + + python3 -c "import fasm.parser as p; print(p.available)" + + An output similar to below: + + :: + + ['antlr', 'textx'] + + indicates that :code:`antlr` is now installed and available, and will be used as the default parser. .. _1-run-an-installer-and-run-an-example: From ad25e9caa9bd22873b18a71e6fb712a639698e84 Mon Sep 17 00:00:00 2001 From: coolbreeze413 Date: Tue, 15 Dec 2020 02:12:11 +0530 Subject: [PATCH 4/8] add original README.md --- README.md | 194 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 194 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..fd5ba0b --- /dev/null +++ b/README.md @@ -0,0 +1,194 @@ +# Quicklogic FPGA Toolchain +Contains SymbiFlow toolchain release packages for Quicklogic FPGAs + +This guide describes everything you need to set up your system to develop for QuickLogic FPGA Toolchain. +Currently, the SymbiFlow Installer runs only on Linux 64bit. + +Below are some ways to run SymbiFlow: +1) Run an installer and follow the instructions to run an example +2) Compile from source code and run example +3) Run SymbiFlow in a container + +## 1) Run an installer and follow instructions to run example + +Download [Symbiflow_v1.3.0](https://github.com/QuickLogic-Corp/quicklogic-fpga-toolchain/releases/download/v1.3.0/Symbiflow_v1.3.0.gz.run) + +This package installs these toolchains : + +- Yosys +- Yosys-Plugins +- VTR +- iverilog +- Architecture definitions installation + + +```bash +#To Install +export INSTALL_DIR="specify the installpath" +bash Symbiflow_v1.3.0.gz.run + +#To Run example +export INSTALL_DIR="specify the installpath" +export PATH="$INSTALL_DIR/quicklogic-arch-defs/bin:$INSTALL_DIR/quicklogic-arch-defs/bin/python:$PATH" +source "$INSTALL_DIR/conda/etc/profile.d/conda.sh" +conda activate + +#Execute the help command to display the help +ql_symbiflow -h +``` + +## Run Example Design + +The example designs are provided in separate directories at $INSTALL_DIR/quicklogic-arch-defs/tests: + +1. `counter_16bit` - simple 16-bit up-counter. The design targets the the device ql-eos-s3 and package PD64. + +To run the examples, run following commands: +```bash +cd $INSTALL_DIR/quicklogic-arch-defs/tests/counter_16bit +ql_symbiflow -compile -d ql-eos-s3 -P pd64 -v counter_16bit.v -t top -p chandalar.pcf + +``` +For more details on the symbiflow options refer the tutorial guide: +[Symbiflow_Tutorial](https://quicklogic-fpga-tool-docs.readthedocs.io/en/latest/index.html) + +For details on the usage of RAM, FIFO and Multiplier blocks, refer to the following document: +[Ram_Fifo_Mult_User_Document](https://quicklogic-fpga-tool-docs.readthedocs.io/en/latest/ram/S3BDeviceHardmacroResources.html) + +## 2) Compile from source code and run example + +This release package contains the following GitHub repositories that are compiled to create this package. Note: Refer the repositories read.md pages for the prerequisites to build. + +You may use the following command to get the source, compile and install it: +```bash +#Checkout *yosys* repository (https://github.com/QuickLogic-Corp/yosys.git), branch: **quicklogic-rebased**. +git clone https://github.com/QuickLogic-Corp/yosys.git -b quicklogic-rebased quicklogic-yosys +cd quicklogic-yosys +#compiling using gcc +make config-gcc +make install PREFIX='specify installation path' +cd - + +#Checkout *yosys-symbiflow-plugins* (https://github.com/QuickLogic-Corp/yosys-symbiflow-plugins), branch: **ql-ios**. +git clone https://github.com/QuickLogic-Corp/yosys-symbiflow-plugins -b ql-ios +cd yosys-symbiflow-plugins +export PATH='specify Yosys installation path as specified in PREFIX in previous step':$PATH +make install +cd - + +#Checkout *vpr* repository (https://github.com/SymbiFlow/vtr-verilog-to-routing.git), branch: **master**. +git clone https://github.com/SymbiFlow/vtr-verilog-to-routing -b master +cd vtr-verilog-to-routing +make + +#Checkout *symbiflow-arch-defs* repository (https://github.com/QuickLogic-Corp/symbiflow-arch-defs.git), branch: **quicklogic-upstream-rebase**. +git clone https://github.com/QuickLogic-Corp/symbiflow-arch-defs.git -b quicklogic-upstream-rebase +export YOSYS='path to Yosys binary, installed in first step' +export VPR='path to vpr binary built' +export GENFASM='path to genfasm binary built' +cd symbiflow-arch-defs +make env +cd build +make all_conda + +#Run any test case in the current terminal window. For example, follow these steps to run a test case: +cd quicklogic/pp3/tests/quicklogic_testsuite/bin2seven +make bin2seven-ql-chandalar_fasm +``` +## 3) Run SymbiFlow in a container + +Containers provide isolated environments, similar to VMs, but lighter weight, and with performance closer to the native machine they run on. Containers start quickly from an efficient layered image which provides an identical environment each time the container starts. A great place to start is the Docker website, which provides links to tutorials and documentation: + +https://www.docker.com/why-docker + +This project uses containers to build Symbiflow automatically whenever a change is pushed to Quicklogic/quicklogic-fpga-toolchain. With each successful build, a container image is pushed as a github package, and may be pulled or run directly by a container runtime such as Docker. Such images are useful for developing continuous integration of FPGA projects. The act of building and testing them automatically through github actions also provides assurances that what is checked into the github source repositories can be built and executed. Below are some of the options for using containers to run or build SymbiFlow for Quicklogic development. + +### Option A) Build a container image locally from Dockerfile.use-installer + +The Dockerfile.use-installer in this repo builds a SymbiFlow container from a released installer. +You can build and tag the symbiflow-ql container with: +``` +docker build . -f Dockerfile.use-installer -t symbiflow-ql +``` +In order to view the gtkwave program, the easiest (but not the safest) thing to do is allow x connections: +``` +xhost + + +docker run -it -e DISPLAY=$DISPLAY -v "/tmp/.X11-unix:/tmp/.X11-unix" symbiflow-ql bash + +or run a prebuilt container automatically built from the installer by github actions: + +docker run -it -e DISPLAY=$DISPLAY -v "/tmp/.X11-unix:/tmp/.X11-unix" docker.pkg.github.com/thirsty2/quicklogic-fpga-toolchain/symbiflow-ql:1.2.0.0 bash +``` +Inside your running docker container, try some of the commands from the tutorial: +[Symbiflow_Tutorial](https://quicklogic-fpga-tool-docs.readthedocs.io/en/latest/index.html) +``` +source "$INSTALL_DIR/conda/etc/profile.d/conda.sh" +conda activate + +#Execute the help command to display the help +ql_symbiflow -h + +cd $INSTALL_DIR/quicklogic-arch-defs/tests/counter_16bit + +# Use iverilog to simulate the design +iverilog -o my_design counter_16bit.v counter_16bit_tb.v +vvp my_design + +# use gtkwave to view the results (assumes you have allowed x connections, and have an xserver running) +gtkwave counter_16bit_tb.vcd + +ql_symbiflow -compile -d ql-eos-s3 -P pd64 -v counter_16bit.v -t top -p chandalar.pcf + +``` + +When you are finished, it would be wise to disallow x connections: +``` +xhost - +``` + + +### Option B) Build a container image locally from Dockerfile + +The Dockerfile in this repo builds SymbiFlow from source. You can create and tag a local image with a Docker command like: +``` +docker build . -t symbiflow-ql-slim-buster +``` +Then you can run the container interactively with a docker command like: +``` +docker run -it symbiflow-ql-slim-buster bash +``` +From your bash session in the container, try: +``` +#Run any test case in the current terminal window. For example, follow these steps to run a test case: +cd /symbiflow-arch-defs/build/quicklogic/pp3/tests/quicklogic_testsuite/bin2seven +make bin2seven-ql-chandalar_fasm + +#Or try: +cd /symbiflow-arch-defs/build/quicklogic/pp3/tests +make all_quick_tests +``` + +### Option C) Use a container image that is built automatically by a github action workflow + +See the 'packages' links for the Docker command to pull a Symbiflow container image, or use it as the basis of a new container. + +You can run bash interactively inside of a prebuilt SymbiFlow container using a docker command like this: +``` +docker run -it docker.pkg.github.com/quicklogic-corp/quicklogic-fpga-toolchain/symbiflow-ql-src:latest bash +``` + +From your bash session in the container, try: +``` +#Run any test case in the current terminal window. For example, follow these steps to run a test case: +cd /symbiflow-arch-defs/build/quicklogic/pp3/tests/quicklogic_testsuite/bin2seven +make bin2seven-ql-chandalar_fasm + +#Or try: +cd /symbiflow-arch-defs/build/quicklogic/pp3/tests +make all_quick_tests +``` + + +## Hardware features that are not supported in this release +- IO registers: Usage of IO registers available in the IO block (Hardware) From d50d8063fef43ce2ca2795ae0dab72862be83e76 Mon Sep 17 00:00:00 2001 From: coolbreeze413 Date: Tue, 15 Dec 2020 02:12:54 +0530 Subject: [PATCH 5/8] remove README.md from git --- README.md | 194 ------------------------------------------------------ 1 file changed, 194 deletions(-) delete mode 100644 README.md diff --git a/README.md b/README.md deleted file mode 100644 index fd5ba0b..0000000 --- a/README.md +++ /dev/null @@ -1,194 +0,0 @@ -# Quicklogic FPGA Toolchain -Contains SymbiFlow toolchain release packages for Quicklogic FPGAs - -This guide describes everything you need to set up your system to develop for QuickLogic FPGA Toolchain. -Currently, the SymbiFlow Installer runs only on Linux 64bit. - -Below are some ways to run SymbiFlow: -1) Run an installer and follow the instructions to run an example -2) Compile from source code and run example -3) Run SymbiFlow in a container - -## 1) Run an installer and follow instructions to run example - -Download [Symbiflow_v1.3.0](https://github.com/QuickLogic-Corp/quicklogic-fpga-toolchain/releases/download/v1.3.0/Symbiflow_v1.3.0.gz.run) - -This package installs these toolchains : - -- Yosys -- Yosys-Plugins -- VTR -- iverilog -- Architecture definitions installation - - -```bash -#To Install -export INSTALL_DIR="specify the installpath" -bash Symbiflow_v1.3.0.gz.run - -#To Run example -export INSTALL_DIR="specify the installpath" -export PATH="$INSTALL_DIR/quicklogic-arch-defs/bin:$INSTALL_DIR/quicklogic-arch-defs/bin/python:$PATH" -source "$INSTALL_DIR/conda/etc/profile.d/conda.sh" -conda activate - -#Execute the help command to display the help -ql_symbiflow -h -``` - -## Run Example Design - -The example designs are provided in separate directories at $INSTALL_DIR/quicklogic-arch-defs/tests: - -1. `counter_16bit` - simple 16-bit up-counter. The design targets the the device ql-eos-s3 and package PD64. - -To run the examples, run following commands: -```bash -cd $INSTALL_DIR/quicklogic-arch-defs/tests/counter_16bit -ql_symbiflow -compile -d ql-eos-s3 -P pd64 -v counter_16bit.v -t top -p chandalar.pcf - -``` -For more details on the symbiflow options refer the tutorial guide: -[Symbiflow_Tutorial](https://quicklogic-fpga-tool-docs.readthedocs.io/en/latest/index.html) - -For details on the usage of RAM, FIFO and Multiplier blocks, refer to the following document: -[Ram_Fifo_Mult_User_Document](https://quicklogic-fpga-tool-docs.readthedocs.io/en/latest/ram/S3BDeviceHardmacroResources.html) - -## 2) Compile from source code and run example - -This release package contains the following GitHub repositories that are compiled to create this package. Note: Refer the repositories read.md pages for the prerequisites to build. - -You may use the following command to get the source, compile and install it: -```bash -#Checkout *yosys* repository (https://github.com/QuickLogic-Corp/yosys.git), branch: **quicklogic-rebased**. -git clone https://github.com/QuickLogic-Corp/yosys.git -b quicklogic-rebased quicklogic-yosys -cd quicklogic-yosys -#compiling using gcc -make config-gcc -make install PREFIX='specify installation path' -cd - - -#Checkout *yosys-symbiflow-plugins* (https://github.com/QuickLogic-Corp/yosys-symbiflow-plugins), branch: **ql-ios**. -git clone https://github.com/QuickLogic-Corp/yosys-symbiflow-plugins -b ql-ios -cd yosys-symbiflow-plugins -export PATH='specify Yosys installation path as specified in PREFIX in previous step':$PATH -make install -cd - - -#Checkout *vpr* repository (https://github.com/SymbiFlow/vtr-verilog-to-routing.git), branch: **master**. -git clone https://github.com/SymbiFlow/vtr-verilog-to-routing -b master -cd vtr-verilog-to-routing -make - -#Checkout *symbiflow-arch-defs* repository (https://github.com/QuickLogic-Corp/symbiflow-arch-defs.git), branch: **quicklogic-upstream-rebase**. -git clone https://github.com/QuickLogic-Corp/symbiflow-arch-defs.git -b quicklogic-upstream-rebase -export YOSYS='path to Yosys binary, installed in first step' -export VPR='path to vpr binary built' -export GENFASM='path to genfasm binary built' -cd symbiflow-arch-defs -make env -cd build -make all_conda - -#Run any test case in the current terminal window. For example, follow these steps to run a test case: -cd quicklogic/pp3/tests/quicklogic_testsuite/bin2seven -make bin2seven-ql-chandalar_fasm -``` -## 3) Run SymbiFlow in a container - -Containers provide isolated environments, similar to VMs, but lighter weight, and with performance closer to the native machine they run on. Containers start quickly from an efficient layered image which provides an identical environment each time the container starts. A great place to start is the Docker website, which provides links to tutorials and documentation: - -https://www.docker.com/why-docker - -This project uses containers to build Symbiflow automatically whenever a change is pushed to Quicklogic/quicklogic-fpga-toolchain. With each successful build, a container image is pushed as a github package, and may be pulled or run directly by a container runtime such as Docker. Such images are useful for developing continuous integration of FPGA projects. The act of building and testing them automatically through github actions also provides assurances that what is checked into the github source repositories can be built and executed. Below are some of the options for using containers to run or build SymbiFlow for Quicklogic development. - -### Option A) Build a container image locally from Dockerfile.use-installer - -The Dockerfile.use-installer in this repo builds a SymbiFlow container from a released installer. -You can build and tag the symbiflow-ql container with: -``` -docker build . -f Dockerfile.use-installer -t symbiflow-ql -``` -In order to view the gtkwave program, the easiest (but not the safest) thing to do is allow x connections: -``` -xhost + - -docker run -it -e DISPLAY=$DISPLAY -v "/tmp/.X11-unix:/tmp/.X11-unix" symbiflow-ql bash - -or run a prebuilt container automatically built from the installer by github actions: - -docker run -it -e DISPLAY=$DISPLAY -v "/tmp/.X11-unix:/tmp/.X11-unix" docker.pkg.github.com/thirsty2/quicklogic-fpga-toolchain/symbiflow-ql:1.2.0.0 bash -``` -Inside your running docker container, try some of the commands from the tutorial: -[Symbiflow_Tutorial](https://quicklogic-fpga-tool-docs.readthedocs.io/en/latest/index.html) -``` -source "$INSTALL_DIR/conda/etc/profile.d/conda.sh" -conda activate - -#Execute the help command to display the help -ql_symbiflow -h - -cd $INSTALL_DIR/quicklogic-arch-defs/tests/counter_16bit - -# Use iverilog to simulate the design -iverilog -o my_design counter_16bit.v counter_16bit_tb.v -vvp my_design - -# use gtkwave to view the results (assumes you have allowed x connections, and have an xserver running) -gtkwave counter_16bit_tb.vcd - -ql_symbiflow -compile -d ql-eos-s3 -P pd64 -v counter_16bit.v -t top -p chandalar.pcf - -``` - -When you are finished, it would be wise to disallow x connections: -``` -xhost - -``` - - -### Option B) Build a container image locally from Dockerfile - -The Dockerfile in this repo builds SymbiFlow from source. You can create and tag a local image with a Docker command like: -``` -docker build . -t symbiflow-ql-slim-buster -``` -Then you can run the container interactively with a docker command like: -``` -docker run -it symbiflow-ql-slim-buster bash -``` -From your bash session in the container, try: -``` -#Run any test case in the current terminal window. For example, follow these steps to run a test case: -cd /symbiflow-arch-defs/build/quicklogic/pp3/tests/quicklogic_testsuite/bin2seven -make bin2seven-ql-chandalar_fasm - -#Or try: -cd /symbiflow-arch-defs/build/quicklogic/pp3/tests -make all_quick_tests -``` - -### Option C) Use a container image that is built automatically by a github action workflow - -See the 'packages' links for the Docker command to pull a Symbiflow container image, or use it as the basis of a new container. - -You can run bash interactively inside of a prebuilt SymbiFlow container using a docker command like this: -``` -docker run -it docker.pkg.github.com/quicklogic-corp/quicklogic-fpga-toolchain/symbiflow-ql-src:latest bash -``` - -From your bash session in the container, try: -``` -#Run any test case in the current terminal window. For example, follow these steps to run a test case: -cd /symbiflow-arch-defs/build/quicklogic/pp3/tests/quicklogic_testsuite/bin2seven -make bin2seven-ql-chandalar_fasm - -#Or try: -cd /symbiflow-arch-defs/build/quicklogic/pp3/tests -make all_quick_tests -``` - - -## Hardware features that are not supported in this release -- IO registers: Usage of IO registers available in the IO block (Hardware) From 0864c45a4a8fd2df7b6029f7bcfd910341b75641 Mon Sep 17 00:00:00 2001 From: coolbreeze413 Date: Tue, 15 Dec 2020 02:24:18 +0530 Subject: [PATCH 6/8] update instructions to use v1.3.1 installer --- README.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.rst b/README.rst index ed87539..8ff63df 100644 --- a/README.rst +++ b/README.rst @@ -79,7 +79,7 @@ While running the compilation with the latest toolchain (v1.3.1 or the daily-bui ---------------------------------------------------------- Download -`Symbiflow_v1.3.0 `__ +`Symbiflow_v1.3.1 `__ This package installs these toolchains : @@ -96,7 +96,7 @@ Steps: :: export INSTALL_DIR="specify the installpath" - bash Symbiflow_v1.3.0.gz.run + bash Symbiflow_v1.3.1.gz.run - Initialize From cf951cf60823a91e813714d9202f70254b49adb9 Mon Sep 17 00:00:00 2001 From: coolbreeze413 Date: Sun, 20 Dec 2020 03:52:49 +0530 Subject: [PATCH 7/8] remove dailybuild instructions from main readme --- README.rst | 75 +++++------------------------------------------------- 1 file changed, 6 insertions(+), 69 deletions(-) diff --git a/README.rst b/README.rst index 8ff63df..c208c6f 100644 --- a/README.rst +++ b/README.rst @@ -10,9 +10,8 @@ Installer runs only on Linux 64bit. Below are some ways to run SymbiFlow: 1) Run an installer and run an example -2) Use the daily build and run an example -3) Compile from source code and run example -4) Run SymbiFlow in a container +2) Compile from source code and run example +3) Run SymbiFlow in a container For more details on the symbiflow options refer the tutorial guide: `Symbiflow_Tutorial `_ @@ -127,71 +126,9 @@ Steps: ql_symbiflow -compile -d ql-eos-s3 -P pd64 -v counter_16bit.v -t top -p chandalar.pcf -.. _2-use-the-daily-build-and-run-an-example: +.. _2-compile-from-source-code-and-run-example: -2) Use the daily build and run an example ------------------------------------------- - -Steps: - -- Install - -:: - - export INSTALL_DIR="specify the installpath" - wget https://repo.continuum.io/miniconda/Miniconda3-latest-Linux-x86_64.sh -O conda_installer.sh - bash conda_installer.sh -b -p $INSTALL_DIR/conda && rm conda_installer.sh - source "$INSTALL_DIR/conda/etc/profile.d/conda.sh" - echo "include-system-site-packages=false" >> $INSTALL_DIR/conda/pyvenv.cfg - CONDA_FLAGS="-y --override-channels -c defaults -c conda-forge" - conda update $CONDA_FLAGS -q conda - curl $(curl https://storage.googleapis.com/symbiflow-arch-defs-install/latest) > arch.tar.gz - tar -C $INSTALL_DIR -xvf arch.tar.gz && rm arch.tar.gz - conda install $CONDA_FLAGS -c quicklogic-corp/label/ql yosys="0.8.0_0003_e80fb742f_20201208_122808 None" python=3.7 - conda install $CONDA_FLAGS -c quicklogic-corp/label/ql yosys-plugins="1.2.0_0011_g21045a9 None" - conda install $CONDA_FLAGS -c quicklogic-corp/label/ql vtr="v8.0.0_rc2_2894_gdadca7ecf 20201008_140004" - conda install $CONDA_FLAGS -c quicklogic-corp iverilog - conda install $CONDA_FLAGS -c tfors gtkwave - conda install $CONDA_FLAGS make lxml simplejson intervaltree git pip - conda activate - pip install python-constraint - pip install serial - pip install git+https://github.com/QuickLogic-Corp/quicklogic-fasm - conda deactivate - -- Initialize - -:: - - export INSTALL_DIR="specify the installpath" - export PATH="$INSTALL_DIR/quicklogic-arch-defs/bin:$INSTALL_DIR/quicklogic-arch-defs/bin/python:$PATH" - source "$INSTALL_DIR/conda/etc/profile.d/conda.sh" - conda activate - -- Run help command - -:: - - ql_symbiflow -h - -- Run Example Design - - The example designs are provided in separate directories at :code:`$INSTALL_DIR/quicklogic-arch-defs/tests` : - - 1. :code:`counter_16bit` - simple 16-bit up-counter. The design targets the device ql-eos-s3 and package PD64. - - To run this example, run following commands: - - :: - - cd $INSTALL_DIR/quicklogic-arch-defs/tests/counter_16bit - ql_symbiflow -compile -d ql-eos-s3 -P pd64 -v counter_16bit.v -t top -p chandalar.pcf - - - -.. _3-compile-from-source-code-and-run-example: - -3) Compile from source code and run example +2) Compile from source code and run example ------------------------------------------- This release package contains the following GitHub repositories that are @@ -237,9 +174,9 @@ it: cd quicklogic/pp3/tests/quicklogic_testsuite/bin2seven make bin2seven-ql-chandalar_fasm -.. _4-run-symbiflow-in-a-container: +.. _3-run-symbiflow-in-a-container: -4) Run SymbiFlow in a container +3) Run SymbiFlow in a container ------------------------------- Containers provide isolated environments, similar to VMs, but lighter From 765267d2337bfb47c053db8a208d4a88d09c7c48 Mon Sep 17 00:00:00 2001 From: coolbreeze413 Date: Sun, 20 Dec 2020 03:55:42 +0530 Subject: [PATCH 8/8] remove mention of daily build in all places --- README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.rst b/README.rst index c208c6f..8d82249 100644 --- a/README.rst +++ b/README.rst @@ -23,7 +23,7 @@ the following document: **NOTE:** -While running the compilation with the latest toolchain (v1.3.1 or the daily-build), the following warning would be seen: +While running the compilation with the latest toolchain (v1.3.1), the following warning would be seen: ::