The TOFE EEPROM format is heavily inspired by both the Raspberry Pi B+ Hat format and the USB2.0 specification. It is however designed to be more compact to facilitate usage of EEPROMs which are as small as only 128 bytes in size and operation on an 8-bit microprocessor.

Overall Structure

HEADER  <- EEPROM header (Required)

ATOM1 <- Designer ID

ATOM2 <- Manufacturer ID (Required)

ATOMn <- xxxx

FOOTER <- EEPROM footer (Required)

Header Format

Bytes

Type

Field Name

Field Value

Field Description

5

c_char * 5

magic

0x84 0x79 0x70 0x69 0x0

("TOFE\0" in ASCII)

Signature to identify this as a TOFE EEPROM

1

uint8

version

0x01

EEPROM data format version

1

uint8

atoms

X

Number of atoms in EEPROM

1

uint8

crc8

X

CRC-8 of complete data (including header), skipping the crc8 field.

4

uint32

len

X

Size of the TOFE data section which follows (including footer)

Footer Format

Bytes

Type

Field Name

Field Value

Field Description

5

c_char * 5

rmagic

0x0 0x69 0x70 0x79 0x84

("\0EFOT" in ASCII)

Signature to identify this as a TOFE EEPROM

Atom Layout

An atom consists of a header and body.

Bytes

Type

Field Name

Field Description

1

uint8

type

Type of the atom

(the high nibble is used to tell the atom format)

1

uint8

length

Atom data length

N

bytes

data

Data for the atom

Atom Types

Atoms should always be sorted by in the same order as this table.

0x0X == String Format

0x1X == URL Format

0x2X == Relative URL Format

0x3X == Expand Int Format

0x4X == License Format

0x5X == Size Offset Format

0x7X == Binary Blob Format

0xDX == Unique Format Atoms

  0xD1 == Comment About Atom

0xFX == Vendor Specific Format

Type

Atom Formats

Req

Uniq

Description

0x00

Invalid Atom

0xff

Invalid Atom

Product Identification Atoms

0x11

URL

No

No

Designer ID

0x12

URL

Yes

Yes

Manufacturer ID

0x13

URL

Yes

Yes

Product ID

0x01

String

xx

Yes

Product Version

0x02

String

No

Yes

Serial Number

0x03

String

No

Yes

Product Part Number / Code

Auxiliary Atoms

0x14

URL

No

No

Auxillary URL

PCB Related Atoms

0x21

RURL

No

Yes

PCB Repository URL

0x04

String

xx

Yes

PCB Revision

0x41

License

Yes

Yes

PCB License

0x31

Timestamp

No

Yes

PCB Production Batch ID

0x32

Timestamp

No

Yes

PCB Population Batch ID

Firmware Related Atoms

0x05

String

No

No

Firmware Description

0x22

RURL

No

No

Firmware Repository URL

0x06

String

No

No

Firmware Revision

0x42

License

No

No

Firmware License

0x33

Timestamp

No

No

Firmware Program Date

EEPROM Related Atoms

0x51

Size+Offset

No

No

EEPROM Size

0x52

Size+Offset

No

No

EEPROM Vendor reserved usage area.

0x53

Size+Offset

No

No

EEPROM TOFE

0x54

Size+Offset

No

No

EEPROM USER

0x55

Size+Offset

No

No

EEPROM GUID

0x56

Size+Offset

No

No

EEPROM HOLE

0x07

String

No

No

EEPROM Part Number

0x57

Size+Offset

No

No

EEPROM GUID "Write location" -- Write the board's GUID to this area.

Informational Atoms

0x23

RURL

No

No

Sample Code Repository URL

0x24

RURL

No

No

Documentation Site

0x07

String

No

No

Comment

0xDx

Unique Structure Atoms

0xD1

Comment On

No

No

Comment on another Atom

0xFx

Vendor Product Specific Atoms

0xF0

0xFE

?

?

?

Atoms reserved for vendor product specific usage. They should be determined by looking at the Product ID.

Either Product Version or PCB Revision value must be populated.

Atom Formats

0x0x - String Format

Bytes

Type

Field Name

Field Value Examples

Field Description

1

uint8

type

XX

1

uint8

len

Length of string

N

utf-8 bytes

str

numato

\xe2\x98\x83

A string

0x1x - URL Format

0x2x - Relative URL Format

Bytes

