Skip to content

S
Simple VME FMC Carrier SVEC
Commit 92b3092e authored by Federico Vaga's avatar Federico Vaga
Browse files
Options

doc: update documentation 

Signed-off-by: Federico Vaga's avatarFederico Vaga <federico.vaga@cern.ch>
parent 522cb422
Hide whitespace changes
Inline Side-by-side
Showing with 248 additions and 85 deletions
doc/hdl-svec-base.rst
View file @ 92b3092e
..
SPDX-License-Identifier: CC-BY-SA-4.0
SPDX-FileCopyrightText: 2019-2020 CERN
.. _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
and it is strongly recommended for any SVEC based design, even though it
is not mandatory. This component groups together a set of ip-cores which
are required to drive hardware chips and FPGA ip-cores that are handy to
develop SPEC based designs.
Version 1.4
~~~~~~~~~~~
The ``SPEC base`` is compliant with the `FPGA device identification`_ rules.
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
========== ========== ================== ============
Components
----------
Rule
The ``SVEC base`` is made of the following components
The following table summarizes the ``SVEC base`` components and after that
you have a brief description of each of them. We do not expect to add or
remove components in the future so this should be an exhaustive list.
=================== ============ ========== =============
Component Start End Cap. Mask Bit
......@@ -80,25 +34,97 @@ Rule
White-Rabbit 0x00001000 0x00001FFF 3
=================== ============ ========== =============
Observation
The capability mask value ``0x1F`` means that all optional components
are instantiated.
.. note::
The *Capability Mask Bit* (Cap. Mask Bit) refers to the bit in the
capability mask described in the `FPGA device identification`_
rules.
CSR
Control and Status register for the ``SVEC base`` device.
Therm. & ID
A onewire interface from `general cores`_ that accesses the SVEC
thermometer to get temperature and serial number.
General Cores I2C OpenCore
An I2C controller from `general cores`_ which bus is wired to the FMC
connector to access the I2C EEPROM on the FMC module.
General Cores SPI OpenCore
An SPI controller from `general cores`_ which bus is wired to the SPI
flash memory on which we store FPGA configurations.
General Cores VIC
An interrupt controller from `general cores`_ that routes FPGA
interrupts to VME slave. The interrupt lines from 0 to 5 are
reserved for internal use as described in the following table. All
other lines are available for users.
============== ===================
Interrupt Line Component
0 Gen-Core I2C Ocore
1 Gen-Core SPI Ocore
2 (reserved)
3 (reserved)
4 (reserved)
5 (reserved)
============== ===================
Build Info
Free format information (ASCII) about the FPGA synthesis.
White-Rabbit
The `White-Rabbit core`_.
.. note::
If the `White-Rabbit core`_ is instantiated then the components
*Therm. & ID* and *General Cores SPI OpenCore* get disabled because
they are incompatible. This because the `White-Rabbit core`_ needs
the OneWire bus and the SPI bus for internal use, therefore those
resources can't be used.
Usage
-----
The ``SVEC base`` component is in ``hdl/rtl/svec_base_wr.vhd`` and
examples of its usage are available in ``hdl/top/``.
Remember that the Linux driver expects the ``SVEC base`` at offset
``0x00000000``.
Meta-Data ROM
-------------
Fixed Part
~~~~~~~~~~
========== ========== ================== ============
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
========== ========== ================== ============
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:
Version 1.4
~~~~~~~~~~~
============== ===================
Interrupt Line Component
0 Gen-Core I2C Ocore
1 Gen-Core SPI
2 (reserved)
3 (reserved)
4 (reserved)
5 (reserved)
============== ===================
========== ========== ================== ============
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
========== ========== ================== ============
.. _`SVEC project`: https://ohwr.org/project/svec
.. _`FPGA device identification`: https://www.ohwr.org/project/fpga-dev-id/
.. _`general cores`: https://www.ohwr.org/projects/general-cores
.. _`GN4124 core`: https://www.ohwr.org/project/gn4124-core/
.. _`White-Rabbit core`: https://ohwr.org/project/wr-cores
doc/sw-driver.rst
View file @ 92b3092e
..
SPDX-License-Identifier: CC-BY-SA-4.0
SPDX-FileCopyrightText: 2019-2020 CERN
.. _svec_driver:
SVEC Driver(s)
==============
Driver(s) Structure
-------------------
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:
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`_.
that all components cooperate correctly. It also provides the support
for FPGA programming through the `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:
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.
available in Linux but also (as a backport) in `general cores`_.
.. _spi_ocore:
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.
distributed separately in `general cores`_.
.. _vic:
VIC
The driver for the VIC interrupt controller IP-core. The driver is
distributed separately.
distributed separately in `general cores`_.
.. _`OHWR`: https://ohwr.org
.. _`SVEC project`: https://ohwr.org/project/svec
.. _`GPIO interface`: https://www.kernel.org/doc/html/latest/driver-api/gpio/index.html
.. _`FMC`: https://www.ohwr.org/projects/fmc-sw
.. _`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~
.. _`DMA Engine`: https://www.kernel.org/doc/html/latest/driver-api/dmaengine/index.html
.. _`general cores`: https://www.ohwr.org/projects/general-cores
Drivers Build and Install
-------------------------
From the project top level directory, you can find the driver(s) source files
under ``software/kernel``.
The SVEC software uses plain ``Makefile`` to build drivers. Therefore, you can
build the driver by executing ``make``. To successfully build the SVEC driver
you need to install the `cheby`_ tool that will generate on fly part of the
code for the :ref:`SVEC base<svec_hdl_svec_base>`. If you do not want to
install `cheby`_ you can define the path to it with the environment
variable ``CHEBY``. Following an example on how to build the driver.::
# define CHEBY only if it is not installed
export CHEBY=/path/to/cheby/proto/cheby.py
cd /path/to/svec/
make -C software/kernel modules
make -C software/kernel modules_install
This will build and install 1 driver:
- :ref:`svec-fmc-carrier.ko<svec_fmc_carrier>`,
::
find software -name "*.ko"
software/kernel/svec-fmc-carrier.ko
Please note that this will not install all soft dependencies which are
distributed separately (:ref:`I2C OpenCore<i2c_ocore>`,
:ref:`SPI OpenCore<spi_ocore>`, :ref:`HT Vector Interrupt Controller<vic>`,
`FMC`_).
.. _`cheby`: https://gitlab.cern.ch/cohtdrivers/cheby
Driver(s) Loading
-----------------
The VME Slave ip-core is part of the :ref:`SVEC base<svec_hdl_svec_base>`
component. Since this is on FPGA, if the FPGA is not programmed then you do not
get the full VME support.
If you need to manually install/remove the driver and its dependencies, you
can use `modprobe(8)`_.::
sudo modprobe svec-fmc-carrier
If you did not install the drivers you can use `insmod(8)`_ and `rmmod(8)`_.
In this case is useful to know what drivers to load (dependencies) and their
(un)loading order.::
# typically part of the distribution
modprobe at24
modprobe mtd
modprobe m25p80
# from OHWR
insmod /path/to/fmc-sw/drivers/fmc/fmc.ko
insmod /path/to/general-cores/software/htvic/drivers/htvic.ko
insmod /path/to/general-cores/software/i2c-ocores/drivers/i2c/busses/i2c-ocores.ko
insmod /path/to/general-cores/software/spi-ocores/drivers/spi/spi-ocores.ko
# Actually the order above does not really matter, what matters
# it is that svec-fmc-carrier.ko is loaded as last
insmod /path/to/svec/software/kernel/svec-fmc-carrier.ko
.. _`modprobe(8)`: https://linux.die.net/man/8/modprobe
.. _`insmod(8)`: https://linux.die.net/man/8/insmod
.. _`rmmod(8)`: https://linux.die.net/man/8/rmmod
Attributes From *sysfs*
-----------------------
In addition to standard *sysfs* attributes for VME, `FPGA manager`_,
and `FMC`_ there more SVEC specific *sysfs* attributes. Here we focus
only on those.
If the FPGA is correctly programmed (an FPGA configuration that uses the
:ref:`SVEC base<svec_hdl_svec_base>`) then there will be a directory
named ``svec-vme-<vme-slot>`` that contains the reference to all FPGA
sub-devices and the following *sysfs* attributes.
``svec-vme-<vme-slot>/application_offset`` [R]
It shows the relative offset (from FPGA base address - resource0) to the
user application loaded.
``svec-vme-<vme-slot>/pcb_rev`` [R]
It shows the SVEC carrier PCB revision number.
``svec-vme-<vme-slot>/reset_app`` [R/W]
It puts in *reset* (1) or *unreset* (0) the user application.
.. _`FPGA manager`: https://www.kernel.org/doc/html/latest/driver-api/fpga/index.html
Attributes From *debugfs*
-------------------------
In addition to standard *debugfs* attributes for VME, `FPGA manager`_,
and `FMC`_ there more SVEC specific *debugfs* attributes. Here we
focus only on those.
``vme-<vme-slot>/fpga_device_metadata`` [R]
It dumps the FPGA device metadata information for the
:ref:`SVEC base<svec_hdl_svec_base>` and, when it exists, the user
application one.
``vme-<vme-slot>/fpga_firmware`` [W]
It configure the FPGA with a bitstream which name is provided as input.
Remember that firmwares are installed in ``/lib/firmware`` and alternatively
you can provide your own path by setting it in
``/sys/module/firmware_class/parameters/path``.
``vme-<vme-slot>/svec-vme-<vme-slot>/csr_regs`` [R]
It dumps the Control/Status register for
the :ref:`SVEC base<svec_hdl_svec_base>`
``vme-<vme-slot>/svec-vme-<vme-slot>/build_info`` [R]
It shows the FPGA configuration synthesis information
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