Overview

PHYTEC's EEPROM Flashtool was designed to simplify the configuration of phyCORE-AM57x SoM variants. This is achieved by using the SoM's EEPROM device to store it's configuration, which is used at boot to configure the target's device tree binary, RAM settings, etc. accordingly. This allows OEMs to deploy a single image that supports multiple hardware targets.

This application note details the use of the PHYTEC EEPROM Flashtool with PHYTEC AM572x SOMs. The structure, content, and process for using the EEPROM data is described and examples of how PHYTEC uses the EEPROM data to facilitate hardware bring-up are provided.

If using BSP-Yocto-TISDK-AM57xx-PD18.1.0 pre-built images and your kernel build timestamp is older than:

"Linux version 4.9.41-ga962b18-BSP-Yocto-TISDK-AM57xx-PD18.1.0 (jenkins@jenkins1-build-machine) (gcc version 6.2.1 20161016 (Linaro GCC 6.2-2016.11) ) #1 SMP PREEMPT Thu Jan 25 20:39:40 PST 2018"

you must upgrade the PHYTEC EEPROM Flashtool on the target before following this guide. Click here to manually update the tool.


Configuration Files Format

The EEPROM Flashtool configuration files are text files comprised of sections, properties, and values. For this application note, we will use the PCM-057.ini configuration file to detail the function and population options of each section. A section is indicated by a set of square brackets that enclose the name of that section. A property and value pair in any given section is formed as 'property: value'. A general example is given below:

Example Flashtool configuration file structure
[section]
property0: value
property1: value
property2: vaule


Required Configuration File Sections:

In each required section below, a description of the section is given and its options follow.

PHYTEC
This section and all of the following properties are required for all configuration files to specify the basic configuration of the SOM and how to properly parse the rest of the configuration file.

  • i2c_bus: This is the I2C bus on which the EEPROM resides in decimal format.
  • i2c_dev: This is the I2C device ID for the EEPROM in hex format.
  • eeprom_offset: This is the offset at which the EEPROM data will be written. This should be set to zero for use with PHYTEC BSPs. Decimal format.
  • kit_options: This is the number of possible kit options for any given PHYTEC SOM. AM572x-based PHYTEC SOMs have nine kit options. Decimal format.

  • mod_version: This is the number associated with the module type (see table below). AM572x-based PHYTEC SOMs are of the PCM type. Decimal format.

    Module TypeValue
    PCM0
    PFL1
    PCA2

Kit
This section is required for all configuration files to specify the names of the kit options for each given configuration file. The number of properties in this section should match the number specified in the kit_options property of the PHYTEC section above. Each property in this section must be a number that corresponds to the zero-based index of the kit options specified by the BOM. The value for each property corresponds to the plain-text name for a kit option. Kit options and their value pair for AM572x-based PHYTEC SOMs are listed in the table below.

Kit Option Index (property)Kit Option Name (value)

0

DDR
1ECC
2eMMC/NAND
3SPI
4Controller Type
5EEPROM
6Ethernet
7RTC
8Temperature

Known

This section is required for all configuration files to specify the known (and allowed) kit options and BOM revisions to be used with the EEPROM Flashtool. Each property in this section is a string that represents a set of kit options and the value for each property represents the maximum known BOM revision for that set of kit options. A property in this section can be a KSP number, such as KSP01, but the following KSP section must be populated with the same KSP number or the EEPROM Flashtool will fail.

KSP

This section is required for all configuration files that have KSP properties in the above Known section. Each property in this section is a string that corresponds to the KSP number and the value for each property is a string that represents the kit options for the KSP. The value for all properties in this section should exactly match with a property in the Known section.

Kit-specific Configuration File Sections:

One section must be added to the configuration file for each entry in the above Kit section. An added section name must exactly match the value of a property in the Kit section. Each kit-specific configuration file section will describe the kits listed in the 'Kits' section.

EEPROM Data Layout

The PHYTEC EEPROM data layout is a 32-byte structure located at offset 0 on the EEPROM. The following table details each entry in the structure for the PHYTEC AM572x SOM EEPROM layout.

