Masahiro Yamada | 6dd1052 | 2020-04-16 18:30:18 +0900 | [diff] [blame] | 1 | /* SPDX-License-Identifier: GPL-2.0 */ |
| 2 | |
| 3 | #ifndef _FDT_REGION_H |
| 4 | #define _FDT_REGION_H |
| 5 | |
| 6 | #ifndef SWIG /* Not available in Python */ |
| 7 | struct fdt_region { |
| 8 | int offset; |
| 9 | int size; |
| 10 | }; |
| 11 | |
| 12 | /* |
| 13 | * Flags for fdt_find_regions() |
| 14 | * |
| 15 | * Add a region for the string table (always the last region) |
| 16 | */ |
| 17 | #define FDT_REG_ADD_STRING_TAB (1 << 0) |
| 18 | |
| 19 | /* |
| 20 | * Add all supernodes of a matching node/property, useful for creating a |
| 21 | * valid subset tree |
| 22 | */ |
| 23 | #define FDT_REG_SUPERNODES (1 << 1) |
| 24 | |
| 25 | /* Add the FDT_BEGIN_NODE tags of subnodes, including their names */ |
| 26 | #define FDT_REG_DIRECT_SUBNODES (1 << 2) |
| 27 | |
| 28 | /* Add all subnodes of a matching node */ |
| 29 | #define FDT_REG_ALL_SUBNODES (1 << 3) |
| 30 | |
| 31 | /* Add a region for the mem_rsvmap table (always the first region) */ |
| 32 | #define FDT_REG_ADD_MEM_RSVMAP (1 << 4) |
| 33 | |
| 34 | /* Indicates what an fdt part is (node, property, value) */ |
| 35 | #define FDT_IS_NODE (1 << 0) |
| 36 | #define FDT_IS_PROP (1 << 1) |
| 37 | #define FDT_IS_VALUE (1 << 2) /* not supported */ |
| 38 | #define FDT_IS_COMPAT (1 << 3) /* used internally */ |
| 39 | #define FDT_NODE_HAS_PROP (1 << 4) /* node contains prop */ |
| 40 | |
| 41 | #define FDT_ANY_GLOBAL (FDT_IS_NODE | FDT_IS_PROP | FDT_IS_VALUE | \ |
| 42 | FDT_IS_COMPAT) |
| 43 | #define FDT_IS_ANY 0x1f /* all the above */ |
| 44 | |
| 45 | /* We set a reasonable limit on the number of nested nodes */ |
| 46 | #define FDT_MAX_DEPTH 32 |
| 47 | |
| 48 | /* Decribes what we want to include from the current tag */ |
| 49 | enum want_t { |
| 50 | WANT_NOTHING, |
| 51 | WANT_NODES_ONLY, /* No properties */ |
| 52 | WANT_NODES_AND_PROPS, /* Everything for one level */ |
| 53 | WANT_ALL_NODES_AND_PROPS /* Everything for all levels */ |
| 54 | }; |
| 55 | |
| 56 | /* Keeps track of the state at parent nodes */ |
| 57 | struct fdt_subnode_stack { |
| 58 | int offset; /* Offset of node */ |
| 59 | enum want_t want; /* The 'want' value here */ |
| 60 | int included; /* 1 if we included this node, 0 if not */ |
| 61 | }; |
| 62 | |
| 63 | struct fdt_region_ptrs { |
| 64 | int depth; /* Current tree depth */ |
| 65 | int done; /* What we have completed scanning */ |
| 66 | enum want_t want; /* What we are currently including */ |
| 67 | char *end; /* Pointer to end of full node path */ |
| 68 | int nextoffset; /* Next node offset to check */ |
| 69 | }; |
| 70 | |
| 71 | /* The state of our finding algortihm */ |
| 72 | struct fdt_region_state { |
| 73 | struct fdt_subnode_stack stack[FDT_MAX_DEPTH]; /* node stack */ |
| 74 | struct fdt_region *region; /* Contains list of regions found */ |
| 75 | int count; /* Numnber of regions found */ |
| 76 | const void *fdt; /* FDT blob */ |
| 77 | int max_regions; /* Maximum regions to find */ |
| 78 | int can_merge; /* 1 if we can merge with previous region */ |
| 79 | int start; /* Start position of current region */ |
Simon Glass | 62a48b4 | 2021-12-08 09:55:35 -0700 | [diff] [blame] | 80 | bool have_node; /* True if any node is included */ |
Masahiro Yamada | 6dd1052 | 2020-04-16 18:30:18 +0900 | [diff] [blame] | 81 | struct fdt_region_ptrs ptrs; /* Pointers for what we are up to */ |
| 82 | }; |
| 83 | |
| 84 | /** |
| 85 | * fdt_find_regions() - find regions in device tree |
| 86 | * |
| 87 | * Given a list of nodes to include and properties to exclude, find |
| 88 | * the regions of the device tree which describe those included parts. |
| 89 | * |
| 90 | * The intent is to get a list of regions which will be invariant provided |
| 91 | * those parts are invariant. For example, if you request a list of regions |
| 92 | * for all nodes but exclude the property "data", then you will get the |
| 93 | * same region contents regardless of any change to "data" properties. |
| 94 | * |
| 95 | * This function can be used to produce a byte-stream to send to a hashing |
| 96 | * function to verify that critical parts of the FDT have not changed. |
| 97 | * |
| 98 | * Nodes which are given in 'inc' are included in the region list, as |
| 99 | * are the names of the immediate subnodes nodes (but not the properties |
| 100 | * or subnodes of those subnodes). |
| 101 | * |
| 102 | * For eaxample "/" means to include the root node, all root properties |
| 103 | * and the FDT_BEGIN_NODE and FDT_END_NODE of all subnodes of /. The latter |
| 104 | * ensures that we capture the names of the subnodes. In a hashing situation |
| 105 | * it prevents the root node from changing at all Any change to non-excluded |
| 106 | * properties, names of subnodes or number of subnodes would be detected. |
| 107 | * |
| 108 | * When used with FITs this provides the ability to hash and sign parts of |
| 109 | * the FIT based on different configurations in the FIT. Then it is |
| 110 | * impossible to change anything about that configuration (include images |
| 111 | * attached to the configuration), but it may be possible to add new |
| 112 | * configurations, new images or new signatures within the existing |
| 113 | * framework. |
| 114 | * |
| 115 | * Adding new properties to a device tree may result in the string table |
| 116 | * being extended (if the new property names are different from those |
| 117 | * already added). This function can optionally include a region for |
| 118 | * the string table so that this can be part of the hash too. |
| 119 | * |
| 120 | * The device tree header is not included in the list. |
| 121 | * |
| 122 | * @fdt: Device tree to check |
| 123 | * @inc: List of node paths to included |
| 124 | * @inc_count: Number of node paths in list |
| 125 | * @exc_prop: List of properties names to exclude |
| 126 | * @exc_prop_count: Number of properties in exclude list |
| 127 | * @region: Returns list of regions |
| 128 | * @max_region: Maximum length of region list |
| 129 | * @path: Pointer to a temporary string for the function to use for |
| 130 | * building path names |
| 131 | * @path_len: Length of path, must be large enough to hold the longest |
| 132 | * path in the tree |
| 133 | * @add_string_tab: 1 to add a region for the string table |
| 134 | * @return number of regions in list. If this is >max_regions then the |
| 135 | * region array was exhausted. You should increase max_regions and try |
| 136 | * the call again. |
| 137 | */ |
| 138 | int fdt_find_regions(const void *fdt, char * const inc[], int inc_count, |
| 139 | char * const exc_prop[], int exc_prop_count, |
| 140 | struct fdt_region region[], int max_regions, |
| 141 | char *path, int path_len, int add_string_tab); |
| 142 | |
| 143 | /** |
| 144 | * fdt_first_region() - find regions in device tree |
| 145 | * |
| 146 | * Given a nodes and properties to include and properties to exclude, find |
| 147 | * the regions of the device tree which describe those included parts. |
| 148 | * |
| 149 | * The use for this function is twofold. Firstly it provides a convenient |
| 150 | * way of performing a structure-aware grep of the tree. For example it is |
| 151 | * possible to grep for a node and get all the properties associated with |
| 152 | * that node. Trees can be subsetted easily, by specifying the nodes that |
| 153 | * are required, and then writing out the regions returned by this function. |
| 154 | * This is useful for small resource-constrained systems, such as boot |
| 155 | * loaders, which want to use an FDT but do not need to know about all of |
| 156 | * it. |
| 157 | * |
| 158 | * Secondly it makes it easy to hash parts of the tree and detect changes. |
| 159 | * The intent is to get a list of regions which will be invariant provided |
| 160 | * those parts are invariant. For example, if you request a list of regions |
| 161 | * for all nodes but exclude the property "data", then you will get the |
| 162 | * same region contents regardless of any change to "data" properties. |
| 163 | * |
| 164 | * This function can be used to produce a byte-stream to send to a hashing |
| 165 | * function to verify that critical parts of the FDT have not changed. |
| 166 | * Note that semantically null changes in order could still cause false |
| 167 | * hash misses. Such reordering might happen if the tree is regenerated |
| 168 | * from source, and nodes are reordered (the bytes-stream will be emitted |
| 169 | * in a different order and many hash functions will detect this). However |
| 170 | * if an existing tree is modified using libfdt functions, such as |
| 171 | * fdt_add_subnode() and fdt_setprop(), then this problem is avoided. |
| 172 | * |
| 173 | * The nodes/properties to include/exclude are defined by a function |
| 174 | * provided by the caller. This function is called for each node and |
| 175 | * property, and must return: |
| 176 | * |
| 177 | * 0 - to exclude this part |
| 178 | * 1 - to include this part |
| 179 | * -1 - for FDT_IS_PROP only: no information is available, so include |
| 180 | * if its containing node is included |
| 181 | * |
| 182 | * The last case is only used to deal with properties. Often a property is |
| 183 | * included if its containing node is included - this is the case where |
| 184 | * -1 is returned.. However if the property is specifically required to be |
| 185 | * included/excluded, then 0 or 1 can be returned. Note that including a |
| 186 | * property when the FDT_REG_SUPERNODES flag is given will force its |
| 187 | * containing node to be included since it is not valid to have a property |
| 188 | * that is not in a node. |
| 189 | * |
| 190 | * Using the information provided, the inclusion of a node can be controlled |
| 191 | * either by a node name or its compatible string, or any other property |
| 192 | * that the function can determine. |
| 193 | * |
| 194 | * As an example, including node "/" means to include the root node and all |
| 195 | * root properties. A flag provides a way of also including supernodes (of |
| 196 | * which there is none for the root node), and another flag includes |
| 197 | * immediate subnodes, so in this case we would get the FDT_BEGIN_NODE and |
| 198 | * FDT_END_NODE of all subnodes of /. |
| 199 | * |
| 200 | * The subnode feature helps in a hashing situation since it prevents the |
| 201 | * root node from changing at all. Any change to non-excluded properties, |
| 202 | * names of subnodes or number of subnodes would be detected. |
| 203 | * |
| 204 | * When used with FITs this provides the ability to hash and sign parts of |
| 205 | * the FIT based on different configurations in the FIT. Then it is |
| 206 | * impossible to change anything about that configuration (include images |
| 207 | * attached to the configuration), but it may be possible to add new |
| 208 | * configurations, new images or new signatures within the existing |
| 209 | * framework. |
| 210 | * |
| 211 | * Adding new properties to a device tree may result in the string table |
| 212 | * being extended (if the new property names are different from those |
| 213 | * already added). This function can optionally include a region for |
| 214 | * the string table so that this can be part of the hash too. This is always |
| 215 | * the last region. |
| 216 | * |
| 217 | * The FDT also has a mem_rsvmap table which can also be included, and is |
| 218 | * always the first region if so. |
| 219 | * |
| 220 | * The device tree header is not included in the region list. Since the |
| 221 | * contents of the FDT are changing (shrinking, often), the caller will need |
| 222 | * to regenerate the header anyway. |
| 223 | * |
| 224 | * @fdt: Device tree to check |
| 225 | * @h_include: Function to call to determine whether to include a part or |
| 226 | * not: |
| 227 | * |
| 228 | * @priv: Private pointer as passed to fdt_find_regions() |
| 229 | * @fdt: Pointer to FDT blob |
| 230 | * @offset: Offset of this node / property |
| 231 | * @type: Type of this part, FDT_IS_... |
| 232 | * @data: Pointer to data (node name, property name, compatible |
| 233 | * string, value (not yet supported) |
| 234 | * @size: Size of data, or 0 if none |
| 235 | * @return 0 to exclude, 1 to include, -1 if no information is |
| 236 | * available |
| 237 | * @priv: Private pointer passed to h_include |
| 238 | * @region: Returns list of regions, sorted by offset |
| 239 | * @max_regions: Maximum length of region list |
| 240 | * @path: Pointer to a temporary string for the function to use for |
| 241 | * building path names |
| 242 | * @path_len: Length of path, must be large enough to hold the longest |
| 243 | * path in the tree |
| 244 | * @flags: Various flags that control the region algortihm, see |
| 245 | * FDT_REG_... |
| 246 | * @return number of regions in list. If this is >max_regions then the |
| 247 | * region array was exhausted. You should increase max_regions and try |
| 248 | * the call again. Only the first max_regions elements are available in the |
| 249 | * array. |
| 250 | * |
| 251 | * On error a -ve value is return, which can be: |
| 252 | * |
| 253 | * -FDT_ERR_BADSTRUCTURE (too deep or more END tags than BEGIN tags |
| 254 | * -FDT_ERR_BADLAYOUT |
| 255 | * -FDT_ERR_NOSPACE (path area is too small) |
| 256 | */ |
| 257 | int fdt_first_region(const void *fdt, |
| 258 | int (*h_include)(void *priv, const void *fdt, int offset, |
| 259 | int type, const char *data, int size), |
| 260 | void *priv, struct fdt_region *region, |
| 261 | char *path, int path_len, int flags, |
| 262 | struct fdt_region_state *info); |
| 263 | |
| 264 | /** fdt_next_region() - find next region |
| 265 | * |
| 266 | * See fdt_first_region() for full description. This function finds the |
| 267 | * next region according to the provided parameters, which must be the same |
| 268 | * as passed to fdt_first_region(). |
| 269 | * |
| 270 | * This function can additionally return -FDT_ERR_NOTFOUND when there are no |
| 271 | * more regions |
| 272 | */ |
| 273 | int fdt_next_region(const void *fdt, |
| 274 | int (*h_include)(void *priv, const void *fdt, int offset, |
| 275 | int type, const char *data, int size), |
| 276 | void *priv, struct fdt_region *region, |
| 277 | char *path, int path_len, int flags, |
| 278 | struct fdt_region_state *info); |
| 279 | |
| 280 | /** |
| 281 | * fdt_add_alias_regions() - find aliases that point to existing regions |
| 282 | * |
| 283 | * Once a device tree grep is complete some of the nodes will be present |
| 284 | * and some will have been dropped. This function checks all the alias nodes |
| 285 | * to figure out which points point to nodes which are still present. These |
| 286 | * aliases need to be kept, along with the nodes they reference. |
| 287 | * |
| 288 | * Given a list of regions function finds the aliases that still apply and |
| 289 | * adds more regions to the list for these. This function is called after |
| 290 | * fdt_next_region() has finished returning regions and requires the same |
| 291 | * state. |
| 292 | * |
| 293 | * @fdt: Device tree file to reference |
| 294 | * @region: List of regions that will be kept |
| 295 | * @count: Number of regions |
| 296 | * @max_regions: Number of entries that can fit in @region |
| 297 | * @info: Region state as returned from fdt_next_region() |
| 298 | * @return new number of regions in @region (i.e. count + the number added) |
| 299 | * or -FDT_ERR_NOSPACE if there was not enough space. |
| 300 | */ |
| 301 | int fdt_add_alias_regions(const void *fdt, struct fdt_region *region, int count, |
| 302 | int max_regions, struct fdt_region_state *info); |
| 303 | #endif /* SWIG */ |
| 304 | |
| 305 | #endif /* _FDT_REGION_H */ |