1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
|
# Reflashing an ITE EC
This doc: [http://go/cros-ite-ec-reflash](https://goto.google.com/cros-ite-ec-reflash)
<br>
First written: 2019-04-02
<br>
Last updated: 2019-04-03
Familiarity with [Chromium OS](https://www.chromium.org/chromium-os) and
[Embedded Controller (EC)](../README.md) development is assumed.
[TOC]
## Background
### Terminology
**ITE EC** refers to the [ITE](http://www.ite.com.tw/)
[IT8320](http://www.ite.com.tw/en/product/view?mid=96)
[Embedded Controller (EC)](https://en.wikipedia.org/wiki/Embedded_controller)
microcontroller when used as a Chromium OS / Chrome OS EC.
**CrOS** refers to Chromium OS, Chrome OS, or both, depending on the context.
The distinction between Chromium OS and Chrome OS is largely immaterial to this
document.
**Servo** refers to a debug board providing direct debug access to various
circuits on a Chrome OS device motherboard. As of this writing, the most common
[servos](https://www.chromium.org/chromium-os/servo) used by CrOS developers are
[CR50 (CCD)](https://www.chromium.org/chromium-os/ccd),
[Servo Micro](https://www.chromium.org/chromium-os/servo/servomicro), and
[Servo v2](https://www.chromium.org/chromium-os/servo/servo-v2). (Note that
[Servo v4](https://www.chromium.org/chromium-os/servo/servov4) is **not** a
Servo in this sense. It is a USB hub with a microcontroller that proxies Servo
functionality from either CR50 or Servo Micro.) See also
[Case-Closed Debug in Chromebooks and Servo Micro](https://chromium.googlesource.com/chromiumos/platform/ec/+/HEAD/board/servo_micro/ccd.md).
### How ITE EC reflashing works
An ITE EC is reflashed using a Servo by:
1. Sending special non-I2C waveforms over its I2C clock and data lines, to
enable a debug mode / direct firmware update (DFU) mode.
1. Communicating with it using I2C, including transferring the actual EC image
over I2C. The ITE EC will only respond over I2C after receiving the special
waveforms.
### Further reading
* [ITE EC firmware reflashing via Servo: How it works](../docs/ite-ec-reflashing.md)
* Googlers, and Partners involved in ITE EC projects *only*:
[The State of ITE CrOS EC Reflashing](https://docs.google.com/document/d/1fs29eBvwKrOWYozLZXTg7ObwAO5dyM4Js2Vq301EwAU/preview)
* That document is not public, do not request access if you lack it.
## How to reflash
### Prerequisites for CR50 CCD
This section applies whether using CR50 CCD via
[Servo v4](https://www.chromium.org/chromium-os/servo/servov4) or
[SuzyQ aka SuzyQable](https://www.sparkfun.com/products/14746).
CR50 MP minimum firmware version: `0.3.15`
<br>
CR50 pre-PVT minimum firmware version: `0.4.15`
Googlers, to upgrade CR50 firmware if needed see
[How to use CCD on CR50](https://docs.google.com/document/d/1MqDAoBsmGTmrFi-WNOoC5R-UFeuQK37_9kaEdCFU8QE/preview).
That document is not public, do not request access if you lack it.
The CR50 CCD capabilities must be set to `always`. To achieve this:
1. Open CCD.
* root shell: `$ gsctool -o`
* CR50 console: `ccd open`
1. Reset CCD to `factory` mode.
* CR50 console: `ccd reset factory`
Reflashing with CR50 also requires the [i2c-pseudo kernel module](#i2c-pseudo),
unless using the [CR50 CCD sans servod](#ccd-sans-servod) alternative method.
### Prerequisites for Servo Micro
This section applies whether the
[Servo Micro](https://www.chromium.org/chromium-os/servo/servomicro) is
connected directly to your development host, or through a
[Servo v4](https://www.chromium.org/chromium-os/servo/servov4).
Servo Micro minimum firmware version: `servo_micro_v2.3.5`
To upgrade Servo Micro firmware if needed:
1. Enter the chroot.
* `$ cros_sdk`
1. Run servo_updater.
* `$ sudo servo_updater --board=servo_micro`
If that still results in too old of a firmware version, use `repo sync` and
`update_chroot` to update your CrOS development environment, then try again.
Reflashing with Servo Micro also requires the
[i2c-pseudo kernel module](#i2c-pseudo).
### Installing i2c-pseudo {#i2c-pseudo}
1. Install the `i2c-pseudo` Linux kernel module. (Do this **outside** of the
chroot!)
* `$ cd src/platform/ec/extra/i2c_pseudo`
* `$ ./install`
**NOTE**: You will need to restart servod after installation.
If the above fails, your system may be missing packages necessary for building
kernel modules. Consult your Linux distribution's documentation and support
forums. After installing any packages that might be missing, simply try the
install script again.
You will need to reinstall `i2c-pseudo` after each kernel upgrade.
There is an intention to
[upstream i2c-pseudo](https://issuetracker.google.com/129565355), though even if
accepted upstream, it may or may not become included with common Linux
distribution kernels.
### Common reflash instructions
These instructions apply when using any kind of Servo, including those with no
special prerequisites (such as
[Servo v2](https://www.chromium.org/chromium-os/servo/servo-v2) with its Yoshi
flex cable connected to the DUT).
1. Enter the chroot (for servod).
* `$ cros_sdk --no-ns-pid`
1. Start servod.
* `$ sudo servod --board=<servod_board_name>`
* For some boards the servod board name is different than the EC codebase
board name used below!
1. Enter the chroot (for flash_ec).
* `$ cros_sdk`
1. Build the EC image for your board.
* `$ cd ~/trunk/src/platform/ec`
* `$ board=<board_name>`
* `$ make -j BOARD="$board"`
1. Run flash_ec from the util directory.
* `$ util/flash_ec --board="$board" --image=build/"$board"/ec.bin`
## CR50 CCD sans servod alternative {#ccd-sans-servod}
This section applies whether using CR50 CCD via
[Servo v4](https://www.chromium.org/chromium-os/servo/servov4) or
[SuzyQ aka SuzyQable](https://www.sparkfun.com/products/14746).
When using CR50 CCD, it is possible to reflash without servod, which _must not_
be running when using this method.
1. Enter the chroot.
* `$ cros_sdk`
1. Build the EC image for your board.
* `$ cd ~/trunk/src/platform/ec`
* `$ board=<board_name>`
* `$ make -j BOARD="$board"`
1. Run iteflash from the build/\<board\>/util directory.
* `$ build/"$board"/util/iteflash --i2c-interface=ccd --i2c-mux
--send-waveform=1 --erase --write=build/"$board"/ec.bin`
WARNING: The `--i2c-mux` flag is only required for some ITE EC boards. For
boards without an I2C mux between CR50 and the EC, that flag _must not_ be
specified. (This is handled for you when using `flash_ec` + `servod` because the
latter has knowledge of which boards are expected to have the I2C mux.)
|
