linux-kernel - Re: [PATCH v8 2/6] Documentation: power: Initial effort to document power

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives
Hash Suite: Windows password security audit tool. GUI, reports in PDF.
[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]
Date:   Tue, 24 Apr 2018 15:40:36 +0300
From:   Heikki Krogerus <heikki.krogerus@...ux.intel.com>
To:     Adam Thomson <Adam.Thomson.Opensource@...semi.com>
Cc:     Guenter Roeck <linux@...ck-us.net>,
        Greg Kroah-Hartman <gregkh@...uxfoundation.org>,
        Sebastian Reichel <sre@...nel.org>,
        Hans de Goede <hdegoede@...hat.com>, Jun Li <jun.li@....com>,
        linux-usb@...r.kernel.org, linux-pm@...r.kernel.org,
        linux-kernel@...r.kernel.org, support.opensource@...semi.com
Subject: Re: [PATCH v8 2/6] Documentation: power: Initial effort to document
 power_supply ABI

On Mon, Apr 23, 2018 at 03:10:57PM +0100, Adam Thomson wrote:
> This commit adds generic ABI information regarding power_supply
> properties. This is an initial attempt to try and align the usage
> of these properties between drivers. As part of this commit,
> common Battery and USB related properties have been listed.
> 
> Signed-off-by: Adam Thomson <Adam.Thomson.Opensource@...semi.com>

Thank you a lot for doing this Adam! FWIW:

Reviewed-by: Heikki Krogerus <heikki.krogerus@...ux.intel.com>

