tools/binman/entry.py

   1 # SPDX-License-Identifier: GPL-2.0+
   2 # Copyright (c) 2016 Google, Inc
   3 #
   4 # Base class for all entries
   5 #
   6
   7 from collections import namedtuple
   8 import importlib
   9 import os
  10 import sys
  11
  12 from dtoc import fdt_util
  13 from patman import tools
  14 from patman.tools import ToHex, ToHexSize
  15 from patman import tout
  16
  17 modules = {}
  18
  19
  20 # An argument which can be passed to entries on the command line, in lieu of
  21 # device-tree properties.
  22 EntryArg = namedtuple('EntryArg', ['name', 'datatype'])
  23
  24 # Information about an entry for use when displaying summaries
  25 EntryInfo = namedtuple('EntryInfo', ['indent', 'name', 'etype', 'size',
  26                                      'image_pos', 'uncomp_size', 'offset',
  27                                      'entry'])
  28
  29 class Entry(object):
  30     """An Entry in the section
  31
  32     An entry corresponds to a single node in the device-tree description
  33     of the section. Each entry ends up being a part of the final section.
  34     Entries can be placed either right next to each other, or with padding
  35     between them. The type of the entry determines the data that is in it.
  36
  37     This class is not used by itself. All entry objects are subclasses of
  38     Entry.
  39
  40     Attributes:
  41         section: Section object containing this entry
  42         node: The node that created this entry
  43         offset: Offset of entry within the section, None if not known yet (in
  44             which case it will be calculated by Pack())
  45         size: Entry size in bytes, None if not known
  46         pre_reset_size: size as it was before ResetForPack(). This allows us to
  47             keep track of the size we started with and detect size changes
  48         uncomp_size: Size of uncompressed data in bytes, if the entry is
  49             compressed, else None
  50         contents_size: Size of contents in bytes, 0 by default
  51         align: Entry start offset alignment relative to the start of the
  52             containing section, or None
  53         align_size: Entry size alignment, or None
  54         align_end: Entry end offset alignment relative to the start of the
  55             containing section, or None
  56         pad_before: Number of pad bytes before the contents when it is placed
  57             in the containing section, 0 if none. The pad bytes become part of
  58             the entry.
  59         pad_after: Number of pad bytes after the contents when it is placed in
  60             the containing section, 0 if none. The pad bytes become part of
  61             the entry.
  62         data: Contents of entry (string of bytes). This does not include
  63             padding created by pad_before or pad_after. If the entry is
  64             compressed, this contains the compressed data.
  65         uncomp_data: Original uncompressed data, if this entry is compressed,
  66             else None
  67         compress: Compression algoithm used (e.g. 'lz4'), 'none' if none
  68         orig_offset: Original offset value read from node
  69         orig_size: Original size value read from node
  70         missing: True if this entry is missing its contents
  71         allow_missing: Allow children of this entry to be missing (used by
  72             subclasses such as Entry_section)
  73         external: True if this entry contains an external binary blob
  74     """
  75     def __init__(self, section, etype, node, name_prefix=''):
  76         # Put this here to allow entry-docs and help to work without libfdt
  77         global state
  78         from binman import state
  79
  80         self.section = section
  81         self.etype = etype
  82         self._node = node
  83         self.name = node and (name_prefix + node.name) or 'none'
  84         self.offset = None
  85         self.size = None
  86         self.pre_reset_size = None
  87         self.uncomp_size = None
  88         self.data = None
  89         self.uncomp_data = None
  90         self.contents_size = 0
  91         self.align = None
  92         self.align_size = None
  93         self.align_end = None
  94         self.pad_before = 0
  95         self.pad_after = 0
  96         self.offset_unset = False
  97         self.image_pos = None
  98         self._expand_size = False
  99         self.compress = 'none'
 100         self.missing = False
 101         self.external = False
 102         self.allow_missing = False
 103
 104     @staticmethod
 105     def Lookup(node_path, etype, expanded):
 106         """Look up the entry class for a node.
 107
 108         Args:
 109             node_node: Path name of Node object containing information about
 110                        the entry to create (used for errors)
 111             etype:   Entry type to use
 112             expanded: Use the expanded version of etype
 113
 114         Returns:
 115             The entry class object if found, else None if not found and expanded
 116                 is True
 117
 118         Raise:
 119             ValueError if expanded is False and the class is not found
 120         """
 121         # Convert something like 'u-boot@0' to 'u_boot' since we are only
 122         # interested in the type.
 123         module_name = etype.replace('-', '_')
 124
 125         if '@' in module_name:
 126             module_name = module_name.split('@')[0]
 127         if expanded:
 128             module_name += '_expanded'
 129         module = modules.get(module_name)
 130
 131         # Also allow entry-type modules to be brought in from the etype directory.
 132
 133         # Import the module if we have not already done so.
 134         if not module:
 135             try:
 136                 module = importlib.import_module('binman.etype.' + module_name)
 137             except ImportError as e:
 138                 if expanded:
 139                     return None
 140                 raise ValueError("Unknown entry type '%s' in node '%s' (expected etype/%s.py, error '%s'" %
 141                                  (etype, node_path, module_name, e))
 142             modules[module_name] = module
 143
 144         # Look up the expected class name
 145         return getattr(module, 'Entry_%s' % module_name)
 146
 147     @staticmethod
 148     def Create(section, node, etype=None, expanded=False):
 149         """Create a new entry for a node.
 150
 151         Args:
 152             section:  Section object containing this node
 153             node:     Node object containing information about the entry to
 154                       create
 155             etype:    Entry type to use, or None to work it out (used for tests)
 156             expanded: True to use expanded versions of entries, where available
 157
 158         Returns:
 159             A new Entry object of the correct type (a subclass of Entry)
 160         """
 161         if not etype:
 162             etype = fdt_util.GetString(node, 'type', node.name)
 163         obj = Entry.Lookup(node.path, etype, expanded)
 164         if obj and expanded:
 165             # Check whether to use the expanded entry
 166             new_etype = etype + '-expanded'
 167             can_expand = not fdt_util.GetBool(node, 'no-expanded')
 168             if can_expand and obj.UseExpanded(node, etype, new_etype):
 169                 etype = new_etype
 170             else:
 171                 obj = None
 172         if not obj:
 173             obj = Entry.Lookup(node.path, etype, False)
 174
 175         # Call its constructor to get the object we want.
 176         return obj(section, etype, node)
 177
 178     def ReadNode(self):
 179         """Read entry information from the node
 180
 181         This must be called as the first thing after the Entry is created.
 182
 183         This reads all the fields we recognise from the node, ready for use.
 184         """
 185         if 'pos' in self._node.props:
 186             self.Raise("Please use 'offset' instead of 'pos'")
 187         self.offset = fdt_util.GetInt(self._node, 'offset')
 188         self.size = fdt_util.GetInt(self._node, 'size')
 189         self.orig_offset = fdt_util.GetInt(self._node, 'orig-offset')
 190         self.orig_size = fdt_util.GetInt(self._node, 'orig-size')
 191         if self.GetImage().copy_to_orig:
 192             self.orig_offset = self.offset
 193             self.orig_size = self.size
 194
 195         # These should not be set in input files, but are set in an FDT map,
 196         # which is also read by this code.
 197         self.image_pos = fdt_util.GetInt(self._node, 'image-pos')
 198         self.uncomp_size = fdt_util.GetInt(self._node, 'uncomp-size')
 199
 200         self.align = fdt_util.GetInt(self._node, 'align')
 201         if tools.NotPowerOfTwo(self.align):
 202             raise ValueError("Node '%s': Alignment %s must be a power of two" %
 203                              (self._node.path, self.align))
 204         self.pad_before = fdt_util.GetInt(self._node, 'pad-before', 0)
 205         self.pad_after = fdt_util.GetInt(self._node, 'pad-after', 0)
 206         self.align_size = fdt_util.GetInt(self._node, 'align-size')
 207         if tools.NotPowerOfTwo(self.align_size):
 208             self.Raise("Alignment size %s must be a power of two" %
 209                        self.align_size)
 210         self.align_end = fdt_util.GetInt(self._node, 'align-end')
 211         self.offset_unset = fdt_util.GetBool(self._node, 'offset-unset')
 212         self.expand_size = fdt_util.GetBool(self._node, 'expand-size')
 213         self.missing_msg = fdt_util.GetString(self._node, 'missing-msg')
 214
 215         # This is only supported by blobs and sections at present
 216         self.compress = fdt_util.GetString(self._node, 'compress', 'none')
 217
 218     def GetDefaultFilename(self):
 219         return None
 220
 221     def GetFdts(self):
 222         """Get the device trees used by this entry
 223
 224         Returns:
 225             Empty dict, if this entry is not a .dtb, otherwise:
 226             Dict:
 227                 key: Filename from this entry (without the path)
 228                 value: Tuple:
 229                     Entry object for this dtb
 230                     Filename of file containing this dtb
 231         """
 232         return {}
 233
 234     def ExpandEntries(self):
 235         """Expand out entries which produce other entries
 236
 237         Some entries generate subnodes automatically, from which sub-entries
 238         are then created. This method allows those to be added to the binman
 239         definition for the current image. An entry which implements this method
 240         should call state.AddSubnode() to add a subnode and can add properties
 241         with state.AddString(), etc.
 242
 243         An example is 'files', which produces a section containing a list of
 244         files.
 245         """
 246         pass
 247
 248     def AddMissingProperties(self, have_image_pos):
 249         """Add new properties to the device tree as needed for this entry
 250
 251         Args:
 252             have_image_pos: True if this entry has an image position. This can
 253                 be False if its parent section is compressed, since compression
 254                 groups all entries together into a compressed block of data,
 255                 obscuring the start of each individual child entry
 256         """
 257         for prop in ['offset', 'size']:
 258             if not prop in self._node.props:
 259                 state.AddZeroProp(self._node, prop)
 260         if have_image_pos and 'image-pos' not in self._node.props:
 261             state.AddZeroProp(self._node, 'image-pos')
 262         if self.GetImage().allow_repack:
 263             if self.orig_offset is not None:
 264                 state.AddZeroProp(self._node, 'orig-offset', True)
 265             if self.orig_size is not None:
 266                 state.AddZeroProp(self._node, 'orig-size', True)
 267
 268         if self.compress != 'none':
 269             state.AddZeroProp(self._node, 'uncomp-size')
 270         err = state.CheckAddHashProp(self._node)
 271         if err:
 272             self.Raise(err)
 273
 274     def SetCalculatedProperties(self):
 275         """Set the value of device-tree properties calculated by binman"""
 276         state.SetInt(self._node, 'offset', self.offset)
 277         state.SetInt(self._node, 'size', self.size)
 278         base = self.section.GetRootSkipAtStart() if self.section else 0
 279         if self.image_pos is not None:
 280             state.SetInt(self._node, 'image-pos', self.image_pos - base)
 281         if self.GetImage().allow_repack:
 282             if self.orig_offset is not None:
 283                 state.SetInt(self._node, 'orig-offset', self.orig_offset, True)
 284             if self.orig_size is not None:
 285                 state.SetInt(self._node, 'orig-size', self.orig_size, True)
 286         if self.uncomp_size is not None:
 287             state.SetInt(self._node, 'uncomp-size', self.uncomp_size)
 288         state.CheckSetHashValue(self._node, self.GetData)
 289
 290     def ProcessFdt(self, fdt):
 291         """Allow entries to adjust the device tree
 292
 293         Some entries need to adjust the device tree for their purposes. This
 294         may involve adding or deleting properties.
 295
 296         Returns:
 297             True if processing is complete
 298             False if processing could not be completed due to a dependency.
 299                 This will cause the entry to be retried after others have been
 300                 called
 301         """
 302         return True
 303
 304     def SetPrefix(self, prefix):
 305         """Set the name prefix for a node
 306
 307         Args:
 308             prefix: Prefix to set, or '' to not use a prefix
 309         """
 310         if prefix:
 311             self.name = prefix + self.name
 312
 313     def SetContents(self, data):
 314         """Set the contents of an entry
 315
 316         This sets both the data and content_size properties
 317
 318         Args:
 319             data: Data to set to the contents (bytes)
 320         """
 321         self.data = data
 322         self.contents_size = len(self.data)
 323
 324     def ProcessContentsUpdate(self, data):
 325         """Update the contents of an entry, after the size is fixed
 326
 327         This checks that the new data is the same size as the old. If the size
 328         has changed, this triggers a re-run of the packing algorithm.
 329
 330         Args:
 331             data: Data to set to the contents (bytes)
 332
 333         Raises:
 334             ValueError if the new data size is not the same as the old
 335         """
 336         size_ok = True
 337         new_size = len(data)
 338         if state.AllowEntryExpansion() and new_size > self.contents_size:
 339             # self.data will indicate the new size needed
 340             size_ok = False
 341         elif state.AllowEntryContraction() and new_size < self.contents_size:
 342             size_ok = False
 343
 344         # If not allowed to change, try to deal with it or give up
 345         if size_ok:
 346             if new_size > self.contents_size:
 347                 self.Raise('Cannot update entry size from %d to %d' %
 348                         (self.contents_size, new_size))
 349
 350             # Don't let the data shrink. Pad it if necessary
 351             if size_ok and new_size < self.contents_size:
 352                 data += tools.GetBytes(0, self.contents_size - new_size)
 353
 354         if not size_ok:
 355             tout.Debug("Entry '%s' size change from %s to %s" % (
 356                 self._node.path, ToHex(self.contents_size),
 357                 ToHex(new_size)))
 358         self.SetContents(data)
 359         return size_ok
 360
 361     def ObtainContents(self):
 362         """Figure out the contents of an entry.
 363
 364         Returns:
 365             True if the contents were found, False if another call is needed
 366             after the other entries are processed.
 367         """
 368         # No contents by default: subclasses can implement this
 369         return True
 370
 371     def ResetForPack(self):
 372         """Reset offset/size fields so that packing can be done again"""
 373         self.Detail('ResetForPack: offset %s->%s, size %s->%s' %
 374                     (ToHex(self.offset), ToHex(self.orig_offset),
 375                      ToHex(self.size), ToHex(self.orig_size)))
 376         self.pre_reset_size = self.size
 377         self.offset = self.orig_offset
 378         self.size = self.orig_size
 379
 380     def Pack(self, offset):
 381         """Figure out how to pack the entry into the section
 382
 383         Most of the time the entries are not fully specified. There may be
 384         an alignment but no size. In that case we take the size from the
 385         contents of the entry.
 386
 387         If an entry has no hard-coded offset, it will be placed at @offset.
 388
 389         Once this function is complete, both the offset and size of the
 390         entry will be know.
 391
 392         Args:
 393             Current section offset pointer
 394
 395         Returns:
 396             New section offset pointer (after this entry)
 397         """
 398         self.Detail('Packing: offset=%s, size=%s, content_size=%x' %
 399                     (ToHex(self.offset), ToHex(self.size),
 400                      self.contents_size))
 401         if self.offset is None:
 402             if self.offset_unset:
 403                 self.Raise('No offset set with offset-unset: should another '
 404                            'entry provide this correct offset?')
 405             self.offset = tools.Align(offset, self.align)
 406         needed = self.pad_before + self.contents_size + self.pad_after
 407         needed = tools.Align(needed, self.align_size)
 408         size = self.size
 409         if not size:
 410             size = needed
 411         new_offset = self.offset + size
 412         aligned_offset = tools.Align(new_offset, self.align_end)
 413         if aligned_offset != new_offset:
 414             size = aligned_offset - self.offset
 415             new_offset = aligned_offset
 416
 417         if not self.size:
 418             self.size = size
 419
 420         if self.size < needed:
 421             self.Raise("Entry contents size is %#x (%d) but entry size is "
 422                        "%#x (%d)" % (needed, needed, self.size, self.size))
 423         # Check that the alignment is correct. It could be wrong if the
 424         # and offset or size values were provided (i.e. not calculated), but
 425         # conflict with the provided alignment values
 426         if self.size != tools.Align(self.size, self.align_size):
 427             self.Raise("Size %#x (%d) does not match align-size %#x (%d)" %
 428                   (self.size, self.size, self.align_size, self.align_size))
 429         if self.offset != tools.Align(self.offset, self.align):
 430             self.Raise("Offset %#x (%d) does not match align %#x (%d)" %
 431                   (self.offset, self.offset, self.align, self.align))
 432         self.Detail('   - packed: offset=%#x, size=%#x, content_size=%#x, next_offset=%x' %
 433                     (self.offset, self.size, self.contents_size, new_offset))
 434
 435         return new_offset
 436
 437     def Raise(self, msg):
 438         """Convenience function to raise an error referencing a node"""
 439         raise ValueError("Node '%s': %s" % (self._node.path, msg))
 440
 441     def Info(self, msg):
 442         """Convenience function to log info referencing a node"""
 443         tag = "Info '%s'" % self._node.path
 444         tout.Detail('%30s: %s' % (tag, msg))
 445
 446     def Detail(self, msg):
 447         """Convenience function to log detail referencing a node"""
 448         tag = "Node '%s'" % self._node.path
 449         tout.Detail('%30s: %s' % (tag, msg))
 450
 451     def GetEntryArgsOrProps(self, props, required=False):
 452         """Return the values of a set of properties
 453
 454         Args:
 455             props: List of EntryArg objects
 456
 457         Raises:
 458             ValueError if a property is not found
 459         """
 460         values = []
 461         missing = []
 462         for prop in props:
 463             python_prop = prop.name.replace('-', '_')
 464             if hasattr(self, python_prop):
 465                 value = getattr(self, python_prop)
 466             else:
 467                 value = None
 468             if value is None:
 469                 value = self.GetArg(prop.name, prop.datatype)
 470             if value is None and required:
 471                 missing.append(prop.name)
 472             values.append(value)
 473         if missing:
 474             self.GetImage().MissingArgs(self, missing)
 475         return values
 476
 477     def GetPath(self):
 478         """Get the path of a node
 479
 480         Returns:
 481             Full path of the node for this entry
 482         """
 483         return self._node.path
 484
 485     def GetData(self, required=True):
 486         """Get the contents of an entry
 487
 488         Args:
 489             required: True if the data must be present, False if it is OK to
 490                 return None
 491
 492         Returns:
 493             bytes content of the entry, excluding any padding. If the entry is
 494                 compressed, the compressed data is returned
 495         """
 496         self.Detail('GetData: size %s' % ToHexSize(self.data))
 497         return self.data
 498
 499     def GetPaddedData(self, data=None):
 500         """Get the data for an entry including any padding
 501
 502         Gets the entry data and uses its section's pad-byte value to add padding
 503         before and after as defined by the pad-before and pad-after properties.
 504
 505         This does not consider alignment.
 506
 507         Returns:
 508             Contents of the entry along with any pad bytes before and
 509             after it (bytes)
 510         """
 511         if data is None:
 512             data = self.GetData()
 513         return self.section.GetPaddedDataForEntry(self, data)
 514
 515     def GetOffsets(self):
 516         """Get the offsets for siblings
 517
 518         Some entry types can contain information about the position or size of
 519         other entries. An example of this is the Intel Flash Descriptor, which
 520         knows where the Intel Management Engine section should go.
 521
 522         If this entry knows about the position of other entries, it can specify
 523         this by returning values here
 524
 525         Returns:
 526             Dict:
 527                 key: Entry type
 528                 value: List containing position and size of the given entry
 529                     type. Either can be None if not known
 530         """
 531         return {}
 532
 533     def SetOffsetSize(self, offset, size):
 534         """Set the offset and/or size of an entry
 535
 536         Args:
 537             offset: New offset, or None to leave alone
 538             size: New size, or None to leave alone
 539         """
 540         if offset is not None:
 541             self.offset = offset
 542         if size is not None:
 543             self.size = size
 544
 545     def SetImagePos(self, image_pos):
 546         """Set the position in the image
 547
 548         Args:
 549             image_pos: Position of this entry in the image
 550         """
 551         self.image_pos = image_pos + self.offset
 552
 553     def ProcessContents(self):
 554         """Do any post-packing updates of entry contents
 555
 556         This function should call ProcessContentsUpdate() to update the entry
 557         contents, if necessary, returning its return value here.
 558
 559         Args:
 560             data: Data to set to the contents (bytes)
 561
 562         Returns:
 563             True if the new data size is OK, False if expansion is needed
 564
 565         Raises:
 566             ValueError if the new data size is not the same as the old and
 567                 state.AllowEntryExpansion() is False
 568         """
 569         return True
 570
 571     def WriteSymbols(self, section):
 572         """Write symbol values into binary files for access at run time
 573
 574         Args:
 575           section: Section containing the entry
 576         """
 577         pass
 578
 579     def CheckEntries(self):
 580         """Check that the entry offsets are correct
 581
 582         This is used for entries which have extra offset requirements (other
 583         than having to be fully inside their section). Sub-classes can implement
 584         this function and raise if there is a problem.
 585         """
 586         pass
 587
 588     @staticmethod
 589     def GetStr(value):
 590         if value is None:
 591             return '<none>  '
 592         return '%08x' % value
 593
 594     @staticmethod
 595     def WriteMapLine(fd, indent, name, offset, size, image_pos):
 596         print('%s  %s%s  %s  %s' % (Entry.GetStr(image_pos), ' ' * indent,
 597                                     Entry.GetStr(offset), Entry.GetStr(size),
 598                                     name), file=fd)
 599
 600     def WriteMap(self, fd, indent):
 601         """Write a map of the entry to a .map file
 602
 603         Args:
 604             fd: File to write the map to
 605             indent: Curent indent level of map (0=none, 1=one level, etc.)
 606         """
 607         self.WriteMapLine(fd, indent, self.name, self.offset, self.size,
 608                           self.image_pos)
 609
 610     def GetEntries(self):
 611         """Return a list of entries contained by this entry
 612
 613         Returns:
 614             List of entries, or None if none. A normal entry has no entries
 615                 within it so will return None
 616         """
 617         return None
 618
 619     def GetArg(self, name, datatype=str):
 620         """Get the value of an entry argument or device-tree-node property
 621
 622         Some node properties can be provided as arguments to binman. First check
 623         the entry arguments, and fall back to the device tree if not found
 624
 625         Args:
 626             name: Argument name
 627             datatype: Data type (str or int)
 628
 629         Returns:
 630             Value of argument as a string or int, or None if no value
 631
 632         Raises:
 633             ValueError if the argument cannot be converted to in
 634         """
 635         value = state.GetEntryArg(name)
 636         if value is not None:
 637             if datatype == int:
 638                 try:
 639                     value = int(value)
 640                 except ValueError:
 641                     self.Raise("Cannot convert entry arg '%s' (value '%s') to integer" %
 642                                (name, value))
 643             elif datatype == str:
 644                 pass
 645             else:
 646                 raise ValueError("GetArg() internal error: Unknown data type '%s'" %
 647                                  datatype)
 648         else:
 649             value = fdt_util.GetDatatype(self._node, name, datatype)
 650         return value
 651
 652     @staticmethod
 653     def WriteDocs(modules, test_missing=None):
 654         """Write out documentation about the various entry types to stdout
 655
 656         Args:
 657             modules: List of modules to include
 658             test_missing: Used for testing. This is a module to report
 659                 as missing
 660         """
 661         print('''Binman Entry Documentation
 662 ===========================
 663
 664 This file describes the entry types supported by binman. These entry types can
 665 be placed in an image one by one to build up a final firmware image. It is
 666 fairly easy to create new entry types. Just add a new file to the 'etype'
 667 directory. You can use the existing entries as examples.
 668
 669 Note that some entries are subclasses of others, using and extending their
 670 features to produce new behaviours.
 671
 672
 673 ''')
 674         modules = sorted(modules)
 675
 676         # Don't show the test entry
 677         if '_testing' in modules:
 678             modules.remove('_testing')
 679         missing = []
 680         for name in modules:
 681             module = Entry.Lookup('WriteDocs', name, False)
 682             docs = getattr(module, '__doc__')
 683             if test_missing == name:
 684                 docs = None
 685             if docs:
 686                 lines = docs.splitlines()
 687                 first_line = lines[0]
 688                 rest = [line[4:] for line in lines[1:]]
 689                 hdr = 'Entry: %s: %s' % (name.replace('_', '-'), first_line)
 690                 print(hdr)
 691                 print('-' * len(hdr))
 692                 print('\n'.join(rest))
 693                 print()
 694                 print()
 695             else:
 696                 missing.append(name)
 697
 698         if missing:
 699             raise ValueError('Documentation is missing for modules: %s' %
 700                              ', '.join(missing))
 701
 702     def GetUniqueName(self):
 703         """Get a unique name for a node
 704
 705         Returns:
 706             String containing a unique name for a node, consisting of the name
 707             of all ancestors (starting from within the 'binman' node) separated
 708             by a dot ('.'). This can be useful for generating unique filesnames
 709             in the output directory.
 710         """
 711         name = self.name
 712         node = self._node
 713         while node.parent:
 714             node = node.parent
 715             if node.name == 'binman':
 716                 break
 717             name = '%s.%s' % (node.name, name)
 718         return name
 719
 720     def ExpandToLimit(self, limit):
 721         """Expand an entry so that it ends at the given offset limit"""
 722         if self.offset + self.size < limit:
 723             self.size = limit - self.offset
 724             # Request the contents again, since changing the size requires that
 725             # the data grows. This should not fail, but check it to be sure.
 726             if not self.ObtainContents():
 727                 self.Raise('Cannot obtain contents when expanding entry')
 728
 729     def HasSibling(self, name):
 730         """Check if there is a sibling of a given name
 731
 732         Returns:
 733             True if there is an entry with this name in the the same section,
 734                 else False
 735         """
 736         return name in self.section.GetEntries()
 737
 738     def GetSiblingImagePos(self, name):
 739         """Return the image position of the given sibling
 740
 741         Returns:
 742             Image position of sibling, or None if the sibling has no position,
 743                 or False if there is no such sibling
 744         """
 745         if not self.HasSibling(name):
 746             return False
 747         return self.section.GetEntries()[name].image_pos
 748
 749     @staticmethod
 750     def AddEntryInfo(entries, indent, name, etype, size, image_pos,
 751                      uncomp_size, offset, entry):
 752         """Add a new entry to the entries list
 753
 754         Args:
 755             entries: List (of EntryInfo objects) to add to
 756             indent: Current indent level to add to list
 757             name: Entry name (string)
 758             etype: Entry type (string)
 759             size: Entry size in bytes (int)
 760             image_pos: Position within image in bytes (int)
 761             uncomp_size: Uncompressed size if the entry uses compression, else
 762                 None
 763             offset: Entry offset within parent in bytes (int)
 764             entry: Entry object
 765         """
 766         entries.append(EntryInfo(indent, name, etype, size, image_pos,
 767                                  uncomp_size, offset, entry))
 768
 769     def ListEntries(self, entries, indent):
 770         """Add files in this entry to the list of entries
 771
 772         This can be overridden by subclasses which need different behaviour.
 773
 774         Args:
 775             entries: List (of EntryInfo objects) to add to
 776             indent: Current indent level to add to list
 777         """
 778         self.AddEntryInfo(entries, indent, self.name, self.etype, self.size,
 779                           self.image_pos, self.uncomp_size, self.offset, self)
 780
 781     def ReadData(self, decomp=True):
 782         """Read the data for an entry from the image
 783
 784         This is used when the image has been read in and we want to extract the
 785         data for a particular entry from that image.
 786
 787         Args:
 788             decomp: True to decompress any compressed data before returning it;
 789                 False to return the raw, uncompressed data
 790
 791         Returns:
 792             Entry data (bytes)
 793         """
 794         # Use True here so that we get an uncompressed section to work from,
 795         # although compressed sections are currently not supported
 796         tout.Debug("ReadChildData section '%s', entry '%s'" %
 797                    (self.section.GetPath(), self.GetPath()))
 798         data = self.section.ReadChildData(self, decomp)
 799         return data
 800
 801     def ReadChildData(self, child, decomp=True):
 802         """Read the data for a particular child entry
 803
 804         This reads data from the parent and extracts the piece that relates to
 805         the given child.
 806
 807         Args:
 808             child: Child entry to read data for (must be valid)
 809             decomp: True to decompress any compressed data before returning it;
 810                 False to return the raw, uncompressed data
 811
 812         Returns:
 813             Data for the child (bytes)
 814         """
 815         pass
 816
 817     def LoadData(self, decomp=True):
 818         data = self.ReadData(decomp)
 819         self.contents_size = len(data)
 820         self.ProcessContentsUpdate(data)
 821         self.Detail('Loaded data size %x' % len(data))
 822
 823     def GetImage(self):
 824         """Get the image containing this entry
 825
 826         Returns:
 827             Image object containing this entry
 828         """
 829         return self.section.GetImage()
 830
 831     def WriteData(self, data, decomp=True):
 832         """Write the data to an entry in the image
 833
 834         This is used when the image has been read in and we want to replace the
 835         data for a particular entry in that image.
 836
 837         The image must be re-packed and written out afterwards.
 838
 839         Args:
 840             data: Data to replace it with
 841             decomp: True to compress the data if needed, False if data is
 842                 already compressed so should be used as is
 843
 844         Returns:
 845             True if the data did not result in a resize of this entry, False if
 846                  the entry must be resized
 847         """
 848         if self.size is not None:
 849             self.contents_size = self.size
 850         else:
 851             self.contents_size = self.pre_reset_size
 852         ok = self.ProcessContentsUpdate(data)
 853         self.Detail('WriteData: size=%x, ok=%s' % (len(data), ok))
 854         section_ok = self.section.WriteChildData(self)
 855         return ok and section_ok
 856
 857     def WriteChildData(self, child):
 858         """Handle writing the data in a child entry
 859
 860         This should be called on the child's parent section after the child's
 861         data has been updated. It
 862
 863         This base-class implementation does nothing, since the base Entry object
 864         does not have any children.
 865
 866         Args:
 867             child: Child Entry that was written
 868
 869         Returns:
 870             True if the section could be updated successfully, False if the
 871                 data is such that the section could not updat
 872         """
 873         return True
 874
 875     def GetSiblingOrder(self):
 876         """Get the relative order of an entry amoung its siblings
 877
 878         Returns:
 879             'start' if this entry is first among siblings, 'end' if last,
 880                 otherwise None
 881         """
 882         entries = list(self.section.GetEntries().values())
 883         if entries:
 884             if self == entries[0]:
 885                 return 'start'
 886             elif self == entries[-1]:
 887                 return 'end'
 888         return 'middle'
 889
 890     def SetAllowMissing(self, allow_missing):
 891         """Set whether a section allows missing external blobs
 892
 893         Args:
 894             allow_missing: True if allowed, False if not allowed
 895         """
 896         # This is meaningless for anything other than sections
 897         pass
 898
 899     def CheckMissing(self, missing_list):
 900         """Check if any entries in this section have missing external blobs
 901
 902         If there are missing blobs, the entries are added to the list
 903
 904         Args:
 905             missing_list: List of Entry objects to be added to
 906         """
 907         if self.missing:
 908             missing_list.append(self)
 909
 910     def GetAllowMissing(self):
 911         """Get whether a section allows missing external blobs
 912
 913         Returns:
 914             True if allowed, False if not allowed
 915         """
 916         return self.allow_missing
 917
 918     def GetHelpTags(self):
 919         """Get the tags use for missing-blob help
 920
 921         Returns:
 922             list of possible tags, most desirable first
 923         """
 924         return list(filter(None, [self.missing_msg, self.name, self.etype]))
 925
 926     def CompressData(self, indata):
 927         """Compress data according to the entry's compression method
 928
 929         Args:
 930             indata: Data to compress
 931
 932         Returns:
 933             Compressed data (first word is the compressed size)
 934         """
 935         self.uncomp_data = indata
 936         if self.compress != 'none':
 937             self.uncomp_size = len(indata)
 938         data = tools.Compress(indata, self.compress)
 939         return data
 940
 941     @classmethod
 942     def UseExpanded(cls, node, etype, new_etype):
 943         """Check whether to use an expanded entry type
 944
 945         This is called by Entry.Create() when it finds an expanded version of
 946         an entry type (e.g. 'u-boot-expanded'). If this method returns True then
 947         it will be used (e.g. in place of 'u-boot'). If it returns False, it is
 948         ignored.
 949
 950         Args:
 951             node:     Node object containing information about the entry to
 952                       create
 953             etype:    Original entry type being used
 954             new_etype: New entry type proposed
 955
 956         Returns:
 957             True to use this entry type, False to use the original one
 958         """
 959         tout.Info("Node '%s': etype '%s': %s selected" %
 960                   (node.path, etype, new_etype))
 961         return True