From 54c9beac6e2e00c3059e9334712dfb4c2cd277bb Mon Sep 17 00:00:00 2001 From: Filip Kokosinski Date: Tue, 8 Dec 2020 13:35:12 +0100 Subject: [PATCH] readme: Remove README-based documentation structure Signed-off-by: Filip Kokosinski --- Makefile | 5 -- README.rst | 218 ++++++++-------------------------------------- README.src.rst | 123 -------------------------- eos-s3/README.rst | 68 --------------- 4 files changed, 38 insertions(+), 376 deletions(-) delete mode 100644 Makefile delete mode 100644 README.src.rst delete mode 100644 eos-s3/README.rst diff --git a/Makefile b/Makefile deleted file mode 100644 index 917c62a..0000000 --- a/Makefile +++ /dev/null @@ -1,5 +0,0 @@ -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 diff --git a/README.rst b/README.rst index 3b776e7..864bddb 100644 --- a/README.rst +++ b/README.rst @@ -1,207 +1,65 @@ 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. +.. image:: https://travis-ci.com/SymbiFlow/symbiflow-examples.svg?branch=master + :target: https://travis-ci.com/SymbiFlow/symbiflow-examples + +This repository provides example FPGA designs that can be built using the +SymbiFlow open source toolchain. These examples target the Xilinx 7-Series and +the QuickLogic EOS S3 devices. The repository includes: -* `eos-s3 `_ - Example FPGA designs for the QuickLogic EOS S3 series of parts: +* `xc7/ <./xc7>`_ and `eos-s3/ <./eos-s3>`_ - Examples for Xilinx 7-Series and EOS-S3 devices, including: * Verilog code * Pin constraints files * Timing constraints files * Makefiles for running the SymbiFlow toolchain +* `docs/ <./docs>`_ - Guide on how to get started with SymbiFlow and build provided examples +* `.github/ <./.github>`_ - Directory with CI configuration and scripts -* `xc7 `_ - Example FPGA designs for the Xilinx 7 series of parts: +Please refer to the `project documentation `_ +for a proper guide on how to run these examples. The examples provided by this +repository are automatically built by extracting necessary code snippets with +`tuttest `_. - * Verilog code - * Pin constraints files - * Timing constraints files - * Makefiles for running the SymbiFlow toolchain +Building those docs +------------------- -* `.travis.yml <.travis.yml>`_ - Travis CI configuration file +To build Sphinx documentation, you need at least Python 3.6. You will also need +to install Sphinx v3.3.0 and additional dependencies, which you can get with +``pip``:: -Clone this repository ---------------------- + pip install -r docs/requirements.txt -If you have not already done so, clone this repository and ``cd`` into it: +Next, just run:: -.. code:: bash + make -C docs html - sudo apt install git - git clone https://github.com/SymbiFlow/symbiflow-examples.git && cd symbiflow-examples +The output will be found in the ``docs/_build/html`` directory. +Running "CI" locally +-------------------- -Prerequisites -------------- +The CI uses a bunch of scripts in the `.github/scripts/ <./.github/scripts>`_ +directory to execute the needed tests. You can use the same scripts locally +to test without having to wait for the online CIs to pass if you +want to quickly test stuff. -Install the following prerequisites before using symbiflow-examples: +For this, you will need `tuttest `_, +which you can install with:: -* For Ubuntu: + pip install git+https://github.com/antmicro/tuttest -.. code:: bash - :name: install-req-ubuntu +* ```` is one of ``{eos-s3, xc7}`` (the two currently + covered platforms - EOS-S3 and Xilinx series 7). +* ```` is one of ``{ubuntu, centos}`` (currently supported operating systems). - apt update && apt install -y wget +To install the toolchain (just the first time), run:: -* For CentOS: + .github/scripts/install-toolchain.sh | bash -c "$(cat /dev/stdin)" -.. code:: bash - :name: install-req-centos - - yum install -y wget which - -Toolchain installation ----------------------- - -This section describes how to install the toolchain. This procedure is divided in three steps: - -- Installing the Conda package manager -- Choosing an installation directory -- Downloading the architecture definitions and installing the toolchain - -1. Conda - -.. code:: bash - :name: wget-conda - - wget https://repo.continuum.io/miniconda/Miniconda3-latest-Linux-x86_64.sh -O conda_installer.sh - -2. Choose the install directory - -The install directory can either be in your home directory -such as ``~/opt/symbiflow`` or in a system directory such as ``/opt/symbiflow``. -If you choose a system directory, you will need root permission to perform the installation, -and so you will need to add some ``sudo`` commands to the instructions below. - -.. code:: bash - - INSTALL_DIR=~/opt/symbiflow - -3. Toolchain - -* For the Artix-7 devices: - -.. code:: bash - :name: xc7-setup-toolchain - - bash conda_installer.sh -b -p $INSTALL_DIR/xc7/conda - source "$INSTALL_DIR/xc7/conda/etc/profile.d/conda.sh" - conda env create -f xc7/environment.yml - conda activate xc7 - mkdir -p $INSTALL_DIR/xc7/install - wget -qO- https://storage.googleapis.com/symbiflow-arch-defs/artifacts/prod/foss-fpga-tools/symbiflow-arch-defs/continuous/install/112/20201208-080919/symbiflow-arch-defs-install-7c1267b7.tar.xz | tar -xJC $INSTALL_DIR/xc7/install - wget -qO- https://storage.googleapis.com/symbiflow-arch-defs/artifacts/prod/foss-fpga-tools/symbiflow-arch-defs/continuous/install/112/20201208-080919/symbiflow-arch-defs-xc7a50t_test-7c1267b7.tar.xz | tar -xJC $INSTALL_DIR/xc7/install - wget -qO- https://storage.googleapis.com/symbiflow-arch-defs/artifacts/prod/foss-fpga-tools/symbiflow-arch-defs/continuous/install/112/20201208-080919/symbiflow-arch-defs-xc7a100t_test-7c1267b7.tar.xz | tar -xJC $INSTALL_DIR/xc7/install - wget -qO- https://storage.googleapis.com/symbiflow-arch-defs/artifacts/prod/foss-fpga-tools/symbiflow-arch-defs/continuous/install/112/20201208-080919/symbiflow-arch-defs-xc7z010_test-7c1267b7.tar.xz | tar -xJC $INSTALL_DIR/xc7/install - conda deactivate - -* For the EOS S3 devices: - -.. code:: bash - :name: eos-s3-setup-toolchain - - bash conda_installer.sh -b -p $INSTALL_DIR/eos-s3/conda - source "$INSTALL_DIR/eos-s3/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/EWuqtXJmalROpI2L5XeewMIBRYVCY8H4yc10nlli-Xq79g?download=1 | tar -xJ -C $INSTALL_DIR/eos-s3/ - 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: -**************************************** - -Before building any example, set the installation directory to match what you set it to earlier, - -.. code:: bash - - export INSTALL_DIR=~/opt/symbiflow - -and prepare the environment: - -.. code:: bash - :name: xc7-prepare-env - - # adding symbiflow toolchain binaries to PATH - export PATH="$INSTALL_DIR/xc7/install/bin:$PATH" - source "$INSTALL_DIR/xc7/conda/etc/profile.d/conda.sh" - conda activate xc7 - -To build the counter example, run any or all of the following commands: - -.. code:: bash - :name: xc7-counter - - pushd xc7/counter_test && TARGET="arty_35" make && popd - pushd xc7/counter_test && TARGET="arty_100" make && popd - pushd xc7/counter_test && TARGET="basys3" make && popd - -To build the picosoc example, run the following commands: - -.. code:: bash - :name: xc7-picosoc - - pushd xc7/picosoc_demo && make && popd - -To build the litex example, run the following commands: - -.. code:: bash - :name: xc7-litex - - mkdir xc7/litex_demo - pushd xc7/litex_demo - 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 --sys-clk-freq 80e6 --no-ident-version --build && popd - popd - -To build the linux-litex-demo example, run the following commands: - -.. code:: bash - :name: xc7-linux - - pushd xc7/linux_litex_demo && make && popd - pushd xc7/linux_litex_demo && TARGET="arty_100" make && popd - -Example design for the EOS S3 devices: -************************************** - -Before building any example, set the installation directory to match what you set it to earlier, - -.. code:: bash - - export INSTALL_DIR=~/opt/symbiflow - -and prepare the environment: - -.. code:: bash - :name: eos-s3-prepare-env - - export PATH="$INSTALL_DIR/eos-s3/install/bin:$PATH" - source "$INSTALL_DIR/eos-s3/conda/etc/profile.d/conda.sh" - conda activate eos-s3 - -To build the example, run the following command: - -.. code:: bash - :name: eos-s3-counter - - pushd eos-s3/btn_counter && make && popd +To build all the examples locally, just run:: + .github/scripts/build-examples.sh | bash -c "$(cat /dev/stdin)" diff --git a/README.src.rst b/README.src.rst deleted file mode 100644 index 23e8066..0000000 --- a/README.src.rst +++ /dev/null @@ -1,123 +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: - -* `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 `_ - 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 - -Clone this repository ---------------------- - -If you have not already done so, clone this repository and ``cd`` into it: - -.. code:: bash - - sudo apt install git - git clone https://github.com/SymbiFlow/symbiflow-examples.git && cd symbiflow-examples - - -Prerequisites -------------- - -Install the following prerequisites before using symbiflow-examples: - -* For Ubuntu: - -.. code:: bash - :name: install-req-ubuntu - - apt update && apt install -y wget - -* For CentOS: - -.. code:: bash - :name: install-req-centos - - yum install -y wget which - -Toolchain installation ----------------------- - -This section describes how to install the toolchain. This procedure is divided in three steps: - -- Installing the Conda package manager -- Choosing an installation directory -- Downloading the architecture definitions and installing the toolchain - -1. Conda - -.. code:: bash - :name: wget-conda - - wget https://repo.continuum.io/miniconda/Miniconda3-latest-Linux-x86_64.sh -O conda_installer.sh - -2. Choose the install directory - -The install directory can either be in your home directory -such as ``~/opt/symbiflow`` or in a system directory such as ``/opt/symbiflow``. -If you choose a system directory, you will need root permission to perform the installation, -and so you will need to add some ``sudo`` commands to the instructions below. - -.. code:: bash - - INSTALL_DIR=~/opt/symbiflow - -3. 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: -**************************************** - -.. 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: -************************************** - -.. include:: eos-s3/README.rst - :start-after:.. build_examples_include_begin_label - :end-before:.. build_examples_include_end_label - diff --git a/eos-s3/README.rst b/eos-s3/README.rst deleted file mode 100644 index addcf4a..0000000 --- a/eos-s3/README.rst +++ /dev/null @@ -1,68 +0,0 @@ -SymbiFlow Toolchain Examples for QuickLogic EOS S3 -================================================== - -#. ``btn_counter`` - simple 4-bit counter driving LEDs. The design targets the `EOS S3 FPGA `__. - -Clone this repository ---------------------- -If you have not already done so, clone this repository and `cd` into it: - -.. code:: bash - - sudo apt install git - git clone https://github.com/SymbiFlow/symbiflow-examples.git && cd symbiflow-examples - - -Setting up the toolchain ------------------------- - -Choose the installation directory (see the `README <../README.rst>`_ one level up for details): - - -.. code:: bash - - export INSTALL_DIR=~/opt/symbiflow # or somewhere else you choose - - -.. toolchain_include_begin_label - -.. code:: bash - :name: eos-s3-setup-toolchain - - bash conda_installer.sh -b -p $INSTALL_DIR/eos-s3/conda - source "$INSTALL_DIR/eos-s3/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/EWuqtXJmalROpI2L5XeewMIBRYVCY8H4yc10nlli-Xq79g?download=1 | tar -xJ -C $INSTALL_DIR/eos-s3/ - conda deactivate - -.. toolchain_include_end_label - -Building the examples ---------------------- - -.. build_examples_include_begin_label - -Before building any example, set the installation directory to match what you set it to earlier, - -.. code:: bash - - export INSTALL_DIR=~/opt/symbiflow - -and prepare the environment: - -.. code:: bash - :name: eos-s3-prepare-env - - export PATH="$INSTALL_DIR/eos-s3/install/bin:$PATH" - source "$INSTALL_DIR/eos-s3/conda/etc/profile.d/conda.sh" - conda activate eos-s3 - -To build the example, run the following command: - -.. code:: bash - :name: eos-s3-counter - - pushd eos-s3/btn_counter && make && popd - -.. build_examples_include_end_label