On Wed, 21 Nov 2018 17:33:02 PST (-0800), atish.patra@xxxxxxx 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
?
@@ -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
+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 restrict ourselves to the open-source IP for now, as versioning the
closed source stuff is a bit of a different problem -- when everyone can see
the source it's easier because we can all agree on exactly what a version
string means.
For the closed source stuff we currently have just the chip-specific strings,
as all that stuff is very chip specific (all sorts of special clocking
constraints). Essentially you'll have to just trust us as to what's compatible
with what -- FWIW, since this is mostly driven by the chip process we really
just have to trust the hardware designers, so we're kind of in the same boat
(though we can at least peek under the covers if we want to). Any versioning
scheme here is doubly complicated because it's closed source and it's chip
specific, so trying to match this up with the open source stuff seems like too
much work.
For now we can at least get everyone on the same page as to how we're
versioning the open-source blocks, which is more important because anyone can
build a chip with those so we need a well defined scheme.
