fdt.py 22 KB

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