| 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. |