[PATCH v2 13/39] acpi: Add a binding for ACPI settings in the device tree

Thu Mar 12 04:24:02 CET 2020

Hi Wolfgang,

On Tue, 10 Mar 2020 at 03:15, Wolfgang Wallner <
wolfgang.wallner at br-automation.com> wrote:
>
> Hi Simon,
>
> -----"Simon Glass" <sjg at chromium.org> schrieb: -----
> >
> > Devices need to report various identifiers in the ACPI tables. Rather
than
> > hard-coding these in drivers it is typically better to put them in the
> > device tree.
> >
> > Add a binding file to describe this.
> >
> > Signed-off-by: Simon Glass <sjg at chromium.org>
> > ---
> >
> > Changes in v2:
> > - Fix definition of HID
> > - Infer hid-over-i2c CID value
> > - Add the hid-over-i2c binding document
> >
> >  doc/device-tree-bindings/device.txt           | 36 +++++++++++++++
> >  .../input/hid-over-i2c.txt                    | 44 +++++++++++++++++++
> >  2 files changed, 80 insertions(+)
> >  create mode 100644 doc/device-tree-bindings/device.txt
> >  create mode 100644 doc/device-tree-bindings/input/hid-over-i2c.txt
> >
> > diff --git a/doc/device-tree-bindings/device.txt
b/doc/device-tree-bindings/device.txt
> > new file mode 100644
> > index 0000000000..31ec2fa31b
> > --- /dev/null
> > +++ b/doc/device-tree-bindings/device.txt
> > @@ -0,0 +1,36 @@
> > +Devices
> > +=======
> > +
> > +Device bindings are described by their own individual binding files.
> > +
> > +U-Boot provides for some optional properties which are documented
here. See
> > +also hid-over-i2c.txt which describes HID devices.
> > +
> > + - acpi,has-power-resource : (boolean) true if this device has a power
resource.
> > +    This causes a PRIC (ACPI PowerResource) to be written containing
the
>
> What is the meaning of PRIC? I can't find a defition for this term.

I'll drop that.

>
> > +    properties provided by this binding, to describe how to handle
powering the
> > +    device up and down using GPIOs
> > + - acpi,compatible : compatible string to report
>
> What does "compatible string" mean in this context? Does it refer to the
> "Compatible ID" (_CID) of ACPI? As stated in the previous mail thread [1],
> I think we could infer many of the ACPI properties from existing device
tree
> properties. Especially I suspect that ACPI's _CID could have a 1:1 mapping
> to the compatible property in device tree. E.g. a driver which states that
> it is compatible with "hid-over-i2c" in its device tree description would
> know (implement internally) that it is also compatible with ACPI's _CID
> "PNP0C50", thus we would not have to add this information in the device
tree.

This is described to in the Linux binding file:

Documentation/acpi/enumeration.txt

The special DT namespace link device ID, PRP0001, provides a means to use
the
existing DT-compatible device identification in ACPI and to satisfy the
above
requirements following from the ACPI specification at the same time.
Namely,
if PRP0001 is returned by _HID, the ACPI subsystem will look for the
"compatible" property in the device object's _DSD and will use the value of
that
property to identify the corresponding device in analogy with the original
DT
device identification algorithm.  If the "compatible" property is not
present
or its value is not valid, the device will not be enumerated by the ACPI
subsystem.  Otherwise, it will be enumerated automatically as a platform
device
(except when an I2C or SPI link from the device to its parent is present, in
which case the ACPI core will leave the device enumeration to the parent's
driver) and the identification strings from the "compatible" property value
will
be used to find a driver for the device along with the device IDs listed by
_CID
(if present).

So we set acpi,hid to "PRP0001" and acpi,compatible to the device-tree
compatible string.

>
> [1] https://lists.denx.de/pipermail/u-boot/2020-February/398856.html
>
> > + - acpi,desc : Contains the string to use as the _DDN (DOS (Disk
Operating
> > +    System) Device Name)
>
> Nit: I assume "desc" stands for "description". But strictly speaking it is
> not a description, it is a device name. I would prefer something like
> "acpi,devname" or even "acpi,ddn".

OK we can go with acpi,ddn. I have been thinking about that as it is one
less mapping to know.

>
> > + - acpi,hid : Contains the string to use as the HID (Hardware ID)
> > +    identifier _HID
> > + - hid-descr-addr : HID register offset (for Human Interface Devices)
>
> This property is already described in the file hid-over-i2c.txt (with a
similar
> but slightly different text), thus I would not describe it here also.

Will drop.

>
> > + - acpi,probed : Tells U-Boot to add 'linux,probed' to the ACPI tables
so that
> > +    Linux will not re-init the device
>
> I can't find 'linux,probed' in the Linux kernel.
> I only find it in patches specific for chromium-os[2], but the description
> there does not match the description given here (there it is described as
> being probed before insertion vs. here it is described as not being probed
> any more).
>
> [2]
https://groups.google.com/a/chromium.org/forum/#!msg/chromium-os-reviews/4HTHl78IGHw/oz82uImnBgAJ

Yes it seems that this has not yet made it upstream to Linux.

I will fix the description.

>
> > + - acpi,uid : _UID value for device
> > +
> > +
> > +Example
> > +-------
> > +
> > +synaptics_touchpad: synaptics-touchpad at 2c {
> > +     compatible = "hid-over-i2c";
> > +     reg = <0x2c>;
> > +     acpi,hid = "PNP0C50";
> > +     acpi,desc = "Synaptics Touchpad";
> > +     interrupts-extended = <&acpi_gpe GPIO_18_IRQ
> > +                     IRQ_TYPE_EDGE_FALLING>;
> > +     acpi,probed;
> > +     hid-descr-addr = <0x20>;
> > +};
> > diff --git a/doc/device-tree-bindings/input/hid-over-i2c.txt
b/doc/device-tree-bindings/input/hid-over-i2c.txt
> > new file mode 100644
>
> Adding the file hid-over-i2c.txt is straight forward, while getting the
ACPI
> bindings correct is probably more tricky. Would it make sense to add this
file
> in an individual patch?

OK I'll split it.

>
> > index 0000000000..c76bafaf98
> > --- /dev/null
> > +++ b/doc/device-tree-bindings/input/hid-over-i2c.txt
>
> This file is taken from the Linux kernel, should this be stated at the
> beginning? (I often see "Taken from ..." in source code files, I'm not
sure
> how this is handled for documentation).

Yes we normally mention that.

>
> > @@ -0,0 +1,44 @@
> > +* HID over I2C Device-Tree bindings
> > +
> > +HID over I2C provides support for various Human Interface Devices over
the
> > +I2C bus. These devices can be for example touchpads, keyboards, touch
screens
> > +or sensors.
> > +
> > +The specification has been written by Microsoft and is currently
available here:
> > +http://msdn.microsoft.com/en-us/library/windows/hardware/hh852380.aspx
> > +
> > +If this binding is used, the kernel module i2c-hid will handle the
communication
> > +with the device and the generic hid core layer will handle the
protocol.
>
> This sentence is specific to the Linux kernel, and does not really apply
to
> U-Boot. I would propose one of the following:
>
> * Point out specifically that the Linux kernel is talked about
> * Drop the sentence
> * State at the beginning of the file that the file is taken unmodified
from the
>   Linux kernel

Yes it's funny that the bindings are supposed to describe hardware but
sometimes the software creeps in.

In fact binding files are always supposed to be unmodified, so I don't
think we can/should change it.

Regards,
Simon