fine-delay.in 84.7 KB
Newer Older
Alessandro Rubini's avatar
Alessandro Rubini committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37
\input texinfo    @c -*-texinfo-*-
%
% fine-delay.in - main file for the documentation
%
%%%%

%------------------------------------------------------------------------------
%
%                         NOTE FOR THE UNAWARE USER
%                         =========================
%
%    This file is a texinfo source. It isn't the binary file of some strange
%    editor of mine. If you want ASCII, you should "make fine-delay.txt".
%
%------------------------------------------------------------------------------

%
% This is not a conventional info file...
% I use three extra features:
%   - The '%' as a comment marker, if at beginning of line ("\%" -> "%")
%   - leading blanks are allowed (this is something I can't live without)
%   - braces are automatically escaped when they appear in example blocks
%

@comment %**start of header
@documentlanguage en
@documentencoding ISO-8859-1
@setfilename fine-delay.info
@settitle fine-delay
@iftex
@afourpaper
@end iftex
@paragraphindent none
@comment %**end of header

@setchapternewpage off

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
38
@set update-month April 2014
39 40
@c the release name below is substituted at build time
@set release __RELEASE_GIT_ID__
Alessandro Rubini's avatar
Alessandro Rubini committed
41 42 43 44

@finalout

@titlepage
45
@title Fine Delay User's Manual
46
@subtitle @value{update-month} (@value{release})
47 48
@subtitle FMC Delay 1ns-4cha hardware and software manual
@author CERN BE-CO-HT / Tomasz Wlostowski, Alessandro Rubini
Alessandro Rubini's avatar
Alessandro Rubini committed
49 50 51 52 53 54 55 56
@end titlepage
@headings single

@c ##########################################################################
@iftex
@contents
@end iftex

57 58 59 60 61 62 63
@unnumbered Revision history
@multitable  @columnfractions .10 .15 .25 .50
@headitem Revision @tab Date @tab Author @tab Changes
@item 1.0 @tab April 2012 @tab AR, TW @tab Initial version
@item 2.0 @tab August 2013 @tab AR, TW @tab Updated to 2.0 software/gateware release
@end multitable

Alessandro Rubini's avatar
Alessandro Rubini committed
64 65 66 67
@c ##########################################################################
@node Top
@top Introduction

68
This is the user manual for the
69
``fmc-delay-1ns-4cha'' board developed on @code{ohwr.org}.  Please
70 71 72
note that the ohwr hardware project is misnamed as @code{fmc-delay-1ns-8cha};
even if the board has 4 channels; the references to @code{8ch} below are thus
correct, even if the may seem wrong.
Alessandro Rubini's avatar
Alessandro Rubini committed
73

74 75 76 77 78 79 80 81 82 83
@c ##########################################################################
@node Repositories and Releases
@chapter Repositories and Releases

The code and documentation is distributed in the following places:

@table @code

@item http://www.ohwr.org/projects/fine-delay-sw/documents

84 85
	This place hosts the pdf documentation for some official
        release, but we prefer to use the @i{files} tab, below.
86 87 88 89 90

@item http://www.ohwr.org/projects/fine-delay-sw/files

	Here we place the @i{.tar.gz} file for every release,
        including the @i{git} tree and compiled documentation (for
91
        those who lack TeX), as well as manuals.
92 93 94 95 96 97 98 99 100 101

@item git://ohwr.org/fmc-projects/fmc-delay-1ns-8cha/fine-delay-sw.git
@itemx git://gitorious.org/fine-delay/fine-delay.git

	Read-only repositories for the software and documentation.
        The former is authoritative, the latter is a backup.

@item git@@ohwr.org:fmc-projects/fmc-delay-1ns-8cha/fine-delay-sw.git
@itemx git@@gitorious.org:fine-delay/fine-delay.git

102
	Read-write repositories, for those authorized. Again, OHWR is
103 104 105 106 107
        the authoritative place, but we tend to push to gitorious as
        well.

@end table

108 109 110 111 112 113 114
@c The official release of this
@c repository has a tag called called
@c @code{@value{tagname}}. The same tag is used in related
@c repositories (@i{zio}, @i{spec-sw} and the hardware repository).
@c Any official hot fixes, if any,  for this
@c release live in the branch called
@c @code{@value{tagname}-fixes}, in each repository.
115 116

@b{Note:} If you got this from the repository (as opposed to a named
117
@i{tar.gz} or @i{pdf} file) it may happen that you are looking at a later commit
118 119
than the release this manual claims to document.
It is a fact of life that developers forget
120
to re-read and fix documentation while updating the code. In that case,
121
please run ``@code{git describe HEAD}'' to ensure where you are.
122

123 124 125 126 127 128 129 130 131 132
@c ##########################################################################
@node Hardware Description
@chapter Hardware Description

The @i{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 
Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
133
name will be further abbreviated as @sc{fine-delay}.
134 135 136 137 138

@c ==========================================================================
@node Requirements and Supported Platforms
@section Requirements and Supported Platforms

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
139
@sc{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:
140 141

@itemize @bullet
Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
142 143 144
@item CERN's SPEC (Simple PCI-Express Carrier) with one @sc{fine-delay} mezzanine.
@item CERN's SVEC (Simple VME64x Carrier) with one or two @sc{fine-delay} mezzanines. 
Note that if only one @sc{fine-delay} is in use, the other slot should be left empty.
145
@end itemize
146 147 148
 
Aside from the FMC and its carrier, the following hardware/software components 
are required:
149

150 151 152 153 154 155
@itemize @bullet
@item For the PCI version: a standard PC with at least one free 4x (or wider) PCI-Express slot.
@item For the VME version: a VME64x crate with a MEN A20 CPU (fixme: can the driver work on RIO or something else?).
@item 50-ohm cables with 1-pin LEMO 00 plugs for connecting the I/O signals.
@item Any Linux (kernel 2.6 or 3.0+) distribution. Backports are provided down to kernel @code{2.6.24}.
@end itemize
156

157 158 159 160
@c ==========================================================================
@node Modes of Operation
@section Modes of Operation

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
161
@sc{fine-delay} can work in one or more of the following modes:
162 163
@itemize @bullet
@item @b{Pulse Delay}: produces one or more pulse(s) on selected outputs
164
a given time after an input trigger pulse (fig. 1a).
165 166 167 168 169 170 171
@item @b{Pulse Generator}: produces one or more pulse(s) on selected outputs starting at an
absolute time value programmed by the user (fig. 1b). In this mode, time base is usually provided by the White Rabbit network.
@item @b{Time to Digital Converter}: tags all trigger pulses and delivers the timestamps to the user's application.
@end itemize

@float
@image{drawings/func, 12cm,,,pdf}
Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
172
@caption{Fig. 1. @sc{fine-delay} operating modes.}
173 174 175 176 177 178 179 180 181 182 183
@end float


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.

@c ==========================================================================
@node Mechanical/Environmental
@section Mechanical/Environmental

184 185
@float
@center @image{drawings/front_panels, 16cm,,,pdf}
Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
186
@caption{Fig. 2. @sc{fine-delay} front panel connector layout.}
187 188
@end float

189 190
@noindent @b{Mechanical and environmental specs:}
@itemize @bullet
191
@item Format: FMC (VITA 57), with rear zone for conduction cooling.
192
@item Operating temperature range: 0 - 90 degC.
193
@item Carrier connection: 160-pin Low Pin Count FMC connector.
194 195 196 197 198 199 200 201
@end itemize

@c ==========================================================================
@node Electrical
@section Electrical

@noindent @b{Inputs/Outputs:}
@itemize @bullet
202 203 204 205
@item 1 trigger input (LEMO 00).
@item 4 pulse outputs (LEMO 00).
@item 2 LEDs (termination status and trigger indicator).
@item Carrier communication via 160-pin Low Pin Count FMC connector.
206 207 208 209 210 211 212 213 214 215 216 217 218 219
@end itemize

@noindent @b{Trigger input:}
@itemize
@item TTL/LVTTL levels, DC-coupled. Reception of a trigger pulse is indicated by blinking the "TRIG" LED in the front panel.
@item 2 kOhm or 50 Ohm input impedance (programmable via software). 50 Ohm termination is indicated by the "TERM" LED in the front panel.
@item Power-up input impedance: 2 kOhm.
@item Protected against short circuit, overcurrent (> 200 mA) and overvoltage (up to +28 V).
@item Maximum input pulse edge rise time: 20 ns.
@end itemize

@noindent @b{Outputs:}
@itemize
@item TTL-compatible levels DC-coupled: Voh = 3 V, Vol = 200 mV (50 Ohm load), Voh = 6 V, Vol = 400 mV (high impedance).
220 221
@item Output impedance: 50 Ohm (source-terminated).
@item Rise/fall time: 2.5 ns (10%% - 90%%, 50 Ohm load).
222 223 224 225 226 227 228
@item Power-up state: LOW (2 kOhm pulldown), guaranteed glitch-free.
@item Protected against continuous short circuit, overcurrent and overvoltage (up to +28 V).
@end itemize

@noindent @b{Power supply:}
@itemize
@item Used power supplies: P12V0, P3V3, P3V3_AUX, VADJ (voltage monitor only).
229
@item Typical current consumption: 200 mA (P12V0) + 1.5 A (P3V3).
230 231 232 233 234 235 236 237 238
@item Power dissipation: 7 W. Forced cooling is required.
@end itemize

@c ==========================================================================
@node Timing
@section Timing

@float
@image{drawings/io_timing, 14cm,,,pdf}
Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
239
@caption{Fig. 2. @sc{fine-delay} timing parameter definitions.}
240 241 242 243
@end float

@noindent @b{Time base:}
@itemize @bullet
244
@item On-board oscillator accuracy: +/- 2.5 ppm (i.e. max. 2.5 ns error for a delay of 1 ms).
245 246 247 248 249 250
@item 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.
@end itemize

@noindent @b{Input timing:}
@itemize @bullet
@item Minimum pulse width: @math{t_{IW}} = 50 ns. Pulses below 24 ns are rejected.
251 252
@item Minimum gap between the last delayed output pulse and subsequent trigger pulse: @math{T_{LT}} = 50 ns.
@item Input TDC performance: 400 ps pp accuracy, 27 ps resolution, 70 ps trigger-to-trigger rms jitter (measured at 500 kHz pulse rate).
253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269
@end itemize

@noindent @b{Output timing:}
@itemize @bullet
@item Resolution: 10 ps.
@item Accuracy (pulse generator mode): 300 ps.
@item Train generation: trains of 1-65536 pulses or continuous square wave up to 10 MHz.
@item Output-to-output jitter (outputs programmed to the same delay): 10 ps rms.
@item Output-to-output jitter (outputs programmed to to different delays, worst case): 30 ps rms.
@item 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.
@item 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.
@end itemize

@noindent @b{Delay mode specific parameters:}
@itemize @bullet
@item Delay accuracy: < 1 ns.
@item Trigger-to-output jitter: 80 ps rms.
270
@item Trigger-to-output delay: minimum @math{T_{DLY}} = 600 ns, maximum @math{T_{DLY}} = 120 s.
271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287
@item Maximum trigger pulse rate: @math{T_{DLY} + N*(T_{SP} + T_{GAP}) +} 100 ns, where N = number of output pulses. 
@item Trigger pulses are ignored until the output with the biggest delay has finished generation of the pulse(s).
@end itemize


@c ==========================================================================
@node Principles of Operation
@section Principles of Operation

@b{Note:} If you are an electronics engineer, you can skip this section, as you will most likely find it rather boring.

@float
@image{drawings/analog_digital_delays, 16cm,,,pdf}
@caption{Fig. 3. Principle of operation of analog and digital delay generators.}
@end float

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, 
Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
288
@sc{fine-delay} is a digital delay generator, which relies on time tag arithmetic. The principle of operation of both generators is illustrated in figure 3.
289

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
290
When a trigger pulse comes to the input, @sc{fine-delay} first produces its' precise time tag using a Time-to-Digital converter (TDC). Afterwards, the time tag is summed together 
291 292 293 294 295
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,
Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
296
and the Pulse Generators can be programmed with arbitrary pulse start times instead of @math{t_{TRIG} + T_{DLY}}. Therefore, @sc{fine-delay} can be used simultaneously as 
297 298
a TDC, pulse generator or a pulse delay.

Alessandro Rubini's avatar
Alessandro Rubini committed
299
@c ##########################################################################
300 301 302
@node Driver Features
@chapter Driver Features

303
This driver is based on @sc{zio} and @i{fmc-bus}.  It supports initial
Alessandro Rubini's avatar
Alessandro Rubini committed
304
setup of the board, setting and reading time, run-time continuous
Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
305
calibration, input timestamping, output pulse generation and readback of output settings from the hardware.  It
Alessandro Rubini's avatar
Alessandro Rubini committed
306
supports user-defined offsets, so our users can tell the driver
307 308 309
about channel-specific delays (for example, to account for wiring) and
ignore the issue in application code.

310 311
For each feature offered the driver (and documentation) the driver
tries to offer
Alessandro Rubini's avatar
Alessandro Rubini committed
312
the following items; sometimes however one of them is missing for a specific
313
driver functionality, if we don't consider it important enough.
314 315 316 317 318 319 320 321 322 323 324

@itemize @bullet
@item A description of how the features works at low level;

@item A low-level user-space program to test the actual mechanism;

@item A C-language API to access the feature with data structures;

@item An example program based on that API.
@end itemize

325 326 327 328
@c ##########################################################################
@node Installation
@chapter Installation

329
This driver depends on four other modules (four @code{ohwr.org}
330 331
packages), as well as the Linux kernel.  Also, it
must talk to a specific FPGA binary file running in the device.
332 333 334 335 336

@c ==========================================================================
@node Gateware Dependencies
@section Gateware Dependencies

337
While previous versions of this package included a gateware binary
Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
338
in the @t{binaries/} subdirectory, in Jan 2014 we decided not to do
Alessandro Rubini's avatar
Alessandro Rubini committed
339
that any more.  Release versions of this package are expected to
340 341 342 343
point to ``current'' gateware images for different carriers.
Clearly the driver is expected to work on any @sc{fmc} carrier,
even those ignored to us, and we can't provide all binaries.

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
344 345 346 347 348 349
The up-to-date gateware binaries for the SVEC and SPEC carriers will be 
always available in the @i{Releases} section of the Fine Delay project:
@url{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.
350

351 352 353 354
@c ==========================================================================
@node Gateware Installation
@section Gateware Installation

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
355 356 357 358 359
By default, the driver looks for a gateware file named @code{/lib/firmware/fmc/[carrier]-fine-delay.bin}, where @code{[carrier]} is the carrier's name (lowercase - currently @code{svec} or @code{spec}). There are two ways to install the gateware:
@itemize
@item The easy way: run @code{make gateware_install} in the target system. This will automatically download all required files and install them in the right place.
@item The difficult way: download the bitstreams from the Release page (or build your own, as you wish) and put them in @code{/lib/firmware/fmc}. You may have to strip the version/date attached to the file names or create symlinks.
@end itemize
360

361
If you have several @i{fine-delay} cards in the same host, you can
Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
362
load different binaries for different cards, using appropriate
Alessandro Rubini's avatar
Alessandro Rubini committed
363 364
module parameters. Loading custom gateware files
is advised only for advanced users/developers. 
365

366 367 368 369
@c ==========================================================================
@node Software Dependencies
@section Software Dependencies

370
The kernel versions I am using during development is 3.4.  Everything
371
used here is known to build with all versions from 2.6.35 to
Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
372
3.12.
373

374
The driver, then, is based on the @sc{zio} framework, available from
375 376 377
@code{ohwr.org}. This version of @sc{zio} doesn't build with 3.13, for
a minor incompatibility, so this version of @i{fine-delay-sw} is
limited to Linux 3.12 as well.
378 379

The FMC mezzanine is supported by means of the @i{fmc-bus}
380
software project. This @i{fine-delay}
Alessandro Rubini's avatar
Alessandro Rubini committed
381
kernel module registers as a @i{driver} for the FMC bus abstraction,
382
and is verified with version @t{v2014-02} of the FMC package.
Alessandro Rubini's avatar
Alessandro Rubini committed
383
The same kernel range applies.
384

385
Both packages (@sc{zio} and @i{fmc-bus})
Alessandro Rubini's avatar
Alessandro Rubini committed
386
are currently checked out as @i{git submodules}
387 388 389
of this package, and each of them is retrieved at the right version
to be compatible with this driver.  This means you may just
ignore software dependencies and everything should work.
390

391 392 393 394 395
@sc{fmc} support is a @i{bus} in the Linux way, so you need both
a @i{device} and a @i{driver}. This driver is known to work both
with the @sc{spec} carrier on @sc{pci} and the @sc{svec} carrier
on @sc{vme}. The software packages that provide the respective @i{device}
are called @i{spec-sw} and @i{svec-sw}; both are hosted on @t{ohwr.org}.
396

397 398 399
Most of the non-@sc{cern} users are expected to run the @sc{spec}
carrier, so a compatible version of @i{spec-sw} is downloaded
as a submodule, too.
400

401 402 403 404
@c ==========================================================================
@node Software Installation
@section Software Installation

405 406 407
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:
408 409 410 411 412

@table @code
@item LINUX

	The top-level directory of the Linux kernel you are compiling
413 414
        against. If not set, the default may work if you compile in the same
        host where you expect to run the driver.
415

416 417
@end table

418 419
Most likely, this is all you need to set. After this, you can
run:
420 421

@example
422
    make
Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
423
    sudo make install gateware_install LINUX=$LINUX
424 425
@end example

426 427
In addition to the normal installation procedure for
@code{fmc-fine-delay.ko} you'll see the following message:
428 429

@example
430
    WARNING: Consider "make prereq_install"
431 432
@end example

433
The @i{prerequisite} packages are @i{zio} and @i{fmc-bus};
434 435 436
unless you already installed your own preferred version, you are
expected to install the version this packages suggests. This step
can be performed by:
437

438 439 440 441
@example
    make
    sudo make prereq_install LINUX=$LINUX
@end example
442

443 444 445 446
The step is not performed by default to avoid overwriting some
other versions of the drivers. After @code{make prereq_install},
the warning message won't be repeated any more if you change this
driver and @code{make install} again.
447

Alessandro Rubini's avatar
Alessandro Rubini committed
448
After installation, your carrier driver should load automatically
449
(for example, the PCI bus will load @code{spec.ko}), but @code{
450
fmc-fine-delay.ko} must be loaded manually, because support for
451
automatic loading is not yet in place. The suggested command is
Alessandro Rubini's avatar
Alessandro Rubini committed
452
one or the other of the following two:
453 454

@smallexample
Alessandro Rubini's avatar
Alessandro Rubini committed
455
   modprobe fmc-fine-delay [<parameter> ...]         # after make install
456
   insmod kernel/fmc-fine-delay.ko [<parameter> ...]  # if not installed
457
@end smallexample
458

Alessandro Rubini's avatar
Alessandro Rubini committed
459 460
Available module parameters are described in @ref{Module Parameters}.
Unless you customized or want to customize one of the three
461 462 463 464
related packages, you can skip the rest of this section.

@sp 1

Alessandro Rubini's avatar
Alessandro Rubini committed
465 466 467
In order to compile @i{fine-delay} against a specific repository of one
of the related packages, ignoring the local @i{submodule}
you can use one or more of the following
468 469 470 471 472 473
environment variables:

@table @code

@item ZIO
@itemx FMC_BUS
474
@itemx SPEC_SW
475 476 477 478 479 480 481 482

	The top-level directory of the repository checkout of each
        package. Most users won't need to set them, as the Makefiles
        point them to the proper place by default.

@end table

If any of the above is set, headers and dependencies for the
483
respective package are taken from the chosen directory. If you
Alessandro Rubini's avatar
Alessandro Rubini committed
484 485
@code{make prereq_install} with any of these variables set, they are
be used to know where to install from, instead of using local submodules.
486

487 488 489 490 491
@c ==========================================================================
@node Module Parameters
@section Module Parameters

The driver accepts a few load-time parameters for configuration. You
492 493
can pass them to @i{insmod} amd @i{modprobe} directly, or write them
in @code{/etc/modules.conf} or the proper file in @code{/etc/modutils/}.
494 495 496 497 498 499 500 501

The following parameters are used:

@table @code

@item verbose=

	The parameter defaults to 0. If set, it enables more diagnostic
502 503 504
        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 @code{DEBUG}).
505

506 507
@item timer_ms=

508 509 510 511 512
	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.
513

514 515
@item calib_s=

516
	The period, in seconds, of temperature measurement to re-calibrate
517 518
        the output delays. Defaults to 30. If set to zero, the
        re-calibration timer is not activated.
519

520 521
@end table

522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540
The module also uses the two parameters provided by the @i{fmc}
framework:

@table @code

@item busid=

	A list of bus identifiers the driver will accept to driver.
        Other identifiers will lead to a failure in the @i{probe}
        function. The meaning of the identifiers is carrier-specific;
        the SPEC uses the bus number and @i{devfn}, where the latter
        is most likely zero.

@item gateware=

	A list of gateware file names. The names passed are made to
        match the @i{busid} parameters, in the same order. This
        means that you can't make the driver load a different gateware
        file without passing the respective @i{busid}. Actually, to
541
        change the gateware for all boards, you may just replace
542 543
        the file in @file{/lib/firmware}. (Maybe I'll add an
        option to change the name at load time for all boards).
544
@c FIXME: name for gateware file (the global one)
545 546 547 548 549 550 551 552 553 554 555 556

@end table

For example, this host has two SPEC cards:

@smallexample
   spusa.root# lspci | grep CERN
   02:00.0 Non-VGA unclassified device: CERN/ECP/EDU Device 018d (rev 03)
   04:00.0 Non-VGA unclassified device: CERN/ECP/EDU Device 018d (rev 03)
@end smallexample

One of the cards hosts a @i{fine-delay} mezzanine and the other does
Alessandro Rubini's avatar
Alessandro Rubini committed
557 558 559 560 561
not. FMC identifiers are not yet used by this driver at this point in time.
(They will be there in  the next release: code is there but not finalized).
So, here
you can use @code{busid=} to choose which SPEC must use @i{fine-delay},
leaving the other one alone:
562 563 564

@smallexample
spusa.root# insmod fmc-fine-delay.ko busid=0x0200
Alessandro Rubini's avatar
Alessandro Rubini committed
565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581
[ 4603.994936] spec 0000:02:00.0: Driver has no ID: matches all
[ 4604.000624] spec 0000:02:00.0: reprogramming with fmc/fine-delay.bin
[ 4604.206515] spec 0000:02:00.0: FPGA programming successful
[ 4604.212442] spec 0000:02:00.0: Gateware successfully loaded
[ 4604.218037] spec 0000:02:00.0: fd_regs_base is 80000
[ 4604.223023] spec 0000:02:00.0: fmc_fine_delay: initializing
[ 4604.228624] spec 0000:02:00.0: calibration: version 3, date 20130427
[ 4605.691404] fd_read_temp: Scratchpad: 9f:04:4b:46:7f:ff:01:10:89
[ 4605.697615] fd_read_temp: Temperature 0x49f (12 bits: 73.937)
[ 4606.645545] fd_calibrate_outputs: ch1: 8ns @@859 (f 827, off 32, t 71.00)
[ 4606.815228] fd_calibrate_outputs: ch2: 8ns @@867 (f 827, off 40, t 71.00)
[ 4607.001027] fd_calibrate_outputs: ch3: 8ns @@854 (f 827, off 27, t 71.00)
[ 4607.187007] fd_calibrate_outputs: ch4: 8ns @@859 (f 827, off 32, t 71.00)
[ 4607.356103] fmc_fine_delay: Found i2c device at 0x50
[ 4607.364039] spec 0000:02:00.0: Using interrupts for input
[ 4607.369549] spec 0000:04:00.0: Driver has no ID: matches all
[ 4607.375243] spec 0000:04:00.0: not using "fmc_fine_delay" according to modparam
582 583 584 585 586 587
@end smallexample

If you use @code{show_sdb=1}, you'll get the following dump of the
internal SDB structure to @i{printk}. The @i{Self Describing Bus} data
structure is described in the documentation of the
@i{fpga-config-space} project, under @code{ohwr.org}.
588 589

@smallexample
Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606
SDB: 00000651:e6a542c9 WB4-Crossbar-GSI   
SDB: 0000ce42:f19ede1a Fine-Delay-Core     (00010000-000107ff)
SDB: 0000ce42:f19ede1a Fine-Delay-Core     (00020000-000207ff)
SDB: 0000ce42:00000013 WB-VIC-Int.Control  (00030000-000300ff)
SDB: 00000651:eef0b198 WB4-Bridge-GSI      (bridge: 00040000)
SDB:    00000651:e6a542c9 WB4-Crossbar-GSI   
SDB:    0000ce42:66cfeb52 WB4-BlockRAM        (00040000-00055fff)
SDB:    00000651:eef0b198 WB4-Bridge-GSI      (bridge: 00060000)
SDB:       00000651:e6a542c9 WB4-Crossbar-GSI   
SDB:       0000ce42:ab28633a WR-Mini-NIC         (00060000-000600ff)
SDB:       0000ce42:650c2d4f WR-Endpoint         (00060100-000601ff)
SDB:       0000ce42:65158dc0 WR-Soft-PLL         (00060200-000602ff)
SDB:       0000ce42:de0d8ced WR-PPS-Generator    (00060300-000603ff)
SDB:       0000ce42:ff07fc47 WR-Periph-Syscon    (00060400-000604ff)
SDB:       0000ce42:e2d13d04 WR-Periph-UART      (00060500-000605ff)
SDB:       0000ce42:779c5443 WR-Periph-1Wire     (00060600-000606ff)
SDB:       0000ce42:779c5445 WR-Periph-AuxWB     (00060700-000607ff)
Alessandro Rubini's avatar
Alessandro Rubini committed
607 608
SDB: Bitstream 'svec-fine-delay' synthesized 20140317 by twlostow \
              (ISE version 133), commit e95b10c776f5f7603f49fcf1330e0c07
Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
609
SDB: Synthesis repository: git://ohwr.org/fmc-projects/fmc-delay-1ns-8cha.git
610 611
@end smallexample

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
612 613
The module also supports some more parameters that are
calibration-specific. They are described in the @ref{Calibration} section.
614

615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636
@c ##########################################################################
@node Source Code Conventions
@chapter Source Code Conventions

This is a random list of conventions I use in this package

@itemize @bullet

@item All internal symbols in the driver begin with @code{fd_}
(excluding local variables like @i{i} and similar stuff). So you know
if something is local or comes from the kernel.

@item All library functions and public data begin with @code{fdelay_}.

@item The board passed as a library token (@code{struct fdelay_board})
is opaque, so the user doesn't access it.  Internally it is called
@code{userb} because @code{b} is the real one being used. If you need
to access library internals from a user file just define
@code{FDELAY_INTERNAL} before including @code{fdelay-lib.h}.

@item The driver header is called @code{fine-delay.h} while the user one
is @code{fdelay-lib.h}. The latter includes the former, which user
637 638 639 640
programs should not refer to.

@item The @i{tools} directory hosts the suggested command-line tools
to use the device for testing and quick access. They demonstrate use
641 642
of the library functions using internally-consistent command line
conventions. All command names begin with @t{fmc-fdelay-}
643

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
644
@item The @i{oldtools} directory includes tools that access @sc{zio}
645 646 647
directly; they are not built by default any more because they are now
deprecated; we also removed documentation for them, for the same
reason.  We keep them for our previous users, in case they still want
648 649 650 651
to run previous scripts the saved in the past. The directory
also includes tools that used to be built withing @t{lib/} and
are deprecated as well. The old tools use
the name patterns @code{fd-raw-} and @code{fdelay-}
652

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
653 654 655 656 657
@item The @i{lib} directory contains the userspace library, providing a
simple C API to access the driver.

@item The @i{tools} directory contains a number of tools built on top of that library that let
you access all features of the @sc{fine-delay} mezzanine.
658 659 660

@end itemize

661
@c ##########################################################################
Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
662 663 664
@c ##########################################################################
@node Using the Provided API
@chapter Using the Provided API
665

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
666 667 668 669 670 671 672
This chapter describes the higher level interface to the board,
designed for user applications to use.  The code lives in the @i{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 @code{fine-delay.h} (which it currently pulls
from the parent directory) and the @sc{zio} headers, retrieved using the
@code{ZIO} environment variable).
673 674

@c ==========================================================================
Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
675 676
@node Initialization and Cleanup
@section Initialization and Cleanup
677

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
678
The library offers the following structures and functions:
679

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
680
@table @code
681

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
682
@item struct fdelay_board;
Alessandro Rubini's avatar
Alessandro Rubini committed
683

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
684 685 686
	This is the ``opaque'' token that is being used by library clients.
        If you want to see the internals define @code{FDELAY_INTERNAL}
        and look at @i{fdelay_list.c}.
687

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
688 689
@item int fdelay_init(void);
@itemx void fdelay_exit(void);
690

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
691 692 693 694 695
	The former function allocates its internal data and returns
	the number of boards currently found on the system. The latter
        releases any allocated data. If @i{init} fails, it returns -1 with
        a proper @code{errno} value. If no boards are there it returns 0.
        You should not load or unload drivers between @i{init} and @i{exit}.
696

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
697 698
@item struct fdelay_board *fdelay_open(int index, int dev_id);
@item int fdelay_close(struct fdelay_board *);
699

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
700 701 702 703 704 705 706
	The former function opens a board and returns a token that can
        be used in subsequent calls. The latter function undoes it.
        You can refer to a board either by index or by
        @code{dev_id}. Either argument (but not both) may be -1. If both
        are different from -1 the index and dev_id must match. If a mismatch
        is found, the function return NULL with @code{EINVAL}; if either index or
        @code{dev_id} are not found, the function returns NULL with @code{ENODEV}.
707

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
708
@item struct fdelay_board *fdelay_open_by_lun(int lun);
709

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
710 711 712 713 714
	The function opens a pointer to a board, similarly to @i{fdelay_open},
        but it uses the Logical Unit Number as argument instead. The LUN
        is used internally be CERN libraries, and the function is needed
        for compatibility with the installed tool-set.  The function uses
        a symbolic link in @i{dev}, created by the local installation procedure.
715

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
716
@end table
717

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
718
Example code: all tools in @code{tools/} subdirectory.
719

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
720 721 722
@c ==========================================================================
@node Time Management
@section Time Management
723

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
724
These are the primitives the library offers for time management, including support for White Rabbit network synchronization.
725

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
726
@table @code
727

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
728
@item struct fdelay_time;
729

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
730 731 732
	The structure has the same fields as the one in the initial
        user-space library. All but @i{utc} are unsigned 32-bit values
        whereas they were different types in the first library.
733

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
734 735
@item int fdelay_set_time(struct fdelay_board *b, struct fdelay_time *t);
@itemx int fdelay_get_time(struct fdelay_board *b, struct fdelay_time *t);
Alessandro Rubini's avatar
Alessandro Rubini committed
736

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
737 738 739 740
	The functions are used to set board time from a user-provided
        time, and to retrieve the current board time to user space.
        The functions return 0 on success. They only use the fields
        @i{utc} and @i{coarse} of @code{struct fdelay_time}.
741

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
742
@item int fdelay_set_host_time(struct fdelay_board *b);
743

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
744 745
	The function sets board time equal to host time. The precision
        should be in the order of 1 microsecond, but will drift over time. This function is only provided to 
Alessandro Rubini's avatar
Alessandro Rubini committed
746 747
        coarsely correlate the board time with the system time. Relying on system time 
        for synchronizing multiple @sc{fine-delays} is strongly discouraged.
748

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
749
@item int fdelay_wr_mode(struct fdelay_board *b, int on);
750

Alessandro Rubini's avatar
Alessandro Rubini committed
751
	The function enables/disables White Rabbit mode.
Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
752 753
        It may fail with @code{ENOTSUPP} if there's no White Rabbit support in the
        gateware.
754

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
755
@item int fdelay_check_wr_mode(struct fdelay_board *b);
756

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
757 758 759
	The function returns 0 if the WR slave is synchronized, @code{EAGAIN}
        if it is enabled by not yet synchronized, @code{ENODEV}
        if WR-mode is currently disabled and @code{ENOLINK} if the WR link is down (e.g. unconnected cable).
760

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
761
@end table
762

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
763
Example code: @code{fmc-fdelay-board-time} tool.
764

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
765 766 767
@c ==========================================================================
@node Input Configuration
@section Input Configuration
768

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
769 770
To configure the input channel for a board, the library offers the
following function and macros:
771

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
772
@table @code
773

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
774 775
@item int fdelay_set_config_tdc(struct fdelay_board *b, int flags);
@itemx int fdelay_get_config_tdc(struct fdelay_board *b);
Alessandro Rubini's avatar
Alessandro Rubini committed
776

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
777 778 779 780 781
	The function configures a few options in the input channel.
	The @i{flags} argument is a bit-mask of the following three
        values (note that 0 is the default at initialization time).
        The function returns -1 with @code{EINVAL} if the @i{flags}
        argument includes undefined bits.
Alessandro Rubini's avatar
Alessandro Rubini committed
782

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
783 784 785
@item FD_TDCF_DISABLE_INPUT
@itemx FD_TDCF_DISABLE_TSTAMP
@itemx FD_TDCF_TERM_50
Alessandro Rubini's avatar
Alessandro Rubini committed
786

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
787 788 789
	The first bit disables the input channel, the second disables
        acquisition of timestamps, and the last enables the 50-ohm
        termination on the input channel.
Alessandro Rubini's avatar
Alessandro Rubini committed
790

791 792
@end table

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
793
Example code: @code{fmc-fdelay-term} tool.
794 795


Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
796 797 798
@c ==========================================================================
@node Reading Input Timestamps
@section Reading Input Timestamps
799

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
800
The library offers the following functions that deal with the input stamps:
801

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
802
@table @code
803

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
804
@item int fdelay_fread(struct fdelay_board *b, struct fdelay_time *t, int n);
805

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
806 807 808
	The function behaves like @i{fread}: it tries to read all samples,
        even if it implies sleeping several times.  Use it only if you are
        aware that all the expected pulses will reach you.
809

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
810 811
@item int fdelay_read(struct fdelay_board *b, struct fdelay_time *t, int n,
		       int flags);
812

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
813 814 815 816 817 818 819
	The function behaves like @i{read}: it will wait at most once
        and return the number of samples that it received.  The @i{flags}
        argument is used to pass 0 or @code{O_NONBLOCK}. If a non-blocking
        read is performed, the function may return -1 with @code{EAGAIN}
        if nothing is pending in the hardware FIFO.
        
@item int fdelay_fileno_tdc(struct fdelay_board *b);
820

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
821 822 823 824 825 826 827
	This returns the file descriptor associated to the TDC device,
        so you can @i{select} or @i{poll} before calling @i{fdelay_read}.
        If access fails (e.g., for permission problems), the functions
        returns -1 with @code{errno} properly set.

@end table

828 829
The test programs for the functions are in @i{oldtools/}, not built by
default.
830 831

@c ==========================================================================
Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
832 833
@node Output Configuration
@section Output Configuration
834

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
835
The library offers the following functions for output configuration:
836

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
837
@table @code
838

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
839 840
@item int fdelay_config_pulse(board, channel, pulse_cfg);
@itemx int fdelay_config_pulse_ps(board, channel, pulse_ps_cfg);
841

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
842 843 844 845 846 847 848
	The two functions configure the channel
        for pulse or delay mode. The channel numbers are 0..3 (that is, the number of the output on the 
        front panel minus 1, you may use @code{FDELAY_OUTPUT} macro to convert). The former function receives
        @code{struct fdelay_pulse} (with split utc/coarse/frac times)
        while the latter receives @code{struct fdelay_pulse_ps}, with
        picosecond-based time values. The functions return 0 on success, -1
        and an error code in @code{errno} in case of failure.
849

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
850 851
@item int fdelay_get_config_pulse(board, channel, pulse_cfg);
@itemx int fdelay_get_config_pulse_ps(board, channel, pulse_ps_cfg);
852

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
853 854 855 856 857
       The two functions return the configuration of the channel (numbered 0..3) read
       from the hardware. They may be used to check the correctness of outputs' programming. The former function returns
       @code{struct fdelay_pulse} (with split utc/coarse/frac times)
       while the latter returns @code{struct fdelay_pulse_ps}, with
       picosecond-based time values.
Alessandro Rubini's avatar
Alessandro Rubini committed
858

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
859
@item int fdelay_has_triggered(struct fdelay_board *b, int channel);
860

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
861 862
	The function returns 1 of the output channel (numbered 0..3) has
        triggered since the last configuration request, 0 otherwise.
863

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
864
@end table
865

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
866 867 868 869
The configuration functions receive a time configuration. The
starting time is passed as @code{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:
870

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
871 872 873 874 875 876
@example
   struct fdelay_time {
           uint64_t utc;
           uint32_t coarse;    uint32_t frac;
           uint32_t seq_id;    uint32_t channel;
   };
877

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
878 879 880 881
   struct fdelay_pulse {
           int mode;           int rep;    /* -1 == infinite */
           struct fdelay_time start, end, loop;
   };
882

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
883 884 885 886 887 888
   struct fdelay_pulse_ps {
           int mode;          int rep;
           struct fdelay_time start;
           uint64_t length, period;
   };
@end example
889

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
890 891 892
The @code{rep} field represents the repetition count, to output a
train of pulses. The mode field is one of @code{FD_OUT_MODE_DISABLED},
@code{FD_OUT_MODE_DELAY}, @code{FD_OUT_MODE_PULSE}.
893

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
894
Example code: @code{fmc-fdelay-pulse} tool.
895

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
896 897
@node Miscellanous functions
@section Miscellanous functions
898

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
899
@table @code
900

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
901 902
@item void fdelay_pico_to_time(uint64_t *pico, struct fdelay_time *time);
           Splits a time value expressed in picoseconds to @sc{fine-delay}'s internal time format (utc/coarse/frac).
903

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
904 905
@item void fdelay_time_to_pico(struct fdelay_time *time, uint64_t *pico);
           Converts from @sc{fine-delay}'s internal time format (utc/coarse/frac) to plain picoseconds.
906

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
907 908
@item float fdelay_read_temperature(struct fdelay_board *b);
            Returns the temperature of the given board, in degrees Celsius.
909

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
910
@end table
911

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
912
@c ##########################################################################
913 914
@node Command Line Tools
@chapter Command Line Tools
915

916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949
This chapter describes the command line tools that come with the
driver and reside in the @code{tools/} subdirectory. They are provided
as diagnostic utilities and to demonstrate how to use the library.

@c ==========================================================================
@node General Command Line Conventions
@section General Command Line Conventions

Most tools accept the following command-line options, in a
consistent way:

@table @code

@item -d <devid>
@itemx -i <index>

	Used to select one board among several. See the description 
        of @i{fdelay_open} in @ref{Initialization and Cleanup}. If no
        argument is given, the ``first'' board is used (index is 0).

@end table

@c ==========================================================================
@node fmc-fdelay-list
@section fmc-fdelay-list

The command takes no arguments. It reports the list of available
boards in the current system:

@smallexample
   spusa# ./tools/fmc-fdelay-list
   ./tools/fmc-fdelay-list: found 1 board
     dev_id 0200, /dev/zio/zio-fd-0200, /sys/bus/zio/devices/zio-fd-0200
@end smallexample
950

951 952 953 954 955
@c ==========================================================================
@node fmc-fdelay-term
@section fmc-fdelay-term

The command can be used to activate or deactivate the 50 ohm
956 957 958
termination resistor.

In addition to the @t{-i} or @t{-d}
959
arguments, mandatory if more than one board is found on the
960 961 962
host system, the command receives one optional argument, either
@t{1} or @t{on} (activate termination) or @t{0} or @t{off}
(deactivate termination).
963 964

@smallexample
965
   spusa# ./tools/fmc-fdelay-term on
966 967 968
   ./tools/fmc-fdelay-term: termination is on
@end smallexample

969 970 971
If no arguments are passed the termination status is reported back but
not changed.

972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014
@c ==========================================================================
@node fmc-fdelay-board-time
@section fmc-fdelay-board-time

The command is used to act on the time notion of the @sc{fine-delay} card.

In addition to the @t{-i} or @t{-d}
arguments, mandatory if more than one board is found on the
host system, the command receives one mandatory argument, that is
either a command or a floating point number. The number is the
time, in seconds, to be set in the card; the command is one of
the following ones:

@table @code
@item get

	Read board time and print to @i{stdout}.

@item host

	Set board time from host time

@item wr

	Lock the boards to White Rabbit time. It may block if no White
	Rabbit is there. No timeout is currently available.

@item local

	Detach the board from White Rabbit, and run local time instead.

@end table

Examples:
@smallexample
   spusa# ./lib/fdelay-board-time  25.5; ./lib/fdelay-board-time get
   25.504007360
   spusa# ./lib/fdelay-board-time  get
   34.111048968
   spusa# ./lib/fdelay-board-time  host
   spusa# ./lib/fdelay-board-time  get
   1335974946.493415600
@end smallexample
1015

1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035
@c ==========================================================================
@node fmc-fdelay-input
@section fmc-fdelay-input

The tool reports input pulses to stdout.  It receives the
usual @t{-i} or @t{-d} arguments to select one board, mandatory
if more than one @sc{fine-delay} card is found.

It receives the following options:

@table @code

@item -c <count>

	Number of pulses to print. Default (0) means run forever.

@item -n

	Nonblocking mode: just print what is pending in the buffer.

1036
@item -f
1037

1038 1039 1040
	Floating point: print as a floatingpoint seconds.pico value.
        The default is a human-readable string, where the decimal part
        is split.
1041

1042
@item -r
1043

1044
	Raw output: print the three hardware timestamps, in decimal.
1045 1046 1047

@end table

1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064
This an example output, reading a pps signal through a 16ns cable:

@smallexample
   spusa.root# ./tools/fmc-fdelay-input -c 3
   seq 10921:     time      11984:000,000,015,328 ps
   seq 10922:     time      11985:000,000,015,410 ps
   seq 10923:     time      11986:000,000,015,248 ps
   spusa.root# ./tools/fmc-fdelay-input -c 3 -r
   seq 10924:      raw   utc      11987,  coarse         1,  frac      3773
   seq 10925:      raw   utc      11988,  coarse         1,  frac      3814
   seq 10926:      raw   utc      11989,  coarse         1,  frac      3794
   spusa.root# ./tools/fmc-fdelay-input -c 3 -f
   seq 10927:     time      11990.000000015328
   seq 10928:     time      11991.000000015410
   seq 10929:     time      11992.000000015410
@end smallexample

1065 1066 1067 1068
In a future release we'll support reading concurrently from several
boards.


1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080
@c ==========================================================================
@node fmc-fdelay-pulse
@section fmc-fdelay-pulse

The program can be used to program one of the output channels to
output a sequence of pulses.  It can parse the following command-line
options:

@table @code
@item -o <output>

	Output channels are numbered 1 to 4, as written on the device panel.
1081
        Each command invocation can set only one output channel; the
1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094
        last @t{-o} specified takes precedence.

@item -c <count>

	Output repeat count: 0 is the default and means forever

@item -m <mode>

	Output mode. Can be @t{pulse}, @t{delay} or @t{disable}.

@item -r <reltime>

	Output pulse at a relative time in the future. The time is
1095 1096 1097 1098
        a fraction of a second, specified as for @t{-T} and @t{-w},
        described below.  For delay mode the time is used as
        a delay value from input events; for pulse mode the time
        represents a fraction of the next absolute second.
1099 1100 1101

@item -D <date>

1102 1103
	Output pulse at a specified date. The argument is parsed
        as @t{<seconds>:<nanoseconds>}.
1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140

@c @item -f <frequency>
@c
@c	Frequency of the output signal. A trailing @t{k} or @t{M}
@c        means kilohertz or megaherts. Floating point is allowed
@c        but internal approximation is not accounted for. So
@c        @t{2.5M} will work, but 2.000001M will probably not.
@c        The last frequency or period specified takes precedence.
@c        Default frequency is 10Hz.

@item -T <period>
@itemx -w <width>

	Period and width of the output signal. A trailing @t{m},
        @t{u}, @t{n}, @t{p} means milli, micro, nano, pico, resp.
        The parser supports additions and subtractions, e.g.
        @t{50m-20n}.
        The period defaults to 100ms and the width defaults to 8us

@item -t

	Wait for the trigger to happen before returning. The boards reports
        a trigger event when the requested pulse sequence is initiated,
        either because the absolute time arrived or because an input
        pulse was detected and the requested delay elapsed.

@item -p
@itemx -1

	Pulse-per-seconds and 10MHz. These are shorthands setting many
        parameters.

@item -v

	Verbose: report action to stdout before telling the driver.

@end table
1141

1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158
This is, for example, how verbose operation reports the request for a single pulse 300ns wide, 2 microseconds into the next second.:

@smallexample
  spusa.root# ./tools/fmc-fdelay-board-time get; \
              ./tools/fmc-fdelay-pulse -i 0 -o 1 -m pulse -r 2u -w 300n -c 1 -t -v
  WR Status: disabled.
  Time: 13728.801090400
  Channel 1, mode pulse, repeat 1
    start  time      13729:000,002,000,000 ps
    end    time      13729:000,002,300,000 ps
    loop   time          0:100,000,000,000 ps
  Channel 1, mode pulse, repeat 1
    start   raw   utc      13729,  coarse       250,  frac         0
    end     raw   utc      13729,  coarse       287,  frac      2048
    loop    raw   utc          0,  coarse  12500000,  frac         0
@end smallexample

1159 1160 1161 1162
@c ==========================================================================
@node fmc-fdelay-status
@section fmc-fdelay-status

1163 1164 1165 1166 1167 1168 1169 1170
The program reports the current output status of the four channels,
both in human-readable and raw format.  The receives no arguments
besides the usual @t{-i} or @t{-d}.

Please note that the tool reads back hardware values, which are already
fixed for calibration delays.  For example, this is the output
I get after the previously-shown activation command, that was for
13729 + 2 microseconds:
1171 1172

@smallexample
1173 1174 1175 1176 1177
  spusa.root# ./tools/fmc-fdelay-status
  Channel 1, mode already-triggered, repeat 1
    start  time      13729:000,001,961,814 ps
    end    time      13729:000,002,261,814 ps
    loop   time          0:100,000,000,000 ps
1178
  Channel 1, mode already-triggered, repeat 1
1179 1180 1181 1182
    start   raw   utc      13729,  coarse       245,  frac       929
    end     raw   utc      13729,  coarse       282,  frac      2977
    loop    raw   utc          0,  coarse  12500000,  frac         0
  [...]
1183 1184
@end smallexample

1185 1186 1187 1188
The difference in value depends on the @t{delay-offset} value for
the channel, according to calibration.


Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
1189 1190 1191
@c ##########################################################################
@node Troubleshooting
@appendix Troubleshooting
1192

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
1193 1194
This chapters lists a few errors that may happen and how to deal with
them.
1195

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
1196 1197 1198
@c ==========================================================================
@node make modules_install misbehaves
@section make modules_install misbehaves
1199

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
1200 1201
The command @i{sudo make modules_install} may place the modules in the wrong
directory or fail with an error like:
1202 1203

@smallexample
Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
1204
   make: *** /lib/modules/2.6.37+/build: No such file or directory.
1205 1206
@end smallexample

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
1207 1208 1209
This happens when you compiled by setting @code{LINUX=} and your
@i{sudo} is not propagating the environment to its child processes.
In this case, you should run this command instead
1210 1211

@smallexample
Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
1212
   sudo make modules_install  LINUX=$LINUX
1213 1214
@end smallexample

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
1215 1216 1217
@c ==========================================================================
@node Version Mismatch
@section Version Mismatch
1218

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
1219
The @i{fdelay} library may report a version mismatch like this:
1220

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
1221 1222 1223 1224 1225 1226 1227 1228 1229 1230
@example
   spusa# ./lib/fmc-fdelay-board-time  get
   fdelay_init: version mismatch, lib(1) != drv(2)
   ./lib/fmc-fdelay-board-time: fdelay_init(): Input/output error
@end example
     
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 @i{/sys}. I suggest recompiling both the kernel
driver and user space from a single release of the source package.
1231 1232


Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
1233 1234
@node Additional Information for Developers
@appendix Additional Information for Developers
1235

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
1236 1237
This appendix contains some extra information on the internals of the driver and how to access it bypassing the library. If you are not
a @sc{fine-delay}, @sc{fmc-bus} or @sc{zio} developer, you can skip this chapter and just use the library.
1238

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
1239 1240
@node Using the driver directly
@section Using the driver directly
1241

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
1242 1243 1244 1245
The driver is designed as a @sc{zio} driver that offers 1 input channel and
4 output channels. Since each output channel is independent (they do
not output at the same time) the device is modeled as 5 separate
@i{csets}.
1246

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
1247 1248 1249
The reader of this chapter is expected to be confident with basic @sc{zio}
concepts, available in @sc{zio} documentation (@sc{zio} is an @code{ohwr.org}
project).
1250

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264
@c ==========================================================================
@node The device
@section The device

The overall device includes a few device attributes and a few attributes
specific to the csets (some attributes for input and some attributes for
output).
The attributes allow to read and write the internal timing of the
card, as well as other internal parameters, documented below. Since @sc{zio}
has no support for @i{ioctl}, all the attributes appear in @i{sysfs}.
For multi-valued attributes (like a time tag, which is more than 32
bits) the order of reading and writing is mandated by the driver
(e.g.: writing the seconds field of a time must be last, as it is the
action that fires hardware access for all current values).
1265

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
1266
The device appears in @i{/dev} as a set of char devices:
1267

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280
@smallexample
   spusa# ls -l /dev/zio/*
   crw------- 1 root root 249,   0 Apr 26 00:26 /dev/zio/zio-fd-0200-0-0-ctrl
   crw------- 1 root root 249,   1 Apr 26 00:26 /dev/zio/zio-fd-0200-0-0-data
   crw------- 1 root root 249,  32 Apr 26 00:26 /dev/zio/zio-fd-0200-1-0-ctrl
   crw------- 1 root root 249,  33 Apr 26 00:26 /dev/zio/zio-fd-0200-1-0-data
   crw------- 1 root root 249,  64 Apr 26 00:26 /dev/zio/zio-fd-0200-2-0-ctrl
   crw------- 1 root root 249,  65 Apr 26 00:26 /dev/zio/zio-fd-0200-2-0-data
   crw------- 1 root root 249,  96 Apr 26 00:26 /dev/zio/zio-fd-0200-3-0-ctrl
   crw------- 1 root root 249,  97 Apr 26 00:26 /dev/zio/zio-fd-0200-3-0-data
   crw------- 1 root root 249, 128 Apr 26 00:26 /dev/zio/zio-fd-0200-4-0-ctrl
   crw------- 1 root root 249, 129 Apr 26 00:26 /dev/zio/zio-fd-0200-4-0-data
@end smallexample
1281

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
1282 1283 1284 1285 1286 1287
The actual pathnames depend on the version of @i{udev}, and the support
library tries the three names that have been used over time
(the newest name is shown above; the oldest didn't have the two
@code{zio} ).
Also, please note that a still-newer version of @i{udev} obeys device
permissions, so you'll have read-only and write-only device files.
1288

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
1289 1290
In this drivers, @i{cset} 0 is for the input signal, and @i{csets} 1..4 are
for the output channels.
1291

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
1292 1293 1294 1295 1296
If more than one board is probed for, you'll have two or more similar
sets of devices, differing in the @i{dev_id} field, i.e. the
@code{0200} that follows the device name @code{zio-fd} in the
stanza above. The @i{dev_id} field is built using the PCI bus
and the @i{devfn} octet; the example above refers to slot 0 of bus 2.
1297

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
1298 1299
For remotely-controlled devices (e.g. Etherbone) the problem will need
to be solved differently.
1300

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
1301 1302 1303
Device (and channel) attributes can be accessed in the proper @i{sysfs}
directory. For a card in slot 0 of bus 2 (like shown above), the
directory is @i{/sys/bus/zio/devices/zio-fd-0200}:
1304 1305

@smallexample
Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
1306 1307 1308 1309 1310
   spusa# ls -Ff /sys/bus/zio/devices/zio-fd-0200/
   ./      enable           utc-l        subsystem  fd-ch1/
   ../     resolution-bits  coarse       power/     fd-ch2/
   uevent  version          command      driver     fd-ch3/
   name    utc-h            temperature  fd-input/  fd-ch4/
1311 1312
@end smallexample

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
1313 1314 1315
@c ==========================================================================
@node Device Attributes
@section Device Attributes
1316

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
1317 1318 1319 1320 1321 1322 1323
Device-wide attributes are the three time tags (@i{utc-h}, @i{utc-l},
@i{coarse}), a read-only @i{version}, a read-only @i{temperature} 
and a write-only @i{command}.
To read device time you
should read @i{utc-h} first.  Reading @u{utc-h} will atomically read
all values from the card and store them in the software driver: when
reading @i{utc-l} and @i{coarse} you'll get such cached values.
1324

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
1325
Example:
1326
@smallexample
Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
1327 1328 1329 1330 1331 1332
   spusa# cd /sys/bus/zio/devices/zio-fd-0200/
   spusa# cat coarse coarse utc-h coarse
   75136756
   75136756
   0
   47088910
1333 1334
@end smallexample

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
1335 1336
To set the time, you can write the three values leaving @i{utc-h}
last: writing @i{utc-h} atomically programs the hardware:
1337 1338

@smallexample
Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
1339 1340 1341 1342
   spusa# echo 10000 > coarse; echo 10000 > utc-l; echo 0 > utc-h
   spusa# cat utc-h utc-l
   0
   10003
1343 1344
@end smallexample

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
1345 1346
The temperature value is scaled by four bits, so you need divide it by
16 to obtain the value in degrees. In this example:
1347 1348

@smallexample
Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
1349 1350
   spusa# cat temperature
   1129
1351 1352
@end smallexample

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
1353 1354 1355 1356 1357 1358 1359
Temperature is 70.5625 degrees.

If you write 0 to @i{command}, board time will be
synchronized to the current Linux clock within one microsecond
(reading Linux time and writing to the @i{fine-delay} registers is
done with interrupts disabled, so the actual synchronization precision
depends on the speed of your CPU and PCI bus):
1360 1361

@smallexample
Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
1362 1363 1364 1365 1366 1367
   spusa# cat utc-h utc-l; echo 0 > command; cat utc-h utc-l; date +%s
   0
   50005
   0
   1335948116
   1335948116
1368 1369
@end smallexample

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
1370 1371
However, please note that the times will diverge over time. Also, if
you are using White-Rabbit mode, host time is irrelevant to the board.
1372

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
1373 1374 1375 1376
I chose to offer a @i{command} channel, which is opaque to the user,
because there are several commands that you may need to send to the
device, and we need to limit the number of attributes. The command numbers
are enumerated in @code{fine-delay.h} and described here below.
1377

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
1378 1379 1380
@c --------------------------------------------------------------------------
@node List of Commands to the Device
@subsection List of Commands to the Device
1381

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
1382 1383
The following commands are currently supported for the @code{command}
write-only file in @i{sysfs}:
1384

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
1385
@table @code
1386

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
1387
@item 0 = FD_CMD_HOST_TIME
1388

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
1389
	Set board time equal to host time.
1390

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
1391
@item 1 = FD_CMD_WR_ENABLE
1392

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
1393
	Enable White-Rabbit mode.
1394

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
1395
@item 2 = FD_CMD_WR_DISABLE
1396

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
1397
	Disable White-Rabbit mode.
1398

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
1399
@item 3 = FD_CMD_WR_QUERY
1400

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
1401 1402 1403 1404 1405
	Tell the user the status of White-Rabbit mode. This is a hack, as
        the return value is reported using error codes. Success means
        White-Rabbit is synchronized.  @code{ENODEV} means WR mode is not supported or inactive,
        @code{EAGAIN} means it is not synchronized yet.
        The error is returned to the @i{write} system call.
1406

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
1407
@item 4 = FD_CMD_DUMP_MCP 
1408

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
1409 1410
	Force dumping to log messages (using a plain @i{printk} the
        GPIO registers in the MCP23S17 device (fixme: is it really needed).
1411

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
1412
@item 5 = FD_CMD_PURGE_FIFO
1413

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
1414
	Empty the input fifo and reset the sequence number.
1415

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
1416
@end table
1417 1418

@c --------------------------------------------------------------------------
Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
1419 1420
@node Reading Board Time
@subsection Reading Board Time
1421

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
1422 1423
The program @i{fd-raw-gettime}, part of this package, allows reading
the current board time using @i{sysfs} directly:
1424

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
1425 1426 1427 1428 1429
@smallexample
   spusa# ./tools/fd-raw-gettime ; sleep 1; ./tools/fd-raw-gettime
   3303.076543536
   3304.082016080
@end smallexample
1430

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
1431 1432
In the example above the time has never been set, so the epoch if FPGA
load time.
1433

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
1434
@b{Note:} the tool is bugged as of year 2038 because it assumes utc-h is 0.
1435

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
1436 1437 1438
@c --------------------------------------------------------------------------
@node Writing Board Time
@subsection Writing Board Time
1439

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
1440 1441
The program @i{fd-raw-settime}, part of this package, allows setting
the current board time using @i{sysfs} directly:
1442

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
1443 1444 1445 1446 1447 1448
@smallexample
   spusa# ./tools/fd-raw-settime  123; ./tools/fd-raw-gettime
   123.000541696
   spusa# ./tools/fd-raw-settime  123 500000000; ./tools/fd-raw-gettime
   123.500570096
@end smallexample
1449

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
1450
@b{Note:} the tool is bugged as of year 2038 because it assumes utc-h is 0.
1451

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
1452 1453 1454
No tool is there to sync the board to Linux time, because writing
0 to the @i{command} attribute is atomic by itself, but there is an
example program using the official API (see @ref{Time Management}).
1455

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
1456 1457 1458 1459 1460 1461 1462 1463 1464 1465 1466 1467 1468 1469 1470 1471 1472 1473 1474 1475 1476 1477 1478 1479 1480 1481 1482 1483 1484 1485 1486 1487 1488 1489 1490 1491 1492 1493 1494 1495 1496 1497 1498 1499 1500 1501 1502 1503 1504 1505 1506 1507 1508
@c ==========================================================================
@node The Input cset
@section The Input cset

The input cset returns blocks with no data and timestamp information in the
control structure (the meta-information associated to data).  Before
January 2014 the driver was suboptimal, but now those limitations are
gone and the driver uses the ``self-timed'' @sc{zio} abstraction, which
allows it to push blocks to the buffer even if no process is yet reading.

Collecting event in empty blocks, with full meta-data description, brings
some overhead in the data flow, mainly for the marshalling of meta-data.
If you need to stamp pulse rates higher than 10kHz we advise you to
rely on the @i{raw_tdc} support, which on an average computer can
timestamp up to 100-150 kHz without data loss. This is described
in @ref{Raw TDC}.  The internals of the input data flow are
described in @ref{The Input Data Flow}, that may help fine-tune
driver parameters to match your timestamping needs.

For normal @sc{zio} blocks, with meta-data and no data, the hardware
timestamp and other information is returned as @i{channel
attributes}, which you can look at using @i{zio-dump} (part of the @sc{zio}
package) or
@i{tools/fd-raw-input} which is part of this package.

@c --------------------------------------------------------------------------
@node Input Device Attributes
@subsection Input Device Attributes

The attributes are all 32-bit unsigned values, and their meaning
is defined in @i{fine-delay.h} for libraries/applications to use them:

@example
   enum fd_zattr_in_idx {
           FD_ATTR_TDC_UTC_H,
           FD_ATTR_TDC_UTC_L,
           FD_ATTR_TDC_COARSE,
           FD_ATTR_TDC_FRAC,
           FD_ATTR_TDC_SEQ,
           FD_ATTR_TDC_CHAN,
           FD_ATTR_TDC_FLAGS,
           FD_ATTR_TDC_OFFSET,
           FD_ATTR_TDC_USER_OFF,

   }; 
   /* Names have been chosen so that 0 is the default at load time */
   #define FD_TDCF_DISABLE_INPUT	1
   #define FD_TDCF_DISABLE_TSTAMP	2
   #define FD_TDCF_TERM_50		4
@end example

The attributes are also visible in @i{/sys}, in the directory
describing the cset:
1509 1510

@smallexample
Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
1511 1512 1513 1514 1515 1516
   spusa# ls -Ff /sys/bus/zio/devices/zio-fd-0200/fd-input/
   ./      enable           utc-l   chan         power/
   ../     current_trigger  coarse  flags        trigger/
   uevent  current_buffer   frac    offset       chan0/
   name    utc-h            seq     user-offset
@end smallexample
1517

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
1518 1519 1520
The timestamp-related values in this file reflect the last stamp that
has been enqueued to user space (this may be the next event to be
read by the actual reading process).
Alessandro Rubini's avatar
Alessandro Rubini committed
1521

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
1522 1523
The @i{offset} attribute
is the stamping offset, in picoseconds, for the TDC channel.
1524 1525 1526 1527
The hardware timestamper's time-base is shifted backwards, so the
driver adds this offset to the raw timestamps it collects. Users should
not change this value, that depends on how hardware and HDL is designed.

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
1528 1529 1530
The @i{user-offset} attribute, which defaults to 0 every time the
driver is loaded, is a
signed value that users can write to represent a number of picoseconds
1531 1532
to be added (or subtracted, if negative)
to the hardware-reported stamps. This is
Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
1533
used to account for delays induced by cabling (range: -2ms to 2ms).
1534

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
1535 1536 1537 1538 1539
The @i{flags} attribute can be used to change three configuration
bits, defined by the respective macros. Please note that the default
at module load time is zero: some of the flags bits are inverted
over the hardware counterpart, but the @code{DISABLE} in flag names
is there to avoid potential errors.
1540

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
1541 1542 1543
@c --------------------------------------------------------------------------
@node Reading with zio-dump
@subsection Reading with zio-dump
1544

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
1545 1546 1547 1548 1549
This is an example read sequence using @i{zio-dump}: data must be ignored
and only the first few extended attributes are meaningful. This can
be used to see low-level details, but please note
that the programs in @code{tools/} and @code{lib/} in this package are
in general a better choice to timestamp input pulses.
1550

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
1551 1552 1553 1554 1555 1556 1557 1558 1559 1560 1561 1562 1563 1564 1565 1566
@smallexample
   spusa# zio-dump /dev/zio/zio-fd-0200-0-0-*
   Ctrl: version 0.5, trigger user, dev fd, cset 0, chan 0
   Ctrl: seq 1, n 16, size 4, bits 32, flags 01000001 (little-endian)
   Ctrl: stamp 1335737285.312696982 (0)
   Device attributes:
       [...]
       Extended: 0x0000003f
       0x0 0x30 0x640f20d 0x60a 0x0 0x0 0x0 0x0
       [...]
       Extended: 0x0000003f
       0x0 0x40 0x454b747 0x1d3 0x1 0x0 0x0 0x0
       [...]
       Extended: 0x0000003f
       0x0 0x47 0xf04c57 0x772 0x2 0x0 0x0 0x0
@end smallexample
1567

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
1568 1569 1570
@c --------------------------------------------------------------------------
@node Reading with fd-raw-input
@subsection Reading with fd-raw-input
1571

Tomasz Wlostowski's avatar
Tomasz Wlostowski committed
1572