LCOV - code coverage report
Current view: top level - zephyr/devicetree - nvmem.h Coverage Total Hit
Test: new.info Lines: 100.0 % 14 14
Test Date: 2025-10-20 12:20:01

            Line data    Source code
       1            1 : /**
       2              :  * @file
       3              :  * @brief NVMEM Devicetree public API header file.
       4              :  */
       5              : 
       6              : /*
       7              :  * Copyright (c) 2024, Andriy Gelman
       8              :  * Copyright (c) 2025, Basalte bv
       9              :  *
      10              :  * SPDX-License-Identifier: Apache-2.0
      11              :  */
      12              : 
      13              : #ifndef INCLUDE_ZEPHYR_DEVICETREE_NVMEM_H_
      14              : #define INCLUDE_ZEPHYR_DEVICETREE_NVMEM_H_
      15              : 
      16              : #ifdef __cplusplus
      17              : extern "C" {
      18              : #endif
      19              : 
      20              : /**
      21              :  * @defgroup devicetree-nvmem Devicetree NVMEM API
      22              :  * @ingroup devicetree
      23              :  * @{
      24              :  */
      25              : 
      26              : /**
      27              :  * @brief Test if a node has an nvmem-cells phandle-array property at a given index
      28              :  *
      29              :  * This expands to 1 if the given index is a valid nvmem-cells property phandle-array index.
      30              :  * Otherwise, it expands to 0.
      31              :  *
      32              :  * Example devicetree fragment:
      33              :  *
      34              :  * @code{.dts}
      35              :  *      eth: ethernet {
      36              :  *              nvmem-cells = <&mac_address>;
      37              :  *              nvmem-cell-names = "mac-address";
      38              :  *      };
      39              :  * @endcode
      40              :  *
      41              :  * Example usage:
      42              :  *
      43              :  * @code{.c}
      44              :  *      DT_NVMEM_CELLS_HAS_IDX(DT_NODELABEL(eth), 0) // 1
      45              :  *      DT_NVMEM_CELLS_HAS_IDX(DT_NODELABEL(eth), 1) // 0
      46              :  * @endcode
      47              :  *
      48              :  * @param node_id node identifier; may or may not have any nvmem-cells property
      49              :  * @param idx index of a nvmem-cells property phandle-array whose existence to check
      50              :  *
      51              :  * @return 1 if the index exists, 0 otherwise
      52              :  */
      53            1 : #define DT_NVMEM_CELLS_HAS_IDX(node_id, idx) DT_PROP_HAS_IDX(node_id, nvmem_cells, idx)
      54              : 
      55              : /**
      56              :  * @brief Test if a node has an nvmem-cell-names array property hold a given name.
      57              :  *
      58              :  * This expands to 1 if the name is available as nvmem-cells-name array property cell.
      59              :  * Otherwise, it expands to 0.
      60              :  *
      61              :  * Example devicetree fragment:
      62              :  *
      63              :  * @code{.dts}
      64              :  *      eth: ethernet {
      65              :  *              nvmem-cells = <&mac_address>;
      66              :  *              nvmem-cell-names = "mac-address";
      67              :  *      };
      68              :  * @endcode
      69              :  *
      70              :  * Example usage:
      71              :  *
      72              :  * @code{.c}
      73              :  *      DT_NVMEM_CELLS_HAS_NAME(DT_NODELABEL(eth), mac_address) // 1
      74              :  *      DT_NVMEM_CELLS_HAS_NAME(DT_NODELABEL(eth), bogus)       // 0
      75              :  * @endcode
      76              :  *
      77              :  * @param node_id node identifier; may or may not have any nvmem-cell-names property
      78              :  * @param name lowercase-and-underscores nvmem-cell-names cell value name to check
      79              :  *
      80              :  * @return 1 if the index exists, 0 otherwise
      81              :  */
      82            1 : #define DT_NVMEM_CELLS_HAS_NAME(node_id, name) DT_PROP_HAS_NAME(node_id, nvmem_cells, name)
      83              : 
      84              : /**
      85              :  * @brief Get the number of elements in an nvmem-cells property
      86              :  *
      87              :  * Example devicetree fragment:
      88              :  *
      89              :  * @code{.dts}
      90              :  *      eth: ethernet {
      91              :  *              nvmem-cells = <&mac_address>;
      92              :  *              nvmem-cell-names = "mac-address";
      93              :  *      };
      94              :  * @endcode
      95              :  *
      96              :  * Example usage:
      97              :  *
      98              :  * @code{.c}
      99              :  *      DT_NUM_NVMEM_CELLS(DT_NODELABEL(eth)) // 1
     100              :  * @endcode
     101              :  *
     102              :  * @param node_id node identifier with an nvmem-cells property
     103              :  *
     104              :  * @return number of elements in the property
     105              :  */
     106            1 : #define DT_NUM_NVMEM_CELLS(node_id) DT_PROP_LEN(node_id, nvmem_cells)
     107              : 
     108              : /**
     109              :  * @brief Get the node identifier for the NVMEM cell from the nvmem-cells property by index.
     110              :  *
     111              :  * Example devicetree fragment:
     112              :  *
     113              :  * @code{.dts}
     114              :  *      mac_eeprom: mac_eeprom@2 {
     115              :  *              nvmem-layout {
     116              :  *                      compatible = "fixed-layout";
     117              :  *                      #address-cells = <1>;
     118              :  *                      #size-cells = <1>;
     119              :  *
     120              :  *                      mac_address: mac_address@fa {
     121              :  *                              reg = <0xfa 0x06>;
     122              :  *                              #nvmem-cell-cells = <0>;
     123              :  *                      };
     124              :  *              };
     125              :  *      };
     126              :  *
     127              :  *      eth: ethernet {
     128              :  *              nvmem-cells = <&mac_address>;
     129              :  *              nvmem-cell-names = "mac-address";
     130              :  *      };
     131              :  * @endcode
     132              :  *
     133              :  * Example usage:
     134              :  *
     135              :  * @code{.c}
     136              :  *      DT_NVMEM_CELL_BY_IDX(DT_NODELABEL(eth), 0) // DT_NODELABEL(mac_address)
     137              :  * @endcode
     138              :  *
     139              :  * @param node_id node identifier for a node with a nvmem-cells property
     140              :  * @param idx index into the nvmem-cells property
     141              :  *
     142              :  * @return the node identifier for the NVMEM cell at index idx
     143              :  */
     144            1 : #define DT_NVMEM_CELL_BY_IDX(node_id, idx) DT_PHANDLE_BY_IDX(node_id, nvmem_cells, idx)
     145              : 
     146              : /**
     147              :  * @brief Equivalent to DT_NVMEM_CELL_BY_IDX(node_id, 0)
     148              :  *
     149              :  * @param node_id node identifier
     150              :  *
     151              :  * @return a node identifier for the NVMEM cell at index 0
     152              :  *         in "nvmem-cells"
     153              :  *
     154              :  * @see DT_NVMEM_CELL_BY_IDX()
     155              :  */
     156            1 : #define DT_NVMEM_CELL(node_id) DT_NVMEM_CELL_BY_IDX(node_id, 0)
     157              : 
     158              : /**
     159              :  * @brief Get the node identifier for the NVMEM cell from the nvmem-cells property by name.
     160              :  *
     161              :  * Example devicetree fragment:
     162              :  *
     163              :  * @code{.dts}
     164              :  *      mac_eeprom: mac_eeprom@2 {
     165              :  *              nvmem-layout {
     166              :  *                      compatible = "fixed-layout";
     167              :  *                      #address-cells = <1>;
     168              :  *                      #size-cells = <1>;
     169              :  *
     170              :  *                      mac_address: mac_address@fa {
     171              :  *                              reg = <0xfa 0x06>;
     172              :  *                              #nvmem-cell-cells = <0>;
     173              :  *                      };
     174              :  *              };
     175              :  *      };
     176              :  *
     177              :  *      eth: ethernet {
     178              :  *              nvmem-cells = <&mac_address>;
     179              :  *              nvmem-cell-names = "mac-address";
     180              :  *      };
     181              :  * @endcode
     182              :  *
     183              :  * Example usage:
     184              :  *
     185              :  * @code{.c}
     186              :  *      DT_NVMEM_CELL_BY_NAME(DT_NODELABEL(eth), mac_address) // DT_NODELABEL(mac_address)
     187              :  * @endcode
     188              :  *
     189              :  * @param node_id node identifier for a node with a nvmem-cells property
     190              :  * @param name lowercase-and-underscores name of an nvmem-cells element
     191              :  *             as defined by the node's nvmem-cell-names property
     192              :  *
     193              :  * @return the node identifier for the NVMEM cell by name
     194              :  */
     195            1 : #define DT_NVMEM_CELL_BY_NAME(node_id, name) DT_PHANDLE_BY_NAME(node_id, nvmem_cells, name)
     196              : 
     197              : /**
     198              :  * @brief Equivalent to DT_NVMEM_CELLS_HAS_IDX(DT_DRV_INST(inst), idx)
     199              :  *
     200              :  * @param inst DT_DRV_COMPAT instance number; may or may not have any nvmem-cells property
     201              :  * @param idx index of an nvmem-cells property phandle-array whose existence to check
     202              :  *
     203              :  * @return 1 if the index exists, 0 otherwise
     204              :  */
     205            1 : #define DT_INST_NVMEM_CELLS_HAS_IDX(inst, idx) DT_NVMEM_CELLS_HAS_IDX(DT_DRV_INST(inst), idx)
     206              : 
     207              : /**
     208              :  * @brief Equivalent to DT_NVMEM_CELLS_HAS_NAME(DT_DRV_INST(inst), name)
     209              :  *
     210              :  * @param inst DT_DRV_COMPAT instance number; may or may not have any nvmem-cell-names property.
     211              :  * @param name lowercase-and-underscores nvmem-cell-names cell value name to check
     212              :  *
     213              :  * @return 1 if the nvmem cell name exists, 0 otherwise
     214              :  */
     215            1 : #define DT_INST_NVMEM_CELLS_HAS_NAME(inst, name) DT_NVMEM_CELLS_HAS_NAME(DT_DRV_INST(inst), name)
     216              : 
     217              : /**
     218              :  * @brief Equivalent to DT_NUM_NVMEM_CELLS(DT_DRV_INST(inst))
     219              :  *
     220              :  * @param inst instance number
     221              :  *
     222              :  * @return number of elements in the nvmem-cells property
     223              :  */
     224            1 : #define DT_INST_NUM_NVMEM_CELLS(inst) DT_NUM_NVMEM_CELLS(DT_DRV_INST(inst))
     225              : 
     226              : /**
     227              :  * @brief Get the node identifier for the controller phandle from an
     228              :  *        nvmem-cells phandle-array property at an index
     229              :  *
     230              :  * @param inst instance number
     231              :  * @param idx logical index into nvmem-cells
     232              :  *
     233              :  * @return the node identifier for the nvmem cell referenced at
     234              :  *         index "idx"
     235              :  *
     236              :  * @see DT_NVMEM_CELL_CTLR_BY_IDX()
     237              :  */
     238            1 : #define DT_INST_NVMEM_CELL_BY_IDX(inst, idx) DT_NVMEM_CELL_BY_IDX(DT_DRV_INST(inst), idx)
     239              : 
     240              : /**
     241              :  * @brief Equivalent to DT_INST_NVMEM_CELL_BY_IDX(inst, 0)
     242              :  *
     243              :  * @param inst instance number
     244              :  *
     245              :  * @return a node identifier for the nvmem cell at index 0
     246              :  *         in nvmem-cells
     247              :  *
     248              :  * @see DT_NVMEM_CELL()
     249              :  */
     250            1 : #define DT_INST_NVMEM_CELL(inst) DT_INST_NVMEM_CELL_BY_IDX(inst, 0)
     251              : 
     252              : /**
     253              :  * @brief Get the node identifier for the controller phandle from an
     254              :  *        nvmem-cells phandle-array property by name
     255              :  *
     256              :  * @param inst instance number
     257              :  * @param name lowercase-and-underscores name of an nvmem-cells element
     258              :  *             as defined by the node's nvmem-cell-names property
     259              :  *
     260              :  * @return the node identifier for the nvmem cell referenced by
     261              :  *         the named element
     262              :  *
     263              :  * @see DT_NVMEM_CELL_BY_NAME()
     264              :  */
     265            1 : #define DT_INST_NVMEM_CELL_BY_NAME(inst, name) DT_NVMEM_CELL_BY_NAME(DT_DRV_INST(inst), name)
     266              : 
     267              : /**
     268              :  * @brief Get the node identifier of the memory controller for an nvmem cell.
     269              :  *
     270              :  * Example devicetree fragment:
     271              :  *
     272              :  * @code{.dts}
     273              :  *      mac_eeprom: mac_eeprom@2 {
     274              :  *              nvmem-layout {
     275              :  *                      compatible = "fixed-layout";
     276              :  *                      #address-cells = <1>;
     277              :  *                      #size-cells = <1>;
     278              :  *
     279              :  *                      mac_address: mac_address@fa {
     280              :  *                              reg = <0xfa 0x06>;
     281              :  *                              #nvmem-cell-cells = <0>;
     282              :  *                      };
     283              :  *              };
     284              :  *      };
     285              :  *
     286              :  *      eth: ethernet {
     287              :  *              nvmem-cells = <&mac_address>;
     288              :  *              nvmem-cell-names = "mac-address";
     289              :  *      };
     290              :  * @endcode
     291              :  *
     292              :  * Example usage:
     293              :  *
     294              :  * @code{.c}
     295              :  *      DT_MTD_FROM_NVMEM_CELL(DT_NVMEM_CELL(DT_NODELABEL(eth))) // DT_NODELABEL(mac_eeprom)
     296              :  * @endcode
     297              :  *
     298              :  * @param node_id node identifier for an nvmem cell node
     299              :  *
     300              :  * @return the node identifier of the Memory Technology Device (MTD) that
     301              :  *         contains the nvmem cell node.
     302              :  */
     303            1 : #define DT_MTD_FROM_NVMEM_CELL(node_id) DT_GPARENT(node_id)
     304              : 
     305              : /**
     306              :  * @}
     307              :  */
     308              : 
     309              : #ifdef __cplusplus
     310              : }
     311              : #endif
     312              : 
     313              : #endif /* INCLUDE_ZEPHYR_DEVICETREE_NVMEM_H_ */
        

Generated by: LCOV version 2.0-1