1 /* SPDX-License-Identifier: GPL-2.0+ */ 2 /* 3 * Copyright 2022 Google LLC 4 * Written by Simon Glass <sjg@chromium.org> 5 */ 6 7 #ifndef _DM_OFNODE_DECL_H 8 #define _DM_OFNODE_DECL_H 9 10 /** 11 * typedef union ofnode_union ofnode - reference to a device tree node 12 * 13 * This union can hold either a straightforward pointer to a struct device_node 14 * in the live device tree, or an offset within the flat device tree. In the 15 * latter case, the pointer value is just the integer offset within the flat DT. 16 * 17 * Thus we can reference nodes in both the live tree (once available) and the 18 * flat tree (until then). Functions are available to translate between an 19 * ofnode and either an offset or a `struct device_node *`. 20 * 21 * The reference can also hold a null offset, in which case the pointer value 22 * here is NULL. This corresponds to a struct device_node * value of 23 * NULL, or an offset of -1. 24 * 25 * There is no ambiguity as to whether ofnode holds an offset or a node 26 * pointer: when the live tree is active it holds a node pointer, otherwise it 27 * holds an offset. The value itself does not need to be unique and in theory 28 * the same value could point to a valid device node or a valid offset. We 29 * could arrange for a unique value to be used (e.g. by making the pointer 30 * point to an offset within the flat device tree in the case of an offset) but 31 * this increases code size slightly due to the subtraction. Since it offers no 32 * real benefit, the approach described here seems best. 33 * 34 * Where multiple trees are in use, this works without any trouble with live 35 * tree, except for aliases, such as ofnode_path("mmc0"), which only work on the 36 * control FDT. When the flat tree is in use, the trees are registered and a 37 * 'tree ID' is encoded into the top bits of @of_offset - see immediately below 38 * for the associated macro definitions. Note that 64-bit machines use the same 39 * encoding, even though there is more space available. This is partly because 40 * the FDT format contains 32-bit values for things like the string-table 41 * offset, therefore 64-bit offsets cannot be supported anyway. 42 * 43 * For the multiple-tree case, an invalid offset (i.e. with of_offset < 0) is 44 * still invalid. It does not contain a tree ID. So there is no way of knowing 45 * which tree produced the invalid offset. 46 * 47 * @np: Pointer to device node, used for live tree 48 * @of_offset: Pointer into flat device tree, used for flat tree. Note that this 49 * is not a really a pointer to a node: it is an offset value. See above. 50 */ 51 typedef union ofnode_union { 52 struct device_node *np; 53 long of_offset; 54 } ofnode; 55 56 /* shift for the tree ID within of_offset */ 57 #define OF_TREE_SHIFT 28 58 59 /* mask to obtain the device tree offset from of_offset */ 60 #define OF_TREE_MASK ((1 << OF_TREE_SHIFT) - 1) 61 62 /* encode a tree ID and node offset into an of_offset value */ 63 #define OFTREE_NODE(tree_id, offs) ((tree_id) << OF_TREE_SHIFT | (offs)) 64 65 /* decode the node offset from an of_offset value */ 66 #define OFTREE_OFFSET(of_offs) ((of_offs) & OF_TREE_MASK) 67 68 /* decode the tree ID from an of_offset value */ 69 #define OFTREE_TREE_ID(of_offs) ((of_offs) >> OF_TREE_SHIFT) 70 71 /* encode a node offset in the tree given by another node's of_offset value */ 72 #define OFTREE_MAKE_NODE(other_of_offset, offs) \ 73 (((offs) & OF_TREE_MASK) | ((other_of_offset) & ~OF_TREE_MASK)) 74 75 /** 76 * struct ofprop - reference to a property of a device tree node 77 * 78 * This struct hold the reference on one property of one node, 79 * using struct ofnode and an offset within the flat device tree or either 80 * a pointer to a struct property in the live device tree. 81 * 82 * Thus we can reference arguments in both the live tree and the flat tree. 83 * 84 * The property reference can also hold a null reference. This corresponds to 85 * a struct property NULL pointer or an offset of -1. 86 * 87 * @node: Pointer to device node 88 * @offset: Pointer into flat device tree, used for flat tree. 89 * @prop: Pointer to property, used for live tree. 90 */ 91 92 struct ofprop { 93 ofnode node; 94 union { 95 int offset; 96 const struct property *prop; 97 }; 98 }; 99 100 /** 101 * union oftree_union - reference to a tree of device tree nodes 102 * 103 * One or other of the members is used, depending on of_live_active() 104 * 105 * @np: Pointer to roott device node, used for live tree 106 * @fdt: Pointer to the flat device tree, used for flat tree 107 */ 108 typedef union oftree_union { 109 struct device_node *np; 110 void *fdt; 111 } oftree; 112 113 #endif 114 115