Commit 8be2eef6 authored by Federico Vaga's avatar Federico Vaga

doc: add SPHINX documentation

Signed-off-by: Federico Vaga's avatarFederico Vaga <federico.vaga@cern.ch>
parent 658e63ef
# SPDX-License-Identifier: CC0-1.0
# SPDX-FileCopyrightText: 2019 CERN
_build
*.man
*.html
*.pdf
\ No newline at end of file
MANUAL=svec-device
# Minimal makefile for Sphinx documentation
#
all: img doc
# You can set these variables from the command line.
SPHINXOPTS =
SPHINXBUILD = sphinx-build
SOURCEDIR = .
BUILDDIR = _build
doc: html man
# Put it first so that "make" without argument is like "make help".
help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
html:
rst2html $(MANUAL).rst > $(MANUAL).html
.PHONY: help Makefile
man:
rst2man --syntax-highlight=none $(MANUAL).rst > $(MANUAL).man
img: svec-logo.png
svec-logo.png: svec-logo.svg
inkscape -f $< -e $@
clean:
rm -f *.html *.man *.png
# 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
# -*- 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 = 'SVEC'
copyright = '2019, Federico Vaga <federico.vaga@cern.ch>'
author = 'Federico Vaga <federico.vaga@cern.ch>'
# The short X.Y version
version = ''
# The full version, including alpha/beta/rc tags
release = 'v1.4.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 = ['_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'
# 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 = ['_build', 'Thumbs.db', '.DS_Store']
# 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 = ['_static']
# 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 = 'SVECdoc'
# -- 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, 'SVEC.tex', 'SVEC 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, 'svec', 'SVEC 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, 'SVEC', 'SVEC Documentation',
author, 'SVEC', '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']
.. _svec_hdl_svec_base:
SVEC Base HDL Component
=======================
The ``SVEC base`` HDL component provides the basic support for the SVEC card
and it strongly recommended for any SVEC based application. The VHDL code for
this component is part of the `SVEC project`_ source code as well as the
necessary Linux drivers.
Interface Rules
---------------
The ``SVEC base`` is an :ref:`FPGA device <device-structure>` that contains
all the necessary logic to use the SVEC carrier's features.
Rule
The ``SVEC base`` design must follow the FPGA design guide lines
Rule
The ``SVEC base`` instance must be present in any SVEC based
design.
Rule
The ``SVEC base`` metadata table must contain the following
constant values
========== ========== ================== ============
Offset Size (bit) Name Default (LE)
0x00000000 32 Vendor ID 0x000010DC
0x00000004 32 Device ID 0x53564543
0x00000008 32 Version <variable>
0x0000000C 32 Byte Order Mark 0xFFFE0000
0x00000010 128 Source ID <variable>
0x00000020 32 Capability Mask <variable>
0x00000030 128 Vendor UUID 0x00000000
========== ========== ================== ============
Observation
The ``SVEC base`` typically is instantiated in a *top level* design
next to an ``Application Device``.
Rule
The ``SVEC base`` must have a 32bit register containing the offset
to the ``Application Device``. If there is no application, then the content
of this register must be ``0x00000000``.
Observation
The ``Application Device`` offset is design specific and it must be
declared in the ``Application Access`` register
Version 1.4
~~~~~~~~~~~
Rule
The ``SVEC base`` metadata table must contain the following
constant values for this version.
========== ========== ================== ============
Offset Size (bit) Name Default (LE)
0x00000000 32 Vendor ID 0x000010DC
0x00000004 32 Device ID 0x53564543
0x00000008 32 Version 0x0104xxxx
0x0000000C 32 Byte Order Mark 0xFFFE0000
0x00000010 128 Source ID <variable>
0x00000020 32 Capability Mask 0x0000000x
0x00000030 128 Vendor UUID 0x00000000
========== ========== ================== ============
Rule
The ``SVEC base`` is made of the following components
=================== ============ ========== =============
Component Start End Cap. Mask Bit
CSR 0x00000040 0x0000005F (Mandatory)
Therm. & ID 0x00000070 0x0000007F 1
Gen-Core I2C Ocore 0x00000080 0x0000009F (Mandatory)
Gen-Core SPI 0x000000A0 0x000000BF 2
Gen-Core VIC 0x00000100 0x000001FF 0
Build info 0x00000200 0x000002FF 4
White-Rabbit 0x00001000 0x00001FFF 3
=================== ============ ========== =============
Observation
The capability mask value ``0x1F`` means that all optional components
are instantiated.
Rule
The ``SVEC base`` must connect the VIC IRQ output to the VME IRQ line
Rule
The ``SVEC base`` reserves the first 6 interrupt lines of
the internal interrupt controller (``VIC``) for the following purposes:
============== ===================
Interrupt Line Component
0 Gen-Core I2C Ocore
1 Gen-Core SPI
2 (reserved)
3 (reserved)
4 (reserved)
5 (reserved)
============== ===================
.. _`SVEC project`: https://ohwr.org/project/svec
================================
Welcome to SPEC's documentation!
================================
The FMC VME Carrier is an FMC carrier in VME64x format that can hold two
FMC cards and an SFP connector. The FMC mezzanine slots use low-pin
count (LPC) connectors. This board is optimised for cost.
The `SVEC project`_ is hosted on the `Open HardWare Repository`_
.. toctree::
:maxdepth: 2
:caption: Contents:
hdl-svec-base
sw-driver
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
.. _`Open HardWare Repository`: https://ohwr.org/
.. _`SVEC project`: https://ohwr.org/project/svec
====
SVEC
====
---------------------------------------------
programming application FPGA
---------------------------------------------
:Author: Federico Vaga <federico.vaga@cern.ch>
:organization: CERN
:Date: 2017-10-12
:Copyright: GNU GPL, version 2 or any later version
:Version: 0.9.0
:Manual section: 4
:Manual group: CERN BECOHT Toolkit
Description
===========
The file ``/dev/svec.[0-N]`` is a character device, usually of mode 0440
and owner root:root. The number ``[0-N]`` represents a *SVEC Module* instance.
It is used to program the *Application FPGA* of a `SVEC module`_ on the VME bus.
The programming procedure consists in taking an FPGA bit-stream from the user
and writing it in the Application FPGA on the SVEC Module.
Once the device has been closed the Application FPGA become active and,
if valid, it will run the FPGA bit-stream provided by the user.
In order to prevent accidental programming, the Application FPGA programming
procedure is protected by the sysfs attribute ``AFPGA/lock``, usually of mode
0644 and owner root:root. On read it returns a string representing the current
locking status. On write it accepts only the strings:
- "unlock" to unlock the programming procedure.
- "lock" to lock the programming procedure
Once the programming procedure has been completed, the device go back to the
locking status.
The complete programming procedure is:
#. unlock the programming procedure by writing "unlock" in ``AFPGA/lock``
#. write the FPGA bit-stream in the character device ``/dev/svec.<N>``
Files
=====
/dev/svec.[0-N]
/sys/bus/vme/device/vme.[0-N]/svec/svec.[0-N]/AFPGA/lock
.. _`SVEC module`: https://www.ohwr.org/projects/svec/
Examples
========
.. code:: sh
echo "unlock" > /sys/bus/vme/devices/vme.8/svec/svec.8/AFPGA/lock
dd if=/path/to/bitstream.bin of=/dev/svec.8
.. code:: sh
echo "unlock" > /sys/bus/vme/devices/vme.8/svec/svec.8/AFPGA/lock
cat /path/to/bitstream.bin > /dev/svec.8
SVEC Driver(s)
==============
There are drivers for the SVEC card and there are drivers for the
:ref:`SVEC base<svec_hdl_svec_base>` component. All these drivers are
managed by:
SVEC FMC Carrier
This is the driver that wrap up all the physical components and the
:ref:`SVEC base<svec_hdl_svec_base>` ones. It configures the card so
that all components cooperate correctly. It also export an
`FPGA manager interface`_.
If the SVEC based application is using the :ref:`SVEC
base<svec_hdl_svec_base>` component then it can profit from the
following driver. They are not all mandatory, it depends on the
application, and most of them are distributed separately:
I2C OCORE
This is the driver for the I2C OCORE IP-core. It is used to communicate with
the standard FMC EEPROM available what on FMC modules. The driver is
available in Linux.
SPI OCORE
This is the driver for the SPI OCORE IP-core. It is used to communicate with
the M25P32 FLASH memory where FPGA bitstreams are stored. The driver is
distributed separately.
VIC
The driver for the VIC interrupt controller IP-core. The driver is
distributed separately.
.. _`SVEC project`: https://ohwr.org/project/svec
.. _`GPIO interface`: https://www.kernel.org/doc/html/latest/driver-api/gpio/index.html
.. _`FPGA manager interface`: https://www.kernel.org/doc/html/latest/driver-api/fpga/index.html
.. _`DMA Engine`: https://www.kernel.org/doc/html/latest/driver-api/dmaengine/index.html~
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