Merge pull request #47 from antmicro/examples-remove

Remove examples directory and improvement documentation

.github/travis/common.sh

@@ -0,0 +1,30 @@
+# Some colors, use it like following;
+# echo -e "Hello ${YELLOW}yellow${NC}"
+GRAY=' \033[0;30m'
+RED=' \033[0;31m'
+GREEN=' \033[0;32m'
+YELLOW=' \033[0;33m'
+PURPLE=' \033[0;35m'
+NC='\033[0m' # No Color
+
+SPACER="echo -e ${GRAY} - ${NC}"
+
+export -f travis_nanoseconds
+export -f travis_fold
+export -f travis_time_start
+export -f travis_time_finish
+export -f travis_wait
+export -f travis_jigger
+
+function start_section() {
+        travis_fold start "$1"
+        travis_time_start
+        echo -e "${PURPLE}${1}${NC}: $2${NC}"
+        echo -e "${GRAY}-------------------------------------------------------------------${NC}"
+}
+
+function end_section() {
+        echo -e "${GRAY}-------------------------------------------------------------------${NC}"
+        travis_time_finish
+        travis_fold end "$1"
+}

.github/travis/git-check.sh

@@ -0,0 +1,27 @@
+set -e
+
+source .github/travis/common.sh
+
+# Output any changes in the repository
+# ------------------------------------------------------------------------
+start_section git-status "Current git status"
+
+git diff
+
+$SPACER
+
+git status
+
+end_section git-status
+
+# Check there are not changes in the repository
+# ------------------------------------------------------------------------
+start_section git-check "Checking git repository isn't dirty"
+
+(
+	. "$(git --exec-path)/git-sh-setup"
+
+	require_clean_work_tree "continue" "Please run ``make README.rst`` to generate correct ``README.rst``."
+)
+
+end_section git-check

.travis.yml

@@ -14,20 +14,22 @@ addons:
 before_install:
         - sudo locale-gen "en_US.UTF-8"
         - export LANG="en_US.UTF-8"
+        - source .github/travis/common.sh
+        - rm README.rst && make README.rst && .github/travis/git-check.sh
         - pip install git+https://github.com/antmicro/tuttest
-        - tuttest README.md unnamed0 | bash -
+        - tuttest README.rst unnamed0 | bash -
 jobs:
   include:
     - stage: SymbiFlow
       install:
-            - tuttest README.md unnamed1 | bash -
+            - tuttest xc7/README.rst unnamed0 | bash -
 
       script:
-            - tuttest README.md unnamed3 | bash -
+            - tuttest xc7/README.rst unnamed1,unnamed2,unnamed3,unnamed4,unnamed5 | bash -
     - #
       install:
-            - tuttest README.md unnamed2 | bash -
+            - tuttest eos-s3/README.rst unnamed0 | bash -
 
       script:
-            - tuttest README.md unnamed4 | bash -
+            - tuttest eos-s3/README.rst unnamed1,unnamed2 | bash -
 

Makefile

@@ -0,0 +1,5 @@
+include scripts/make/conda.mk
+
+README.rst: README.src.rst eos-s3/README.rst xc7/README.rst | $(CONDA_ENV_PYTHON)
+	@rm -f README.rst
+	$(IN_CONDA_ENV) rst_include include README.src.rst - > README.rst

README.md