> ---
>  Documentation/ABI/testing/sysfs-class-power | 443 ++++++++++++++++++++++++++++
>  MAINTAINERS                                 |   1 +
>  2 files changed, 444 insertions(+)
> 
> diff --git a/Documentation/ABI/testing/sysfs-class-power b/Documentation/ABI/testing/sysfs-class-power
> index f85ce9e..e046566 100644
> --- a/Documentation/ABI/testing/sysfs-class-power
> +++ b/Documentation/ABI/testing/sysfs-class-power
> @@ -1,3 +1,446 @@
> +===== General Properties =====
> +
> +What:		/sys/class/power_supply/<supply_name>/manufacturer
> +Date:		May 2007
> +Contact:	linux-pm@...r.kernel.org
> +Description:
> +		Reports the name of the device manufacturer.
> +
> +		Access: Read
> +		Valid values: Represented as string
> +
> +What:		/sys/class/power_supply/<supply_name>/model_name
> +Date:		May 2007
> +Contact:	linux-pm@...r.kernel.org
> +Description:
> +		Reports the name of the device model.
> +
> +		Access: Read
> +		Valid values: Represented as string
> +
> +What:		/sys/class/power_supply/<supply_name>/serial_number
> +Date:		January 2008
> +Contact:	linux-pm@...r.kernel.org
> +Description:
> +		Reports the serial number of the device.
> +
> +		Access: Read
> +		Valid values: Represented as string
> +
> +What:		/sys/class/power_supply/<supply_name>/type
> +Date:		May 2010
> +Contact:	linux-pm@...r.kernel.org
> +Description:
> +		Describes the main type of the supply.
> +
> +		Access: Read
> +		Valid values: "Battery", "UPS", "Mains", "USB"
> +
> +===== Battery Properties =====
> +
> +What:		/sys/class/power_supply/<supply_name>/capacity
> +Date:		May 2007
> +Contact:	linux-pm@...r.kernel.org
> +Description:
> +		Fine grain representation of battery capacity.
> +		Access: Read
> +		Valid values: 0 - 100 (percent)
> +
> +What:		/sys/class/power_supply/<supply_name>/capacity_alert_max
> +Date:		July 2012
> +Contact:	linux-pm@...r.kernel.org
> +Description:
> +		Maximum battery capacity trip-wire value where the supply will
> +		notify user-space of the event. This is normally used for the
> +		battery discharging scenario where user-space needs to know the
> +		battery has dropped to an upper level so it can take
> +		appropriate action (e.g. warning user that battery level is
> +		low).
> +
> +		Access: Read, Write
> +		Valid values: 0 - 100 (percent)
> +
> +What:		/sys/class/power_supply/<supply_name>/capacity_alert_min
> +Date:		July 2012
> +Contact:	linux-pm@...r.kernel.org
> +Description:
> +		Minimum battery capacity trip-wire value where the supply will
> +		notify user-space of the event. This is normally used for the
> +		battery discharging scenario where user-space needs to know the
> +		battery has dropped to a lower level so it can take
> +		appropriate action (e.g. warning user that battery level is
> +		critically low).
> +
> +		Access: Read, Write
> +		Valid values: 0 - 100 (percent)
> +
> +What:		/sys/class/power_supply/<supply_name>/capacity_level
> +Date:		June 2009
> +Contact:	linux-pm@...r.kernel.org
> +Description:
> +		Coarse representation of battery capacity.
> +
> +		Access: Read
> +		Valid values: "Unknown", "Critical", "Low", "Normal", "High",
> +			      "Full"
> +
> +What:		/sys/class/power_supply/<supply_name>/current_avg
> +Date:		May 2007
> +Contact:	linux-pm@...r.kernel.org
> +Description:
> +		Reports an average IBAT current reading for the battery, over a
> +		fixed period. Normally devices will provide a fixed interval in
> +		which they average readings to smooth out the reported value.
> +
> +		Access: Read
> +		Valid values: Represented in microamps
> +
> +What:		/sys/class/power_supply/<supply_name>/current_max
> +Date:		October 2010
> +Contact:	linux-pm@...r.kernel.org
> +Description:
> +		Reports the maximum IBAT current allowed into the battery.
> +
> +		Access: Read
> +		Valid values: Represented in microamps
> +
> +What:		/sys/class/power_supply/<supply_name>/current_now
> +Date:		May 2007
> +Contact:	linux-pm@...r.kernel.org
> +Description:
> +		Reports an instant, single IBAT current reading for the battery.
> +		This value is not averaged/smoothed.
> +
> +		Access: Read
> +		Valid values: Represented in microamps
> +
> +What:		/sys/class/power_supply/<supply_name>/charge_type
> +Date:		July 2009
> +Contact:	linux-pm@...r.kernel.org
> +Description:
> +		Represents the type of charging currently being applied to the
> +		battery.
> +
> +		Access: Read
> +		Valid values: "Unknown", "N/A", "Trickle", "Fast"
> +
> +What:		/sys/class/power_supply/<supply_name>/charge_term_current
> +Date:		July 2014
> +Contact:	linux-pm@...r.kernel.org
> +Description:
> +		Reports the charging current value which is used to determine
> +		when the battery is considered full and charging should end.
> +
> +		Access: Read
> +		Valid values: Represented in microamps
> +
> +What:		/sys/class/power_supply/<supply_name>/health
> +Date:		May 2007
> +Contact:	linux-pm@...r.kernel.org
> +Description:
> +		Reports the health of the battery or battery side of charger
> +		functionality.
> +
> +		Access: Read
> +		Valid values: "Unknown", "Good", "Overheat", "Dead",
> +			      "Over voltage", "Unspecified failure", "Cold",
> +			      "Watchdog timer expire", "Safety timer expire"
> +
> +What:		/sys/class/power_supply/<supply_name>/precharge_current
> +Date:		June 2017
> +Contact:	linux-pm@...r.kernel.org
> +Description:
> +		Reports the charging current applied during pre-charging phase
> +		for a battery charge cycle.
> +
> +		Access: Read
> +		Valid values: Represented in microamps
> +
> +What:		/sys/class/power_supply/<supply_name>/present
> +Date:		May 2007
> +Contact:	linux-pm@...r.kernel.org
> +Description:
> +		Reports whether a battery is present or not in the system.
> +
> +		Access: Read
> +		Valid values:
> +			0: Absent
> +			1: Present
> +
> +What:		/sys/class/power_supply/<supply_name>/status
> +Date:		May 2007
> +Contact:	linux-pm@...r.kernel.org
> +Description:
> +		Represents the charging status of the battery. Normally this
> +		is read-only reporting although for some supplies this can be
> +		used to enable/disable charging to the battery.
> +
> +		Access: Read, Write
> +		Valid values: "Unknown", "Charging", "Discharging",
> +			      "Not charging", "Full"
> +
> +What:		/sys/class/power_supply/<supply_name>/technology
> +Date:		May 2007
> +Contact:	linux-pm@...r.kernel.org
> +Description:
> +		Describes the battery technology supported by the supply.
> +
> +		Access: Read
> +		Valid values: "Unknown", "NiMH", "Li-ion", "Li-poly", "LiFe",
> +			      "NiCd", "LiMn"
> +
> +What:		/sys/class/power_supply/<supply_name>/temp
> +Date:		May 2007
> +Contact:	linux-pm@...r.kernel.org
> +Description:
> +		Reports the current TBAT battery temperature reading.
> +
> +		Access: Read
> +		Valid values: Represented in 1/10 Degrees Celsius
> +
> +What:		/sys/class/power_supply/<supply_name>/temp_alert_max
> +Date:		July 2012
> +Contact:	linux-pm@...r.kernel.org
> +Description:
> +		Maximum TBAT temperature trip-wire value where the supply will
> +		notify user-space of the event. This is normally used for the
> +		battery charging scenario where user-space needs to know the
> +		battery temperature has crossed an upper threshold so it can
> +		take appropriate action (e.g. warning user that battery level is
> +		critically high, and charging has stopped).
> +
> +		Access: Read
> +		Valid values: Represented in 1/10 Degrees Celsius
> +
> +What:		/sys/class/power_supply/<supply_name>/temp_alert_min
> +Date:		July 2012
> +Contact:	linux-pm@...r.kernel.org
> +Description:
> +		Minimum TBAT temperature trip-wire value where the supply will
> +		notify user-space of the event. This is normally used for the
> +		battery charging scenario where user-space needs to know the
> +		battery temperature has crossed a lower threshold so it can take
> +		appropriate action (e.g. warning user that battery level is
> +		high, and charging current has been reduced accordingly to
> +		remedy the situation).
> +
> +		Access: Read
> +		Valid values: Represented in 1/10 Degrees Celsius
> +
> +What:		/sys/class/power_supply/<supply_name>/temp_max
> +Date:		July 2014
> +Contact:	linux-pm@...r.kernel.org
> +Description:
> +		Reports the maximum allowed TBAT battery temperature for
> +		charging.
> +
> +		Access: Read
> +		Valid values: Represented in 1/10 Degrees Celsius
> +
> +What:		/sys/class/power_supply/<supply_name>/temp_min
> +Date:		July 2014
> +Contact:	linux-pm@...r.kernel.org
> +Description:
> +		Reports the minimum allowed TBAT battery temperature for
> +		charging.
> +
> +		Access: Read
> +		Valid values: Represented in 1/10 Degrees Celsius
> +
> +What:		/sys/class/power_supply/<supply_name>/voltage_avg,
> +Date:		May 2007
> +Contact:	linux-pm@...r.kernel.org
> +Description:
> +		Reports an average VBAT voltage reading for the battery, over a
> +		fixed period. Normally devices will provide a fixed interval in
> +		which they average readings to smooth out the reported value.
> +
> +		Access: Read
> +		Valid values: Represented in microvolts
> +
> +What:		/sys/class/power_supply/<supply_name>/voltage_max,
> +Date:		January 2008
> +Contact:	linux-pm@...r.kernel.org
> +Description:
> +		Reports the maximum safe VBAT voltage permitted for the battery,
> +		during charging.
> +
> +		Access: Read
> +		Valid values: Represented in microvolts
> +
> +What:		/sys/class/power_supply/<supply_name>/voltage_min,
> +Date:		January 2008
> +Contact:	linux-pm@...r.kernel.org
> +Description:
> +		Reports the minimum safe VBAT voltage permitted for the battery,
> +		during discharging.
> +
> +		Access: Read
> +		Valid values: Represented in microvolts
> +
> +What:		/sys/class/power_supply/<supply_name>/voltage_now,
> +Date:		May 2007
> +Contact:	linux-pm@...r.kernel.org
> +Description:
> +		Reports an instant, single VBAT voltage reading for the battery.
> +		This value is not averaged/smoothed.
> +
> +		Access: Read
> +		Valid values: Represented in microvolts
> +
> +===== USB Properties =====
> +
> +What: 		/sys/class/power_supply/<supply_name>/current_avg
> +Date:		May 2007
> +Contact:	linux-pm@...r.kernel.org
> +Description:
> +		Reports an average IBUS current reading over a fixed period.
> +		Normally devices will provide a fixed interval in which they
> +		average readings to smooth out the reported value.
> +
> +		Access: Read
> +		Valid values: Represented in microamps
> +
> +
> +What: 		/sys/class/power_supply/<supply_name>/current_max
> +Date:		October 2010
> +Contact:	linux-pm@...r.kernel.org
> +Description:
> +		Reports the maximum IBUS current the supply can support.
> +
> +		Access: Read
> +		Valid values: Represented in microamps
> +
> +What: 		/sys/class/power_supply/<supply_name>/current_now
> +Date:		May 2007
> +Contact:	linux-pm@...r.kernel.org
> +Description:
> +		Reports the IBUS current supplied now. This value is generally
> +		read-only reporting, unless the 'online' state of the supply
> +		is set to be programmable, in which case this value can be set
> +		within the reported min/max range.
> +
> +		Access: Read, Write
> +		Valid values: Represented in microamps
> +
> +What:		/sys/class/power_supply/<supply_name>/input_current_limit
> +Date:		July 2014
> +Contact:	linux-pm@...r.kernel.org
> +Description:
> +		Details the incoming IBUS current limit currently set in the
> +		supply. Normally this is configured based on the type of
> +		connection made (e.g. A configured SDP should output a maximum
> +		of 500mA so the input current limit is set to the same value).
> +
> +		Access: Read, Write
> +		Valid values: Represented in microamps
> +
> +What:		/sys/class/power_supply/<supply_name>/online,
> +Date:		May 2007
> +Contact:	linux-pm@...r.kernel.org
> +Description:
> +		Indicates if VBUS is present for the supply. When the supply is
> +		online, and the supply allows it, then it's possible to switch
> +		between online states (e.g. Fixed -> Programmable for a PD_PPS
> +		USB supply so voltage and current can be controlled).
> +
> +		Access: Read, Write
> +		Valid values:
> +			0: Offline
> +			1: Online Fixed - Fixed Voltage Supply
> +			2: Online Programmable - Programmable Voltage Supply
> +
> +What:		/sys/class/power_supply/<supply_name>/temp
> +Date:		May 2007
> +Contact:	linux-pm@...r.kernel.org
> +Description:
> +		Reports the current supply temperature reading. This would
> +		normally be the internal temperature of the device itself (e.g
> +		TJUNC temperature of an IC)
> +
> +		Access: Read
> +		Valid values: Represented in 1/10 Degrees Celsius
> +
> +What:		/sys/class/power_supply/<supply_name>/temp_alert_max
> +Date:		July 2012
> +Contact:	linux-pm@...r.kernel.org
> +Description:
> +		Maximum supply temperature trip-wire value where the supply will
> +		notify user-space of the event. This is normally used for the
> +		charging scenario where user-space needs to know the supply
> +		temperature has crossed an upper threshold so it can take
> +		appropriate action (e.g. warning user that the supply
> +		temperature is critically high, and charging has stopped to
> +		remedy the situation).
> +
> +		Access: Read
> +		Valid values: Represented in 1/10 Degrees Celsius
> +
> +What:		/sys/class/power_supply/<supply_name>/temp_alert_min
> +Date:		July 2012
> +Contact:	linux-pm@...r.kernel.org
> +Description:
> +		Minimum supply temperature trip-wire value where the supply will
> +		notify user-space of the event. This is normally used for the
> +		charging scenario where user-space needs to know the supply
> +		temperature has crossed a lower threshold so it can take
> +		appropriate action (e.g. warning user that the supply
> +		temperature is high, and charging current has been reduced
> +		accordingly to remedy the situation).
> +
> +		Access: Read
> +		Valid values: Represented in 1/10 Degrees Celsius
> +
> +What:		/sys/class/power_supply/<supply_name>/temp_max
> +Date:		July 2014
> +Contact:	linux-pm@...r.kernel.org
> +Description:
> +		Reports the maximum allowed supply temperature for operation.
> +
> +		Access: Read
> +		Valid values: Represented in 1/10 Degrees Celsius
> +
> +What:		/sys/class/power_supply/<supply_name>/temp_min
> +Date:		July 2014
> +Contact:	linux-pm@...r.kernel.org
> +Description:
> +		Reports the mainimum allowed supply temperature for operation.
> +
> +		Access: Read
> +		Valid values: Represented in 1/10 Degrees Celsius
> +
> +What: 		/sys/class/power_supply/<supply_name>/voltage_max
> +Date:		January 2008
> +Contact:	linux-pm@...r.kernel.org
> +Description:
> +		Reports the maximum VBUS voltage the supply can support.
> +
> +		Access: Read
> +		Valid values: Represented in microvolts
> +
> +What: 		/sys/class/power_supply/<supply_name>/voltage_min
> +Date:		January 2008
> +Contact:	linux-pm@...r.kernel.org
> +Description:
> +		Reports the minimum VBUS voltage the supply can support.
> +
> +		Access: Read
> +		Valid values: Represented in microvolts
> +
> +What: 		/sys/class/power_supply/<supply_name>/voltage_now
> +Date:		May 2007
> +Contact:	linux-pm@...r.kernel.org
> +Description:
> +		Reports the VBUS voltage supplied now. This value is generally
> +		read-only reporting, unless the 'online' state of the supply
> +		is set to be programmable, in which case this value can be set
> +		within the reported min/max range.
> +
> +		Access: Read, Write
> +		Valid values: Represented in microvolts
> +
> +===== Device Specific Properties =====
> +
>  What:		/sys/class/power/ds2760-battery.*/charge_now
>  Date:		May 2010
>  KernelVersion:	2.6.35
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 0a1410d..700bfb7 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -11242,6 +11242,7 @@ M:	Sebastian Reichel <sre@...nel.org>
>  L:	linux-pm@...r.kernel.org
>  T:	git git://git.kernel.org/pub/scm/linux/kernel/git/sre/linux-power-supply.git
>  S:	Maintained
> +F:	Documentation/ABI/testing/sysfs-class-power
>  F:	Documentation/devicetree/bindings/power/supply/
>  F:	include/linux/power_supply.h
>  F:	drivers/power/supply/
> -- 
> 1.9.1

-- 
heikki