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