cmake: DT: Add support for out-of-tree binding root directories

Just like board's can be placed in out-of-tree BOARD_ROOT's, we now
support DeviceTree sources and bindings being placed in out-of-tree
DTS_ROOT's.

This required for out-of-tree drivers that use DeviceTree.

To implement this we get rid of various user-settable CMake variables
like DTS_APP_BINDINGS, DTS_APP_INCLUDE, and instead have ZEPHYR_BASE,
APPLICATION_SOURCE_DIR and out-of-tree directories conform to using
the same DTS_ROOT concept and directory structure.

Signed-off-by: Sebastian Bøe <sebastian.boe@nordicsemi.no>

cmake/dts.cmake

@@ -12,12 +12,20 @@ file(MAKE_DIRECTORY ${PROJECT_BINARY_DIR}/include/generated)
 # CMake configure-time.
 #
 # See ~/zephyr/doc/dts
-set(GENERATED_DTS_BOARD_UNFIXED_H    ${PROJECT_BINARY_DIR}/include/generated/generated_dts_board_unfixed.h)
+set(GENERATED_DTS_BOARD_UNFIXED_H ${PROJECT_BINARY_DIR}/include/generated/generated_dts_board_unfixed.h)
-set(GENERATED_DTS_BOARD_CONF ${PROJECT_BINARY_DIR}/include/generated/generated_dts_board.conf)
+set(GENERATED_DTS_BOARD_CONF      ${PROJECT_BINARY_DIR}/include/generated/generated_dts_board.conf)
+
 set_ifndef(DTS_SOURCE ${BOARD_DIR}/${BOARD}.dts)
 set_ifndef(DTS_COMMON_OVERLAYS ${ZEPHYR_BASE}/dts/common/common.dts)
-set_ifndef(DTS_APP_BINDINGS ${APPLICATION_SOURCE_DIR}/dts/bindings)
+
-set_ifndef(DTS_APP_INCLUDE ${APPLICATION_SOURCE_DIR}/dts)
+# 'DTS_ROOT' is a list of directories where a directory tree with DT
+# files may be found. It always includes the application directory and
+# ${ZEPHYR_BASE}.
+list(APPEND
+  DTS_ROOT
+  ${APPLICATION_SOURCE_DIR}
+  ${ZEPHYR_BASE}
+  )
 
 set(dts_files
   ${DTS_SOURCE}
@@ -64,6 +72,33 @@ if(SUPPORTS_DTS)
     math(EXPR i "${i}+1")
   endforeach()
 
+  foreach(dts_root ${DTS_ROOT})
+    foreach(dts_root_path
+        include
+        dts/common
+        dts/${ARCH}
+        dts
+        )
+      set(full_path ${dts_root}/${dts_root_path})
+      if(EXISTS ${full_path})
+        list(APPEND
+          DTS_ROOT_SYSTEM_INCLUDE_DIRS
+          -isystem ${full_path}
+          )
+      endif()
+    endforeach()
+  endforeach()
+
+  foreach(dts_root ${DTS_ROOT})
+    set(full_path ${dts_root}/dts/bindings)
+    if(EXISTS ${full_path})
+      list(APPEND
+        DTS_ROOT_BINDINGS
+        ${full_path}
+        )
+    endif()
+  endforeach()
+
   # TODO: Cut down on CMake configuration time by avoiding
   # regeneration of generated_dts_board_unfixed.h on every configure. How
   # challenging is this? What are the dts dependencies? We run the
@@ -77,11 +112,7 @@ if(SUPPORTS_DTS)
     COMMAND ${CMAKE_C_COMPILER}
     -x assembler-with-cpp
     -nostdinc
-    -isystem ${DTS_APP_INCLUDE}
+    ${DTS_ROOT_SYSTEM_INCLUDE_DIRS}
-    -isystem ${ZEPHYR_BASE}/include
-    -isystem ${ZEPHYR_BASE}/dts/common
-    -isystem ${ZEPHYR_BASE}/dts/${ARCH}
-    -isystem ${ZEPHYR_BASE}/dts
     ${DTC_INCLUDE_FLAG_FOR_DTS}  # include the DTS source and overlays
     ${NOSYSDEF_CFLAG}
     -D__DTS__
@@ -124,13 +155,9 @@ if(SUPPORTS_DTS)
     message(FATAL_ERROR "command failed with return code: ${ret}")
   endif()
 
-  if(NOT EXISTS ${DTS_APP_BINDINGS})
-    set(DTS_APP_BINDINGS)
-  endif()
-
   set(CMD_EXTRACT_DTS_INCLUDES ${PYTHON_EXECUTABLE} ${ZEPHYR_BASE}/scripts/dts/extract_dts_includes.py
     --dts ${BOARD}.dts_compiled
-    --yaml ${ZEPHYR_BASE}/dts/bindings ${DTS_APP_BINDINGS}
+    --yaml ${DTS_ROOT_BINDINGS}
     --keyvalue ${GENERATED_DTS_BOARD_CONF}
     --include ${GENERATED_DTS_BOARD_UNFIXED_H}
     --old-alias-names

doc/application/index.rst

@@ -510,12 +510,12 @@ again.
 .. _application_debugging:
 .. _custom_board_definition:
 
-Custom Board and SOC Definitions
+Custom Board, DeviceTree and SOC Definitions
-********************************
+********************************************
 
-In cases where the board or platform you are developing for is not yet supported
+In cases where the board or platform you are developing for is not yet
-by Zephyr, you can add the board and SOC definition to your application and
+supported by Zephyr, you can add board, DeviceTree and SOC definitions
-build for this board or SOC without having to add them to the Zephyr tree.
+to your application without having to add them to the Zephyr tree.
 
 The structure needed to support out-of-tree board and SOC development
 is similar to how boards and SOCs are maintained in the Zephyr tree. By using
@@ -644,6 +644,29 @@ Zephyr binary into your application directory.
 You can also define the ``SOC_ROOT`` variable in the application
 :file:`CMakeLists.txt` file.
 
+DeviceTree Definitions
+======================
+
+Additional DeviceTree directory trees, or DTS_ROOTs, can be added by
+creating this directory tree:
+
+    dts/bindings/
+    dts/common/
+    dts/arm/
+    include/
+
+Where 'arm' is changed to the appropriate architecture. Each directory
+is optional. The binding directory contains bindings and the other
+directories contain files that can be included from DT sources.
+
+Once the directory structure is in place, you can use it by specifying
+its location through the ``DTS_ROOT`` CMake Cache variable::
+
+   cmake -DDTS_ROOT=<path to dts root>
+
+You can also define the variable in the application
+:file:`CMakeLists.txt` file.
+
 .. _ext-projs:
 
 Modules (External projects)