path: root/zephyr/Kconfig.battery

# Copyright 2020 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.

menuconfig PLATFORM_EC_BATTERY
	bool "Battery support"
	select HAS_TASK_CHARGER
	help
	  Enables battery support on the board. Requires selection of a battery
	  and a charger IC.

	  If using I2C batteries, you must define I2C_PORT_BATTERY in your
	  board's i2c_map.h file so that the EC code will know which I2C
	  port the battery is on.

if PLATFORM_EC_BATTERY

choice "Battery select"
	prompt "Select the battery to use"
	help
	  Select the battery used on the board. If you are ensure, select the
	  smart battery option.

config PLATFORM_EC_BATTERY_SMART
	bool "Support a smart battery"
	depends on PLATFORM_EC_I2C
	help
	  Many batteries support the Smart Battery Specification and therefore
	  have common registers which can be accessed to control and monitor
	  the battery.

	  See here for the spec: http://sbs-forum.org/specs/sbdat110.pdf

endchoice

choice "Battery presence detection"
	prompt "Method to use to detect the battery"
	help
	  This selects the method to use to detect the presence of a battery.

	  Battery detection is important since it can be used to indicate that
	  the case is open, so security features can be disabled. It is also
	  useful to report to the user when the battery is missing, e.g. with
	  a desktop icon.

config PLATFORM_EC_BATTERY_PRESENT_CUSTOM
	bool "Call a board-provided function"
	help
	  Use this method to provide a board-provided battery_is_present()
	  function to determine whether the battery is currently present.
	  This should be implemented in the board code and can use any
	  reasonable method to detect the battery.

config PLATFORM_EC_BATTERY_PRESENT_GPIO
	bool "Check a GPIO"
	help
	  Use this method if a GPIO signals whether the battery is present. The
	  GPIO should read low if the battery is present, high if absent.

	  The GPIO is hard-coded to GPIO_BATT_PRES_ODL so you should define this
	  in the device tree and GPIO map. The convention is to use the signal
	  name from schematic as both the node name and label for the GPIO. For
	  example:

	    /* gpio.dts */
	    ec_batt_pres_odl {
	    	gpios = <&gpioe 5 GPIO_INPUT>;
	    	label = "EC_BATT_PRES_ODL";
	    };

	    /* gpio_map.h */
	    #define GPIO_BATT_PRES_ODL		NAMED_GPIO(ec_batt_pres_odl)

endchoice  # battery presence

config PLATFORM_EC_USE_BATTERY_DEVICE_CHEMISTRY
	bool "Provide information about battery chemistry"
	help
	  Enable this to specify the chemistry of the battery device. It is
	  only used for stress testing of reading the battery information over
	  I2C.

config PLATFORM_EC_BATTERY_DEVICE_CHEMISTRY
	string "Battery-device chemistry"
	depends on PLATFORM_EC_USE_BATTERY_DEVICE_CHEMISTRY
	help
	  Specify the battery chemistry for use with the I2C stress test.
	  The value provided here must match what is read from the real
	  battery. This is used in sb_i2c_test_read() to check that the battery
	  is returning the right information. If it is not, there might be
	  something wrong with the I2C implementation.

config PLATFORM_EC_I2C_VIRTUAL_BATTERY
	bool "I2C virtual battery"
	help
	  Enables driver for a virtual battery. It is used to minimalize I2C
	  traffic which is generated by the I2C_PASSTHRU host command.
	  The battery parameters, which are already cached in EC are used to
	  return desired data to host instead of issuing I2C transaction every
	  time.

choice "Charger select"
	prompt "Select the charger to use"
	help
	  Select the battery charger IC used on the board. Only one charger may
	  be selected.

