Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1753432AbdLNQYZ (ORCPT ); Thu, 14 Dec 2017 11:24:25 -0500 Received: from mail-qt0-f196.google.com ([209.85.216.196]:38560 "EHLO mail-qt0-f196.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1753090AbdLNQYV (ORCPT ); Thu, 14 Dec 2017 11:24:21 -0500 X-Google-Smtp-Source: ACJfBovre56zV4bnG/pBx6NKEsOyoYFOLycJ7AsrR2Pc4tEDYDOyzJ/9DtycLenRkC2xxBZpntGW+1v2I3GYui0wSdI= MIME-Version: 1.0 In-Reply-To: <20171214151610.19153-6-boris.brezillon@free-electrons.com> References: <20171214151610.19153-1-boris.brezillon@free-electrons.com> <20171214151610.19153-6-boris.brezillon@free-electrons.com> From: Geert Uytterhoeven Date: Thu, 14 Dec 2017 17:24:19 +0100 X-Google-Sender-Auth: CPbaIiraYd7z3BUveUC7ruYWSZg Message-ID: Subject: Re: [PATCH v2 5/7] dt-bindings: i3c: Document core bindings To: Boris Brezillon Cc: Wolfram Sang , Linux I2C , Jonathan Corbet , linux-doc@vger.kernel.org, Greg Kroah-Hartman , Arnd Bergmann , Przemyslaw Sroka , Arkadiusz Golec , Alan Douglas , Bartosz Folta , Damian Kos , Alicja Jurasik-Urbaniak , Cyprian Wronka , Suresh Punnoose , Thomas Petazzoni , Nishanth Menon , Rob Herring , Pawel Moll , Mark Rutland , Ian Campbell , Kumar Gala , devicetree@vger.kernel.org, Linux Kernel Mailing List , Vitor Soares , Linus Walleij Content-Type: text/plain; charset="UTF-8" Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Length: 4904 Lines: 140 Hi Boris, On Thu, Dec 14, 2017 at 4:16 PM, Boris Brezillon wrote: > A new I3C subsystem has been added and a generic description has been > created to represent the I3C bus and the devices connected on it. > > Document this generic representation. > > Signed-off-by: Boris Brezillon Thanks for your patch! > --- /dev/null > +++ b/Documentation/devicetree/bindings/i3c/i3c.txt > @@ -0,0 +1,128 @@ > +Generic device tree bindings for I3C busses > +=========================================== > + > +This document describes generic bindings that should be used to describe I3C > +busses in a device tree. > + > +Required properties > +------------------- > + > +- #address-cells - should be <1>. Read more about addresses below. > +- #size-cells - should be <0>. > +- compatible - name of I3C bus controller following generic names > + recommended practice. > + > +For other required properties e.g. to describe register sets, > +clocks, etc. check the binding documentation of the specific driver. > + > +Optional properties > +------------------- > + > +These properties may not be supported by all I3C master drivers. Each I3C > +master bindings should specify which of them are supported. > + > +- i3c-scl-frequency: frequency (in Hz) of the SCL signal used for I3C > + transfers. When undefined the core set it to 12.5MHz. sets > + > +- i2c-scl-frequency: frequency (in Hz) of the SCL signal used for I2C > + transfers. When undefined, the core looks at LVR values LVR (Legacy I2C Virtual Register) > + of I2C devices described in the device tree to determine > + the maximum I2C frequency. > + > +I2C devices > +=========== > + > +Each I2C device connected to the bus should be described in a subnode with > +the following properties: This colon looks a bit funny here, as below is a sentence, not a list. > + > +All properties described in Documentation/devicetree/bindings/i2c/i2c.txt are > +valid here. Perhaps rewrite as: Each I2C device connected to the bus should be described in a subnode with properties. All properties described in Documentation/devicetree/bindings/i2c/i2c.txt are valid here, but several new properties have been added. > + > +New required properties: > +------------------------ > +- i3c-lvr: 32 bits integer property (only the lowest 8 bits are meaningful) > + describing device capabilities as described in the I3C > + specification. > + > + bit[31:8]: unused > + bit[7:5]: I2C device index. Possible values > + * 0: I2C device has a 50 ns spike filter > + * 1: I2C device does not have a 50 ns spike filter but supports high > + frequency on SCL > + * 2: I2C device does not have a 50 ns spike filter and is not > + tolerant to high frequencies > + * 3-7: reserved > + > + bit[4]: tell whether the device operates in FM or FM+ mode > + * 0: FM+ mode > + * 1: FM mode As this is the only reference to "FM", perhaps clarify the acronym, like you do for DAA below. > + > + bit[3:0]: device type > + * 0-15: reserved > + > +I3C devices > +=========== > + > +All I3C devices are supposed to support DAA (Dynamic Address Assignment), and > +are thus discoverable. So, by default, I3C devices do not have to be described > +in the device tree. > +This being said, one might want to attach extra resources to these devices, > +and those resources may have to be described in the device tree, which in turn > +means we have to describe I3C devices. > + > +Another use case for describing an I3C device in the device tree is when this > +I3C device has a static address and we want to assign it a specific dynamic > +address before the DAA takes place (so that other devices on the bus can't > +take this dynamic address). > + > +Required properties > +------------------- > +- i3c-pid: PID (Provisional ID). 64-bit property which is used to match a > + device discovered during DAA with its device tree definition. The > + PID is supposed to be unique on a given bus, which guarantees a 1:1 > + match. This property becomes optional if a reg property is defined, > + meaning that the device has a static address. > + > +Optional properties > +------------------- > +- reg: static address. Only valid is the device has a static address. if -- Gr{oetje,eeting}s, Geert -- Geert Uytterhoeven -- There's lots of Linux beyond ia32 -- geert@linux-m68k.org In personal conversations with technical people, I call myself a hacker. But when I'm talking to journalists I just say "programmer" or something like that. -- Linus Torvalds