fdt.py 22 KB

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