FMC Identification
  ******************
  
  The FMC standard requires every compliant mezzanine to carry
  identification information in an I2C EEPROM.  The information must be
  laid out according to the "IPMI Platform Management FRU Information",
  where IPMI is a lie I'd better not expand, and FRU means "Field
  Replaceable Unit".
  
  The FRU information is an intricate unreadable binary blob that must
  live at offset 0 of the EEPROM, and typically extends for a few hundred
  bytes. The standard allows the application to use all the remaining
  storage area of the EEPROM as it wants.
  
  This chapter explains how to create your own EEPROM image and how to
  write it in your mezzanine, as well as how devices and drivers are
  paired at run time.  EEPROM programming uses tools that are part of this
  package and SDB (part of the fpga-config-space package).
  
  The first sections are only interesting for manufacturers who need to
  write the EEPROM. If you are just a software developer writing an FMC
  device or driver, you may jump straight to *note SDB Support::.
  
  
  Building the FRU Structure
  ==========================
  
  If you want to know the internals of the FRU structure and despair, you
  can retrieve the document from
  `http://download.intel.com/design/servers/ipmi/FRU1011.pdf' .  The
  standard is awful and difficult without reason, so we only support the
  minimum mandatory subset - we create a simple structure and parse it
  back at run time, but we are not able to either generate or parse more
  arcane features like non-english languages and 6-bit text.  If you need
  more items of the FRU standard for your boards, please submit patches.
  
  This package includes the Python script that Matthieu Cattin wrote to
  generate the FRU binary blob, based on an helper libipmi by Manohar
  Vanga and Matthieu himself.  I changed the test script to receive
  parameters from the command line or from the environment (the command
  line takes precedence)
  
  To make a long story short, in order to build a standard-compliant
  binary file to be burned in your EEPROM, you need the following items:
  
          Environment    Opt     Official Name          Default
  ---------------------------------------------------------------------
          FRU_VENDOR     -v      "Board Manufacturer"   fmc-example
          FRU_NAME       -n      "Board Product Name"   mezzanine
          FRU_SERIAL     -s      `Board Serial Number"  0001
          FRU_PART       -p      "Board Part Number"    sample-part
          FRU_OUTPUT     -o      not applicable         /dev/stdout
  
  The "Official Name" above is what you find in the FRU official
  documentation, chapter 11, page 7 ("Board Info Area Format").  The
  output option is used to save the generated binary to a specific file
  name instead of stdout.
  
  You can pass the items to the FRU generator either in the environment
  or on the command line.  This package has currently no support for
  specifying power consumption or such stuff, but I plan to add it as
  soon as I find some time for that.
  
  FIXME: consumption etc for FRU are here or in PTS?
  
  The following example creates a binary image for a specific board:
  
          ./tools/fru-generator -v CERN -n FmcAdc100m14b4cha \
                 -s HCCFFIA___-CR000003 -p EDA-02063-V5-0 > eeprom.bin
  
  The following example shows a script that builds several binary EEPROM
  images for a series of boards, changing the serial number for each of
  them. The script uses a mix of environment variables and command line
  options, and uses the same string patterns shown above.
  
          #!/bin/sh
  
          export FRU_VENDOR="CERN"
          export FRU_NAME="FmcAdc100m14b4cha"
          export FRU_PART="EDA-02063-V5-0"
  
          serial="HCCFFIA___-CR"
  
          for number in $(seq 1 50); do
             # build number-string "ns"
             ns="$(printf %06d $number)"
             ./fru-generator -s "${serial}${ns}" > eeprom-${ns}.bin
          done
  
  
  Using SDB-FS in the EEPROM
  ==========================
  
  If you want to use SDB as a filesystem in the EEPROM device within the
  mezzanine, you should create one such filesystem using gensdbfs, from
  the fpga-config-space package on OHWR.
  
  By using an SBD filesystem you can cluster several files in a single
  EEPROM, so both the host system and a soft-core running in the FPGA (if
  any) can access extra production-time information.
  
  We chose to use SDB as a storage filesystem because the format is very
  simple, and both the host system and the soft-core will likely already
  include support code for such format. The SDB library offered by the
  fpga-config-space is less than 1kB under LM32, so it proves quite up to
  the task.
  
  The SDB entry point (which acts as a directory listing) cannot live at
  offset zero in the flash device, because the FRU information must live
  there.  To avoid wasting precious storage space while still allowing
  for more-than-minimal FRU structures, the fmc.ko will look for the SDB
  record at address 256, 512 and 1024.
  
  In order to generate the complete EEPROM image you'll need a
  configuration file for gensdbfs: you tell the program where to place
  the sdb entry point, and you must force the FRU data file to be placed
  at the beginning of the storage device. If needed, you can also place
  other files at a special offset (we sometimes do it for backward
  compatibility with drivers we wrote before implementing SDB for flash
  memory).
  
  The directory tools/sdbfs of this package includes a well-commented
  example that you may want to use as a starting point (the comments are
  in the file called -SDB-CONFIG-).  Reading documentation for gensdbfs
  is a suggested first step anyways.
  
  This package (generic FMC bus support) only accesses two files in the
  EEPROM: the FRU information, at offset zero, with a suggested filename
  of IPMI-FRU and the short name for the mezzanine, in a file called
  name. The IPMI-FRU name is not mandatory, but a strongly suggested
  choice; the name filename is mandatory, because this is the preferred
  short name used by the FMC core.  For example, a name of "fdelay" may
  supplement a Product Name like "FmcDelay1ns4cha" - exactly as
  demonstrated in `tools/sdbfs'.
  
  Note: SDB access to flash memory is not yet supported, so the short
  name currently in use is just the "Product Name" FRU string.
  
  The example in tools/sdbfs includes an extra file, that is needed by
  the fine-delay driver, and must live at a known address of 0x1800.  By
  running gensdbfs on that directory you can output your binary EEPROM
  image (here below spusa$ is the shell prompt):
  
          spusa$ ../fru-generator -v CERN -n FmcDelay1ns4cha -s proto-0 \
                        -p EDA-02267-V3 > IPMI-FRU
          spusa$ ls -l
          total 16
          -rw-rw-r-- 1 rubini staff 975 Nov 19 18:08 --SDB-CONFIG--
          -rw-rw-r-- 1 rubini staff 216 Nov 19 18:13 IPMI-FRU
          -rw-rw-r-- 1 rubini staff  11 Nov 19 18:04 fd-calib
          -rw-rw-r-- 1 rubini staff   7 Nov 19 18:04 name
          spusa$ sudo gensdbfs . /lib/firmware/fdelay-eeprom.bin
          spusa$ sdb-read -l -e 0x100 /lib/firmware/fdelay-eeprom.bin
          /home/rubini/wip/sdbfs/userspace/sdb-read: listing format is to be defined
          46696c6544617461:2e202020  00000100-000018ff .
          46696c6544617461:6e616d65  00000200-00000206 name
          46696c6544617461:66642d63  00001800-000018ff fd-calib
          46696c6544617461:49504d49  00000000-000000d7 IPMI-FRU
          spusa$ ../fru-dump /lib/firmware/fdelay-eeprom.bin
          /lib/firmware/fdelay-eeprom.bin: manufacturer: CERN
          /lib/firmware/fdelay-eeprom.bin: product-name: FmcDelay1ns4cha
          /lib/firmware/fdelay-eeprom.bin: serial-number: proto-0
          /lib/firmware/fdelay-eeprom.bin: part-number: EDA-02267-V3
  
  As expected, the output file is both a proper sdbfs object and an IPMI
  FRU information blob. The fd-calib file lives at offset 0x1800 and is
  over-allocated to 256 bytes, according to the configuration file for
  gensdbfs.