Skip to contentSkip to conversation

Battery class driver.

PATCH David Woodhouse 8 participants 21 messages Oct 23, 2006 – Oct 25, 2006 Kbuild

lore
Share & tools
lore
#0 lore raw

At git://git.infradead.org/battery-2.6.git there is an initial implementation of a battery class, along with a driver which makes use of it. The patch is below, and also viewable at
http://git.infradead.org/?p=battery-2.6.git;a=commitdiff;h=master;hp=linus

I don't like the sysfs interaction much -- is it really necessary for me to provide a separate function for each attribute, rather than a single function which handles them all and is given the individual attribute as an argument? That seems strange and bloated.

I'm half tempted to ditch the sysfs attributes and just use a single seq_file, in fact.

The idea is that all batteries should be presented to userspace through this class instead of through the existing mess of PMU/APM/ACPI and even APM _emulation_.

I think I probably want to make AC power a separate 'device' too, rather than an attribute of any given battery. And when there are multiple power supplies, there should be multiple such devices. So maybe it should be a 'power supply' class, not a battery class at all?

Comments?

commit 42fe507a262b2a2879ca62740c5312778ae78627

Author: David Woodhouse <[email protected]>
Date:   Mon Oct 23 18:14:54 2006 +0100

[BATTERY] Add support for OLPC battery

commit 6cbec3b84e3ce737b4217788841ea10a28a5e340

Author: David Woodhouse <[email protected]>
Date:   Mon Oct 23 18:14:14 2006 +0100

[BATTERY] Add initial implementation of battery class

I really don't like the sysfs interaction, and I don't much like the internal interaction with the battery drivers either. In fact, there isn't much I _do_ like, but it's good enough as a straw man.

Makefile renamed from Makefile~ +1 -0
@@ -30,6 +30,7 @@ obj-$(CONFIG_PARPORT)		+= parport/
 obj-y				+= base/ block/ misc/ mfd/ net/ media/
 obj-$(CONFIG_NUBUS)		+= nubus/
 obj-$(CONFIG_ATM)		+= atm/
+obj-$(CONFIG_BATTERY_CLASS)	+= battery/
 obj-$(CONFIG_PPC_PMAC)		+= macintosh/
 obj-$(CONFIG_XEN)		+= xen/
 obj-$(CONFIG_IDE)		+= ide/
Kconfig renamed from Kconfig~ +2 -0
@@ -28,6 +28,8 @@ source "drivers/ieee1394/Kconfig"
 
 source "drivers/message/i2o/Kconfig"
 
+source "drivers/battery/Kconfig"
+
 source "drivers/macintosh/Kconfig"
 
 source "drivers/net/Kconfig"
battery/Makefile new file +4 -0
@@ -0,0 +1,4 @@
+# Battery code
+obj-$(CONFIG_BATTERY_CLASS)		+= battery-class.o
+
+obj-$(CONFIG_OLPC_BATTERY)		+= olpc-battery.o
battery/Kconfig new file +22 -0
@@ -0,0 +1,22 @@
+
+menu "Battery support"
+
+config BATTERY_CLASS
+       tristate "Battery support"
+       help
+         Say Y to enable battery class support. This allows a battery
+	 information to be presented in a uniform manner for all types
+	 of batteries.
+
+	 Battery information from APM and ACPI is not yet available by
+	 this method, but should soon be. If you use APM or ACPI, say
+	 'N', although saying 'Y' would be harmless.
+
+config OLPC_BATTERY
+       tristate "One Laptop Per Child battery"
+       depends on BATTERY_CLASS && X86_32
+       help
+         Say Y to enable support for the battery on the $100 laptop.
+
+
+endmenu
battery/battery-class.c new file +286 -0

286 lines not on this page · raw message

battery/olpc-battery.c new file +198 -0

198 lines not on this page · raw message

linux/battery.h new file +84 -0

84 lines not on this page · raw message

Signature · 1 line
dwmw2
#1 lore raw
Quoted 11 lines · David Woodhouse
battery/battery-class.c new file +11 -0
+BATTERY_DEVICE_ATTR("temp1",TEMP1,milli);
+BATTERY_DEVICE_ATTR("temp1_name",TEMP1_NAME,string);
+BATTERY_DEVICE_ATTR("temp2",TEMP2,milli);
+BATTERY_DEVICE_ATTR("temp2_name",TEMP2_NAME,string);
+BATTERY_DEVICE_ATTR("voltage",VOLTAGE,milli);
+BATTERY_DEVICE_ATTR("voltage_design",VOLTAGE_DESIGN,milli);
+BATTERY_DEVICE_ATTR("current",CURRENT,milli);
+BATTERY_DEVICE_ATTR("charge_rate",CHARGE_RATE,milli);
+BATTERY_DEVICE_ATTR("charge_max",CHARGE_MAX,milli);
+BATTERY_DEVICE_ATTR("charge_last",CHARGE_LAST,milli);
+BATTERY_DEVICE_ATTR("charge_low",CHARGE_LOW,milli);

