OpenEC

OpenEC firmware project

Openec is an effort for an open implementation of the firmware on the EC. It currently is in an early stage and only outputs/accepts data via a serial adapter [[1]] and a terminal program. Downloading openec to an XO might damage the XO, please drop a note to the openec mailing list first.

Mailing List

http://lists.laptop.org/listinfo/openec

Related Documentation

ENE KB3700 Datasheet

http://sdcc.sourceforge.net/doc/sdccman.pdf

Getting the source

The source is in the git repository OpenEC and can be browsed online there.

To get this code onto your machine please change to a newly created directory and do:

git-clone git://dev.laptop.org/projects/openec

While using the git to get the sources is recommended you can also download a tar file of the source: http://dev.laptop.org/git?p=projects/openec;a=snapshot;h=HEAD

Tools for OpenEc

git

source revision tool (recommended)

sdcc

Compiler sdcc 2.7.0 or later (needed) http://sdcc.sf.net (Compiler which generates the binary for the EC)

gcc

Compiler (optional for openec) the source is currently also compilable with GCC

doxygen

Source documentation tool (optional), http://www.doxygen.org

LaTeX

text tool (optional), needed if a pdf version of the documentation should be generated. A html version of the source documentation can be generated without LaTeX

Srecord

srecord (needed), http://srecord.sf.net, handling of hex (etc.) files (Version 1.36)

Make

(needed), GNU make, should be there anyway.

D52

Disassembler (optional), http://www.8052.com/users/disasm/ , generates disassembled file openec.d52

Download software

spiflash.dic (needed), see http://lists.laptop.org/pipermail/openec/2007-August/000061.html . Forth software to download the EC firmware to the target. Be sure to backup the complete firmware (including manufacturing data) first

Hardware adapter

serial adapter (needed) http://wiki.laptop.org/go/Image:Serial_adapter.jpg Hardware adapter to download to target. Connects to CN24 and an RS232 null-modem cable (an additional oscillator is needed (66MHz(?) to CN24,Pin5)). Additional instructions are at SPI FLASH Recovery. (The instructions there address recovery of the complete flash)

Jumpers

2 jumpers for Recovery Mode jumper block (see above)

Null modem cable

(needed) to connect the serial adapter to a serial port

Serial port

(needed) Not all new PC and very few notebooks still have a serial port (an USB to serial adapter might be additionally needed then)

Terminal Software

minicom (recommended). Needed to see or capture debugging output. Parameters 115kBaud, 8N1, no handshake - other terminal programs can be used too.

Compiling on the host for the EC

If the necessary tools are installed it is a simple "make" inside the openec directory:

make

Listing files and a binary file currently named openec.do_not_use.bin are generated. (Intentionally no more details here about how to proceed:)

Compiling on the host for the host

Run make with an additional argument inside the openec directory:

make -f Makefile.gcc

you can then run

./openec.gcc | less

there. The EC specific hardware is not present on the host, so openec.gcc will be of limited use. Running openec.gcc on the host does not endanger the host:)

Files of the C implementation

adc.c        handle the ADC on the EC
battery.c    Skeleton for battery handling with the Embedded Controller (key) 
build.c      Keeps version related info
compiler.h   include file to allow compiling with SDCC and GCC
Doxyfile     Control file for Source Documentation tool Doxygen
ds2756.c     Handle Maxim/Dallas DS2756 battery fuel gauge IC
flash.c      access the flash on the EC (0x00000..0xFffff)
fs_entry.c   Trampoline for a bankswitching routine
idle.c       Idle mode
kb3700.h     header file for ENE KB3700 Keyboard Controler
led.c        handle LEDs
main.c       Skeleton for the Embedded Controller of the OLPC project
manufacturing.c  Access manufacturing data
Makefile.gcc Makefile for compiling with GCC
Makefile     SDCC Makefile
matrix_3x3.c Routines to handle 3x3 matrix within the OLPC project
monitor.c    Monitor program
openec.ctl   Control file for D52 disassembler    
port_0x6c.c  host communication routines for the EC of the OLPC
sfr_dump.c   dump register settings
sfr_rw.c     reading/writing mcs-51 sfr (special function registers)
states.c     Helps debugging state machines
temperature.c Temperature reading and interpolation
timer.c      Timer routines for the Embedded Controller of the OLPC project
uart.c       handle serial IO on the EC
unused_irq.c Safe IRQ stubs for unused IRQ
watchdog.c   Watchdog of the EC

Status

Timer IRQ functional, blinks LEDs, decodes cursor keys, uart functional, dumps registers outputs (ec-dump.fth like), outputs status of internal state machines, reads temperature sensor, reads and outputs manufacturing data (B1), actively uses idle mode, reads and outputs data of the one-wire battery fuel gauge IC. Includes a monitor program that allows to read/write xdata Special Function Registers. Reacts on Power button but does not power up the XO yet.

Status is tested on B1 and B2, yet to confirm in newer versions of the XO.

Boot message

Green on black lines as shown in a serial terminal program. Grey on black lines are comments.

