From mboxrd@z Thu Jan 1 00:00:00 1970 From: Simon Glass Date: Wed, 11 Mar 2020 21:24:02 -0600 Subject: [PATCH v2 13/39] acpi: Add a binding for ACPI settings in the device tree In-Reply-To: References: <20200309034504.149659-1-sjg@chromium.org> <20200308214442.v2.13.I7842b2dd0d6b475301fc044c6640d8089873053f@changeid> Message-ID: List-Id: MIME-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit To: u-boot@lists.denx.de Hi Wolfgang, On Tue, 10 Mar 2020 at 03:15, Wolfgang Wallner < wolfgang.wallner@br-automation.com> wrote: > > Hi Simon, > > -----"Simon Glass" 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 > > --- > > > > 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