Commit 259ecee3 authored by Dimitris Lampridis's avatar Dimitris Lampridis Committed by Federico Vaga

doc: import gateware documentation starting point

Signed-off-by: Federico Vaga's avatarFederico Vaga <federico.vaga@cern.ch>
parent 00b79fa3
*~
*.aux
*.cp
*.cps
*.fn
*.fns
*.html
*.info
*.ky
*.log
/*.pdf
*.pg
*.texi
*.toc
*.tp
/*.txt
*.vr
build_env
_build
# Minimal makefile for Sphinx documentation
#
# You can set these variables from the command line.
SPHINXOPTS =
SPHINXBUILD = sphinx-build
SPHINXPROJ = FMCADC100M14bit4Channel
# 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
......@@ -17,4 +17,4 @@ help:
# 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
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# Configuration file for the Sphinx documentation builder.
#
# FMC ADC 100M 14 bit 4 Channel documentation build configuration file, created by
# sphinx-quickstart on Thu Jan 25 09:54:50 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.
# 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
......@@ -22,22 +15,11 @@
# sys.path.insert(0, os.path.abspath('.'))
# -- General configuration ------------------------------------------------
# -- Project information -----------------------------------------------------
# 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.autodoc',
'sphinx.ext.todo',
'sphinx.ext.coverage',
'sphinx.ext.graphviz',]
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
project = 'FMC-ADC-100M-14B-4CHA'
copyright = u'2013-2020, CERN, documentation released under CC-BY-SA-4.0'
author = 'Matthieu Cattin, Dimitris Lampridis <dimitrios.lampridis@cern.ch>, Federico Vaga <federico.vaga@cern.ch>'
# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
......@@ -48,148 +30,69 @@ source_suffix = '.rst'
# The master toctree document.
master_doc = 'index'
# General information about the project.
project = 'FMC ADC 100M 14 bit 4 Channel'
copyright = '2018, Federico Vaga <federico.vaga@cern.ch>'
author = 'Federico Vaga <federico.vaga@cern.ch>'
# 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 short X.Y version.
version = '5.0'
# The full version, including alpha/beta/rc tags.
# The full version, including alpha/beta/rc tags
release = '5.0'
# 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']
# -- 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.ext.autodoc',
'sphinx.ext.todo',
'sphinx.ext.coverage',
'sphinx.ext.graphviz',
]
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = True
# 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_env', '_build', 'Thumbs.db', '.DS_Store']
# -- Options for HTML output ----------------------------------------------
# -- 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'
html_theme = "sphinx_rtd_theme"
html_theme = 'sphinx_rtd_theme'
# If true, links to the reST sources are added to the pages.
#
html_show_sourcelink = False
# 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.
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
#
# html_theme_options = {}
html_show_sphinx = False
# 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 = 'FMCADC100M14bit4Channeldoc'
# -- 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, 'FMCADC100M14bit4Channel.tex', 'FMC ADC 100M 14 bit 4 Channel Documentation',
'Federico Vaga \\textless{}federico.vaga@cern.ch\\textgreater{}', '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, 'fmcadc100m14bit4channel', 'FMC ADC 100M 14 bit 4 Channel Documentation',
[author], 1)
(master_doc,
'FMCADC100M14bit4Channel.tex',
'FMC ADC 100M 14 bit 4 Channel Documentation',
'Matthieu Cattin,\\\Dimitris Lampridis \\textless{}dimitrios.lampridis@cern.ch\\textgreater{},\\\ Federico Vaga \\textless{}federico.vaga@cern.ch\\textgreater{}',
'manual'),
]
# -- 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, 'FMCADC100M14bit4Channel', 'FMC ADC 100M 14 bit 4 Channel Documentation',
author, 'FMCADC100M14bit4Channel', 'One line description of project.',
'Miscellaneous'),
]
# -- Options for Epub output ----------------------------------------------
# Bibliographic Dublin Core info.
epub_title = project
epub_author = author
epub_publisher = author
epub_copyright = copyright
# The unique identifier of the text. This can be a ISBN number
# or the project homepage.
#
# epub_identifier = ''
# A unique identification for the text.
# The name of an image file (relative to this directory) to place at the top of
# the title page.
#
# epub_uid = ''
# A list of files that should not be packed into the epub file.
epub_exclude_files = ['search.html']
smart_quotes = False
latex_logo = 'fig/ohr_logo_lowres.png'
..
SPDX-License-Identifier: CC-BY-SA-4.0
SPDX-FileCopyrightText: 2020 CERN
.. FMC-ADC-100M-14B-4CHA documentation master file, created by
sphinx-quickstart on Thu Aug 6 14:57:13 2020.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to FMC ADC 100M 14 bit 4 Channel's documentation!
=========================================================
This is the user manual of the driver for the `FMC ADC 100M 14b 4cha`_
board developed on the `Open Hardware Repository`_. FMC is the form
factor of the card, ADC is its role, 100M means it can acquire
100Msample per second, 14b is the numbers of meaningful bits and 4cha
states it has 4 input channels (plus a trigger input).
.. _`Open Hardware Repository`: http://www.ohwr.org/
.. _`FMC ADC 100M 14b 4cha`: http://www.ohwr.org/projects/fmc-adc-100m14b4cha
FMC-ADC-100M-14B-4CHA documentation
===================================
.. toctree::
:maxdepth: 2
:caption: Contents:
:caption: Table of Contents
introduction
software/index
gateware/index
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
.. Copyright (c) 2013-2020 CERN (home.cern)
SPDX-License-Identifier: CC-BY-SA-4.0
.. _introduction:
------------
Introduction
------------
This document describes the gateware developed to support the FmcAdc100m14b4cha (later refered to as
fmc-adc) mezzanine card on the `SPEC`_ and `SVEC`_ carrier cards. The gateware is the HDL code
used to generate the bitstream that configures the FPGA on the carrier (sometimes also called
firmware). The gateware architecture is described in detail. The configuration and operation of
the fmc-adc is also explained. On the other hand, this manual is not intended to provide
information about the software used to control the fmc-adc board, nor details about it's hardware
design.
Repositories and Releases
=========================
.. _SPEC: http://www.ohwr.org/projects/spec
.. _SVEC: http://www.ohwr.org/projects/svec
SOURCES = $(wildcard *.cheby)
TARGETS = $(SOURCES:.cheby=.htm)
all: $(TARGETS)
.PHONY: $(TARGETS) clean
$(TARGETS): %.htm : %.cheby
@echo "\n\033[34m\033[1m-> Processing file $<\033[0m"
@cheby -i $< --gen-doc=$@ --doc html
# @cheby -i $< --gen-doc=$(@:.htm=.rst) --doc rest
# @cheby -i $< --gen-doc=$(@:.htm=.md) --doc md
clean:
@rm -f *.md *.rst *.htm
memory-map:
name: spec_ref_fmc_adc_100m_doc
bus: wb-32-be
description: SPEC FMC-ADC-100M full memory map
children:
- submap:
name: spec_base_mmap
address: 0x0000
description: SPEC base memory map
filename: ../../../hdl/ip_cores/spec/hdl/rtl/spec_base_regs.cheby
- submap:
name: metadata
address: 0x2000
size: 0x40
interface: wb-32-be
x-hdl:
busgroup: True
description: a ROM containing the application metadata
- submap:
name: fmc_adc_mezzanine
address: 0x4000
description: FMC ADC Mezzanine
filename: ../../../hdl/cheby/fmc_adc_mezzanine_mmap.cheby
memory-map:
name: svec_ref_fmc_adc_100m_doc
bus: wb-32-be
description: SVEC FMC-ADC-100M full memory map
children:
- submap:
name: svec_base_mmap
address: 0x0000
description: SVEC base memory map
filename: ../../../hdl/ip_cores/svec/hdl/rtl/svec_base_regs.cheby
- submap:
name: metadata
address: 0x2000
size: 0x40
interface: wb-32-be
x-hdl:
busgroup: True
description: a ROM containing the application metadata
- submap:
name: fmc1_adc_mezzanine
address: 0x4000
description: FMC ADC Mezzanine slot 1
filename: ../../../hdl/cheby/fmc_adc_mezzanine_mmap.cheby
- submap:
name: fmc2_adc_mezzanine
address: 0x6000
description: FMC ADC Mezzanine slot 2
filename: ../../../hdl/cheby/fmc_adc_mezzanine_mmap.cheby
alabaster==0.7.12
appdirs==1.4.3
Babel==2.8.0
CacheControl==0.12.6
certifi==2019.11.28
chardet==3.0.4
colorama==0.4.3
contextlib2==0.6.0
distlib==0.3.0
distro==1.4.0
docutils==0.16
html5lib==1.0.1
idna==2.8
imagesize==1.2.0
Jinja2==2.11.2
lockfile==0.12.2
MarkupSafe==1.1.1
msgpack==0.6.2
packaging==20.3
pep517==0.8.2
pkg-resources==0.0.0
progress==1.5
Pygments==2.6.1
pyparsing==2.4.6
pytoml==0.1.21
pytz==2020.1
requests==2.23.0
retrying==1.3.3
six==1.14.0
snowballstemmer==2.0.0
Sphinx==3.1.2
sphinx-rtd-theme==0.5.0
sphinxcontrib-applehelp==1.0.2
sphinxcontrib-devhelp==1.0.2
sphinxcontrib-htmlhelp==1.0.3
sphinxcontrib-jsmath==1.0.1
sphinxcontrib-qthelp==1.0.3
sphinxcontrib-serializinghtml==1.1.4
urllib3==1.25.8
webencodings==0.5.1
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment