1FMC Identification
   4The FMC standard requires every compliant mezzanine to carry
   5identification information in an I2C EEPROM.  The information must be
   6laid out according to the "IPMI Platform Management FRU Information",
   7where IPMI is a lie I'd better not expand, and FRU means "Field
   8Replaceable Unit".
  10The FRU information is an intricate unreadable binary blob that must
  11live at offset 0 of the EEPROM, and typically extends for a few hundred
  12bytes. The standard allows the application to use all the remaining
  13storage area of the EEPROM as it wants.
  15This chapter explains how to create your own EEPROM image and how to
  16write it in your mezzanine, as well as how devices and drivers are
  17paired at run time.  EEPROM programming uses tools that are part of this
  18package and SDB (part of the fpga-config-space package).
  20The first sections are only interesting for manufacturers who need to
  21write the EEPROM. If you are just a software developer writing an FMC
  22device or driver, you may jump straight to *note SDB Support::.
  25Building the FRU Structure
  28If you want to know the internals of the FRU structure and despair, you
  29can retrieve the document from
  30`' .  The
  31standard is awful and difficult without reason, so we only support the
  32minimum mandatory subset - we create a simple structure and parse it
  33back at run time, but we are not able to either generate or parse more
  34arcane features like non-english languages and 6-bit text.  If you need
  35more items of the FRU standard for your boards, please submit patches.
  37This package includes the Python script that Matthieu Cattin wrote to
  38generate the FRU binary blob, based on an helper libipmi by Manohar
  39Vanga and Matthieu himself.  I changed the test script to receive
  40parameters from the command line or from the environment (the command
  41line takes precedence)
  43To make a long story short, in order to build a standard-compliant
  44binary file to be burned in your EEPROM, you need the following items:
  46        Environment    Opt     Official Name          Default
  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
  54The "Official Name" above is what you find in the FRU official
  55documentation, chapter 11, page 7 ("Board Info Area Format").  The
  56output option is used to save the generated binary to a specific file
  57name instead of stdout.
  59You can pass the items to the FRU generator either in the environment
  60or on the command line.  This package has currently no support for
  61specifying power consumption or such stuff, but I plan to add it as
  62soon as I find some time for that.
  64FIXME: consumption etc for FRU are here or in PTS?
  66The following example creates a binary image for a specific board:
  68        ./tools/fru-generator -v CERN -n FmcAdc100m14b4cha \
  69               -s HCCFFIA___-CR000003 -p EDA-02063-V5-0 > eeprom.bin
  71The following example shows a script that builds several binary EEPROM
  72images for a series of boards, changing the serial number for each of
  73them. The script uses a mix of environment variables and command line
  74options, and uses the same string patterns shown above.
  76        #!/bin/sh
  78        export FRU_VENDOR="CERN"
  79        export FRU_NAME="FmcAdc100m14b4cha"
  80        export FRU_PART="EDA-02063-V5-0"
  82        serial="HCCFFIA___-CR"
  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
  91Using SDB-FS in the EEPROM
  94If you want to use SDB as a filesystem in the EEPROM device within the
  95mezzanine, you should create one such filesystem using gensdbfs, from
  96the fpga-config-space package on OHWR.
  98By using an SBD filesystem you can cluster several files in a single
  99EEPROM, so both the host system and a soft-core running in the FPGA (if
 100any) can access extra production-time information.
 102We chose to use SDB as a storage filesystem because the format is very
 103simple, and both the host system and the soft-core will likely already
 104include support code for such format. The SDB library offered by the
 105fpga-config-space is less than 1kB under LM32, so it proves quite up to
 106the task.
 108The SDB entry point (which acts as a directory listing) cannot live at
 109offset zero in the flash device, because the FRU information must live
 110there.  To avoid wasting precious storage space while still allowing
 111for more-than-minimal FRU structures, the fmc.ko will look for the SDB
 112record at address 256, 512 and 1024.
 114In order to generate the complete EEPROM image you'll need a
 115configuration file for gensdbfs: you tell the program where to place
 116the sdb entry point, and you must force the FRU data file to be placed
 117at the beginning of the storage device. If needed, you can also place
 118other files at a special offset (we sometimes do it for backward
 119compatibility with drivers we wrote before implementing SDB for flash
 122The directory tools/sdbfs of this package includes a well-commented
 123example that you may want to use as a starting point (the comments are
 124in the file called -SDB-CONFIG-).  Reading documentation for gensdbfs
 125is a suggested first step anyways.
 127This package (generic FMC bus support) only accesses two files in the
 128EEPROM: the FRU information, at offset zero, with a suggested filename
 129of IPMI-FRU and the short name for the mezzanine, in a file called
 130name. The IPMI-FRU name is not mandatory, but a strongly suggested
 131choice; the name filename is mandatory, because this is the preferred
 132short name used by the FMC core.  For example, a name of "fdelay" may
 133supplement a Product Name like "FmcDelay1ns4cha" - exactly as
 134demonstrated in `tools/sdbfs'.
 136Note: SDB access to flash memory is not yet supported, so the short
 137name currently in use is just the "Product Name" FRU string.
 139The example in tools/sdbfs includes an extra file, that is needed by
 140the fine-delay driver, and must live at a known address of 0x1800.  By
 141running gensdbfs on that directory you can output your binary EEPROM
 142image (here below spusa$ is the shell prompt):
 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
 165As expected, the output file is both a proper sdbfs object and an IPMI
 166FRU information blob. The fd-calib file lives at offset 0x1800 and is
 167over-allocated to 256 bytes, according to the configuration file for