Commit e1edbee0 authored by Maciej Lipinski's avatar Maciej Lipinski

update the documentation appropriately and improve clarity

parent 478d97d4
......@@ -65,12 +65,17 @@ 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 fully configurable by the user that only generates interrupts.
The HW train pulse generator improves the precision of the pulses due to the
software does not need to reprogram a new pulse in each interrupt. In this implementation,
the software only takes care of the number of pulses to disable them when all
the pulses have been generated.
This version of the driver adds support for generating a train pulses in HW and
a new virtual channel that generates interrupts and is fully configurable by the user.
The HW train pulse generator improves the precision of the pulses which are
not any more generated in software as it was the case in the previous versions.
In this implementation, the software only takes care of the number of pulses to
disable them when all the pulses have been generated.
This and previous versions of the driver provide support for immediate pulse
generation, programmed pulse generation synchronized with White Rabbit clock,
and input pulse timestamping. The driver provides an ioctl interface to configure
the hdl core.
@c ##########################################################################
@node Compiling the Drivers
......@@ -124,7 +129,7 @@ the case shown above your driver will end up being installed
/mnt/target/lib/modules/4.15.0/extra/fmc-dio.ko
@end example
Please note that by default the package compiles an installs the
Please note that by default the package compiles and installs the
@i{fmc-bus} modules, too (the project is a @i{git} submodule).
@c ##########################################################################
......@@ -251,12 +256,12 @@ The @i{sw/tools} directory contains all the userspace tools the manage the
@node Overview of the Driver
@section Overview of the Driver
This fmc-dio driver add support for both versions of the fmc-dio hdl core.
This fmc-dio driver provides support for both versions of the fmc-dio hdl core,
i.e. the current version with extended functionality and a previous version.
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.
pulse timestamping.
@c ==========================================================================
@node Accessing the DIO Channels
......@@ -280,7 +285,7 @@ for device-specific use:
field. (For example, we may return EEPROM contents to user space
on request).
@b{Warning}: the command is not implemented because we still have
@b{Warning}: The command is not implemented because we still have
no mezzanine identification in place. The error being returned
is @code{EAGAIN}; user code can rely on that error to know it
is actually talking with a SPEC device, even if no identification
......@@ -386,7 +391,7 @@ The arguments have the following meaning
@b{Note}: This command, like everything else in this package, numbers
channels from 0 through 5, whereas the back panel of the mezzanine
numbers them 0 through 4. The last channel does not represent a physical channel,
numbers them 1 through 5. The last channel does not represent a physical channel,
it is a virtual channel to generate interrupts.
The current version of the tool supports the following commands:
......@@ -421,20 +426,19 @@ The current version of the tool supports the following commands:
visual inspection. The @code{period} parameter, if specified, requests for
a pulse train, with the specified time period between raising edges;
the @code{count} parameter is the number of times to run pulse generation (-1 means forever,
0 means ``stop ongoing generating pulses'').
0 means ``stop ongoing pulse generation'').
@item irq <when> [<period> <count>]
This command only generates interrupts and does not generate any
physical pulse. The duration must be specified in a range between
1ms and 2s, the @code{when} argument can be the string @code{now},
physical pulse. 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.
The @code{period} parameter, if specified, requests for a interrupt train, with the
specified time period between rising edges; the @code{count} parameter is the number
of times to run pulse generation (-1 means forever, 0 means ``stop ongoing generating pulses'').
specified time period between interrupts; the @code{count} parameter is the number
of times to run interrupt generation (-1 means forever, 0 means ``stop ongoing interrupt generation'').
@item mode <channel> <mode> [<channel> <mode> ...]
@itemx mode <m0><m1><m2><m3><m4>
......@@ -444,7 +448,7 @@ The current version of the tool supports the following commands:
configures all 5 channels by means of a 5-bytes-long string,
each characters specifies a mode according to the next table.
The irq channel can not be configured with this command, it is
automatically configured with the @code{irq} command.
should be configured with the @code{irq} command.
This is the list of supported modes for channels:
......@@ -500,8 +504,13 @@ This is the list of supported modes for channels:
@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'
This command disables interrupt coming from the selected channel if the second
argument is 'y' and enables it if the argument is 'Y'. In normal operation
(if not disabled), an interrupt is generated on a channel (0-4) when a pulse
is received or transmitted on this channel. For example, if channel 0 is
configured to generate 1 Pulse Per Second, an interrupt is generated every
time 1 PPS is generated on this channel. This command allows to disable
such generation of interrupts.
......@@ -514,8 +523,10 @@ This is the list of supported modes for channels:
@b{Note}: At startup, the DIO channels are configured by default as:
@code{wr-dio-cmd mode p00ic}.
The new hardware pulse generation feature allows to configure train pulses with a higher
frequency than older version. However, there is still a software limitation due to the
The new hardware pulse generation feature allows to configure a pulse train with a higher
frequency than the previous version. However, if interrupts are not disabled with
the mask_irq command, there is still a software limitation due to the
interrupts handling (see following section for deeper details) and this frequency should
be controlled in a proper way just to avoid PC freezing. It depends on your current machine
configuration and can be easily characterized with the existing tools for fmc-dio project.
......@@ -580,7 +591,7 @@ because it spends all of its time in interrupt handling.
This problem is transient: as soon as you remove the offending cable
the system recovers. However, you need a 10MHz input signal if you
want to run your SPEC device to be a White Rabbit @i{grandmaster}. In
order to support that, the driver disables DIO interrupts when the
order to support that, the driver automatically disables DIO interrupts when the
time spent in interrupt management exceeds 80% of the total time,
averaged over one thousand interrupt events. Ethernet interrupts
are not affected. The fact is reported by a kernel message, using
......@@ -595,10 +606,14 @@ kilohertz and still be able to feed higher frequencies without manual
intervention. However, after DIO interrupts are disabled, the only
way to re-enable them is removing and reloading the device driver.
@b{Note}: if you run two SPEC cards, and one is fed with high frequency
pulses, it may happen that interrupts are disabled on both boards.
The safeguard is currently not very refined, as it was implemented in
a hurry.
On the other hand, you can manually disable interrupts on a channel where
you expect high frequency input signals by using the mask_irq command, see
previous section.
@b{Note}: If you run two SPEC cards, and one is fed with high frequency
pulses without disabling the interrupts manually, it may happen that interrupts
are automatically disabled on both boards. The safeguard is currently not
very refined, as it was implemented in a hurry.
@c ==========================================================================
@node WR-DIO Pulse per Second
......
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