ByteNameDescription
1-4headerPHYTEC EEPROM header. Unsigned 4-byte integer.
5api_versionPHYTEC EEPROM layout API version. Unsigned 1-byte integer.
6mod_version0: PCM, 1: PFL, 2: PCA. Unsigned 1-byte integer.
7som_pcb_revisionPHYTEC SOM PCB revision. Unsigned 1-byte integer.
8-13macMAC ID for primary ethernet port. Six unsigned 1-byte hex values.
14ksp0: No KSP, 1: KSP, 2: KSM. Unsigned 1-byte integer.
15kspnoNumber for KSP/KSM module. Unsigned 1-byte integer.
16-26kit_optSet of kit options. For the AM572x, this is an 11-character ASCII string with no null termination.
27-31reservedReserved bytes that may be utilized by customers or by PHYTEC in a newer PHYTEC EEPROM API version.
32bsThe number of bits set in all of the preceding bytes. Unsigned 1-byte integer.

If you would like to utilize the reserved space for your own identification purposes, feel free to do so but be aware that the PHYTEC EEPROM Layout API may change in the future. Additionally, the PHYTEC EEPROM Flashtool will need to be modified to accommodate the reading, writing, and display of this new data.

Using the EEPROM Flashtool

If you are working with a custom SOM or a SOM with an EEPROM that hasn't been programmed, you will want to flash your EEPROM using the EEPROM Flashtool. This section will detail where the EEPROM Flashtool and default configuration files are located and how to properly use the tool.

If you need guidance on booting into Linux on your board, please refer to the latest Yocto BSP Quickstart listed here.

In the PHYTEC Linux BSP filesystem, the EEPROM Flashtool is located in /usr/bin/phytec-eeprom-flashtool/ and its configuration files are located in /usr/bin/phytec-eeprom-flashtool/configs/. By default, the EEPROM Flashtool directory is not present in the root user's path. Run the following command to add the EEPROM Flashtool directory to your path:

export PATH=/usr/bin/phytec-eeprom-flashtool:$PATH

The use of the EEPROM Flashtool is simple. From the README:

Use of this tool requires a properly-formatted configuration file for each
target PHYTEC platform (PCM-057.ini for PCM-057 boards, for example).
By default, this tool looks for configuration files in a 'configs' subdirectory
to where the script is currently located.

Usage:

	phytec_eeprom_flashtool.py [(-d|--dir) DIR] <command>

	-d or --dir <DIR> overrides the config directory (relative or absolute)

Commands:

	read <SOM>

	Description:
	Read command reads the EEPROM and prints the EEPROM contents and kit
	options described by the <SOM>.ini file.

	display <BOM> <PCB revision>

	Description:
	Display command parses the kit options, BOM revision, and PCB revision
	and prints the resulting EEPROM contents without writing to the EEPROM.
	This command is intended as a "dry run" for the write command.

	write <BOM> <PCB revision>

	Description:
	Write command parses the kit options, BOM revision, and PCB revision
	and writes them to the EEPROM.

Examples:

	phytec_eeprom_flashtool.py read PCM-057

	phytec_eeprom_flashtool.py display PCM-057-40201111I.A0 3

	phytec_eeprom_flashtool.py write PCM-057-KSP01.A2 4

PCB revision

Supported SoM PCB revisions can be found in the BSP's Release Notes.

In the above examples, the read, display, and write commands all look to the configuration file specified by the SOM argument or the first seven characters of the BOM argument. This configuration file is PCM-057.ini for the above examples because of the given arguments. This configuration file may be edited to suit your needs, or a new configuration file may be created by referring to the Configuration Files Format section and then used by modifying the example commands.

Using the EEPROM Data

Once the EEPROM has been programmed with the correct options for your SOM using the EEPROM Flashtool, you may use the stored data to configure the board as you see fit. Currently, PHYTEC uses the EEPROM data to configure the RAM size and timings, whether ECC support is enabled, and to set the board name. Examples of the use of the EEPROM data can be found in the uboot-phytec Git repo. The following links will provide relevant commits for reference:

Getting the Script

PHYTEC's EEPROM Flashtool script can be downloaded at the following address:

https://stash.phytec.com/scm/pub/phytec-eeprom-flashtool.git

Download the EEPROM Flashtool on Target
udhcpc -i eth0
rm -rf /usr/bin/phytec-eeprom-flashtool
git clone https://stash.phytec.com/scm/pub/phytec-eeprom-flashtool.git /usr/bin/phytec-eeprom-flashtool -b v1.01.00
Download the EEPROM Flashtool on Host
sudo rm -rf /media/<user>/rootfs/usr/bin/phytec-eeprom-flashtool
sudo git clone https://stash.phytec.com/scm/pub/phytec-eeprom-flashtool.git /media/<user>/rootfs/usr/bin/phytec-eeprom-flashtool -b v1.01.00