@@ -1,111 +0,0 @@
-# SymbiFlow examples
-
-This repository provides example FPGA designs that can be built using the SymbiFlow open source toolchain.
-The examples target the Xilinx Artix-7 and the QuickLogic EOS S3 devices.
-
-The repository includes:
-
-* [examples](./examples) - Example FPGA designs including:
-
-  * Verilog code
-  * Pin constraints files
-  * Timing constraints files
-  * Makefiles for running the SymbiFlow toolchain
-
-* [.travis.yml](.travis.yml) - Travis CI configuration file
-
-## Toolchain installation
-
-This section describes how to install the toolchain. This procedure is divided in two steps:
-
-- Installing the Conda package manager
-- Downloading the architecture definitions and installing the toolchain
-
-1. Conda
-
-```bash
-wget https://repo.continuum.io/miniconda/Miniconda3-latest-Linux-x86_64.sh -O conda_installer.sh
-```
-
-2. Toolchain
-
-For the Artix-7 devices:
-
-```bash
-INSTALL_DIR="/opt/symbiflow/xc7"
-bash conda_installer.sh -b -p $INSTALL_DIR/conda && rm conda_installer.sh
-source "$INSTALL_DIR/conda/etc/profile.d/conda.sh"
-conda env create -f examples/xc7/environment.yml
-conda activate xc7
-wget -qO- https://storage.googleapis.com/symbiflow-arch-defs/artifacts/prod/foss-fpga-tools/symbiflow-arch-defs/presubmit/install/477/20200714-082108/symbiflow-arch-defs-install-8eb88e76.tar.xz | tar -xJ --one-top-level=$INSTALL_DIR/install
-conda deactivate
-```
-
-For the EOS S3 devices:
-
-```bash
-export INSTALL_DIR="/opt/symbiflow/eos-s3"
-wget 'https://github.com/QuickLogic-Corp/quicklogic-fpga-toolchain/releases/download/v1.1.0/Symbiflow_v1.1.0.gz.run'
-bash Symbiflow_v1.1.0.gz.run
-```
-
-## Build Example Designs
-
-With the toolchain installed, you can build the example designs.
-The example designs are provided in separate directories:
-
-* `examples/xc7` directory for the Artix-7 devices
-* `examples/eos-s3` directory for the EOS S3 devices
-
-### Example designs for the Artix-7 devices:
-
-1. `counter` - simple 4-bit counter driving LEDs. The design targets the [Basys3 board](https://store.digilentinc.com/basys-3-artix-7-fpga-trainer-board-recommended-for-introductory-users/) and the [Arty board](https://store.digilentinc.com/arty-a7-artix-7-fpga-development-board-for-makers-and-hobbyists/).
-1. `picosoc` - [picorv32](https://github.com/cliffordwolf/picorv32) based SoC. The design targets the [Basys3 board](https://store.digilentinc.com/basys-3-artix-7-fpga-trainer-board-recommended-for-introductory-users/).
-1. `linux_litex` - [LiteX](https://github.com/enjoy-digital/litex) based system with Linux capable [VexRiscv core](https://github.com/SpinalHDL/VexRiscv). The design includes [DDR](https://github.com/enjoy-digital/litedram) and [Ethernet](https://github.com/enjoy-digital/liteeth) controllers. The design targets the [Arty board](https://store.digilentinc.com/arty-a7-artix-7-fpga-development-board-for-makers-and-hobbyists/).
-
-The Linux images for the `linux_litex` example can be built following the [linux on litex vexriscv](https://github.com/litex-hub/linux-on-litex-vexriscv) instructions.
-The `linux_litex` example is already provided with working Linux images.
-
-To build the examples, run the following commands:
-
-```bash
-export INSTALL_DIR="/opt/symbiflow/xc7"
-# adding symbiflow toolchain binaries to PATH
-export PATH="$INSTALL_DIR/install/bin:$PATH"
-source "$INSTALL_DIR/conda/etc/profile.d/conda.sh"
-conda activate xc7
-git clone https://github.com/SymbiFlow/symbiflow-examples && cd symbiflow-examples
-# counter example
-pushd examples/xc7/counter_test && TARGET="arty_50" make && popd
-pushd examples/xc7/counter_test && TARGET="arty_100" make && popd
-pushd examples/xc7/counter_test && make clean && TARGET="basys3" make && popd
-# picosoc example
-pushd examples/xc7/picosoc_demo && make && popd
-# litex example
-wget https://raw.githubusercontent.com/enjoy-digital/litex/master/litex_setup.py
-chmod +x litex_setup.py
-./litex_setup.py init
-./litex_setup.py install
-wget https://static.dev.sifive.com/dev-tools/riscv64-unknown-elf-gcc-8.1.0-2019.01.0-x86_64-linux-ubuntu14.tar.gz
-tar -xf riscv64-unknown-elf-gcc-8.1.0-2019.01.0-x86_64-linux-ubuntu14.tar.gz
-export PATH=$PATH:$PWD/riscv64-unknown-elf-gcc-8.1.0-2019.01.0-x86_64-linux-ubuntu14/bin/
-pushd litex/litex/boards/targets && ./arty.py --toolchain symbiflow --cpu-type vexriscv --build && popd
-# linux litex example
-pushd examples/xc7/linux_litex_demo && make && popd
-```
-
-### Example design for the EOS S3 devices:
-
-1. `btn_counter` - simple 4-bit counter driving LEDs. The design targets the [EOS S3 FPGA](https://www.quicklogic.com/products/eos-s3/).
-
-To build the example, run the following commands:
-
-```bash
-export INSTALL_DIR="/opt/symbiflow/eos-s3"
-export PATH="$INSTALL_DIR/install/bin:$INSTALL_DIR/install/bin/python:$PATH"
-source "$INSTALL_DIR/conda/etc/profile.d/conda.sh"
-conda activate
-
-git clone https://github.com/SymbiFlow/symbiflow-examples && cd symbiflow-examples
-pushd examples/eos-s3 && make && popd
-```

README.rst

@@ -0,0 +1,145 @@
+SymbiFlow examples
+==================
+
+This repository provides example FPGA designs that can be built using the SymbiFlow open source toolchain.
+The examples target the Xilinx Artix-7 and the QuickLogic EOS S3 devices.
+
+The repository includes:
+
+* `eos-s3 </eos-s3>`_ - Example FPGA designs for the QuickLogic EOS S3 series of parts:
+
+  * Verilog code
+  * Pin constraints files
+  * Timing constraints files
+  * Makefiles for running the SymbiFlow toolchain
+
+* `xc7 </xc7>`_ - Example FPGA designs for the Xilinx 7 series of parts:
+
+  * Verilog code
+  * Pin constraints files
+  * Timing constraints files
+  * Makefiles for running the SymbiFlow toolchain
+
+* `.travis.yml <.travis.yml>`_ - Travis CI configuration file
+
+Toolchain installation
+----------------------
+
+This section describes how to install the toolchain. This procedure is divided in two steps:
+
+- Installing the Conda package manager
+- Downloading the architecture definitions and installing the toolchain
+
+#. Conda
+
+.. code:: bash
+
+        wget https://repo.continuum.io/miniconda/Miniconda3-latest-Linux-x86_64.sh -O conda_installer.sh
+
+#. Toolchain
+
+* For the Artix-7 devices:
+
+.. code:: bash
+
+        INSTALL_DIR="/opt/symbiflow/xc7"
+        bash conda_installer.sh -b -p $INSTALL_DIR/conda && rm conda_installer.sh
+        source "$INSTALL_DIR/conda/etc/profile.d/conda.sh"
+        conda env create -f xc7/environment.yml
+        conda activate xc7
+        wget -qO- https://storage.googleapis.com/symbiflow-arch-defs/artifacts/prod/foss-fpga-tools/symbiflow-arch-defs/presubmit/install/477/20200714-082108/symbiflow-arch-defs-install-8eb88e76.tar.xz | tar -xJ --one-top-level=$INSTALL_DIR/install
+        conda deactivate
+
+* For the EOS S3 devices:
+
+.. code:: bash
+
+        export INSTALL_DIR="/opt/symbiflow/eos-s3"
+        bash conda_installer.sh -b -p $INSTALL_DIR/conda && rm conda_installer.sh
+        source "$INSTALL_DIR/conda/etc/profile.d/conda.sh"
+        conda env create -f eos-s3/environment.yml
+        conda activate eos-s3
+        wget -qO- https://quicklogic-my.sharepoint.com/:u:/p/kkumar/Eb7341Bq-XRAukVQ6oQ6PrgB-qdFbrsrPEON1yTa4krFSA?download=1 | tar -xJ -C $INSTALL_DIR
+        cp -r $INSTALL_DIR/conda/envs/eos-s3/share/yosys/* $INSTALL_DIR/conda/envs/eos-s3/share/
+        conda deactivate
+
+Build Example Designs
+---------------------
+
+With the toolchain installed, you can build the example designs.
+The example designs are provided in separate directories:
+
+* ``xc7`` directory for the Artix-7 devices
+* ``eos-s3`` directory for the EOS S3 devices
+
+Example designs for the Artix-7 devices:
+****************************************
+
+* For the Artix-7 devices:
+
+Before building any example, prepare environment:
+
+.. code:: bash
+
+        export INSTALL_DIR="/opt/symbiflow/xc7"
+        # adding symbiflow toolchain binaries to PATH
+        export PATH="$INSTALL_DIR/install/bin:$PATH"
+        source "$INSTALL_DIR/conda/etc/profile.d/conda.sh"
+        conda activate xc7
+        git clone https://github.com/SymbiFlow/symbiflow-examples && cd symbiflow-examples
+
+To build the counter example, run the following commands:
+
+.. code:: bash
+
+        pushd xc7/counter_test && make clean && TARGET="arty_50" make && popd
+        pushd xc7/counter_test && make clean && TARGET="arty_100" make && popd
+        pushd xc7/counter_test && make clean && TARGET="basys3" make && popd
+
+To build the picosoc example, run the following commands:
+
+.. code:: bash
+
+        pushd xc7/picosoc_demo && make && popd
+
+To build the litex example, run the following commands:
+
+.. code:: bash
+
+        wget https://raw.githubusercontent.com/enjoy-digital/litex/master/litex_setup.py
+        chmod +x litex_setup.py
+        ./litex_setup.py init
+        ./litex_setup.py install
+        wget https://static.dev.sifive.com/dev-tools/riscv64-unknown-elf-gcc-8.1.0-2019.01.0-x86_64-linux-ubuntu14.tar.gz
+        tar -xf riscv64-unknown-elf-gcc-8.1.0-2019.01.0-x86_64-linux-ubuntu14.tar.gz
+        export PATH=$PATH:$PWD/riscv64-unknown-elf-gcc-8.1.0-2019.01.0-x86_64-linux-ubuntu14/bin/
+        pushd litex/litex/boards/targets && ./arty.py --toolchain symbiflow --cpu-type vexriscv --build && popd
+
+To build the linux-litex-demo example, run the following commands:
+
+.. code:: bash
+
+        pushd xc7/linux_litex_demo && make && popd
+
+Example design for the EOS S3 devices:
+**************************************
+
+* For the EOS S3 devices:
+
+Before building example, prepare environment:
+
+.. code:: bash
+
+        export INSTALL_DIR="/opt/symbiflow/eos-s3"
+        export PATH="$INSTALL_DIR/install/bin:$PATH"
+        source "$INSTALL_DIR/conda/etc/profile.d/conda.sh"
+        conda activate eos-s3
+
+        git clone https://github.com/SymbiFlow/symbiflow-examples && cd symbiflow-examples
+
+To build the example, run the following command:
+
+.. code:: bash
+
+        pushd eos-s3/btn_counter && make && popd
+

README.src.rst

@@ -0,0 +1,80 @@
+SymbiFlow examples
+==================
+
+This repository provides example FPGA designs that can be built using the SymbiFlow open source toolchain.
+The examples target the Xilinx Artix-7 and the QuickLogic EOS S3 devices.
+
+The repository includes:
+
+* `eos-s3 </eos-s3>`_ - Example FPGA designs for the QuickLogic EOS S3 series of parts:
+
+  * Verilog code
+  * Pin constraints files
+  * Timing constraints files
+  * Makefiles for running the SymbiFlow toolchain
+
+* `xc7 </xc7>`_ - Example FPGA designs for the Xilinx 7 series of parts:
+
+  * Verilog code
+  * Pin constraints files
+  * Timing constraints files
+  * Makefiles for running the SymbiFlow toolchain
+
+* `.travis.yml <.travis.yml>`_ - Travis CI configuration file
+
+Toolchain installation
+----------------------
+
+This section describes how to install the toolchain. This procedure is divided in two steps:
+
+- Installing the Conda package manager
+- Downloading the architecture definitions and installing the toolchain
+
+#. Conda
+
+.. code:: bash
+
+        wget https://repo.continuum.io/miniconda/Miniconda3-latest-Linux-x86_64.sh -O conda_installer.sh
+
+#. Toolchain
+
+* For the Artix-7 devices:
+
+.. include:: xc7/README.rst
+   :start-after:.. toolchain_include_begin_label
+   :end-before:.. toolchain_include_end_label
+
+
+* For the EOS S3 devices:
+
+.. include:: eos-s3/README.rst
+   :start-after:.. toolchain_include_begin_label
+   :end-before:.. toolchain_include_end_label
+
+Build Example Designs
+---------------------
+
+With the toolchain installed, you can build the example designs.
+The example designs are provided in separate directories:
+
+* ``xc7`` directory for the Artix-7 devices
+* ``eos-s3`` directory for the EOS S3 devices
+
+Example designs for the Artix-7 devices:
+****************************************
+
+* For the Artix-7 devices:
+
+.. include:: xc7/README.rst
+   :start-after:.. build_examples_include_begin_label
+   :end-before:.. build_examples_include_end_label
+
+Example design for the EOS S3 devices:
+**************************************
+
+* For the EOS S3 devices:
+
+.. include:: eos-s3/README.rst
+   :start-after:.. build_examples_include_begin_label
+   :end-before:.. build_examples_include_end_label
+

environment.yml

@@ -0,0 +1,8 @@
+name: symbiflow-examples
+channels:
+  - defaults
+dependencies:
+  - python
+  - pip
+  - pip:
+    - -r file:requirements.txt

eos-s3/README.rst

@@ -0,0 +1,46 @@
+SymbiFlow Toolchain Examples for QuickLogic EOS S3
+==================================================
+
+#. ``btn_counter`` - simple 4-bit counter driving LEDs. The design targets the `EOS S3 FPGA <https://www.quicklogic.com/products/eos-s3/>`__.
+
+Setting up the toolchain
+------------------------
+
+.. toolchain_include_begin_label
+
+.. code:: bash
+
+        export INSTALL_DIR="/opt/symbiflow/eos-s3"
+        bash conda_installer.sh -b -p $INSTALL_DIR/conda && rm conda_installer.sh
+        source "$INSTALL_DIR/conda/etc/profile.d/conda.sh"
+        conda env create -f eos-s3/environment.yml
+        conda activate eos-s3
+        wget -qO- https://quicklogic-my.sharepoint.com/:u:/p/kkumar/Eb7341Bq-XRAukVQ6oQ6PrgB-qdFbrsrPEON1yTa4krFSA?download=1 | tar -xJ -C $INSTALL_DIR
+        cp -r $INSTALL_DIR/conda/envs/eos-s3/share/yosys/* $INSTALL_DIR/conda/envs/eos-s3/share/
+        conda deactivate
+
+.. toolchain_include_end_label
+
+Building the examples
+---------------------
+
+.. build_examples_include_begin_label
+
+Before building example, prepare environment:
+
+.. code:: bash
+
+        export INSTALL_DIR="/opt/symbiflow/eos-s3"
+        export PATH="$INSTALL_DIR/install/bin:$PATH"
+        source "$INSTALL_DIR/conda/etc/profile.d/conda.sh"
+        conda activate eos-s3
+
+        git clone https://github.com/SymbiFlow/symbiflow-examples && cd symbiflow-examples
+
+To build the example, run the following command:
+
+.. code:: bash
+
+        pushd eos-s3/btn_counter && make && popd
+
+.. build_examples_include_end_label

eos-s3/environment.yml

@@ -0,0 +1,17 @@
+name: eos-s3
+channels:
+  - conda-forge
+  - quicklogic-corp
+dependencies:
+  - quicklogic-corp::yosys=0.6.0_0013_g2478b28
+  - quicklogic-corp::yosys-plugins=0.1.0_0005_g6bbbc9b
+  - quicklogic-corp::vtr=v8.0.0_rc2_4006_g36a4d4b
+  - make
+  - lxml
+  - simplejson
+  - intervaltree
+  - git
+  - pip
+  # Packages installed from PyPI
+  - pip:
+    - -r file:requirements.txt

eos-s3/requirements.txt

@@ -0,0 +1,2 @@
+python-constraint
+git+https://github.com/QuickLogic-Corp/quicklogic-fasm

examples/eos-s3/environment.yml

@@ -1,16 +0,0 @@
-name: eos-s3
-channels:
-  - antmicro/label/ql
-dependencies:
-  - antmicro/label/ql::yosys
-  - antmicro/label/ql::yosys-plugins
-  - antmicro/label/ql::vtr
-  - make
-  - lxml
-  - simplejson
-  - intervaltree
-  - git
-  - pip
-  # Packages installed from PyPI
-  - pip:
-    - -r file:requirements.txt

examples/eos-s3/quickfeather.pcf

@@ -1,5 +0,0 @@
-set_io clk      63
-set_io led(0)   34
-set_io led(1)   39
-set_io led(2)   38
-set_io led(3)   25

examples/eos-s3/requirements.txt

@@ -1,4 +0,0 @@
-python-constraint
-git+https://github.com/symbiflow/fasm
-git+https://github.com/antmicro/quicklogic-fasm
-git+https://github.com/antmicro/quicklogic-fasm-utils

requirements.txt

@@ -0,0 +1 @@
+rst_include

scripts/make/conda.mk

@@ -0,0 +1,97 @@
+SHELL := /bin/bash
+
+UNAME_S := $(shell uname -s)
+ifneq (, $(findstring Linux, $(UNAME_S)))
+        OSFLAG := Linux
+endif
+ifeq ($(UNAME_S), Darwin)
+        OSFLAG := MacOSX
+endif
+ifneq (, $(findstring Cygwin, $(UNAME_S)))
+        OSFLAG := Linux
+endif
+ifneq (, $(findstring MINGW, $(UNAME_S)))
+        OSFLAG := Linux
+endif
+
+MAKE_DIR          := $(dir $(lastword $(MAKEFILE_LIST)))
+TOP_DIR           := $(realpath $(MAKE_DIR)/../..)
+ENV_DIR           := $(TOP_DIR)/env
+REQUIREMENTS_FILE := $(TOP_DIR)/requirements.txt
+ENVIRONMENT_FILE  := $(TOP_DIR)/environment.yml
+
+CONDA_DIR         := $(ENV_DIR)/conda
+DOWNLOADS_DIR     := $(ENV_DIR)/downloads
+CONDA_PYTHON      := $(CONDA_DIR)/bin/python
+CONDA_PKGS_DIR    := $(DOWNLOADS_DIR)/conda-pkgs
+CONDA_PKGS_DEP    := $(CONDA_PKGS_DIR)/urls.txt
+CONDA_ENV_NAME    := symbiflow-examples
+CONDA_ENV_PYTHON  := $(CONDA_DIR)/envs/$(CONDA_ENV_NAME)/bin/python
+IN_CONDA_ENV_BASE := source $(CONDA_DIR)/bin/activate &&
+IN_CONDA_ENV      := $(IN_CONDA_ENV_BASE) conda activate $(CONDA_ENV_NAME) &&
+
+$(ENV_DIR): | $(DOWNLOADS_DIR)
+	mkdir -p $(END_DIR)
+
+$(DOWNLOADS_DIR):
+	mkdir -p $(DOWNLOADS_DIR)
+
+$(DOWNLOADS_DIR)/Miniconda3-latest-$(OSFLAG)-x86_64.sh: | $(DOWNLOADS_DIR)
+	wget https://repo.anaconda.com/miniconda/Miniconda3-latest-$(OSFLAG)-x86_64.sh -O $(DOWNLOADS_DIR)/Miniconda3-latest-$(OSFLAG)-x86_64.sh
+	chmod a+x $(DOWNLOADS_DIR)/Miniconda3-latest-$(OSFLAG)-x86_64.sh
+
+$(CONDA_PKGS_DEP): $(CONDA_PYTHON)
+	$(IN_CONDA_ENV_BASE) conda config --system --add pkgs_dirs $(CONDA_PKGS_DIR)
+
+$(CONDA_PYTHON): $(DOWNLOADS_DIR)/Miniconda3-latest-$(OSFLAG)-x86_64.sh
+	$(DOWNLOADS_DIR)/Miniconda3-latest-$(OSFLAG)-x86_64.sh -p $(CONDA_DIR) -b -f
+	touch $(CONDA_PYTHON)
+
+$(CONDA_DIR)/envs: $(CONDA_PYTHON)
+	$(IN_CONDA_ENV_BASE) conda config --system --add envs_dirs $(CONDA_DIR)/envs
+
+$(CONDA_ENV_PYTHON): $(ENVIRONMENT_FILE) $(REQUIREMENTS_FILE) | $(CONDA_PYTHON) $(CONDA_DIR)/envs $(CONDA_PKGS_DEP)
+	$(IN_CONDA_ENV_BASE) conda env update --name $(CONDA_ENV_NAME) --file $(ENVIRONMENT_FILE)
+	touch $(CONDA_ENV_PYTHON)
+
+env: $(CONDA_ENV_PYTHON)
+	$(IN_CONDA_ENV) conda info
+
+.PHONY: env
+
+enter: $(CONDA_ENV_PYTHON)
+	$(IN_CONDA_ENV) bash
+
+.PHONY: enter
+
+clean:
+	rm -rf env/conda
+
+.PHONY: clean
+
+dist-clean:
+	rm -rf conda
+
+.PHONY: dist-clean
+
+
+FILTER_TOP = sed -e's@$(TOP_DIR)/@$$TOP_DIR/@'
+env-info:
+	@echo "             Top level directory is: '$(TOP_DIR)'"
+	@echo "              The version number is: '$$(git describe)'"
+	@echo "            Git repository is using: $$(du -h -s $(TOP_DIR)/.git | sed -e's/\s.*//')" \
+		| $(FILTER_TOP)
+	@echo
+	@echo "     Environment setup directory is: '$(ENV_DIR)'" \
+		| $(FILTER_TOP)
+	@echo "    Download and cache directory is: '$(DOWNLOADS_DIR)' (using $$(du -h -s $(DOWNLOADS_DIR) | sed -e's/\s.*//'))" \
+		| $(FILTER_TOP)
+	@echo "               Conda's directory is: '$(CONDA_DIR)' (using $$(du -h -s $(CONDA_DIR) | sed -e's/\s.*//'))" \
+		| $(FILTER_TOP)
+	@echo " Conda's packages download cache is: '$(CONDA_PKGS_DIR)' (using $$(du -h -s $(CONDA_PKGS_DIR) | sed -e's/\s.*//'))" \
+		| $(FILTER_TOP)
+	@echo "           Conda's Python binary is: '$(CONDA_ENV_PYTHON)'"\
+		| $(FILTER_TOP)
+
+
+.PHONY: info

xc7/README.rst

@@ -0,0 +1,79 @@
+SymbiFlow Toolchain Examples for Xilinx 7 Series
+================================================
+
+#. ``counter`` - simple 4-bit counter driving LEDs. The design targets the `Basys3 board <https://store.digilentinc.com/basys-3-artix-7-fpga-trainer-board-recommended-for-introductory-users/>`__ and the `Arty board <https://store.digilentinc.com/arty-a7-artix-7-fpga-development-board-for-makers-and-hobbyists/>`__.
+
+#. ``picosoc`` - `picorv32 <https://github.com/cliffordwolf/picorv32>`__ based SoC. The design targets the `Basys3 board <https://store.digilentinc.com/basys-3-artix-7-fpga-trainer-board-recommended-for-introductory-users/>`__.
+
+#. ``linux_litex`` - `LiteX <https://github.com/enjoy-digital/litex>`__ based system with Linux capable `VexRiscv core <https://github.com/SpinalHDL/VexRiscv>`__. The design includes `DDR <https://github.com/enjoy-digital/litedram>`__ and `Ethernet <https://github.com/enjoy-digital/liteeth>`__ controllers. The design targets the `Arty board <https://store.digilentinc.com/arty-a7-artix-7-fpga-development-board-for-makers-and-hobbyists/>`__.
+
+The Linux images for the ``linux_litex`` example can be built following the `linux on litex vexriscv <https://github.com/litex-hub/linux-on-litex-vexriscv>`__ instructions.
+The ``linux_litex`` example is already provided with working Linux images.
+
+Setting up the toolchain
+------------------------
+
+.. toolchain_include_begin_label
+
+.. code:: bash
+
+        INSTALL_DIR="/opt/symbiflow/xc7"
+        bash conda_installer.sh -b -p $INSTALL_DIR/conda && rm conda_installer.sh
+        source "$INSTALL_DIR/conda/etc/profile.d/conda.sh"
+        conda env create -f xc7/environment.yml
+        conda activate xc7
+        wget -qO- https://storage.googleapis.com/symbiflow-arch-defs/artifacts/prod/foss-fpga-tools/symbiflow-arch-defs/presubmit/install/477/20200714-082108/symbiflow-arch-defs-install-8eb88e76.tar.xz | tar -xJ --one-top-level=$INSTALL_DIR/install
+        conda deactivate
+
+.. toolchain_include_end_label
+
+Building the examples
+---------------------
+
+.. build_examples_include_begin_label
+
+Before building any example, prepare environment:
+
+.. code:: bash
+
+        export INSTALL_DIR="/opt/symbiflow/xc7"
+        # adding symbiflow toolchain binaries to PATH
+        export PATH="$INSTALL_DIR/install/bin:$PATH"
+        source "$INSTALL_DIR/conda/etc/profile.d/conda.sh"
+        conda activate xc7
+        git clone https://github.com/SymbiFlow/symbiflow-examples && cd symbiflow-examples
+
+To build the counter example, run the following commands:
+
+.. code:: bash
+
+        pushd xc7/counter_test && make clean && TARGET="arty_50" make && popd
+        pushd xc7/counter_test && make clean && TARGET="arty_100" make && popd
+        pushd xc7/counter_test && make clean && TARGET="basys3" make && popd
+
+To build the picosoc example, run the following commands:
+
+.. code:: bash
+
+        pushd xc7/picosoc_demo && make && popd
+
+To build the litex example, run the following commands:
+
+.. code:: bash
+
+        wget https://raw.githubusercontent.com/enjoy-digital/litex/master/litex_setup.py
+        chmod +x litex_setup.py
+        ./litex_setup.py init
+        ./litex_setup.py install
+        wget https://static.dev.sifive.com/dev-tools/riscv64-unknown-elf-gcc-8.1.0-2019.01.0-x86_64-linux-ubuntu14.tar.gz
+        tar -xf riscv64-unknown-elf-gcc-8.1.0-2019.01.0-x86_64-linux-ubuntu14.tar.gz
+        export PATH=$PATH:$PWD/riscv64-unknown-elf-gcc-8.1.0-2019.01.0-x86_64-linux-ubuntu14/bin/
+        pushd litex/litex/boards/targets && ./arty.py --toolchain symbiflow --cpu-type vexriscv --build && popd
+
+To build the linux-litex-demo example, run the following commands:
+
+.. code:: bash
+
+        pushd xc7/linux_litex_demo && make && popd
+
+.. build_examples_include_end_label