Skip to content
Snippets Groups Projects
Commit 18c22b53 authored by Federico Vaga's avatar Federico Vaga
Browse files

doc: add a bit of documentation 


Signed-off-by: default avatarFederico Vaga <federico.vaga@cern.ch>
parent 2e04b6f8
Branches
Tags
No related merge requests found
Hide whitespace changes
Inline Side-by-side
doc/hdl-spec-base.rst 0 → 100644
+ 109
− 0
View file @ 18c22b53
.. _spec_hdl_spec_base:
SPEC Base HDL Component
=======================
The ``SPEC base`` HDL component provides the basic support for the SPEC card
and it strongly recommended for any SPEC based application. The VHDL code for
this component is part of the `SPEC project`_ source code as well as the
necessary Linux drivers.
Interface Rules
---------------
The ``SPEC base`` is an :ref:`FPGA device <device-structure>` that contains
all the necessary logic to use the SPEC carrier's features.
Rule
The ``SPEC base`` design must follow the FPGA design guide lines
Rule
The ``SPEC base`` instance must be present in any SPEC based
design.
Rule
The ``SPEC base`` metadata table must contain the following
constant values
========== ========== ================== ============
Offset Size (bit) Name Default (LE)
0x00000000 32 Vendor ID 0x000010DC
0x00000004 32 Device ID 0x53504543
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 ``SPEC base`` typically is instantiated in a *top level* design
next to an ``Application Device``.
Rule
The ``SPEC 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 ``SPEC 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 0x53504543
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 ``SPEC 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
DMA for DDR 0x000000C0 0x000000FF 5
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 ``SPEC base`` must connect the VIC IRQ output to the ``GPIO 8`` on
the GN4124 chip
Observation
The GN4124 ``GPIO 9`` can be used for interrupts by the application.
Rule
The ``SPEC 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 Gen-Core Gennum DMA DONE
3 (reserved)
4 (reserved)
5 (reserved)
============== ===================
.. _`SPEC project`: https://ohwr.org/project/spec
doc/index.rst
+ 17
− 6
View file @ 18c22b53
.. SPEC documentation master file, created by
sphinx-quickstart on Wed Sep 4 17:35:06 2019.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
================================
Welcome to SPEC's documentation!
================================
The Simple PCIe FMC Carrier (SPEC) is a 4 lane PCIe card that has an
FPGA and can hold one FMC module and one SFP connector.
Its bridge to the PCIe bus is the Gennum GN4124 chip and its purpose
is to create a bridge between the PCIe bus and the FPGA. With the
exception of the M25P32 FLASH memory, all components are connected to
the FPGA. This implies that an FPGA configuration is necessary to
fully use the card.
The `SPEC project`_ is hosted on the `Open HardWare Repository`_
.. toctree::
:maxdepth: 2
:caption: Contents:
hdl-spec-base
sw-driver
Indices and tables
==================
......@@ -18,3 +26,6 @@ Indices and tables
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
.. _`Open HardWare Repository`: https://ohwr.org/
.. _`SPEC project`: https://ohwr.org/project/spec
doc/sw-driver.rst 0 → 100644
+ 51
− 0
View file @ 18c22b53
SPEC Driver(s)
==============
There are drivers for the GN4124 chip and there are drivers for the
:ref:`SPEC base<spec_hdl_spec_base>` component. All these drivers are
managed by:
SPEC FMC Carrier
This is the driver that wrap up all the physical components and the
:ref:`SPEC base<spec_hdl_spec_base>` ones. It configures the card so
that all components cooperate correctly.
The driver for the GN4124 chip are always present and distributed as
part of the SPEC driver. They must work no matter what FPGA design has
been loaded on FPGA.
GN4124 GPIO
This driver provides support for the GN4124 GPIOs. It uses the standard
Linux `GPIO interface`_ and it export a dedicated IRQ domain.
Gn4124 FCL
This driver provides support for the GN4124 FCL (FPGA Configuration Loader).
It uses the `FPGA manager interface`_ to program the FPGA at runtime.
If the SPEC based application is using the :ref:`SPEC
base<spec_hdl_spec_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:
SPEC GN412x DMA
This driver provides for DMA transfers to/from the SPEC DDR. It uses
the standard Linux `DMA Engine`_. It is part of the `SPEC project`_
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.
.. _`SPEC project`: https://ohwr.org/project/spec
.. _`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~
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