tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
FMC: add documentation for the core
This is selected sections of the current manual for fmc-bus, as
developed outside of the kernel before submission.
Like the other patches in this set, it corresponds to commit ab23167f of
the repository at ohwr.org
Signed-off-by: Alessandro Rubini <rubini@gnudd.com>
Acked-by: Juan David Gonzalez Cobas <dcobas@cern.ch>
Acked-by: Emilio G. Cota <cota@braap.org>
Acked-by: Samuel Iglesias Gonsalvez <siglesias@igalia.com>
Acked-by: Rob Landley <rob@landley.net>
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
authored by
Alessandro Rubini
and committed by
Greg Kroah-Hartman
022c6747
77864f2e
+821
+2
Documentation/00-INDEX
+2
Documentation/00-INDEX
+26
Documentation/fmc/00-INDEX
+26
Documentation/fmc/00-INDEX
···
1
+
2
+
Documentation in this directory comes from sections of the manual we
3
+
wrote for the externally-developed fmc-bus package. The complete
4
+
manual as of today (2013-02) is available in PDF format at
5
+
http://www.ohwr.org/projects/fmc-bus/files
6
+
7
+
00-INDEX
8
+
- this file.
9
+
10
+
FMC-and-SDB.txt
11
+
- What are FMC and SDB, basic concepts for this framework
12
+
13
+
API.txt
14
+
- The functions that are exported by the bus driver
15
+
16
+
parameters.txt
17
+
- The module parameters
18
+
19
+
carrier.txt
20
+
- writing a carrier (a device)
21
+
22
+
mezzanine.txt
23
+
- writing code for your mezzanine (a driver)
24
+
25
+
identifiers.txt
26
+
- how identification and matching works
+47
Documentation/fmc/API.txt
+47
Documentation/fmc/API.txt
···
1
+
Functions Exported by fmc.ko
2
+
****************************
3
+
4
+
The FMC core exports the usual 4 functions that are needed for a bus to
5
+
work, and a few more:
6
+
7
+
int fmc_driver_register(struct fmc_driver *drv);
8
+
void fmc_driver_unregister(struct fmc_driver *drv);
9
+
int fmc_device_register(struct fmc_device *fmc);
10
+
void fmc_device_unregister(struct fmc_device *fmc);
11
+
12
+
int fmc_device_register_n(struct fmc_device **fmc, int n);
13
+
void fmc_device_unregister_n(struct fmc_device **fmc, int n);
14
+
15
+
uint32_t fmc_readl(struct fmc_device *fmc, int offset);
16
+
void fmc_writel(struct fmc_device *fmc, uint32_t val, int off);
17
+
void *fmc_get_drvdata(struct fmc_device *fmc);
18
+
void fmc_set_drvdata(struct fmc_device *fmc, void *data);
19
+
20
+
int fmc_reprogram(struct fmc_device *f, struct fmc_driver *d, char *gw,
21
+
int sdb_entry);
22
+
23
+
The data structure that describe a device is detailed in *note FMC
24
+
Device::, the one that describes a driver is detailed in *note FMC
25
+
Driver::. Please note that structures of type fmc_device must be
26
+
allocated by the caller, but must not be released after unregistering.
27
+
The fmc-bus itself takes care of releasing the structure when their use
28
+
count reaches zero - actually, the device model does that in lieu of us.
29
+
30
+
The functions to register and unregister n devices are meant to be used
31
+
by carriers that host more than one mezzanine. The devices must all be
32
+
registered at the same time because if the FPGA is reprogrammed, all
33
+
devices in the array are affected. Usually, the driver matching the
34
+
first device will reprogram the FPGA, so other devices must know they
35
+
are already driven by a reprogrammed FPGA.
36
+
37
+
If a carrier hosts slots that are driven by different FPGA devices, it
38
+
should register as a group only mezzanines that are driven by the same
39
+
FPGA, for the reason outlined above.
40
+
41
+
Finally, the fmc_reprogram function calls the reprogram method (see
42
+
*note The API Offered by Carriers:: and also scans the memory area for
43
+
an SDB tree. You can pass -1 as sdb_entry to disable such scan.
44
+
Otherwise, the function fails if no tree is found at the specified
45
+
entry point. The function is meant to factorize common code, and by
46
+
the time you read this it is already used by the spec-sw and fine-delay
47
+
modules.
+88
Documentation/fmc/FMC-and-SDB.txt
+88
Documentation/fmc/FMC-and-SDB.txt
···
1
+
2
+
FMC (FPGA Mezzanine Card) is the standard we use for our I/O devices,
3
+
in the context of White Rabbit and related hardware.
4
+
5
+
In our I/O environments we need to write drivers for each mezzanine
6
+
card, and such drivers must work regardless of the carrier being used.
7
+
To achieve this, we abstract the FMC interface.
8
+
9
+
We have a carrier for PCI-E called SPEC and one for VME called SVEC,
10
+
but more are planned. Also, we support stand-alone devices (usually
11
+
plugged on a SPEC card), controlled through Etherbone, developed by GSI.
12
+
13
+
Code and documentation for the FMC bus was born as part of the spec-sw
14
+
project, but now it lives in its own project. Other projects, i.e.
15
+
software support for the various carriers, should include this as a
16
+
submodule.
17
+
18
+
The most up to date version of code and documentation is always
19
+
available from the repository you can clone from:
20
+
21
+
git://ohwr.org/fmc-projects/fmc-bus.git (read-only)
22
+
git@ohwr.org:fmc-projects/fmc-bus.git (read-write for developers)
23
+
24
+
Selected versions of the documentation, as well as complete tar
25
+
archives for selected revisions are placed to the Files section of the
26
+
project: `http://www.ohwr.org/projects/fmc-bus/files'
27
+
28
+
29
+
What is FMC
30
+
***********
31
+
32
+
FMC, as said, stands for "FPGA Mezzanine Card". It is a standard
33
+
developed by the VME consortium called VITA (VMEbus International Trade
34
+
Association and ratified by ANSI, the American National Standard
35
+
Institute. The official documentation is called "ANSI-VITA 57.1".
36
+
37
+
The FMC card is an almost square PCB, around 70x75 millimeters, that is
38
+
called mezzanine in this document. It usually lives plugged into
39
+
another PCB for power supply and control; such bigger circuit board is
40
+
called carrier from now on, and a single carrier may host more than one
41
+
mezzanine.
42
+
43
+
In the typical application the mezzanine is mostly analog while the
44
+
carrier is mostly digital, and hosts an FPGA that must be configured to
45
+
match the specific mezzanine and the desired application. Thus, you may
46
+
need to load different FPGA images to drive different instances of the
47
+
same mezzanine.
48
+
49
+
FMC, as such, is not a bus in the usual meaning of the term, because
50
+
most carriers have only one connector, and carriers with several
51
+
connectors have completely separate electrical connections to them.
52
+
This package, however, implements a bus as a software abstraction.
53
+
54
+
55
+
What is SDB
56
+
***********
57
+
58
+
SDB (Self Describing Bus) is a set of data structures that we use for
59
+
enumerating the internal structure of an FPGA image. We also use it as
60
+
a filesystem inside the FMC EEPROM.
61
+
62
+
SDB is not mandatory for use of this FMC kernel bus, but if you have SDB
63
+
this package can make good use of it. SDB itself is developed in the
64
+
fpga-config-space OHWR project. The link to the repository is
65
+
`git://ohwr.org/hdl-core-lib/fpga-config-space.git' and what is used in
66
+
this project lives in the sdbfs subdirectory in there.
67
+
68
+
SDB support for FMC is described in *note FMC Identification:: and
69
+
*note SDB Support::
70
+
71
+
72
+
SDB Support
73
+
***********
74
+
75
+
The fmc.ko bus driver exports a few functions to help drivers taking
76
+
advantage of the SDB information that may be present in your own FPGA
77
+
memory image.
78
+
79
+
The module exports the following functions, in the special header
80
+
<linux/fmc-sdb.h>. The linux/ prefix in the name is there because we
81
+
plan to submit it upstream in the future, and don't want to force
82
+
changes on our drivers if that happens.
83
+
84
+
int fmc_scan_sdb_tree(struct fmc_device *fmc, unsigned long address);
85
+
void fmc_show_sdb_tree(struct fmc_device *fmc);
86
+
signed long fmc_find_sdb_device(struct sdb_array *tree, uint64_t vendor,
87
+
uint32_t device, unsigned long *sz);
88
+
int fmc_free_sdb_tree(struct fmc_device *fmc);
+311
Documentation/fmc/carrier.txt
+311
Documentation/fmc/carrier.txt
···
1
+
FMC Device
2
+
**********
3
+
4
+
Within the Linux bus framework, the FMC device is created and
5
+
registered by the carrier driver. For example, the PCI driver for the
6
+
SPEC card fills a data structure for each SPEC that it drives, and
7
+
registers an associated FMC device for each card. The SVEC driver can
8
+
do exactly the same for the VME carrier (actually, it should do it
9
+
twice, because the SVEC carries two FMC mezzanines). Similarly, an
10
+
Etherbone driver will be able to register its own FMC devices, offering
11
+
communication primitives through frame exchange.
12
+
13
+
The contents of the EEPROM within the FMC are used for identification
14
+
purposes, i.e. for matching the device with its own driver. For this
15
+
reason the device structure includes a complete copy of the EEPROM
16
+
(actually, the carrier driver may choose whether or not to return it -
17
+
for example we most likely won't have the whole EEPROM available for
18
+
Etherbone devices.
19
+
20
+
The following listing shows the current structure defining a device.
21
+
Please note that all the machinery is in place but some details may
22
+
still change in the future. For this reason, there is a version field
23
+
at the beginning of the structure. As usual, the minor number will
24
+
change for compatible changes (like a new flag) and the major number
25
+
will increase when an incompatible change happens (for example, a
26
+
change in layout of some fmc data structures). Device writers should
27
+
just set it to the value FMC_VERSION, and be ready to get back -EINVAL
28
+
at registration time.
29
+
30
+
struct fmc_device {
31
+
unsigned long version;
32
+
unsigned long flags;
33
+
struct module *owner; /* char device must pin it */
34
+
struct fmc_fru_id id; /* for EEPROM-based match */
35
+
struct fmc_operations *op; /* carrier-provided */
36
+
int irq; /* according to host bus. 0 == none */
37
+
int eeprom_len; /* Usually 8kB, may be less */
38
+
int eeprom_addr; /* 0x50, 0x52 etc */
39
+
uint8_t *eeprom; /* Full contents or leading part */
40
+
char *carrier_name; /* "SPEC" or similar, for special use */
41
+
void *carrier_data; /* "struct spec *" or equivalent */
42
+
__iomem void *fpga_base; /* May be NULL (Etherbone) */
43
+
__iomem void *slot_base; /* Set by the driver */
44
+
struct fmc_device **devarray; /* Allocated by the bus */
45
+
int slot_id; /* Index in the slot array */
46
+
int nr_slots; /* Number of slots in this carrier */
47
+
unsigned long memlen; /* Used for the char device */
48
+
struct device dev; /* For Linux use */
49
+
struct device *hwdev; /* The underlying hardware device */
50
+
unsigned long sdbfs_entry;
51
+
struct sdb_array *sdb;
52
+
uint32_t device_id; /* Filled by the device */
53
+
char *mezzanine_name; /* Defaults to ``fmc'' */
54
+
void *mezzanine_data;
55
+
};
56
+
57
+
The meaning of most fields is summarized in the code comment above.
58
+
59
+
The following fields must be filled by the carrier driver before
60
+
registration:
61
+
62
+
* version: must be set to FMC_VERSION.
63
+
64
+
* owner: set to MODULE_OWNER.
65
+
66
+
* op: the operations to act on the device.
67
+
68
+
* irq: number for the mezzanine; may be zero.
69
+
70
+
* eeprom_len: length of the following array.
71
+
72
+
* eeprom_addr: 0x50 for first mezzanine and so on.
73
+
74
+
* eeprom: the full content of the I2C EEPROM.
75
+
76
+
* carrier_name.
77
+
78
+
* carrier_data: a unique pointer for the carrier.
79
+
80
+
* fpga_base: the I/O memory address (may be NULL).
81
+
82
+
* slot_id: the index of this slot (starting from zero).
83
+
84
+
* memlen: if fpga_base is valid, the length of I/O memory.
85
+
86
+
* hwdev: to be used in some dev_err() calls.
87
+
88
+
* device_id: a slot-specific unique integer number.
89
+
90
+
91
+
Please note that the carrier should read its own EEPROM memory before
92
+
registering the device, as well as fill all other fields listed above.
93
+
94
+
The following fields should not be assigned, because they are filled
95
+
later by either the bus or the device driver:
96
+
97
+
* flags.
98
+
99
+
* fru_id: filled by the bus, parsing the eeprom.
100
+
101
+
* slot_base: filled and used by the driver, if useful to it.
102
+
103
+
* devarray: an array og all mezzanines driven by a singe FPGA.
104
+
105
+
* nr_slots: set by the core at registration time.
106
+
107
+
* dev: used by Linux.
108
+
109
+
* sdb: FPGA contents, scanned according to driver's directions.
110
+
111
+
* sdbfs_entry: SDB entry point in EEPROM: autodetected.
112
+
113
+
* mezzanine_data: available for the driver.
114
+
115
+
* mezzanine_name: filled by fmc-bus during identification.
116
+
117
+
118
+
Note: mezzanine_data may be redundant, because Linux offers the drvdata
119
+
approach, so the field may be removed in later versions of this bus
120
+
implementation.
121
+
122
+
As I write this, she SPEC carrier is already completely functional in
123
+
the fmc-bus environment, and is a good reference to look at.
124
+
125
+
126
+
The API Offered by Carriers
127
+
===========================
128
+
129
+
The carrier provides a number of methods by means of the
130
+
`fmc_operations' structure, which currently is defined like this
131
+
(again, it is a moving target, please refer to the header rather than
132
+
this document):
133
+
134
+
struct fmc_operations {
135
+
uint32_t (*readl)(struct fmc_device *fmc, int offset);
136
+
void (*writel)(struct fmc_device *fmc, uint32_t value, int offset);
137
+
int (*reprogram)(struct fmc_device *f, struct fmc_driver *d, char *gw);
138
+
int (*validate)(struct fmc_device *fmc, struct fmc_driver *drv);
139
+
int (*irq_request)(struct fmc_device *fmc, irq_handler_t h,
140
+
char *name, int flags);
141
+
void (*irq_ack)(struct fmc_device *fmc);
142
+
int (*irq_free)(struct fmc_device *fmc);
143
+
int (*gpio_config)(struct fmc_device *fmc, struct fmc_gpio *gpio,
144
+
int ngpio);
145
+
int (*read_ee)(struct fmc_device *fmc, int pos, void *d, int l);
146
+
int (*write_ee)(struct fmc_device *fmc, int pos, const void *d, int l);
147
+
};
148
+
149
+
The individual methods perform the following tasks:
150
+
151
+
`readl'
152
+
`writel'
153
+
These functions access FPGA registers by whatever means the
154
+
carrier offers. They are not expected to fail, and most of the time
155
+
they will just make a memory access to the host bus. If the
156
+
carrier provides a fpga_base pointer, the driver may use direct
157
+
access through that pointer. For this reason the header offers the
158
+
inline functions fmc_readl and fmc_writel that access fpga_base if
159
+
the respective method is NULL. A driver that wants to be portable
160
+
and efficient should use fmc_readl and fmc_writel. For Etherbone,
161
+
or other non-local carriers, error-management is still to be
162
+
defined.
163
+
164
+
`validate'
165
+
Module parameters are used to manage different applications for
166
+
two or more boards of the same kind. Validation is based on the
167
+
busid module parameter, if provided, and returns the matching
168
+
index in the associated array. See *note Module Parameters:: in in
169
+
doubt. If no match is found, `-ENOENT' is returned; if the user
170
+
didn't pass `busid=', all devices will pass validation. The value
171
+
returned by the validate method can be used as index into other
172
+
parameters (for example, some drivers use the `lm32=' parameter in
173
+
this way). Such "generic parameters" are documented in *note
174
+
Module Parameters::, below. The validate method is used by
175
+
`fmc-trivial.ko', described in *note fmc-trivial::.
176
+
177
+
`reprogram'
178
+
The carrier enumerates FMC devices by loading a standard (or
179
+
golden) FPGA binary that allows EEPROM access. Each driver, then,
180
+
will need to reprogram the FPGA by calling this function. If the
181
+
name argument is NULL, the carrier should reprogram the golden
182
+
binary. If the gateware name has been overridden through module
183
+
parameters (in a carrier-specific way) the file loaded will match
184
+
the parameters. Per-device gateware names can be specified using
185
+
the `gateware=' parameter, see *note Module Parameters::. Note:
186
+
Clients should call rhe new helper, fmc_reprogram, which both
187
+
calls this method and parse the SDB tree of the FPGA.
188
+
189
+
`irq_request'
190
+
`irq_ack'
191
+
`irq_free'
192
+
Interrupt management is carrier-specific, so it is abstracted as
193
+
operations. The interrupt number is listed in the device
194
+
structure, and for the mezzanine driver the number is only
195
+
informative. The handler will receive the fmc pointer as dev_id;
196
+
the flags argument is passed to the Linux request_irq function,
197
+
but fmc-specific flags may be added in the future. You'll most
198
+
likely want to pass the `IRQF_SHARED' flag.
199
+
200
+
`gpio_config'
201
+
The method allows to configure a GPIO pin in the carrier, and read
202
+
its current value if it is configured as input. See *note The GPIO
203
+
Abstraction:: for details.
204
+
205
+
`read_ee'
206
+
`write_ee'
207
+
Read or write the EEPROM. The functions are expected to be only
208
+
called before reprogramming and the carrier should refuse them
209
+
with `ENODEV' after reprogramming. The offset is expected to be
210
+
within 8kB (the current size), but addresses up to 1MB are
211
+
reserved to fit bigger I2C devices in the future. Carriers may
212
+
offer access to other internal flash memories using these same
213
+
methods: for example the SPEC driver may define that its carrier
214
+
I2C memory is seen at offset 1M and the internal SPI flash is seen
215
+
at offset 16M. This multiplexing of several flash memories in the
216
+
same address space is is carrier-specific and should only be used
217
+
by a driver that has verified the `carrier_name' field.
218
+
219
+
220
+
221
+
The GPIO Abstraction
222
+
====================
223
+
224
+
Support for GPIO pins in the fmc-bus environment is not very
225
+
straightforward and deserves special discussion.
226
+
227
+
While the general idea of a carrier-independent driver seems to fly,
228
+
configuration of specific signals within the carrier needs at least
229
+
some knowledge of the carrier itself. For this reason, the specific
230
+
driver can request to configure carrier-specific GPIO pins, numbered
231
+
from 0 to at most 4095. Configuration is performed by passing a
232
+
pointer to an array of struct fmc_gpio items, as well as the length of
233
+
the array. This is the data structure:
234
+
235
+
struct fmc_gpio {
236
+
char *carrier_name;
237
+
int gpio;
238
+
int _gpio; /* internal use by the carrier */
239
+
int mode; /* GPIOF_DIR_OUT etc, from <linux/gpio.h> */
240
+
int irqmode; /* IRQF_TRIGGER_LOW and so on */
241
+
};
242
+
243
+
By specifying a carrier_name for each pin, the driver may access
244
+
different pins in different carriers. The gpio_config method is
245
+
expected to return the number of pins successfully configured, ignoring
246
+
requests for other carriers. However, if no pin is configured (because
247
+
no structure at all refers to the current carrier_name), the operation
248
+
returns an error so the caller will know that it is running under a
249
+
yet-unsupported carrier.
250
+
251
+
So, for example, a driver that has been developed and tested on both
252
+
the SPEC and the SVEC may request configuration of two different GPIO
253
+
pins, and expect one such configuration to succeed - if none succeeds
254
+
it most likely means that the current carrier is a still-unknown one.
255
+
256
+
If, however, your GPIO pin has a specific known role, you can pass a
257
+
special number in the gpio field, using one of the following macros:
258
+
259
+
#define FMC_GPIO_RAW(x) (x) /* 4096 of them */
260
+
#define FMC_GPIO_IRQ(x) ((x) + 0x1000) /* 256 of them */
261
+
#define FMC_GPIO_LED(x) ((x) + 0x1100) /* 256 of them */
262
+
#define FMC_GPIO_KEY(x) ((x) + 0x1200) /* 256 of them */
263
+
#define FMC_GPIO_TP(x) ((x) + 0x1300) /* 256 of them */
264
+
#define FMC_GPIO_USER(x) ((x) + 0x1400) /* 256 of them */
265
+
266
+
Use of virtual GPIO numbers (anything but FMC_GPIO_RAW) is allowed
267
+
provided the carrier_name field in the data structure is left
268
+
unspecified (NULL). Each carrier is responsible for providing a mapping
269
+
between virtual and physical GPIO numbers. The carrier may then use the
270
+
_gpio field to cache the result of this mapping.
271
+
272
+
All carriers must map their I/O lines to the sets above starting from
273
+
zero. The SPEC, for example, maps interrupt pins 0 and 1, and test
274
+
points 0 through 3 (even if the test points on the PCB are called
275
+
5,6,7,8).
276
+
277
+
If, for example, a driver requires a free LED and a test point (for a
278
+
scope probe to be plugged at some point during development) it may ask
279
+
for FMC_GPIO_LED(0) and FMC_GPIO_TP(0). Each carrier will provide
280
+
suitable GPIO pins. Clearly, the person running the drivers will know
281
+
the order used by the specific carrier driver in assigning leds and
282
+
testpoints, so to make a carrier-dependent use of the diagnostic tools.
283
+
284
+
In theory, some form of autodetection should be possible: a driver like
285
+
the wr-nic (which uses IRQ(1) on the SPEC card) should configure
286
+
IRQ(0), make a test with software-generated interrupts and configure
287
+
IRQ(1) if the test fails. This probing step should be used because even
288
+
if the wr-nic gateware is known to use IRQ1 on the SPEC, the driver
289
+
should be carrier-independent and thus use IRQ(0) as a first bet -
290
+
actually, the knowledge that IRQ0 may fail is carrier-dependent
291
+
information, but using it doesn't make the driver unsuitable for other
292
+
carriers.
293
+
294
+
The return value of gpio_config is defined as follows:
295
+
296
+
* If no pin in the array can be used by the carrier, `-ENODEV'.
297
+
298
+
* If at least one virtual GPIO number cannot be mapped, `-ENOENT'.
299
+
300
+
* On success, 0 or positive. The value returned is the number of
301
+
high input bits (if no input is configured, the value for success
302
+
is 0).
303
+
304
+
While I admit the procedure is not completely straightforward, it
305
+
allows configuration, input and output with a single carrier operation.
306
+
Given the typical use case of FMC devices, GPIO operations are not
307
+
expected to ever by in hot paths, and GPIO access so fare has only been
308
+
used to configure the interrupt pin, mode and polarity. Especially
309
+
reading inputs is not expected to be common. If your device has GPIO
310
+
capabilities in the hot path, you should consider using the kernel's
311
+
GPIO mechanisms.
+168
Documentation/fmc/identifiers.txt
+168
Documentation/fmc/identifiers.txt
···
1
+
FMC Identification
2
+
******************
3
+
4
+
The FMC standard requires every compliant mezzanine to carry
5
+
identification information in an I2C EEPROM. The information must be
6
+
laid out according to the "IPMI Platform Management FRU Information",
7
+
where IPMI is a lie I'd better not expand, and FRU means "Field
8
+
Replaceable Unit".
9
+
10
+
The FRU information is an intricate unreadable binary blob that must
11
+
live at offset 0 of the EEPROM, and typically extends for a few hundred
12
+
bytes. The standard allows the application to use all the remaining
13
+
storage area of the EEPROM as it wants.
14
+
15
+
This chapter explains how to create your own EEPROM image and how to
16
+
write it in your mezzanine, as well as how devices and drivers are
17
+
paired at run time. EEPROM programming uses tools that are part of this
18
+
package and SDB (part of the fpga-config-space package).
19
+
20
+
The first sections are only interesting for manufacturers who need to
21
+
write the EEPROM. If you are just a software developer writing an FMC
22
+
device or driver, you may jump straight to *note SDB Support::.
23
+
24
+
25
+
Building the FRU Structure
26
+
==========================
27
+
28
+
If you want to know the internals of the FRU structure and despair, you
29
+
can retrieve the document from
30
+
`http://download.intel.com/design/servers/ipmi/FRU1011.pdf' . The
31
+
standard is awful and difficult without reason, so we only support the
32
+
minimum mandatory subset - we create a simple structure and parse it
33
+
back at run time, but we are not able to either generate or parse more
34
+
arcane features like non-english languages and 6-bit text. If you need
35
+
more items of the FRU standard for your boards, please submit patches.
36
+
37
+
This package includes the Python script that Matthieu Cattin wrote to
38
+
generate the FRU binary blob, based on an helper libipmi by Manohar
39
+
Vanga and Matthieu himself. I changed the test script to receive
40
+
parameters from the command line or from the environment (the command
41
+
line takes precedence)
42
+
43
+
To make a long story short, in order to build a standard-compliant
44
+
binary file to be burned in your EEPROM, you need the following items:
45
+
46
+
Environment Opt Official Name Default
47
+
---------------------------------------------------------------------
48
+
FRU_VENDOR -v "Board Manufacturer" fmc-example
49
+
FRU_NAME -n "Board Product Name" mezzanine
50
+
FRU_SERIAL -s `Board Serial Number" 0001
51
+
FRU_PART -p "Board Part Number" sample-part
52
+
FRU_OUTPUT -o not applicable /dev/stdout
53
+
54
+
The "Official Name" above is what you find in the FRU official
55
+
documentation, chapter 11, page 7 ("Board Info Area Format"). The
56
+
output option is used to save the generated binary to a specific file
57
+
name instead of stdout.
58
+
59
+
You can pass the items to the FRU generator either in the environment
60
+
or on the command line. This package has currently no support for
61
+
specifying power consumption or such stuff, but I plan to add it as
62
+
soon as I find some time for that.
63
+
64
+
FIXME: consumption etc for FRU are here or in PTS?
65
+
66
+
The following example creates a binary image for a specific board:
67
+
68
+
./tools/fru-generator -v CERN -n FmcAdc100m14b4cha \
69
+
-s HCCFFIA___-CR000003 -p EDA-02063-V5-0 > eeprom.bin
70
+
71
+
The following example shows a script that builds several binary EEPROM
72
+
images for a series of boards, changing the serial number for each of
73
+
them. The script uses a mix of environment variables and command line
74
+
options, and uses the same string patterns shown above.
75
+
76
+
#!/bin/sh
77
+
78
+
export FRU_VENDOR="CERN"
79
+
export FRU_NAME="FmcAdc100m14b4cha"
80
+
export FRU_PART="EDA-02063-V5-0"
81
+
82
+
serial="HCCFFIA___-CR"
83
+
84
+
for number in $(seq 1 50); do
85
+
# build number-string "ns"
86
+
ns="$(printf %06d $number)"
87
+
./fru-generator -s "${serial}${ns}" > eeprom-${ns}.bin
88
+
done
89
+
90
+
91
+
Using SDB-FS in the EEPROM
92
+
==========================
93
+
94
+
If you want to use SDB as a filesystem in the EEPROM device within the
95
+
mezzanine, you should create one such filesystem using gensdbfs, from
96
+
the fpga-config-space package on OHWR.
97
+
98
+
By using an SBD filesystem you can cluster several files in a single
99
+
EEPROM, so both the host system and a soft-core running in the FPGA (if
100
+
any) can access extra production-time information.
101
+
102
+
We chose to use SDB as a storage filesystem because the format is very
103
+
simple, and both the host system and the soft-core will likely already
104
+
include support code for such format. The SDB library offered by the
105
+
fpga-config-space is less than 1kB under LM32, so it proves quite up to
106
+
the task.
107
+
108
+
The SDB entry point (which acts as a directory listing) cannot live at
109
+
offset zero in the flash device, because the FRU information must live
110
+
there. To avoid wasting precious storage space while still allowing
111
+
for more-than-minimal FRU structures, the fmc.ko will look for the SDB
112
+
record at address 256, 512 and 1024.
113
+
114
+
In order to generate the complete EEPROM image you'll need a
115
+
configuration file for gensdbfs: you tell the program where to place
116
+
the sdb entry point, and you must force the FRU data file to be placed
117
+
at the beginning of the storage device. If needed, you can also place
118
+
other files at a special offset (we sometimes do it for backward
119
+
compatibility with drivers we wrote before implementing SDB for flash
120
+
memory).
121
+
122
+
The directory tools/sdbfs of this package includes a well-commented
123
+
example that you may want to use as a starting point (the comments are
124
+
in the file called -SDB-CONFIG-). Reading documentation for gensdbfs
125
+
is a suggested first step anyways.
126
+
127
+
This package (generic FMC bus support) only accesses two files in the
128
+
EEPROM: the FRU information, at offset zero, with a suggested filename
129
+
of IPMI-FRU and the short name for the mezzanine, in a file called
130
+
name. The IPMI-FRU name is not mandatory, but a strongly suggested
131
+
choice; the name filename is mandatory, because this is the preferred
132
+
short name used by the FMC core. For example, a name of "fdelay" may
133
+
supplement a Product Name like "FmcDelay1ns4cha" - exactly as
134
+
demonstrated in `tools/sdbfs'.
135
+
136
+
Note: SDB access to flash memory is not yet supported, so the short
137
+
name currently in use is just the "Product Name" FRU string.
138
+
139
+
The example in tools/sdbfs includes an extra file, that is needed by
140
+
the fine-delay driver, and must live at a known address of 0x1800. By
141
+
running gensdbfs on that directory you can output your binary EEPROM
142
+
image (here below spusa$ is the shell prompt):
143
+
144
+
spusa$ ../fru-generator -v CERN -n FmcDelay1ns4cha -s proto-0 \
145
+
-p EDA-02267-V3 > IPMI-FRU
146
+
spusa$ ls -l
147
+
total 16
148
+
-rw-rw-r-- 1 rubini staff 975 Nov 19 18:08 --SDB-CONFIG--
149
+
-rw-rw-r-- 1 rubini staff 216 Nov 19 18:13 IPMI-FRU
150
+
-rw-rw-r-- 1 rubini staff 11 Nov 19 18:04 fd-calib
151
+
-rw-rw-r-- 1 rubini staff 7 Nov 19 18:04 name
152
+
spusa$ sudo gensdbfs . /lib/firmware/fdelay-eeprom.bin
153
+
spusa$ sdb-read -l -e 0x100 /lib/firmware/fdelay-eeprom.bin
154
+
/home/rubini/wip/sdbfs/userspace/sdb-read: listing format is to be defined
155
+
46696c6544617461:2e202020 00000100-000018ff .
156
+
46696c6544617461:6e616d65 00000200-00000206 name
157
+
46696c6544617461:66642d63 00001800-000018ff fd-calib
158
+
46696c6544617461:49504d49 00000000-000000d7 IPMI-FRU
159
+
spusa$ ../fru-dump /lib/firmware/fdelay-eeprom.bin
160
+
/lib/firmware/fdelay-eeprom.bin: manufacturer: CERN
161
+
/lib/firmware/fdelay-eeprom.bin: product-name: FmcDelay1ns4cha
162
+
/lib/firmware/fdelay-eeprom.bin: serial-number: proto-0
163
+
/lib/firmware/fdelay-eeprom.bin: part-number: EDA-02267-V3
164
+
165
+
As expected, the output file is both a proper sdbfs object and an IPMI
166
+
FRU information blob. The fd-calib file lives at offset 0x1800 and is
167
+
over-allocated to 256 bytes, according to the configuration file for
168
+
gensdbfs.
+123
Documentation/fmc/mezzanine.txt
+123
Documentation/fmc/mezzanine.txt
···
1
+
FMC Driver
2
+
**********
3
+
4
+
An FMC driver is concerned with the specific mezzanine and associated
5
+
gateware. As such, it is expected to be independent of the carrier
6
+
being used: it will perform I/O accesses only by means of
7
+
carrier-provided functions.
8
+
9
+
The matching between device and driver is based on the content of the
10
+
EEPROM (as mandated by the FMC standard) or by the actual cores
11
+
configured in the FPGA; the latter technique is used when the FPGA is
12
+
already programmed when the device is registered to the bus core.
13
+
14
+
In some special cases it is possible for a driver to directly access
15
+
FPGA registers, by means of the `fpga_base' field of the device
16
+
structure. This may be needed for high-bandwidth peripherals like fast
17
+
ADC cards. If the device module registered a remote device (for example
18
+
by means of Etherbone), the `fpga_base' pointer will be NULL.
19
+
Therefore, drivers must be ready to deal with NULL base pointers, and
20
+
fail gracefully. Most driver, however, are not expected to access the
21
+
pointer directly but run fmc_readl and fmc_writel instead, which will
22
+
work in any case.
23
+
24
+
In even more special cases, the driver may access carrier-specific
25
+
functionality: the `carrier_name' string allows the driver to check
26
+
which is the current carrier and make use of the `carrier_data'
27
+
pointer. We chose to use carrier names rather than numeric identifiers
28
+
for greater flexibility, but also to avoid a central registry within
29
+
the `fmc.h' file - we hope other users will exploit our framework with
30
+
their own carriers. An example use of carrier names is in GPIO setup
31
+
(see *note The GPIO Abstraction::), although the name match is not
32
+
expected to be performed by the driver. If you depend on specific
33
+
carriers, please check the carrier name and fail gracefully if your
34
+
driver finds it is running in a yet-unknown-to-it environment.
35
+
36
+
37
+
ID Table
38
+
========
39
+
40
+
Like most other Linux drivers, and FMC driver must list all the devices
41
+
which it is able to drive. This is usually done by means of a device
42
+
table, but in FMC we can match hardware based either on the contents of
43
+
their EEPROM or on the actual FPGA cores that can be enumerated.
44
+
Therefore, we have two tables of identifiers.
45
+
46
+
Matching of FRU information depends on two names, the manufacturer (or
47
+
vendor) and the device (see *note FMC Identification::); for
48
+
flexibility during production (i.e. before writing to the EEPROM) the
49
+
bus supports a catch-all driver that specifies NULL strings. For this
50
+
reason, the table is specified as pointer-and-length, not a a
51
+
null-terminated array - the entry with NULL names can be a valid entry.
52
+
53
+
Matching on FPGA cores depends on two numeric fields: the 64-bit vendor
54
+
number and the 32-bit device number. Support for matching based on
55
+
class is not yet implemented. Each device is expected to be uniquely
56
+
identified by an array of cores (it matches if all of the cores are
57
+
instantiated), and for consistency the list is passed as
58
+
pointer-and-length. Several similar devices can be driven by the same
59
+
driver, and thus the driver specifies and array of such arrays.
60
+
61
+
The complete set of involved data structures is thus the following:
62
+
63
+
struct fmc_fru_id { char *manufacturer; char *product_name; };
64
+
struct fmc_sdb_one_id { uint64_t vendor; uint32_t device; };
65
+
struct fmc_sdb_id { struct fmc_sdb_one_id *cores; int cores_nr; };
66
+
67
+
struct fmc_device_id {
68
+
struct fmc_fru_id *fru_id; int fru_id_nr;
69
+
struct fmc_sdb_id *sdb_id; int sdb_id_nr;
70
+
};
71
+
72
+
A better reference, with full explanation, is the <linux/fmc.h> header.
73
+
74
+
75
+
Module Parameters
76
+
=================
77
+
78
+
Most of the FMC drivers need the same set of kernel parameters. This
79
+
package includes support to implement common parameters by means of
80
+
fields in the `fmc_driver' structure and simple macro definitions.
81
+
82
+
The parameters are carrier-specific, in that they rely on the busid
83
+
concept, that varies among carriers. For the SPEC, the identifier is a
84
+
PCI bus and devfn number, 16 bits wide in total; drivers for other
85
+
carriers will most likely offer something similar but not identical,
86
+
and some code duplication is unavoidable.
87
+
88
+
This is the list of parameters that are common to several modules to
89
+
see how they are actually used, please look at spec-trivial.c.
90
+
91
+
`busid='
92
+
This is an array of integers, listing carrier-specific
93
+
identification numbers. For PIC, for example, `0x0400' represents
94
+
bus 4, slot 0. If any such ID is specified, the driver will only
95
+
accept to drive cards that appear in the list (even if the FMC ID
96
+
matches). This is accomplished by the validate carrier method.
97
+
98
+
`gateware='
99
+
The argument is an array of strings. If no busid= is specified,
100
+
the first string of gateware= is used for all cards; otherwise the
101
+
identifiers and gateware names are paired one by one, in the order
102
+
specified.
103
+
104
+
`show_sdb='
105
+
For modules supporting it, this parameter asks to show the SDB
106
+
internal structure by means of kernel messages. It is disabled by
107
+
default because those lines tend to hide more important messages,
108
+
if you look at the system console while loading the drivers.
109
+
Note: the parameter is being obsoleted, because fmc.ko itself now
110
+
supports dump_sdb= that applies to every client driver.
111
+
112
+
113
+
For example, if you are using the trivial driver to load two different
114
+
gateware files to two different cards, you can use the following
115
+
parameters to load different binaries to the cards, after looking up
116
+
the PCI identifiers. This has been tested with a SPEC carrier.
117
+
118
+
insmod fmc-trivial.ko \
119
+
busid=0x0200,0x0400 \
120
+
gateware=fmc/fine-delay.bin,fmc/simple-dio.bin
121
+
122
+
Please note that not all sub-modules support all of those parameters.
123
+
You can use modinfo to check what is supported by each module.
+56
Documentation/fmc/parameters.txt
+56
Documentation/fmc/parameters.txt
···
1
+
Module Parameters in fmc.ko
2
+
***************************
3
+
4
+
The core driver receives two module parameters, meant to help debugging
5
+
client modules. Both parameters can be modified by writing to
6
+
/sys/module/fmc/parameters/, because they are used when client drivers
7
+
are devices are registered, not when fmc.ko is loaded.
8
+
9
+
`dump_eeprom='
10
+
If not zero, the parameter asks the bus controller to dump the
11
+
EEPROM of any device that is registered, using printk.
12
+
13
+
`dump_sdb='
14
+
If not zero, the parameter prints the SDB tree of every FPGA it is
15
+
loaded by fmc_reprogram(). If greater than one, it asks to dump
16
+
the binary content of SDB records. This currently only dumps the
17
+
top-level SDB array, though.
18
+
19
+
20
+
EEPROM dumping avoids repeating lines, since most of the contents is
21
+
usually empty and all bits are one or zero. This is an example of the
22
+
output:
23
+
24
+
[ 6625.850480] spec 0000:02:00.0: FPGA programming successful
25
+
[ 6626.139949] spec 0000:02:00.0: Manufacturer: CERN
26
+
[ 6626.144666] spec 0000:02:00.0: Product name: FmcDelay1ns4cha
27
+
[ 6626.150370] FMC: mezzanine 0: 0000:02:00.0 on SPEC
28
+
[ 6626.155179] FMC: dumping eeprom 0x2000 (8192) bytes
29
+
[ 6626.160087] 0000: 01 00 00 01 00 0b 00 f3 01 0a 00 a5 85 87 c4 43
30
+
[ 6626.167069] 0010: 45 52 4e cf 46 6d 63 44 65 6c 61 79 31 6e 73 34
31
+
[ 6626.174019] 0020: 63 68 61 c7 70 72 6f 74 6f 2d 30 cc 45 44 41 2d
32
+
[ 6626.180975] 0030: 30 32 32 36 37 2d 56 33 da 32 30 31 32 2d 31 31
33
+
[...]
34
+
[ 6626.371366] 0200: 66 64 65 6c 61 79 0a 00 00 00 00 00 00 00 00 00
35
+
[ 6626.378359] 0210: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
36
+
[ 6626.385361] [...]
37
+
[ 6626.387308] 1800: 70 6c 61 63 65 68 6f 6c 64 65 72 ff ff ff ff ff
38
+
[ 6626.394259] 1810: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff
39
+
[ 6626.401250] [...]
40
+
41
+
The dump of SDB looks like the following; the example shows the simple
42
+
golden gateware for the SPEC card, removing the leading timestamps to
43
+
fit the page:
44
+
45
+
spec 0000:02:00.0: SDB: 00000651:e6a542c9 WB4-Crossbar-GSI
46
+
spec 0000:02:00.0: SDB: 0000ce42:ff07fc47 WR-Periph-Syscon (00000000-000000ff)
47
+
FMC: mezzanine 0: 0000:02:00.0 on SPEC
48
+
FMC: poor dump of sdb first level:
49
+
0000: 53 44 42 2d 00 02 01 00 00 00 00 00 00 00 00 00
50
+
0010: 00 00 00 00 00 00 01 ff 00 00 00 00 00 00 06 51
51
+
0020: e6 a5 42 c9 00 00 00 02 20 12 05 11 57 42 34 2d
52
+
0030: 43 72 6f 73 73 62 61 72 2d 47 53 49 20 20 20 00
53
+
0040: 00 00 01 01 00 00 00 07 00 00 00 00 00 00 00 00
54
+
0050: 00 00 00 00 00 00 00 ff 00 00 00 00 00 00 ce 42
55
+
0060: ff 07 fc 47 00 00 00 01 20 12 03 05 57 52 2d 50
56
+
0070: 65 72 69 70 68 2d 53 79 73 63 6f 6e 20 20 20 01