dts: support specifying preprocessor flags for devicetree

In some cases it is useful to use the C preprocessor to control the
content of a devicetree file.  A specific use case is in testing,
where different combinations of node properties must be checked.
Provide a mechanism to allow arbitrary preprocessor flags to be passed
through CMake to affect the devicetree content.

Signed-off-by: Peter A. Bigot <pab@pabigot.com>

cmake/dts.cmake

@@ -140,6 +140,7 @@ if(SUPPORTS_DTS)
     ${DTC_INCLUDE_FLAG_FOR_DTS}  # include the DTS source and overlays
     ${NOSYSDEF_CFLAG}
     -D__DTS__
+    ${DTS_EXTRA_CPPFLAGS}
     -P
     -E   # Stop after preprocessing
     -MD  # Generate a dependency file as a side-effect

doc/application/index.rst

@@ -783,6 +783,20 @@ You can also define the variable in the application :file:`CMakeLists.txt`
 file. Make sure to do so **before** pulling in the Zephyr boilerplate with
 ``find_package(Zephyr ...)``.
 
+Devicetree source are passed through the C preprocessor, so you can
+include files that can be located in a ``DTS_ROOT`` directory.  By
+convention devicetree include files have a ``.dtsi`` extension.
+
+You can also use the preprocessor to control the content of a devicetree
+file, by specifying directives through the ``DTS_EXTRA_CPPFLAGS`` CMake
+Cache variable:
+
+.. zephyr-app-commands::
+   :tool: all
+   :board: <board name>
+   :gen-args: -DDTS_EXTRA_CPPFLAGS=-DTEST_ENABLE_FEATURE
+   :goals: build
+   :compact:
 
 Application Debugging
 *********************