From 1fc306b147175d4163ae6ec3c48a4613699e1b1e Mon Sep 17 00:00:00 2001 From: Rick Altherr Date: Mon, 5 Feb 2018 16:07:16 -0800 Subject: [PATCH 1/3] docs: Initial setup for Sphinx-based documentation Signed-off-by: Rick Altherr --- docs/.gitignore | 1 + docs/Makefile | 20 ++++++ docs/conf.py | 179 ++++++++++++++++++++++++++++++++++++++++++++++++ docs/index.rst | 19 +++++ 4 files changed, 219 insertions(+) create mode 100644 docs/.gitignore create mode 100644 docs/Makefile create mode 100644 docs/conf.py create mode 100644 docs/index.rst diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 00000000..e35d8850 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1 @@ +_build diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000..d8bf25c3 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +SPHINXPROJ = ProjectX-Ray +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) \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 00000000..9d14b725 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,179 @@ +# -*- coding: utf-8 -*- +# +# Project X-Ray documentation build configuration file, created by +# sphinx-quickstart on Mon Feb 5 11:04:37 2018. +# +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import os +import re + +# 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('.')) + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.0' + +# 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.ext.imgmath', 'sphinx.ext.autodoc', 'sphinx.ext.doctest', + 'sphinx.ext.autosummary', 'sphinx.ext.napoleon', 'sphinx.ext.todo' +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +# source_suffix = ['.rst', '.md'] +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'Project X-Ray' +copyright = u'2018, SymbiFlow Team' +author = u'SymbiFlow Team' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The full version, including alpha/beta/rc tags. +release = re.sub('^v', '', os.popen('git describe ').read().strip()) +# The short X.Y version. +version = release + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This patterns also effect to html_static_path and html_extra_path +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = True + +# -- Options for HTML output ---------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'sphinx_rtd_theme' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# +# html_theme_options = {} + +# Enable github links when not on readthedocs +on_rtd = os.environ.get('READTHEDOCS', None) == 'True' +if not on_rtd: + html_context = { + "display_github": True, # Integrate GitHub + "github_user": "symbiflow", # Username + "github_repo": "prjxray", # Repo name + "github_version": "master", # Version + "conf_py_path": "/doc/", + } + +# 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'] + +# Custom sidebar templates, must be a dictionary that maps document names +# to template names. +# +# This is required for the alabaster theme +# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars +html_sidebars = { + '**': [ + 'relations.html', # needs 'show_related': True theme option to display + 'searchbox.html', + ] +} + +# -- Options for HTMLHelp output ------------------------------------------ + +# Output file base name for HTML help builder. +htmlhelp_basename = 'prjxray' + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + ( + master_doc, 'ProjectX-Ray.tex', u'Project X-Ray Documentation', + u'SymbiFlow Team', 'manual'), +] + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'projectx-ray', u'Project X-Ray Documentation', [author], 1) +] + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + ( + master_doc, 'ProjectX-Ray', u'Project X-Ray Documentation', author, + 'ProjectX-Ray', 'One line description of project.', 'Miscellaneous'), +] + +# Example configuration for intersphinx: refer to the Python standard library. +intersphinx_mapping = {'https://docs.python.org/': None} diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 00000000..0f4b2898 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,19 @@ +.. Project X-Ray documentation master file, created by + sphinx-quickstart on Mon Feb 5 11:04:37 2018. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to Project X-Ray +========================================= + +`Project X-Ray`_ documents the `Xilinx`_ 7-Series FPGA architecture to enable +development of open-source tools. Our goal is to provide sufficient information +to develop a free and open Verilog to bitstream toolchain for these devices. + +.. _Project X-Ray: https://github.com/SymbiFlow/prjxray +.. _Xilinx: http://www.xilinx.com/ + +.. toctree:: + :maxdepth: 2 + :caption: Xilinx 7-series Architecture + From dd5305a2717ae82423345818ba4e0f0e3baaf936 Mon Sep 17 00:00:00 2001 From: Rick Altherr Date: Mon, 5 Feb 2018 16:08:20 -0800 Subject: [PATCH 2/3] docs: Define some terms Tried to merge definitions from wiki/Glossary and my understandings of terms related to architecture and configuration. Signed-off-by: Rick Altherr --- docs/architecture/glossary.rst | 67 ++++++++++++++++++++++++++++++++++ docs/index.rst | 1 + 2 files changed, 68 insertions(+) create mode 100644 docs/architecture/glossary.rst diff --git a/docs/architecture/glossary.rst b/docs/architecture/glossary.rst new file mode 100644 index 00000000..ab798595 --- /dev/null +++ b/docs/architecture/glossary.rst @@ -0,0 +1,67 @@ +Glossary +======================== + +.. glossary:: + + basic element + BEL + basic logic element + BLE + For example a LUT5, LUT6, CARRY4, or MUX, but not PIPs. + + BELs come in two types: + + * Basic BEL - A logic unit which does things. + * Routing BEL - A unit which is statically configured at the routing time. + + + bitstream + Binary data that is directly loaded into an FPGA to perform configuration. + Contains configuration :term:`frames ` as well as programming + sequences and other commands required to load and activate same. + + column + Collection of :term:`tiles ` physically organized as a vertical line. + + configurable logic block + CLB + Basic building block of logic. + + frame + Fundamental unit of configuration data consisting of 101 :term:`words `. + + half + Portion of a device defined by a virtual line dividing the two sets of global + clock buffers present in a device. The two halves are simply referred to as + the top and bottom halves. + + node + Collection of :term:`wires ` spanning one or more tiles. + + programmable interconnect point + PIP + Connection point between two wires in a tile that may be enabled or + disabled by the configuration. + + horizontal clock row + Portion of a device including 12 horizontal clocks and the 50 interconnect + and function tiles associated with them. A :term:`half` contains one or + more horizontal clock rows and each half may have a different number of + rows. + + site + Portion of a tile where :term:`BELs ` can be placed. :term:`Slices + ` in a :term:`CLB` tile are sites. + + slice + Portion of a :term:`CLB` tile that contains :term:`BELs `. + + tile + Fundamental unit of physical structure containing a single type of + resource or function. + + wire + Physical wire within a :term:`tile`. + + word + 32-bits stored in big-endian order. Fundamental unit of :term:`bitstream` format. diff --git a/docs/index.rst b/docs/index.rst index 0f4b2898..51041785 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -17,3 +17,4 @@ to develop a free and open Verilog to bitstream toolchain for these devices. :maxdepth: 2 :caption: Xilinx 7-series Architecture + architecture/glossary From beb8e0bcf98eca075a1a8cda8a666658f5661347 Mon Sep 17 00:00:00 2001 From: Rick Altherr Date: Mon, 5 Feb 2018 16:10:11 -0800 Subject: [PATCH 3/3] docs: overview of 7-Series architecture Describes the top-level physical structure. Signed-off-by: Rick Altherr --- docs/architecture/overview.rst | 33 +++++++++++++++++++++++++++++++++ docs/index.rst | 1 + 2 files changed, 34 insertions(+) create mode 100644 docs/architecture/overview.rst diff --git a/docs/architecture/overview.rst b/docs/architecture/overview.rst new file mode 100644 index 00000000..fb58e60b --- /dev/null +++ b/docs/architecture/overview.rst @@ -0,0 +1,33 @@ +.. _architecture_overview-label: + +Overview +======== + +.. todo:: add diagrams. + +Xilinx 7-Series architecture utilizes a hierarchical design of chainable +structures to scale across the Spartan, Artix, Kintex, and Virtex product +lines. This documentation focuses on the Artix and Kintex devices and omits +some concepts introduced in Virtex devices. + +At the top-level, 7-Series devices are divided into two :term:`halves ` +by a virtual horizontal line separating two sets of global clock buffers +(BUFGs). While global clocks can be connected such that they span both sets of +BUFGs, the two halves defined by this division are treated as separate entities +as related to configuration. The halves are referred to simply as the top and +bottom halves. + +Each halves is next divided vertically into one or more :term:`horizontal clock +rows `, numbered outward from the global clock buffer +dividing line. Each horizontal clock row contains 12 clock lines that extend +across the device perpendicular to the global clock spine. Similar to the +global clock spine, each horizontal clock row is divided into two halves by two +sets of horizontal clock buffers (BUFHs), one on each side of the global clock +spine, yielding two :term:`clock domains `. Horizontal clocks +may be used within a single clock domain, connected to span both clock domains +in a horizontal clock row, or connected to global clocks. + +Clock domains have a fixed height of 50 :term:`interconnect tiles +` centered around the horizontal clock lines (25 above, 25 +below). Various function tiles, such as :term:`CLBs `, are attached to interconnect +tiles. diff --git a/docs/index.rst b/docs/index.rst index 51041785..78c1bd01 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -17,4 +17,5 @@ to develop a free and open Verilog to bitstream toolchain for these devices. :maxdepth: 2 :caption: Xilinx 7-series Architecture + architecture/overview architecture/glossary