[Arm-netbook] defining the eoma68 eeprom usage

[luke.leighton]

hi aaron, thanks for joining in here.  most welcome.

On Sun, Nov 3, 2013 at 9:34 AM, Aaron J. Seigo <aseigo at kde.org> wrote:
> Hi...
>
> On the eoma68 spec it says:
>
> "The EEPROM MUST NOT be used for the storage of user data: it is reserved
> exclusively for EOMA-68."

 yes.  my concerns here are that the EEPROM would be overwritten by
user applications otherwise, potentially destroying the ability of CPU
Cards to identify the device.  as it is i'm concerned about the
possibility of android viruses resulting in the id info being
destroyed and ending up with mass product recalls.  if it wasn't for
the possibility of kernel upgrades breaking device-tree file format or
interoperability i would have said it has to be a one-time fusable
PROM [or at least there being a factory-install write protect on the
EEPROM].

 the hardware's not going to change, so why would the data
representing it change?

> My understanding from past threads on the matter is that currently the only
> specified usage for this by EOMA-68 is a product ID string + device node tree.

 there was some debate about whether device node trees *plural* would
be more appropriate - one per "thing".  e.g. "GPIO pin 5" would have
its own device-tree node describing what it was for.  "LCD" would have
its own device-node tree in lieu of most LCDs not properly supporting
EDID [and even when they do they often have totally false data] and so
on.

 the other possibility being considered was to turn that on its head
and define "purposes".  such as a "Reset" purpose, to which "GPIO5"
happens to be allocated.  and "display", to which "LCD" happens to be
allocated.  this would make more sense inasmuch as some hardware
devices will have e.g. DisplayLink USB-based screens, but then those
are USB and they're self-describing so are out-of-scope _anyway_.

> It would be most useful if there was a definition on the layout.

 indeed!  it's been very much a "we'll cross that bridge when we get
to it" thing - and that's almost time, now.

> *cough*

:)

> A defined data structure allowing for future expansion

 yes.  this can be something as simple as a bit field (i learned a
trick or two from microsoft and the DCE/RPC specification).  the trick
is describe "capabilities" rather than have "revision numbers" - how
can future hardware / software otherwise support interoperability?
i've been working with Ettus Research USRPs recently and their
hard-coded use of "revision numbers" for communications formats
between firmware and the libraries is a downgrade-upgrade nightmare.
so.  yes.  bit-field with "capabilities" where the last bit is
reserved for "yet more future expansion" a la escape-sequence.

> as well as vendor specific
> additions would be golden.

 ah.  right.  knowing partly the answer already [and thank you for
agreeing to join the list to discuss this!], i have to ask, for the
benefit of the list: what _kind_ of vendor-specific additions?
specific examples, general examples, doesn't matter.

 bear in mind that the EEPROM is only 32k in size, it's a $0.10 part,
and its main purpose is to store this critical missing identification
data that all the other EOMA68 buses don't need because they're
self-describing.

> A simple page based system would suffice afaics. Sth like:
>
> Address         Size                    Value
> ======  ===             ====
> 0x00            2                       Page identifier (defined by EOMA68 spec)
> 0x02            2                       Size of page data
> 0x06            val 0x02        Page data
>
> Page data would (obviously) be limited to a maximum 64k in size, but that
> really should not be an issue given the application (and given how much data
> you can read at a time via i2c_smbus calls). A checksum could be added
> to the page header if desired to verify the data read in, but that could also
> be left to the page specific data. I don’t think a checksum is needed for the
> device ID page, for instance.

  i recommend having at least one byte saying "capabilities", as the
first byte.  then you can read that first byte and go "oh.  bit {say}
5 is set!  that means we use the new-spangly-expanded-data-format"
which happens to be that you use 32-bit addressing not 16-bit for
example.  8th bit you set to be "escape sequence".

 then, yes!  you can set one of the bits as "there is a checksum".
another way to do this is to have a checksum "page".  hmm, so many
possibilities...


> Page identifiers would be things like: "0x01 Device ID".

 originally i was going to follow the principle of USB class : vendor.
 but now that i think about it this is best reserved for an actual
in-page piece of information.  so there would be "0x01 Device ID Page
Info" then a page with that type would have... oh you describe it
below already :)

> A simple, sequential page ordering would to make it easy to use a function
> lookup table to parse the data. Page 0x00 would be a special “there are no
> more pages” id.

 ... giving a simple linked list in effect.  yes.  like it.

