Documentation/fmc/identifiers.txt

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