LCOV - code coverage report
Current view: top level - zephyr/devicetree - clocks.h Coverage Total Hit
Test: new.info Lines: 100.0 % 19 19
Test Date: 2025-09-05 16:43:28

            Line data    Source code
       1            1 : /**
       2              :  * @file
       3              :  * @brief Clocks Devicetree macro public API header file.
       4              :  */
       5              : 
       6              : /*
       7              :  * Copyright (c) 2020, Linaro Ltd.
       8              :  *
       9              :  * SPDX-License-Identifier: Apache-2.0
      10              :  */
      11              : 
      12              : #ifndef ZEPHYR_INCLUDE_DEVICETREE_CLOCKS_H_
      13              : #define ZEPHYR_INCLUDE_DEVICETREE_CLOCKS_H_
      14              : 
      15              : #ifdef __cplusplus
      16              : extern "C" {
      17              : #endif
      18              : 
      19              : /**
      20              :  * @defgroup devicetree-clocks Devicetree Clocks API
      21              :  * @ingroup devicetree
      22              :  * @ingroup clock_control_interface
      23              :  * @{
      24              :  */
      25              : 
      26              : /**
      27              :  * @brief Test if a node has a clocks phandle-array property at a given index
      28              :  *
      29              :  * This expands to 1 if the given index is valid clocks property phandle-array index.
      30              :  * Otherwise, it expands to 0.
      31              :  *
      32              :  * Example devicetree fragment:
      33              :  *
      34              :  *     n1: node-1 {
      35              :  *             clocks = <...>, <...>;
      36              :  *     };
      37              :  *
      38              :  *     n2: node-2 {
      39              :  *             clocks = <...>;
      40              :  *     };
      41              :  *
      42              :  * Example usage:
      43              :  *
      44              :  *     DT_CLOCKS_HAS_IDX(DT_NODELABEL(n1), 0) // 1
      45              :  *     DT_CLOCKS_HAS_IDX(DT_NODELABEL(n1), 1) // 1
      46              :  *     DT_CLOCKS_HAS_IDX(DT_NODELABEL(n1), 2) // 0
      47              :  *     DT_CLOCKS_HAS_IDX(DT_NODELABEL(n2), 1) // 0
      48              :  *
      49              :  * @param node_id node identifier; may or may not have any clocks property
      50              :  * @param idx index of a clocks property phandle-array whose existence to check
      51              :  * @return 1 if the index exists, 0 otherwise
      52              :  */
      53            1 : #define DT_CLOCKS_HAS_IDX(node_id, idx) \
      54              :         DT_PROP_HAS_IDX(node_id, clocks, idx)
      55              : 
      56              : /**
      57              :  * @brief Test if a node has a clock-names array property holds a given name
      58              :  *
      59              :  * This expands to 1 if the name is available as clocks-name array property cell.
      60              :  * Otherwise, it expands to 0.
      61              :  *
      62              :  * Example devicetree fragment:
      63              :  *
      64              :  *     n1: node-1 {
      65              :  *             clocks = <...>, <...>;
      66              :  *             clock-names = "alpha", "beta";
      67              :  *     };
      68              :  *
      69              :  *     n2: node-2 {
      70              :  *             clocks = <...>;
      71              :  *             clock-names = "alpha";
      72              :  *     };
      73              :  *
      74              :  * Example usage:
      75              :  *
      76              :  *     DT_CLOCKS_HAS_NAME(DT_NODELABEL(n1), alpha) // 1
      77              :  *     DT_CLOCKS_HAS_NAME(DT_NODELABEL(n1), beta)  // 1
      78              :  *     DT_CLOCKS_HAS_NAME(DT_NODELABEL(n2), beta)  // 0
      79              :  *
      80              :  * @param node_id node identifier; may or may not have any clock-names property.
      81              :  * @param name lowercase-and-underscores clock-names cell value name to check
      82              :  * @return 1 if the clock name exists, 0 otherwise
      83              :  */
      84            1 : #define DT_CLOCKS_HAS_NAME(node_id, name) \
      85              :         DT_PROP_HAS_NAME(node_id, clocks, name)
      86              : 
      87              : /**
      88              :  * @brief Get the number of elements in a clocks property
      89              :  *
      90              :  * Example devicetree fragment:
      91              :  *
      92              :  *     n1: node-1 {
      93              :  *             clocks = <&foo>, <&bar>;
      94              :  *     };
      95              :  *
      96              :  *     n2: node-2 {
      97              :  *             clocks = <&foo>;
      98              :  *     };
      99              :  *
     100              :  * Example usage:
     101              :  *
     102              :  *     DT_NUM_CLOCKS(DT_NODELABEL(n1)) // 2
     103              :  *     DT_NUM_CLOCKS(DT_NODELABEL(n2)) // 1
     104              :  *
     105              :  * @param node_id node identifier with a clocks property
     106              :  * @return number of elements in the property
     107              :  */
     108            1 : #define DT_NUM_CLOCKS(node_id) \
     109              :         DT_PROP_LEN(node_id, clocks)
     110              : 
     111              : 
     112              : /**
     113              :  * @brief Get the node identifier for the controller phandle from a
     114              :  *        "clocks" phandle-array property at an index
     115              :  *
     116              :  * Example devicetree fragment:
     117              :  *
     118              :  *     clk1: clock-controller@... { ... };
     119              :  *
     120              :  *     clk2: clock-controller@... { ... };
     121              :  *
     122              :  *     n: node {
     123              :  *             clocks = <&clk1 10 20>, <&clk2 30 40>;
     124              :  *     };
     125              :  *
     126              :  * Example usage:
     127              :  *
     128              :  *     DT_CLOCKS_CTLR_BY_IDX(DT_NODELABEL(n), 0)) // DT_NODELABEL(clk1)
     129              :  *     DT_CLOCKS_CTLR_BY_IDX(DT_NODELABEL(n), 1)) // DT_NODELABEL(clk2)
     130              :  *
     131              :  * @param node_id node identifier
     132              :  * @param idx logical index into "clocks"
     133              :  * @return the node identifier for the clock controller referenced at
     134              :  *         index "idx"
     135              :  * @see DT_PHANDLE_BY_IDX()
     136              :  */
     137            1 : #define DT_CLOCKS_CTLR_BY_IDX(node_id, idx) \
     138              :         DT_PHANDLE_BY_IDX(node_id, clocks, idx)
     139              : 
     140              : /**
     141              :  * @brief Equivalent to DT_CLOCKS_CTLR_BY_IDX(node_id, 0)
     142              :  * @param node_id node identifier
     143              :  * @return a node identifier for the clocks controller at index 0
     144              :  *         in "clocks"
     145              :  * @see DT_CLOCKS_CTLR_BY_IDX()
     146              :  */
     147            1 : #define DT_CLOCKS_CTLR(node_id) DT_CLOCKS_CTLR_BY_IDX(node_id, 0)
     148              : 
     149              : /**
     150              :  * @brief Get the node identifier for the controller phandle from a
     151              :  *        clocks phandle-array property by name
     152              :  *
     153              :  * Example devicetree fragment:
     154              :  *
     155              :  *     clk1: clock-controller@... { ... };
     156              :  *
     157              :  *     clk2: clock-controller@... { ... };
     158              :  *
     159              :  *     n: node {
     160              :  *             clocks = <&clk1 10 20>, <&clk2 30 40>;
     161              :  *             clock-names = "alpha", "beta";
     162              :  *     };
     163              :  *
     164              :  * Example usage:
     165              :  *
     166              :  *     DT_CLOCKS_CTLR_BY_NAME(DT_NODELABEL(n), beta) // DT_NODELABEL(clk2)
     167              :  *
     168              :  * @param node_id node identifier
     169              :  * @param name lowercase-and-underscores name of a clocks element
     170              :  *             as defined by the node's clock-names property
     171              :  * @return the node identifier for the clock controller referenced by name
     172              :  * @see DT_PHANDLE_BY_NAME()
     173              :  */
     174            1 : #define DT_CLOCKS_CTLR_BY_NAME(node_id, name) \
     175              :         DT_PHANDLE_BY_NAME(node_id, clocks, name)
     176              : 
     177              : /**
     178              :  * @brief Get a clock specifier's cell value at an index
     179              :  *
     180              :  * Example devicetree fragment:
     181              :  *
     182              :  *     clk1: clock-controller@... {
     183              :  *             compatible = "vnd,clock";
     184              :  *             #clock-cells = < 2 >;
     185              :  *     };
     186              :  *
     187              :  *     n: node {
     188              :  *             clocks = < &clk1 10 20 >, < &clk1 30 40 >;
     189              :  *     };
     190              :  *
     191              :  * Bindings fragment for the vnd,clock compatible:
     192              :  *
     193              :  *     clock-cells:
     194              :  *       - bus
     195              :  *       - bits
     196              :  *
     197              :  * Example usage:
     198              :  *
     199              :  *     DT_CLOCKS_CELL_BY_IDX(DT_NODELABEL(n), 0, bus) // 10
     200              :  *     DT_CLOCKS_CELL_BY_IDX(DT_NODELABEL(n), 1, bits) // 40
     201              :  *
     202              :  * @param node_id node identifier for a node with a clocks property
     203              :  * @param idx logical index into clocks property
     204              :  * @param cell lowercase-and-underscores cell name
     205              :  * @return the cell value at index "idx"
     206              :  * @see DT_PHA_BY_IDX()
     207              :  */
     208            1 : #define DT_CLOCKS_CELL_BY_IDX(node_id, idx, cell) \
     209              :         DT_PHA_BY_IDX(node_id, clocks, idx, cell)
     210              : 
     211              : /**
     212              :  * @brief Get a clock specifier's cell value by name
     213              :  *
     214              :  * Example devicetree fragment:
     215              :  *
     216              :  *     clk1: clock-controller@... {
     217              :  *             compatible = "vnd,clock";
     218              :  *             #clock-cells = < 2 >;
     219              :  *     };
     220              :  *
     221              :  *     n: node {
     222              :  *             clocks = < &clk1 10 20 >, < &clk1 30 40 >;
     223              :  *             clock-names = "alpha", "beta";
     224              :  *     };
     225              :  *
     226              :  * Bindings fragment for the vnd,clock compatible:
     227              :  *
     228              :  *     clock-cells:
     229              :  *       - bus
     230              :  *       - bits
     231              :  *
     232              :  * Example usage:
     233              :  *
     234              :  *     DT_CLOCKS_CELL_BY_NAME(DT_NODELABEL(n), alpha, bus) // 10
     235              :  *     DT_CLOCKS_CELL_BY_NAME(DT_NODELABEL(n), beta, bits) // 40
     236              :  *
     237              :  * @param node_id node identifier for a node with a clocks property
     238              :  * @param name lowercase-and-underscores name of a clocks element
     239              :  *             as defined by the node's clock-names property
     240              :  * @param cell lowercase-and-underscores cell name
     241              :  * @return the cell value in the specifier at the named element
     242              :  * @see DT_PHA_BY_NAME()
     243              :  */
     244            1 : #define DT_CLOCKS_CELL_BY_NAME(node_id, name, cell) \
     245              :         DT_PHA_BY_NAME(node_id, clocks, name, cell)
     246              : 
     247              : /**
     248              :  * @brief Equivalent to DT_CLOCKS_CELL_BY_IDX(node_id, 0, cell)
     249              :  * @param node_id node identifier for a node with a clocks property
     250              :  * @param cell lowercase-and-underscores cell name
     251              :  * @return the cell value at index 0
     252              :  * @see DT_CLOCKS_CELL_BY_IDX()
     253              :  */
     254            1 : #define DT_CLOCKS_CELL(node_id, cell) DT_CLOCKS_CELL_BY_IDX(node_id, 0, cell)
     255              : 
     256              : /**
     257              :  * @brief Equivalent to DT_CLOCKS_HAS_IDX(DT_DRV_INST(inst), idx)
     258              :  * @param inst DT_DRV_COMPAT instance number; may or may not have any clocks property
     259              :  * @param idx index of a clocks property phandle-array whose existence to check
     260              :  * @return 1 if the index exists, 0 otherwise
     261              :  */
     262            1 : #define DT_INST_CLOCKS_HAS_IDX(inst, idx) \
     263              :         DT_CLOCKS_HAS_IDX(DT_DRV_INST(inst), idx)
     264              : 
     265              : /**
     266              :  * @brief Equivalent to DT_CLOCK_HAS_NAME(DT_DRV_INST(inst), name)
     267              :  * @param inst DT_DRV_COMPAT instance number; may or may not have any clock-names property.
     268              :  * @param name lowercase-and-underscores clock-names cell value name to check
     269              :  * @return 1 if the clock name exists, 0 otherwise
     270              :  */
     271            1 : #define DT_INST_CLOCKS_HAS_NAME(inst, name) \
     272              :         DT_CLOCKS_HAS_NAME(DT_DRV_INST(inst), name)
     273              : 
     274              : /**
     275              :  * @brief Equivalent to DT_NUM_CLOCKS(DT_DRV_INST(inst))
     276              :  * @param inst instance number
     277              :  * @return number of elements in the clocks property
     278              :  */
     279            1 : #define DT_INST_NUM_CLOCKS(inst) \
     280              :         DT_NUM_CLOCKS(DT_DRV_INST(inst))
     281              : 
     282              : /**
     283              :  * @brief Get the node identifier for the controller phandle from a
     284              :  *        "clocks" phandle-array property at an index
     285              :  *
     286              :  * @param inst instance number
     287              :  * @param idx logical index into "clocks"
     288              :  * @return the node identifier for the clock controller referenced at
     289              :  *         index "idx"
     290              :  * @see DT_CLOCKS_CTLR_BY_IDX()
     291              :  */
     292            1 : #define DT_INST_CLOCKS_CTLR_BY_IDX(inst, idx) \
     293              :         DT_CLOCKS_CTLR_BY_IDX(DT_DRV_INST(inst), idx)
     294              : 
     295              : /**
     296              :  * @brief Equivalent to DT_INST_CLOCKS_CTLR_BY_IDX(inst, 0)
     297              :  * @param inst instance number
     298              :  * @return a node identifier for the clocks controller at index 0
     299              :  *         in "clocks"
     300              :  * @see DT_CLOCKS_CTLR()
     301              :  */
     302            1 : #define DT_INST_CLOCKS_CTLR(inst) DT_INST_CLOCKS_CTLR_BY_IDX(inst, 0)
     303              : 
     304              : /**
     305              :  * @brief Get the node identifier for the controller phandle from a
     306              :  *        clocks phandle-array property by name
     307              :  *
     308              :  * @param inst instance number
     309              :  * @param name lowercase-and-underscores name of a clocks element
     310              :  *             as defined by the node's clock-names property
     311              :  * @return the node identifier for the clock controller referenced by
     312              :  *         the named element
     313              :  * @see DT_CLOCKS_CTLR_BY_NAME()
     314              :  */
     315            1 : #define DT_INST_CLOCKS_CTLR_BY_NAME(inst, name) \
     316              :         DT_CLOCKS_CTLR_BY_NAME(DT_DRV_INST(inst), name)
     317              : 
     318              : /**
     319              :  * @brief Get a DT_DRV_COMPAT instance's clock specifier's cell value
     320              :  *        at an index
     321              :  * @param inst DT_DRV_COMPAT instance number
     322              :  * @param idx logical index into clocks property
     323              :  * @param cell lowercase-and-underscores cell name
     324              :  * @return the cell value at index "idx"
     325              :  * @see DT_CLOCKS_CELL_BY_IDX()
     326              :  */
     327            1 : #define DT_INST_CLOCKS_CELL_BY_IDX(inst, idx, cell) \
     328              :         DT_CLOCKS_CELL_BY_IDX(DT_DRV_INST(inst), idx, cell)
     329              : 
     330              : /**
     331              :  * @brief Get a DT_DRV_COMPAT instance's clock specifier's cell value by name
     332              :  * @param inst DT_DRV_COMPAT instance number
     333              :  * @param name lowercase-and-underscores name of a clocks element
     334              :  *             as defined by the node's clock-names property
     335              :  * @param cell lowercase-and-underscores cell name
     336              :  * @return the cell value in the specifier at the named element
     337              :  * @see DT_CLOCKS_CELL_BY_NAME()
     338              :  */
     339            1 : #define DT_INST_CLOCKS_CELL_BY_NAME(inst, name, cell) \
     340              :         DT_CLOCKS_CELL_BY_NAME(DT_DRV_INST(inst), name, cell)
     341              : 
     342              : /**
     343              :  * @brief Equivalent to DT_INST_CLOCKS_CELL_BY_IDX(inst, 0, cell)
     344              :  * @param inst DT_DRV_COMPAT instance number
     345              :  * @param cell lowercase-and-underscores cell name
     346              :  * @return the value of the cell inside the specifier at index 0
     347              :  */
     348            1 : #define DT_INST_CLOCKS_CELL(inst, cell) \
     349              :         DT_INST_CLOCKS_CELL_BY_IDX(inst, 0, cell)
     350              : 
     351              : /**
     352              :  * @}
     353              :  */
     354              : 
     355              : #ifdef __cplusplus
     356              : }
     357              : #endif
     358              : 
     359              : #endif  /* ZEPHYR_INCLUDE_DEVICETREE_CLOCKS_H_ */
        

Generated by: LCOV version 2.0-1