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_hdl_svec_base:
SVEC Base HDL Component SVEC Base HDL Component
======================= =======================
The ``SVEC base`` HDL component provides the basic support for the SVEC card 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 and it is strongly recommended for any SVEC based design, even though it
this component is part of the `SVEC project`_ source code as well as the is not mandatory. This component groups together a set of ip-cores which
necessary Linux drivers. are required to drive hardware chips and FPGA ip-cores that are handy to
develop SPEC based designs.
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 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.
========== ========== ================== ============ Components
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 following table summarizes the ``SVEC base`` components and after that
The ``SVEC base`` is made of the following components 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 Component Start End Cap. Mask Bit
...@@ -80,25 +34,97 @@ Rule ...@@ -80,25 +34,97 @@ Rule
White-Rabbit 0x00001000 0x00001FFF 3 White-Rabbit 0x00001000 0x00001FFF 3
=================== ============ ========== ============= =================== ============ ========== =============
Observation .. note::
The capability mask value ``0x1F`` means that all optional components The *Capability Mask Bit* (Cap. Mask Bit) refers to the bit in the
are instantiated. 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 Version 1.4
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 Offset Size (bit) Name Default (LE)
0 Gen-Core I2C Ocore 0x00000000 32 Vendor ID 0x000010DC
1 Gen-Core SPI 0x00000004 32 Device ID 0x53564543
2 (reserved) 0x00000008 32 Version 0x0104xxxx
3 (reserved) 0x0000000C 32 Byte Order Mark 0xFFFE0000
4 (reserved) 0x00000010 128 Source ID <variable>
5 (reserved) 0x00000020 32 Capability Mask 0x0000000x
============== =================== 0x00000030 128 Vendor UUID 0x00000000
========== ========== ================== ============
.. _`SVEC project`: https://ohwr.org/project/svec .. _`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) SVEC Driver(s)
============== ==============
Driver(s) Structure
-------------------
There are drivers for the SVEC card and there are drivers for the 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 :ref:`SVEC base<svec_hdl_svec_base>` component. All these drivers are
managed by: managed by:
.. _svec_fmc_carrier:
SVEC FMC Carrier SVEC FMC Carrier
This is the driver that wrap up all the physical components and the 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 :ref:`SVEC base<svec_hdl_svec_base>` ones. It configures the card so
that all components cooperate correctly. It also export an that all components cooperate correctly. It also provides the support
`FPGA manager interface`_. for FPGA programming through the `FPGA manager interface`_.
If the SVEC based application is using the :ref:`SVEC If the SVEC based application is using the :ref:`SVEC
base<svec_hdl_svec_base>` component then it can profit from the base<svec_hdl_svec_base>` component then it can profit from the
following driver. They are not all mandatory, it depends on the following driver. They are not all mandatory, it depends on the
application, and most of them are distributed separately: application, and most of them are distributed separately:
.. _i2c_ocore:
I2C OCORE I2C OCORE
This is the driver for the I2C OCORE IP-core. It is used to communicate with 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 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 SPI OCORE
This is the driver for the SPI OCORE IP-core. It is used to communicate with 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 the M25P32 FLASH memory where FPGA bitstreams are stored. The driver is
distributed separately. distributed separately in `general cores`_.
.. _vic:
VIC VIC
The driver for the VIC interrupt controller IP-core. The driver is 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 .. _`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 .. _`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