dts: binding-template: document conditions for use of default values
The YAML binding allows for a default which is used to substitute a
value if one is not explicit in the devicetree source. This feature
is mis-used when defaults are provided that are likely to be
incorrect.
Document concerns with the use of default and provide guidance for
when it can be used, what to do when it shouldn't, and noting the need
to explain the source of the default in the binding documentation.
Signed-off-by: Peter Bigot <peter.bigot@nordicsemi.no>
diff --git a/dts/binding-template.yaml b/dts/binding-template.yaml
index 7e5e144..3807062 100644
--- a/dts/binding-template.yaml
+++ b/dts/binding-template.yaml
@@ -205,6 +205,11 @@
# foo = <&label1 1 2>, <&label2 3 4>; // Okay for 'type: phandle-array'
# etc.
#
+# A property with 'deprecated: True' indicates to both the user and the tooling
+# that the property is meant to be phased out. The tooling will report a
+# warning if the devicetree includes the property that is flagged as deprecated.
+# There will be no other impact to having 'deprecated: True' set on the property.
+#
# The optional 'default:' setting gives a value that will be used if the
# property is missing from the device tree node. If 'default: <default>' is
# given for a property <prop> and <prop> is missing, then the output will be as
@@ -214,10 +219,27 @@
# Note that it only makes sense to combine 'default:' with 'required: false'.
# Combining it with 'required: true' will raise an error.
#
-# A property with 'deprecated: True' indicates to both the user and the tooling
-# that the property is meant to be phased out. The tooling will report a
-# warning if the devicetree includes the property that is flagged as deprecated.
-# There will be no other impact to having 'deprecated: True' set on the property.
+# There is a risk in using 'default:' when the value in the binding may be
+# incorrect for a particular board or hardware configuration. For example,
+# defaulting the capacity of the connected power cell in a charging IC binding
+# is likely to be incorrect. For such properties it's better to make the
+# property 'required: true', forcing the devicetree maintainer into an explicit
+# and witting choice.
+#
+# Driver developers should use their best judgment as to whether a value can be
+# safely defaulted. Candidates for default values include delays that would
+# different only under unusual conditions (such as intervening hardware), or
+# configuration for devices that have a standard initial configuration (such as
+# a USB audio headset).
+#
+# Properties may also be defaulted to the vendor-specified power-up default as
+# long as they're independent. If changing one property would require changing
+# another to create a consistent configuration then those properties should be
+# made required.
+#
+# In any case where 'default:' is used the property documentation should
+# explain why the value was selected and any conditions that would make it
+# necessary to provide a different value.
#
# See below for examples of 'default:'. Putting 'default:' on any property type
# besides those used in the examples will raise an error.
@@ -258,6 +280,7 @@
type: int
required: false
default: 123
+ description: Value for int register, default is power-up configuration.
array-with-default:
type: array
