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.