Firmware revision, Mask revision, Stackpointer, Compile date:openec 0.0.6p0 Mask(a0) ID(??) SP(43) Nov 19 2007 20:07:35
Some version tags from manufacturing data: T# "20061113-B001" S# "TPCL10EN64600125"
Dump of xdata Special Function Registers: GPIOO fc00: 40 00 00 00 GPIOE fc10: 02 06 e0 00 08 00 GPIOD fc20: 01 10 e0 00 00 00 GPIOIN fc30: ff ff ff 03 ff f1 3f GPIOPU fc40: 00 20 e0 03 00 00 GPIOOD fc50: 00 00 e0 00 GPIOIE fc60: 80 20 00 0f f0 00 04 GPIOM fc70: 01 KBC fc80: 40 00 00 00 00 00 10 PWM fe00: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 GPT fe50: 08 00 00 00 00 00 00 00 01 47 WDT fe80: 03 00 32 00 6b 0c LPC fe90: 00 00 ff 2c a0 fd 00 80 00 62 00 00 00 00 00 00 SPI fea0: 00 00 00 00 00 64 34 00 00 00 00 00 00 00 00 00 PS2 fee0: 00 00 00 00 00 ef 0f EC ff00: a0 00 0f 90 00 00 00 00 00 80 80 00 2f 94 00 95 00 00 1f 11 00 07 3e 83 00 fe 00 00 00 00 37 00 GPWUEN ff30: 00 00 00 00 GPWUPF ff40: 00 00 20 0c GPWUPS ff50: 00 00 00 00 GPWUEL ff60: 00 00 00 00
Verbose dump of GPIO registers (including GPIO name, pin number, symbolic name, input/output value, pull-up or open drain configuration):

Name Pin EC_name I/O/P/D alt_input/alt_output GPIO00(06) VR_ON# - - - - (?)(GA20) GPIO01(09) WLAN_EN - 0 - - (?)(KBRST#) GPIO02(10) SWI# - - - - (?)(?) GPIO03(16) CLK_EC_LPC - - - - (PCICLK)(?) GPIO04(17) PCI_RST# - - - - (PCIRST#)(?) GPIO05(22) SCI# - - - - (?)(SCI#) GPIO06(23) TX - - - - (?) PWM0/E51_TXD GPIO07(24) RX/BAT_L0 1 - - - E51_RXD (PWM1/E51_CLK) GPIO08(25) EC_EAPD - - - - (?)(PWM2) GPIO09(26) LED_PWR# - 0 - - (?)(PWM3) GPIO0a(27) LED_CHG_R# - 0 - - (?)(PWM4) GPIO0b(28) WAKEUP - - - - (E51_TMR0)(?) GPIO0c(29) PWR_BUT# - - - - (E51_TMR1)(?) GPIO0d(30) ECRST# 1 - 1 - ECRST# (E51_TXD) GPIO0e(31) CHG - - - - (E51_INT0)(PLLCLK32) GPIO0f(32) CC0 - - - - (E51_INT1)(POR) GPIO10(37) WLAN WAKEUP - - - - (?)(?) GPIO11(43) KBSCLK - - - - (PSCLK1)(PSCLK1) GPIO12(44) KBSDAT - - - - (PSDAT1)(PSDAT1) GPIO13(45) TPCLK - - - - (PSCLK2)(PSCLK2) GPIO14(46) TPDAT - - - - (PSDAT2)(PSDAT2) GPIO15(47) KEY_OUT_3/ISP_CLK - 1 1 1 (TEST_CLK)(?) GPIO16(48) KEY_OUT_1/ISP_EN# - 1 1 1 (TP_CLK_TEST)(?) GPIO17(53) KEY_OUT_2 - 1 1 1 (TP_PLL_TEST)(CLK) GPIO18(54) MIC_AC/ISP_EN2# 1 - 1 - TP_ISP_MODE (CLK32MHz(8051)) GPIO19(55) EB_MODE 1 - 1 - TP_IO_TEST (CLK16MHz(peri)) GPIO1a(56) MAIN_ON 0 - - -  ? (CLK32MHz(WDT)) GPIO1b(57) SUS_ON 0 - - -  ? (?) GPIOe0(01) EC_WP# - - - - GPIOe1(02) CV_SET - - - - GPIOe2(03) DQ - - - - GPIOe3(04) LED_CHG_G# - 0 - - GPIOe4(17) KEY_IN_1 1 - - - GPIOe5(18) KEY_IN_2 1 - - - GPIOe6(19) KEY_IN_3 1 - - - GPIOe7(20) POWER_BUTTON# 1 - - - GPIOe8(33) BAT_L1 - - - - GPIOec(49) SPIWP# - - - - GPIOed(50) DCON_EN - - - - GPIOee(51) T188(B1,WLAN,41) - - - - GPIOef(52) ECPWRRQST - - - - GPIAd0(38) TEMP - - - - 00 GPIAd1(39) EC_ID - - - - 58 GPIAd2(40) ACIN 1 - - - fe GPIAd3(34) ISYS - - - - GPIAd4(35) CVM - - - - GPIAd5(36) WAKEUP_EC - - - -

