Commit | Line | Data |
---|---|---|
6007b1bd AR |
1 | fmc-write-eeprom |
2 | ================ | |
3 | ||
4 | This module is designed to load a binary file from /lib/firmware and to | |
5 | write it to the internal EEPROM of the mezzanine card. This driver uses | |
6 | the `busid' generic parameter. | |
7 | ||
8 | Overwriting the EEPROM is not something you should do daily, and it is | |
9 | expected to only happen during manufacturing. For this reason, the | |
10 | module makes it unlikely for the random user to change a working EEPROM. | |
11 | ||
5c9a8736 AR |
12 | However, since the EEPROM may include application-specific information |
13 | other than the identification, later versions of this packages added | |
14 | write-support through sysfs. See *note Accessing the EEPROM::. | |
15 | ||
16 | To avoid damaging the EEPROM content, the module takes the following | |
17 | measures: | |
6007b1bd AR |
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 | ||
37 | Each TLV tuple is formatted in this way: the header is 5 bytes, | |
38 | followed by data. The first byte is `w' for write, the next two bytes | |
39 | represent the address, in little-endian byte order, and the next two | |
40 | represent the data length, in little-endian order. The length does not | |
41 | include the header (it is the actual number of bytes to be written). | |
42 | ||
43 | This 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 | ||
52 | Please note that you'll most likely want to use SDBFS to build your | |
53 | EEPROM image, at least if your mezzanines are being used in the White | |
54 | Rabbit environment. For this reason the TLV format is not expected to | |
55 | be used much and is not expected to be developed further. | |
56 | ||
57 | If you want to try reflashing fake EEPROM devices, you can use the | |
58 | fmc-fakedev.ko module (see *note fmc-fakedev::). Whenever you change | |
59 | the image starting at offset 0, it will deregister and register again | |
60 | after two seconds. Please note, however, that if fmc-write-eeprom is | |
61 | still loaded, the system will associate it to the new device, which | |
62 | will be reprogrammed and thus will be unloaded after two seconds. The | |
63 | following example removes the module after it reflashed fakedev the | |
64 | first 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 | ||
5c9a8736 | 78 | Accessing the EEPROM |
6007b1bd AR |
79 | ===================== |
80 | ||
5c9a8736 AR |
81 | The bus creates a sysfs binary file called eeprom for each mezzanine it |
82 | knows 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 | ||
89 | Everybody can read the files and the superuser can also modify it, but | |
90 | the operation may on the carrier driver, if the carrier is unable to | |
91 | access the I2C bus. For example, the spec driver can access the bus | |
92 | only with its golden gateware: after a mezzanine driver reprogrammed | |
93 | the FPGA with a custom circuit, the carrier is unable to access the | |
94 | EEPROM and returns ENOTSUPP. | |
95 | ||
96 | An alternative way to write the EEPROM is the mezzanine driver | |
97 | fmc-write-eeprom (See *note fmc-write-eeprom::), but the procedure is | |
98 | more complex. |