Line data    Source code

       1           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           1 : #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           1 : #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_ */