[Openec] Announcing XO EC-1.75

[Richard A. Smith]

EC-1.75

OLPC is happy to announce the existence of a mostly [1] public code base 
for the embedded controller (EC) used on the XO 1.75.

For the impatient:

git clone git://dev.laptop.org/users/rsmith/ec-1.75

Before we talk about what EC-1.75 is and what you can do with it let's 
first talk about what it's not.

What it's not:

EC-1.75 is not OpenEC.

OpenEC [2] is an alternate EC codebase for XO-1 that was almost 
completely written by Frieder Ferlemann based on the datasheet for the 
KB3700 and bits of released information describing the XO-1 hardware. 
Although the code loads and runs on a XO-1 EC most of it is untested and 
the tree is currently unmaintained.  However, it blazed a path and 
served as a guideline for creating EC-1.75.  Many thanks to Frieder for 
his contribution.

[2] http://wiki.laptop.org/go/OpenEC

What it is:

EC-1.75 was derived from the existing (closed) OLPC EC code base with 
all code that was not copyright OLPC or Quanta removed.  The missing 
bits were then re-implemented for the EnE KB3930 in the 1.75 A1 
prototype and currently are being ported to the EnE IO3731 in the A2 
prototype.  EC-1.75 is licensed GPL + a special linking exception and 
all code is now copyright OLPC.  EC-1.75 is also targeted exclusively at 
the 1.75 A2 board and beyond. Although parts of the code base were 
created on Gen 1.5 machines and those branches exist in the tree there 
are currently no plans to continue developing those branches.

I mentioned that some of the original code carried a Quanta copyright. 
The new code now carries an OLPC copyright.  The original EC code was 
jointly developed by Quanta and OLPC, and our agreement gives both 
parties joint ownership of it.  We've used that base to create the new 
EC-1.75 code under a new OLPC copyright - Quanta jointly owns the code 
and could do the same sort of thing as well.  All code in the EC-1.75 
tree will continue to hold an OLPC copyright, so new authors must adhere 
to that practice.

We realize that copyright assignment to OLPC is not an optimal situation 
for accepting contributions from the community but doing it this way 
allowed us to open up the code while keeping the man-hours of 
enhancement and bug fixing work from the previous codebase.

Description of the branches in the EC-1.75 repository:

3700 :
     Early development code for XO-1.5.

3930-A1 :
     Port of codebase to the 1.75 A1 board.

3731 :
     Port of codebase to the 1.75 A2 board.

master :
     Mash-up of all the above branches + development head.  Since the 
hardware for A2 only became available last week, this
branch is changing frequently.

stable :
     Not really used right now since there isn't any stable code.


What it's good for:

Unless you have an XO 1.75 A2 board, not much.  A1 boards are now 
deprecated and will be removed from service as soon as A2 boards are 
distributed.  The KB3930 on the A1 boards will no longer be supported. 
As of this writing (Ver: 4_0.0.6) all major blocks of the EC on the A2 
board are up and running.  If you don't have a 1.75 it's still possible 
to play if you spend the time to backport the code from the master 
branch on to the 3700 branch and produce something that will work on a 
1.5.  The 1.5 can be programmed with an external SPI programmer so you 
don't have to worry about bricking the 1.5.  The result could then be 
pulled into OpenEC as a starting point for 1.5.  Email me if you are 
interested in undertaking that task.


Development requirements:

EC-1.75 A2 currently requires you to use the Keil (non-free) or SDCC 
(free) compiler.  The SDCC compiler currently generates an image that is 
too large to fit in the 32 KiB of flash space on the IO3731 EC chip, so 
we're using Keil. [3]  We hope to move back to SDCC (see below).
To program the EC code into an A2 you need a programmer that understands 
how to do the EnE EDI protocol.  OLPC uses external programmers with 
some custom software but OFW can also program the EC as long as the 
system is not bricked.


[1] Mostly open:

EnE, the manufacturer of the EC's, has requested that we not release 
information on various parts of the EC.  One of these parts is the PS/2 
interface which is used to talk to the keyboard and mouse.  Code that 
uses these parts is contained in a sub-module called "private" and is 
only accessible by parties that have signed the OLPC NDA agreement.  The 
special exception in the license allows linking against this private 
code without that code coming under the GPL.  On A1 boards and "as 
built" A2 boards these closed PS/2 interfaces are used.  A2 boards 
however, have the ability to route the keyboard and mouse data streams 
to the security processor on the the host SoC rather than the EC.  OLPC 
has code for the security processor that will bit-bang the PS/2 
protocol.  The main processor on the SoC can then read the keyboard and 
mouse data from the security processor rather than the EC.  This data 
path has not been fully implemented all the way to the Linux command 
line but soon after the A2 bring up dust settles it will be finished and 
undergo wider testing.  If it proves to be viable then the private code 
will be deprecated and eventually dropped from the tree.  We hope that 
removal of the PS/2 and keyboard/mouse code will bring the size back 
down to a point where an SDCC image will fit in the IO3731 and a fully 
open codebase + toolchain can be realized.

[3] Works as long as you can check out the private tree.  Compile fails 
if not.

Datasheets:

The public datasheet for the IO3731 is available here:

http://wiki.laptop.org/images/5/56/IO3731_v12_OLPC_20110117.pdf

This datasheet has the descriptions of the non-public interfaces removed.

Discussion:

Since the OpenEC mailing list already exists [4] I don't really see much 
value in creating a list thats specific to EC-1.75.  Any discussions are 
valuable to both code bases.  Therefore please see the OpenEC list if 
you want to follow the development of EC-1.75.  Questions on this 
announcement and simple questions or discussions are fine for devel at .l.o 
but please send things like patches or very detailed questions to the 
OpenEC list.

[4] http://lists.laptop.org/listinfo/openec

So, that's the plan -- right now we're using a non-free compiler (Keil) 
to build a mostly free (except for PS/2) EC for 1.75, but we're near to 
replacing the non-free compiler and the non-free PS/2 code at the same 
time.  As always, we welcome your help!

-- 
Richard A. Smith  <richard at laptop.org>
One Laptop per Child