battery/battery-class.c line 167

Quoted 10 lines
battery/battery-class.c new file +10 -0
+BATTERY_DEVICE_ATTR("charge_warn",CHARGE_WARN,milli);
+BATTERY_DEVICE_ATTR("charge_unit",CHARGE_UNITS,string);
+BATTERY_DEVICE_ATTR("charge_percent",CHARGE_PCT,int);
+BATTERY_DEVICE_ATTR("time_remaining",TIME_REMAINING,int);
+BATTERY_DEVICE_ATTR("manufacturer",MANUFACTURER,string);
+BATTERY_DEVICE_ATTR("technology",TECHNOLOGY,string);
+BATTERY_DEVICE_ATTR("model",MODEL,string);
+BATTERY_DEVICE_ATTR("serial",SERIAL,string);
+BATTERY_DEVICE_ATTR("type",TYPE,string);
+BATTERY_DEVICE_ATTR("oem_info",OEM_INFO,string);

Without commenting on the rest:

The tp_smapi code also provides average current and power, the charge cycle count, the date of first use, the date of manufacture and controls for altering the charge behaviour of the battery. Are these things that should go in the generic class?

Signature · 1 line
Matthew Garrett | [email protected]
#2 lore raw
Quoted 6 lines · Matthew Garrett

Without commenting on the rest:

The tp_smapi code also provides average current and power, the charge cycle count, the date of first use, the date of manufacture and controls for altering the charge behaviour of the battery. Are these things that should go in the generic class?

Yes, almost certainly. I went looking for what ACPI, PMU and of course OLPC provided, but missed the others.

Signature · 1 line
dwmw2
#3 lore raw
In reply to Matthew Garrett
Quoted 5 lines

The tp_smapi code also provides average current and power, the charge cycle count, the date of first use, the date of manufacture and controls for altering the charge behaviour of the battery. Are these things that should go in the generic class?

Also, should we create files for things that the backend doesn't provide ? Seems like a waste of memory to me.

Ben

#4 lore raw
In reply to David Woodhouse
Quoted 9 lines · David Woodhouse

At git://git.infradead.org/battery-2.6.git there is an initial implementation of a battery class, along with a driver which makes use of it. The patch is below, and also viewable at
http://git.infradead.org/?p=battery-2.6.git;a=commitdiff;h=master;hp=linus

I don't like the sysfs interaction much -- is it really necessary for me to provide a separate function for each attribute, rather than a single function which handles them all and is given the individual attribute as an argument? That seems strange and bloated.

It is, but no one has asked for it to be changed to be like the struct device attributes are. In fact, why not just use the struct device attributes here instead? That will be much easier and keep me from having to convert your code over to use it in the future :)

Quoted 2 lines

I'm half tempted to ditch the sysfs attributes and just use a single seq_file, in fact.

Ick, no. You should use the hwmon interface, and standardize on a proper battery api just like those developers have standardized on other sensor apis that are exported to userspace. Take a look at Documentation/hwmon/sysfs-interface for an example of what it should look like.

Quoted 3 lines

The idea is that all batteries should be presented to userspace through this class instead of through the existing mess of PMU/APM/ACPI and even APM _emulation_.

Yes, I agree this should be done in this manner.

Quoted 4 lines

I think I probably want to make AC power a separate 'device' too, rather than an attribute of any given battery. And when there are multiple power supplies, there should be multiple such devices. So maybe it should be a 'power supply' class, not a battery class at all?

That sounds good to me.

Jean, I know you had some ideas with regards to this in the past.

thanks,

greg k-h

#5 lore raw
Quoted 9 lines · Greg KH
Quoted 2 lines · David Woodhouse

I'm half tempted to ditch the sysfs attributes and just use a single seq_file, in fact.

Ick, no. You should use the hwmon interface, and standardize on a proper battery api just like those developers have standardized on other sensor apis that are exported to userspace. Take a look at Documentation/hwmon/sysfs-interface for an example of what it should look like.

Ok, nevermind, it looks like your code does do something much like this, which is great. Just make sure your units are the same as the other hwmon drivers and everything should be fine.

thanks,

greg k-h

#6 lore raw
In reply to Greg KH
Quoted 11 lines · Greg KH
Quoted 9 lines · David Woodhouse

At git://git.infradead.org/battery-2.6.git there is an initial implementation of a battery class, along with a driver which makes use of it. The patch is below, and also viewable at
http://git.infradead.org/?p=battery-2.6.git;a=commitdiff;h=master;hp=linus

I don't like the sysfs interaction much -- is it really necessary for me to provide a separate function for each attribute, rather than a single function which handles them all and is given the individual attribute as an argument? That seems strange and bloated.

Quoted 4 lines

