Merge pull request #88 from antmicro/sphinx_docs_cleaned
Add sphinx-based documentation
This commit is contained in:
Tomasz Michalak
GitHub
commit
2bf0a5b2d9
|
|
@ -0,0 +1,97 @@
|
|||
#!/bin/bash
|
||||
#
|
||||
# Copyright (C) 2020 The SymbiFlow Authors.
|
||||
#
|
||||
# Licensed under the Apache License, Version 2.0 (the "License");
|
||||
# you may not use this file except in compliance with the License.
|
||||
# You may obtain a copy of the License at
|
||||
#
|
||||
# https://www.apache.org/licenses/LICENSE-2.0
|
||||
#
|
||||
# Unless required by applicable law or agreed to in writing, software
|
||||
# distributed under the License is distributed on an "AS IS" BASIS,
|
||||
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
# See the License for the specific language governing permissions and
|
||||
# limitations under the License.
|
||||
#
|
||||
# SPDX-License-Identifier: Apache-2.0
|
||||
|
||||
set -e
|
||||
|
||||
CURRENT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )"
|
||||
source ${CURRENT_DIR}/common.sh
|
||||
|
||||
# -- validate input ----------------------------------------------------------
|
||||
|
||||
function help() {
|
||||
echo
|
||||
echo "Build examples from the repository"
|
||||
echo
|
||||
echo "Syntax: $0 fpga_family [examples]..."
|
||||
echo "Arguments:"
|
||||
echo " fpga_family - A supported FPGA family"
|
||||
echo " examples - A name of an available example"
|
||||
echo
|
||||
}
|
||||
|
||||
if [[ ! $# -ge 1 ]]; then
|
||||
echo "Invalid number of arguments!"
|
||||
help
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# -- tuttest -----------------------------------------------------------------
|
||||
|
||||
fpga_family=$1
|
||||
shift
|
||||
|
||||
examples="$@"
|
||||
if [ "$fpga_family" == "xc7" -a -z "$examples" ]; then
|
||||
examples="counter picosoc litex_linux"
|
||||
elif [ "$fpga_family" == "eos-s3" -a -z "$examples" ]; then
|
||||
examples="counter"
|
||||
fi
|
||||
|
||||
# activate conda and enter example dir
|
||||
tuttest_exec docs/building-examples.rst export-install-dir
|
||||
tuttest_exec docs/building-examples.rst fpga-fam-$fpga_family
|
||||
tuttest_exec docs/building-examples.rst conda-prep-env
|
||||
tuttest_exec docs/building-examples.rst conda-act-env
|
||||
tuttest_exec docs/building-examples.rst enter-dir-$fpga_family
|
||||
|
||||
# Xilinx 7-Series examples
|
||||
if [ "$fpga_family" = "xc7" ]; then
|
||||
for example in $examples; do
|
||||
case $example in
|
||||
"counter")
|
||||
tuttest_exec xc7/counter_test/README.rst example-counter-*-group
|
||||
;;
|
||||
"picosoc")
|
||||
tuttest_exec xc7/picosoc_demo/README.rst example-picosoc-*-group
|
||||
;;
|
||||
"litex_linux")
|
||||
tuttest_exec xc7/linux_litex_demo/README.rst example-litex-deps
|
||||
tuttest_exec xc7/linux_litex_demo/README.rst example-litex-*-group
|
||||
;;
|
||||
*)
|
||||
echo "ERROR: Unknown example name: $example"
|
||||
exit 1
|
||||
;;
|
||||
esac
|
||||
done
|
||||
# QuickLogic EOS-S3 examples
|
||||
elif [ "$fpga_family" = "eos-s3" ]; then
|
||||
for example in $examples; do
|
||||
case $example in
|
||||
"counter")
|
||||
tuttest eos-s3/btn_counter/README.rst eos-s3-counter
|
||||
;;
|
||||
*)
|
||||
echo "ERROR: Unknown example name: $example"
|
||||
exit 1
|
||||
;;
|
||||
esac
|
||||
done
|
||||
else
|
||||
echo "ERROR: Unknown fpga_family: $fpga_family"
|
||||
fi
|
||||
|
|
@ -1,19 +1,31 @@
|
|||
# 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
|
||||
#!/bin/bash
|
||||
#
|
||||
# Copyright (C) 2020 The SymbiFlow Authors.
|
||||
#
|
||||
# Licensed under the Apache License, Version 2.0 (the "License");
|
||||
# you may not use this file except in compliance with the License.
|
||||
# You may obtain a copy of the License at
|
||||
#
|
||||
# https://www.apache.org/licenses/LICENSE-2.0
|
||||
#
|
||||
# Unless required by applicable law or agreed to in writing, software
|
||||
# distributed under the License is distributed on an "AS IS" BASIS,
|
||||
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
# See the License for the specific language governing permissions and
|
||||
# limitations under the License.
|
||||
#
|
||||
# SPDX-License-Identifier: Apache-2.0
|
||||
|
||||
SPACER="echo -e ${GRAY} - ${NC}"
|
||||
|
||||
function start_section() {
|
||||
echo -e "${PURPLE}${1}${NC}: $2${NC}"
|
||||
echo -e "${GRAY}-------------------------------------------------------------------${NC}"
|
||||
}
|
||||
|
||||
function end_section() {
|
||||
echo -e "${GRAY}-------------------------------------------------------------------${NC}"
|
||||
function tuttest_exec() {
|
||||
cat << EOF
|
||||
echo
|
||||
echo "==================================================================== "
|
||||
echo "OUTPUT : tuttest $@"
|
||||
echo "EXECUTED COMMAND:"
|
||||
echo
|
||||
echo '$(tuttest $@)'
|
||||
echo "-------------------------------------------------------------------- "
|
||||
echo
|
||||
EOF
|
||||
tuttest "$@"
|
||||
}
|
||||
|
|
|
|||
|
|
@ -1,27 +0,0 @@
|
|||
set -e
|
||||
|
||||
source .github/scripts/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
|
||||
|
|
@ -0,0 +1,53 @@
|
|||
#!/bin/bash
|
||||
#
|
||||
# Copyright (C) 2020 The SymbiFlow Authors.
|
||||
#
|
||||
# Licensed under the Apache License, Version 2.0 (the "License");
|
||||
# you may not use this file except in compliance with the License.
|
||||
# You may obtain a copy of the License at
|
||||
#
|
||||
# https://www.apache.org/licenses/LICENSE-2.0
|
||||
#
|
||||
# Unless required by applicable law or agreed to in writing, software
|
||||
# distributed under the License is distributed on an "AS IS" BASIS,
|
||||
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
# See the License for the specific language governing permissions and
|
||||
# limitations under the License.
|
||||
#
|
||||
# SPDX-License-Identifier: Apache-2.0
|
||||
|
||||
set -e
|
||||
|
||||
CURRENT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )"
|
||||
source ${CURRENT_DIR}/common.sh
|
||||
|
||||
# -- validate input -----------------------------------------------------------
|
||||
|
||||
function help() {
|
||||
echo
|
||||
echo "Install the SymbiFlow toolchain as described in the sphinx documentation"
|
||||
echo
|
||||
echo "Syntax: $0 fpga_family os"
|
||||
echo "Arguments:"
|
||||
echo " fpga_family - A supported FPGA family"
|
||||
echo " os - A supported operating system"
|
||||
echo
|
||||
}
|
||||
|
||||
if [[ ! $# -eq 2 ]]; then
|
||||
echo "ERROR: Invalid number of arguments"
|
||||
help
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# -- tuttest ------------------------------------------------------------------
|
||||
|
||||
fpga_family=$1
|
||||
os=$2
|
||||
|
||||
tuttest_exec docs/getting-symbiflow.rst install-reqs-$os
|
||||
tuttest_exec docs/getting-symbiflow.rst wget-conda
|
||||
tuttest_exec docs/getting-symbiflow.rst conda-install-dir
|
||||
tuttest_exec docs/getting-symbiflow.rst fpga-fam-$fpga_family
|
||||
tuttest_exec docs/getting-symbiflow.rst conda-setup
|
||||
tuttest_exec docs/getting-symbiflow.rst download-arch-def-$fpga_family
|
||||
|
|
@ -1,13 +0,0 @@
|
|||
#!/bin/bash
|
||||
|
||||
function tuttest_exec () {
|
||||
echo " ==================================================================== " 1>&2
|
||||
echo " CMD : tuttest $@ " 1>&2
|
||||
echo " OUTPUT: " 1>&2
|
||||
echo "" 1>&2
|
||||
echo "$(tuttest $@)" 1>&2
|
||||
echo " -------------------------------------------------------------------- " 1>&2
|
||||
echo "" 1>&2
|
||||
|
||||
tuttest "$@"
|
||||
}
|
||||
|
|
@ -0,0 +1,67 @@
|
|||
name: doc-test
|
||||
|
||||
on: [push, pull_request]
|
||||
|
||||
jobs:
|
||||
test-sphinx-docs:
|
||||
runs-on: ubuntu-18.04
|
||||
strategy:
|
||||
fail-fast: false
|
||||
matrix:
|
||||
include:
|
||||
- {fpga-fam: "eos-s3", os: "ubuntu", os-version: "xenial", example: "counter"}
|
||||
- {fpga-fam: "eos-s3", os: "ubuntu", os-version: "bionic", example: "counter"}
|
||||
- {fpga-fam: "eos-s3", os: "ubuntu", os-version: "focal", example: "counter"}
|
||||
- {fpga-fam: "eos-s3", os: "centos", os-version: "7", example: "counter"}
|
||||
- {fpga-fam: "eos-s3", os: "centos", os-version: "8", example: "counter"}
|
||||
|
||||
- {fpga-fam: "xc7", os: "ubuntu", os-version: "xenial", example: "counter"}
|
||||
- {fpga-fam: "xc7", os: "ubuntu", os-version: "bionic", example: "counter"}
|
||||
- {fpga-fam: "xc7", os: "ubuntu", os-version: "focal", example: "counter"}
|
||||
- {fpga-fam: "xc7", os: "centos", os-version: "7", example: "counter"}
|
||||
- {fpga-fam: "xc7", os: "centos", os-version: "8", example: "counter"}
|
||||
|
||||
- {fpga-fam: "xc7", os: "ubuntu", os-version: "xenial", example: "picosoc"}
|
||||
- {fpga-fam: "xc7", os: "ubuntu", os-version: "bionic", example: "picosoc"}
|
||||
- {fpga-fam: "xc7", os: "ubuntu", os-version: "focal", example: "picosoc"}
|
||||
- {fpga-fam: "xc7", os: "centos", os-version: "7", example: "picosoc"}
|
||||
- {fpga-fam: "xc7", os: "centos", os-version: "8", example: "picosoc"}
|
||||
|
||||
- {fpga-fam: "xc7", os: "ubuntu", os-version: "xenial", example: "litex_linux"}
|
||||
- {fpga-fam: "xc7", os: "ubuntu", os-version: "bionic", example: "litex_linux"}
|
||||
- {fpga-fam: "xc7", os: "ubuntu", os-version: "focal", example: "litex_linux"}
|
||||
- {fpga-fam: "xc7", os: "centos", os-version: "7", example: "litex_linux"}
|
||||
- {fpga-fam: "xc7", os: "centos", os-version: "8", example: "litex_linux"}
|
||||
env:
|
||||
LANG: "en_US.UTF-8"
|
||||
DOCKER_NAME: test
|
||||
IN_DOCKER_EXEC: "docker exec -t test bash -e -c"
|
||||
|
||||
steps:
|
||||
- name: Setup repository
|
||||
uses: actions/checkout@v2
|
||||
|
||||
- name: Set Up Python
|
||||
uses: actions/setup-python@v2
|
||||
|
||||
- name: Setup Docker
|
||||
run: |
|
||||
docker create --name $DOCKER_NAME -v $PWD:$PWD --workdir $PWD --tty ${{matrix.os}}:${{matrix.os-version}}
|
||||
docker start $DOCKER_NAME
|
||||
|
||||
- name: Install tuttest
|
||||
run: |
|
||||
sudo locale-gen $LANG
|
||||
pip3 install git+https://github.com/antmicro/tuttest#egg=tuttest
|
||||
|
||||
- name: Install SymbiFlow toolchain
|
||||
run: bash .github/scripts/install-toolchain.sh ${{matrix.fpga-fam}} ${{matrix.os}} | ${IN_DOCKER_EXEC} "$(cat /dev/stdin)"
|
||||
|
||||
- name: Build examples
|
||||
run: bash .github/scripts/build-examples.sh ${{matrix.fpga-fam}} ${{matrix.example}} | ${IN_DOCKER_EXEC} "$(cat /dev/stdin)"
|
||||
|
||||
- uses: actions/upload-artifact@v2
|
||||
with:
|
||||
name: symbiflow-examples-bitstreams
|
||||
path: |
|
||||
**/*.bit
|
||||
|
|
@ -1,83 +0,0 @@
|
|||
name: tuttest
|
||||
on: [push, pull_request]
|
||||
|
||||
jobs:
|
||||
examples:
|
||||
runs-on: ubuntu-18.04
|
||||
strategy:
|
||||
fail-fast: false
|
||||
matrix:
|
||||
include:
|
||||
- {toolchain: "eos-s3", os: "ubuntu", os-version: "xenial", example: "eos-s3-counter"}
|
||||
- {toolchain: "eos-s3", os: "ubuntu", os-version: "bionic", example: "eos-s3-counter"}
|
||||
- {toolchain: "eos-s3", os: "ubuntu", os-version: "focal", example: "eos-s3-counter"}
|
||||
- {toolchain: "eos-s3", os: "centos", os-version: "7", example: "eos-s3-counter"}
|
||||
- {toolchain: "eos-s3", os: "centos", os-version: "8", example: "eos-s3-counter"}
|
||||
|
||||
- {toolchain: "xc7", os: "ubuntu", os-version: "xenial", example: "xc7-counter"}
|
||||
- {toolchain: "xc7", os: "ubuntu", os-version: "bionic", example: "xc7-counter"}
|
||||
- {toolchain: "xc7", os: "ubuntu", os-version: "focal", example: "xc7-counter"}
|
||||
- {toolchain: "xc7", os: "centos", os-version: "7", example: "xc7-counter"}
|
||||
- {toolchain: "xc7", os: "centos", os-version: "8", example: "xc7-counter"}
|
||||
|
||||
- {toolchain: "xc7", os: "ubuntu", os-version: "xenial", example: "xc7-picosoc"}
|
||||
- {toolchain: "xc7", os: "ubuntu", os-version: "bionic", example: "xc7-picosoc"}
|
||||
- {toolchain: "xc7", os: "ubuntu", os-version: "focal", example: "xc7-picosoc"}
|
||||
- {toolchain: "xc7", os: "centos", os-version: "7", example: "xc7-picosoc"}
|
||||
- {toolchain: "xc7", os: "centos", os-version: "8", example: "xc7-picosoc"}
|
||||
|
||||
- {toolchain: "xc7", os: "ubuntu", os-version: "xenial", example: "xc7-litex"}
|
||||
- {toolchain: "xc7", os: "ubuntu", os-version: "bionic", example: "xc7-litex"}
|
||||
- {toolchain: "xc7", os: "ubuntu", os-version: "focal", example: "xc7-litex"}
|
||||
- {toolchain: "xc7", os: "centos", os-version: "7", example: "xc7-litex"}
|
||||
- {toolchain: "xc7", os: "centos", os-version: "8", example: "xc7-litex"}
|
||||
|
||||
- {toolchain: "xc7", os: "ubuntu", os-version: "xenial", example: "xc7-linux"}
|
||||
- {toolchain: "xc7", os: "ubuntu", os-version: "bionic", example: "xc7-linux"}
|
||||
- {toolchain: "xc7", os: "ubuntu", os-version: "focal", example: "xc7-linux"}
|
||||
- {toolchain: "xc7", os: "centos", os-version: "7", example: "xc7-linux"}
|
||||
- {toolchain: "xc7", os: "centos", os-version: "8", example: "xc7-linux"}
|
||||
|
||||
env:
|
||||
LANG: "en_US.UTF-8"
|
||||
DOCKER_NAME: test
|
||||
IN_DOCKER_EXEC: "docker exec -t test bash -ex -c"
|
||||
|
||||
steps:
|
||||
- name: Prepare Repository
|
||||
uses: actions/checkout@v2
|
||||
|
||||
- name: Set Up Python
|
||||
uses: actions/setup-python@v2
|
||||
|
||||
- name: Install Prerequisites
|
||||
run: |
|
||||
sudo locale-gen $LANG
|
||||
pip3 install git+https://github.com/antmicro/tuttest#egg=tuttest dataclasses
|
||||
|
||||
- name: Set Up Docker
|
||||
run: |
|
||||
docker create --name $DOCKER_NAME --env LANG="en_US.UTF-8" --env LANGUAGE="en_US" --env DEBIAN_FRONTEND="noninteractive" --env INSTALL_DIR=~/opt/symbiflow/ -v $PWD:$PWD --workdir $PWD --tty ${{matrix.os}}:${{matrix.os-version}}
|
||||
docker start $DOCKER_NAME
|
||||
|
||||
- name: Test Main README.rst
|
||||
run: |
|
||||
rm README.rst && make README.rst && .github/scripts/git-check.sh
|
||||
|
||||
- name: (tuttest) Install SymbiFlow Toolchain
|
||||
run: |
|
||||
source .github/scripts/tuttest_exec.sh
|
||||
tuttest_exec README.rst install-req-${{matrix.os}} | ${IN_DOCKER_EXEC} "$(cat /dev/stdin)"
|
||||
tuttest_exec README.rst wget-conda | ${IN_DOCKER_EXEC} "$(cat /dev/stdin)"
|
||||
tuttest_exec ${{matrix.toolchain}}/README.rst ${{matrix.toolchain}}-setup-toolchain | ${IN_DOCKER_EXEC} "$(cat /dev/stdin)"
|
||||
|
||||
- name: (tuttest) Test Example
|
||||
run: |
|
||||
source .github/scripts/tuttest_exec.sh
|
||||
tuttest_exec ${{matrix.toolchain}}/README.rst ${{matrix.toolchain}}-prepare-env,${{matrix.example}} | ${IN_DOCKER_EXEC} "$(cat /dev/stdin)"
|
||||
|
||||
- uses: actions/upload-artifact@v2
|
||||
with:
|
||||
path: |
|
||||
**/*.bit
|
||||
!xc7/litex_demo/pythondata-cpu-microwatt/**/*.bit
|
||||
|
|
@ -0,0 +1,31 @@
|
|||
# Copyright (C) 2020 The SymbiFlow Authors.
|
||||
#
|
||||
# Licensed under the Apache License, Version 2.0 (the "License");
|
||||
# you may not use this file except in compliance with the License.
|
||||
# You may obtain a copy of the License at
|
||||
#
|
||||
# https://www.apache.org/licenses/LICENSE-2.0
|
||||
#
|
||||
# Unless required by applicable law or agreed to in writing, software
|
||||
# distributed under the License is distributed on an "AS IS" BASIS,
|
||||
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
# See the License for the specific language governing permissions and
|
||||
# limitations under the License.
|
||||
#
|
||||
# SPDX-License-Identifier: Apache-2.0
|
||||
#
|
||||
|
||||
# .readthedocs.yml
|
||||
# Read the Docs configuration file
|
||||
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
|
||||
|
||||
version: 2
|
||||
|
||||
sphinx:
|
||||
configuration: docs/conf.py
|
||||
fail_on_warning: true
|
||||
|
||||
python:
|
||||
version: 3.7
|
||||
install:
|
||||
- requirements: docs/requirements.txt
|
||||
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://github.com/symbiflow/symbiflow-examples/workflows/sphinx-tuttest/badge.svg?branch=master
|
||||
:target: https://github.com/SymbiFlow/symbiflow-examples/actions
|
||||
|
||||
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
|
||||
|
||||
|
|
@ -0,0 +1,3 @@
|
|||
*.png binary
|
||||
*.gif binary
|
||||
*.jpg binary
|
||||
|
|
@ -0,0 +1 @@
|
|||
_build
|
||||
|
|
@ -0,0 +1,36 @@
|
|||
# Copyright (C) 2020 The SymbiFlow Authors.
|
||||
#
|
||||
# Licensed under the Apache License, Version 2.0 (the "License");
|
||||
# you may not use this file except in compliance with the License.
|
||||
# You may obtain a copy of the License at
|
||||
#
|
||||
# https://www.apache.org/licenses/LICENSE-2.0
|
||||
#
|
||||
# Unless required by applicable law or agreed to in writing, software
|
||||
# distributed under the License is distributed on an "AS IS" BASIS,
|
||||
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
# See the License for the specific language governing permissions and
|
||||
# limitations under the License.
|
||||
#
|
||||
# SPDX-License-Identifier: Apache-2.0
|
||||
#
|
||||
|
||||
# Minimal makefile for Sphinx documentation
|
||||
#
|
||||
# You can set these variables from the command line, and also
|
||||
# from the environment for the first two.
|
||||
SPHINXOPTS ?=
|
||||
SPHINXBUILD ?= sphinx-build
|
||||
SOURCEDIR = .
|
||||
BUILDDIR = _build
|
||||
|
||||
# Put it first so that "make" without argument is like "make help".
|
||||
help:
|
||||
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
||||
|
||||
.PHONY: help Makefile
|
||||
|
||||
# Catch-all target: route all unknown targets to Sphinx using the new
|
||||
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
|
||||
%: Makefile
|
||||
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
||||
|
|
@ -0,0 +1,82 @@
|
|||
Building example designs
|
||||
========================
|
||||
|
||||
Before building any example, set the installation directory to match what you
|
||||
set it to earlier, for example:
|
||||
|
||||
.. code-block:: bash
|
||||
:name: export-install-dir
|
||||
|
||||
export INSTALL_DIR=~/opt/symbiflow
|
||||
|
||||
Select your fpga family:
|
||||
|
||||
.. tabs::
|
||||
|
||||
.. group-tab:: Artix-7
|
||||
|
||||
.. code-block:: bash
|
||||
:name: fpga-fam-xc7
|
||||
|
||||
FPGA_FAM="xc7"
|
||||
|
||||
.. group-tab:: EOS S3
|
||||
|
||||
.. code-block:: bash
|
||||
:name: fpga-fam-eos-s3
|
||||
|
||||
FPGA_FAM="eos-s3"
|
||||
|
||||
Next, prepare the enviroment:
|
||||
|
||||
.. code-block:: bash
|
||||
:name: conda-prep-env
|
||||
|
||||
export PATH="$INSTALL_DIR/$FPGA_FAM/install/bin:$PATH";
|
||||
source "$INSTALL_DIR/$FPGA_FAM/conda/etc/profile.d/conda.sh"
|
||||
|
||||
Finally, enter your working Conda enviroment:
|
||||
|
||||
.. code-block:: bash
|
||||
:name: conda-act-env
|
||||
|
||||
conda activate $FPGA_FAM
|
||||
|
||||
.. note::
|
||||
|
||||
If you don't know how to upload any of the following examples onto your
|
||||
development board, please refer to the Running examples section.
|
||||
|
||||
|
||||
Xilinx 7-Series
|
||||
---------------
|
||||
|
||||
Enter the directory that contains examples for Xilinx 7-Series FPGAs:
|
||||
|
||||
.. code-block:: bash
|
||||
:name: enter-dir-xc7
|
||||
|
||||
cd xc7
|
||||
|
||||
.. jinja:: xc7_counter_test
|
||||
:file: templates/example.jinja
|
||||
|
||||
.. jinja:: xc7_picosoc_demo
|
||||
:file: templates/example.jinja
|
||||
|
||||
.. jinja:: xc7_linux_litex_demo
|
||||
:file: templates/example.jinja
|
||||
|
||||
|
||||
QuickLogic EOS S3
|
||||
-----------------
|
||||
|
||||
Enter the directory that contains examples for QuickLogic EOS S3:
|
||||
|
||||
.. code-block:: bash
|
||||
:name: enter-dir-eos-s3
|
||||
|
||||
cd eos-s3
|
||||
|
||||
.. jinja:: eos-s3_btn_counter
|
||||
:file: templates/example.jinja
|
||||
|
|
@ -0,0 +1,250 @@
|
|||
import os
|
||||
from docutils.core import publish_doctree
|
||||
|
||||
|
||||
full_name_lut = {
|
||||
'a35t': 'Arty 35T',
|
||||
'a100t': 'Arty 100T',
|
||||
'basys3': 'Basys 3',
|
||||
'eos_s3': 'EOS S3',
|
||||
}
|
||||
families = ('xc7', 'eos-s3')
|
||||
|
||||
|
||||
def handle_default_with_literals(block):
|
||||
"""
|
||||
Extracts information from a block that contains literal blocks in
|
||||
its subtree. The text from the block is combined with the contents
|
||||
of the literal blocks. This is used, i.e., when the code is inserted
|
||||
in the text with `` marks.
|
||||
|
||||
Args:
|
||||
block: A block with a literal block in the subtree
|
||||
|
||||
Returns: A dictionary with the extracted information
|
||||
|
||||
"""
|
||||
text = ""
|
||||
for node in block.traverse(include_self=False, condition=lambda x:
|
||||
x.parent.tagname.strip() != 'literal'):
|
||||
tagname = node.tagname.strip()
|
||||
if tagname in ('paragraph',):
|
||||
continue
|
||||
|
||||
if tagname == 'literal':
|
||||
text = text + '``' + node.astext() + '``'
|
||||
else:
|
||||
text = text + node.astext()
|
||||
|
||||
ret = {}
|
||||
ret['type'] = block.tagname.strip()
|
||||
ret['text'] = text
|
||||
|
||||
return ret
|
||||
|
||||
|
||||
def subtree_has_tag(block, tagname):
|
||||
"""
|
||||
Check if the doctree node contains a particular tag in its subtree.
|
||||
|
||||
Args:
|
||||
block: A block that has to be checked
|
||||
tagname: The searched tag
|
||||
|
||||
Returns: True if the subtree contains a node with the tagname or False otherwise.
|
||||
|
||||
"""
|
||||
|
||||
for node in block.traverse(include_self=False):
|
||||
if node.tagname.strip() == tagname:
|
||||
return True
|
||||
|
||||
return False
|
||||
|
||||
|
||||
def handle_title(block):
|
||||
"""
|
||||
Extracts information from a title block (from a README doctree).
|
||||
|
||||
Args:
|
||||
block: A title doctree block
|
||||
|
||||
Returns: A dictionary with the extracted information
|
||||
|
||||
"""
|
||||
|
||||
ret = {
|
||||
'type': 'title',
|
||||
'text': '\n'.join((block.astext(), '~' * 20)),
|
||||
}
|
||||
|
||||
return ret
|
||||
|
||||
|
||||
def handle_img(block):
|
||||
"""
|
||||
Extracts information from an image block (from a README doctree).
|
||||
|
||||
Args:
|
||||
block: An image doctree block
|
||||
|
||||
Returns: A dictionary with the extracted information
|
||||
|
||||
"""
|
||||
|
||||
ret = {}
|
||||
ret['type'] = 'image'
|
||||
ret['uri'] = os.path.join(*block['uri'].split('/')[3:])
|
||||
ret['align'] = block.get('align', 'center')
|
||||
ret['width'] = block.get('width', '100%')
|
||||
|
||||
return ret
|
||||
|
||||
|
||||
def handle_literal_block(block):
|
||||
"""
|
||||
Extracts information from a literal block (from a README doctree).
|
||||
|
||||
Args:
|
||||
block: A literal doctree block
|
||||
|
||||
Returns: A dictionary with the extracted information
|
||||
|
||||
"""
|
||||
|
||||
ret = {}
|
||||
ret['type'] = 'literal_block'
|
||||
ret['text'] = block.astext().split('\n')
|
||||
ret['classes'] = block['classes']
|
||||
|
||||
try:
|
||||
ret['name'] = full_name_lut[''.join(block['names']).split('-')[2]]
|
||||
except:
|
||||
ret['name'] = ''
|
||||
|
||||
return ret
|
||||
|
||||
|
||||
def handle_note(block):
|
||||
"""
|
||||
Extracts information from a note block (from a README doctree).
|
||||
If the block contain literal block in its subtree, the data from that block
|
||||
will also be extracted.
|
||||
|
||||
Args:
|
||||
block: A note doctree block
|
||||
|
||||
Returns: A dictionary with the extracted information
|
||||
|
||||
"""
|
||||
ret = {}
|
||||
ret['type'] = block.tagname.strip()
|
||||
|
||||
if subtree_has_tag(block, 'literal'):
|
||||
for node in block.traverse(condition=lambda x:
|
||||
x.tagname.strip() == 'paragraph'):
|
||||
ret['text'] = handle_default_with_literals(node)['text']
|
||||
else:
|
||||
ret['text'] = block.astext()
|
||||
|
||||
ret['text'] = ret['text'].split('\n')
|
||||
|
||||
return ret
|
||||
|
||||
|
||||
def handle_default(block):
|
||||
"""
|
||||
Extracts information from doctree blocks that need not be handled in
|
||||
a special way. Nevertheless, if the block contains a literal block,
|
||||
the informaton from that block will also be extracted.
|
||||
|
||||
Args:
|
||||
block: A doctree block
|
||||
|
||||
Returns: A dictionary with the extracted information
|
||||
|
||||
"""
|
||||
if subtree_has_tag(block, 'literal'):
|
||||
return handle_default_with_literals(block)
|
||||
|
||||
ret = {}
|
||||
ret['type'] = block.tagname.strip()
|
||||
ret['text'] = block.astext()
|
||||
|
||||
return ret
|
||||
|
||||
|
||||
handle_block_funcs = {
|
||||
'title': handle_title,
|
||||
'image': handle_img,
|
||||
'literal_block': handle_literal_block,
|
||||
'note': handle_note,
|
||||
'default': handle_default,
|
||||
}
|
||||
|
||||
|
||||
def get_blocks(text):
|
||||
"""
|
||||
Get a traversed README doctree
|
||||
|
||||
Args:
|
||||
text: Text of the example's README
|
||||
|
||||
Returns: Returns an iterable containing the README document structure
|
||||
See `traverse` implementation in docutils/nodes.py for more details.
|
||||
|
||||
"""
|
||||
doctree = publish_doctree(text)
|
||||
|
||||
return doctree.traverse(condition=lambda x: x.tagname.strip() != 'document'
|
||||
and x.parent.tagname.strip() != 'note')
|
||||
|
||||
|
||||
def fill_context(text):
|
||||
"""
|
||||
Creates a jinja context dictionary for a SymbiFlow Toolchain usage example.
|
||||
The dictionary contains all the important information from the example's README.
|
||||
|
||||
Args:
|
||||
text: Text of the example's README
|
||||
|
||||
Returns: A context dictionary that should be added to the main jinja_contexts
|
||||
|
||||
"""
|
||||
ret = []
|
||||
|
||||
start_group = False
|
||||
in_group = False
|
||||
for block in get_blocks(text):
|
||||
tagname = block.tagname.strip()
|
||||
|
||||
# do not process those
|
||||
if tagname in ('#text', 'inline', 'literal'):
|
||||
continue
|
||||
|
||||
# try do get handler; if not found, use the default one
|
||||
if tagname not in handle_block_funcs.keys():
|
||||
handler = 'default'
|
||||
else:
|
||||
handler = tagname
|
||||
|
||||
entry = handle_block_funcs[handler](block)
|
||||
|
||||
# internal logic for grouping code blocks into tab groups
|
||||
if tagname == 'literal_block' and 'group' in ''.join(block['names']):
|
||||
if not in_group:
|
||||
start_group = True
|
||||
in_group = True
|
||||
else:
|
||||
start_group = False
|
||||
in_group = True
|
||||
else:
|
||||
in_group = False
|
||||
start_group = False
|
||||
|
||||
entry['start_group'] = start_group
|
||||
entry['in_group'] = in_group
|
||||
|
||||
ret.append(entry)
|
||||
|
||||
return ret
|
||||
|
|
@ -0,0 +1,111 @@
|
|||
#!/usr/bin/env python3
|
||||
# -*- coding: utf-8 -*-
|
||||
#
|
||||
# Copyright (C) 2020 The SymbiFlow Authors.
|
||||
#
|
||||
# Licensed under the Apache License, Version 2.0 (the "License");
|
||||
# you may not use this file except in compliance with the License.
|
||||
# You may obtain a copy of the License at
|
||||
#
|
||||
# https://www.apache.org/licenses/LICENSE-2.0
|
||||
#
|
||||
# Unless required by applicable law or agreed to in writing, software
|
||||
# distributed under the License is distributed on an "AS IS" BASIS,
|
||||
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
# See the License for the specific language governing permissions and
|
||||
# limitations under the License.
|
||||
#
|
||||
# SPDX-License-Identifier: Apache-2.0
|
||||
|
||||
# Configuration file for the Sphinx documentation builder.
|
||||
#
|
||||
# This file only contains a selection of the most common options. For a full
|
||||
# list see the documentation:
|
||||
# https://www.sphinx-doc.org/en/master/usage/configuration.html
|
||||
|
||||
# -- Path setup --------------------------------------------------------------
|
||||
|
||||
# If extensions (or modules to document with autodoc) are in another directory,
|
||||
# add these directories to sys.path here. If the directory is relative to the
|
||||
# documentation root, use os.path.abspath to make it absolute, like shown here.
|
||||
#
|
||||
import os
|
||||
import sys
|
||||
sys.path.insert(0, os.path.abspath('.'))
|
||||
|
||||
# -- Project information -----------------------------------------------------
|
||||
|
||||
project = u'SymbiFlow examples'
|
||||
authors = u'SymbiFlow'
|
||||
copyright = authors + u', 2020'
|
||||
|
||||
# -- General configuration ---------------------------------------------------
|
||||
|
||||
# Add any Sphinx extension module names here, as strings. They can be
|
||||
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
|
||||
# ones.
|
||||
extensions = [
|
||||
'sphinx_tabs.tabs',
|
||||
'sphinxcontrib.jinja',
|
||||
]
|
||||
|
||||
# Add any paths that contain templates here, relative to this directory.
|
||||
templates_path = ['_templates']
|
||||
|
||||
# List of patterns, relative to source directory, that match files and
|
||||
# directories to ignore when looking for source files.
|
||||
# This pattern also affects html_static_path and html_extra_path.
|
||||
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
|
||||
|
||||
|
||||
# -- Options for HTML output -------------------------------------------------
|
||||
|
||||
# The theme to use for HTML and HTML Help pages. See the documentation for
|
||||
# a list of builtin themes.
|
||||
#
|
||||
|
||||
html_show_sourcelink = True
|
||||
html_sidebars = {
|
||||
"**": ["logo-text.html", "globaltoc.html", "localtoc.html", "searchbox.html"]
|
||||
}
|
||||
|
||||
html_theme = 'sphinx_material'
|
||||
html_theme_options = {
|
||||
'nav_title': project,
|
||||
'color_primary': 'deep-purple',
|
||||
'color_accent': 'purple',
|
||||
'repo_name': "symbiflow/symbiflow-examples",
|
||||
'repo_url': 'https://github.com/symbiflow/symbiflow-examples',
|
||||
'globaltoc_depth': 2,
|
||||
'globaltoc_collapse': True
|
||||
}
|
||||
|
||||
# Add any paths that contain custom static files (such as style sheets) here,
|
||||
# relative to this directory. They are copied after the builtin static files,
|
||||
# so a file named "default.css" will overwrite the builtin "default.css".
|
||||
# html_static_path = ['_static']
|
||||
|
||||
|
||||
# -- Collect READMEs from examples --------------------------------------------
|
||||
|
||||
from collect_readmes import full_name_lut, families, fill_context
|
||||
|
||||
jinja_contexts = {}
|
||||
top_dir = os.path.join(os.path.dirname(__file__), '..')
|
||||
for family in families:
|
||||
examples = os.scandir(os.path.join(top_dir, family))
|
||||
for example in examples:
|
||||
if example.is_dir():
|
||||
|
||||
# get README
|
||||
path = os.path.join(top_dir, family, example, 'README.rst')
|
||||
|
||||
# skip if file does not exist
|
||||
if not os.path.isfile(path):
|
||||
continue
|
||||
|
||||
with open(path) as f:
|
||||
text = f.read()
|
||||
|
||||
key = '_'.join((family, example.name))
|
||||
jinja_contexts[key] = {'blocks': fill_context(text)}
|
||||
|
|
@ -0,0 +1,133 @@
|
|||
Getting SymbiFlow
|
||||
=================
|
||||
|
||||
This section describe how to install SymbiFlow and setup a fully working
|
||||
enviroment to later build example desings.
|
||||
|
||||
Prerequisites
|
||||
-------------
|
||||
|
||||
To be able to follow through this tutorial, install the following software:
|
||||
|
||||
.. tabs::
|
||||
|
||||
.. group-tab:: Ubuntu
|
||||
|
||||
.. code-block:: bash
|
||||
:name: install-reqs-ubuntu
|
||||
|
||||
apt update -y
|
||||
apt install -y git wget xz-utils
|
||||
|
||||
.. group-tab:: CentOS
|
||||
|
||||
.. code-block:: bash
|
||||
:name: install-reqs-centos
|
||||
|
||||
yum update -y
|
||||
yum install -y git wget which xz
|
||||
|
||||
|
||||
Next, clone the SymbiFlow examples repository and enter it:
|
||||
|
||||
.. code-block:: bash
|
||||
:name: get-symbiflow
|
||||
|
||||
git clone https://github.com/SymbiFlow/symbiflow-examples
|
||||
cd symbiflow-examples
|
||||
|
||||
Toolchain installation
|
||||
----------------------
|
||||
|
||||
Now we are able to install the SymbiFlow toolchain. This procedure is divided
|
||||
into three steps:
|
||||
|
||||
- installing the Conda package manager,
|
||||
- choosing an installation directory,
|
||||
- downloading the architecture definitions and installing the toolchain.
|
||||
|
||||
Conda
|
||||
~~~~~
|
||||
|
||||
Download Conda installer script:
|
||||
|
||||
.. code-block:: bash
|
||||
:name: wget-conda
|
||||
|
||||
wget https://repo.continuum.io/miniconda/Miniconda3-latest-Linux-x86_64.sh -O conda_installer.sh
|
||||
|
||||
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-block:: bash
|
||||
:name: conda-install-dir
|
||||
|
||||
export INSTALL_DIR=~/opt/symbiflow
|
||||
|
||||
Toolchain
|
||||
~~~~~~~~~
|
||||
|
||||
Select your target FPGA family:
|
||||
|
||||
.. tabs::
|
||||
|
||||
.. group-tab:: Artix-7
|
||||
|
||||
.. code-block:: bash
|
||||
:name: fpga-fam-xc7
|
||||
|
||||
export FPGA_FAM=xc7
|
||||
|
||||
.. group-tab:: EOS S3
|
||||
|
||||
.. code-block:: bash
|
||||
:name: fpga-fam-eos-s3
|
||||
|
||||
export FPGA_FAM=eos-s3
|
||||
|
||||
Next, setup Conda and your system's enviroment:
|
||||
|
||||
.. code-block:: bash
|
||||
:name: conda-setup
|
||||
|
||||
bash conda_installer.sh -u -b -p $INSTALL_DIR/$FPGA_FAM/conda;
|
||||
source "$INSTALL_DIR/$FPGA_FAM/conda/etc/profile.d/conda.sh";
|
||||
conda env create -f $FPGA_FAM/environment.yml
|
||||
|
||||
Download architecture definitions:
|
||||
|
||||
.. tabs::
|
||||
|
||||
.. group-tab:: Artix-7
|
||||
|
||||
.. code-block:: bash
|
||||
:name: download-arch-def-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
|
||||
|
||||
.. group-tab:: EOS-S3
|
||||
|
||||
.. code-block:: bash
|
||||
:name: download-arch-def-eos-s3
|
||||
|
||||
wget -qO- https://quicklogic-my.sharepoint.com/:u:/p/kkumar/EWuqtXJmalROpI2L5XeewMIBRYVCY8H4yc10nlli-Xq79g?download=1 | tar -xJ -C $INSTALL_DIR/eos-s3/
|
||||
|
||||
If the above commands exited without errors, you have successfuly installed and configured your working enviroment.
|
||||
|
||||
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
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 391 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 401 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 369 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 371 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 1.1 MiB |
Binary file not shown.
|
After Width: | Height: | Size: 6.2 MiB |
Binary file not shown.
|
After Width: | Height: | Size: 103 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 58 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 3.7 MiB |
Binary file not shown.
|
After Width: | Height: | Size: 5.4 MiB |
Binary file not shown.
|
After Width: | Height: | Size: 58 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 54 KiB |
|
|
@ -0,0 +1,34 @@
|
|||
Welcome to SymbiFlow examples!
|
||||
==============================
|
||||
|
||||
This guide explains how to get started with SymbiFlow and build example designs
|
||||
from the `SymbiFlow Examples <https://github.com/symbiflow/symbiflow-examples>`_
|
||||
GitHub repository. It currently focuses on the following FPGA families:
|
||||
|
||||
- Artix-7 from Xilinx,
|
||||
- EOS S3 from QuickLogic.
|
||||
|
||||
Follow this guide to:
|
||||
|
||||
- :doc:`install SymbiFlow <getting-symbiflow>` and all of its dependencies,
|
||||
- :doc:`build <building-examples>` and :doc:`upload <running-examples>`
|
||||
example designs onto the devboard of your choice.
|
||||
|
||||
About SymbiFlow
|
||||
---------------
|
||||
|
||||
SymbiFlow is a fully open source toolchain for the development of FPGAs,
|
||||
currently targeting chips from multiple vendors, e.g.:
|
||||
|
||||
- Xilinx 7-Series
|
||||
- Lattice iCE40
|
||||
- Lattice ECP5 FPGAs
|
||||
- QuickLogic EOS S3
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:caption: Sections
|
||||
|
||||
getting-symbiflow
|
||||
building-examples
|
||||
running-examples
|
||||
|
|
@ -0,0 +1,4 @@
|
|||
Sphinx==3.3.0
|
||||
sphinx-material==0.0.32
|
||||
sphinx-tabs==1.3.0
|
||||
sphinx-jinja==1.1.1
|
||||
|
|
@ -0,0 +1,123 @@
|
|||
Running example designs
|
||||
========================
|
||||
|
||||
This section desribes how to properly connect your board.
|
||||
It also helps you configure and run any other software that is necessary to observe results.
|
||||
|
||||
Connecting development boards
|
||||
-----------------------------
|
||||
|
||||
Arty board
|
||||
~~~~~~~~~~
|
||||
|
||||
#. Connect the board to your computer using the USB cable:
|
||||
#. Connect the board to your computer using the Ethernet cable
|
||||
(only if you want to test the LiteX Linux Example)
|
||||
|
||||
.. image:: images/arty-usb-ethernet.png
|
||||
:width: 49%
|
||||
:align: center
|
||||
|
||||
Basys 3 board
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
Connect the Basys3 Board to your computer using the USB cable:
|
||||
|
||||
.. image:: images/basys3-usb.png
|
||||
:width: 49%
|
||||
:align: center
|
||||
|
||||
Connecting to UART
|
||||
------------------
|
||||
|
||||
First check available teletypes with:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
ls -l /dev | grep ttyUSB
|
||||
|
||||
You should see at least one, e.g.:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
crw-rw----+ 1 root plugdev 188, 0 11-06 13:58 ttyUSB0
|
||||
crw-rw----+ 1 root plugdev 188, 1 11-06 13:58 ttyUSB1
|
||||
|
||||
Simply use ``picocom`` to connect:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
picocom -b 115200 --imap lfcrlf /dev/ttyUSB1
|
||||
|
||||
.. warning::
|
||||
|
||||
Substitute ``115200`` with the baud rate that your design uses!
|
||||
|
||||
.. warning::
|
||||
|
||||
Please note that ``/dev/ttyUSB1`` is just an example. The number appearing may change!
|
||||
|
||||
.. note::
|
||||
|
||||
If the picocom is unable to connect to any ``ttyUSBx`` device, you probably don't have appropriate user permissions.
|
||||
On Debian distributions, type the command below to add the user to the ``dialout`` group.
|
||||
This should resolve the missing permissions problem:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo usermod -a -G dialout `whoami`
|
||||
|
||||
Setting up TFTP
|
||||
---------------
|
||||
|
||||
It is assumed that the server is running on port ``6069`` and uses ``/tftp`` directory.
|
||||
|
||||
#. Install tftp with (Ubuntu example):
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo apt install tftpd-hpa
|
||||
|
||||
#. Create a directory for the server:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo mkdir -p /tftp
|
||||
sudo chmod 777 -R /tftp
|
||||
sudo chown tftp -R /tftp
|
||||
|
||||
#. Set up your TFTP configuration with:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
cat << EOF | sudo tee /etc/default/tftpd-hpa
|
||||
TFTP_USERNAME="tftp"
|
||||
TFTP_DIRECTORY="/tftp"
|
||||
TFTP_ADDRESS=":6069"
|
||||
TFTP_OPTIONS="--secure"
|
||||
EOF
|
||||
|
||||
#. Restart the TFTP server:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo systemctl restart tftpd-hpa
|
||||
|
||||
Configuring your network interfaces
|
||||
-----------------------------------
|
||||
|
||||
Check your network interfaces with:
|
||||
|
||||
.. code-block::
|
||||
|
||||
ip link
|
||||
|
||||
Add IPv4 address to you interface:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
ip addr add 192.168.100.100/24 dev eth0
|
||||
|
||||
.. warning::
|
||||
|
||||
``192.169.100.100/24`` and ``eth0`` are just examples!
|
||||
|
|
@ -0,0 +1,51 @@
|
|||
{% for block in blocks -%}
|
||||
|
||||
{% if block.type == 'literal_block' %}
|
||||
|
||||
{% if not block.start_group and not block.in_group %}
|
||||
.. code-block:: {% if 'bash' in block.classes %}bash{% endif %}
|
||||
|
||||
{% for line in block.text -%}
|
||||
{{ line }}
|
||||
{% endfor %}
|
||||
|
||||
{% elif block.start_group %}
|
||||
.. tabs::
|
||||
|
||||
.. group-tab:: {{ block.name }}
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
{% for line in block.text -%}
|
||||
{{ line }}
|
||||
{% endfor %}
|
||||
{% elif block.in_group %}
|
||||
.. group-tab:: {{ block.name }}
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
{% for line in block.text -%}
|
||||
{{ line }}
|
||||
{% endfor %}
|
||||
|
||||
{% endif %}
|
||||
|
||||
{% elif block.type == 'image' %}
|
||||
.. image:: {{ block.uri }}
|
||||
:align: {{ block.align }}
|
||||
:width: {{ block.width }}
|
||||
|
||||
{% elif block.type == 'note' %}
|
||||
.. note::
|
||||
|
||||
{% for line in block.text -%}
|
||||
{{ line }}
|
||||
{% endfor %}
|
||||
|
||||
|
||||
{% else %}
|
||||
{{ block.text }}
|
||||
|
||||
{% endif %}
|
||||
|
||||
{% endfor %}
|
||||
|
|
@ -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
|
||||
|
|
@ -0,0 +1,10 @@
|
|||
Button counter
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
This example design features a simple 4-bit counter driving LEDs. To build the
|
||||
counter example, run the following command:
|
||||
|
||||
.. code-block:: bash
|
||||
:name: eos-s3-counter
|
||||
|
||||
make -C btn_counter
|
||||
|
|
@ -0,0 +1,35 @@
|
|||
Counter test
|
||||
~~~~~~~~~~~~
|
||||
|
||||
This example design features a simple 4-bit counter driving LEDs. To build the
|
||||
counter example, depending on your hardware, run:
|
||||
|
||||
.. code-block:: bash
|
||||
:name: example-counter-a35t-group
|
||||
|
||||
TARGET="arty_35" make -C counter_test
|
||||
|
||||
|
||||
.. code-block:: bash
|
||||
:name: example-counter-a100t-group
|
||||
|
||||
TARGET="arty_100" make -C counter_test
|
||||
|
||||
|
||||
.. code-block:: bash
|
||||
:name: example-counter-basys3-group
|
||||
|
||||
TARGET="basys3" make -C counter_test
|
||||
|
||||
Now you can upload the design with:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
openocd -f ${INSTALL_DIR}/conda/share/openocd/scripts/board/digilent_arty.cfg -c "init; pld load 0 top.bit; exit"
|
||||
|
||||
|
||||
The result should be as follows:
|
||||
|
||||
.. image:: ../../docs/images/counter-example-arty.gif
|
||||
:align: center
|
||||
:width: 50%
|
||||
|
|
@ -0,0 +1,59 @@
|
|||
Linux LiteX demo
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
This example design features a Linix-capable SoC based around VexRiscv soft
|
||||
CPU. It also includes DDR and Ethernet controllers. To build the litex example,
|
||||
run the following commands:
|
||||
|
||||
.. code-block:: bash
|
||||
:name: example-litex-deps
|
||||
|
||||
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, depending on your hardware, run:
|
||||
|
||||
.. code-block:: bash
|
||||
:name: example-litex-a35t-group
|
||||
|
||||
TARGET="arty_35" make -C linux_litex_demo
|
||||
|
||||
.. code-block:: bash
|
||||
:name: example-litex-a100t-group
|
||||
|
||||
TARGET="arty_100" make -C linux_litex_demo
|
||||
|
||||
Now you can upload the design with:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
openocd -f ${INSTALL_DIR}/conda/share/openocd/scripts/board/digilent_arty.cfg -c "init; pld load 0 top.bit; exit"
|
||||
|
||||
.. note::
|
||||
|
||||
LiteX on Linux demo excepts you to use IPv4 address of ``192.168.100.100/24``
|
||||
on your network interface.
|
||||
|
||||
You should observe the following line in the OpenOCD output
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
Info : JTAG tap: xc7.tap tap/device found: 0x0362d093 (mfg: 0x049 (Xilinx), part: 0x362d, ver: 0x0)
|
||||
|
||||
In the ``picocom`` terminal, you should observe the following output:
|
||||
|
||||
.. image:: ../../docs/images/linux-example-console.gif
|
||||
:align: center
|
||||
:width: 80%
|
||||
|
||||
Additionally, two LED's on the board should be turned on
|
||||
|
||||
.. image:: ../../docs/images/linux-example-arty.jpg
|
||||
:width: 49%
|
||||
:align: center
|
||||
|
|
@ -0,0 +1,54 @@
|
|||
PicoSoC demo
|
||||
~~~~~~~~~~~~
|
||||
|
||||
This example features a picorv32 soft CPU and a SoC based on it. To build the
|
||||
picosoc example, run the following commands:
|
||||
|
||||
.. code-block:: bash
|
||||
:name: example-picosoc-basys3-group
|
||||
|
||||
TARGET="basys3" make -C picosoc_demo
|
||||
|
||||
Now you can upload the design with:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
openocd -f ${INSTALL_DIR}/conda/share/openocd/scripts/board/digilent_arty.cfg -c "init; pld load 0 top.bit; exit"
|
||||
|
||||
|
||||
You should observe the following line in the OpenOCD output:
|
||||
|
||||
.. code-block::
|
||||
|
||||
Info : JTAG tap: xc7.tap tap/device found: 0x0362d093 (mfg: 0x049 (Xilinx), part: 0x362d, ver: 0x0)
|
||||
|
||||
The UART output should look as follows:
|
||||
|
||||
.. code-block::
|
||||
|
||||
Terminal ready
|
||||
Press ENTER to continue..
|
||||
Press ENTER to continue..
|
||||
Press ENTER to continue..
|
||||
Press ENTER to continue..
|
||||
|
||||
____ _ ____ ____
|
||||
| _ \(_) ___ ___/ ___| ___ / ___|
|
||||
| |_) | |/ __/ _ \___ \ / _ \| |
|
||||
| __/| | (_| (_) |__) | (_) | |___
|
||||
|_| |_|\___\___/____/ \___/ \____|
|
||||
|
||||
|
||||
[9] Run simplistic benchmark
|
||||
|
||||
Command>
|
||||
|
||||
.. note::
|
||||
|
||||
PicoSoC uses baud rate of ``460800`` by default.
|
||||
|
||||
The board's LED should blink at a regular rate from left to the right
|
||||
|
||||
.. image:: ../../docs/images/picosoc-example-basys3.gif
|
||||
:width: 49%
|
||||
:align: center
|
||||
Loading…
Reference in New Issue