On Thu, Mar 16, 2017 at 1:45 AM, Liam Breck <liam@xxxxxxxxxxxxxxxxx> wrote: > On Wed, Mar 15, 2017 at 4:50 PM, Rob Herring <robh@xxxxxxxxxx> wrote: >> On Wed, Mar 15, 2017 at 5:04 PM, Liam Breck <liam@xxxxxxxxxxxxxxxxx> wrote: >>> On Wed, Mar 15, 2017 at 1:10 PM, Rob Herring <robh@xxxxxxxxxx> wrote: >>>> On Thu, Mar 2, 2017 at 12:31 PM, Liam Breck <liam@xxxxxxxxxxxxxxxxx> wrote: >>>>> Hi Rob, >>>>> >>>>> On Thu, Mar 2, 2017 at 7:14 AM, Rob Herring <robh@xxxxxxxxxx> wrote: >>>>>> On Sun, Feb 26, 2017 at 11:11:09PM -0800, Liam Breck wrote: >>>>>>> From: Liam Breck <kernel@xxxxxxxxxxxxxxxxx> >>>>>>> >>>>>>> Documentation of static battery characteristics that can be defined >>>>>>> for batteries which cannot self-identify. This information is required >>>>>>> by fuel-gauge and charger chips for proper handling of the battery. >>>>>>> >>>>>>> Cc: Rob Herring <robh@xxxxxxxxxx> >>>>>>> Cc: devicetree@xxxxxxxxxxxxxxx >>>>>>> Signed-off-by: Matt Ranostay <matt@ranostay.consulting> >>>>>>> Signed-off-by: Liam Breck <kernel@xxxxxxxxxxxxxxxxx> >>>>>>> --- >>>>>>> .../devicetree/bindings/power/supply/battery.txt | 42 ++++++++++++++++++++++ >>>>>>> 1 file changed, 42 insertions(+) >>>>>>> create mode 100644 Documentation/devicetree/bindings/power/supply/battery.txt >>>>>>> >>>>>>> diff --git a/Documentation/devicetree/bindings/power/supply/battery.txt b/Documentation/devicetree/bindings/power/supply/battery.txt >>>>>>> new file mode 100644 >>>>>>> index 0000000..3d916bd >>>>>>> --- /dev/null >>>>>>> +++ b/Documentation/devicetree/bindings/power/supply/battery.txt >>>>>>> @@ -0,0 +1,42 @@ >>>>>>> +Battery Characteristics >>>>>>> + >>>>>>> +Required Properties: >>>>>>> + - compatible: Must be "fixed-battery" >>>>>> >>>>>> Still not liking this name, but I don't have a better suggestion. Please >>>>>> describe here what is and isn't a "fixed battery". >>>>> >>>>> Sebastian...? >>>>> >>>>>>> + >>>>>>> +Optional Properties: >>>>>>> + - voltage-min-design-microvolt: drained battery voltage >>>>>>> + - energy-full-design-microwatt-hours: battery design energy >>>>>>> + - charge-full-design-microamp-hours: battery design capacity >>>>>>> + >>>>>>> +Future Properties must be named for the corresponding elements in >>>>>>> +enum power_supply_property, defined in include/linux/power_supply.h. >>>>>> >>>>>> Um, no. That's exactly not how DT bindings should be done. >>>>> >>>>> Power supply components surface stats in sysfs using the names in enum >>>>> power_supply_property. For example, >>>>> /sys/class/power_supply/.../voltage_min_design. Matching input (DT) >>>>> and output (sysfs) names is sensible. The above comment is already >>>>> attached to struct power_supply_battery_info, which is the initial >>>>> destination for the above DT properties. >>>>> >>>>> Shall I mention sysfs in the above comment? >>>> >>>> Absolutely not. Bindings should not reference Linux. >>>> >>>> While sometimes things can align, there is no guarantee that they >>>> will. DT is h/w description. sysfs is user configuration. >>> >>> sysfs for power_supply also provides fixed hw characteristics. >>> >>> Sebastian proposed DT:battery specifically to be consumed by >>> power_supply_core. Allowing names in DT:battery and >>> power_supply_property to diverge would cause confusion and wasted >>> time, for no particular benefit. As there is no rationale to >>> reconsider the names of these fields for DT:battery, let's write that >>> into the docs. >> >> Write it into the Linux docs then. The DT docs need to stand on their >> own for the standalone DT tree[1] that other projects import. > > We will document it on the Linux side. But referencing a Linux header > file as the origin of property names in DT;battery does not create a > Linux dependency for standalone DT. It merely clarifies the naming > scheme. Perhaps, but it doesn't help the perception that bindings located in the kernel tree are "kernel bindings". The policy is bindings should stand on their own. > Also a huge number of DT bindings are Linux-specific, as they are > implemented by some kernel driver. Do you plan to rip those out of > devicetree-rebasing? Care to highlight some? I'm aware of a few cases, but hardly a "huge number". I hear lots of complaints of bindings/dts's being Linux specific, but no specific examples nor attempts to fix those cases. I'd happily take patches to at least mark bad or linux specific bindings. Rob -- To unsubscribe from this list: send the line "unsubscribe devicetree" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