It is, but no one has asked for it to be changed to be like the struct device attributes are. In fact, why not just use the struct device attributes here instead? That will be much easier and keep me from having to convert your code over to use it in the future :)

Heh, OK. I'll look at that. Thanks.

Quoted 6 lines
Quoted 2 lines

I'm half tempted to ditch the sysfs attributes and just use a single seq_file, in fact.

Ick, no. You should use the hwmon interface, and standardize on a proper battery api just like those developers have standardized on other sensor apis that are exported to userspace.

Er, yes. The whole point in this is so we can standardise on a proper battery API. I'm only really supposed to be adding support for the battery on the $100 laptop, but I just couldn't bring myself to do yet another different battery driver without trying to bring in some sanity.

I sincerely hope that those responsible for the various other different userspace interfaces for PMU, ACPI, etc. are all hanging their heads in shame at this point :)

Signature · 1 line
dwmw2
#7 lore raw
Quoted 4 lines

I sincerely hope that those responsible for the various other different userspace interfaces for PMU, ACPI, etc. are all hanging their heads in shame at this point :)

/me looks at ACPI ... :)

Ben.

#8 lore raw
In reply to Greg KH
Quoted 31 lines · Greg KH
Quoted 9 lines · David Woodhouse

At git://git.infradead.org/battery-2.6.git there is an initial implementation of a battery class, along with a driver which makes use of it. The patch is below, and also viewable at
http://git.infradead.org/?p=battery-2.6.git;a=commitdiff;h=master;hp=linus

I don't like the sysfs interaction much -- is it really necessary for me to provide a separate function for each attribute, rather than a single function which handles them all and is given the individual attribute as an argument? That seems strange and bloated.

It is, but no one has asked for it to be changed to be like the struct device attributes are. In fact, why not just use the struct device attributes here instead? That will be much easier and keep me from having to convert your code over to use it in the future :)

Quoted 2 lines

I'm half tempted to ditch the sysfs attributes and just use a single seq_file, in fact.

Ick, no. You should use the hwmon interface, and standardize on a proper battery api just like those developers have standardized on other sensor apis that are exported to userspace. Take a look at Documentation/hwmon/sysfs-interface for an example of what it should look like.

Quoted 3 lines

The idea is that all batteries should be presented to userspace through this class instead of through the existing mess of PMU/APM/ACPI and even APM _emulation_.

Yes, I agree this should be done in this manner.

Quoted 8 lines
Quoted 4 lines

I think I probably want to make AC power a separate 'device' too, rather than an attribute of any given battery. And when there are multiple power supplies, there should be multiple such devices. So maybe it should be a 'power supply' class, not a battery class at all?

That sounds good to me.

Jean, I know you had some ideas with regards to this in the past.

Did I? I don't remember 8]

Anyway I don't have much to add over what you said. The hwmon interface proved to be good, so the battery interface should look the same. Sysfs files, one integer value per file, using standard names and units, with "small units" (mV, mW etc...) so that you have enough resolution in all present and future cases.

Signature · 1 line
Jean Delvare
#9 lore raw
In reply to David Woodhouse

Hi,

Quoted 3 lines · David Woodhouse

The idea is that all batteries should be presented to userspace through this class instead of through the existing mess of PMU/APM/ACPI and even APM _emulation_.

Yea, that would be nice, we've got code in HAL to handle all these three (and more) and provide one coherent interface. The battery class abstraction should probably be flexible enough to handle things such as

- UPS's
- Bluetooth devices with batteries
- USB wireless mice / keyboards
- ... and so on.

if someone wants to write a kernel-space driver for these some day. We handle the latter in HAL using some user space code and to me it's still an open question (and not really a very interesting one) whether you want the code kernel- or user-side.

