doc: dts: document zephyr, prefix for props/compats

We have established a convention that the zephyr, prefix in property
names indicates some sort of zephyr-specific extension to a common
binding, or a zephyr-specific driver configuration knob. We also have
established a convention that compatibles which begin with "zephyr,"
are specific to our operating system. Document these facts.

Signed-off-by: Marti Bolivar <marti.bolivar@nordicsemi.no>

doc/build/dts/bindings-upstream.rst

@@ -208,3 +208,28 @@ Some examples of what **not** to do, and why:
        # This is the recommended value chosen by the manufacturer.
        default: 2
        description: baz time in milliseconds
+
+The ``zephyr,`` prefix
+**********************
+
+You must add this prefix to property names in the following cases:
+
+- Zephyr-specific extensions to bindings we share with upstream Linux. One
+  example is the ``zephyr,vref-mv`` ADC channel property which is common to ADC
+  controllers defined in :zephyr_file:`dts/bindings/adc/adc-controller.yaml`.
+  This channel binding is partially shared with an analogous Linux binding, and
+  Zephyr-specific extensions are marked as such with the prefix.
+
+- Configuration values that are specific to a Zephyr device driver. One example
+  is the ``zephyr,lazy-load`` property in the :dtcompatible:`ti,bq274xx`
+  binding. Though devicetree in general is a hardware description and
+  configuration language, it is Zephyr's only mechanism for configuring driver
+  behavior for an individual ``struct device``. Therefore, as a compromise,
+  we do allow some software configuration in Zephyr's devicetree bindings, as
+  long as they use this prefix to show that they are Zephyr specific.
+
+You may use the ``zephyr,`` prefix when naming a devicetree compatible that is
+specific to Zephyr. One example is
+:dtcompatible:`zephyr,ipc-openamp-static-vrings`. In this case, it's permitted
+but not required to add the ``zephyr,`` prefix to properties defined in the
+binding.