config PLATFORM_EC_CHARGER_ISL9237
	bool "Use the ISL9237 charger"
	depends on PLATFORM_EC_I2C
	select PLATFORM_EC_CHARGER_NARROW_VDC
	select PLATFORM_EC_CHARGER_OTG_SUPPORTED
	help
	  Enables a driver for the ISL9237 VCD Battery Charger. This is a
	  digitally-configurable, buck-boost battery charger that supporting
	  Narrow Voltage Direct Charging (NVDC). It supports an input voltage
	  range of 3.2-23.4V and output of 2.4-13.8V. It provides an I2C
	  interface for configuration an provides a USB On-The-Go (OTG)
	  function for 2- and 3-cell battery applications.

config PLATFORM_EC_CHARGER_ISL9238
	bool "Use the ISL9238 charger"
	depends on PLATFORM_EC_I2C
	select PLATFORM_EC_CHARGER_NARROW_VDC
	select PLATFORM_EC_CHARGER_OTG_SUPPORTED
	help
	  Enables a driver for the ISL9238 VCD Battery Charger. This is a
	  digitally-configurable, buck-boost battery charger that supporting
	  Narrow Voltage Direct Charging (NVDC). It supports an input voltage
	  range of 3.2-23.4V and output of 2.4-18.3V. It provides an I2C
	  interface for configuration.

config PLATFORM_EC_CHARGER_ISL9238C
	bool "Use the ISL9238 Rev C charger"
	depends on PLATFORM_EC_I2C
	select PLATFORM_EC_CHARGER_NARROW_VDC
	select PLATFORM_EC_CHARGER_OTG_SUPPORTED
	help
	  Enable a driver for the ISL9238 Rev C VCD Battery Charger. This
	  is a digitally-configurable, buck-boost battery charger that
	  supporting Narrow Voltage Direct Charging (NVDC). It supports an input
	  voltage range of 3.2-23.4V and output of 2.4-18.3V. It provides an I2C
	  interface for configuration.

	  This option is separate from PLATFORM_EC_CHARGER_ISL9238 since there
	  is no way in software to distinguish between rev. A/B and rev. C.

config PLATFORM_EC_CHARGER_ISL9241
	bool "Use the ISL9241 charger"
	depends on PLATFORM_EC_I2C
	# Hardware based charge ramp is broken in the ISL9241 (b/169350714)
	select PLATFORM_EC_CHARGER_CHGRAMP_BROKEN
	help
	  Enables a driver for the ISL9241 VCD Battery Charger. This is a
	  digitally-configurable, buck-boost battery charger that can support
	  both Narrow Voltage Direct Charging (NVDC) and Hybrid Power Buck Boost
	  (HPBB/Bypass) charging and switch between the modes under firmware
	  control. It supports an input voltage range of 3.9-23.4V and output
	  of 3.9-18.3V. It provides an I2C interface for configuration.

config PLATFORM_EC_CHARGER_BQ25710
	bool "Use the BQ25710 charger"
	depends on PLATFORM_EC_I2C
	select PLATFORM_EC_CHARGER_NARROW_VDC
	help
	  Enables the driver for the TI BQ25710 battery charger
	  controller. This is a synchronous narrow voltage DC buck-boost
	  battery charger for one to four battery cell applications. A
	  wide range of input power sources are supported such as high
	  voltage USB-C power delivery.

config PLATFORM_EC_CHARGER_BQ25720
	bool "Use the BQ25720 charger"
	depends on PLATFORM_EC_I2C
	select PLATFORM_EC_CHARGER_NARROW_VDC
	help
	  Enables the driver for the TI BQ25720 battery charger
	  controller. This is a synchronous narrow voltage DC buck-boost
	  battery charger for one to four battery cell applications. A
	  wide range of input power sources are supported such as high
	  voltage USB-C power delivery.

endchoice  # "Charger select"

config PLATFORM_EC_CHARGER_DISCHARGE_ON_AC
	bool "Board supports discharge mode"
	help
	  Enable this if the board supports discharging the battery even when
	  AC power is present. This is used for testing. The function is
	  provided either by the charger or by custom code in the board.

if PLATFORM_EC_CHARGER_DISCHARGE_ON_AC