As an aside, you probably want some kind of device symlink for the "battery class" instance in sysfs such that it points to the "physical" device. For ACPI/PMU/APM etc. I guess it points to somewhere in /sys/devices/platform; for a Bluetooth device it might point to the Bluetooth device in sysfs (cf. Marcel's patch to do this) and so on. Otherwise it's hard for user space to figure out what the battery is used for. Perhaps the driver itself can contribute with some kind of sysfs file 'usage' that can assume values "laptop_battery", "ups" etc., dunno if that's a good idea.

I think that it requires some degree of documentation for the files you export including docs on the ranges. Probably worth sticking to *some* convention such as if you can't provide a given value then the file simply isn't there instead of just providing some magic value like charge=0 if you don't know the charge. That probably means you need some kind of 'sentinel' for each value that will make the generic battery class code omit presenting the file.

(I'm not sure whether there are any general sysfs guidelines on this so forgive me if there is already.)

Please also avoid putting more than on value in a single file, e.g. I think we want to avoid e.g. this

 # cat /sys/class/battery/OLPC/state
 present,low,charging

and rather have is_present, is_charging, is_discharging and so on; i.e. one value per file even if we're talking about flags. It's just less messy this way.

Quoted 4 lines

I think I probably want to make AC power a separate 'device' too, rather than an attribute of any given battery. And when there are multiple power supplies, there should be multiple such devices. So maybe it should be a 'power supply' class, not a battery class at all?

So I happen to think they are different beasts. Some batteries may not be rechargable by the host / device (think USB wireless mice with normal AAA batteries) and some power supply units may not have a battery (think big iron with multiple PSU's). I think, in general, they have different characteristics (they share some though) so perhaps it would be good to have different abstractions? I'm not a domain expert here though.

How do we plan to get updates to user space? The ACPI code today provides updates via the ACPI socket but that is broken on some hardware so essentially HAL polls by reading /proc/acpi/battery/BAT0/state some every 30 secs on, and, on some boxen, that generates a SMBIOS trap or some other expensive operation. That's wrong.

So I think the generic battery class code should cache everything which has the nice side effect that any stupid user space app doesn't bring the system to it's knees just because it's re-reading the same file over and over again.

So, perhaps the battery class should provide a file called 'timestamp' or something that is only writable by the super user. If you read from that file it gives the time when the information was last updated. If you write to the file it will force the driver query the hardware and update the other files. Reading any other file than 'timestamp' will just read cached information.

The mechanism to notify user space that something have been updated would be either to make the timestamp file pollable or use an uevent or something else (no input drivers please).

If the hardware is able to generate an interrupt when certain data on the battery has changed the driver simply updates the timestamp file.

With this scheme, user space simply does this

10 poll on /sys/class/battery/BAT0/timestamp with timeout=30sec 20 if timeout, write to 'timestamp' file to force polling 30 read values from sysfs and update graphics for battery icon etc. 40 goto 10

and we only poll when the hardware don't provide such interrupts / hardware is broken so it don't provide interrupts.

Specifically, user space can decide to make the timeout infinite or decide not to poll under certain conditions etc. etc.

How about that?

David

#10 lore raw
Quoted 22 lines · David Zeuthen

Hi,

Quoted 3 lines · David Woodhouse

The idea is that all batteries should be presented to userspace through this class instead of through the existing mess of PMU/APM/ACPI and even APM _emulation_.

Yea, that would be nice, we've got code in HAL to handle all these three (and more) and provide one coherent interface. The battery class abstraction should probably be flexible enough to handle things such as

- UPS's
- Bluetooth devices with batteries
- USB wireless mice / keyboards
- ... and so on.

if someone wants to write a kernel-space driver for these some day. We handle the latter in HAL using some user space code and to me it's still an open question (and not really a very interesting one) whether you want the code kernel- or user-side.

Quoted 9 lines

As an aside, you probably want some kind of device symlink for the "battery class" instance in sysfs such that it points to the "physical" device. For ACPI/PMU/APM etc. I guess it points to somewhere in /sys/devices/platform; for a Bluetooth device it might point to the Bluetooth device in sysfs (cf. Marcel's patch to do this) and so on. Otherwise it's hard for user space to figure out what the battery is used for. Perhaps the driver itself can contribute with some kind of sysfs file 'usage' that can assume values "laptop_battery", "ups" etc., dunno if that's a good idea.

By using a real device for the battery, you will get this for free, along with a symlink back from the sysfs class if you so desire. I know HAL can handle this properly, as we are doing this in the next opensuse release (10.2) for almost all class devices.

Actually, using the hwmon class is probably the best, as you are doing much the same thing. I don't think a new class is probably needed here.

Quoted 7 lines

I think that it requires some degree of documentation for the files you export including docs on the ranges. Probably worth sticking to *some* convention such as if you can't provide a given value then the file simply isn't there instead of just providing some magic value like charge=0 if you don't know the charge. That probably means you need some kind of 'sentinel' for each value that will make the generic battery class code omit presenting the file.

Documentation/hwmon/sysfs-interface is the proper format for documenting this to start with. Documentation/ABI is probably the best place for it to end up in eventually.

Quoted 2 lines

(I'm not sure whether there are any general sysfs guidelines on this so forgive me if there is already.)

Yes, see above :)

Quoted 9 lines

Please also avoid putting more than on value in a single file, e.g. I think we want to avoid e.g. this

 # cat /sys/class/battery/OLPC/state
 present,low,charging

and rather have is_present, is_charging, is_discharging and so on; i.e. one value per file even if we're talking about flags. It's just less messy this way.

Agreed.

Quoted 23 lines
Quoted 4 lines

I think I probably want to make AC power a separate 'device' too, rather than an attribute of any given battery. And when there are multiple power supplies, there should be multiple such devices. So maybe it should be a 'power supply' class, not a battery class at all?

So I happen to think they are different beasts. Some batteries may not be rechargable by the host / device (think USB wireless mice with normal AAA batteries) and some power supply units may not have a battery (think big iron with multiple PSU's). I think, in general, they have different characteristics (they share some though) so perhaps it would be good to have different abstractions? I'm not a domain expert here though.

How do we plan to get updates to user space? The ACPI code today provides updates via the ACPI socket but that is broken on some hardware so essentially HAL polls by reading /proc/acpi/battery/BAT0/state some every 30 secs on, and, on some boxen, that generates a SMBIOS trap or some other expensive operation. That's wrong.

So I think the generic battery class code should cache everything which has the nice side effect that any stupid user space app doesn't bring the system to it's knees just because it's re-reading the same file over and over again.

Quoted 6 lines

So, perhaps the battery class should provide a file called 'timestamp' or something that is only writable by the super user. If you read from that file it gives the time when the information was last updated. If you write to the file it will force the driver query the hardware and update the other files. Reading any other file than 'timestamp' will just read cached information.

You can poll the sysfs file, which means you just sleep until something changes in it and then you wake up and read it. Sound accepatble?

thanks,

greg k-h

#11 lore raw
Quoted 9 lines · Greg KH
Quoted 6 lines

So, perhaps the battery class should provide a file called 'timestamp' or something that is only writable by the super user. If you read from that file it gives the time when the information was last updated. If you write to the file it will force the driver query the hardware and update the other files. Reading any other file than 'timestamp' will just read cached information.

You can poll the sysfs file, which means you just sleep until something changes in it and then you wake up and read it. Sound accepatble?

Yea, however I still think there needs to be a 'timestamp' file so

a) we don't need to poll every file in /sys/class/battery/BAT0 (if we had to do that, we would (potentially) wake up N times!); and

b) if the kernel ensures that the 'timestamp' file is updated last, we get atomic updates (which might matter for drawing pretty graphs, guestimating remaining time etc.); and

c) it provides some mechanism to instruct the driver to go read the values from the hardware (if that is what user space wants) nonwithstanding that the hardware / driver delivers asynchronous updates once in a while via an IRQ.

Notably user space can see _when_ the values from the hardware was retrieved the last time which makes it easier to work around with hardware / drivers that don't provide asynchronous updates even when they are supposed to (if there is some bug with e.g. the ACPI stack).

This implies that the battery class should probably cache the values as to make the platform driver as simple as possible. I've got a bad feeling things like caching is badly frowned upon in kernel space but I thought I'd ask for it anyway :-). I hope I've stated my case :-)

(Anyway, the point is that I want to avoid having an open file descriptor for each and every file in /sys/class/battery/BAT0 to put it into the huge poll() stmt in my main loop (granted with things like glib it's dead simple), that's all.. Caching might also avoid excessive round trips to the hardware but one can argue both way in most cases.)

So.. how all this relates to hwmon I'm not sure.. looking briefly at Documentation/hwmon/sysfs-interface no such thing seems to be available, I'm not sure how libsensors get by here but the problem is sorta similar. I do think batteries in itself deserves it's own abstraction instead of using hwmon but I'm no expert on this.

Btw, an OLPC specific feature is also to instruct the Embedded Controller (EC) to stop delivering IRQ's on battery/ac_adapter changes. This is so the host CPU won't be woken up when e.g. in e-book reader mode (or whatever) where the host CPU is supposed to be turned off to save juice.
This is simple right now as the EC currently doesn't deliver any IRQ's at all [1] and I guess a simple sysfs file in the OLPC platform device will let us do that once we actually get IRQ delivery. Thus, I'm not sure "stop IRQ delivery" belongs in the battery class proper. This is also why we need device link to the OLPC platform device.

David

[1] : but see http://dev.laptop.org/ticket/224

#12 lore raw
Quoted 2 lines · David Zeuthen

b) if the kernel ensures that the 'timestamp' file is updated last, we get atomic updates

Atomic updates require either double-buffering the data (twice worse than mere caching...) or locking away access during update (in which case the order doesn't mater).

But yes, lack of atomicity in sysfs is a big issue. We don't seem to have any ABI convention for providing atomic snapshots of those dozen-small-atribute directories.

Quoted 9 lines

Notably user space can see _when_ the values from the hardware was retrieved the last time

This is a good thing, but is orthogonal to the how-do-we-poll issue.

So.. how all this relates to hwmon I'm not sure.. looking briefly at Documentation/hwmon/sysfs-interface no such thing seems to be available,

Yes, hwmon ignores merrily ignores this issue, as do all other data-through-sysfs drivers I've looked at. Except for the patched hdaps driver in the tp_smapi package, which has a (very) rudimentary solution via caching and a configurable in-kernel polling timer.

Shem

#13 lore raw
In reply to David Zeuthen

Hi,

Quoted 1 line · David Zeuthen

How do we plan to get updates to user space?

There was a long LKML thread ("Generic battery interface") about this in July. This a general issue in sysfs, applicably whenever sysfs is used to communicate device data (as opposed to system configuration). We need a generic solution. Here are a few of the considerations that came up in that thread:

- Efficiency on both poll-based and event-based hardware data sources.
- Avoiding unnecessary timer interrupts on tickless kernels.
- Letting multiple userspace clients poll the same data source at different rates, without causing duplicate queries or unnecessary process wakeups.
- Avoiding duplicate queries on poll-based hardware that provides several attributes simultaneously.

Here's my latest proposed solution in that thread (but see the dozens of messages before and after for context...):
http://lkml.org/lkml/2006/7/30/193

Quoted 5 lines

The ACPI code today
provides updates via the ACPI socket but that is broken on some hardware so essentially HAL polls by reading /proc/acpi/battery/BAT0/state some every 30 secs on, and, on some boxen, that generates a SMBIOS trap or some other expensive operation. That's wrong.

30 seconds? I've seen battery applets that poll 1sec intervals (that's actually useful when you tweak power saving). And for things like the hdaps accelerometer driver, we're at the 50HZ region.

Quoted 21 lines

So, perhaps the battery class should provide a file called 'timestamp' or something that is only writable by the super user. If you read from that file it gives the time when the information was last updated. If you write to the file it will force the driver query the hardware and update the other files. Reading any other file than 'timestamp' will just read cached information.

The mechanism to notify user space that something have been updated would be either to make the timestamp file pollable or use an uevent or something else (no input drivers please).

If the hardware is able to generate an interrupt when certain data on the battery has changed the driver simply updates the timestamp file.

With this scheme, user space simply does this

10 poll on /sys/class/battery/BAT0/timestamp with timeout=30sec 20 if timeout, write to 'timestamp' file to force polling 30 read values from sysfs and update graphics for battery icon etc. 40 goto 10

Quoted 5 lines

and we only poll when the hardware don't provide such interrupts / hardware is broken so it don't provide interrupts.

Specifically, user space can decide to make the timeout infinite or decide not to poll under certain conditions etc. etc.

This is a very interesting approach; I don't recall anything like this from on the older thread.
There are a few problems though:
You can't require reading battery status to be a root-only operation. When mutiple userspace apps poll the battery, you'll get race conditions on timestamp, and even in the best case all the apps will be woken up at the poll rate of the most-frequently-polling app (think of that happening at 50HZ for hdaps...).

Shem

#14 lore raw
Quoted 3 lines · Shem Multinymous

30 seconds? I've seen battery applets that poll 1sec intervals (that's actually useful when you tweak power saving). And for things like the hdaps accelerometer driver, we're at the 50HZ region.

