OpenEC: Difference between revisions

From OLPC
Jump to navigation Jump to search
(added commented bootup message, other changes)
m (→‎Getting the source: Removed outdated online browsing URL.)
 
(11 intermediate revisions by 6 users not shown)
Line 1: Line 1:
{{Translations}}
= OpenEC firmware project =
{{Olpcboxtop|toptext=[[{{PAGENAME}}|Embedded Controller]]}}
{{OBX source dev|projects/openec}}
{{Olpcboxbottom}}


openec is an effort for an open implementation of the firmware on the [[Embedded_controller|EC]].
OpenEC is an effort for an open implementation of the firmware on the [[Embedded_controller|EC]].
It currently is in an early stage and only outputs/accepts data via a serial adapter [[http://wiki.laptop.org/go/Image:Serial_adapter.jpg]]
It currently (Sept. 2008) is in an early stage and only outputs/accepts data via a serial adapter [[http://wiki.laptop.org/go/Image:Serial_adapter.jpg]] and a terminal program.

and a terminal program.
Downloading openec to an XO '''might damage the XO''', please drop a note to the openec mailing list first.
Downloading OpenEC to an XO '''might damage the XO''', please drop a note to the openec mailing list first.


== Mailing List ==
== Mailing List ==
http://lists.laptop.org/listinfo/openec
http://lists.laptop.org/listinfo/openec

== Related Documentation ==

[[Media:KB3700-ds-01.pdf|ENE KB3700 Datasheet]]

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


== Getting the source ==
== Getting the source ==

The source is in the git repository [http://dev.laptop.org/git.do?p=projects/openec;a=summary OpenEC] and can be browsed online there.


To get this code onto your machine please change to a newly created directory and do:
To get this code onto your machine please change to a newly created directory and do:
git-clone git://dev.laptop.org/projects/openec
git clone http://dev.laptop.org/git/users/rsmith/ec-1.75

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 ==
== Tools for OpenEC ==


; git : source revision tool (recommended)
; git : source revision tool (recommended)
Line 41: Line 33:
; 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)
; 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.
; 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 ==
== Compiling on the host for the EC ==
Line 101: Line 92:
Reacts on Power button but does not power up the XO yet.
Reacts on Power button but does not power up the XO yet.


Status is tested on B1 but yet to be confirmed for others.
''Status is tested on B1 and B2, yet to confirm in newer versions of the XO.''
Confirmed for B2


== Boot message ==
== Boot message ==
Green on black lines as shown in a serial terminal program. Grey on black lines are comments.
''Green on black lines as shown in a serial terminal program. Grey on black lines are comments.''

<div style="background:black; color:green; white-space:pre"> <font face="Courier"><span style="color:grey">
<div style="background:black; color:green; white-space:pre"> <font face="Courier"><span style="color:grey">
Firmware revision, Mask revision, Stackpointer, Compile date:</span>openec 0.0.6p0 Mask(a0) ID(??) SP(43) Nov 19 2007 20:07:35
Firmware revision, Mask revision, Stackpointer, Compile date:</span>openec 0.0.6p0 Mask(a0) ID(??) SP(43) Nov 19 2007 20:07:35
Line 132: Line 123:
GPWUEL ff60: 00 00 00 00
GPWUEL ff60: 00 00 00 00
<br><span style="color:grey">Verbose dump of GPIO registers (including GPIO name, pin number, symbolic name, input/output value, pull-up or open drain configuration):</span>
<br><span style="color:grey">Verbose dump of GPIO registers (including GPIO name, pin number, symbolic name, input/output value, pull-up or open drain configuration):</span>

Name Pin EC_name I/O/P/D alt_input/alt_output
Name Pin EC_name I/O/P/D alt_input/alt_output
GPIO00(06) VR_ON# - - - - (?)(GA20)
GPIO00(06) VR_ON# - - - - (?)(GA20)
Line 180: Line 172:
GPIAd4(35) CVM - - - -
GPIAd4(35) CVM - - - -
GPIAd5(36) WAKEUP_EC - - - -
GPIAd5(36) WAKEUP_EC - - - -

<br><span style="color:grey">Dump of mcs51 data memory:</span>
<br><span style="color:grey">Dump of mcs51 data memory:</span>

DATA 00: 00 00 02 03 07 00 00 13
DATA 00: 00 00 02 03 07 00 00 13
DATA 08: 00 00 00 00 00 00 00 00
DATA 08: 00 00 00 00 00 00 00 00
Line 197: Line 191:
DATA 70: 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
DATA 78: 00 00 00 00 00 00 00 00

<br><span style="color:grey">Dump of mcs51 Special Function Registers:</span>
<br><span style="color:grey">Dump of mcs51 Special Function Registers:</span>

SFR 80: 01 45 82 3e e6 ea 31 00
SFR 80: 01 45 82 3e e6 ea 31 00
SFR 88: 00 00 00 00 00 00 0e 12
SFR 88: 00 00 00 00 00 00 0e 12
Line 214: Line 210:
SFR f0: 01 9a 9e a2 a6 aa ae b2
SFR f0: 01 9a 9e a2 a6 aa ae b2
SFR f8: 00 ba be c2 c6 ca ce d2
SFR f8: 00 ba be c2 c6 ca ce d2

<br><span style="color:grey">Status of the state-machines <em>before</em> reset (includes time, number of main loop iterations, etc.):</span>
<br><span style="color:grey">Status of the state-machines <em>before</em> reset (includes time, number of
main loop iterations, etc.):</span>

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

<br><span style="color:grey">Dump of manufacturing data:</span>
<br><span style="color:grey">Dump of manufacturing data:</span>

ww ""
ww ""
S# "TPCL10EN64600125"
S# "TPCL10EN64600125"
Line 229: Line 230:
SD "2006-11-17"
SD "2006-11-17"
New DS2756 E:31
New DS2756 E:31

<br><span style="color:grey">Serial number, voltage, current, charge and temperature of the battery back:</span>
<br><span style="color:grey">Serial number, voltage, current, charge and temperature of the battery back:</span>
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</font></div>
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</font></div>


== 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.

<div style="background:black; color:green; white-space:pre"><font face="Courier"><span style="color:grey">; set address within 64k:</span>

<span style="color:blue">m ffff<return></span>
<span style="color:grey">; set 64k page:</span>
<span style="color:blue">M 0e<return></span>
<span style="color:grey">; show topmost byte:</span>
<span style="color:blue"><return></span>
0effff: 77 w
<span style="color:grey">; show other bytes:</span>
<span style="color:blue">-</span>
0efffe: 77 w
<span style="color:blue">-</span>
0efffd: 00
</font></div>

=== 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'''.

<div style="background:black; color:green; white-space:pre"><font face="Courier"><span style="color:grey">; set address </span>

<span style="color:blue">m fc20<return></span>
<span style="color:grey">; setting bit 1 (WLAN led should light)</span>
<span style="color:blue">| 02<return></span>
<span style="color:grey">; clearing bit 1 (WLAN led should be off again)</span>
<span style="color:blue">& fd<return></span>
</font></div>


== Desired Features ==
== Desired Features ==
Line 236: Line 304:
* Failsafe code
* Failsafe code
* Easy debugging
* Easy debugging
* GCC compilable (nice to have).


== To Do ==
== To Do ==


* lots
* Find co-workers, lots

== Related Documentation ==

* [[Media:KB3700-ds-01.pdf|ENE KB3700 Datasheet]]
* [http://sdcc.sourceforge.net/doc/sdccman.pdf SDCC Manual]
* [[Embedded controller]]

* [http://lists.laptop.org/pipermail/devel/2008-May/014533.html Why the firmware wasn't open in the first place (see the end of the message)]


[[category:EC]]
[[category:EC]]
[[category:firmware]]
[[category:firmware]]
[[category:Software_development]]
[[category:Software development]]

Latest revision as of 14:12, 27 October 2010

  english | español HowTo [ID# 248121]  +/-  

OpenEC is an effort for an open implementation of the firmware on the EC. It currently (Sept. 2008) 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

Getting the source

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

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

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

Related Documentation