Dump of mcs51 data memory:

DATA 00: 00 00 02 03 07 00 00 13 DATA 08: 00 00 00 00 00 00 00 00 DATA 10: 00 00 00 00 00 00 00 0d DATA 18: 19 26 32 3f 4b 58 00 00 DATA 20: c2 02 00 00 00 00 00 00 DATA 28: 00 00 00 00 00 00 00 00 DATA 30: 00 00 00 00 00 00 00 00 DATA 38: 00 00 00 35 50 fc 00 00 DATA 40: 00 00 61 03 44 e5 26 69 DATA 48: 31 2f 20 ab 01 30 ab 01 DATA 50: ab 01 ab 00 01 ab 00 00 DATA 58: 00 00 00 00 00 00 00 00 DATA 60: 00 00 00 00 00 00 00 00 DATA 68: 00 00 00 00 00 00 00 00 DATA 70: 00 00 00 00 00 00 00 00 DATA 78: 00 00 00 00 00 00 00 00

Dump of mcs51 Special Function Registers:

SFR 80: 01 45 82 3e e6 ea 31 00 SFR 88: 00 00 00 00 00 00 0e 12 SFR 90: 80 31 31 31 26 2a 2e 32 SFR 98: 50 00 00 8b 46 4a 4e 52 SFR a0: f4 5a 5e 62 66 6a 6e 72 SFR a8: 90 7a 7e 82 86 8a 8e 92 SFR b0: 80 9a 9e a2 a6 aa ae b2 SFR b8: 00 ba be c2 c6 ca ce d2 SFR c0: d6 da de e2 e6 ea ee f2 SFR c8: f6 fa fe 02 06 0a 0e 12 SFR d0: 00 1a 1e 22 26 2a 2e 32 SFR d8: 00 3a 3e 42 46 4a 4e 52 SFR e0: 2e 5a 5e 62 66 6a 6e 72 SFR e8: 00 7a 7e 82 86 8a 8e 92 SFR f0: 01 9a 9e a2 a6 aa ae b2 SFR f8: 00 ba be c2 c6 ca ce d2

Status of the state-machines before reset (includes time, number of main loop iterations, etc.):

time numb co ma po ba d3s ch wa 00a3 00a9 ee 00 ff ee 01 02 ee ff 000000 0000 00 00

Dump of manufacturing data:

ww "" S# "TPCL10EN64600125" P# "1CL1XZU0KDB" U# "146CE6AD-25BA-4711-9184-635FDF47CDFC" BV "Q2A42" F# "F6" T# "20061113-B001" TS "DOWNLOAD" SW "178-olpc-redhat-stream-development-jffs2.img" SD "2006-11-17" New DS2756 E:31

Serial number, voltage, current, charge and temperature of the battery back: Ser:6d2a00000000 U_raw:56d0 I_raw:fffd I_avg_raw:0000 Q_raw:fdf9 T_raw:1546 E:fb00 6667mV 0mA 0mA -216mAh

2125cC

Built-in monitor program

OpenEC includes a monitor program which allows to input/output data via the serial adapter connected to CN24. The commands of the monitor are subject to change.

? short list of the supported commands
b battery info (short)
B battery info (longer)
c temperature of the onboard sensor (celsius)
d dump mcs51 DATA and SFR memory
g dump xdata SFR (directly comparable to output of ec-dump.fth)
G dump GPIO SFR (human readable)
m set memory address (expects 2 or 4 hex digits
  (2 digits for DATA/SFR memory, 4 digits for xdata/code memory))
M set 64k memory page (expects 2 hex digits).
  Next 'm' will reset this again.
r reboot
s dump states
S dump states continuously (toggle ON/OFF)
w watchdog reset
+ increment address (and output contents of address)
- decrement address (and output contents of address)
= set content of address to (expects 2 hex digits)
  (Note: SFR and code memory is not written)
& bitwise and (expects 2 hex digits)
| bitwise or  (expects 2 hex digits)
<return> output contents of address

Monitor example: reading manufacturing data

The Manufacturing Data is located at 0x0effff and below. The monitor on the EC can be used to access the data.

; set address within 64k:

m ffff<return> ; set 64k page: M 0e<return> ; show topmost byte: <return> 0effff: 77 w ; show other bytes: - 0efffe: 77 w - 0efffd: 00

Monitor example: switching WLAN_EN

The voltage for the wlan module is switched by GPIO01 WLAN_EN. The module can be switched on/off with the monitor. Please double-check what you are doing. Switching SFR registers might damage the XO.

; set address

m fc20<return> ; setting bit 1 (WLAN led should light) | 02<return> ; clearing bit 1 (WLAN led should be off again) & fd<return>

Desired Features

• Failsafe code
• Easy debugging

To Do

• Find co-workers, lots

Inner Links

• Embedded controller
• Why the firmware wasn't open in the first place (see the end of the message)