readme: Remove README-based documentation structure
Signed-off-by: Filip Kokosinski <fkokosinski@antmicro.com>
This commit is contained in:
Filip Kokosinski
Robert Winkler
parent
2fbbf647db
commit
54c9beac6e
5
Makefile
5
Makefile
|
|
@ -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
|
||||
218
README.rst
218
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 </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 </xc7>`_ - Example FPGA designs for the Xilinx 7 series of parts:
|
||||
Please refer to the `project documentation <https://symbiflow-examples.readthedocs.io>`_
|
||||
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 <https://github.com/antmicro/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 <https://github.com/antmicro/tuttest/>`_,
|
||||
which you can install with::
|
||||
|
||||
* For Ubuntu:
|
||||
pip install git+https://github.com/antmicro/tuttest
|
||||
|
||||
.. code:: bash
|
||||
:name: install-req-ubuntu
|
||||
* ``<fpga-family>`` is one of ``{eos-s3, xc7}`` (the two currently
|
||||
covered platforms - EOS-S3 and Xilinx series 7).
|
||||
* ``<os>`` 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 <fpga-family> <os> | 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 <fpga-family> | bash -c "$(cat /dev/stdin)"
|
||||
|
|
|
|||
123
README.src.rst
123
README.src.rst
|
|
@ -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 </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
|
||||
|
||||
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
|
||||
|
||||
|
|
@ -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 <https://www.quicklogic.com/products/eos-s3/>`__.
|
||||
|
||||
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
|
||||
Loading…
Reference in New Issue