1DT compatible string versioning for SiFive open-source IP blocks
2
3This document describes the version specification for DT "compatible"
4strings for open-source SiFive IP blocks.  HDL for these IP blocks
5can be found in this public repository:
6
7https://github.com/sifive/sifive-blocks
8
9IP block-specific DT compatible strings are contained within the HDL,
10in the form "sifive,<ip-block-name><integer version number>".
11
12An example is "sifive,uart0" from:
13
14https://github.com/sifive/sifive-blocks/blob/v1.0/src/main/scala/devices/uart/UART.scala#L43
15
16Until these IP blocks (or IP integration) support version
17auto-discovery, the maintainers of these IP blocks intend to increment
18the suffixed number in the compatible string whenever the software
19interface to these IP blocks changes, or when the functionality of the
20underlying IP blocks changes in a way that software should be aware of.
21
22Driver developers can use compatible string "match" values such as
23"sifive,uart0" to indicate that their driver is compatible with the
24register interface and functionality associated with the relevant
25upstream sifive-blocks commits.  It is expected that most drivers will
26match on these IP block-specific compatible strings.
27
28DT data authors, when writing data for a particular SoC, should
29continue to specify an SoC-specific compatible string value, such as
30"sifive,fu540-c000-uart".  This way, if SoC-specific
31integration-specific bug fixes or workarounds are needed, the kernel
32or other system software can match on this string to apply them.  The
33IP block-specific compatible string (such as "sifive,uart0") should
34then be specified as a subsequent value.
35
36An example of this style:
37
38    compatible = "sifive,fu540-c000-uart", "sifive,uart0";
39