Skip to contentSkip to conversation

dt-bindings: add IP versioning document for Microchip FPGAs

RFC In review Conor Dooley 4 participants 5 messages Aug 30, 2024 – Sep 9, 2024 Device tree bindings

lore
Share & tools
lore
#0 lore raw

RFC 1/1 dt-bindings: add IP versioning document for Microchip FPGAs

From: Conor Dooley <[email protected]>

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.

---
cc: [email protected]
CC: [email protected]
CC: [email protected]
CC: Rob Herring <[email protected]>
CC: Krzysztof Kozlowski <[email protected]>
CC: Conor Dooley <[email protected]>
CC: [email protected]
CC: [email protected]

---
 .../bindings/microchip/ip-versioning.txt      | 34 +++++++++++++++++++
 1 file changed, 34 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/microchip/ip-versioning.txt
Documentation/devicetree/bindings/microchip/ip-versioning.txt new file +34 -0
new file mode 100644
index 000000000000..4a4e0e74c4e6
@@ -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";
Signature · 1 line
2.45.2
#1 lore raw
Quoted 8 lines · Conor Dooley

From: Conor Dooley <[email protected]>

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

#2 lore raw
Quoted 10 lines · Krzysztof Kozlowski
Quoted 8 lines · Conor Dooley

From: Conor Dooley <[email protected]>

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.

Quoted 2 lines

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.

maintainer
#3 lore raw
In reply to Conor Dooley
Quoted 33 lines · Conor Dooley

From: Conor Dooley <[email protected]>

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.

---
cc: [email protected]
CC: [email protected]
CC: [email protected]
CC: Rob Herring <[email protected]>
CC: Krzysztof Kozlowski <[email protected]>
CC: Conor Dooley <[email protected]>
CC: [email protected]
CC: [email protected]

---
 .../bindings/microchip/ip-versioning.txt      | 34 +++++++++++++++++++
 1 file changed, 34 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/microchip/ip-versioning.txt
Documentation/devicetree/bindings/microchip/ip-versioning.txt new file +4 -0
new file mode 100644
index 000000000000..4a4e0e74c4e6
@@ -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.

Documentation/devicetree/bindings/microchip/ip-versioning.txt line 14

Quoted 10 lines
Documentation/devicetree/bindings/microchip/ip-versioning.txt new file +10 -0
+
+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

#4 lore raw
Quoted 38 lines · Rob Herring
Quoted 37 lines · Conor Dooley

From: Conor Dooley <[email protected]>

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.

---
cc: [email protected]
CC: [email protected]
CC: [email protected]
CC: Rob Herring <[email protected]>
CC: Krzysztof Kozlowski <[email protected]>
CC: Conor Dooley <[email protected]>
CC: [email protected]
CC: [email protected]

---
 .../bindings/microchip/ip-versioning.txt      | 34 +++++++++++++++++++
 1 file changed, 34 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/microchip/ip-versioning.txt
Documentation/devicetree/bindings/microchip/ip-versioning.txt new file +8 -0
new file mode 100644
index 000000000000..4a4e0e74c4e6
@@ -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:
Quoted 8 lines

Documentation/devicetree/bindings/microchip/ip-versioning.txt line 14

Quoted 6 lines
Documentation/devicetree/bindings/microchip/ip-versioning.txt new file +6 -0
+"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.