[Arm-netbook] identification eeprom: data layout

[Aaron J. Seigo]

hi all,

i’m going to try this again in a new thread and with hopefully more clarity. i 
mixed 4 related topics into one email last time and apparently that doesn’t 
work here, which is fine. i’ll try again and break this into dedicated threads 
for each so we can (hopefully) discuss each topic without distraction.

this email is about the layout of data on the EEPROM.

Purpose: 

Each chassis needs to ship chassis-specific information such as the vendor and 
device ID on the identification EEPROM. There must be a defined data structure 
for that information such that a bootloader/OS loaded on any given CPU card 
can read it out.


Goals:

* Appropriate for storage on an EEPROM (low overhead)
* Appropriate for access via i2c+smbus
* Can be use to store heterogeneous data. Already identified are:
	* Device and vendor ID
	* Device tree
* Reliable, within the first two constraints, it must involve as few hacks as 
possible and as many reasonable mechanisms for reliable usage
* Extensible, allowing for future expansion as necessary


Proposal:

To create a specification for the “device information data segment” (DIDS) to 
be referenced by the EOMA68 standard in relation to the data stored on the 
EOMA68 identification EEPROM.

Keeping it separate from the EOMA68 standard:

* keeps the EOMA68 spec concise
* allows other open hardware implementations to more easily consider adoption


Implementation:

The DIDS will consist of a single contiguous block of binary data. The IDS 
will be segmented into variable size pages, and the IDS will be prefaced with 
a header.

	Header 

The header will be 4 bytes in size with the following layout:

Byte         	Size                		Value
======          ===                     ====
0x00               2                       	Capabilities bytes
0x02               1                       	Checksum byte	
0x03               1                       	Reserved

The capabilities bytes are a bitfield. All bits are currently reserved for 
future usage and may only be assigned in future revisions of the EOMA68 
specification. An IDS for this version of the EOMA68 spec must contain the 
value 0x00

The checksum byte is the CRC-8 result of the IDS. (The CRC-8 algorithm must be 
referenced from the final specification to avoid any ambiguities.)

The final byte is reserved for future use.


	Pages

Other than the header, the remainder of the IDS will be divided into variable 
length pages. Each page starts with a header with the following format:

Byte             Size                Value
======      ===             	====
0x00            2                       Page identifier (defined by EOMA68 spec)
0x02            2                       Size of page data

The page identifier (PID) is used to detect the layout of the data in the page, 
and all PIDs up to and including 32768 are defined in the DIDS specification. 
Values above 32768 are reserved. 

The page data then follows directly after the header. The maximum size of page 
data is limited by the page size value contained in 2 bytes, or 64k. A page 
may consist of 0 bytes of data, which may be used in cases where the PID 
itself is sufficiently informative on its own.

The only page layout exception allowed is for the last, or terminal, page. The 
0x00 value is used to identify the terminal page, and the remaining 2 bytes 
are ignored and therefore may contain any values. The terminal page always has 
page size of zero, regardless of the value stored in the last 2 bytes.

Navigating between pages becomes an exercise in reading page headers, seeking 
to the end of the page (processing the contents along the way if desired) and 
repeating for the next page until the terminal page is encountered.

There is no page index. Variable length pages without an accompanying index 
means that it is not possible to seek directly to a given page; however given 
the relatively small size of the IDS, the small number of pages and that the 
headers allow skipping from page to page this is deemed acceptable. 

-- 
Aaron J. Seigo