Reading the battery status has the potential to call an SMI that might take an arbitrary period of time to return, and we found that having querying at around the 1 second mark tended to result in noticable system performace degredation.

Possibly it would be useful if the kernel could keep track of how long certain queries take? That would let userspace calibrate itself without having to worry about whether it was preempted or not.

Quoted 1 line

You can't require reading battery status to be a root-only operation.

We certainly can. Whether we want to is another matter :) I tend to agree that moving to a setup that makes it harder for command-line users to read the battery status would be a regression.

Signature · 1 line
Matthew Garrett | [email protected]
#15 lore raw
Quoted 15 lines · Matthew Garrett
Quoted 3 lines · Shem Multinymous

30 seconds? I've seen battery applets that poll 1sec intervals (that's actually useful when you tweak power saving). And for things like the hdaps accelerometer driver, we're at the 50HZ region.

Reading the battery status has the potential to call an SMI that might take an arbitrary period of time to return, and we found that having querying at around the 1 second mark tended to result in noticable system performace degredation.

Possibly it would be useful if the kernel could keep track of how long certain queries take? That would let userspace calibrate itself without having to worry about whether it was preempted or not.

Quoted 5 lines
Quoted 1 line

You can't require reading battery status to be a root-only operation.

We certainly can. Whether we want to is another matter :) I tend to agree that moving to a setup that makes it harder for command-line users to read the battery status would be a regression.

