Line data    Source code

       1           1 : /**
       2             :  * @file
       3             :  * @brief Flash 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_FIXED_PARTITION_H_
      13             : #define ZEPHYR_INCLUDE_DEVICETREE_FIXED_PARTITION_H_
      14             : 
      15             : #ifdef __cplusplus
      16             : extern "C" {
      17             : #endif
      18             : 
      19             : /**
      20             :  * @defgroup devicetree-fixed-partition Devicetree Fixed Partition API
      21             :  * @ingroup devicetree
      22             :  * @{
      23             :  */
      24             : 
      25             : /**
      26             :  * @brief Get a node identifier for a fixed partition with
      27             :  *        a given label property
      28             :  *
      29             :  * Example devicetree fragment:
      30             :  *
      31             :  *     flash@... {
      32             :  *              partitions {
      33             :  *                      compatible = "fixed-partitions";
      34             :  *                      boot_partition: partition@0 {
      35             :  *                              label = "mcuboot";
      36             :  *                      };
      37             :  *                      slot0_partition: partition@c000 {
      38             :  *                              label = "image-0";
      39             :  *                      };
      40             :  *                      ...
      41             :  *              };
      42             :  *     };
      43             :  *
      44             :  * Example usage:
      45             :  *
      46             :  *     DT_NODE_BY_FIXED_PARTITION_LABEL(mcuboot) // node identifier for boot_partition
      47             :  *     DT_NODE_BY_FIXED_PARTITION_LABEL(image_0) // node identifier for slot0_partition
      48             :  *
      49             :  * @param label lowercase-and-underscores label property value
      50             :  * @return a node identifier for the partition with that label property
      51             :  */
      52           1 : #define DT_NODE_BY_FIXED_PARTITION_LABEL(label) \
      53             :         DT_CAT(DT_COMPAT_fixed_partitions_LABEL_, label)
      54             : 
      55             : /**
      56             :  * @brief Test if a fixed partition with a given label property exists
      57             :  * @param label lowercase-and-underscores label property value
      58             :  * @return 1 if any "fixed-partitions" child node has the given label,
      59             :  *         0 otherwise.
      60             :  */
      61           1 : #define DT_HAS_FIXED_PARTITION_LABEL(label) \
      62             :         IS_ENABLED(DT_CAT3(DT_COMPAT_fixed_partitions_LABEL_, label, _EXISTS))
      63             : 
      64             : /**
      65             :  * @brief Test if fixed-partition compatible node exists
      66             :  *
      67             :  * @param node_id DTS node to test
      68             :  * @return 1 if node exists and is fixed-partition compatible, 0 otherwise.
      69             :  */
      70           1 : #define DT_FIXED_PARTITION_EXISTS(node_id)              \
      71             :         DT_NODE_HAS_COMPAT(DT_PARENT(node_id), fixed_partitions)
      72             : 
      73             : /**
      74             :  * @brief Get a numeric identifier for a fixed partition
      75             :  * @param node_id node identifier for a fixed-partitions child node
      76             :  * @return the partition's ID, a unique zero-based index number
      77             :  */
      78           1 : #define DT_FIXED_PARTITION_ID(node_id) DT_CAT(node_id, _PARTITION_ID)
      79             : 
      80             : /**
      81             :  * @brief Get the node identifier of the flash memory for a partition
      82             :  * @param node_id node identifier for a fixed-partitions child node
      83             :  * @return the node identifier of the internal memory that contains the
      84             :  * fixed-partitions node, or @ref DT_INVALID_NODE if it doesn't exist.
      85             :  */
      86           1 : #define DT_MEM_FROM_FIXED_PARTITION(node_id)                                                       \
      87             :         COND_CODE_1(DT_NODE_HAS_COMPAT(DT_GPARENT(node_id), soc_nv_flash), (DT_GPARENT(node_id)),  \
      88             :                     (DT_INVALID_NODE))
      89             : 
      90             : /**
      91             :  * @brief Get the node identifier of the flash controller for a partition
      92             :  * @param node_id node identifier for a fixed-partitions child node
      93             :  * @return the node identifier of the memory technology device that
      94             :  * contains the fixed-partitions node.
      95             :  */
      96           1 : #define DT_MTD_FROM_FIXED_PARTITION(node_id)                                                       \
      97             :         COND_CODE_1(DT_NODE_EXISTS(DT_MEM_FROM_FIXED_PARTITION(node_id)),                          \
      98             :                     (DT_PARENT(DT_MEM_FROM_FIXED_PARTITION(node_id))), (DT_GPARENT(node_id)))
      99             : 
     100             : /**
     101             :  * @brief Get the absolute address of a fixed partition
     102             :  *
     103             :  * Example devicetree fragment:
     104             :  *
     105             :  *     &flash_controller {
     106             :  *             flash@1000000 {
     107             :  *                     compatible = "soc-nv-flash";
     108             :  *                     partitions {
     109             :  *                             compatible = "fixed-partitions";
     110             :  *                             storage_partition: partition@3a000 {
     111             :  *                                     label = "storage";
     112             :  *                             };
     113             :  *                     };
     114             :  *             };
     115             :  *     };
     116             :  *
     117             :  * Here, the "storage" partition is seen to belong to flash memory
     118             :  * starting at address 0x1000000. The partition's unit address of
     119             :  * 0x3a000 represents an offset inside that flash memory.
     120             :  *
     121             :  * Example usage:
     122             :  *
     123             :  *     DT_FIXED_PARTITION_ADDR(DT_NODELABEL(storage_partition)) // 0x103a000
     124             :  *
     125             :  * This macro can only be used with partitions of internal memory
     126             :  * addressable by the CPU. Otherwise, it may produce a compile-time
     127             :  * error, such as: `'__REG_IDX_0_VAL_ADDRESS' undeclared`.
     128             :  *
     129             :  * @param node_id node identifier for a fixed-partitions child node
     130             :  * @return the partition's offset plus the base address of the flash
     131             :  * node containing it.
     132             :  */
     133           1 : #define DT_FIXED_PARTITION_ADDR(node_id)                                                           \
     134             :         (DT_REG_ADDR(DT_MEM_FROM_FIXED_PARTITION(node_id)) + DT_REG_ADDR(node_id))
     135             : 
     136             : /**
     137             :  * @}
     138             :  */
     139             : 
     140             : #ifdef __cplusplus
     141             : }
     142             : #endif
     143             : 
     144             : #endif  /* ZEPHYR_INCLUDE_DEVICETREE_FIXED_PARTITION_H_ */