From ffd1abde6623b3c5956c498aab90c7a78292243d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Mart=C3=AD=20Bol=C3=ADvar?= <marti.bolivar@nordicsemi.no>
Date: Sat, 28 Mar 2020 16:19:14 -0700
Subject: [PATCH] include: devicetree.h: API for /chosen zephyr,foo
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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 |  9 ++++++
 doc/zephyr.doxyfile.in             |  3 +-
 include/devicetree.h               |  1 +
 include/devicetree/zephyr.h        | 48 ++++++++++++++++++++++++++++++
 4 files changed, 60 insertions(+), 1 deletion(-)
 create mode 100644 include/devicetree/zephyr.h

diff --git a/doc/reference/devicetree/index.rst b/doc/reference/devicetree/index.rst
index cd9c1ab2b1f..45a22208a68 100644
--- a/doc/reference/devicetree/index.rst
+++ b/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
diff --git a/doc/zephyr.doxyfile.in b/doc/zephyr.doxyfile.in
index 274f5aa1d71..b6d129a4831 100644
--- a/doc/zephyr.doxyfile.in
+++ b/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
diff --git a/include/devicetree.h b/include/devicetree.h
index 621430b0869..bb89f7850aa 100644
--- a/include/devicetree.h
+++ b/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 */
diff --git a/include/devicetree/zephyr.h b/include/devicetree/zephyr.h
new file mode 100644
index 00000000000..3071690bf1c
--- /dev/null
+++ b/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