doc: document current status of wr-nic

Signed-off-by: Alessandro Rubini <rubini@gnudd.com>

doc/spec-sw.in

@@ -39,7 +39,7 @@
 
 @titlepage
 @title SPEC Software Support
-@subtitle Version 2.0-rc1 (@value{update-month})
+@subtitle (@value{update-month})
 @subtitle A driver for the SPEC card and its FMC modules
 @author Alessandro Rubini for CERN (BE-CO-HT)
 @end titlepage
@@ -627,9 +627,7 @@ The port supports hardware timestamping for user frames through the
 standard Linux mechanisms, but at this point no sample code is provided
 in this package.
 
-@b{Warning:} While frame transmission is perfectly working, there is
-still a problem in the RX data path and no data can be received with
-this version of the software and gateware.
+@b{Warning}: time stamping is not working, but we are on the problem.
 
 @c ==========================================================================
 @node Accessing the DIO Channels
@@ -691,15 +689,26 @@ non-selected channels are ignored by the driver.  To stop output
 generation, the application must request a starting time of 0.0
 seconds for the channels it wants to stop.
 
-@b{Warning}: there is a problem with pulse output at a specified time,
-only immediate pulse is working. The bug is in the FPGA binary and is
-being worked on.
-
 @b{Warning}: currently the @i{pulse train} mode is not supported
 by software.
       
-Specifics about the use of individual fields is shown in the driver itself
-and in the user-space programs that call the command.
+Specifics about the use of individual fields is shown in the header
+(in a big comment block), in the driver itself and in the user-space
+programs that call @i{ioctl}.
+
+In lab environments you may be concerned about the duration of the
+@i{ioctl} implementation, because it sometimes seems to do more work
+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,
+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
+@end example
 
 @c ==========================================================================
 @node WR-NIC User Tool
@@ -709,16 +718,22 @@ In the @file{tools/} subdirectory of this project, you find the
 @file{wr-dio-cmd} program, which is a command-line interface to the
 @i{ioctl} command to simplify initial access to the DIO device.
 
-Please note that neither timestamping nor pulse generation works
-if the WR core is running and has valid times: it must either be
-a master or a slave in synchronized state.
+Please note that neither timestamping nor pulse generation work
+if the WR core is not running or has an invalid time: it must either be
+a master or a synchronized slave.
+
+Moreover, please note that this tool is just a demonstration to quickly
+test the I/O features of the device (and for me to verify the kernel
+part is actually working): for serious use you should call
+@i{ioctl} by yourself with proper arguments, and avoid all the parsing
+of ASCII and repeated invocation of this program.
 
 This is the general syntax of the command:
 
 @example
    wr-dio-cmd <ifname> <cmd> [<args> ...]
 @end example
-@c FIXME:   wr-dio-cmd <ifname> <cmd> [<args> ...] [<cmd> [<args> ...]]
+@c FIXME:   wr-dio-cmd <ifname> <cmd> [<args> ...]
 
 The arguments have the following meaning
 
@@ -731,36 +746,40 @@ The arguments have the following meaning
 
 @item cmd
 
-	The specific command. Currently the tool supports @code{stamp}
-        and @code{pulse}.
+	The specific command. Supported commands are listed below.
+        Each command takes zero or more of arguments. If you pass
+        a wrong number of arguments no help is provided in the error
+        message. If one argument is wrong (e.g., not a number) the
+	error message is meant to be directly helpful.
 
 @end table
 
-@c FIXME: argument to stamp
-The @code{stamp} command currently takes no arguments. It reports
-to stdout all the available timestamps, scanning the FIFO for all
-channels in order.  Later I'll add a <i>channel</i> argument to restrict
-the report to only one channel (the driver already supports this).
+The current version of the tool supports the following commands:
+
+@table @code
 
-The @code{pulse} command receives three arguments:
+@item stamp [<channel>]
+@itemx stampm [<channel-mask>]
 
-@example
-   wr-dio-cmd wr0 pulse <channel> <fraction> <start>
-@end example
+	The commands are used to retrieve timestamps from the card.
+        If no arguments are passed, the tool reports to @i{stdout} all
+        timestamps for all channels (they are ordered by channel, not
+        by time). If one integer argument is passed, it can be a channel
+        number in the range 0 to 4 (@code{stamp} command) or a mask
+        in the range 0 to 0x1f (@code{stampm} command).
 
-The @code{channel} argument is a number, in the range 0-4. The
-@code{fraction} argument is a decimal number, for example @code{.1}
-representing the length in second of the pulse; the length is
-truncated to a multiple of 8ns.  The @code{start} argument is
-either the string @code{now}, or an absolute number of seconds, or
-a relative number of seconds. A relative time is expressed as
-@code{+@i{nr}} (for example, @code{+3}) and requests the pulse
-at the start of a second, @i{nr} seconds in the future.
+@item pulse <channel> <duration> <when>
 
-@c FIXME: support fractional starting times
+	Channel is an integer in the range 0 to 4. The duration must
+        be specified as a fraction of a second (decimal number, with
+        leading dot), 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 not modified. The @code{+} form is useful for simple checks with
+        visual inspection.
 
-@b{Warning}: due to problems in the current gateware, only immediate
-pulses are actually generated by hardware.
+@end table
 
 @c ==========================================================================
 @node The Future of WR-NIC 
@@ -863,16 +882,18 @@ The tools currently available are:
 @itemize @bullet
 
 @item Identification of the mezzanine is completely missing; every @i{fmc}
-driver at this point takes hold of every device.
+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.
-
-@item The NIC data transfer only works in the transmit direction. This looks
-like a bug in the gateware and we are investigating on both sides.
+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).
+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
 in @file{wr-dio.h}.
@@ -881,13 +902,11 @@ in @file{wr-dio.h}.
 and timestamps to be collected without polling the FIFO.
 
 @item The @i{wr-nic} functionality should be completely detached from
-the specific mezzanine.
+the specific mezzanine. This is a longer-term desire.
 
 @item The package should be verified with a wide range of kernel versions.
 Currently I compiled and tested only under Linux-3.4.
 
-@item A number of temporary @i{printk} should be removed.
-
 @end itemize
 
 @c ##########################################################################
@@ -897,4 +916,4 @@ Currently I compiled and tested only under Linux-3.4.
 @c  LocalWords:  gnudd titlepage iftex texinfo CERN documentlanguage settitle
 @c  LocalWords:  documentencoding setfilename afourpaper paragraphindent EEPROM
 @c  LocalWords:  setchapternewpage finalout eeprom gateware devmem devfn busid
-@c  LocalWords:  speclib Gennum
+@c  LocalWords:  speclib Gennum timestamps stampm ifname timespec timestamp