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