About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / fmc / identifiers.txt


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.
Hide Line Numbers


About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog