Documentation/fmc/identifiers.txt - linux - Git at Google

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