cleanup: Battery header files and filenames

battery.h is the high-level interface.  battery_smart.h is the
low-level interface.  Most things don't need the low-level interface,
but were including smart_battery.h solely to get at battery.h.  Fixed
this.  Also merged battery_pack.h into battery.h, since it was odd to
split that data across multiple header files.  Tidied the function
comments in battery.h as well.

No functional changes, just renaming files and adding comments.

BUG=chrome-os-partner:18343
BRANCH=none
TEST=build all boards; pass unit tests

Change-Id: I5ef372f0a5f8f5f36e09a3a1ce24008685c1fd0d
Signed-off-by: Randall Spangler <rspangler@chromium.org>
Reviewed-on: https://chromium-review.googlesource.com/171967
Reviewed-by: Bill Richardson <wfrichar@chromium.org>

1 files changed, 250 insertions, 62 deletions

diff --git a/include/battery.h b/include/battery.h
index c5177d6cae..10d0b6dcd0 100644
--- a/include/battery.h
+++ b/include/battery.h
@@ -8,6 +8,8 @@
 #ifndef __CROS_EC_BATTERY_H
 #define __CROS_EC_BATTERY_H
 
+#include "common.h"
+
 /* Stop charge when charging and battery level >= this percentage */
 #define BATTERY_LEVEL_FULL		100
 
@@ -31,110 +33,296 @@
  */
 #define BATTERY_LEVEL_SHUTDOWN		  3
 
+/* 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) */
+	int desired_voltage;  /* Charging voltage desired by battery (mV) */
+	int desired_current;  /* Charging current desired by battery (mA) */
+};
+
+/* Working temperature ranges in degrees C */
+struct battery_temperature_ranges {
+	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;
+};
+extern const struct battery_temperature_ranges bat_temp_ranges;
+
+/* Battery constants */
+struct battery_info {
+	/* Design voltage in mV */
+	int voltage_max;
+	int voltage_normal;
+	int voltage_min;
+	/* Pre-charge current in mA */
+	int precharge_current;
+};
+
+/**
+ * Return vendor-provided battery constants.
+ */
+const struct battery_info *battery_get_info(void);
+
+/**
+ * Modify battery parameters to match vendor charging profile.
+ *
+ * @param batt		Battery parameters to modify
+ */
+void battery_vendor_params(struct batt_params *batt);
+
+/**
+ * Attempt communication with the battery.
+ *
+ * @return non-zero if the battery responds.
+ */
+int battery_is_connected(void);
+
+/**
+ * Get battery mode.
+ *
+ * See MODE_* constants in smart_battery.h
+ *
+ * @param mode		Destination for current mode.
+ * @return non-zero if error.
+ */
+int battery_get_mode(int *mode);
+
+/**
+ * Set battery mode.
+ *
+ * See MODE_* constants in smart_battery.h
+ *
+ * @param mode		New mode.
+ * @return non-zero if error.
+ */
+int battery_set_mode(int mode);
 
-/* Get/set battery mode */
-int battery_get_battery_mode(int *mode);
+/**
+ * Check if battery is reporting capacity in 10 mW units.
+ *
+ * @param val		Destination for capacity units; set zero if mAh or
+ *			non-zero if 10 mW.
+ * @return non-zero if error.
+ */
+int battery_is_in_10mw_mode(int *val);
 
-int battery_set_battery_mode(int mode);
+/**
+ * Set battery capacity units.
+ *
+ * @param enabled	Set mode to mAh (=0) or 10 mW (=1)
+ * @return non-zero if error.
+ */
+int battery_set_10mw_mode(int enabled);
 
-/* Read battery temperature
- * unit: 0.1 K
+/**
+ * Read battery temperature.
+ *
+ * @param deci_kelvin	Destination for battery temperature in units of 0.1 K
+ * @return non-zero if error.
  */
 int battery_temperature(int *deci_kelvin);
 
-/* Read battery voltage
- * unit: mV
+/**
+ * Read battery voltage.
+ *
+ * @param voltage	Destination for voltage in mW
+ * @return non-zero if error.
  */
 int battery_voltage(int *voltage);
 
-/* Relative state of charge in percent */
-int battery_state_of_charge(int *percent);
+/**
+ * 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);
 
-/* Absolute state of charge in percent */
-int battery_state_of_charge_abs(int *percent);
+/**
+ * Read charging voltage desired by battery.
+ *
+ * @param voltage	Destination for voltage in mV.
+ * @return non-zero if error.
+ */
+int battery_desired_voltage(int *voltage);
 
-/*
- * Set 'val' to non-zero if the battery is reporting capacity in 10mW.
- * Otherwise, in mAh.
+/**
+ * Read battery discharging current.
+ *
+ * @param current	Destination for discharge current in mA; negative
+ *			value indicates charging.
+ * @return non-zero if error.
  */
