Commit b95e05fb authored by Tomasz Wlostowski's avatar Tomasz Wlostowski

Merge remote-tracking branch 'fdsw/develop' into tom-spec-convention

parents 44b4ee21 54eafb43
*.o
*.ko
*~
*.mod.c
/.tmp_versions
.*cmd
modules.order
Module.symvers
Makefile.specific
*.tmp
GTAGS
GPATH
GRTAGS
[submodule "zio"]
path = zio
url = git://ohwr.org/misc/zio.git
==========
Change Log
==========
[3.0.0] - 2019-10-17
====================
Functionalists are mainly the same as before, but the architecture has changed
and some loading mechanism as well, for this reason we decided to increase
the major version.
This diff is collapsed.
# include parent_common.mk for buildsystem's defines
# use absolute path for REPO_PARENT
REPO_PARENT ?= $(shell /bin/pwd)/..
-include $(REPO_PARENT)/parent_common.mk
all: kernel lib tools
# The user can override, using environment variables, all these three:
ZIO ?= zio
# ZIO_ABS has to be absolut path, due to beeing
# passed to the Kbuild
ZIO_ABS ?= $(abspath $(ZIO) )
export ZIO_ABS
ZIO_VERSION = $(shell cd $(ZIO_ABS); git describe --always --dirty --long --tags)
export ZIO_VERSION
DIRS = $(ZIO_ABS) kernel lib tools
$(SPEC_SW_ABS):
kernel: $(ZIO_ABS)
lib: $(ZIO_ABS)
tools: lib
DESTDIR ?= /usr/local
.PHONY: all clean modules install modules_install $(DIRS)
.PHONY: gitmodules prereq_install prereq_install_warn
install modules_install: prereq_install_warn
all clean modules install modules_install: $(DIRS)
clean: TARGET = clean
modules: TARGET = modules
install: TARGET = install
modules_install: TARGET = modules_install
$(DIRS):
$(MAKE) -C $@ $(TARGET)
SUBMOD = $(ZIO_ABS)
prereq_install_warn:
@test -f .prereq_installed || \
echo -e "\n\n\tWARNING: Consider \"make prereq_install\"\n"
prereq_install:
for d in $(SUBMOD); do $(MAKE) -C $$d modules_install || exit 1; done
touch .prereq_installed
$(ZIO_ABS): zio-init_repo
# init submodule if missing
zio-init_repo:
@test -d $(ZIO_ABS)/doc || ( echo "Checking out submodule $(ZIO_ABS)" && git submodule update --init $(ZIO_ABS) )
include scripts/gateware.mk
Please check doc/
In ./doc/, fine-delay.in is the source file, and you can "make" to get
pdf and other formats provided you have the proper tools installed
(mainly texinfo and tex).
*~
*.aux
*.cp
*.cps
*.fn
*.html
*.info
*.ky
*.log
fine-delay.pdf
*.pg
*.texi
*.toc
*.tp
/*.txt
*.vr
_build
.doxystamp
doxygen-fd-output
# Minimal makefile for Sphinx documentation
#
# You can set these variables from the command line, and also
# from the environment for the first two.
SPHINXOPTS ?=
SPHINXBUILD ?= sphinx-build
SOURCEDIR = .
BUILDDIR = _build
# Put it first so that "make" without argument is like "make help".
help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
.PHONY: help Makefile
# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
$(MAKE) -C drawings
$(MAKE) doxygen TARGET=$@
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
GIT_VERSION = $(shell git describe --dirty --long --tags)
GIT_VERSION = $(shell git describe --dirty --long --tags)
doxygen:
ifeq ($(TARGET),clean)
@rm -rf doxygen-fd-output .doxystamp
else
$(MAKE) .doxystamp
endif
# List of Doxygen folders to consider
DOXINPUT := ../../lib
DOXINPUT += ../../kernel/fine-delay.h
DOXEXCL := ../../lib/PyFmcFineDelay
# List of actual Doxygen source files
DOXSRC = $(shell find $(DOXINPUT) -type f -name '*.[chS]')
.doxystamp: $(DOXSRC)
GIT_VERSION=$(GIT_VERSION) DOXINPUT="$(DOXINPUT)" DOXEXCL="$(DOXEXCL)" doxygen ./doxygen-fd-config
@touch .doxystamp
# Configuration file for the Sphinx documentation builder.
#
# This file only contains a selection of the most common options. For a full
# list see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html
# -- Path setup --------------------------------------------------------------
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
# import os
# import sys
# sys.path.insert(0, os.path.abspath('.'))
# -- Project information -----------------------------------------------------
project = 'Fmc Fine-Delay Software'
copyright = '2020, Alessandro Rubini'
author = 'Alessandro Rubini <rubini@gnudd.com>, Tomasz Wlostowski <Tomasz.Wlostowski@cern.ch>'
# -- General configuration ---------------------------------------------------
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
'breathe',
]
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The master toctree document.
master_doc = 'index'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
# -- Options for HTML output -------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
html_theme = 'sphinx_rtd_theme'
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
breathe_projects = {
"fine-delay": "doxygen-fd-output/xml/",
}
breathe_default_project = "fine-delay"
This diff is collapsed.
# SPDX-License-Identifier: CC0-1.0
#
# SPDX-FileCopyrightText: 2020 CERN
PROJECT_NAME = "Fmc Fine Delay"
PROJECT_NUMBER = $(GIT_VERSION)
PROJECT_BRIEF = "Fmc Fine Delay"
PROJECT_LOGO =
OUTPUT_DIRECTORY = doxygen-fd-output
CREATE_SUBDIRS = YES
TAB_SIZE = 8
OPTIMIZE_OUTPUT_FOR_C = YES
EXTRACT_STATIC = YES
CASE_SENSE_NAMES = YES
WARN_NO_PARAMDOC = YES
WARN_IF_UNDOCUMENTED = NO
INPUT = $(DOXINPUT)
RECURSIVE = YES
EXCLUDE = $(DOXEXCL)
GENERATE_HTML = NO
GENERATE_LATEX = NO
GENERATE_XML = YES
*.png
\ No newline at end of file
EPSIMAGES := $(shell ls *eps)
all: images
clean:
@rm $(EPSIMAGES:.eps=.png)
images: $(EPSIMAGES:.eps=.png)
%.png: %.eps
@convert $< $@
.PHONY: all clean images
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
Figure 1: Modes of operation of FmcDelay
This diff is collapsed.
Figure 2: Definition of output timings
======
Driver
======
Driver Features
===============
This driver is based on `zio`_ and it uses `fmc`_. It supports initial
setup of the board, setting and reading time, run-time continuous
calibration, input timestamping, output pulse generation and readback of
output settings from the hardware. It supports user-defined offsets,
so our users can tell the driver about channel-specific delays (for
example, to account for wiring) and ignore the issue in application code.
For each feature offered the driver (and documentation) the driver
tries to offer the following items; sometimes however one of them is missing
for a specific driver functionality, if we don't consider it important enough.
* A description of how the features works at low level;
* A low-level user-space program to test the actual mechanism;
* A C-language API to access the feature with data structures;
* An example program based on that API.
.. _drv_param:
Module Parameters
=================
The driver accepts a few load-time parameters for configuration. You
can pass them to *insmod* amd *modprobe* directly, or write them
in ``/etc/modules.conf`` or the proper file in ``/etc/modutils/``.
The following parameters are used:
verbose=
The parameter defaults to 0. If set, it enables more diagnostic
messages during probe (you may find it is not used, but it is
left in to be useful during further development, and avoid
compile-time changes like use of ``DEBUG``).
timer_ms=
The period of the internal timer, if not zero.
The timer is used to poll for input events instead of enabling
the interrupt. The default interval is 0, which means to
use interrupt support. You may want to use the timer while
porting to a different carrier, before sorting out IRQ issues.
calib_s=
The period, in seconds, of temperature measurement to re-calibrate
the output delays. Defaults to 30. If set to zero, the
re-calibration timer is not activated.
The module also supports some more parameters that are
calibration-specific. They are described in the :ref:`Calibration<dev_cal>`
section.
.. _zio: https://www.ohwr.org/project/zio
.. _fmc: https://www.ohwr.org/project/fmc-sw
Welcome to Fmc Fine-Delay Software's documentation!
===================================================
.. toctree::
:maxdepth: 2
:caption: Contents:
introduction
installation
driver
library
tools
developer-info
troubleshooting
#! /usr/bin/sed -f
# allow "%" as a comment char, but only at the beginning of the line
s/^%/@c /
#s/[^\\]%.*$//
s/^\\%/%/
#preserve blanks and braces in @example blocks
/^@example/,/^@end example/ s/{/@{/g
/^@example/,/^@end example/ s/}/@}/g
/^@example/,/^@end example/ p
/^@example/,/^@end example/ d
/^@smallexample/,/^@end smallexample/ s/{/@{/g
/^@smallexample/,/^@end smallexample/ s/}/@}/g
/^@smallexample/,/^@end smallexample/ p
/^@smallexample/,/^@end smallexample/ d
# remove leading blanks
s/^[ ]*//
============
Installation
============
This driver depends on two other modules (four http://ohwr.org.
packages), as well as the Linux kernel. Also, it
must talk to a specific FPGA binary file running in the device.
Gateware Dependencies
=====================
While previous versions of this package included a gateware binary
in the ``binaries/`` subdirectory, in Jan 2014 we decided not to do
that any more. Release versions of this package are expected to
point to ``current`` gateware images for different carriers.
Clearly the driver is expected to work on any *fmc* carrier,
even those ignored to us, and we can't provide all binaries.
The up-to-date gateware binaries for the SVEC and SPEC carriers will be
always available in the *Releases* section of the Fine Delay project:
http://www.ohwr.org/projects/fmc-delay-1ns-8cha/wiki/Releases
Note that the release gateware contains a stable version of
the White Rabbit PTP Core firmware. This firmware may be reloaded dynamically
at any time using carrier-specific tools.
Gateware Installation
=====================
By default, the driver looks for a gateware file named
``/lib/firmware/fmc/[carrier]-fine-delay.bin``, where ``[carrier]`` is the
carrier's name (lowercase - currently ``svec`` or ``spec``).
To install the gateware download the bitstreams from the Release page (or build
your own, as you wish) and put them in ``/lib/firmware/fmc``. You may have
to strip the version/date attached to the file names or create symlinks.
Follow your carrier instructions to load the gateware on the FPGA.
Software Dependencies
=====================
The kernel versions I am using during development is 3.10. Everything
used here is known to build with all versions from 2.6.35 to 3.12.
The driver, then, is based on the `zio`_ framework, available from
http://ohwr.org.
The FMC mezzanine is supported by means of the `fmc`_ software project.
Both packages (`zio`_ and `fmc`_) need to be downloaded and compiled. We do not
provide submodules because their version may conflict with other projects.
It is duty of the final user to guarantee a consistent installation.
Software Installation
=====================
To install this software package, you need to tell it where your
kernel sources live, so the package can pick the right header files.
You need to set only one environment variable:
LINUX
The top-level directory of the Linux kernel you are compiling
against. If not set, the default may work if you compile in the same
host where you expect to run the driver.
Most likely, this is all you need to set. After this, you can
run:::
make
sudo make install LINUX=$LINUX
After installation, your carrier driver should load automatically
(for example, the PCI bus will load ``spec-fmc-carrier.ko``), but
``fmc-fine-delay.ko`` must be loaded manually, because support for automatic
loading is not yet in place. The suggested command is one or the other of
the following two:::
modprobe fmc-fine-delay [<parameter> ...] # after make install
insmod kernel/fmc-fine-delay.ko [<parameter> ...] # if not installed
Available module parameters are described in :ref:`Module Parameters<drv_param>`.
Unless you customized or want to customize one of the three
related packages, you can skip the rest of this section.
In order to compile *fine-delay* against a specific repository you can use
the following environment variables:
ZIO
The top-level directory of the repository checkout of each
package.
FMC
The top-level directory of the repository checkout of each
package.
Headers and dependencies for the respective package are taken from the chosen
directory.
.. _zio: https://www.ohwr.org/project/zio
.. _fmc: https://www.ohwr.org/project/fmc-sw
============
Introduction
============
This is the user manual for the *fmc-delay-1ns-4cha* board developed on
http://ohwr.org. Please note that the ohwr hardware project is
misnamed as *fmc-delay-1ns-8cha*; even if the board has 4
channels; the references to *8ch* below are thus correct, even if
the may seem wrong.
Repositories and Releases
=========================
The code and documentation is distributed in the following places:
http://www.ohwr.org/projects/fine-delay-sw/documents
This place hosts the pdf documentation for some official
release, but we prefer to use the *files* tab, below.
https://ohwr.org/project/fine-delay-sw.git
Read-only repositories for the software and documentation.
ssh://git@ohwr.org:7999/project/fine-delay-sw.git
Read-write repositories, for those authorized.
.. note::
If you got this from the repository (as opposed to a named
*tar.gz* or *pdf* file) it may happen that you are looking at a later
commit than the release this manual claims to document.
It is a fact of life that developers forget
to re-read and fix documentation while updating the code. In that case,
please run ``git describe HEAD`` to ensure where you are.
Hardware Description
====================
The *FMC Delay 1ns-4cha* is an FPGA Mezzanine Card (FMC - VITA 57 standard),
whose main purpose is to produce pulses delayed by a user-programmed value with
respect to the input trigger pulse. The card can also work as a Time to
Digital converter (TDC) or as a programmable pulse generator triggering at a
given TAI time.
For the sake of clarity of this document, the card's name will be further
abbreviated as *fine-delay*.
Requirements and Supported Platforms
====================================
*fine-delay* can work with any VITA 57-compliant FMC carrier, provided that
the carrier's FPGA has enough logic resources. The current software/gateware
release officially supports the following carrier and mezzanine combinations:
* CERN's SPEC (Simple PCI-Express Carrier) with one *fine-delay* mezzanine.
* CERN's SVEC (Simple VME64x Carrier) with one or two *fine-delay* mezzanines.
Note that if only one *fine-delay* is in use, the other slot should be left
empty.
Aside from the FMC and its carrier, the following hardware/software components
are required:
* For the PCI version: a standard PC with at least one free 4x (or wider)
PCI-Express slot.
* For the VME version: a VME64x crate with a MEN A20/A25 CPU.
* 50-ohm cables with 1-pin LEMO 00 plugs for connecting the I/O signals.
* Any Linux distribution (validated with
CentOS 7 3.10.0-957.1.3.rt56.913.el7.x86_64)
Modes of Operation
==================
*fine-delay* can work in one or more of the following modes:
Pulse Delay
It produces one or more pulse(s) on selected outputs
a given time after an input trigger pulse.
Pulse Generator
Itproduces one or more pulse(s) on selected outputs
starting at an absolute time value programmed by the user.
In this mode, time base is usually provided by the White Rabbit network.
Time to Digital Converter
It tags all trigger pulses and delivers the timestamps to the user's
application.
.. image:: drawings/func.png
:alt: *fine-delay* operating modes.
Modes (pulse delay/generator) can be selected independently for each output.
For example, one can configure the output 1 to delay trigger pulses
by 1 us, and the output 2 to produce a pulse at the beginning of each second.
The TDC mode can be enabled for the input at any time and
does not interfere with the operation of the channels being time tagged.
Mechanical/Environmental
========================
.. image:: drawings/front_panels.png
:alt: *fine-delay* front panel connector layout.
**Mechanical and environmental specs:**
* Format: FMC (VITA 57), with rear zone for conduction cooling.
* Operating temperature range: 0 - 90 degC.
* Carrier connection: 160-pin Low Pin Count FMC connector.
Electrical
==========
Inputs/Outputs
--------------
* 1 trigger input (LEMO 00).
* 4 pulse outputs (LEMO 00).
* 2 LEDs (termination status and trigger indicator).
* Carrier communication via 160-pin Low Pin Count FMC connector.
Trigger input
-------------
* TTL/LVTTL levels, DC-coupled. Reception of a trigger pulse is indicated by
blinking the "TRIG" LED in the front panel.
* 2 kOhm or 50 Ohm input impedance (programmable via software).
50 Ohm termination is indicated by the "TERM" LED in the front panel.
* Power-up input impedance: 2 kOhm.
* Protected against short circuit, overcurrent (> 200 mA) and overvoltage
(up to +28 V).
* Maximum input pulse edge rise time: 20 ns.
Outputs
-------
* TTL-compatible levels DC-coupled: Voh = 3 V, Vol = 200 mV (50 Ohm load),
Voh = 6 V, Vol = 400 mV (high impedance).
* Output impedance: 50 Ohm (source-terminated).
* Rise/fall time: 2.5 ns (10%% - 90%%, 50 Ohm load).
* Power-up state: LOW (2 kOhm pulldown), guaranteed glitch-free.
* Protected against continuous short circuit, overcurrent and overvoltage
(up to +28 V).
Power supply
------------
* Used power supplies: P12V0, P3V3, P3V3_AUX, VADJ (voltage monitor only).
* Typical current consumption: 200 mA (P12V0) + 1.5 A (P3V3).
* Power dissipation: 7 W. Forced cooling is required.
Timing
======
.. image:: drawings/io_timing.png
:alt: *fine-delay* timing parameter definitions.
Time base
---------
* On-board oscillator accuracy: +/- 2.5 ppm (i.e. max. 2.5 ns error for a
delay of 1 ms).
* When using White Rabbit as the timing reference: depending on the
characteristics of the grandmaster clock and the carrier used. On SPEC
v 4.0 FMC carrier, the accuracy is better than 1 ns.
Input timing
------------
* Minimum pulse width: :math:`t_{IW}` = 50 ns. Pulses below 24 ns are rejected.
* Minimum gap between the last delayed output pulse and subsequent trigger
pulse: :math:`T_{LT}` = 50 ns.
* Input TDC performance: 400 ps pp accuracy, 27 ps resolution,
70 ps trigger-to-trigger rms jitter (measured at 500 kHz pulse rate).
Output timing
-------------
* Resolution: 10 ps.
* Accuracy (pulse generator mode): 300 ps.
* Train generation: trains of 1-65536 pulses or continuous square wave up
to 10 MHz.
* Output-to-output jitter (outputs programmed to the same delay): 10 ps rms.
* Output-to-output jitter (outputs programmed to to different delays, worst
case): 30 ps rms.
* Output pulse spacing (:math:`T_{SP}`) : 100 ns - 16 s. Adjustable in 10 ps
steps when both :math:`T_{PW}`, :math:`T_{GAP}` > 200 ns. Outside that range,
:math:`T_{SP}` resolution is limited to 4 ns.
* Output pulse start (:math:`t_{START}`) resolution: 10 ps for the rising edge
of the pulse, 10 ps for subsequent pulses if the condition above is met,
otherwise 4 ns.
Delay mode specific parameters
------------------------------
* Delay accuracy: < 1 ns.
* Trigger-to-output jitter: 80 ps rms.
* Trigger-to-output delay: minimum :math:`T_{DLY}` = 600 ns,
maximum :math:`T_{DLY}` = 120 s.
* Maximum trigger pulse rate: :math:`T_{DLY} + N*(T_{SP} + T_{GAP}) +` 100 ns,
where N = number of output pulses.
* Trigger pulses are ignored until the output with the biggest delay has
finished generation of the pulse(s).
Principles of Operation
=======================
.. note::
if you are an electronics engineer, you can skip this section, as
you will most likely find it rather boring.
.. image:: drawings/analog_digital_delays.png
:alt: Principle of operation of analog and digital delay generators.
Contrary to typical analog delay cards, which work by comparing an analog ramp
triggered by the input pulse with a voltage proportional to the desired delay,
*fine-delay* is a digital delay generator, which relies on time tag arithmetic.
The principle of operation of both generators is illustrated in the figure
above.
When a trigger pulse comes to the input, *fine-delay* first produces its'
precise time tag using a Time-to-Digital converter (TDC). Afterwards,
the time tag is summed together with the delay preset and the result is
passed to a digital pulse generator.
In its simplest form, it consists of a free running counter and a comparator.
When the counter reaches the value provided on the input, a pulse is produced
on the output.
Note that in order for the system to work correctly, both the TDC and
the Pulse Generator must use exactly the same time base (not shown on
the drawings).
Digital architecture brings several advantages compared to analog
predecessors: Timestamps generated by the TDC can be also passed to
the host system, and the Pulse Generators can be programmed with arbitrary
pulse start times instead of :math:`t_{TRIG} + T_{DLY}`. Therefore,
*fine-delay* can be used simultaneously as a TDC, pulse generator or
a pulse delay.
======================
Using the Provided API
======================
This chapter describes the higher level interface to the board,
designed for user applications to use. The code lives in the *lib}
subdirectory of this package. The directory uses a plain Makefile (not
a Kbuild one) so it can be copied elsewhere and compiled stand-alone.
Only, it needs a copy of ``fine-delay.h`` (which it currently pulls
from the parent directory) and the *zio* headers, retrieved using the
``ZIO`` environment variable).
.. _lib_init:
Initialization and Cleanup
==========================
Before using this library it must be initilized by calling
:c:func:`fdelay_init`. When you are not going to use the library anymore
call :c:func:`fdelay_exit` to release all allocated resources.
.. doxygenfunction:: fdelay_init
.. doxygenfunction:: fdelay_exit
In order to be able to handle a *fine-delay* device you must open it
with one of the following functions :c:func:`fdelay_open` or
:c:func:`fdelay_open_by_lun`. All these functions return a device token
which is required by most *fine-delay* functions. When you do not want to
use anymore the device, you should close it with :c:func:`fdelay_close`.
.. doxygenfunction:: fdelay_open
.. doxygenfunction:: fdelay_open_by_lun
.. doxygenfunction:: fdelay_close
Example code: all tools in ``tools/`` subdirectory.
.. _lib_time:
Time Management
===============
These are the primitives the library offers for time management, including
support for White Rabbit network synchronization.
.. doxygenfunction:: fdelay_set_time
.. doxygenfunction:: fdelay_get_time
.. doxygenfunction:: fdelay_set_host_time
.. doxygenfunction:: fdelay_wr_mode
.. doxygenfunction:: fdelay_check_wr_mode
Example code: ``fmc-fdelay-board-time`` tool.
.. _lib_input:
Input Configuration
===================
To configure the input channel for a board, the library offers the
following function and macros:
.. doxygenfunction:: fdelay_set_config_tdc
.. doxygenfunction:: fdelay_get_config_tdc
.. doxygendefine:: FD_TDCF_DISABLE_INPUT
.. doxygendefine:: FD_TDCF_DISABLE_TSTAMP
.. doxygendefine:: FD_TDCF_TERM_50
Example code: ``fmc-fdelay-term`` tool.
Reading Input Timestamps
========================
The library offers the following functions that deal with the input stamps:
.. doxygenfunction:: fdelay_read
.. doxygenfunction:: fdelay_fread
.. doxygenfunction:: fdelay_fileno_tdc
.. _lib_output:
Output Configuration
====================
The library offers the following functions for output configuration:
.. doxygenfunction:: fdelay_config_pulse
.. doxygenfunction:: fdelay_config_pulse_ps
.. doxygenfunction:: fdelay_get_config_pulse
.. doxygenfunction:: fdelay_get_config_pulse_ps
.. doxygenfunction:: fdelay_has_triggered
The configuration functions receive a time configuration. The
starting time is passed as ``struct fdelay_time``, while the
pulse end and loop period are passed using either the same structure
or a scalar number of picoseconds. These are the relevant structures:
.. doxygenstruct:: fdelay_time
:members:
.. doxygenstruct:: fdelay_pulse
:members:
.. doxygenstruct:: fdelay_pulse_ps
:members:
Example code: ``fmc-fdelay-pulse`` tool.
Miscellanous functions
======================
.. doxygenfunction:: fdelay_pico_to_time
.. doxygenfunction:: fdelay_time_to_pico
.. doxygenfunction:: fdelay_read_temperature
This diff is collapsed.
===============
Troubleshooting
===============
This chapters lists a few errors that may happen and how to deal with
them.
make modules_install misbehaves
===============================
The command ``sudo make modules_install`` may place the modules in the wrong
directory or fail with an error like:::
make: \*\*\* /lib/modules/3.10/build: No such file or directory.
This happens when you compiled by setting ``LINUX=`` and your
*sudo* is not propagating the environment to its child processes.
In this case, you should run this command instead::
sudo make modules_install LINUX=$LINUX
Version Mismatch
================
The *fdelay* library may report a version mismatch like this:::
spusa# ./tools/fmc-fdelay-board-time -d 0x5 get
Incompatible version driver-library
This reports a difference in the way ZIO attributes are laid out, so user
space may exchange wrong data in the ZIO control block, or may try to
access inexistent files in */sys*. I suggest recompiling both the kernel
driver and user space from a single release of the source package.
.tmp_versions
.*.o.d
KBUILD_EXTRA_SYMBOLS += $(ZIO_EXTRA_SYMBOLS-y)
KBUILD_EXTRA_SYMBOLS += $(FMC_EXTRA_SYMBOLS-y)
ccflags-y += -DVERSION=\"$(VERSION)\"
ccflags-y += -I$(src)
ccflags-y += -I$(ZIO_ABS)/include
ccflags-y += -I$(FMC_ABS)/include
# Extract ZIO minimum compatible version
ccflags-y += -D__ZIO_MIN_MAJOR_VERSION=$(shell echo $(ZIO_VERSION) | cut -d '-' -f 1 | cut -d '.' -f 1 | tr -d 'v'; )
ccflags-y += -D__ZIO_MIN_MINOR_VERSION=$(shell echo $(ZIO_VERSION) | cut -d '-' -f 1 | cut -d '.' -f 2; )
# add versions of supermodule. It is useful when fine-delay-sw is included as sub-module
# of a bigger project that we want to track
ifdef CONFIG_SUPER_REPO
ifdef CONFIG_SUPER_REPO_VERSION
SUBMODULE_VERSIONS += MODULE_INFO(version_$(CONFIG_SUPER_REPO),\"$(CONFIG_SUPER_REPO_VERSION)\");
endif
endif
# add versions of used submodules
SUBMODULE_VERSIONS += MODULE_INFO(version_zio,\"$(ZIO_VERSION)\");
ccflags-y += -DADDITIONAL_VERSIONS="$(SUBMODULE_VERSIONS)"
subdirs-ccflags-y = $(ccflags-y)
obj-m := fmc-fine-delay.o
obj-m += fmc-fine-delay-spec.o
obj-m += fmc-fine-delay-svec.o
fmc-fine-delay-objs = fd-zio.o fd-irq.o fd-core.o
fmc-fine-delay-objs += onewire.o spi.o gpio.o
fmc-fine-delay-objs += acam.o calibrate.o pll.o time.o
fmc-fine-delay-objs += calibration.o
fmc-fine-delay-spec-objs := fmc-fine-delay-spec-core.o
fmc-fine-delay-svec-objs := fmc-fine-delay-svec-core.o
\ No newline at end of file
# SPDX-License-Identifier: GPL-2.0-or-later
#
# Copyright (C) 2019 CERN
-include Makefile.specific
# include parent_common.mk for buildsystem's defines
#use absolute path for REPO_PARENT
REPO_PARENT ?= $(shell /bin/pwd)/../..
-include $(REPO_PARENT)/parent_common.mk
CPPCHECK ?= cppcheck
DKMS ?= 0
CURDIR := $(shell /bin/pwd)
KVERSION ?= $(shell uname -r)
LINUX ?= /lib/modules/$(KVERSION)/build
ifdef REPO_PARENT
ZIO ?= $(REPO_PARENT)/fmc/zio
FMC ?= $(REPO_PARENT)/fmc-sw
endif
ifeq ($(DKMS), 1)
# Take last installed version (if installed using RPM it should be OK)
ZIO_VERSION ?= $(shell basename $(shell ls -d $(DKMSTREE)/zio/* | grep -E "\/[0-9]+\.[0-9]+\.[0-9]+" | sort -V | tail -n 1))
ZIO_ABS ?= $(DKMSTREE)/zio/$(ZIO_VERSION)/source
ZIO_EXTRA_SYMBOLS-y = $(DKMSTREE)/zio/kernel-$(KVERSION)-$(shell uname -p)/module/Module.symvers
else
ifndef ZIO
$(error "Missing ZIO environment variable")
endif
ifndef FMC
$(error "Missing FMC environment variable")
endif
ZIO_ABS ?= $(abspath $(ZIO))
ZIO_EXTRA_SYMBOLS-y = $(ZIO_ABS)/drivers/zio/Module.symvers
ZIO_VERSION ?= $(shell cd $(ZIO_ABS); git describe --always --dirty --long --tags)
FMC_ABS ?= $(abspath $(FMC))
FMC_EXTRA_SYMBOLS-y = $(FMC_ABS)/drivers/fmc/Module.symvers
endif
GIT_VERSION = $(shell git describe --always --dirty --long --tags)
all modules:
$(MAKE) -C $(LINUX) M=$(CURDIR) ZIO_ABS=$(ZIO_ABS) FMC_ABS=$(FMC_ABS) \
ZIO_EXTRA_SYMBOLS-y=$(ZIO_EXTRA_SYMBOLS-y) \
FMC_EXTRA_SYMBOLS-y=$(FMC_EXTRA_SYMBOLS-y) \
ZIO_VERSION=$(ZIO_VERSION) \
GIT_VERSION=$(GIT_VERSION) \
modules
install modules_install: modules
$(MAKE) -C $(LINUX) M=$(CURDIR) modules_install
# be able to run the "clean" rule even if $(LINUX) is not valid
clean:
rm -rf *.o *~ .*.cmd *.ko *.mod.c .tmp_versions Module.symvers \
Module.markers modules.order
cppcheck:
$(CPPCHECK) -q -I. -I$(ZIO_ABS)/include -I$(FMC_BUS_ABS)/ --enable=all *.c *.h
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
/*
* SPI access to fine-delay internals
*
* Copyright (C) 2012 CERN (www.cern.ch)
* Author: Tomasz Wlostowski <tomasz.wlostowski@cern.ch>
* Author: Alessandro Rubini <rubini@gnudd.com>
*
* This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public License
* version 2 as published by the Free Software Foundation or, at your
* option, any later version.
*/
#include <linux/jiffies.h>
#include <linux/io.h>
#include <linux/delay.h>
#include "fine-delay.h"
#include "hw/fd_main_regs.h"
int fd_spi_xfer(struct fd_dev *fd, int ss, int num_bits,
uint32_t in, uint32_t *out)
{
uint32_t scr = 0, r;
unsigned long j = jiffies + HZ;
scr = FD_SCR_DATA_W(in)| FD_SCR_CPOL;
if(ss == FD_CS_PLL)
scr |= FD_SCR_SEL_PLL;
else if(ss == FD_CS_GPIO)
scr |= FD_SCR_SEL_GPIO;
fd_writel(fd, scr, FD_REG_SCR);
fd_writel(fd, scr | FD_SCR_START, FD_REG_SCR);
while (!(fd_readl(fd, FD_REG_SCR) & FD_SCR_READY))
if (jiffies > j)
break;
if (!(fd_readl(fd, FD_REG_SCR) & FD_SCR_READY))
return -EIO;
scr = fd_readl(fd, FD_REG_SCR);
r = FD_SCR_DATA_R(scr);
if(out) *out=r;
udelay(100); /* FIXME: check */
return 0;
}
int fd_spi_init(struct fd_dev *fd)
{
/* write default to DAC for VCXO */
fd_spi_xfer(fd, FD_CS_DAC, 24, fd->calib.vcxo_default_tune & 0xffff,
NULL);
return 0;
}
void fd_spi_exit(struct fd_dev *fd)
{
/* nothing to do */
}
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
zio @ 0765fa5d
Subproject commit 0765fa5d25466524889e9f5fb8976fbf429fabb3
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