mbox: Move MBOX_DT_* macros

Move MBOX_DT_* macros to include/devicetree/mbox.h and use the correct
DT_MBOX_* prefix.

Signed-off-by: Carlo Caione <ccaione@baylibre.com>

doc/reference/api/overview.rst

@@ -207,6 +207,11 @@ current :ref:`stability level <api_lifecycle>`.
      - 2.5
      - 2.5
 
+   * - :ref:`mbox_api`
+     - Experimental
+     - 1.0
+     - 3.0
+
    * - :ref:`mqtt_socket_interface`
      - Unstable
      - 1.14

doc/reference/devicetree/api.rst

@@ -280,6 +280,16 @@ channels (e.g. ADC or DAC channels) for conversion.
 
 .. doxygengroup:: devicetree-io-channels
 
+.. _devicetree-mbox-api:
+
+MBOX
+====
+
+These conveniences may be used for nodes which describe MBOX controllers/users,
+and properties related to them.
+
+.. doxygengroup:: devicetree-mbox
+
 .. _devicetree-pinctrl-api:
 
 Pinctrl (pin control)

include/devicetree.h

@@ -3026,5 +3026,6 @@
 #include <devicetree/pinctrl.h>
 #include <devicetree/can.h>
 #include <devicetree/reset.h>
+#include <devicetree/mbox.h>
 
 #endif /* DEVICETREE_H */

include/devicetree/mbox.h

@@ -0,0 +1,100 @@
+/**
+ * @file
+ * @brief MBOX Devicetree macro public API header file.
+ */
+
+/*
+ * Copyright (c) 2022 Carlo Caione <ccaione@baylibre.com>
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#ifndef ZEPHYR_INCLUDE_DEVICETREE_MBOX_H_
+#define ZEPHYR_INCLUDE_DEVICETREE_MBOX_H_
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @defgroup devicetree-mbox Devicetree MBOX API
+ * @ingroup devicetree
+ * @{
+ */
+
+/**
+ * @brief Get the node identifier for the MBOX controller from a mboxes
+ *	  property by name
+ *
+ * Example devicetree fragment:
+ *
+ *     mbox1: mbox-controller@... { ... };
+ *
+ *     n: node {
+ *             mboxes = <&mbox1 8>,
+ *                      <&mbox1 9>;
+ *             mbox-names = "tx", "rx";
+ *     };
+ *
+ * Example usage:
+ *
+ *     DT_MBOX_CTLR_BY_NAME(DT_NODELABEL(n), tx) // DT_NODELABEL(mbox1)
+ *     DT_MBOX_CTLR_BY_NAME(DT_NODELABEL(n), rx) // DT_NODELABEL(mbox1)
+ *
+ * @param node_id node identifier for a node with a mboxes property
+ * @param name lowercase-and-underscores name of a mboxes element
+ *             as defined by the node's mbox-names property
+ *
+ * @return the node identifier for the MBOX controller in the named element
+ *
+ * @see DT_PHANDLE_BY_NAME()
+ */
+#define DT_MBOX_CTLR_BY_NAME(node_id, name) \
+	DT_PHANDLE_BY_NAME(node_id, mboxes, name)
+
+/**
+ * @brief Get a MBOX channel value by name
+ *
+ * Example devicetree fragment:
+ *
+ *     mbox1: mbox@... {
+ *             #mbox-cells = <1>;
+ *     };
+ *
+ *     n: node {
+ *		mboxes = <&mbox1 1>,
+ *		         <&mbox1 6>;
+ *		mbox-names = "tx", "rx";
+ *     };
+ *
+ * Bindings fragment for the mbox compatible:
+ *
+ *     mbox-cells:
+ *       - channel
+ *
+ * Example usage:
+ *
+ *     DT_MBOX_CHANNEL_BY_NAME(DT_NODELABEL(n), tx) // 1
+ *     DT_MBOX_CHANNEL_BY_NAME(DT_NODELABEL(n), rx) // 6
+ *
+ * @param node_id node identifier for a node with a mboxes property
+ * @param name lowercase-and-underscores name of a mboxes element
+ *             as defined by the node's mbox-names property
+ *
+ * @return the channel value in the specifier at the named element or 0 if no
+ *         channels are supported
+ *
+ * @see DT_PHA_BY_NAME_OR()
+ */
+#define DT_MBOX_CHANNEL_BY_NAME(node_id, name) \
+	DT_PHA_BY_NAME_OR(node_id, mboxes, name, channel, 0)
+
+/**
+ * @}
+ */
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif  /* ZEPHYR_INCLUDE_DEVICETREE_MBOX_H_ */

include/drivers/mbox.h

@@ -68,6 +68,7 @@
 
 #include <kernel.h>
 #include <device.h>
