include/dm/ofnode_decl.h

   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  * For now these points use constant types, since we don't allow writing
  35  * the DT.
  36  *
  37  * @np: Pointer to device node, used for live tree
  38  * @of_offset: Pointer into flat device tree, used for flat tree. Note that this
  39  *      is not a really a pointer to a node: it is an offset value. See above.
  40  */
  41 typedef union ofnode_union {
  42         const struct device_node *np;
  43         long of_offset;
  44 } ofnode;
  45
  46 /**
  47  * struct ofprop - reference to a property of a device tree node
  48  *
  49  * This struct hold the reference on one property of one node,
  50  * using struct ofnode and an offset within the flat device tree or either
  51  * a pointer to a struct property in the live device tree.
  52  *
  53  * Thus we can reference arguments in both the live tree and the flat tree.
  54  *
  55  * The property reference can also hold a null reference. This corresponds to
  56  * a struct property NULL pointer or an offset of -1.
  57  *
  58  * @node: Pointer to device node
  59  * @offset: Pointer into flat device tree, used for flat tree.
  60  * @prop: Pointer to property, used for live treee.
  61  */
  62
  63 struct ofprop {
  64         ofnode node;
  65         union {
  66                 int offset;
  67                 const struct property *prop;
  68         };
  69 };
  70
  71 #endif
  72