0001 DT compatible string versioning for SiFive open-source IP blocks
0002
0003 This document describes the version specification for DT "compatible"
0004 strings for open-source SiFive IP blocks. HDL for these IP blocks
0005 can be found in this public repository:
0006
0007 https://github.com/sifive/sifive-blocks
0008
0009 IP block-specific DT compatible strings are contained within the HDL,
0010 in the form "sifive,<ip-block-name><integer version number>".
0011
0012 An example is "sifive,uart0" from:
0013
0014 https://github.com/sifive/sifive-blocks/blob/v1.0/src/main/scala/devices/uart/UART.scala#L43
0015
0016 Until these IP blocks (or IP integration) support version
0017 auto-discovery, the maintainers of these IP blocks intend to increment
0018 the suffixed number in the compatible string whenever the software
0019 interface to these IP blocks changes, or when the functionality of the
0020 underlying IP blocks changes in a way that software should be aware of.
0021
0022 Driver developers can use compatible string "match" values such as
0023 "sifive,uart0" to indicate that their driver is compatible with the
0024 register interface and functionality associated with the relevant
0025 upstream sifive-blocks commits. It is expected that most drivers will
0026 match on these IP block-specific compatible strings.
0027
0028 DT data authors, when writing data for a particular SoC, should
0029 continue to specify an SoC-specific compatible string value, such as
0030 "sifive,fu540-c000-uart". This way, if SoC-specific
0031 integration-specific bug fixes or workarounds are needed, the kernel
0032 or other system software can match on this string to apply them. The
0033 IP block-specific compatible string (such as "sifive,uart0") should
0034 then be specified as a subsequent value.
0035
0036 An example of this style:
0037
0038 compatible = "sifive,fu540-c000-uart", "sifive,uart0";
