Skip to content

F
FMC TDC 1ns 5cha
Commit a66846ef authored by Adam Wujek's avatar Adam Wujek
Browse files
Options

doc: update documentation 

Signed-off-by: 's avatarAdam Wujek <dev_public@wujek.eu>
parent 445ee122
Hide whitespace changes
Inline Side-by-side
Showing with 208 additions and 54 deletions
doc/gateware/index.rst
View file @ a66846ef
......@@ -20,11 +20,11 @@ Here is the procedure to build the FPGA binary image from the hdl
source.::
# Install ``hdlmake`` (version 3.4).
# Get fmc-adc hdl sources.
git clone git://ohwr.org/project/fmc-adc-100m14b4cha.git <src_dir>
# Get fmc-tdc hdl sources.
git clone https://ohwr.org/project/fmc-tdc.git <src_dir>
# Goto the synthesis directory.
cd <src_dir>/hdl/<carrier>/syn/
cd <src_dir>/hdl/syn/<carrier>/
# Fetch the dependencies and generate a synthesis Makefile.
hdlmake
......@@ -36,18 +36,11 @@ Source Code Organisation
------------------------
hdl/rtl/
ADC specific hdl sources.
hdl/cheby/
ADC specific ``cheby`` sources, html documentation and C header
file.
TDC specific hdl sources.
hdl/ip_cores/
Location of fetched hdl cores and libraries.
hdl/platform/<platform>
Platform related hdl sources.
hdl/top/<design>
Top-level hdl module for selected design.
......@@ -63,7 +56,7 @@ hdl/testbench/
Dependencies
------------
The fmc-adc gateware depends on the following hdl cores and libraries:
The fmc-tdc gateware depends on the following hdl cores and libraries:
`General Cores`_, `DDR3 SP6 core`_, `GN4124 core`_ (SPEC only),
`SPEC`_ (SPEC only) `VME64x Slave`_ (SVEC only), `SVEC`_ (SVEC only),
`WR Cores`_.
......
doc/gateware/memory-map.rst
View file @ a66846ef
......@@ -6,7 +6,7 @@
The Memory Map
==============
Following the memory map for the part of the ADC design that drives
Following the memory map for the part of the TDC design that drives
the FMC-TDC-1NS-5CH modules.
.. only:: latex
......@@ -21,7 +21,7 @@ the FMC-TDC-1NS-5CH modules.
Supported Designs
=================
Here you can find the complete memory MAP for the supported
designs. This will include the TDC register as well as the carrier
designs. This will include the TDC registers as well as the carrier
registers and any other component used in an FMC-TDC-1NS-5CH design.
.. toctree::
......
doc/gateware/spec_ref_fmc_tdc.rst
View file @ a66846ef
......@@ -12,12 +12,22 @@ FMC-TDC-1NS-5CHA mezzanine.
Carrier
=======
.. only:: latex
.. warning::
Unfortunatelly we are not able to include the memory map in PDF format.
Please for the memory map refer to the online documentation,
.. raw:: html
:file: regs/spec_base_regs.htm
FMC-TDC-1NS-5CHA
================
.. only:: latex
.. warning::
Unfortunatelly we are not able to include the memory map in PDF format.
Please for the memory map refer to the online documentation,
.. raw:: html
:file: regs/spec_ref_fmc_tdc_mmap.htm
doc/gateware/svec_ref_fmc_tdc.rst
View file @ a66846ef
......@@ -2,9 +2,9 @@
SPDX-License-Identifier: CC-BY-SA-4.0
SPDX-FileCopyrightText: 2022 CERN
=================
SVEC FMC ADC 100M
=================
=====================
SVEC FMC-TDC-1NS-5CHA
=====================
The memory map is divided in two parts: the `Carrier`_ part common to
all SPEC designs, and the `FMC-TDC-1NS-5CHA`_ part specific to the
......@@ -12,6 +12,11 @@ FMC-TDC-1NS-5CHA mezzanine.
Carrier
=======
.. only:: latex
.. warning::
Unfortunatelly we are not able to include the memory map in PDF format.
Please for the memory map refer to the online documentation,
.. raw:: html
:file: regs/svec_base_regs.htm
......@@ -19,5 +24,11 @@ Carrier
FMC-TDC-1NS-5CHA
================
.. only:: latex
.. warning::
Unfortunatelly we are not able to include the memory map in PDF format.
Please for the memory map refer to the online documentation,
.. raw:: html
:file: regs/svec_ref_fmc_tdc_mmap.htm
doc/introduction.rst
View file @ a66846ef
......@@ -51,4 +51,4 @@ this license, visit http://creativecommons.org/licenses/by-sa/4.0/.
.. _`FMC TDC 1ns 5 Channels`: https://ohwr.org/project/fmc-tdc
.. _`Open HardWare Repository`: https://ohwr.org/
.. _`Semantic Versioning`: https://semver.org/
.. _`FPGA Bitstream Page`: https://ohwr.org/project/fmc-tdc/wikis/Documents/Bitstreams
.. _`FPGA Release Page`: https://ohwr.org/project/fmc-tdc/wikis/Releases
doc/software/driver.rst
View file @ a66846ef
......@@ -12,7 +12,7 @@ Driver Features
Requirements
============
The fmcadc100m14b4ch device driver has been developed and tested on Linux
The fmc-tdc device driver has been developed and tested on Linux
3.10. Other Linux versions might work as well but it is not guaranteed.
This driver depends on the `zio`_ framework and `fmc`_ library; we
......@@ -46,16 +46,16 @@ available via PATH variable.
$ make install
.. note::
Since version v8.0.0 the fmctdc1ns5ch device driver does not
Since version v8.0.0 the fmc-tdc device driver does not
depend anymore on `fmc-bus`_ subsystem, instead it uses a new
`fmc`_ library
The building process generates 3 Linux modules:
*kernel/fmc-tdc.ko*, *kernel/fmc-tdc-spec.ko*, and
*kernel/fmc-tdc-svec.ko*.
*kernel/fmc-tdc.ko*, *kernel/fmc-tdc-spec.ko* (for SPEC card), and
*kernel/fmc-tdc-svec.ko* (for SVEC card).
Building Dependencies
---------------------
Drivers' Dependencies
=====================
The TDC driver requires the following drivers to function:
......@@ -78,7 +78,7 @@ Please read the following subsections for details
Cheby
-----
'''''
Clone *cheby* repository:
::
......@@ -94,7 +94,7 @@ It may be required to install *python-setuptools* or *python-setuptools.noarch*
package using your Linux distribution's software manager.
Wbgen2
------
''''''
Clone *wbgen2* repository:
::
......@@ -109,7 +109,7 @@ compilation):
FPGA Manager
------------
''''''''''''
If kernel module *fpga-mgr.ko* is not available in the kernel that is used,
probably the backported version is needed.
......@@ -148,7 +148,7 @@ Build and install kernel modules (*zio-buf-vmalloc.ko* and *zio.ko*):
General cores
-------------
'''''''''''''
Clone *general-cores* repository:
::
......@@ -167,8 +167,8 @@ and *htvic.ko*):
Spec
----
SPEC
''''
Clone *spec* repository:
::
......@@ -204,7 +204,7 @@ Build and install kernel modules (*gn412x-fcl.ko*, *gn412x-gpio.ko*,
Top Level Driver
================
The fmctdc is a generic driver for an FPGA device that could
The fmc-tdc is a generic driver for an FPGA device that could
be instanciated on a number of FMC carriers. For each carrier we write
a little Linux module which acts as a top level driver (like the MFD
drivers in the Linux kernel). In these modules there is the knowledge
......@@ -288,33 +288,48 @@ channel set represents a single TDC channel.
cset4 -- chan0;
}
The TDC registers can be accessed in the proper sysfs directory:::
The TDC registers can be accessed in the proper sysfs directory:
::
cd /sys/bus/zio/devices/tdc-1n5c-${ID}.
cd /sys/bus/zio/devices/tdc-1n5c-${ID}
The overall device (*tdc-1n5c*) provides the following attributes:
calibration_data
It is a binary attribute which allows the user to change the runt-time
It is a binary attribute which allows the user to change the run-time
calibration data (the EEPROM will not be touched). The ``fmc-tdc-calibration``
tool can be used to read write calibration data.
To be consistent, this binary interface expects **only** little endian
values because this is the endianess used to store calibration data for
values because this is the endianness used to store calibration data for
this device.
coarse
Coarse part of the current TAI time. This value is in nanoseconds with
8 ns resolution.
The ``fmc-tdc-time`` tool can be used to read TAI time.
command
Send the command to the driver. As today it is possible to enable/disable
White Rabbit, set the board to the current time or check the source of
the timing.
The ``fmc-tdc-time`` tool can be used to send the commands related to the
current time source.
seconds
Current TAI time in seconds. The ``fmc-tdc-time`` tool can be used to read TAI
time.
temperature
It shows the current temperature
It shows the current temperature. To get the temperature in C degrees use
the formula ``temperature/16``. The ``fmc-tdc-temperature`` tool can be used
to read the temperature.
transfer-mode
It shows the current transfer mode. 0 for FIFO, 1 for DMA.
wr-offset
Offset used by White Rabbit.
The Channel Set
'''''''''''''''
......@@ -366,12 +381,12 @@ allocate each block, the latter uses vmalloc to allocate the whole data
area. While the kmalloc buffer is linked with the core ZIO kernel
module, vmalloc is a separate module. The driver currently prefers
kmalloc, but even when it preferred vmalloc (up to mid June 2013), if
the respective module wad not loaded, ZIO would instantiate kmalloc.
the respective module was not loaded, ZIO would instantiate kmalloc.
You can change the buffer type, while not acquiring, by writing its name
to the proper attribute. For example::
echo vmalloc > /sys/bus/zio/devices/adc-100m14b-0200/cset0/current_buffer
echo vmalloc > /sys/bus/zio/devices/tdc-1n5c-0004/cset0/current_buffer
The disadvantage of kmalloc is that each block is limited in size.
usually 128kB (but current kernels allows up to 4MB blocks). The bigger
......@@ -381,7 +396,7 @@ buffer size is defined for each buffer instance, i.e. for each channel.
In this case we acquire only from the interleaved channel, so before
making a 1000-long multishot acquisition you can do::
export DEV=/sys/bus/zio/devices/adc-100m14b-0200
export DEV=/sys/bus/zio/devices/tdc-1n5c-0004
echo 1000 > $DEV/cset0/chani/buffer/max-buffer-len
The vmalloc buffer allows mmap support, so when using vmalloc you can
......@@ -395,13 +410,14 @@ The vmalloc buffer type starts off with a size of 128kB, but you can
change it (while not acquiring), by writing to the associated attribute
of the interleaved channel. For example this sets it to 10MB::
export DEV=/sys/bus/zio/devices/adc-100m14b-0200
export DEV=/sys/bus/zio/devices/tdc-1n5c-0004
echo 10000 > $DEV/cset0/chani/buffer/max-buffer-kb
The debugfs Interface
=====================
The fmctdc1ns5cha driver exports a set of debugfs attributes which
When the DMA mode is used, the fmctdc1ns5cha driver exports a set of debugfs
attributes which
are supposed to be used only for debugging activities. For each device
instance you will see a directory in ``/sys/kernel/debug/fmc-tdc.*``.
......
doc/software/library-api.rst
View file @ a66846ef
.. Copyright (c) 2022 CERN (home.cern)
SPDX-License-Identifier: CC-BY-SA-4.0
.. _lib_api:
The Library API
================
......
doc/software/library.rst
View file @ a66846ef
......@@ -8,10 +8,11 @@ Here you can find all the information about the *fmc-tdc* API and the
main library behaviour that you need to be aware of to write
applications.
This document introduces the developers to the development with the ADC library.
This document introduces the developers to the development with the TDC library.
Here you can find an overview about the API, the rational behind it and
examples of its usage. It is not the purpose of the document to describe
the API details. The complete API is available in the Library API document.
the API details. The complete API is available in
:doc:`the Library API <library-api>` section.
.. note::
......@@ -62,7 +63,7 @@ variable is set appropriately.
The :manpage:`errno` values can be standard Posix items like
``EINVAL``, or library-specific values, for example
``ADC_ERR_VMALLOC`` (*driver vmalloc allocator not available*). All
``FMCTDC_ERR_VMALLOC`` (*driver vmalloc allocator not available*). All
library-specific error values have a value greater than 4096, to
prevent collision with standard values. To convert such values to a
string please use :cpp:func:`fmctdc_strerror()`
......@@ -97,7 +98,7 @@ needs. Function :cpp:func:`fmctdc_open_by_lun()` is the open by LUN
The usage is exactly the same as :cpp:func:`fmctdc_open()` only that it uses
the LUN instead of the device ID.
No automatic action is take by :cpp:func:`fmctdc_open()`. Hence, you
No automatic action is taken by :cpp:func:`fmctdc_open()`. Hence, you
may want to flush the buffers before starting a new acquisition
session. You can do this with :cpp:func:`fmctdc_flush()`
......@@ -105,7 +106,7 @@ session. You can do this with :cpp:func:`fmctdc_flush()`
:language: c
:lines: 72-90
Configuration And Status
Configuration and Status
------------------------
The TDC configuration API is based on a number of getter and setter
......@@ -229,7 +230,7 @@ gateware using, respectivily, :cpp:func:`fmctdc_channel_enable()` and
:language: c
:lines: 194-204
You have to may functions to read timestamp :cpp:func:`fmctdc_read()`
To read timestamps you may use functions :cpp:func:`fmctdc_read()`
and :cpp:func:`fmctdc_fread()`. As the name may suggest, the first
behaves like :manpage:`read` and the second as :manpage:`fread`.
......@@ -246,12 +247,14 @@ If you need to flush the buffer, you can use :cpp:func:`fmctdc_flush()`.
Timestamp Math
--------------
The TDC library API has functions to support timestamp math. They
allow you to *add*, *subtract*, *compare*, *normalize*, and
allow you to *add*, *subtract*, *normalize*, and
*approximate*. These functions are: :cpp:func:`fmctdc_ts_add()`,
:cpp:func:`fmctdc_ts_sub()`, :cpp:func:`_fmctdc_tscmp()`,
:cpp:func:`fmctdc_ts_norm()`, :cpp:func:`fmctdc_ts_ps()`,and
:cpp:func:`fmctdc_ts_sub()`,
:cpp:func:`fmctdc_ts_norm()`, :cpp:func:`fmctdc_ts_ps()`, and
:cpp:func:`fmctdc_ts_approx_ns()`.
.. # NOTE: the "compare " function is not implemented in the library
.. _`ZIO`: https://www.ohwr.org/project/zio
.. _`SVEC`: https://www.ohwr.org/projects/svec
.. _`SPEC`: https://www.ohwr.org/projects/spec
doc/software/tools.rst
View file @ a66846ef
......@@ -6,26 +6,145 @@ Tools
=====
The driver is distributed with a few tools living in the ``tools/``
subdirectory and they do not use any dedicated library, instead
they do raw accesses to the driver. The programs are meant to provide
examples about the use of the driver and library interface
subdirectory, most of these tools use the fmc-tdc library.
The programs are meant to provide examples about the use of the driver and
library interface.
List TDC boards
---------------
The tool ``fmc-tdc-list`` is capable of listing the available boards in
the system. Below is the output from the command on an example system
with 3 SPEC boards, each populated with a TDC mezzanine.
::
$ fmc-tdc-list
FMC-TDC Device ID 0019
FMC-TDC Device ID 0018
FMC-TDC Device ID 0017
Termination Configuration
-------------------------
The tool ``fmc-tdc-term`` enables or disables the 50 Ohm termination
of a given input channel. The listing below shows the run of ``fmc-tdc-term``
tool to get the current status of the 50 Ohm termination on the TDC board with
an ID assigned to 4:
::
$ fmc-tdc-term 0x4
channel 0: 50 Ohm termination is off
channel 1: 50 Ohm termination is off
channel 2: 50 Ohm termination is off
channel 3: 50 Ohm termination is off
channel 4: 50 Ohm termination is off
To set the 50 Ohm termination e.g. on channel 0 on the TDC board with an ID
assigned to 4 please execute the following command:
::
$ fmc-tdc-term 0x4 0 on
channel 0: 50 Ohm termination is on
Reading Temperature
-------------------
The tool ``fmc-tdc-temperature`` allows to read the current temperature of
the TDC board.
The command below reads the temperature of the TDC board with an ID assigned
to 4:
::
$ fmc-tdc-temperature 0x4
31.4 deg C
Getting And Setting Board Time
------------------------------
The tool ``fmc-tdc-time`` allows to read and switch the time source to
White-Rabbit or local oscillator. The command below gets the information about
the current time source:
::
$ fmc-tdc-time 0x4 get
WR Status: synchronized.
Current TAI time is 1647471357.000000000 s
In the example above, the time source has been set to White-Rabbit.
To set the time source to the local oscillator:
::
$ fmc-tdc-time 0x4 local
# no output after the command is executed
To set the time source to the White-Rabbit:
::
$ fmc-tdc-time 0x4 wr
Locking the card to WR: ... locked!
Read Timestamps
---------------
The tool ``fmc-tdc-tstamp`` can print acquired timestamps. In the example below
the tool prints 5 samples (``-s`` parameter) from the channel 2 (``-c`` parameter)
on the board with the ID 0x19 (``-D`` parameter).
::
fmc-tdc-tstamp -D 0x19 -c 2 -s 5
channel 2 | channel seq 0
ts 0000041028s 590492339195ps
diff 0000041028s 590492339195ps [0.000024 Hz]
channel 2 | channel seq 1
ts 0000041028s 591492339023ps
diff 0000000000s 000999999828ps [1000.001000 Hz]
channel 2 | channel seq 2
ts 0000041028s 592492338931ps
diff 0000000000s 000999999908ps [1000.001000 Hz]
channel 2 | channel seq 3
ts 0000041028s 593492338597ps
diff 0000000000s 000999999666ps [1000.001000 Hz]
channel 2 | channel seq 4
ts 0000041028s 594492338425ps
diff 0000000000s 000999999828ps [1000.001000 Hz]
User Offset Configuration
-------------------------
The tool ``fmc-tdc-offset`` sets or gets the user-offset applied to the incoming
timestamps. The example below show that all offsets are set to 0 in an example
setup.
::
$ fmc-tdc-offset 0x19
channel 0: 0 ps
channel 1: 0 ps
channel 2: 0 ps
channel 3: 0 ps
channel 4: 0 ps
Calibration Data
----------------
The tool ``fmc-tdc-calibration`` reads calibration data from a file that
contains it in binary form and shows it on STDOUT in binary form or in human
readable one (default).
This could be used to change the TDC calibration data at runtime
by redirecting the binary output of this program to the proper
sysfs binary attribute.
This tool expects all values to be little endian.
Please note that the TDC driver supports only ps precision, but
calibration data is typically stored with sub-picosecond
precision. For this reason, according to your source, calibration
values may disagree on the fs part.
The example below shows the read of calibration data:
::
$ fmc-tdc-calibration -f /sys/bus/zio/devices/tdc-1n5c-0004/calibration_data
Temperature: 47 C
White Rabbit Offset: 229460000 fs
Zero Offset
ch1-ch2: -109000 fs
ch2-ch3: 493000 fs
ch3-ch4: 499000 fs
ch4-ch5: 336000 fs
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