I think it's up to the backend to poll more slowly and cache the results on those machines then.

Ben.

#16 lore raw
Quoted 9 lines · Benjamin Herrenschmidt
Quoted 4 lines · Matthew Garrett

Reading the battery status has the potential to call an SMI that might take an arbitrary period of time to return, and we found that having querying at around the 1 second mark tended to result in noticable system performace degredation.

I think it's up to the backend to poll more slowly and cache the results on those machines then.

The kernel backend or the userspace backend? We need to decide on terminology :) There's no good programmatic way of determining how long a query will take other than doing it and looking at the result. I guess we could do that at boot time.

Signature · 1 line
Matthew Garrett | [email protected]
#17 lore raw
Quoted 8 lines · Matthew Garrett
Quoted 6 lines · Benjamin Herrenschmidt
Quoted 4 lines · Matthew Garrett

Reading the battery status has the potential to call an SMI that might take an arbitrary period of time to return, and we found that having querying at around the 1 second mark tended to result in noticable system performace degredation.

Quoted 5 lines
Quoted 2 lines

I think it's up to the backend to poll more slowly and cache the results on those machines then.

The kernel backend or the userspace backend? We need to decide on terminology :)

The kernel. Userspace don't have to know the details of how hard it is for the backend to fetch the data imho.