choice "Discharge control method"
	prompt "Select the method of controlling discharge"
	help
	  Select which method is provided to enable and disable the discharge
	  mode.

config PLATFORM_EC_CHARGER_DISCHARGE_ON_AC_CHARGER
	bool "Charger controls discharge mode"
	help
	  Enable this if the charger controls selection of discharge mode.
	  In this case the charger must provide a function:

	     int charger_discharge_on_ac(int enabled)

	  It should enable this feature if enabled is true, else disable it.
	  The function should return EC_SUCCESS

config PLATFORM_EC_CHARGER_DISCHARGE_ON_AC_CUSTOM
	bool "Custom control of discharge mode"
	help
	  Enable this if the discharge mode is controlled by a custom function.
	  This function is typically provided by the board implementation:

	     int board_discharge_on_ac(int enabled)

	  It should enable this feature if enabled is true, else disable it.
	  The function should return EC_SUCCESS

endchoice  # "Discharge control method"

endif  # PLATFORM_EC_CHARGER_DISCHARGE_ON_AC

config PLATFORM_EC_CHARGER_BQ25720_VSYS_TH2_CUSTOM
	bool "VSYS_TH2 override"
	depends on PLATFORM_EC_CHARGER_BQ25720
	help
	  Enable customizing the charger's VSYS_TH2 threshold.

config PLATFORM_EC_CHARGER_BQ25720_VSYS_TH2_DV
	int "VSYS threshold 2 in deci-volts"
	range 32 95
	default 32
	depends on PLATFORM_EC_CHARGER_BQ25720_VSYS_TH2_CUSTOM
	help
	  Sets the VSYS threshold 2 in deci volts. This is the first
	  threshold that will be encountered when VSYS droops, typically
	  due to high power demand from the main processor. The charger
	  chip reacts by asserting PROCHOT which the main processor uses
	  as an indication to throttle back and reduce power demand. The
	  charger chip uses default thresholds which may be low enough
	  to cause system instability. The default for 1S batteries is
	  3.2v and 5.9v for 2S or higher batteries.  The valid range is
	  3.2v - 3.9v for 1S and 3.2 - 9.5v for 2S or higher batteries.

config PLATFORM_EC_CHARGER_MAINTAIN_VBAT
	bool "Maintain VBAT voltage regardless of AC state"
	help
	  Leave the charger VBAT configured to battery-requested voltage under
	  all conditions, even when AC is not present. This may be necessary to
	  work around quirks of certain charger chips, such as the BD9995X.

config PLATFORM_EC_CHARGER_NARROW_VDC
	bool
	help
	  Select this if the charger uses a Narrow Voltage Direct Charging.
	  Narrow VDC (NVDC) reduces power loss by reducing the voltage range of
	  the VDC node. This reduction is accomplished by replacing the
	  battery-charger circuit with a system-charger voltage regulator, thus
	  narrowing the VDC range. This in turn enables DC/DC converter
	  optimisations in the system and allows the removal of the power-path
	  switch, saving additional power, board area, and cost.

	  This should be enabled by charger drivers which need it. It cannot
	  be set otherwise, even in prj.conf

config PLATFORM_EC_CHARGER_OTG_SUPPORTED
	bool
	help
	  Indicates that the charger supports an OTG (On-The-Go) function,
	  which allows supplying output power from the battery to a connected
	  device.

	  This should be enabled by charger drivers which support it. It cannot
	  be set otherwise, even in prj.conf

config PLATFORM_EC_CHARGER_OTG
	bool "Allow supplying output power from the battery"
	depends on PLATFORM_EC_CHARGER_OTG_SUPPORTED
	help
	  Enable charger's OTG functions, i.e. make it possible to supply
	  output power from the battery. This option is available if the
	  selected charger supports it.

