diff options
Diffstat (limited to 'Documentation/fmc/fmc-write-eeprom.txt')
| -rw-r--r-- | Documentation/fmc/fmc-write-eeprom.txt | 98 |
1 files changed, 98 insertions, 0 deletions
diff --git a/Documentation/fmc/fmc-write-eeprom.txt b/Documentation/fmc/fmc-write-eeprom.txt new file mode 100644 index 000000000..e0a971215 --- /dev/null +++ b/Documentation/fmc/fmc-write-eeprom.txt @@ -0,0 +1,98 @@ +fmc-write-eeprom +================ + +This module is designed to load a binary file from /lib/firmware and to +write it to the internal EEPROM of the mezzanine card. This driver uses +the `busid' generic parameter. + +Overwriting the EEPROM is not something you should do daily, and it is +expected to only happen during manufacturing. For this reason, the +module makes it unlikely for the random user to change a working EEPROM. + +However, since the EEPROM may include application-specific information +other than the identification, later versions of this packages added +write-support through sysfs. See *note Accessing the EEPROM::. + +To avoid damaging the EEPROM content, the module takes the following +measures: + + * It accepts a `file=' argument (within /lib/firmware) and if no + such argument is received, it doesn't write anything to EEPROM + (i.e. there is no default file name). + + * If the file name ends with `.bin' it is written verbatim starting + at offset 0. + + * If the file name ends with `.tlv' it is interpreted as + type-length-value (i.e., it allows writev(2)-like operation). + + * If the file name doesn't match any of the patterns above, it is + ignored and no write is performed. + + * Only cards listed with `busid=' are written to. If no busid is + specified, no programming is done (and the probe function of the + driver will fail). + + +Each TLV tuple is formatted in this way: the header is 5 bytes, +followed by data. The first byte is `w' for write, the next two bytes +represent the address, in little-endian byte order, and the next two +represent the data length, in little-endian order. The length does not +include the header (it is the actual number of bytes to be written). + +This is a real example: that writes 5 bytes at position 0x110: + + spusa.root# od -t x1 -Ax /lib/firmware/try.tlv + 000000 77 10 01 05 00 30 31 32 33 34 + 00000a + spusa.root# insmod /tmp/fmc-write-eeprom.ko busid=0x0200 file=try.tlv + [19983.391498] spec 0000:03:00.0: write 5 bytes at 0x0110 + [19983.414615] spec 0000:03:00.0: write_eeprom: success + +Please note that you'll most likely want to use SDBFS to build your +EEPROM image, at least if your mezzanines are being used in the White +Rabbit environment. For this reason the TLV format is not expected to +be used much and is not expected to be developed further. + +If you want to try reflashing fake EEPROM devices, you can use the +fmc-fakedev.ko module (see *note fmc-fakedev::). Whenever you change +the image starting at offset 0, it will deregister and register again +after two seconds. Please note, however, that if fmc-write-eeprom is +still loaded, the system will associate it to the new device, which +will be reprogrammed and thus will be unloaded after two seconds. The +following example removes the module after it reflashed fakedev the +first time. + + spusa.root# insmod fmc-fakedev.ko + [ 72.984733] fake-fmc: Manufacturer: fake-vendor + [ 72.989434] fake-fmc: Product name: fake-design-for-testing + spusa.root# insmod fmc-write-eeprom.ko busid=0 file=fdelay-eeprom.bin; \ + rmmod fmc-write-eeprom + [ 130.874098] fake-fmc: Matching a generic driver (no ID) + [ 130.887845] fake-fmc: programming 6155 bytes + [ 130.894567] fake-fmc: write_eeprom: success + [ 132.895794] fake-fmc: Manufacturer: CERN + [ 132.899872] fake-fmc: Product name: FmcDelay1ns4cha + + +Accessing the EEPROM +===================== + +The bus creates a sysfs binary file called eeprom for each mezzanine it +knows about: + + spusa.root# cd /sys/bus/fmc/devices; ls -l */eeprom + -r--r--r-- 1 root root 8192 Feb 21 12:30 FmcAdc100m14b4cha-0800/eeprom + -r--r--r-- 1 root root 8192 Feb 21 12:30 FmcDelay1ns4cha-0200/eeprom + -r--r--r-- 1 root root 8192 Feb 21 12:30 FmcDio5cha-0400/eeprom + +Everybody can read the files and the superuser can also modify it, but +the operation may on the carrier driver, if the carrier is unable to +access the I2C bus. For example, the spec driver can access the bus +only with its golden gateware: after a mezzanine driver reprogrammed +the FPGA with a custom circuit, the carrier is unable to access the +EEPROM and returns ENOTSUPP. + +An alternative way to write the EEPROM is the mezzanine driver +fmc-write-eeprom (See *note fmc-write-eeprom::), but the procedure is +more complex. |