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.
@end menu
@c ##########################################################################
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
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
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
@node The Core Driver
@chapter The Core Driver
The core driver lives in the @i{kernel} subdirectory. Like the board
itself, it is a carrier for sub-modules.
@menu
* Compiling the Driver::
* Driver Operation::
* Future Plans::
@end menu
@c ==========================================================================
@node Compiling the Driver
@section Compiling the Drivers
To compile
it, 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.2,
but I at least compile-test back to 2.6.35.
@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 in
@example
/mnt/target/lib/modules/3.2.0/extra/spec.ko
@end example
@c ==========================================================================
@node Driver Operation
@section Driver Operation
The driver @code{spec.ko} will simply register 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).
The kernel will call the @i{probe} method of the driver, which in
turn perform the following actions:
@itemize @bullet
@item Program a @i{firmware} (or @i{gateware}) file in the FPGA
@item Load program code for the internal CPU (if any)
@item Load a sub-module for driving the FMC card (if any).
@end itemize
If the first step fails, nothing more is tried; the second and third
steps are expected to fail (you may not run a CPU in the FPGA or you
may have its program already included in the @i{gateware} file);
similarly you may not need a sub-driver, because the card is
stand-alone and needs no Linux driver.
The three files being looked for are named like this, assuming here
the card is seen under PCIe bus number 2:
@table @code
@item spec-B0002.bin
This is the name of the @i{gateware} file, which is looked-for
in @code{/lib/firmware} by the @i{hotplug} or @i{udev} program.
@item spec-B0002-cpu.bin
This is the program code for the embedded CPU. Again, it must
live in @code{/lib/firmware}
@item spec-B0002.ko
The kernel sub-module. It is loaded using @i{modprobe}, so
it should live in the same place where @code{spec.ko} is found.
Also, please run ``@code{depmod -a}'' after copying or renaming
the file
@end table
The central part of actual names of the three files is
customizable. You can use the @code{name=} module parameter to change
it. The default value, ``@code{%b}'' expands to the bus number, as
shown. This allows to differentiate between cards, and have different
bitstreams and sub-drivers for each of them, according to the
geographical placement in the host computer.
The names being passed are using literally, with the exceptrion
of the following three formats:
@table @code
@item %b
The bus number, expanded as @code{B%04x"}.
@item %s
The @i{slot} and @i{function} composite number, expanded as
@code{S%04x}. Note that usually every PCIe mechanical slot is
seen as a separate bus number, so using @code{%s} is not generally
useful.
@item %%
A literal @code{%}.
@end table
For example, I have two cards, fit in bus number 2 and 3. I prepared
the files for the card in slot 3 but not for the one in slot 2; I
receive the following messages when loading with the default name
(@code{%b}). Here the @code{0} and @code{-2} items are error codes (0
means success):
@smallexample
spec_probe (device 0002:0000)
spec 0000:02:00.0: Can't load firwmare "spec-B0002.bin" - -2
spec_probe (device 0003:0000)
spec_load_fpga: got binary file "spec-B0003.bin", 1484404 (0x16a674) bytes
spec_load_lm32: got program file "spec-B0003-cpu.bin", 49044 (0xbf94) bytes
LM32 has been restarted
spec_load_submodule: load "spec-B0003": 0
@end smallexample
The following messages are printed if I pass @code{name=pippo} (Italian for
@i{foo}):
@smallexample
spec_probe (device 0002:0000)
spec 0000:02:00.0: Can't load firwmare "spec-pippo.bin" - -2
spec_probe (device 0003:0000)
spec 0000:03:00.0: Can't load firwmare "spec-pippo.bin" - -2
@end smallexample
Please note that when a sub-module is loaded, it registers in the kernel
with its real name, not the one you renamed it to. For example,
the output of @i{lsmod} in the former case shown above is as follows,
even if the module has been loaded as @code{spec-B0003.ko}:
@example
Module Size Used by
spec 3835 0
spec_fine_delay 421 0
@end example
@c ==========================================================================
@node Future Plans
@section Future Plans
The SPEC driver should scan its own wishbone bus according to the
self-description specification, that is being finalized these times,
instead of using static file names.
@c ##########################################################################
@bye
@c LocalWords: gnudd titlepage iftex texinfo CERN documentlanguage settitle
@c LocalWords: documentencoding setfilename afourpaper paragraphindent
@c LocalWords: setchapternewpage finalout