]>
Commit | Line | Data |
---|---|---|
022c6747 AR |
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. |