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 import fdt_util
  13 import tools
  14 from tools import ToHex, ToHexSize
  15 import tout
  16
  17 modules = {}
  18
  19 our_path = os.path.dirname(os.path.realpath(__file__))
  20
  21
  22 # An argument which can be passed to entries on the command line, in lieu of
  23 # device-tree properties.
  24 EntryArg = namedtuple('EntryArg', ['name', 'datatype'])
  25
  26 # Information about an entry for use when displaying summaries
  27 EntryInfo = namedtuple('EntryInfo', ['indent', 'name', 'etype', 'size',
  28                                      'image_pos', 'uncomp_size', 'offset',
  29                                      'entry'])
  30
  31 class Entry(object):
  32     """An Entry in the section
  33
  34     An entry corresponds to a single node in the device-tree description
  35     of the section. Each entry ends up being a part of the final section.
  36     Entries can be placed either right next to each other, or with padding
  37     between them. The type of the entry determines the data that is in it.
  38
  39     This class is not used by itself. All entry objects are subclasses of
  40     Entry.
  41
  42     Attributes:
  43         section: Section object containing this entry
  44         node: The node that created this entry
  45         offset: Offset of entry within the section, None if not known yet (in
  46             which case it will be calculated by Pack())
  47         size: Entry size in bytes, None if not known
  48         pre_reset_size: size as it was before ResetForPack(). This allows us to
  49             keep track of the size we started with and detect size changes
  50         uncomp_size: Size of uncompressed data in bytes, if the entry is
  51             compressed, else None
  52         contents_size: Size of contents in bytes, 0 by default
  53         align: Entry start offset alignment, or None
  54         align_size: Entry size alignment, or None
  55         align_end: Entry end offset alignment, or None
  56         pad_before: Number of pad bytes before the contents, 0 if none
  57         pad_after: Number of pad bytes after the contents, 0 if none
  58         data: Contents of entry (string of bytes)
  59         compress: Compression algoithm used (e.g. 'lz4'), 'none' if none
  60         orig_offset: Original offset value read from node
  61         orig_size: Original size value read from node
  62     """
  63     def __init__(self, section, etype, node, name_prefix=''):
  64         # Put this here to allow entry-docs and help to work without libfdt
  65         global state
  66         import state
  67
  68         self.section = section
  69         self.etype = etype
  70         self._node = node
  71         self.name = node and (name_prefix + node.name) or 'none'
  72         self.offset = None
  73         self.size = None
  74         self.pre_reset_size = None
  75         self.uncomp_size = None
  76         self.data = None
  77         self.contents_size = 0
  78         self.align = None
  79         self.align_size = None
  80         self.align_end = None
  81         self.pad_before = 0
  82         self.pad_after = 0
  83         self.offset_unset = False
  84         self.image_pos = None
  85         self._expand_size = False
  86         self.compress = 'none'
  87
  88     @staticmethod
  89     def Lookup(node_path, etype):
  90         """Look up the entry class for a node.
  91
  92         Args:
  93             node_node: Path name of Node object containing information about
  94                        the entry to create (used for errors)
  95             etype:   Entry type to use
  96
  97         Returns:
  98             The entry class object if found, else None
  99         """
 100         # Convert something like 'u-boot@0' to 'u_boot' since we are only
 101         # interested in the type.
 102         module_name = etype.replace('-', '_')
 103         if '@' in module_name:
 104             module_name = module_name.split('@')[0]
 105         module = modules.get(module_name)
 106
 107         # Also allow entry-type modules to be brought in from the etype directory.
 108
 109         # Import the module if we have not already done so.
 110         if not module:
 111             old_path = sys.path
 112             sys.path.insert(0, os.path.join(our_path, 'etype'))
 113             try:
 114                 module = importlib.import_module(module_name)
 115             except ImportError as e:
 116                 raise ValueError("Unknown entry type '%s' in node '%s' (expected etype/%s.py, error '%s'" %
 117                                  (etype, node_path, module_name, e))
 118             finally:
 119                 sys.path = old_path
 120             modules[module_name] = module
 121
 122         # Look up the expected class name
 123         return getattr(module, 'Entry_%s' % module_name)
 124
 125     @staticmethod
 126     def Create(section, node, etype=None):
 127         """Create a new entry for a node.
 128
 129         Args:
 130             section: Section object containing this node
 131             node:    Node object containing information about the entry to
 132                      create
 133             etype:   Entry type to use, or None to work it out (used for tests)
 134
 135         Returns:
 136             A new Entry object of the correct type (a subclass of Entry)
 137         """
 138         if not etype:
 139             etype = fdt_util.GetString(node, 'type', node.name)
 140         obj = Entry.Lookup(node.path, etype)
 141
 142         # Call its constructor to get the object we want.
 143         return obj(section, etype, node)
 144
 145     def ReadNode(self):
 146         """Read entry information from the node
 147
 148         This must be called as the first thing after the Entry is created.
 149
 150         This reads all the fields we recognise from the node, ready for use.
 151         """
 152         if 'pos' in self._node.props:
 153             self.Raise("Please use 'offset' instead of 'pos'")
 154         self.offset = fdt_util.GetInt(self._node, 'offset')
 155         self.size = fdt_util.GetInt(self._node, 'size')
 156         self.orig_offset = fdt_util.GetInt(self._node, 'orig-offset')
 157         self.orig_size = fdt_util.GetInt(self._node, 'orig-size')
 158         if self.GetImage().copy_to_orig:
 159             self.orig_offset = self.offset
 160             self.orig_size = self.size
 161
 162         # These should not be set in input files, but are set in an FDT map,
 163         # which is also read by this code.
 164         self.image_pos = fdt_util.GetInt(self._node, 'image-pos')
 165         self.uncomp_size = fdt_util.GetInt(self._node, 'uncomp-size')
 166
 167         self.align = fdt_util.GetInt(self._node, 'align')
 168         if tools.NotPowerOfTwo(self.align):
 169             raise ValueError("Node '%s': Alignment %s must be a power of two" %
 170                              (self._node.path, self.align))
 171         self.pad_before = fdt_util.GetInt(self._node, 'pad-before', 0)
 172         self.pad_after = fdt_util.GetInt(self._node, 'pad-after', 0)
 173         self.align_size = fdt_util.GetInt(self._node, 'align-size')
 174         if tools.NotPowerOfTwo(self.align_size):
 175             self.Raise("Alignment size %s must be a power of two" %
 176                        self.align_size)
 177         self.align_end = fdt_util.GetInt(self._node, 'align-end')
 178         self.offset_unset = fdt_util.GetBool(self._node, 'offset-unset')
 179         self.expand_size = fdt_util.GetBool(self._node, 'expand-size')
 180
 181     def GetDefaultFilename(self):
 182         return None
 183
 184     def GetFdts(self):
 185         """Get the device trees used by this entry
 186
 187         Returns:
 188             Empty dict, if this entry is not a .dtb, otherwise:
 189             Dict:
 190                 key: Filename from this entry (without the path)
 191                 value: Tuple:
 192                     Fdt object for this dtb, or None if not available
 193                     Filename of file containing this dtb
 194         """
 195         return {}
 196
 197     def ExpandEntries(self):
 198         pass
 199
 200     def AddMissingProperties(self):
 201         """Add new properties to the device tree as needed for this entry"""
 202         for prop in ['offset', 'size', 'image-pos']:
 203             if not prop in self._node.props:
 204                 state.AddZeroProp(self._node, prop)
 205         if self.GetImage().allow_repack:
 206             if self.orig_offset is not None:
 207                 state.AddZeroProp(self._node, 'orig-offset', True)
 208             if self.orig_size is not None:
 209                 state.AddZeroProp(self._node, 'orig-size', True)
 210
 211         if self.compress != 'none':
 212             state.AddZeroProp(self._node, 'uncomp-size')
 213         err = state.CheckAddHashProp(self._node)
 214         if err:
 215             self.Raise(err)
 216
 217     def SetCalculatedProperties(self):
 218         """Set the value of device-tree properties calculated by binman"""
 219         state.SetInt(self._node, 'offset', self.offset)
 220         state.SetInt(self._node, 'size', self.size)
 221         base = self.section.GetRootSkipAtStart() if self.section else 0
 222         state.SetInt(self._node, 'image-pos', self.image_pos - base)
 223         if self.GetImage().allow_repack:
 224             if self.orig_offset is not None:
 225                 state.SetInt(self._node, 'orig-offset', self.orig_offset, True)
 226             if self.orig_size is not None:
 227                 state.SetInt(self._node, 'orig-size', self.orig_size, True)
 228         if self.uncomp_size is not None:
 229             state.SetInt(self._node, 'uncomp-size', self.uncomp_size)
 230         state.CheckSetHashValue(self._node, self.GetData)
 231
 232     def ProcessFdt(self, fdt):
 233         """Allow entries to adjust the device tree
 234
 235         Some entries need to adjust the device tree for their purposes. This
 236         may involve adding or deleting properties.
 237
 238         Returns:
 239             True if processing is complete
 240             False if processing could not be completed due to a dependency.
 241                 This will cause the entry to be retried after others have been
 242                 called
 243         """
 244         return True
 245
 246     def SetPrefix(self, prefix):
 247         """Set the name prefix for a node
 248
 249         Args:
 250             prefix: Prefix to set, or '' to not use a prefix
 251         """
 252         if prefix:
 253             self.name = prefix + self.name
 254
 255     def SetContents(self, data):
 256         """Set the contents of an entry
 257
 258         This sets both the data and content_size properties
 259
 260         Args:
 261             data: Data to set to the contents (bytes)
 262         """
 263         self.data = data
 264         self.contents_size = len(self.data)
 265
 266     def ProcessContentsUpdate(self, data):
 267         """Update the contents of an entry, after the size is fixed
 268
 269         This checks that the new data is the same size as the old. If the size
 270         has changed, this triggers a re-run of the packing algorithm.
 271
 272         Args:
 273             data: Data to set to the contents (bytes)
 274
 275         Raises:
 276             ValueError if the new data size is not the same as the old
 277         """
 278         size_ok = True
 279         new_size = len(data)
 280         if state.AllowEntryExpansion() and new_size > self.contents_size:
 281             # self.data will indicate the new size needed
 282             size_ok = False
 283         elif state.AllowEntryContraction() and new_size < self.contents_size:
 284             size_ok = False
 285
 286         # If not allowed to change, try to deal with it or give up
 287         if size_ok:
 288             if new_size > self.contents_size:
 289                 self.Raise('Cannot update entry size from %d to %d' %
 290                         (self.contents_size, new_size))
 291
 292             # Don't let the data shrink. Pad it if necessary
 293             if size_ok and new_size < self.contents_size:
 294                 data += tools.GetBytes(0, self.contents_size - new_size)
 295
 296         if not size_ok:
 297             tout.Debug("Entry '%s' size change from %s to %s" % (
 298                 self._node.path, ToHex(self.contents_size),
 299                 ToHex(new_size)))
 300         self.SetContents(data)
 301         return size_ok
 302
 303     def ObtainContents(self):
 304         """Figure out the contents of an entry.
 305
 306         Returns:
 307             True if the contents were found, False if another call is needed
 308             after the other entries are processed.
 309         """
 310         # No contents by default: subclasses can implement this
 311         return True
 312
 313     def ResetForPack(self):
 314         """Reset offset/size fields so that packing can be done again"""
 315         self.Detail('ResetForPack: offset %s->%s, size %s->%s' %
 316                     (ToHex(self.offset), ToHex(self.orig_offset),
 317                      ToHex(self.size), ToHex(self.orig_size)))
 318         self.pre_reset_size = self.size
 319         self.offset = self.orig_offset
 320         self.size = self.orig_size
 321
 322     def Pack(self, offset):
 323         """Figure out how to pack the entry into the section
 324
 325         Most of the time the entries are not fully specified. There may be
 326         an alignment but no size. In that case we take the size from the
 327         contents of the entry.
 328
 329         If an entry has no hard-coded offset, it will be placed at @offset.
 330
 331         Once this function is complete, both the offset and size of the
 332         entry will be know.
 333
 334         Args:
 335             Current section offset pointer
 336
 337         Returns:
 338             New section offset pointer (after this entry)
 339         """
 340         self.Detail('Packing: offset=%s, size=%s, content_size=%x' %
 341                     (ToHex(self.offset), ToHex(self.size),
 342                      self.contents_size))
 343         if self.offset is None:
 344             if self.offset_unset:
 345                 self.Raise('No offset set with offset-unset: should another '
 346                            'entry provide this correct offset?')
 347             self.offset = tools.Align(offset, self.align)
 348         needed = self.pad_before + self.contents_size + self.pad_after
 349         needed = tools.Align(needed, self.align_size)
 350         size = self.size
 351         if not size:
 352             size = needed
 353         new_offset = self.offset + size
 354         aligned_offset = tools.Align(new_offset, self.align_end)
 355         if aligned_offset != new_offset:
 356             size = aligned_offset - self.offset
 357             new_offset = aligned_offset
 358
 359         if not self.size:
 360             self.size = size
 361
 362         if self.size < needed:
 363             self.Raise("Entry contents size is %#x (%d) but entry size is "
 364                        "%#x (%d)" % (needed, needed, self.size, self.size))
 365         # Check that the alignment is correct. It could be wrong if the
 366         # and offset or size values were provided (i.e. not calculated), but
 367         # conflict with the provided alignment values
 368         if self.size != tools.Align(self.size, self.align_size):
 369             self.Raise("Size %#x (%d) does not match align-size %#x (%d)" %
 370                   (self.size, self.size, self.align_size, self.align_size))
 371         if self.offset != tools.Align(self.offset, self.align):
 372             self.Raise("Offset %#x (%d) does not match align %#x (%d)" %
 373                   (self.offset, self.offset, self.align, self.align))
 374         self.Detail('   - packed: offset=%#x, size=%#x, content_size=%#x, next_offset=%x' %
 375                     (self.offset, self.size, self.contents_size, new_offset))
 376
 377         return new_offset
 378
 379     def Raise(self, msg):
 380         """Convenience function to raise an error referencing a node"""
 381         raise ValueError("Node '%s': %s" % (self._node.path, msg))
 382
 383     def Detail(self, msg):
 384         """Convenience function to log detail referencing a node"""
 385         tag = "Node '%s'" % self._node.path
 386         tout.Detail('%30s: %s' % (tag, msg))
 387
 388     def GetEntryArgsOrProps(self, props, required=False):
 389         """Return the values of a set of properties
 390
 391         Args:
 392             props: List of EntryArg objects
 393
 394         Raises:
 395             ValueError if a property is not found
 396         """
 397         values = []
 398         missing = []
 399         for prop in props:
 400             python_prop = prop.name.replace('-', '_')
 401             if hasattr(self, python_prop):
 402                 value = getattr(self, python_prop)
 403             else:
 404                 value = None
 405             if value is None:
 406                 value = self.GetArg(prop.name, prop.datatype)
 407             if value is None and required:
 408                 missing.append(prop.name)
 409             values.append(value)
 410         if missing:
 411             self.Raise('Missing required properties/entry args: %s' %
 412                        (', '.join(missing)))
 413         return values
 414
 415     def GetPath(self):
 416         """Get the path of a node
 417
 418         Returns:
 419             Full path of the node for this entry
 420         """
 421         return self._node.path
 422
 423     def GetData(self):
 424         self.Detail('GetData: size %s' % ToHexSize(self.data))
 425         return self.data
 426
 427     def GetOffsets(self):
 428         """Get the offsets for siblings
 429
 430         Some entry types can contain information about the position or size of
 431         other entries. An example of this is the Intel Flash Descriptor, which
 432         knows where the Intel Management Engine section should go.
 433
 434         If this entry knows about the position of other entries, it can specify
 435         this by returning values here
 436
 437         Returns:
 438             Dict:
 439                 key: Entry type
 440                 value: List containing position and size of the given entry
 441                     type. Either can be None if not known
 442         """
 443         return {}
 444
 445     def SetOffsetSize(self, offset, size):
 446         """Set the offset and/or size of an entry
 447
 448         Args:
 449             offset: New offset, or None to leave alone
 450             size: New size, or None to leave alone
 451         """
 452         if offset is not None:
 453             self.offset = offset
 454         if size is not None:
 455             self.size = size
 456
 457     def SetImagePos(self, image_pos):
 458         """Set the position in the image
 459
 460         Args:
 461             image_pos: Position of this entry in the image
 462         """
 463         self.image_pos = image_pos + self.offset
 464
 465     def ProcessContents(self):
 466         """Do any post-packing updates of entry contents
 467
 468         This function should call ProcessContentsUpdate() to update the entry
 469         contents, if necessary, returning its return value here.
 470
 471         Args:
 472             data: Data to set to the contents (bytes)
 473
 474         Returns:
 475             True if the new data size is OK, False if expansion is needed
 476
 477         Raises:
 478             ValueError if the new data size is not the same as the old and
 479                 state.AllowEntryExpansion() is False
 480         """
 481         return True
 482
 483     def WriteSymbols(self, section):
 484         """Write symbol values into binary files for access at run time
 485
 486         Args:
 487           section: Section containing the entry
 488         """
 489         pass
 490
 491     def CheckOffset(self):
 492         """Check that the entry offsets are correct
 493
 494         This is used for entries which have extra offset requirements (other
 495         than having to be fully inside their section). Sub-classes can implement
 496         this function and raise if there is a problem.
 497         """
 498         pass
 499
 500     @staticmethod
 501     def GetStr(value):
 502         if value is None:
 503             return '<none>  '
 504         return '%08x' % value
 505
 506     @staticmethod
 507     def WriteMapLine(fd, indent, name, offset, size, image_pos):
 508         print('%s  %s%s  %s  %s' % (Entry.GetStr(image_pos), ' ' * indent,
 509                                     Entry.GetStr(offset), Entry.GetStr(size),
 510                                     name), file=fd)
 511
 512     def WriteMap(self, fd, indent):
 513         """Write a map of the entry to a .map file
 514
 515         Args:
 516             fd: File to write the map to
 517             indent: Curent indent level of map (0=none, 1=one level, etc.)
 518         """
 519         self.WriteMapLine(fd, indent, self.name, self.offset, self.size,
 520                           self.image_pos)
 521
 522     def GetEntries(self):
 523         """Return a list of entries contained by this entry
 524
 525         Returns:
 526             List of entries, or None if none. A normal entry has no entries
 527                 within it so will return None
 528         """
 529         return None
 530
 531     def GetArg(self, name, datatype=str):
 532         """Get the value of an entry argument or device-tree-node property
 533
 534         Some node properties can be provided as arguments to binman. First check
 535         the entry arguments, and fall back to the device tree if not found
 536
 537         Args:
 538             name: Argument name
 539             datatype: Data type (str or int)
 540
 541         Returns:
 542             Value of argument as a string or int, or None if no value
 543
 544         Raises:
 545             ValueError if the argument cannot be converted to in
 546         """
 547         value = state.GetEntryArg(name)
 548         if value is not None:
 549             if datatype == int:
 550                 try:
 551                     value = int(value)
 552                 except ValueError:
 553                     self.Raise("Cannot convert entry arg '%s' (value '%s') to integer" %
 554                                (name, value))
 555             elif datatype == str:
 556                 pass
 557             else:
 558                 raise ValueError("GetArg() internal error: Unknown data type '%s'" %
 559                                  datatype)
 560         else:
 561             value = fdt_util.GetDatatype(self._node, name, datatype)
 562         return value
 563
 564     @staticmethod
 565     def WriteDocs(modules, test_missing=None):
 566         """Write out documentation about the various entry types to stdout
 567
 568         Args:
 569             modules: List of modules to include
 570             test_missing: Used for testing. This is a module to report
 571                 as missing
 572         """
 573         print('''Binman Entry Documentation
 574 ===========================
 575
 576 This file describes the entry types supported by binman. These entry types can
 577 be placed in an image one by one to build up a final firmware image. It is
 578 fairly easy to create new entry types. Just add a new file to the 'etype'
 579 directory. You can use the existing entries as examples.
 580
 581 Note that some entries are subclasses of others, using and extending their
 582 features to produce new behaviours.
 583
 584
 585 ''')
 586         modules = sorted(modules)
 587
 588         # Don't show the test entry
 589         if '_testing' in modules:
 590             modules.remove('_testing')
 591         missing = []
 592         for name in modules:
 593             if name.startswith('__'):
 594                 continue
 595             module = Entry.Lookup(name, 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'