> The page ID # space could be split in 2 between EOMA68 and vendor, giving
> 32768 possible page IDs to both (far more than necessary, but 1 byte isn’t
> enough, and i don’t see any benefit to trying to pack bytes together and bit
> twiddling on the software side to unpack them).

 true.

> this would have the nice
> characteristic of any page id with the high bit set to 1 would be a vendor
> page.

 ... but, again, before getting to that, i'd like to determine what
those vendor-specific applications are, and to discuss whether it's
appropriate to even have them.  given the potential risks of having
the hardware destroyed by user applications getting it wrong i'm
inclined very much towards the "absolutely not" end of the spectrum.

 i owned a Motorola A1200.  actually i owned two.  one of them was
already a brick (ebay purchase... *sigh*...)  in the end i worked out
what happened, after i had the phone switched off over a timezone
change.  basically when i powered the phone up after a prolonged
period of disuse, it tried to overwrite its own firmware, got it
wrong, and destroyed itself.  that was _two_ $300 costly bricks i
owned.  both of them out of warranty.

 so for safety, even _allowing_ vendors to write to the EEPROM is
something that i would like to see *actively* prevented.

 if vendors *really* want some non-volatile space, there's a couple of
options.  1) some NAND/NOR 2) a second EEPROM [with a different
address] 3) other [e.g. a proper crypto-chip].

 these I2C EEPROMs are only $0.10 to $0.15 so it's not a huge deal to
put a 2nd one down on any board.


> The device ID page data definition might look sth like:
>
> Size in Byte(s)         Value
> ==========              ======================
> 2                                       Device type (assigned centrally)
> 2                                       Device revision
> 4                                       Vendor ID (assigned centrally)
> 4                                       Product ID (vendor generated, registered centrally)
> N                                       Manufacturer cstring
> N                                       Product cstring
> N                                       Serial number cstring

 can i think of anything else here.... no i think you have it covered.
 the guiding principle here is the USB spec / consortium.  and the
linux kernel MACHINE_TYPE registry.


> A set of defined pages would be marked as REQUIRED and standard page IDs would
> be defined as well. I’d actually recommend this definition to be housed
> *outside* of the EOMA68 spec so that it can be used more broadly by the open
> hardware community (where such things seem non-existent) and to keep the
> EOMA68 spec from becoming too monstrous.

 yes.  2nd spec.  and separate registry.

> This approach would have a number of advantages imo:
>
> * quick access to any given page without lots of index overhead (just jump
> through the page headers)

 yep.

> * minimum size is self documenting: all REQUIRED pages (e.g. device ID page)
> become the minimum size for the EEPROM on the device

 yep.

> * It avoids (imho) stupid hard coded lengths;

 duh.

> it’s no longer 1985, even in the
> embedded world people and many/most of the products we’re working on have
> application class processors, and even the ones with “just” microcontrolers
> can do a hell of a lot such that hard coded page sizes just don’t make sense
> * It allows some vendor flexibility

 ... let's discuss this separately ok?

> I am willing to write a small C library that takes a well formed set of data,
> parses all the EOMA68 bits and offers nice API to access things like
> device ID data, keeping implementation details at arms length from
> applications. I could also provide a tool that takes a descriptor file in a
> human readable format and converts it into a proper EOMA68 packed structure to
> be written to an EEPROM.

 awesome!

> Obviously we need agreement on the above before I do
> this.

 yes.  my only main addition would be that "capabilities" field, as
well as asking you to come up with some reasonable argument as to why
the risk of vendors (or viruses) overwriting critical data should be
considered.

>
> Some additional semi-random notes from reading the EOMA68 spec regarding the
> EEPROM:
>
> In the "Start-up procedure” section, it gives the EEPROM address as  0xA2
> rather than 0x51. I would recommend not putting the address here, but rather
> dealing with all those details in the "Requirements for I2C” section and
> giving the EEPROM a proper name there (e.g. the RID EEPROM, for Required
> IDentification).

 ... ey good idea.

> In fact, I’d re-org that section entirely to be like:
>
> Required Interfaces
>         Rational for interface selections*
>         i2c
>                 The "Required IDentification” EEPROM
>         USB
>         SATA
>         ETHERNET
>         RGB/TTL
>
>
> * I would remove all mention of specific vendors here; this is a specification
> after all,

 true.

> so I’d kill the last para about All Winner and costing. I would
> also move each of the line items about the interfaces to the section on that
> interface
>
> Thoughts?

 register on elinux.org, knock yourself out.  it's a wiki after all :)
 let's see what happens.  i really appreciate someon else being
willing to contribute to the development process in such a large way
that helps make the spec "real".

l.