Documentation/fmc/fmc-write-eeprom.txt

   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
  12 The module takes the following measures:
  13
  14    * It accepts a `file=' argument (within /lib/firmware) and if no
  15      such argument is received, it doesn't write anything to EEPROM
  16      (i.e. there is no default file name).
  17
  18    * If the file name ends with `.bin' it is written verbatim starting
  19      at offset 0.
  20
  21    * If the file name ends with `.tlv' it is interpreted as
  22      type-length-value (i.e., it allows writev(2)-like operation).
  23
  24    * If the file name doesn't match any of the patterns above, it is
  25      ignored and no write is performed.
  26
  27    * Only cards listed with `busid=' are written to. If no busid is
  28      specified, no programming is done (and the probe function of the
  29      driver will fail).
  30
  31
  32 Each TLV tuple is formatted in this way: the header is 5 bytes,
  33 followed by data. The first byte is `w' for write, the next two bytes
  34 represent the address, in little-endian byte order, and the next two
  35 represent the data length, in little-endian order. The length does not
  36 include the header (it is the actual number of bytes to be written).
  37
  38 This is a real example: that writes 5 bytes at position 0x110:
  39
  40         spusa.root# od -t x1 -Ax /lib/firmware/try.tlv
  41         000000 77 10 01 05 00 30 31 32 33 34
  42         00000a
  43         spusa.root# insmod /tmp/fmc-write-eeprom.ko busid=0x0200 file=try.tlv
  44         [19983.391498] spec 0000:03:00.0: write 5 bytes at 0x0110
  45         [19983.414615] spec 0000:03:00.0: write_eeprom: success
  46
  47 Please note that you'll most likely want to use SDBFS to build your
  48 EEPROM image, at least if your mezzanines are being used in the White
  49 Rabbit environment. For this reason the TLV format is not expected to
  50 be used much and is not expected to be developed further.
  51
  52 If you want to try reflashing fake EEPROM devices, you can use the
  53 fmc-fakedev.ko module (see *note fmc-fakedev::).  Whenever you change
  54 the image starting at offset 0, it will deregister and register again
  55 after two seconds.  Please note, however, that if fmc-write-eeprom is
  56 still loaded, the system will associate it to the new device, which
  57 will be reprogrammed and thus will be unloaded after two seconds.  The
  58 following example removes the module after it reflashed fakedev the
  59 first time.
  60
  61      spusa.root# insmod fmc-fakedev.ko
  62         [   72.984733]  fake-fmc: Manufacturer: fake-vendor
  63         [   72.989434]  fake-fmc: Product name: fake-design-for-testing
  64         spusa.root# insmod fmc-write-eeprom.ko busid=0 file=fdelay-eeprom.bin; \
  65             rmmod fmc-write-eeprom
  66         [  130.874098]  fake-fmc: Matching a generic driver (no ID)
  67         [  130.887845]  fake-fmc: programming 6155 bytes
  68         [  130.894567]  fake-fmc: write_eeprom: success
  69         [  132.895794]  fake-fmc: Manufacturer: CERN
  70         [  132.899872]  fake-fmc: Product name: FmcDelay1ns4cha
  71
  72
  73 Writing to the EEPROM
  74 =====================
  75
  76 Once you have created a binary file for your EEPROM, you can write it
  77 to the storage medium using the fmc-write-eeprom (See *note
  78 fmc-write-eeprom::, while relying on a carrier driver.  The procedure
  79 here shown here uses the SPEC driver
  80 (`http://www.ohwr.org/projects/spec-sw').
  81
  82 The example assumes no driver is already loaded (actually, I unloaded
  83 them by hand as everything loads automatically at boot time after you
  84 installed the modules), and shows kernel messages together with
  85 commands. Here the prompt is spusa.root# and two SPEC cards are plugged
  86 in the system.
  87
  88      spusa.root# insmod fmc.ko
  89      spusa.root# insmod spec.ko
  90      [13972.382818] spec 0000:02:00.0:  probe for device 0002:0000
  91      [13972.392773] spec 0000:02:00.0: got file "fmc/spec-init.bin", 1484404 (0x16a674) bytes
  92      [13972.591388] spec 0000:02:00.0: FPGA programming successful
  93      [13972.883011] spec 0000:02:00.0: EEPROM has no FRU information
  94      [13972.888719] spec 0000:02:00.0: No device_id filled, using index
  95      [13972.894676] spec 0000:02:00.0: No mezzanine_name found
  96      [13972.899863] /home/rubini/wip/spec-sw/kernel/spec-gpio.c - spec_gpio_init
  97      [13972.906578] spec 0000:04:00.0:  probe for device 0004:0000
  98      [13972.916509] spec 0000:04:00.0: got file "fmc/spec-init.bin", 1484404 (0x16a674) bytes
  99      [13973.115096] spec 0000:04:00.0: FPGA programming successful
 100      [13973.401798] spec 0000:04:00.0: EEPROM has no FRU information
 101      [13973.407474] spec 0000:04:00.0: No device_id filled, using index
 102      [13973.413417] spec 0000:04:00.0: No mezzanine_name found
 103      [13973.418600] /home/rubini/wip/spec-sw/kernel/spec-gpio.c - spec_gpio_init
 104      spusa.root# ls /sys/bus/fmc/devices
 105      fmc-0000  fmc-0001
 106      spusa.root# insmod fmc-write-eeprom.ko busid=0x0200 file=fdelay-eeprom.bin
 107      [14103.966259] spec 0000:02:00.0: Matching an generic driver (no ID)
 108      [14103.975519] spec 0000:02:00.0: programming 6155 bytes
 109      [14126.373762] spec 0000:02:00.0: write_eeprom: success
 110      [14126.378770] spec 0000:04:00.0: Matching an generic driver (no ID)
 111      [14126.384903] spec 0000:04:00.0: fmc_write_eeprom: no filename given: not programming
 112      [14126.392600] fmc_write_eeprom: probe of fmc-0001 failed with error -2
 113
 114 Reading back the EEPROM
 115 =======================
 116
 117 In order to read back the binary content of the EEPROM of your
 118 mezzanine device, the bus creates a read-only sysfs file called eeprom
 119 for each mezzanine it knows about:
 120
 121    spusa.root# cd /sys/bus/fmc/devices; ls -l */eeprom
 122    -r--r--r-- 1 root root 8192 Apr  9 16:53 FmcDelay1ns4cha-f001/eeprom
 123    -r--r--r-- 1 root root 8192 Apr  9 17:19 fake-design-for-testing-f002/eeprom
 124    -r--r--r-- 1 root root 8192 Apr  9 17:19 fake-design-for-testing-f003/eeprom
 125    -r--r--r-- 1 root root 8192 Apr  9 17:19 fmc-f004/eeprom