Quoted 3 lines

There's no good programmatic way of determining how long
a query will take other than doing it and looking at the result. I guess we could do that at boot time.

Ben.

#18 lore raw
In reply to Matthew Garrett
Quoted 4 lines · Matthew Garrett

The kernel backend or the userspace backend? We need to decide on terminology :) There's no good programmatic way of determining how long a query will take other than doing it and looking at the result. I guess we could do that at boot time.

This is up to the kernel driver. Most drivers have fairly accurate knowledge about the hardware they read, in terms of both the cost of reading and the rate of change that's worth tracking.

The important thing is to define an ABI convention that lets userspace tell the driver when it wants the next refresh (via either David's timestamp or my suggested ioctl). The driver can then make its informed decision on how to reasonably fulfill the request.

Shem

#19 lore raw
In reply to David Woodhouse

Hi David,

Quoted 2 lines · David Woodhouse

At git://git.infradead.org/battery-2.6.git there is an initial implementation of a battery class

Excellent. It's about time the messy, inconsistent /proc battery ABI gets cleaned up.

Quoted 4 lines

I think I probably want to make AC power a separate 'device' too, rather than an attribute of any given battery. And when there are multiple power supplies, there should be multiple such devices. So maybe it should be a 'power supply' class, not a battery class at all?

It should be seprate, and probably a different class since most attributes don't make sense for AC.

battery/battery-class.c line 33

Quoted 5 lines
battery/battery-class.c new file +5 -0
+static ssize_t battery_attribute_show_int(struct class_device *dev, char *buf, int attr)
+{
+        struct battery_classdev *battery_cdev = class_get_devdata(dev);
+        ssize_t ret = 0;
+	long value;

There's some tab-vs-space noise here and elsewhere.

Quoted 4 lines
battery/battery-class.c new file +4 -0
+static ssize_t battery_attribute_show_milli(struct class_device *dev, char *buf, int attr)
+{
+        struct battery_classdev *battery_cdev = class_get_devdata(dev);
+        ssize_t ret = 0;

battery/battery-class.c line 58

Quoted 10 lines
battery/battery-class.c new file +10 -0
+	long value;
+
+	ret = battery_cdev->query_long(battery_cdev, attr, &value);
+	if (ret)
+		return ret;
+
+	sprintf(buf, "%ld.%03ld\n", value/1000, value % 1000);
+        ret = strlen(buf) + 1;
+        return ret;
+}

The sysfs spec (Documentation/hwmon/sysfs-interface) prescribes milli as integer, not simulated floating point ("All sysfs values are fixed point numbers"). Better follow that.

Quoted 7 lines
battery/battery-class.c new file +7 -0
+static ssize_t battery_attribute_show_status(struct class_device *dev, char *buf)
+{
+        struct battery_classdev *battery_cdev = class_get_devdata(dev);
+        ssize_t ret = 0;
+	unsigned long status;
+
+	status = battery_cdev->status(battery_cdev, ~BAT_STAT_AC);

battery/battery-class.c line 90

Quoted 10 lines
battery/battery-class.c new file +10 -0
+	if (status & BAT_STAT_ERROR)
+		return -EIO;
+
+	if (status & BAT_STAT_PRESENT)
+		sprintf(buf, "present");
+	else
+		sprintf(buf, "absent");
+
+	if (status & BAT_STAT_LOW)
+		strcat(buf, ",low");

I suggest a more sysfs-ish approach:

"present" attribute, containing 0 or 1.
"state" attribute, containing one of "charging","discharging" and "idle". "low" attribute, containing 0 or 1.
Et cetera.

battery/battery-class.c line 153

Quoted 7 lines
battery/battery-class.c new file +7 -0
+BATTERY_DEVICE_ATTR("temp1",TEMP1,milli);
+BATTERY_DEVICE_ATTR("temp1_name",TEMP1_NAME,string);
+BATTERY_DEVICE_ATTR("temp2",TEMP2,milli);
+BATTERY_DEVICE_ATTR("temp2_name",TEMP2_NAME,string);
+BATTERY_DEVICE_ATTR("voltage",VOLTAGE,milli);
+BATTERY_DEVICE_ATTR("voltage_design",VOLTAGE_DESIGN,milli);
+BATTERY_DEVICE_ATTR("current",CURRENT,milli);

The Smart Battery System spec
(http://www.sbs-forum.org/specs/sbdat110.pdf) defines two current
readouts: "Current()" for instantaneous value, and "AverageCurrent()" for a one-minute rolling average.

On ThinkPads, the value reported by ACPI is actually AverageCurrent(). Both values can be read by accessing the embedded controller (the tp_smapi out-of-tree driver does this). Both values are useful and can differ considerably.

I suggest having both "current_now" and "current_avg", as done in tp_smapi.

Quoted 1 line

+BATTERY_DEVICE_ATTR("charge_rate",CHARGE_RATE,milli);

There's a terminology issue here. "Charge" is problematic for two reasons:
First, it's inaccurate: many batteries report not electric charge (coulomb) but energy (watt-hour), and there are probably devices out there that report only percent.
Second, it's confusing to have "charge" both as a quantity and as an action.

The SBS spec takes pain to always refer to "capacity" or "charge capacity" as a generic term for energy or electric charge. I think "capacity" is a reasonable generic term, and tp_smapi follows it.

For this attribute, I suggest using "rate_{now,avg}", and defining it to use the same units as the capacity readouts.

In addition, there should be "power_{now,avg}" attributes which are always in watts regardless of the capacity readouts. This does not necessarily duplicate voltage * current_{now,avg}, because the hardware may be able to perform accurate integration over time.

Quoted 1 line

+BATTERY_DEVICE_ATTR("charge_max",CHARGE_MAX,milli);

SBS uses "DesignCapacity()" and tp_smapi uses "design_capacity". I suggest "capacity_design".

Quoted 1 line

+BATTERY_DEVICE_ATTR("charge_last",CHARGE_LAST,milli);

SBS uses "FullChargeCapacity()" and tp_smapi uses last_full_capacity. I suggest "capacity_last_full".

battery/battery-class.c line 159

Quoted 3 lines
battery/battery-class.c new file +3 -0
+BATTERY_DEVICE_ATTR("charge_low",CHARGE_LOW,milli);
+BATTERY_DEVICE_ATTR("charge_warn",CHARGE_WARN,milli);
+BATTERY_DEVICE_ATTR("charge_unit",CHARGE_UNITS,string);

s/charge/capacity/.
BTW, the SBS defines the possible capacity units (CAPACITY_MODE bit) as mAh and 10mWh. I guess the latter should be normalized by drivers to mWh where applicable.

Quoted 1 line

+BATTERY_DEVICE_ATTR("charge_percent",CHARGE_PCT,int);

Percent of what? SBS distinguishes between "RelativeStateOfCharge()" (percent of last full capacity") and "AbsoluteStateOfCharge()" (percent of design capacity).

I suggest defining it to be the former and calling it "capacity_percent".

Quoted 1 line

+BATTERY_DEVICE_ATTR("time_remaining",TIME_REMAINING,int);

Separate attributes are needed for "time to full charge" and "remaining time to full discharge". They're completely different things (and sysfs doesn't let you read the time and status atomically).

SBS defines "RunTimeToEmpty()", "AverageTimeToEmpty()" and "AverageTimeToFull()", which using my suggested convention would become:

time_to_empty_now
time_to_empty_avg
time_to_full

I guess SBS considered charging rate to be stable enough not to bother with average vs. instantaneous rates. However, with the OLPC hand/foot crank in mind, maybe we should have the full set:

time_to_empty_now
time_to_empty_avg
time_to_full_now
time_to_full_avg

Quoted 1 line

+BATTERY_DEVICE_ATTR("type",TYPE,string);

What's this?

Quoted 1 line

+BATTERY_DEVICE_ATTR("oem_info",OEM_INFO,string);

Tthe ThinkPad embedded controller battery interface also provides a "barcode" data, which is 13-character submodel identifer. Not sure if it should get a separate attribute, or appended to "model". FWIW, tp_smapi does the former.

There are also the following, defined in SBS and exposed by tp_smapi:
cycle_count
date_manufactured

And ThinkPads also have this non-SBS extension:
date_first_used

Do you intend to also encompass battery control commands? See here for what ThinkPads can do:
http://thinkwiki.org/wiki/Tp_smapi#Battery_charge_control_features

Shem

#20 lore raw
In reply to David Woodhouse

Hi!

Quoted 4 lines

At git://git.infradead.org/battery-2.6.git there is an initial implementation of a battery class, along with a driver which makes use of it. The patch is below, and also viewable at
http://git.infradead.org/?p=battery-2.6.git;a=commitdiff;h=master;hp=linus

Thanks a lot for this work.

Quoted 7 lines

I don't like the sysfs interaction much -- is it really necessary for me to provide a separate function for each attribute, rather than a single function which handles them all and is given the individual attribute as an argument? That seems strange and bloated.

I'm half tempted to ditch the sysfs attributes and just use a single seq_file, in fact.

No, please don't.

Pavel

Signature · 1 line
Thanks for all the (sleeping) penguins.