1 /**
2  * @file
3  * @brief MBOX Devicetree macro public API header file.
4  */
5 
6 /*
7  * Copyright (c) 2022 Carlo Caione <ccaione@baylibre.com>
8  *
9  * SPDX-License-Identifier: Apache-2.0
10  */
11 
12 #ifndef ZEPHYR_INCLUDE_DEVICETREE_MBOX_H_
13 #define ZEPHYR_INCLUDE_DEVICETREE_MBOX_H_
14 
15 #ifdef __cplusplus
16 extern "C" {
17 #endif
18 
19 /**
20  * @defgroup devicetree-mbox Devicetree MBOX API
21  * @ingroup devicetree
22  * @{
23  */
24 
25 /**
26  * @brief Get the node identifier for the MBOX controller from a mboxes
27  *	  property by name
28  *
29  * Example devicetree fragment:
30  *
31  *     mbox1: mbox-controller@... { ... };
32  *
33  *     n: node {
34  *             mboxes = <&mbox1 8>,
35  *                      <&mbox1 9>;
36  *             mbox-names = "tx", "rx";
37  *     };
38  *
39  * Example usage:
40  *
41  *     DT_MBOX_CTLR_BY_NAME(DT_NODELABEL(n), tx) // DT_NODELABEL(mbox1)
42  *     DT_MBOX_CTLR_BY_NAME(DT_NODELABEL(n), rx) // DT_NODELABEL(mbox1)
43  *
44  * @param node_id node identifier for a node with a mboxes property
45  * @param name lowercase-and-underscores name of a mboxes element
46  *             as defined by the node's mbox-names property
47  *
48  * @return the node identifier for the MBOX controller in the named element
49  *
50  * @see DT_PHANDLE_BY_NAME()
51  */
52 #define DT_MBOX_CTLR_BY_NAME(node_id, name) \
53 	DT_PHANDLE_BY_NAME(node_id, mboxes, name)
54 
55 /**
56  * @brief Get a MBOX channel value by name
57  *
58  * Example devicetree fragment:
59  *
60  *     mbox1: mbox@... {
61  *             #mbox-cells = <1>;
62  *     };
63  *
64  *     n: node {
65  *		mboxes = <&mbox1 1>,
66  *		         <&mbox1 6>;
67  *		mbox-names = "tx", "rx";
68  *     };
69  *
70  * Bindings fragment for the mbox compatible:
71  *
72  *     mbox-cells:
73  *       - channel
74  *
75  * Example usage:
76  *
77  *     DT_MBOX_CHANNEL_BY_NAME(DT_NODELABEL(n), tx) // 1
78  *     DT_MBOX_CHANNEL_BY_NAME(DT_NODELABEL(n), rx) // 6
79  *
80  * @param node_id node identifier for a node with a mboxes property
81  * @param name lowercase-and-underscores name of a mboxes element
82  *             as defined by the node's mbox-names property
83  *
84  * @return the channel value in the specifier at the named element or 0 if no
85  *         channels are supported
86  *
87  * @see DT_PHA_BY_NAME_OR()
88  */
89 #define DT_MBOX_CHANNEL_BY_NAME(node_id, name) \
90 	DT_PHA_BY_NAME_OR(node_id, mboxes, name, channel, 0)
91 
92 /**
93  * @}
94  */
95 
96 #ifdef __cplusplus
97 }
98 #endif
99 
100 #endif  /* ZEPHYR_INCLUDE_DEVICETREE_MBOX_H_ */
101