Newer
Older
\input texinfo @c -*-texinfo-*-
%
% spec-sw.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 spec-sw.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
@setfilename spec-sw.info
@settitle spec-sw
@iftex
@afourpaper
@end iftex
@paragraphindent none
@comment %**end of header
@setchapternewpage off
@subtitle @value{update-month}
@subtitle A driver for the SPEC card and its FMC modules
@author Alessandro Rubini for CERN
@end titlepage
@headings single
@c ##########################################################################
@iftex
@contents
@end iftex
@c ##########################################################################
@node Top
@top Introduction
This is the manual for the SPEC device driver. SPEC is the @i{Simple
PCI-Express Carrier} for FMC cards, developed at
@url{http://www.ohwr.org/projects/spec}. This manual is part of the
associated software project, hosted at
@url{http://www.ohwr.org/projects/spec-sw}, whose @i{git} repository
hosts the latest version.
@c ##########################################################################
@node History and Overview
@chapter History and Overview
This driver is pretty different from the initial implementation, such as
the one used by @i{fine-delay-sw-v1.1}. If you use such version, please
compile the manual you find in your source code repository.
The package currently includes both the @i{spec} driver and the
@i{fmc-core} driver (which benefits from its own documentation file
which you may want to read.
@c ##########################################################################
@node Compiling the Drivers
@chapter Compiling the Drivers
The kernel modules part of this package live in the @i{kernel}
subdirectory. To compile them, you need to
set the following variables in your environment:
@table @code
@item LINUX
The top directory of the kernel sources for the version you
are going to run the driver under. I'm testing mostly with 3.4,
but this version compiles against Linux-2.6.30 and later ones.
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
@item CROSS_COMPILE
If you are cross-compiling, you need to set this variable.
It is not usually needed for the PC, but if you are using
the @i{Powec} board, you'll most likely need this. It is not
needed if you compile for a different-sized PC (see below).
@item ARCH
If you are cross-compiling, set this variable. Use @code{powerpc}
for the @i{Powec}, @code{x86-64} if you compile on a 32-bit PC
to run on a 64-bit PC and @code{i386} if you compile on a 64-bit
PC to run on a 32-bit PC.
@end table
To compile run ``@code{make}'' with the previous variables set. To
install run ``@code{make install} to install under
@code{/lib/modules/3.2.0} (or other version-based directory). You can
set @code{INSTALL_MOD_PATH} to set a prefix before @code{/lib/modules}.
For example, if your target computer's filesystem is mounted under
@code{/mnt/target} you can run
@example
make install INSTALL_MOD_PATH=/mnt/target
@end example
The modules are installed under the subdirectory @code{extra}. In
the previous case your driver will end up being installed
(together with the other modules) as
@example
/mnt/target/lib/modules/3.2.0/extra/spec.ko
@end example
@c ##########################################################################
@node Role of spec.ko
@chapter Role of spec.ko
The @code{spec.ko} driver depends on @code{fmc-core.ko}, that must
be loaded first (if you don't rely on automatic dependencies).
The driver @code{spec.ko} registers itself as a PCI driver,
using both the ``old'' vendor and device ID (the Gennum identifiers)
and the new ones (CERN vendor and SPEC device).
For each new SPEC device found on the system, the driver performs the
following steps:
@item It enables MSI interrupts, the only kind supported in this package.
@item It loads the @code{spec-init.bin} ``golden'' gateware file.
@item It checks that the content of the binary is as expected (using
a minimal @i{sdb}-based verification).
@item It reads the whole I2C EEPROM found on the mezzanine.
@item It allocates an @i{fmc_device} structure and registers as
a nee device in the @i{fmc} bus.
Failure of any of those steps is fatal.
The module can receive the following parameters to customize its operation:
@table @code
@item test_irq
IF not zero, this parameter requests to self-test interrupt
generation, using the Gennum registers. This usually does not
work on my host, for yet unknown reasons (and that's why it is
disabled by default).
@item i2c_dump
If not zero, this parameter requests to @i{printk} the content
of the FMC eeprom, for diagnostic purposes.
@item fw_name
This string parameter can be used to override the default name
for the initialization binary file.
@end table
Any mezzanine-specific action must be performed by the driver for the
specific FMC card, including reprograming the FPGA with the final
gateware file. Similarly, the @i{spec} driver is not concerned with
programming the LM32 image, when it makes sense to. This is different
from the role splitting in previous versions of the driver.
@b{Note:} the gateware binary is looked-for in @i{/lib/firmware/fmc},
which is where all fmc-related external files are expected to live.
That's because our own installations share firmware for COTS peripherals
but mount a host-specific NFS subdirectory.
Please refer to the @i{fmc-bus} document for details about the overall
design of the interactions of carriers and mezzanines.
@b{Warning:} currently the @i{match} function of the bus always
returns success: the mezzanines I currently have for testing have no
ID records written in their internal EEPROM, so I'm not able to setup
the associated data structures and code. For this reason there is no
@i{module_alias} support nor autoprobe of drivers: any @i{fmc} driver
you load will drive all SPEC cards found on the system.
@c ##########################################################################
@node fmc-trivial.ko
@chapter fmc-trivial.ko
The simple module @i{fmc-trivial} is just a simple client that
registers an interrupt handler. I use it to verify the basic mechanism
of the FMC bus and how interrupts work. It's worth reading, but it's not
worth describing here.
@c ##########################################################################
@node fmc-write-eeprom.ko
@chapter fmc-write-eeprom.ko
This module, not yet written, will be able to load a binary file from
@i{/lib/firmware/fmc} and write it to the internal EEPROM of the mezzanine.
Partial writing is allowed by filling a simple TLV array of binary areas.
@c ##########################################################################
@node The WR-NIC
@chapter The WR-NIC
The @i{wr-nic} driver is being worked on. It should be a model of how
FMC drivers should behave, so it is hosted in this package.
The driver will register an Network Interface Card on the host computer,
to allow exchanging data on the same fiber channel where White-Rabbit
synchronization is taking place. The driver relies on the 5-channel
digital I/O mezzanine to time-stamp incoming pulses and generate
precisely timed output signals.
@c ##########################################################################
@node User-Space Tools
@chapter User-Space Tools
The @i{tools} subdirectory of this package includes a few host-side
programs that may be useful while working with the SPEC device.
They are all base on the same @i{speclib}, part of the same directory,
so all of them accept some parameters in common, in order to identify
one specific SPEC card if you have more than one:
@table @code
@item -b <bus>
This option specifies the bus number
@item -d <devfn>
This is used to specify the device and function number, but it
is expected to be 0 on most if not all the computers. You won't
generally need to specify the @i{devfn} value.
@end table
If no arguments are supplied, the tools act on the @i{first} device
if more than one is plugged. The meaning of @i{first} is actually undefined
and system-dependent.
The tools currently available are:
@table @i
@item specmem
The program acts like @i{devmem} or @i{devmem2} but in a
simplified way. It receives one or two command line arguments:
one for reading and two for writing. Both arguments are used
as hex numbers, whether or not the leading @code{0x} is
specified. The program makes a single 32-bit
access to BAR0 of the Gennum PCI bridge; the first argument is
the address, and the second argument is the value to be written.
The @code{VERBOSE} environment variable makes the tool slightly
more verbose. If you pass @code{-g} you will access the Gennum
registers (for example, for GPIO access).
@item spec-cl
This is the @i{cpu loader}. It is not called @i{lm32-loader} to
avoid confusion with other tools we have been using. It
loads a program at offset 0x80000 in BAR0. This is where we
usually have RAM memory for the soft-core running in the SPEC.
If the program lives at aa different address, you can pass
@code{-c <number>} to specify a different address (note
that the leading @code{0x} is required to pass an hex address).
@item spec-fwloader
This is a user-space loader for the gateware file. It simply
receives a file name argument (after the optinal bus number for
the device).
@item spec-vuart
A simple tool to talk with the virtual-uart device inside the
SPEC. The default base address for the peripheral is 0xe0500
but you can can change it passing @code{-u <address>}.
@end table
@c ##########################################################################
@bye
@c LocalWords: gnudd titlepage iftex texinfo CERN documentlanguage settitle
@c LocalWords: documentencoding setfilename afourpaper paragraphindent
@c LocalWords: setchapternewpage finalout