Based on kernel version 4.16.1. Page generated on 2018-04-09 11:53 EST.
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.