+#include <devicetree/mbox.h>
 
 #ifdef __cplusplus
 extern "C" {
@@ -123,77 +124,10 @@ struct mbox_channel {
  */
 #define MBOX_DT_CHANNEL_GET(node_id, name)					\
 	{									\
-		.dev = DEVICE_DT_GET(MBOX_DT_CTLR_BY_NAME(node_id, name)),	\
+		.dev = DEVICE_DT_GET(DT_MBOX_CTLR_BY_NAME(node_id, name)),	\
-		.id = MBOX_DT_CHANNEL_ID_BY_NAME(node_id, name),		\
+		.id = DT_MBOX_CHANNEL_BY_NAME(node_id, name),			\
 	}
 
-/**
- * @brief Get the node identifier for the MBOX controller from a mboxes
- *	  property by name
- *
- * Example devicetree fragment:
- *
- *     mbox1: mbox-controller@... { ... };
- *
- *     n: node {
- *             mboxes = <&mbox1 8>,
- *                      <&mbox1 9>;
- *             mbox-names = "tx", "rx";
- *     };
- *
- * Example usage:
- *
- *     MBOX_DT_CTLR_BY_NAME(DT_NODELABEL(n), tx) // DT_NODELABEL(mbox1)
- *     MBOX_DT_CTLR_BY_NAME(DT_NODELABEL(n), rx) // DT_NODELABEL(mbox1)
- *
- * @param node_id node identifier for a node with a mboxes property
- * @param name lowercase-and-underscores name of a mboxes element
- *             as defined by the node's mbox-names property
- *
- * @return the node identifier for the MBOX controller in the named element
- *
- * @see DT_PHANDLE_BY_NAME()
- */
-#define MBOX_DT_CTLR_BY_NAME(node_id, name) \
-	DT_PHANDLE_BY_NAME(node_id, mboxes, name)
-
-/**
- * @brief Get a MBOX channel value by name
- *
- * Example devicetree fragment:
- *
- *     mbox1: mbox@... {
- *             #mbox-cells = <1>;
- *     };
- *
- *     n: node {
- *		mboxes = <&mbox1 1>,
- *		         <&mbox1 6>;
- *		mbox-names = "tx", "rx";
- *     };
- *
- * Bindings fragment for the mbox compatible:
- *
- *     mbox-cells:
- *       - channel
- *
- * Example usage:
- *
- *     MBOX_DT_CHANNEL_ID_BY_NAME(DT_NODELABEL(n), tx) // 1
- *     MBOX_DT_CHANNEL_ID_BY_NAME(DT_NODELABEL(n), rx) // 6
- *
- * @param node_id node identifier for a node with a mboxes property
- * @param name lowercase-and-underscores name of a mboxes element
- *             as defined by the node's mbox-names property
- *
- * @return the channel value in the specifier at the named element or 0 if no
- *         channels are supported
- *
- * @see DT_PHA_BY_NAME_OR()
- */
-#define MBOX_DT_CHANNEL_ID_BY_NAME(node_id, name) \
-	DT_PHA_BY_NAME_OR(node_id, mboxes, name, channel, 0)
-
 /**
  * @typedef mbox_callback_t
  *

tests/lib/devicetree/api/src/main.c

@@ -2191,24 +2191,24 @@ static void test_mbox(void)
 	zassert_equal(channel_tx.id, 1, "");
 	zassert_equal(channel_rx.id, 2, "");
 
-	zassert_equal(MBOX_DT_CHANNEL_ID_BY_NAME(TEST_TEMP, tx), 1, "");
+	zassert_equal(DT_MBOX_CHANNEL_BY_NAME(TEST_TEMP, tx), 1, "");
-	zassert_equal(MBOX_DT_CHANNEL_ID_BY_NAME(TEST_TEMP, rx), 2, "");
+	zassert_equal(DT_MBOX_CHANNEL_BY_NAME(TEST_TEMP, rx), 2, "");
 
-	zassert_true(DT_SAME_NODE(MBOX_DT_CTLR_BY_NAME(TEST_TEMP, tx),
+	zassert_true(DT_SAME_NODE(DT_MBOX_CTLR_BY_NAME(TEST_TEMP, tx),
 				  DT_NODELABEL(test_mbox)), "");
-	zassert_true(DT_SAME_NODE(MBOX_DT_CTLR_BY_NAME(TEST_TEMP, rx),
+	zassert_true(DT_SAME_NODE(DT_MBOX_CTLR_BY_NAME(TEST_TEMP, rx),
 				  DT_NODELABEL(test_mbox)), "");
 
-	zassert_equal(MBOX_DT_CHANNEL_ID_BY_NAME(TEST_TEMP, tx), 1, "");
+	zassert_equal(DT_MBOX_CHANNEL_BY_NAME(TEST_TEMP, tx), 1, "");
-	zassert_equal(MBOX_DT_CHANNEL_ID_BY_NAME(TEST_TEMP, rx), 2, "");
+	zassert_equal(DT_MBOX_CHANNEL_BY_NAME(TEST_TEMP, rx), 2, "");
 
 	const struct mbox_channel channel_zero = MBOX_DT_CHANNEL_GET(TEST_TEMP, zero);
 
 	zassert_equal(channel_zero.id, 0, "");
 
-	zassert_equal(MBOX_DT_CHANNEL_ID_BY_NAME(TEST_TEMP, zero), 0, "");
+	zassert_equal(DT_MBOX_CHANNEL_BY_NAME(TEST_TEMP, zero), 0, "");
 
-	zassert_true(DT_SAME_NODE(MBOX_DT_CTLR_BY_NAME(TEST_TEMP, zero),
+	zassert_true(DT_SAME_NODE(DT_MBOX_CTLR_BY_NAME(TEST_TEMP, zero),
 				  DT_NODELABEL(test_mbox_zero_cell)), "");
 }