Type

Field Name

Field Value Examples

Field Description

1

uint8

type

XX

1

uint8

len

Length of string + 1

1

uint8

to

URL atom this is relative too

N

utf-8 bytes

str

numato

\xe2\x98\x83

A string

0x3x - Expand Int Format

Bytes

Type

Field Name

Field Value Examples

Field Description

1

uint8

type

XX

1

uint8

len

x

Number of bytes required to store the timestamp

x

uint8

data

0x4x - License Format

Bytes

Type

Field Name

Field Value Examples

Field Description

1

uint8

type

XX

1

uint8

crc8

XX

1

uint8

len

0x01

1

uint8 enum

license

def _l(li, ver):

  return li << 3 | ver

Invalid       = 0

# -

MIT           = _l(1, 1)

# -

BSD_simple    = _l(2, 1)

BSD_new       = _l(2, 2)

BSD_isc       = _l(2, 3)

# -

Apache_v2     = _l(3, 1)

# -

GPL_v2        = _l(4, 1)

GPL_v3        = _l(4, 2)

# -

LGPL_v21      = _l(5, 1)

LGPL_v3       = _l(5, 2)

# -

CC0_v1        = _l(6, 1)

# -

CC_BY_v10     = _l(7, 1)

CC_BY_v20     = _l(7, 2)

CC_BY_v25     = _l(7, 3)

CC_BY_v30     = _l(7, 4)

CC_BY_v40     = _l(7, 5)

# -

CC_BY_SA_v10  = _l(8, 1)

CC_BY_SA_v20  = _l(8, 2)

CC_BY_SA_v25  = _l(8, 3)

CC_BY_SA_v30  = _l(8, 4)

CC_BY_SA_v40  = _l(8, 5)

# -

TAPR_v10      = _l(9, 1)

# -

CERN_v11      = _l(10, 1)

CERN_v12      = _l(10, 2)

# -

Proprietary   = 0xff

0x5x - Size Offset Format

Bytes

Type

Field Name

Field Value Examples

Field Description

1

uint8

type

XX

1

uint8

crc8

XX

1

uint8

len

0x08

len == 0x2, then X == 1 byte, Y == uint8

len == 0x4, then X == 2 bytes, Y == uint16

len == 0x8, then X == 4 bytes, Y == uint32

X

uintY

offset

Offset into the EEPROM for area

X

uintY

size

Size of the area

0x6x - Binary Format

Bytes

Type

Field Name

Field Value Examples

Field Description

1

uint8

type

XX

2

uint16

len

Length of binary data + 4*2 +1

1

uint8

crc8

XX

4

c_char * 4

start identifier

The start identifier must not be found in the data bytes.

N

bytes

data

User data

4

c_char * 4

end

identifier

The end identifier string should be identical to the start identifier

0xD1 - Comment on Atom

Bytes

Type

Field Name

Field Value Examples

Field Description

1

uint8

type

XX

1

uint8

len

Length of string + 1

1

uint8

about

1

Atom this comment is about

N

utf-8 bytes

str

numato

\xe2\x98\x83

A string

Example EEPROMs

LowSpeedIO EEPROM

MilkyMist Board EEPROM

Other EEPROM formats


Bytes

Type

Field Name

Field Value Examples

Field Description

1

uint8

type

XX

1

uint8

count

XX

1

uint8

crc8

XX

1

uint8

len

Length of URL + 1

1

enum / bitfield

tld

0x00 - Invalid

0x01 - domain+'.com'

0x02 - domain+'.org'

… Full list here

0xfd - TLD included in url

0xfe -  is in UTF-8 and includes TLD

0xff - Invalid

Specifies a TLD to be inserted into the url field before the first slash or colon.

The root domain contains 1096 top-level domains, we only have space for 256, so 0xfd is reserved for including the TLD in the url field.

N

ASCII bytes or UTF-8 bytes

url

numato

hdmi2usb

hdmi2usb/tofe

test:80/hello

The url with the TLD removed.

Examples;

numato (with tld=0x01) -> https://numato.com

hdmi2usb (with tld=0xC) -> https://hdmi2usb.tv

hdmi2usb/tofe (with tld=0xC) -> https://hdmi2usb.tv/tofe

test:80/hello (with tld=0x5) -> https://test.info:80/hello

test.com/abc.html (with tld=0xfd) -> https://test.com/abc.html