[RFC v1] dt-bindings: add IP versioning document for Microchip FPGAs

[RFC v1] dt-bindings: add IP versioning document for Microchip FPGAs

[Conor Dooley]

From: Conor Dooley <conor.dooley@microchip.com>

This is a pretty rough document I conjured up in 5 minutes, to document
my expectations for compatible strings for both our FPGA IP blocks and
reference designs that we ship, a la the one that exists for SiFive IPs.
There's been some internal conversations lately about this naming etc,
so good to have something written down.

Signed-off-by: Conor Dooley <conor.dooley@microchip.com>
---
cc: cyril.jean@microchip.com
CC: valentina.fernandezalanis@microchip.com
CC: nitin.deshpande@microchip.com
CC: Rob Herring <robh@kernel.org>
CC: Krzysztof Kozlowski <krzk+dt@kernel.org>
CC: Conor Dooley <conor+dt@kernel.org>
CC: devicetree@vger.kernel.org
CC: linux-kernel@vger.kernel.org
---
 .../bindings/microchip/ip-versioning.txt      | 34 +++++++++++++++++++
 1 file changed, 34 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/microchip/ip-versioning.txt

diff --git a/Documentation/devicetree/bindings/microchip/ip-versioning.txt b/Documentation/devicetree/bindings/microchip/ip-versioning.txt
new file mode 100644
index 000000000000..4a4e0e74c4e6
--- /dev/null
+++ b/Documentation/devicetree/bindings/microchip/ip-versioning.txt
@@ -0,0 +1,34 @@
+Devicetree compatible string versioning for Microchip FPGA IP blocks and reference designs
+
+This document describes the versioning guidelines for compatible strings
+used on Microchip FPGA IP blocks and reference designs.
+
+IP block-specific compatible strings are in the form:
+"microchip,<ip-block-name>-rtl-v<major version number>"
+or optionally:
+"microchip,<ip-block-name>-rtl-v<major version number>.<minor version number>"
+
+<ip-block-name> should be the name of the IP in Libero's IP catalog.
+In most cases a major version should be sufficient, as breaking changes are
+intended to be accompanied by a version update, but if not, the optional minor
+version should be used,
+
+An example is:
+  compatible = "microchip,corei2c-rtl-v7";
+
+If the IP is integrated as a "hard" peripheral in an SoC, the expectation is
+that there will be a fallback to the IP block it was derived from, if
+appropriate, such as:
+  compatible = "microchip,mpfs-i2c", "microchip,corei2c-rtl-v7";
+
+The versioning scheme for reference designs that Microchip provides for its
+development kits is similar:
+"microchip,<soc>-<board>-reference-rtl-v<yymm>".
+
+This should be followed by a fallback compatible belonging to the board itself:
+"microchip,<soc>-<board>"
+and then one for the soc:
+"microchip,<soc>"
+
+For example:
+  compatible = "microchip,mpfs-icicle-reference-rtl-v2210", "microchip,mpfs-icicle-kit", "microchip,mpfs";
-- 
2.45.2

Re: [RFC v1] dt-bindings: add IP versioning document for Microchip FPGAs

[Krzysztof Kozlowski]

On Fri, Aug 30, 2024 at 05:00:40PM +0100, Conor Dooley wrote:
> From: Conor Dooley <conor.dooley@microchip.com>
> 
> This is a pretty rough document I conjured up in 5 minutes, to document
> my expectations for compatible strings for both our FPGA IP blocks and
> reference designs that we ship, a la the one that exists for SiFive IPs.
> There's been some internal conversations lately about this naming etc,
> so good to have something written down.
> 

You can try to make it a schema. Take a peak at:
Documentation/devicetree/bindings/arm/qcom-soc.yaml


Best regards,
Krzysztof

Re: [RFC v1] dt-bindings: add IP versioning document for Microchip FPGAs

[Rob Herring]

On Fri, Aug 30, 2024 at 05:00:40PM +0100, Conor Dooley wrote:
> From: Conor Dooley <conor.dooley@microchip.com>
> 
> This is a pretty rough document I conjured up in 5 minutes, to document
> my expectations for compatible strings for both our FPGA IP blocks and
> reference designs that we ship, a la the one that exists for SiFive IPs.
> There's been some internal conversations lately about this naming etc,
> so good to have something written down.
> 
> Signed-off-by: Conor Dooley <conor.dooley@microchip.com>
> ---
> cc: cyril.jean@microchip.com
> CC: valentina.fernandezalanis@microchip.com
> CC: nitin.deshpande@microchip.com
> CC: Rob Herring <robh@kernel.org>
> CC: Krzysztof Kozlowski <krzk+dt@kernel.org>
> CC: Conor Dooley <conor+dt@kernel.org>
> CC: devicetree@vger.kernel.org
> CC: linux-kernel@vger.kernel.org
> ---
>  .../bindings/microchip/ip-versioning.txt      | 34 +++++++++++++++++++
>  1 file changed, 34 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/microchip/ip-versioning.txt
> 
> diff --git a/Documentation/devicetree/bindings/microchip/ip-versioning.txt b/Documentation/devicetree/bindings/microchip/ip-versioning.txt
> new file mode 100644
> index 000000000000..4a4e0e74c4e6
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/microchip/ip-versioning.txt
> @@ -0,0 +1,34 @@
> +Devicetree compatible string versioning for Microchip FPGA IP blocks and reference designs
> +
> +This document describes the versioning guidelines for compatible strings
> +used on Microchip FPGA IP blocks and reference designs.
> +
> +IP block-specific compatible strings are in the form:
> +"microchip,<ip-block-name>-rtl-v<major version number>"
> +or optionally:
> +"microchip,<ip-block-name>-rtl-v<major version number>.<minor version number>"
> +
> +<ip-block-name> should be the name of the IP in Libero's IP catalog.
> +In most cases a major version should be sufficient, as breaking changes are
> +intended to be accompanied by a version update, but if not, the optional minor
> +version should be used,

