tools/dtoc/fdt.py

   1 #!/usr/bin/python
   2 # SPDX-License-Identifier: GPL-2.0+
   3 #
   4 # Copyright (C) 2016 Google, Inc
   5 # Written by Simon Glass <sjg@chromium.org>
   6 #
   7
   8 import struct
   9 import sys
  10
  11 import fdt_util
  12 import libfdt
  13 from libfdt import QUIET_NOTFOUND
  14
  15 # This deals with a device tree, presenting it as an assortment of Node and
  16 # Prop objects, representing nodes and properties, respectively. This file
  17 # contains the base classes and defines the high-level API. You can use
  18 # FdtScan() as a convenience function to create and scan an Fdt.
  19
  20 # This implementation uses a libfdt Python library to access the device tree,
  21 # so it is fairly efficient.
  22
  23 # A list of types we support
  24 (TYPE_BYTE, TYPE_INT, TYPE_STRING, TYPE_BOOL, TYPE_INT64) = range(5)
  25
  26 def CheckErr(errnum, msg):
  27     if errnum:
  28         raise ValueError('Error %d: %s: %s' %
  29             (errnum, libfdt.fdt_strerror(errnum), msg))
  30
  31 class Prop:
  32     """A device tree property
  33
  34     Properties:
  35         name: Property name (as per the device tree)
  36         value: Property value as a string of bytes, or a list of strings of
  37             bytes
  38         type: Value type
  39     """
  40     def __init__(self, node, offset, name, bytes):
  41         self._node = node
  42         self._offset = offset
  43         self.name = name
  44         self.value = None
  45         self.bytes = str(bytes)
  46         self.dirty = False
  47         if not bytes:
  48             self.type = TYPE_BOOL
  49             self.value = True
  50             return
  51         self.type, self.value = self.BytesToValue(bytes)
  52
  53     def RefreshOffset(self, poffset):
  54         self._offset = poffset
  55
  56     def Widen(self, newprop):
  57         """Figure out which property type is more general
  58
  59         Given a current property and a new property, this function returns the
  60         one that is less specific as to type. The less specific property will
  61         be ble to represent the data in the more specific property. This is
  62         used for things like:
  63
  64             node1 {
  65                 compatible = "fred";
  66                 value = <1>;
  67             };
  68             node1 {
  69                 compatible = "fred";
  70                 value = <1 2>;
  71             };
  72
  73         He we want to use an int array for 'value'. The first property
  74         suggests that a single int is enough, but the second one shows that
  75         it is not. Calling this function with these two propertes would
  76         update the current property to be like the second, since it is less
  77         specific.
  78         """
  79         if newprop.type < self.type:
  80             self.type = newprop.type
  81
  82         if type(newprop.value) == list and type(self.value) != list:
  83             self.value = [self.value]
  84
  85         if type(self.value) == list and len(newprop.value) > len(self.value):
  86             val = self.GetEmpty(self.type)
  87             while len(self.value) < len(newprop.value):
  88                 self.value.append(val)
  89
  90     def BytesToValue(self, bytes):
  91         """Converts a string of bytes into a type and value
  92
  93         Args:
  94             A string containing bytes
  95
  96         Return:
  97             A tuple:
  98                 Type of data
  99                 Data, either a single element or a list of elements. Each element
 100                 is one of:
 101                     TYPE_STRING: string value from the property
 102                     TYPE_INT: a byte-swapped integer stored as a 4-byte string
 103                     TYPE_BYTE: a byte stored as a single-byte string
 104         """
 105         bytes = str(bytes)
 106         size = len(bytes)
 107         strings = bytes.split('\0')
 108         is_string = True
 109         count = len(strings) - 1
 110         if count > 0 and not strings[-1]:
 111             for string in strings[:-1]:
 112                 if not string:
 113                     is_string = False
 114                     break
 115                 for ch in string:
 116                     if ch < ' ' or ch > '~':
 117                         is_string = False
 118                         break
 119         else:
 120             is_string = False
 121         if is_string:
 122             if count == 1:
 123                 return TYPE_STRING, strings[0]
 124             else:
 125                 return TYPE_STRING, strings[:-1]
 126         if size % 4:
 127             if size == 1:
 128                 return TYPE_BYTE, bytes[0]
 129             else:
 130                 return TYPE_BYTE, list(bytes)
 131         val = []
 132         for i in range(0, size, 4):
 133             val.append(bytes[i:i + 4])
 134         if size == 4:
 135             return TYPE_INT, val[0]
 136         else:
 137             return TYPE_INT, val
 138
 139     @classmethod
 140     def GetEmpty(self, type):
 141         """Get an empty / zero value of the given type
 142
 143         Returns:
 144             A single value of the given type
 145         """
 146         if type == TYPE_BYTE:
 147             return chr(0)
 148         elif type == TYPE_INT:
 149             return struct.pack('<I', 0);
 150         elif type == TYPE_STRING:
 151             return ''
 152         else:
 153             return True
 154
 155     def GetOffset(self):
 156         """Get the offset of a property
 157
 158         Returns:
 159             The offset of the property (struct fdt_property) within the file
 160         """
 161         self._node._fdt.CheckCache()
 162         return self._node._fdt.GetStructOffset(self._offset)
 163
 164     def SetInt(self, val):
 165         """Set the integer value of the property
 166
 167         The device tree is marked dirty so that the value will be written to
 168         the block on the next sync.
 169
 170         Args:
 171             val: Integer value (32-bit, single cell)
 172         """
 173         self.bytes = struct.pack('>I', val);
 174         self.value = val
 175         self.type = TYPE_INT
 176         self.dirty = True
 177
 178     def Sync(self, auto_resize=False):
 179         """Sync property changes back to the device tree
 180
 181         This updates the device tree blob with any changes to this property
 182         since the last sync.
 183
 184         Args:
 185             auto_resize: Resize the device tree automatically if it does not
 186                 have enough space for the update
 187
 188         Raises:
 189             FdtException if auto_resize is False and there is not enough space
 190         """
 191         if self._offset is None or self.dirty:
 192             node = self._node
 193             fdt_obj = node._fdt._fdt_obj
 194             if auto_resize:
 195                 while fdt_obj.setprop(node.Offset(), self.name, self.bytes,
 196                                     (libfdt.NOSPACE,)) == -libfdt.NOSPACE:
 197                     fdt_obj.resize(fdt_obj.totalsize() + 1024)
 198                     fdt_obj.setprop(node.Offset(), self.name, self.bytes)
 199             else:
 200                 fdt_obj.setprop(node.Offset(), self.name, self.bytes)
 201
 202
 203 class Node:
 204     """A device tree node
 205
 206     Properties:
 207         offset: Integer offset in the device tree
 208         name: Device tree node tname
 209         path: Full path to node, along with the node name itself
 210         _fdt: Device tree object
 211         subnodes: A list of subnodes for this node, each a Node object
 212         props: A dict of properties for this node, each a Prop object.
 213             Keyed by property name
 214     """
 215     def __init__(self, fdt, parent, offset, name, path):
 216         self._fdt = fdt
 217         self.parent = parent
 218         self._offset = offset
 219         self.name = name
 220         self.path = path
 221         self.subnodes = []
 222         self.props = {}
 223
 224     def GetFdt(self):
 225         """Get the Fdt object for this node
 226
 227         Returns:
 228             Fdt object
 229         """
 230         return self._fdt
 231
 232     def FindNode(self, name):
 233         """Find a node given its name
 234
 235         Args:
 236             name: Node name to look for
 237         Returns:
 238             Node object if found, else None
 239         """
 240         for subnode in self.subnodes:
 241             if subnode.name == name:
 242                 return subnode
 243         return None
 244
 245     def Offset(self):
 246         """Returns the offset of a node, after checking the cache
 247
 248         This should be used instead of self._offset directly, to ensure that
 249         the cache does not contain invalid offsets.
 250         """
 251         self._fdt.CheckCache()
 252         return self._offset
 253
 254     def Scan(self):
 255         """Scan a node's properties and subnodes
 256
 257         This fills in the props and subnodes properties, recursively
 258         searching into subnodes so that the entire tree is built.
 259         """
 260         fdt_obj = self._fdt._fdt_obj
 261         self.props = self._fdt.GetProps(self)
 262         phandle = fdt_obj.get_phandle(self.Offset())
 263         if phandle:
 264             self._fdt.phandle_to_node[phandle] = self
 265
 266         offset = fdt_obj.first_subnode(self.Offset(), QUIET_NOTFOUND)
 267         while offset >= 0:
 268             sep = '' if self.path[-1] == '/' else '/'
 269             name = fdt_obj.get_name(offset)
 270             path = self.path + sep + name
 271             node = Node(self._fdt, self, offset, name, path)
 272             self.subnodes.append(node)
 273
 274             node.Scan()
 275             offset = fdt_obj.next_subnode(offset, QUIET_NOTFOUND)
 276
 277     def Refresh(self, my_offset):
 278         """Fix up the _offset for each node, recursively
 279
 280         Note: This does not take account of property offsets - these will not
 281         be updated.
 282         """
 283         fdt_obj = self._fdt._fdt_obj
 284         if self._offset != my_offset:
 285             self._offset = my_offset
 286         offset = fdt_obj.first_subnode(self._offset, QUIET_NOTFOUND)
 287         for subnode in self.subnodes:
 288             if subnode.name != fdt_obj.get_name(offset):
 289                 raise ValueError('Internal error, node name mismatch %s != %s' %
 290                                  (subnode.name, fdt_obj.get_name(offset)))
 291             subnode.Refresh(offset)
 292             offset = fdt_obj.next_subnode(offset, QUIET_NOTFOUND)
 293         if offset != -libfdt.FDT_ERR_NOTFOUND:
 294             raise ValueError('Internal error, offset == %d' % offset)
 295
 296         poffset = fdt_obj.first_property_offset(self._offset, QUIET_NOTFOUND)
 297         while poffset >= 0:
 298             p = fdt_obj.get_property_by_offset(poffset)
 299             prop = self.props.get(p.name)
 300             if not prop:
 301                 raise ValueError("Internal error, property '%s' missing, "
 302                                  'offset %d' % (p.name, poffset))
 303             prop.RefreshOffset(poffset)
 304             poffset = fdt_obj.next_property_offset(poffset, QUIET_NOTFOUND)
 305
 306     def DeleteProp(self, prop_name):
 307         """Delete a property of a node
 308
 309         The property is deleted and the offset cache is invalidated.
 310
 311         Args:
 312             prop_name: Name of the property to delete
 313         Raises:
 314             ValueError if the property does not exist
 315         """
 316         CheckErr(self._fdt._fdt_obj.delprop(self.Offset(), prop_name),
 317                  "Node '%s': delete property: '%s'" % (self.path, prop_name))
 318         del self.props[prop_name]
 319         self._fdt.Invalidate()
 320
 321     def AddZeroProp(self, prop_name):
 322         """Add a new property to the device tree with an integer value of 0.
 323
 324         Args:
 325             prop_name: Name of property
 326         """
 327         self.props[prop_name] = Prop(self, None, prop_name, '\0' * 4)
 328
 329     def SetInt(self, prop_name, val):
 330         """Update an integer property int the device tree.
 331
 332         This is not allowed to change the size of the FDT.
 333
 334         Args:
 335             prop_name: Name of property
 336             val: Value to set
 337         """
 338         self.props[prop_name].SetInt(val)
 339
 340     def Sync(self, auto_resize=False):
 341         """Sync node changes back to the device tree
 342
 343         This updates the device tree blob with any changes to this node and its
 344         subnodes since the last sync.
 345
 346         Args:
 347             auto_resize: Resize the device tree automatically if it does not
 348                 have enough space for the update
 349
 350         Raises:
 351             FdtException if auto_resize is False and there is not enough space
 352         """
 353         # Sync subnodes in reverse so that we don't disturb node offsets for
 354         # nodes that are earlier in the DT. This avoids an O(n^2) rescan of
 355         # node offsets.
 356         for node in reversed(self.subnodes):
 357             node.Sync(auto_resize)
 358
 359         # Sync properties now, whose offsets should not have been disturbed.
 360         # We do this after subnodes, since this disturbs the offsets of these
 361         # properties.
 362         prop_list = sorted(self.props.values(), key=lambda prop: prop._offset,
 363                            reverse=True)
 364         for prop in prop_list:
 365             prop.Sync(auto_resize)
 366
 367
 368 class Fdt:
 369     """Provides simple access to a flat device tree blob using libfdts.
 370
 371     Properties:
 372       fname: Filename of fdt
 373       _root: Root of device tree (a Node object)
 374     """
 375     def __init__(self, fname):
 376         self._fname = fname
 377         self._cached_offsets = False
 378         self.phandle_to_node = {}
 379         if self._fname:
 380             self._fname = fdt_util.EnsureCompiled(self._fname)
 381
 382             with open(self._fname) as fd:
 383                 self._fdt_obj = libfdt.Fdt(fd.read())
 384
 385     def LookupPhandle(self, phandle):
 386         """Look up a phandle
 387
 388         Args:
 389             phandle: Phandle to look up (int)
 390
 391         Returns:
 392             Node object the phandle points to
 393         """
 394         return self.phandle_to_node.get(phandle)
 395
 396     def Scan(self, root='/'):
 397         """Scan a device tree, building up a tree of Node objects
 398
 399         This fills in the self._root property
 400
 401         Args:
 402             root: Ignored
 403
 404         TODO(sjg@chromium.org): Implement the 'root' parameter
 405         """
 406         self._cached_offsets = True
 407         self._root = self.Node(self, None, 0, '/', '/')
 408         self._root.Scan()
 409
 410     def GetRoot(self):
 411         """Get the root Node of the device tree
 412
 413         Returns:
 414             The root Node object
 415         """
 416         return self._root
 417
 418     def GetNode(self, path):
 419         """Look up a node from its path
 420
 421         Args:
 422             path: Path to look up, e.g. '/microcode/update@0'
 423         Returns:
 424             Node object, or None if not found
 425         """
 426         node = self._root
 427         parts = path.split('/')
 428         if len(parts) < 2:
 429             return None
 430         for part in parts[1:]:
 431             node = node.FindNode(part)
 432             if not node:
 433                 return None
 434         return node
 435
 436     def Flush(self):
 437         """Flush device tree changes back to the file
 438
 439         If the device tree has changed in memory, write it back to the file.
 440         """
 441         with open(self._fname, 'wb') as fd:
 442             fd.write(self._fdt_obj.as_bytearray())
 443
 444     def Sync(self, auto_resize=False):
 445         """Make sure any DT changes are written to the blob
 446
 447         Args:
 448             auto_resize: Resize the device tree automatically if it does not
 449                 have enough space for the update
 450
 451         Raises:
 452             FdtException if auto_resize is False and there is not enough space
 453         """
 454         self._root.Sync(auto_resize)
 455         self.Invalidate()
 456
 457     def Pack(self):
 458         """Pack the device tree down to its minimum size
 459
 460         When nodes and properties shrink or are deleted, wasted space can
 461         build up in the device tree binary.
 462         """
 463         CheckErr(self._fdt_obj.pack(), 'pack')
 464         self.Invalidate()
 465
 466     def GetContents(self):
 467         """Get the contents of the FDT
 468
 469         Returns:
 470             The FDT contents as a string of bytes
 471         """
 472         return self._fdt_obj.as_bytearray()
 473
 474     def GetFdtObj(self):
 475         """Get the contents of the FDT
 476
 477         Returns:
 478             The FDT contents as a libfdt.Fdt object
 479         """
 480         return self._fdt_obj
 481
 482     def GetProps(self, node):
 483         """Get all properties from a node.
 484
 485         Args:
 486             node: Full path to node name to look in.
 487
 488         Returns:
 489             A dictionary containing all the properties, indexed by node name.
 490             The entries are Prop objects.
 491
 492         Raises:
 493             ValueError: if the node does not exist.
 494         """
 495         props_dict = {}
 496         poffset = self._fdt_obj.first_property_offset(node._offset,
 497                                                       QUIET_NOTFOUND)
 498         while poffset >= 0:
 499             p = self._fdt_obj.get_property_by_offset(poffset)
 500             prop = Prop(node, poffset, p.name, p)
 501             props_dict[prop.name] = prop
 502
 503             poffset = self._fdt_obj.next_property_offset(poffset,
 504                                                          QUIET_NOTFOUND)
 505         return props_dict
 506
 507     def Invalidate(self):
 508         """Mark our offset cache as invalid"""
 509         self._cached_offsets = False
 510
 511     def CheckCache(self):
 512         """Refresh the offset cache if needed"""
 513         if self._cached_offsets:
 514             return
 515         self.Refresh()
 516         self._cached_offsets = True
 517
 518     def Refresh(self):
 519         """Refresh the offset cache"""
 520         self._root.Refresh(0)
 521
 522     def GetStructOffset(self, offset):
 523         """Get the file offset of a given struct offset
 524
 525         Args:
 526             offset: Offset within the 'struct' region of the device tree
 527         Returns:
 528             Position of @offset within the device tree binary
 529         """
 530         return self._fdt_obj.off_dt_struct() + offset
 531
 532     @classmethod
 533     def Node(self, fdt, parent, offset, name, path):
 534         """Create a new node
 535
 536         This is used by Fdt.Scan() to create a new node using the correct
 537         class.
 538
 539         Args:
 540             fdt: Fdt object
 541             parent: Parent node, or None if this is the root node
 542             offset: Offset of node
 543             name: Node name
 544             path: Full path to node
 545         """
 546         node = Node(fdt, parent, offset, name, path)
 547         return node
 548
 549 def FdtScan(fname):
 550     """Returns a new Fdt object"""
 551     dtb = Fdt(fname)
 552     dtb.Scan()
 553     return dtb