include: devicetree.h: API for /chosen zephyr,foo

Add a devicetree/zephyr.h header, which is meant to contain
definitions for /chosen properties specific to Zephyr.

Currently, this just deals with zephyr,entropy.  We add a
DT_CHOSEN_ZEPHYR_ENTROPY_LABEL macro which expands to the label for the
node pointed to by zephyr,entropy.

Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
Signed-off-by: Kumar Gala <kumar.gala@linaro.org>

doc/reference/devicetree/index.rst

@@ -96,3 +96,12 @@ SPI
 
 .. doxygengroup:: devicetree-spi
    :project: Zephyr
+
+Zephyr specific /chosen nodes
+=============================
+
+These are conveniences for commonly used zephyr-specific properties of the
+``/chosen`` node. They may have fallbacks from :file:`dts_fixup.h` files.
+
+.. doxygengroup:: devicetree-zephyr
+   :project: Zephyr

doc/zephyr.doxyfile.in

@@ -1998,7 +1998,8 @@ PREDEFINED             = "CONFIG_ARCH_HAS_CUSTOM_BUSY_WAIT" \
                          "__aligned(x)=" \
                          "__printf_like(x, y)=" \
                          "__attribute__(x)=" \
-                         "__syscall="
+                         "__syscall=" \
+                         "DT_DOXYGEN"
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
 # tag can be used to specify a list of macro names that should be expanded. The

include/devicetree.h

@@ -1492,5 +1492,6 @@
 #include <devicetree/gpio.h>
 #include <devicetree/spi.h>
 #include <devicetree/dma.h>
+#include <devicetree/zephyr.h>
 
 #endif /* DEVICETREE_H */

include/devicetree/zephyr.h

@@ -0,0 +1,48 @@
+/*
+ * Copyright (c) 2020 Nordic Semiconductor ASA
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * @file
+ * @brief Zephyr-specific devicetree /chosen properties
+ */
+
+#ifndef ZEPHYR_INCLUDE_DEVICETREE_ZEPHYR_H_
+#define ZEPHYR_INCLUDE_DEVICETREE_ZEPHYR_H_
+
+/**
+ * @defgroup devicetree-zephyr Zephyr's /chosen nodes
+ * @{
+ */
+
+/*
+ * This file is currently deliberately not defining macros for some
+ * existing zephyr,foo chosen nodes, such as zephyr,sram, until there
+ * are users for them. Feel free to extend it as needed.
+ *
+ * Getting doxygen to play along with all the dts-specific ifdeffery
+ * proved too complex for DT_CHOSEN_ZEPHYR_ENTROPY_LABEL, so we document
+ * everything under a DT_DOXYGEN define.
+ */
+
+#ifdef DT_DOXYGEN
+/**
+ * @def DT_CHOSEN_ZEPHYR_ENTROPY_LABEL
+ *
+ * @brief If there is a chosen node zephyr,entropy property which has
+ *        a label property, that property's value. Undefined otherwise.
+ */
+#define DT_CHOSEN_ZEPHYR_ENTROPY_LABEL ""
+#endif /* DT_DOXYGEN */
+
+#if DT_NODE_HAS_PROP(DT_CHOSEN(zephyr_entropy), label)
+#define DT_CHOSEN_ZEPHYR_ENTROPY_LABEL DT_LABEL(DT_CHOSEN(zephyr_entropy))
+#endif
+
+/**
+ * @}
+ */
+
+#endif