Hi Atish, On Wed, 21 Nov 2018, Atish Patra wrote: > On 11/21/18 5:07 PM, Paul Walmsley wrote: > > > > For IP blocks that are generated from the public, open-source > > sifive-blocks repository, describe the version numbering policy > > that its maintainers intend to use, upon request from Rob > > Herring <robh@xxxxxxxxxx>. > > > > Cc: Rob Herring <robh+dt@xxxxxxxxxx> > > Cc: Palmer Dabbelt <palmer@xxxxxxxxxx> > > Cc: Megan Wachs <megan@xxxxxxxxxx> > > Cc: Wesley Terpstra <wesley@xxxxxxxxxx> > > Cc: Mark Rutland <mark.rutland@xxxxxxx> > > Cc: devicetree@xxxxxxxxxxxxxxx > > Cc: linux-riscv@xxxxxxxxxxxxxxxxxxx > > Cc: linux-kernel@xxxxxxxxxxxxxxx > > Signed-off-by: Paul Walmsley <paul.walmsley@xxxxxxxxxx> > > Signed-off-by: Paul Walmsley <paul@xxxxxxxxx> > > --- > > > > Hi Rob, please let me know if this document works with your > > requirements, or if some changes are needed. - Paul > > > > .../sifive/sifive-blocks-ip-versioning.txt | 38 +++++++++++++++++++ > > 1 file changed, 38 insertions(+) > > create mode 100644 > > Documentation/devicetree/bindings/sifive/sifive-blocks-ip-versioning.txt > > > > diff --git > > a/Documentation/devicetree/bindings/sifive/sifive-blocks-ip-versioning.txt > > b/Documentation/devicetree/bindings/sifive/sifive-blocks-ip-versioning.txt > > new file mode 100644 > > index 000000000000..b899e5c6e00c > > --- /dev/null > > +++ > > b/Documentation/devicetree/bindings/sifive/sifive-blocks-ip-versioning.txt > > It should be be under > Documentation/devicetree/bindings/riscv/sifive/sifive-blocks-ip-versioning.txt > ? These IP blocks could be used with any CPU architecture - ARM, x86, MIPS, etc. - so it probably makes sense just to keep them under sifive/, rather than associating them with a specific CPU architecture. > > @@ -0,0 +1,38 @@ > > +DT compatible string versioning for SiFive open-source IP blocks > > + > > +This document describes the version specification for DT "compatible" > > +strings for open-source SiFive IP blocks. HDL for these IP blocks > > +can be found in this public repository: > > + > > +https://github.com/sifive/sifive-blocks > > + > > +IP block-specific DT compatible strings are contained within the HDL, > > +in the form "sifive,<ip-block-name><integer version number>". > > + > > +An example is "sifive,uart0" from: > > + > > +https://github.com/sifive/sifive-blocks/blob/master/src/main/scala/devices/uart/UART.scala#L43 > > + > > +Until these IP blocks (or IP integration) support version > > +autodiscovery, the maintainers of these IP blocks intend to increment > > /s/autodiscovery/auto discovery I've changed it to "auto-discovery" per your request. Let me know if it's not OK for you > > +the suffixed number in the compatible string whenever the software > > +interface to these IP blocks changes, or when the functionality of the > > +underlying IP blocks changes in a way that software should be aware of. > > + > > +Driver developers can use compatible string "match" values such as > > +"sifive,uart0" to indicate that their driver is compatible with the > > +register interface and functionality associated with the relevant > > +upstream sifive-blocks commits. It is expected that most drivers will > > +match on these IP block-specific compatible strings. > > + > > +DT data authors, when writing data for a particular SoC, should > > +continue to specify an SoC-specific compatible string value, such as > > +"sifive,fu540-c000-uart". This way, if SoC-specific > > +integration-specific bug fixes or workarounds are needed, the kernel > > +or other system software can match on this string to apply them. The > > +IP block-specific compatible string (such as "sifive,uart0") should > > +then be specified as a subsequent value. > > + > > +An example of this style: > > + > > + compatible = "sifive,fu540-c000-uart", "sifive,uart0"; > > > > Just for the sake of completion, should this document also specify what should > be the style of any possible closed IP as well? Let's handle those separately, as Palmer discussed. Thanks for the review, - Paul