config PLATFORM_EC_CHARGER_PROFILE_OVERRIDE
	bool "Override the charger profile"
	help
	  Select this if the charger should call battery_override_params() to
	  limit/correct the voltage and current requested by the battery pack
	  before acting on the request.

	  The board must provide this function:

	    void battery_override_params(struct batt_params *batt);

	  It may modify the parameters as needed.

config PLATFORM_EC_CHARGER_PSYS
	bool "Support system power-monitor (PSYS) function"
	help
	  Enable this to support monitoring of system power using the charger's
	  PSYS function. The charger provides an output which can be read
	  using an ADC channel on the EC.

config PLATFORM_EC_CHARGER_PSYS_READ
	bool "Allow reading PSYS (system power) value"
	depends on PLATFORM_EC_CHARGER_PSYS
	help
	  Enable support for reading the system-power value (PSYS). This
	  calls the function charger_get_system_power() which is provided
	  by the charger.

	  It also enables the "psys" console command.

	  Sample output:

	    PSYS from chg_adc: 456 mW

config PLATFORM_EC_CHARGER_SENSE_RESISTOR
	int "Value of the charge sense-resistor, in mOhms"
	help
	  The charge sense-resistor is used to detect the charge current to the
	  battery. Its value must be known for the calculation to be correct.
	  The value is typically around 10 mOhms.

config PLATFORM_EC_CHARGER_SENSE_RESISTOR_AC
	int "Value of the input sense-resistor, in mOhms"
	help
	  The input sense-resistor is used to detect the input current from the
	  external AC power supply. Its value must be known for the calculation
	  to be correct. The value is typically around 10 mOhms.

config PLATFORM_EC_BATTERY_FUEL_GAUGE
	bool "Board supplies battery info"
	help
	  The fuel gauge information is used to cut off the battery for shipping
	  mode and to check the charge/discharge FET status.  The battery
	  information is used to set voltage, current and temperature operating
	  limits for the battery.

config PLATFORM_EC_CHARGER_CHGRAMP_BROKEN
	bool
	help
	  This is selected if the charger's support for hardware-controlled
	  charge ramping is broken. In some cases the charger has problems
	  which make it unusable and we must fall back to software-controlled
	  charge ramping.

	  This should be enabled by charger drivers which need it. It cannot
	  be set otherwise, even in prj.conf

choice "Charge-ramp method"
	prompt "Select the charge-ramp method"
	help
	  Select the method used for ramping up charging of a battery. It is
	  preferred to use the hardware method if the charger chip can support
	  it. If not, software-controlled charging can be used, with a slight
	  increase in code size.

config PLATFORM_EC_CHARGE_RAMP_HW
	bool "Hardware-controlled charging"
	depends on !PLATFORM_EC_CHARGER_CHGRAMP_BROKEN
	help
	   Disables software control of ramping up charging. This is used when
	   the hardware has a a mechanism for ramping input current and
	   backing-off as needed.

config PLATFORM_EC_CHARGE_RAMP_SW
	bool "Software-controlled charging"
	select HAS_TASK_CHG_RAMP
	help
	  Enables ramping up charging from an external source to the maximum
	  available within the source's limits and taking into account the
	  current needs of the device. It handles the user plugging chargers in
	  and removing them.

endchoice  # "Charge-ramp method"

config PLATFORM_EC_CONSOLE_CMD_CHARGER_ADC_AMON_BMON
	bool "Console command: amonbmon"
	help
	  Enable the 'amonbmon' command. This shows the charger adapter-current
	  monitor (AMON) and battery-charging current monitor (BMON).

	     amonbmon a | b

config PLATFORM_EC_CONSOLE_CMD_CHGRAMP
	bool "Console command: chgramp"
	depends on PLATFORM_EC_CHARGE_RAMP_SW
	default y
	help
	  Enable the "chgramp" command. This shows the current state of the
	  chg_ramp task. It shows the state of each port and the current limit
	  for each port. The 'State' shown is from enum chg_ramp_state.

	  Chg Ramp:
	    State: 5
	    Min ICL: 2000
	    Active ICL: 2000
	    Port 0:
	      OC idx:0
	      OC 0: s-1 oc_det0 icl0
	      OC 1: s0 oc_det0 icl0
	      OC 2: s0 oc_det0 icl0
	    Port 1:
	      OC idx:0
	      OC 0: s-1 oc_det0 icl0
	      OC 1: s0 oc_det0 icl0
	      OC 2: s0 oc_det0 icl0