Please cover where do version numbers come from?

Rob

Re: [RFC v1] dt-bindings: add IP versioning document for Microchip FPGAs

[Conor Dooley]

[-- Attachment #1: Type: text/plain, Size: 2485 bytes --]

On Tue, Sep 03, 2024 at 09:59:43AM -0500, Rob Herring wrote:
> On Fri, Aug 30, 2024 at 05:00:40PM +0100, Conor Dooley wrote:
> > From: Conor Dooley <conor.dooley@microchip.com>
> > 
> > This is a pretty rough document I conjured up in 5 minutes, to document
> > my expectations for compatible strings for both our FPGA IP blocks and
> > reference designs that we ship, a la the one that exists for SiFive IPs.
> > There's been some internal conversations lately about this naming etc,
> > so good to have something written down.
> > 
> > Signed-off-by: Conor Dooley <conor.dooley@microchip.com>
> > ---
> > cc: cyril.jean@microchip.com
> > CC: valentina.fernandezalanis@microchip.com
> > CC: nitin.deshpande@microchip.com
> > CC: Rob Herring <robh@kernel.org>
> > CC: Krzysztof Kozlowski <krzk+dt@kernel.org>
> > CC: Conor Dooley <conor+dt@kernel.org>
> > CC: devicetree@vger.kernel.org
> > CC: linux-kernel@vger.kernel.org
> > ---
> >  .../bindings/microchip/ip-versioning.txt      | 34 +++++++++++++++++++
> >  1 file changed, 34 insertions(+)
> >  create mode 100644 Documentation/devicetree/bindings/microchip/ip-versioning.txt
> > 
> > diff --git a/Documentation/devicetree/bindings/microchip/ip-versioning.txt b/Documentation/devicetree/bindings/microchip/ip-versioning.txt
> > new file mode 100644
> > index 000000000000..4a4e0e74c4e6
> > --- /dev/null
> > +++ b/Documentation/devicetree/bindings/microchip/ip-versioning.txt
> > @@ -0,0 +1,34 @@
> > +Devicetree compatible string versioning for Microchip FPGA IP blocks and reference designs
> > +
> > +This document describes the versioning guidelines for compatible strings
> > +used on Microchip FPGA IP blocks and reference designs.
> > +
> > +IP block-specific compatible strings are in the form:
> > +"microchip,<ip-block-name>-rtl-v<major version number>"
> > +or optionally:
> > +"microchip,<ip-block-name>-rtl-v<major version number>.<minor version number>"
> > +
> > +<ip-block-name> should be the name of the IP in Libero's IP catalog.
> > +In most cases a major version should be sufficient, as breaking changes are
> > +intended to be accompanied by a version update, but if not, the optional minor
> > +version should be used,
> 
> Please cover where do version numbers come from?

From the IP itself, it's either listed in the catalog entry or in the
information for the instance. I'll have to double check exactly where it
can be found, but that is the source.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [RFC v1] dt-bindings: add IP versioning document for Microchip FPGAs

[Conor Dooley]

[-- Attachment #1: Type: text/plain, Size: 931 bytes --]

On Sat, Aug 31, 2024 at 08:45:06AM +0200, Krzysztof Kozlowski wrote:
> On Fri, Aug 30, 2024 at 05:00:40PM +0100, Conor Dooley wrote:
> > From: Conor Dooley <conor.dooley@microchip.com>
> > 
> > This is a pretty rough document I conjured up in 5 minutes, to document
> > my expectations for compatible strings for both our FPGA IP blocks and
> > reference designs that we ship, a la the one that exists for SiFive IPs.
> > There's been some internal conversations lately about this naming etc,
> > so good to have something written down.
> > 
> 
> You can try to make it a schema. Take a peak at:
> Documentation/devicetree/bindings/arm/qcom-soc.yaml

Sure, I don't mind doing that - however given the breadth of microchip's
portfolio (and thus naming schemes) there may actually be little by way
of enforcement gained by making it into a binding. I'll give it a go and
see how permissive it ends up having to be.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]