path: root/include/battery.h

/* 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_NOT_INIT = -1,
	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 display_charge;   /* Display charge in 10ths of a % (1000=100.0%) */
	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
#define BATT_FLAG_IMBALANCED_CELL		0x00000800
/* 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 manufacturer name.
 *
 * This can be overridden to return a chip or board custom string.
 *
 * @param dest		Destination buffer.
 * @param size		Length of destination buffer in chars.
 * @return non-zero if error.
 */
int get_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);

/**
 * Report the absolute difference between the highest and lowest cell voltage in
 * the battery pack, in millivolts.  On error or unimplemented, returns '0'.
 */
int battery_imbalance_mv(void);

/**
 * 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

/*
 * If remaining charge is more than x% of the full capacity, the
 * remaining charge is raised to the full capacity before it's
 * reported to the rest of the system.
 *
 * Some batteries don't update full capacity timely or don't update it
 * at all. On such systems, compensation is required to guarantee
 * the remaining charge will be equal to the full capacity eventually.
 *
 * On some systems, Rohm charger generates audio noise when the battery
 * is fully charged and AC is plugged. A workaround is to do charge-
 * discharge cycles between 93 and 100%. On such systems, compensation
 * was also applied to mask this cycle from users.
 *
 * This used to be done in ACPI, thus, all software components except EC
 * was seeing the compensated charge. Now we do it in EC. It has more
 * knowledge on the charger and the battery. So, it can perform more
 * granular and precise compensation.
 *
 * TODO: Currently, this is applied only to smart battery. Apply it to other
 *       battery drivers as needed.
 */
void battery_compensate_params(struct batt_params *batt);

#endif /* __CROS_EC_BATTERY_H */