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
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
|
/* Copyright (c) 2013 The Chromium OS Authors. All rights reserved.
* Use of this source code is governed by a BSD-style license that can be
* found in the LICENSE file.
*
* Battery charging parameters and constraints
*/
#ifndef __CROS_EC_BATTERY_H
#define __CROS_EC_BATTERY_H
#include "common.h"
#include "host_command.h"
/* Battery index, only used with CONFIG_BATTERY_V2. */
enum battery_index {
BATT_IDX_INVALID = -1,
BATT_IDX_MAIN = 0,
BATT_IDX_BASE = 1,
};
#ifdef CONFIG_BATTERY_V2
extern struct ec_response_battery_static_info
battery_static[CONFIG_BATTERY_COUNT];
extern struct ec_response_battery_dynamic_info
battery_dynamic[CONFIG_BATTERY_COUNT];
#endif
/* Stop charge when charging and battery level >= this percentage */
#define BATTERY_LEVEL_FULL 100
/* Tell host we're charged when battery level >= this percentage */
#ifdef CONFIG_BATTERY_LEVEL_NEAR_FULL
#define BATTERY_LEVEL_NEAR_FULL CONFIG_BATTERY_LEVEL_NEAR_FULL
#else
#define BATTERY_LEVEL_NEAR_FULL 97
#endif
/*
* Send battery-low host event when discharging and battery level <= this level
*/
#define BATTERY_LEVEL_LOW 10
/*
* Send battery-critical host event when discharging and battery level <= this
* level.
*/
#define BATTERY_LEVEL_CRITICAL 5
/*
* Shut down main processor and/or hibernate EC when discharging and battery
* level < this level.
*/
#define BATTERY_LEVEL_SHUTDOWN 3
/*
* Sometimes we have hardware to detect battery present, sometimes we have to
* wait until we've been able to talk to the battery.
*/
enum battery_present {
BP_NO = 0,
BP_YES = 1,
BP_NOT_SURE,
};
enum battery_cutoff_states {
BATTERY_CUTOFF_STATE_NORMAL = 0,
BATTERY_CUTOFF_STATE_CUT_OFF,
BATTERY_CUTOFF_STATE_PENDING,
};
enum battery_disconnect_state {
BATTERY_DISCONNECTED = 0,
BATTERY_NOT_DISCONNECTED,
BATTERY_DISCONNECT_ERROR,
};
/* Battery parameters */
struct batt_params {
int temperature; /* Temperature in 0.1 K */
int state_of_charge; /* State of charge (percent, 0-100) */
int voltage; /* Battery voltage (mV) */
int current; /* Battery current (mA); negative=discharging */
int desired_voltage; /* Charging voltage desired by battery (mV) */
int desired_current; /* Charging current desired by battery (mA) */
int remaining_capacity; /* Remaining capacity in mAh */
int full_capacity; /* Capacity in mAh (might change occasionally) */
int status; /* Battery status */
enum battery_present is_present; /* Is the battery physically present */
int flags; /* Flags */
};
/*
* Provide a 1 minute average of the current and voltage on the battery.
* Does not check for flags or whether those values are bad readings.
* See driver/battery/[your_driver].h/c for details on implementation and
* how the average is calculated.
*/
int battery_get_avg_current(void); /* in mA */
int battery_get_avg_voltage(void); /* in mV */
/* Flags for batt_params */
/* Battery wants to be charged */
#define BATT_FLAG_WANT_CHARGE 0x00000001
/* Battery is responsive (talking to us via I2C) */
#define BATT_FLAG_RESPONSIVE 0x00000002
/* Bits to indicate which parameter(s) could not be read */
#define BATT_FLAG_BAD_TEMPERATURE 0x00000004
#define BATT_FLAG_BAD_STATE_OF_CHARGE 0x00000008
#define BATT_FLAG_BAD_VOLTAGE 0x00000010
#define BATT_FLAG_BAD_CURRENT 0x00000020
#define BATT_FLAG_BAD_DESIRED_VOLTAGE 0x00000040
#define BATT_FLAG_BAD_DESIRED_CURRENT 0x00000080
#define BATT_FLAG_BAD_REMAINING_CAPACITY 0x00000100
#define BATT_FLAG_BAD_FULL_CAPACITY 0x00000200
#define BATT_FLAG_BAD_STATUS 0x00000400
/* All of the above BATT_FLAG_BAD_* bits */
#define BATT_FLAG_BAD_ANY 0x000007fc
/* Battery constants */
struct battery_info {
/* Design voltage in mV */
int voltage_max;
int voltage_normal;
int voltage_min;
/* (TODO(chromium:756700): add desired_charging_current */
/* Pre-charge current in mA */
int precharge_current;
/* Working temperature ranges in degrees C */
int8_t start_charging_min_c;
int8_t start_charging_max_c;
int8_t charging_min_c;
int8_t charging_max_c;
int8_t discharging_min_c;
int8_t discharging_max_c;
};
/**
* Return vendor-provided battery constants.
*/
const struct battery_info *battery_get_info(void);
/**
* Get current battery parameters.
*
* Error conditions are reported via batt.flags.
*
* @param batt Destination for battery data
*/
void battery_get_params(struct batt_params *batt);
/**
* Modify battery parameters to match vendor charging profile.
*
* @param batt Battery parameters to modify
*/
void battery_override_params(struct batt_params *batt);
/**
* Check for presence of battery.
*
* @return Whether there is a battery attached or not, or if we can't tell.
*/
enum battery_present battery_is_present(void);
/**
* Check for physical presence of battery.
*
* @return Whether there is a battery physically present, but possibly
* in a disconnected or cut off state, or if we can't tell;
*/
enum battery_present battery_hw_present(void);
/**
* Check for battery initialization status.
*
* @return zero if not initialized.
*/
int board_battery_initialized(void);
/**
* Get battery mode.
*
* See MODE_* constants in battery_smart.h
*
* @param mode Destination for current mode.
* @return non-zero if error.
*/
int battery_get_mode(int *mode);
/**
* Read nominal voltage battery is designed to supply.
*
* @param voltage Destination for voltage in mW
* @return non-zero if error.
*/
int battery_design_voltage(int *voltage);
/**
* Read absolute state of charge.
*
* @param percent Destination for charge in percent
* @return non-zero if error.
*/
int battery_state_of_charge_abs(int *percent);
/**
* Read battery remaining capacity.
*
* @param capacity Destination for capacity in mAh
* @return non-zero if error.
*/
int battery_remaining_capacity(int *capacity);
/**
* Read battery full charge capacity.
*
* @param capacity Destination for capacity in mAh
* @return non-zero if error.
*/
int battery_full_charge_capacity(int *capacity);
/**
* Read the nominal capacity the battery is designed to supply when new.
*
* @param capacity Destination for capacity in mAh
* @return non-zero if error.
*/
int battery_design_capacity(int *capacity);
/**
* Read time in minutes left when discharging.
*
* @param capacity Destination for remaining time in minutes.
* @return non-zero if error.
*/
int battery_time_to_empty(int *minutes);
/**
* Read run time in minutes left when discharging.
*
* @param capacity Destination for remaining time in minutes.
* @return non-zero if error.
*/
int battery_run_time_to_empty(int *minutes);
/**
* Read time in minutes left to full capacity when charging.
*
* @param capacity Destination for remaining time in minutes.
* @return non-zero if error.
*/
int battery_time_to_full(int *minutes);
/**
* Calculate battery time in minutes, under an assumed current.
*
* @param rate Current to use for calculation, in mA.
* If > 0, calculates charging time; if < 0, calculates
* discharging time; 0 is invalid and sets minutes=0.
* @param minutes Destination for calculated time in minutes.
* @return non-zero if error.
*/
int battery_time_at_rate(int rate, int *minutes);
/**
* Read battery status.
*
* @param status Destination for status; see STATUS_* in battery_smart.h.
* @return non-zero if error.
*/
int battery_status(int *status);
/**
* Read battery charge cycle count.
*
* @param count Destination for count.
* @return non-zero if error.
*/
int battery_cycle_count(int *count);
/**
* Read battery serial number.
*
* @param serial Destination for serial number.
* @return non-zero if error.
*/
int battery_serial_number(int *serial);
/**
* Read manufacturer name.
*
* @param dest Destination buffer.
* @param size Length of destination buffer in chars.
* @return non-zero if error.
*/
int battery_manufacturer_name(char *dest, int size);
/**
* Read device name.
*
* @param dest Destination buffer.
* @param size Length of destination buffer in chars.
* @return non-zero if error.
*/
int battery_device_name(char *dest, int size);
/**
* Read battery type/chemistry.
*
* @param dest Destination buffer.
* @param size Length of destination buffer in chars.
* @return non-zero if error.
*/
int battery_device_chemistry(char *dest, int size);
/**
* Read device manufacture date.
*
* @param year Destination for year
* @param month Destination for month
* @param day Destination for day
* @return non-zero if error.
*/
int battery_manufacturer_date(int *year, int *month, int *day);
/**
* Call board-specific cut-off function.
*
* @return EC_RES_INVALID_COMMAND if the battery doesn't support.
*/
int board_cut_off_battery(void);
/**
* Return if the battery has been cut off.
*/
int battery_is_cut_off(void);
/**
* Read battery vendor parameter.
*
* Vendor parameter handlers are implemented in a board-specific battery.c
*
* @param param Parameter identifier.
* @param value Location to store retrieved value.
* @return non-zero if error.
*/
int battery_get_vendor_param(uint32_t param, uint32_t *value);
/**
* Write battery vendor parameter.
*
* Vendor parameter handlers are implemented in a board-specific battery.c
*
* @param param Parameter identifier.
* @param value Value to write to the battery.
* @return non-zero if error.
*/
int battery_set_vendor_param(uint32_t param, uint32_t value);
/**
* Wait for battery stable.
*
* @return non-zero if error.
*/
int battery_wait_for_stable(void);
/**
* Print all battery info for debugging purposes
*/
void print_battery_debug(void);
/**
* Get the disconnect state of the battery.
*/
enum battery_disconnect_state battery_get_disconnect_state(void);
#ifdef CONFIG_BATTERY_V2
/**
* Refresh battery information in host memory mapped region, if index is
* currently presented.
*/
void battery_memmap_refresh(enum battery_index index);
/**
* Set which index to present in host memory mapped region.
*/
void battery_memmap_set_index(enum battery_index index);
#endif /* CONFIG_BATTERY_V2 */
#ifdef CONFIG_CMD_I2C_STRESS_TEST_BATTERY
extern struct i2c_stress_test_dev battery_i2c_stress_test_dev;
#endif
#endif /* __CROS_EC_BATTERY_H */
|