-int battery_is_in_10mw_mode(int *val);
+int battery_current(int *current);
 
-/* Set battery capacity mode to mAh(=0) or 10mW(=1). */
-int battery_set_10mw_mode(int enabled);
+/**
+ * Read averaged battery discharging current.
+ *
+ * @param current	Destination for discharge current in mA; negative
+ *			value indicates charging.
+ * @return non-zero if error.
+ */
+int battery_average_current(int *current);
 
-/*
- * Battery remaining capacity
- * unit: mAh or 10mW, depends on battery mode
+/**
+ * Read charging current desired by battery.
+ *
+ * @param current	Destination for current in mA.
+ * @return non-zero if error.
+ */
+int battery_desired_current(int *current);
+
+/**
+ * Read battery relative state of charge.
+ *
+ * @param percent	Destination for charge in percent
+ * @return non-zero if error.
+ */
+int battery_state_of_charge(int *percent);
+
+/**
+ * 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; units are mAh or 10 mW,
+ *			depending on battery_is_in_10mw_mode().
+ * @return non-zero if error.
  */
 int battery_remaining_capacity(int *capacity);
 
-/* Battery full charge capacity */
+/**
+ * Read battery full charge capacity.
+ *
+ * @param capacity	Destination for capacity; units are mAh or 10 mW,
+ *			depending on battery_is_in_10mw_mode().
+ * @return non-zero if error.
+ */
 int battery_full_charge_capacity(int *capacity);
 
-/* Time in minutes left when discharging */
+/**
+ * Read the nominal capacity the battery is designed to supply when new.
+ *
+ * @param capacity	Destination for capacity; units are mAh or 10 mW,
+ *			depending on battery_is_in_10mw_mode().
+ * @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);
 
-/* Time in minutes to full when charging */
+/**
+ * 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);
 
-/* The current battery desired to charge
- * unit: mA
+/**
+ * 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_desired_current(int *current);
+int battery_time_at_rate(int rate, int *minutes);
 
-/* The voltage battery desired to charge
- * unit: mV
+/**
+ * Check if battery allows charging.
+ *
+ * @param allowed	Non-zero if charging allowed; zero if not allowed.
+ * @return non-zero if error.
  */
-int battery_desired_voltage(int *voltage);
-
-/* Check if battery allows charging */
 int battery_charging_allowed(int *allowed);
 
-/* Read battery status */
+/**
+ * Read battery status.
+ *
+ * @param status	Destination for status; see STATUS_* in smart_battery.h.
+ * @return non-zero if error.
+ */
 int battery_status(int *status);
 
-/* Battery charge cycle count */
-int battery_cycle_count(int *count);
-
-/* Designed battery capacity
- * unit: mAh or 10mW depends on battery mode
+/**
+ * Read battery charge cycle count.
+ *
+ * @param count		Destination for count.
+ * @return non-zero if error.
  */
-int battery_design_capacity(int *capacity);
+int battery_cycle_count(int *count);
 
-/* Designed battery output voltage
- * unit: mV
+/**
+ * Read battery serial number.
+ *
+ * @param serial	Destination for serial number.
+ * @return non-zero if error.
  */
-int battery_design_voltage(int *voltage);
-
-/* Read serial number */
 int battery_serial_number(int *serial);
 
-/* Read manufacturer name */
-int battery_manufacturer_name(char *manufacturer_name, int buf_size);
-
-/* Read device name */
-int battery_device_name(char *device_name, int buf_size);
-
-/* Read battery type/chemistry */
-int battery_device_chemistry(char *device_chemistry, int buf_size);
+/**
+ * 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 battery discharging current
- * unit: mA
- * negative value: charging
+/**
+ * Read device name.
+ *
+ * @param dest		Destination buffer.
+ * @param size		Length of destination buffer in chars.
+ * @return non-zero if error.
  */
-int battery_current(int *current);
-int battery_average_current(int *current);
+int battery_device_name(char *dest, int size);
 
-/* Calculate battery time in minutes, under a charging rate
- * rate >  0: charging, negative time to full
- * rate <  0: discharging, positive time to empty
- * rate == 0: invalid input, time = 0
+/**
+ * Read battery type/chemistry.
+ *
+ * @param dest		Destination buffer.
+ * @param size		Length of destination buffer in chars.
+ * @return non-zero if error.
  */
-int battery_time_at_rate(int rate, int *minutes);
+int battery_device_chemistry(char *dest, int size);
 
-/* Read manufacturer date */
+/**
+ * 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);
 
 #endif /* __CROS_EC_BATTERY_H */