sw-driver.rst 6.02 KB
Newer Older
1 2 3 4 5 6
..
  SPDX-License-Identifier: CC-BY-SA-4.0
  SPDX-FileCopyrightText: 2019-2020 CERN

.. _svec_driver:

7 8 9
SVEC Driver(s)
==============

10 11 12
Driver(s) Structure
-------------------

13 14 15 16
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:

17 18
.. _svec_fmc_carrier:

19 20 21
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
22 23
  that all components cooperate correctly. It also provides the support
  for FPGA programming through the `FPGA manager interface`_.
24 25 26 27 28 29

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:

30 31
.. _i2c_ocore:

32 33 34
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
35 36 37
  available in Linux but also (as a backport) in `general cores`_.

.. _spi_ocore:
38 39 40 41

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
42 43 44
  distributed separately in `general cores`_.

.. _vic:
45 46 47

VIC
  The driver for the VIC interrupt controller IP-core. The driver is
48
  distributed separately in `general cores`_.
49

50
.. _`OHWR`: https://ohwr.org
51
.. _`SVEC project`: https://ohwr.org/project/svec
52
.. _`FMC`: https://www.ohwr.org/projects/fmc-sw
53
.. _`FPGA manager interface`: https://www.kernel.org/doc/html/latest/driver-api/fpga/index.html
54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173
.. _`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