config PLATFORM_EC_BATTERY_CRITICAL_SHUTDOWN_CUT_OFF
	bool "Enable battery cut off on critical power level"
	help
	  If this option is enabled, the battery will enter cut-off
	  mode in case of critical power level.

config PLATFORM_EC_BATTERY_CHECK_CHARGE_TEMP_LIMITS
	bool "Monitor battery temperature while charging"
	help
	  Enable monitoring of battery temperature while charging and
	  stop charging if is outside of the safe range.

config PLATFORM_EC_BATTERY_CUT_OFF
	bool "Host/Console command: battery cut-off"
	help
	  Enables support for disconnecting the battery using the "cutoff"
	  console command and the EC_CMD_BATTERY_CUT_OFF host command.
	  Once defined, a board specific board_cut_off_battery() function
	  has to be provided.

config PLATFORM_EC_BATTERY_HW_PRESENT_CUSTOM
	bool "Hardware check of battery presence"
	help
	  Once defined, the charger will check a board specific function
	  battery_hw_present() for battery hw presence as an additional
	  condition to determine if power on is allowed for factory override,
	  where allowing booting of a bare board with no battery and no power
	  button press is required.

config PLATFORM_EC_BATTERY_REVIVE_DISCONNECT
	bool "Check battery disconnect state"
	help
	  Check for battery in disconnect state (similar to cut-off state).
	  If this battery is found to be in disconnect state, take it out of
	  this state by force-applying a charge current. Once defined,
	  a battery_get_disconnect_state() function has to be provided.

config PLATFORM_EC_BATTERY_MEASURE_IMBALANCE
	bool "Measure the battery cells imbalance"
	help
	  Smart battery driver should measure the voltage cell imbalance in the
	  battery pack.
	  This requires a battery driver capable of the measurement.
	  If enabled, the AP enabling may be prevented if battery is too
	  imbalanced.

config PLATFORM_EC_BATTERY_MAX_IMBALANCE_MV
	int "Max battery imbalance in millivolts"
	depends on PLATFORM_EC_BATTERY_MEASURE_IMBALANCE
	default 200
	help
	  Imbalanced battery packs in this situation appear to have balanced
	  charge very quickly after beginning the charging cycle, since dV/dQ
	  rapidly decreases as the cell is charged out of deep discharge.
	  Increasing the value of
	  CONFIG_PLATFORM_EC_CHARGER_MIN_BAT_PCT_IMBALANCED_POWER_ON will make a
	  system tolerant of larger values of
	  CONFIG_PLATFORM_EC_BATTERY_MAX_IMBALANCE_MV.

config PLATFORM_EC_CHARGER_MIN_BAT_PCT_IMBALANCED_POWER_ON
	int "Minimum battery percentage for power on with an imbalanced pack"
	depends on PLATFORM_EC_BATTERY_MEASURE_IMBALANCE
	default 5
	range 0 100
	help
	  If battery pack is in imbalanced state and current state of charge is
	  below this value, the AP won't be powered on.

config PLATFORM_EC_BATT_FULL_CHIPSET_OFF_INPUT_LIMIT_MV
	int "Voltage limit in mV when battery is full and AP is off"
	depends on PLATFORM_EC_USB_PE_SM && PLATFORM_EC_CHARGE_MANAGER
	default -1
	help
	  If set to a non-negative value, input voltage will be reduced to given
	  value when chipset is in S5/G3 state and battery is fully charged.
	  This condition is checked on chipset shutdown and startup, AC change
	  and battery SOC change.

endif # PLATFORM_EC_BATTERY