[PATCH 6/8] arm64: dts: qcom: msm8916-pm8916: Clarify purpose

[Stephan Gerhold <stephan@gerhold.net>]

Goal of the msm8916-pm8916.dtsi is to reduce the boilerplate necessary
to create a device tree for a typical board with the MSM8916 SoC
combined with the PM8916 PMIC. > 99% of all MSM8916 boards use the same
standard setup where many of the PM8916 regulators have a fixed purpose
and only some are left up for board-specific use.

While MSM8916 (and perhaps MSM8939 soon) is currently the only platform
with such an include, it has definitely proven useful. With more than
30 boards using it (not all of them upstream yet) it simplifies the
review a lot and reduces the chance of configuring the standard
components incorrectly.

In preparation of extending its scope slightly, add a comment at the
top that clearly explains what the .dtsi represents and when it should
(or should not) be used.

Signed-off-by: Stephan Gerhold <stephan@gerhold.net>
---
 arch/arm64/boot/dts/qcom/msm8916-pm8916.dtsi | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/arch/arm64/boot/dts/qcom/msm8916-pm8916.dtsi b/arch/arm64/boot/dts/qcom/msm8916-pm8916.dtsi
index 5b3ed7137e1f..29ef46c33350 100644
--- a/arch/arm64/boot/dts/qcom/msm8916-pm8916.dtsi
+++ b/arch/arm64/boot/dts/qcom/msm8916-pm8916.dtsi
@@ -1,4 +1,12 @@
 // SPDX-License-Identifier: GPL-2.0-only
+/*
+ * msm8916-pm8916.dtsi describes common properties (e.g. regulator connections)
+ * that apply to most devices that make use of the MSM8916 SoC and PM8916 PMIC.
+ * Many regulators have a fixed purpose in the original reference design and
+ * were rarely re-used for different purposes. Devices that deviate from the
+ * typical reference design should not make use of this include and instead add
+ * the necessary properties in the board-specific device tree.
+ */
 
 #include "msm8916.dtsi"
 #include "pm8916.dtsi"

-- 
2.40.1