Skip to content

F
FMC DIO 5ch TTL a
Commit 8e6ffe09 authored by Jorge Machado's avatar Jorge Machado
Browse files
Options

Update fmc-dio doc

parent 3f3164f6
Hide whitespace changes
Inline Side-by-side
Showing with 90 additions and 84 deletions
doc/fmc-dio.in
View file @ 8e6ffe09
......@@ -43,7 +43,8 @@
@title FMC DIO Software Support
@subtitle @value{update-month} (@value{release})
@subtitle A driver for the FMC DIO module
@author Alessandro Rubini for CERN (BE-CO-HT), Jorge Machado Cano (Seven Solutions)
@author Alessandro Rubini for CERN (BE-CO-HT)
@author Jorge Machado Cano for Seven Solutions
@end titlepage
@headings single
......@@ -64,12 +65,15 @@ This is the manual for the fmc-dio device driver.
@node History and Overview
@chapter History and Overview
This version of the driver includes support for train pulses generated by HW and
a new virtual channel that only generates interrupts.
The HW train pulse generator improves the precision of the pulses.
@c ##########################################################################
@node Compiling the Drivers
@chapter Compiling the Drivers
The kernel modules that are part of this package live in the @i{kernel}
The kernel modules that are part of this package live in the @i{sw/kernel}
subdirectory. To compile them, you need to
set the following variables in your environment:
......@@ -132,8 +136,8 @@ totally configurable pulses. It also recovers timestamps of external and generat
pulses.
@c ==========================================================================
@node fmc-dio Initialization
@section fmc-dio Initialization
@node Initialization of fmc-dio
@section Initialization of fmc-dio
There is no need to explicitly initialize the FMC-DIO driver.
......@@ -141,7 +145,7 @@ There is no need to explicitly initialize the FMC-DIO driver.
@node Interrupts in fmc-dio.ko
@section Interrupts in fmc-dio.ko
There is only an interrupt to control the number of pulses that has been generated.
There is only one interrupt to control the number of pulses that has been generated.
@c ==========================================================================
@node Code Layout
......@@ -156,16 +160,16 @@ spread over several directories:
@table @file
@item fmc-bus/
@item sw/fmc-bus/
FMC-BUS kernel driver support (see specific doc inside)
@item kernel/
@item sw/kernel/
This directory contains the low level functions to configure each
physical channel and the interrupt management.
@item tools/
@item sw/tools/
This directory hosts the userspace tools that uses the low level
functions.
......@@ -177,63 +181,63 @@ register definitions. This is the role of each of them:
@table @file
@item kernel/fmc-dio.c
@item kernel/fmc-dio.h
@item sw/kernel/fmc-dio.c
@item sw/kernel/fmc-dio.h
Code and headers of the driver initialization. It also detects
the version of the FPGA binary to able coherent memory accesses
through all the code.
@item kernel/fmc-dio-gpio.c
@item sw/kernel/fmc-dio-gpio.c
DIO GPIO support skeleton to be developed.
@item kernel/fmc-dio-internal.c
@item sw/kernel/fmc-dio-internal.c
Code that excecutes the requested operations through the IOCTL.
It also implements the interrupt management.
@item kernel/fmc-dio-mdev.c
@item sw/kernel/fmc-dio-mdev.c
This code created the device and connects the IOCTL.
@item kernel/hw/ppsg-regs.h
@item kernel/hw/wr-dio-regs.c
@item kernel/hw/wr-dio-regs.h
@item kernel/hw/wr-dio-regs_v1.c
@item kernel/hw/wr-dio-regs_v1.h
@item kernel/hw/wr-dio-regs_v2.c
@item kernel/hw/wr-dio-regs_v2.h
@item sw/kernel/hw/ppsg-regs.h
@item sw/kernel/hw/wr-dio-regs.c
@item sw/kernel/hw/wr-dio-regs.h
@item sw/kernel/hw/wr-dio-regs_v1.c
@item sw/kernel/hw/wr-dio-regs_v1.h
@item sw/kernel/hw/wr-dio-regs_v2.c
@item sw/kernel/hw/wr-dio-regs_v2.h
Code and headers with the register map of the fmc-dio. It also
implements some functions to get the offset of each register.
@end table
The @i{tools} directory contains all the userspace tools the manage the
The @i{sw/tools} directory contains all the userspace tools the manage the
@i{fmc-dio} driver. This is the role of each of them:
@table @file
@item tools/net_tstamp.h
@item tools/stamp-frame.c
@item sw/tools/net_tstamp.h
@item sw/tools/stamp-frame.c
Code and headers of timestampig related functions.
@item tools/wr-dio-agent.c
@item sw/tools/wr-dio-agent.c
Code to receive almosteverything that appears on the cable.
@item tools/wr-dio-cmd.c
@item sw/tools/wr-dio-cmd.c
Code that implements the userpace commands to manage the fmc-dio
channels.
@item tools/wr-dio-pps.c
@item sw/tools/wr-dio-pps.c
Example of a PPS generation.
@item tools/wr-dio-ruler.c
@item sw/tools/wr-dio-ruler.c
Code to transmit raw Ethernet frames to the broadcast address.
......@@ -243,7 +247,12 @@ The @i{tools} directory contains all the userspace tools the manage the
@node Overview of the Driver
@section Overview of the Driver
TO BE WRITTEN
This fmc-dio driver add support for both versions of the fmc-dio hdl core.
The fmc-dio hdl core provides immediate pulse generation, immediate pulse
train generator, programmed pulse/pulse train generation synchronized with
White Rabbit clock, programmed/immediate interrupt generation and input
pulse timestamping. The driver provides an ioctl interface to configure the
hdl core.
@c ==========================================================================
@node Accessing the DIO Channels
......@@ -311,13 +320,13 @@ In lab environments you may be concerned about the duration of the
than needed. To verify whether we have an over-engineering problem in
kernel space, I provided a simple measurement of how much time is
spent in the @i{Ioctl} itself. The @i{make} variable
@code{WR_NIC_CFLAGS} can be used to pass extra flags to the compiler,
@code{WR_DIO_FLAGS} can be used to pass extra flags to the compiler,
and the macro @code{DIO_STAT} enables the time measurement.
Compiling with the following command thus enable such measurement
and associated @i{printk} -- the time is usually 5 microseconds for me:
@example
make WR_NIC_FLAGS=-DDIO_STAT
make WR_DIO_FLAGS=-DDIO_STAT
@end example
Previous versions of this manual described how to command pulses on
......@@ -330,7 +339,7 @@ fast, so calling it several times is acceptable).
@node FMC-DIO Command Tool
@section FMC-DIO Command Tool
In the @file{tools/} subdirectory of this project, you find the
In the @file{sw/tools/} subdirectory of this project, you find the
@file{wr-dio-cmd} program, which is a command-line interface to the
@i{ioctl} command that acts on the @i{simple-DIO} mezzanine card. Other
@code{wr-dio-} tools are provided (and described below) but this is
......@@ -349,17 +358,17 @@ of ASCII and repeated invocation of this program.
This is the general syntax of the command:
@example
wr-dio-cmd <ifname> <cmd> [<arg> ...]
wr-dio-cmd <devname> <cmd> [<arg> ...]
@end example
The arguments have the following meaning
@table @code
@item ifname
@item devname
The name of the network interface, most likely @code{wr0}
The name of the device, most likely @code{/dev/fmc-dio-1:0}
(if you have more than one SPEC card, the other interfaces are
called @code{wr1}, @code{wr2} and so on).
called @code{/dev/fmc-dio-1:1}, @code{/dev/fmc-dio-1:2} and so on).
@item cmd
......@@ -408,21 +417,20 @@ The current version of the tool supports the following commands:
visual inspection. @code{period}, if specified, requests for
a pulse train, with the specified time period between raising edges;
@code{count} is the number of instances to run (-1 means forever,
0 means ``stop generating pulses'').
0 means ``stop ongoing generating pulses'').
@item irq <when> [<period> <count>]
This command only generates interrupts and does not generate any
physical pulse. The duration must be specified as a fraction of a
second (decimal number, less than one second), the @code{when}
argument can be the string @code{now}, an absolute time
(@code{<seconds>.<fraction>}) or a relative time
physical pulse. The duration must be specified in a range between
1ms and 2s, the @code{when} argument can be the string @code{now},
an absolute time (@code{<seconds>.<fraction>}) or a relative time
(@code{+<seconds>.<fraction}). In the last case, the current second
is added to @code{<seconds>} while the fraction is used unchanged.
The @code{+} form is useful for simple checks with visual inspection.
@code{period}, if specified, requests for a pulse train, with the
@code{period}, if specified, requests for a interrupt train, with the
specified time period between rising edges; @code{count} is the number
of instances to run (-1 means forever, 0 means ``stop generating pulses'').
of instances to run (-1 means forever, 0 means ``stop ongoing generating pulses'').
@item mode <channel> <mode> [<channel> <mode> ...]
@itemx mode <m0><m1><m2><m3><m4>
......@@ -434,6 +442,20 @@ The current version of the tool supports the following commands:
The irq channel can not be configured with this command, it is
automatically configured with the @code{irq} command.
@item update_width <channel> <new_width>
This command updates the width of the last pulse train programmed.
The duration must be specified as a fraction of a second (decimal number,
less than one second). The command reads the previous period and checks if
the new width is compatible.
@item mask_irq <channel> <Y/y>
This command disables the interrupt of the selected channel if the second
argument is 'y' and enables it if the argument is 'Y'
@end table
This is the list of supported modes for channels:
......@@ -520,8 +542,23 @@ Example uses of the tool follow:
# Generate interrupt now
wr-dio-cmd /dev/fmc-dio-1:0 irq now
# Generate 100 interrupts every 10 ms at the next second
# Generate a train of 100 interrupts every 10 ms starting at the next second
wr-dio-cmd /dev/fmc-dio-1:0 irq +1 .01 100
# Make a train of indefinite pulses, 1ms wide every 5ms
wr-dio-cmd /dev/fmc-dio-1:0 pulse 1 0.001 now 0.005 -1
# Stop the previous pulse train
wr-dio-cmd /dev/fmc-dio-1:0 pulse 1 0.001 now 0.005 0
# Update pulse width in channel 1 to 10ms
wr-dio-cmd /dev/fmc-dio-1:0 update_width 1 0.01
# Disable interrupts in channel 0
wr-dio-cmd /dev/fmc-dio-1:0 mask_irq 0 y
# Enable interrupts in channel 2
wr-dio-cmd /dev/fmc-dio-1:0 mask_irq 2 Y
@end example
......@@ -569,7 +606,7 @@ file.
The program is meant as a source code example, more than a real PPS
signal. If you need a real WR-driven pulse-per-second, you should
use the channel0 wich is "hard-wired" to the PTP core and can be configured by
use the channel0 which is "hard-wired" to the PTP core and can be configured by
executing: ``@t{wr-dio-cmd mode 0 p}''.
The program just fires a 1ms-long @i{pps} pulse on one of the output
......@@ -665,7 +702,7 @@ command line argument is the name of the @i{White Rabbit} interface to
use (for most users it is @code{wr0}):
@example
wr-dio-agent wr0
wr-dio-agent [-V] <wr-if> <dio-dev>
@end example
The @i{ruler} command, on the other hand, waits for timestamps
......@@ -689,7 +726,7 @@ reprograms all output triggers at each input event.
@b{Note}: As usual, channels are numbered 0 through 4.
@example
wr-dio-ruler wr1 IN0 L3+0.001 R3+0.001 L4+0.002
wr-dio-ruler wr1 /dev/fmc-dio-1:0 IN0 L3+0.001 R3+0.001 L4+0.002
@end example
There is no sample code that generates trains of pulses as a response
......@@ -716,26 +753,26 @@ on @code{spusa} are replicated to one local channel and two remote channels,
with a delay of 1ms. The input events in this case are from a @i{pulse-per-second} signal:
@smallexample
tornado.root# /tmp/wr-dio-agent wr0 &
tornado.root# /tmp/wr-dio-agent wr0 /dev/fmc-dio-1:0 &
spusa.root# wr-dio-ruler wr1 IN4 L3+.001 R4+.001 R2+.001
spusa.root# wr-dio-ruler wr1 /dev/fmc-dio-1:0 IN4 L3+.001 R4+.001 R2+.001
wr-dio-ruler: configured for local channel 3, delay 0.001000000
wr-dio-ruler: configured for remote channel 4, delay 0.001000000
wr-dio-ruler: configured for remote channel 2, delay 0.001000000
[... wait a few seconds ...]
spusa.root# wr-dio-cmd wr1 stamp 3
spusa.root# wr-dio-cmd /dev/fmc-dio-1:0 stamp 3
ch 3, 385.001000000
ch 3, 386.001000000
ch 3, 387.001000000
ch 3, 388.001000000
tornado.root# wr-dio-cmd wr0 stamp 2
tornado.root# wr-dio-cmd /dev/fmc-dio-1:0 stamp 2
ch 2, 385.001000000
ch 2, 386.001000000
ch 2, 387.001000000
ch 2, 388.001000000
tornado.root# wr-dio-cmd wr0 stamp 4
tornado.root# wr-dio-cmd /dev/fmc-dio-1:0 stamp 4
ch 4, 385.001000000
ch 4, 386.001000000
ch 4, 387.001000000
......@@ -748,26 +785,14 @@ with a delay of 1ms. The input events in this case are from a @i{pulse-per-secon
@itemize @bullet
@item Identification of the mezzanine is completely missing; every @i{fmc}
driver at this point takes hold of every device. We are working on this,
and the next version of spec-sw will support identification, with a flag
to run without identification for users whose EEPROM has not been programmed.
@item Both spec and wr-nic should have GPIO support with @i{gpiolib};
there is skeletal support but no real code for actual I/O. This is not
a priority, just a wish list for better Linux integration.
@item The NIC driver should directly support setting the White Rabbit
mode for each card (grandmaster, free-running master or slave). This
will be supported at module load time, not at runtime (for that please
use the UART).
@item DIO support in @i{wr-nic} is missing some of the features listed
@item DIO support is missing some of the features listed
in @file{wr-dio.h} (i.e. DAC control)>
@item The @i{wr-nic} functionality should be completely detached from
the specific mezzanine. This is a longer-term desire.
@item Locking in kernel code should be verified with a serious audit
effort. There are no known issues at this point, but some code may
be made safer.
......@@ -780,26 +805,7 @@ be made safer.
This package should be portable. However I didn't test it on a wide
variety of systems. Currently most of my use is
on a 32-bit x86 host, running version 3.4 of the kernel.
The complete package builds without any warning from version 2.6.37
up to 3.13 (I didn't try later versions, yet). Frame timestamping
changed seriously after 2.6.36, so the @code{wr-nic.ko} driver is not
easily backward portable.
To allow use of the core @i{spec} driver, to drive custom mezzanines,
the @i{Makefile} supports the configuration variable
@code{CONFIG_WR_NIC}, which you may set to @code{n} before compiling:
@smallexample
export CONFIG_WR_NIC=n
@end smallexample
With this in place, the package compiles without any warning on a
32-bit PC from version 2.6.30 onwards.
By using the backport branch of the 2013-05 release you can build
for all kernels back to 2.6.27 and also 2.6.24 (the one we were still
using in production). Later releases have no associated backport branch.
on a 64-bit x86 host, running version between 4.15-4.18 of the kernel.
@c ##########################################################################
@bye
......
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