1fmc-write-eeprom
2================
3
4This module is designed to load a binary file from /lib/firmware and to
5write it to the internal EEPROM of the mezzanine card. This driver uses
6the `busid' generic parameter.
7
8Overwriting the EEPROM is not something you should do daily, and it is
9expected to only happen during manufacturing. For this reason, the
10module makes it unlikely for the random user to change a working EEPROM.
11
12However, since the EEPROM may include application-specific information
13other than the identification, later versions of this packages added
14write-support through sysfs. See *note Accessing the EEPROM::.
15
16To avoid damaging the EEPROM content, the module takes the following
17measures:
18
19   * It accepts a `file=' argument (within /lib/firmware) and if no
20     such argument is received, it doesn't write anything to EEPROM
21     (i.e. there is no default file name).
22
23   * If the file name ends with `.bin' it is written verbatim starting
24     at offset 0.
25
26   * If the file name ends with `.tlv' it is interpreted as
27     type-length-value (i.e., it allows writev(2)-like operation).
28
29   * If the file name doesn't match any of the patterns above, it is
30     ignored and no write is performed.
31
32   * Only cards listed with `busid=' are written to. If no busid is
33     specified, no programming is done (and the probe function of the
34     driver will fail).
35
36
37Each TLV tuple is formatted in this way: the header is 5 bytes,
38followed by data. The first byte is `w' for write, the next two bytes
39represent the address, in little-endian byte order, and the next two
40represent the data length, in little-endian order. The length does not
41include the header (it is the actual number of bytes to be written).
42
43This is a real example: that writes 5 bytes at position 0x110:
44
45        spusa.root# od -t x1 -Ax /lib/firmware/try.tlv
46        000000 77 10 01 05 00 30 31 32 33 34
47        00000a
48        spusa.root# insmod /tmp/fmc-write-eeprom.ko busid=0x0200 file=try.tlv
49        [19983.391498] spec 0000:03:00.0: write 5 bytes at 0x0110
50        [19983.414615] spec 0000:03:00.0: write_eeprom: success
51
52Please note that you'll most likely want to use SDBFS to build your
53EEPROM image, at least if your mezzanines are being used in the White
54Rabbit environment. For this reason the TLV format is not expected to
55be used much and is not expected to be developed further.
56
57If you want to try reflashing fake EEPROM devices, you can use the
58fmc-fakedev.ko module (see *note fmc-fakedev::).  Whenever you change
59the image starting at offset 0, it will deregister and register again
60after two seconds.  Please note, however, that if fmc-write-eeprom is
61still loaded, the system will associate it to the new device, which
62will be reprogrammed and thus will be unloaded after two seconds.  The
63following example removes the module after it reflashed fakedev the
64first time.
65
66     spusa.root# insmod fmc-fakedev.ko
67        [   72.984733]  fake-fmc: Manufacturer: fake-vendor
68        [   72.989434]  fake-fmc: Product name: fake-design-for-testing
69        spusa.root# insmod fmc-write-eeprom.ko busid=0 file=fdelay-eeprom.bin; \
70            rmmod fmc-write-eeprom
71        [  130.874098]  fake-fmc: Matching a generic driver (no ID)
72        [  130.887845]  fake-fmc: programming 6155 bytes
73        [  130.894567]  fake-fmc: write_eeprom: success
74        [  132.895794]  fake-fmc: Manufacturer: CERN
75        [  132.899872]  fake-fmc: Product name: FmcDelay1ns4cha
76
77
78Accessing the EEPROM
79=====================
80
81The bus creates a sysfs binary file called eeprom for each mezzanine it
82knows about:
83
84        spusa.root# cd /sys/bus/fmc/devices; ls -l */eeprom
85        -r--r--r-- 1 root root 8192 Feb 21 12:30 FmcAdc100m14b4cha-0800/eeprom
86        -r--r--r-- 1 root root 8192 Feb 21 12:30 FmcDelay1ns4cha-0200/eeprom
87        -r--r--r-- 1 root root 8192 Feb 21 12:30 FmcDio5cha-0400/eeprom
88
89Everybody can read the files and the superuser can also modify it, but
90the operation may on the carrier driver, if the carrier is unable to
91access the I2C bus.  For example, the spec driver can access the bus
92only with its golden gateware: after a mezzanine driver reprogrammed
93the FPGA with a custom circuit, the carrier is unable to access the
94EEPROM and returns ENOTSUPP.
95
96An alternative way to write the EEPROM is the mezzanine driver
97fmc-write-eeprom (See *note fmc-write-eeprom::), but the procedure is
98more complex.
99