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              :  * @ingroup mbox_interface
      23              :  * @{
      24              :  */
      25              : 
      26              : /**
      27              :  * @brief Get the node identifier for the MBOX controller from a mboxes
      28              :  *        property by name
      29              :  *
      30              :  * Example devicetree fragment:
      31              :  *
      32              :  *     mbox1: mbox-controller@... { ... };
      33              :  *
      34              :  *     n: node {
      35              :  *             mboxes = <&mbox1 8>,
      36              :  *                      <&mbox1 9>;
      37              :  *             mbox-names = "tx", "rx";
      38              :  *     };
      39              :  *
      40              :  * Example usage:
      41              :  *
      42              :  *     DT_MBOX_CTLR_BY_NAME(DT_NODELABEL(n), tx) // DT_NODELABEL(mbox1)
      43              :  *     DT_MBOX_CTLR_BY_NAME(DT_NODELABEL(n), rx) // DT_NODELABEL(mbox1)
      44              :  *
      45              :  * @param node_id node identifier for a node with a mboxes property
      46              :  * @param name lowercase-and-underscores name of a mboxes element
      47              :  *             as defined by the node's mbox-names property
      48              :  *
      49              :  * @return the node identifier for the MBOX controller in the named element
      50              :  *
      51              :  * @see DT_PHANDLE_BY_NAME()
      52              :  */
      53            1 : #define DT_MBOX_CTLR_BY_NAME(node_id, name) \
      54              :         DT_PHANDLE_BY_NAME(node_id, mboxes, name)
      55              : 
      56              : /**
      57              :  * @brief Get a MBOX channel value by name
      58              :  *
      59              :  * Example devicetree fragment:
      60              :  *
      61              :  *     mbox1: mbox@... {
      62              :  *             #mbox-cells = <1>;
      63              :  *     };
      64              :  *
      65              :  *     n: node {
      66              :  *              mboxes = <&mbox1 1>,
      67              :  *                       <&mbox1 6>;
      68              :  *              mbox-names = "tx", "rx";
      69              :  *     };
      70              :  *
      71              :  * Bindings fragment for the mbox compatible:
      72              :  *
      73              :  *     mbox-cells:
      74              :  *       - channel
      75              :  *
      76              :  * Example usage:
      77              :  *
      78              :  *     DT_MBOX_CHANNEL_BY_NAME(DT_NODELABEL(n), tx) // 1
      79              :  *     DT_MBOX_CHANNEL_BY_NAME(DT_NODELABEL(n), rx) // 6
      80              :  *
      81              :  * @param node_id node identifier for a node with a mboxes property
      82              :  * @param name lowercase-and-underscores name of a mboxes element
      83              :  *             as defined by the node's mbox-names property
      84              :  *
      85              :  * @return the channel value in the specifier at the named element or 0 if no
      86              :  *         channels are supported
      87              :  *
      88              :  * @see DT_PHA_BY_NAME_OR()
      89              :  */
      90            1 : #define DT_MBOX_CHANNEL_BY_NAME(node_id, name) \
      91              :         DT_PHA_BY_NAME_OR(node_id, mboxes, name, channel, 0)
      92              : 
      93              : /**
      94              :  * @}
      95              :  */
      96              : 
      97              : #ifdef __cplusplus
      98              : }
      99              : #endif
     100              : 
     101              : #endif  /* ZEPHYR_INCLUDE_DEVICETREE_MBOX_H_ */