devicetree: add CONFIG_LEGACY_DEVICETREE_MACROS

This default-y option allows continued use of the legacy devicetree
macros.

There are no functional changes yet, but when this is default n,
old-style DT code won't build. At that point, adding any of these will
be a fix to keep old-style code working:

- "CONFIG_LEGACY_DEVICETREE_MACROS=y" to prj.conf
- "-- -DCONFIG_LEGACY_DEVICETREE_MACROS=y" to the west build command
- "-DCONFIG_LEGACY_DEVICETREE_MACROS=y" to the cmake command

This option can be changed to default n in time for the Zephyr 2.3
release. That will provide users of Zephyr 2.2 with a smooth migration
path to the new devicetree.h API after 2.3 is released, which
nonetheless will alert them immediately that something is wrong due to
build errors.

Unfortunately, __DEPRECATED_MACRO is not sufficient in all cases as a
warning to users. This is because, at least in GCC, macros defined
using __DEPRECATED_MACRO cannot be used in preprocessor lines like
"#if DT_SOME_LEGACY_MACRO".

Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>

Kconfig.zephyr

@@ -348,6 +348,14 @@ config MAKEFILE_EXPORTS
 	  Generates a file with build information that can be read by
 	  third party Makefile-based build systems.
 
+config LEGACY_DEVICETREE_MACROS
+	bool "Allow use of legacy devicetree macros"
+	default y
+	help
+	  Allows use of legacy devicetree macros which were used in
+	  Zephyr 2.2 and previous versions, rather than the devicetree.h
+	  API introduced during the Zephyr 2.3 development cycle.
+
 endmenu
 endmenu
 

doc/releases/release-notes-2.3.rst

@@ -73,6 +73,12 @@ Deprecated in this release
   * nrf52_pca20020 has been renamed to thingy52_nrf52832
   * nrf5340_dk_nrf5340 has been renamed to nrf5340pdk_nrf5340
 
+* Devicetree
+
+  * The C macros generated from devicetree. Use the new ``<devicetree.h>``
+    accessor API instead; see :ref:`dt-guide` for details. Use of the legacy
+    macros requires enabling :option:`CONFIG_LEGACY_DEVICETREE_MACROS`.
+
 Removed APIs in this release
 ============================
 

include/devicetree.h

@@ -16,8 +16,20 @@
 #ifndef DEVICETREE_H
 #define DEVICETREE_H
 
+#ifdef _LINKER
+/*
+ * Linker scripts include this file too, and autoconf.h isn't
+ * automatically included for those files the way it is for C source
+ * files. Make sure we pull it in before using
+ * CONFIG_LEGACY_DEVICETREE_MACROS in that case.
+ */
+#include <autoconf.h>
+#endif
+
 #include <devicetree_unfixed.h>
+#ifdef CONFIG_LEGACY_DEVICETREE_MACROS
 #include <devicetree_legacy_unfixed.h>
+#endif
 #include <devicetree_fixups.h>
 
 #include <sys/util.h>