From d6d6951496b196254b163a9b71ed0b777cf7cbfc Mon Sep 17 00:00:00 2001 From: Xifan Tang Date: Thu, 13 Sep 2018 15:38:41 -0600 Subject: [PATCH] Adding documentation --- docs/Makefile | 19 ++ docs/make.bat | 35 ++++ docs/source/arch_lang/define_phy_modules.rst | 4 + docs/source/arch_lang/index.rst | 13 ++ docs/source/arch_lang/link_phy_modules.rst | 2 + docs/source/arch_lang/multimode_support.rst | 2 + docs/source/conf.py | 173 ++++++++++++++++++ docs/source/contact.rst | 7 + .../fpga_bitstream/command_line_usage.rst | 2 + .../fpga_bitstream/file_organization.rst | 2 + docs/source/fpga_bitstream/index.rst | 11 ++ docs/source/fpga_spice/command_line_usage.rst | 2 + docs/source/fpga_spice/file_organization.rst | 2 + docs/source/fpga_spice/index.rst | 12 ++ docs/source/fpga_spice/spice_simulation.rst | 2 + .../fpga_verilog/command_line_usage.rst | 2 + .../source/fpga_verilog/file_organization.rst | 2 + docs/source/fpga_verilog/func_verify.rst | 2 + docs/source/fpga_verilog/index.rst | 15 ++ docs/source/fpga_verilog/sc_flow.rst | 2 + docs/source/index.rst | 47 +++++ docs/source/reference.rst | 5 + docs/source/tutorials/index.rst | 8 + docs/source/z_reference.bib | 29 +++ 24 files changed, 400 insertions(+) create mode 100644 docs/Makefile create mode 100644 docs/make.bat create mode 100644 docs/source/arch_lang/define_phy_modules.rst create mode 100644 docs/source/arch_lang/index.rst create mode 100644 docs/source/arch_lang/link_phy_modules.rst create mode 100644 docs/source/arch_lang/multimode_support.rst create mode 100644 docs/source/conf.py create mode 100644 docs/source/contact.rst create mode 100644 docs/source/fpga_bitstream/command_line_usage.rst create mode 100644 docs/source/fpga_bitstream/file_organization.rst create mode 100644 docs/source/fpga_bitstream/index.rst create mode 100644 docs/source/fpga_spice/command_line_usage.rst create mode 100644 docs/source/fpga_spice/file_organization.rst create mode 100644 docs/source/fpga_spice/index.rst create mode 100644 docs/source/fpga_spice/spice_simulation.rst create mode 100644 docs/source/fpga_verilog/command_line_usage.rst create mode 100644 docs/source/fpga_verilog/file_organization.rst create mode 100644 docs/source/fpga_verilog/func_verify.rst create mode 100644 docs/source/fpga_verilog/index.rst create mode 100644 docs/source/fpga_verilog/sc_flow.rst create mode 100644 docs/source/index.rst create mode 100644 docs/source/reference.rst create mode 100644 docs/source/tutorials/index.rst create mode 100644 docs/source/z_reference.bib diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 000000000..69fe55ecf --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,19 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +SOURCEDIR = source +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/make.bat b/docs/make.bat new file mode 100644 index 000000000..543c6b13b --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% + +:end +popd diff --git a/docs/source/arch_lang/define_phy_modules.rst b/docs/source/arch_lang/define_phy_modules.rst new file mode 100644 index 000000000..75dc52aab --- /dev/null +++ b/docs/source/arch_lang/define_phy_modules.rst @@ -0,0 +1,4 @@ +Define a physical module for FPGA SPICE, Verilog and Bitstream Generator +======================================================================== + + diff --git a/docs/source/arch_lang/index.rst b/docs/source/arch_lang/index.rst new file mode 100644 index 000000000..1d6efbad4 --- /dev/null +++ b/docs/source/arch_lang/index.rst @@ -0,0 +1,13 @@ +.. _arch_lang: + Extended FPGA Architecture Description Language + +.. toctree:: + :maxdepth: 2 + + define_phy_modules + + link_phy_modules + + multimode_support + + diff --git a/docs/source/arch_lang/link_phy_modules.rst b/docs/source/arch_lang/link_phy_modules.rst new file mode 100644 index 000000000..573f5971c --- /dev/null +++ b/docs/source/arch_lang/link_phy_modules.rst @@ -0,0 +1,2 @@ +Link defined physical modules to the original VPR architecture description +========================================================================== diff --git a/docs/source/arch_lang/multimode_support.rst b/docs/source/arch_lang/multimode_support.rst new file mode 100644 index 000000000..64b04d3d2 --- /dev/null +++ b/docs/source/arch_lang/multimode_support.rst @@ -0,0 +1,2 @@ +Modeling Physical Design of Multi-mode Configurable Logic Block Architectures +============================================================================= diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 000000000..df04d1daf --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,173 @@ +# -*- coding: utf-8 -*- +# +# Configuration file for the Sphinx documentation builder. +# +# This file does only contain a selection of the most common options. For a +# full list see the documentation: +# http://www.sphinx-doc.org/en/master/config + +# -- 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'OpenFPGA' +copyright = u'2018, Xifan Tang' +author = u'Xifan Tang' + +# The short X.Y version +version = u'' +# The full version, including alpha/beta/rc tags +release = u'1.0' + + +# -- 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 = [ +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['ytemplates'] + +# 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' + +# 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 pattern also affects html_static_path and html_extra_path. +exclude_patterns = [] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = None + + +# -- 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 = 'alabaster' + +# 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 = {} + +# 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 = ['ystatic'] + +# Custom sidebar templates, must be a dictionary that maps document names +# to template names. +# +# The default sidebars (for documents that don't match any pattern) are +# defined by theme itself. Builtin themes are using these templates by +# default: ``['localtoc.html', 'relations.html', 'sourcelink.html', +# 'searchbox.html']``. +# +# html_sidebars = {} + + +# -- Options for HTMLHelp output --------------------------------------------- + +# Output file base name for HTML help builder. +htmlhelp_basename = 'OpenFPGAdoc' + + +# -- 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, 'OpenFPGA.tex', u'OpenFPGA Documentation', + u'Xifan Tang', '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, 'openfpga', u'OpenFPGA 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, 'OpenFPGA', u'OpenFPGA Documentation', + author, 'OpenFPGA', 'One line description of project.', + 'Miscellaneous'), +] + + +# -- Options for Epub output ------------------------------------------------- + +# Bibliographic Dublin Core info. +epub_title = project + +# The unique identifier of the text. This can be a ISBN number +# or the project homepage. +# +# epub_identifier = '' + +# A unique identification for the text. +# +# epub_uid = '' + +# A list of files that should not be packed into the epub file. +epub_exclude_files = ['search.html'] \ No newline at end of file diff --git a/docs/source/contact.rst b/docs/source/contact.rst new file mode 100644 index 000000000..4c4f54352 --- /dev/null +++ b/docs/source/contact.rst @@ -0,0 +1,7 @@ +.. _contact: + +Contact +======= + +Prof. Pierre-Emmanuel Gaillardon +pierre-emmanuel.gaillardon@utah.edu diff --git a/docs/source/fpga_bitstream/command_line_usage.rst b/docs/source/fpga_bitstream/command_line_usage.rst new file mode 100644 index 000000000..c4b297d28 --- /dev/null +++ b/docs/source/fpga_bitstream/command_line_usage.rst @@ -0,0 +1,2 @@ +Command-line Options for FPGA Bitstream Generator +================================================= diff --git a/docs/source/fpga_bitstream/file_organization.rst b/docs/source/fpga_bitstream/file_organization.rst new file mode 100644 index 000000000..5a538703e --- /dev/null +++ b/docs/source/fpga_bitstream/file_organization.rst @@ -0,0 +1,2 @@ +Bistream Output File Format +============================ diff --git a/docs/source/fpga_bitstream/index.rst b/docs/source/fpga_bitstream/index.rst new file mode 100644 index 000000000..31f4e4e98 --- /dev/null +++ b/docs/source/fpga_bitstream/index.rst @@ -0,0 +1,11 @@ +.. _fpga_bistream: + User Manual for FPGA Bitstream Generator + +.. toctree:: + :maxdepth: 2 + + command_line_usage + + file_organization + + diff --git a/docs/source/fpga_spice/command_line_usage.rst b/docs/source/fpga_spice/command_line_usage.rst new file mode 100644 index 000000000..c4b297d28 --- /dev/null +++ b/docs/source/fpga_spice/command_line_usage.rst @@ -0,0 +1,2 @@ +Command-line Options for FPGA Bitstream Generator +================================================= diff --git a/docs/source/fpga_spice/file_organization.rst b/docs/source/fpga_spice/file_organization.rst new file mode 100644 index 000000000..5a538703e --- /dev/null +++ b/docs/source/fpga_spice/file_organization.rst @@ -0,0 +1,2 @@ +Bistream Output File Format +============================ diff --git a/docs/source/fpga_spice/index.rst b/docs/source/fpga_spice/index.rst new file mode 100644 index 000000000..873321720 --- /dev/null +++ b/docs/source/fpga_spice/index.rst @@ -0,0 +1,12 @@ +.. _fpga_spice: + User Manual for FPGA-SPICE support + +.. toctree:: + :maxdepth: 2 + + command_line_usage + + file_organization + + spice_simulation + diff --git a/docs/source/fpga_spice/spice_simulation.rst b/docs/source/fpga_spice/spice_simulation.rst new file mode 100644 index 000000000..0156f38d5 --- /dev/null +++ b/docs/source/fpga_spice/spice_simulation.rst @@ -0,0 +1,2 @@ +Run SPICE simulation +==================== diff --git a/docs/source/fpga_verilog/command_line_usage.rst b/docs/source/fpga_verilog/command_line_usage.rst new file mode 100644 index 000000000..c4b297d28 --- /dev/null +++ b/docs/source/fpga_verilog/command_line_usage.rst @@ -0,0 +1,2 @@ +Command-line Options for FPGA Bitstream Generator +================================================= diff --git a/docs/source/fpga_verilog/file_organization.rst b/docs/source/fpga_verilog/file_organization.rst new file mode 100644 index 000000000..5a538703e --- /dev/null +++ b/docs/source/fpga_verilog/file_organization.rst @@ -0,0 +1,2 @@ +Bistream Output File Format +============================ diff --git a/docs/source/fpga_verilog/func_verify.rst b/docs/source/fpga_verilog/func_verify.rst new file mode 100644 index 000000000..67b0c8808 --- /dev/null +++ b/docs/source/fpga_verilog/func_verify.rst @@ -0,0 +1,2 @@ +Perform Functionality Verification +================================== diff --git a/docs/source/fpga_verilog/index.rst b/docs/source/fpga_verilog/index.rst new file mode 100644 index 000000000..984e17347 --- /dev/null +++ b/docs/source/fpga_verilog/index.rst @@ -0,0 +1,15 @@ +.. _fpga_verilog: + User Manual for FPGA Verilog Generator + +.. toctree:: + :maxdepth: 2 + + command_line_usage + + file_organization + + func_verify + + sc_flow + + diff --git a/docs/source/fpga_verilog/sc_flow.rst b/docs/source/fpga_verilog/sc_flow.rst new file mode 100644 index 000000000..04fc2f658 --- /dev/null +++ b/docs/source/fpga_verilog/sc_flow.rst @@ -0,0 +1,2 @@ +From Verilog to Layout +====================== diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 000000000..7075278c8 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,47 @@ +.. OpenFPGA documentation master file, created by + sphinx-quickstart on Thu Sep 13 12:15:14 2018. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to OpenFPGA's documentation! +==================================== + +For more information on the ABC see :ref:`ABC`. +For more information on the VPR see :ref:`VTR` +For more information on the original FPGA architecture description language see :ref:`fpga_arch_description` + +.. toctree:: + :maxdepth: 2 + :caption: Extended Architecture Description Language + + arch_lang/index + +.. toctree:: + :maxdepth: 2 + :caption: OpenFPGA VPR Usage + fpga_spice/index + fpga_verilog/index + fpga_bitstream/index + +.. toctree:: + :maxdepth: 2 + :caption: Tutorial + tutorials/index + +.. toctree:: + :maxdepths: 2 + :caption: Appendix + + contact + references + + + + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/docs/source/reference.rst b/docs/source/reference.rst new file mode 100644 index 000000000..47ba3edd5 --- /dev/null +++ b/docs/source/reference.rst @@ -0,0 +1,5 @@ +Publications & References +======================== + +.. bibilography:: z_reference.bib + :all: diff --git a/docs/source/tutorials/index.rst b/docs/source/tutorials/index.rst new file mode 100644 index 000000000..667328646 --- /dev/null +++ b/docs/source/tutorials/index.rst @@ -0,0 +1,8 @@ +.. _tutorials: + Tutorials + +.. toctree:: + :maxdepth: 2 + + + diff --git a/docs/source/z_reference.bib b/docs/source/z_reference.bib new file mode 100644 index 000000000..7ac078638 --- /dev/null +++ b/docs/source/z_reference.bib @@ -0,0 +1,29 @@ +% This should the last document processed by sphinx (to resolve all citations). hence +% the z_ prefix to the filename + +@INPROCEEDINGS{XTang_ICCD_2015, +author={X. Tang and P. Gaillardon and G. De Micheli}, +booktitle={2015 33rd IEEE International Conference on Computer Design (ICCD)}, +title={FPGA-SPICE: A simulation-based power estimation framework for FPGAs}, +year={2015}, +volume={}, +number={}, +pages={696-703}, +keywords={circuit simulation;field programmable gate arrays;logic design;power consumption;SPICE;table lookup;flip-flops;global routing architecture;circuit elements;grid-level testbenches;full-chip-level testbenches;component-level testbenches;architectural description language;LUTs;FPGAs routing multiplexers;look up tables;power consumption;analytical power models;probabilistic activity estimation;field programmable gate array;simulation-based power estimation framework;FPGA-SPICE;Field programmable gate arrays;Routing;Integrated circuit modeling;Estimation;SPICE;Table lookup}, +doi={10.1109/ICCD.2015.7357183}, +ISSN={}, +month={Oct},} + +@ARTICLE{XTang_JETCAS_2018, +author={X. Tang and E. Giacomin and G. De Micheli and P. Gaillardon}, +journal={IEEE Journal on Emerging and Selected Topics in Circuits and Systems}, +title={Post-P amp;R Performance and Power Analysis for RRAM-Based FPGAs}, +year={2018}, +volume={8}, +number={3}, +pages={639-650}, +keywords={Field programmable gate arrays;Random access memory;Analytical models;Delays;Resistance;Routing;Programmable logic arrays;resistive ram;simulation;system modeling;integrated circuit reliability}, +doi={10.1109/JETCAS.2018.2847600}, +ISSN={2156-3357}, +month={Sept},} +