tools/binman/etype/section.py

   1 # SPDX-License-Identifier:      GPL-2.0+
   2 # Copyright (c) 2018 Google, Inc
   3 # Written by Simon Glass <sjg@chromium.org>
   4
   5 """Entry-type module for sections (groups of entries)
   6
   7 Sections are entries which can contain other entries. This allows hierarchical
   8 images to be created.
   9 """
  10
  11 from collections import OrderedDict
  12 import re
  13 import sys
  14
  15 from binman.entry import Entry
  16 from dtoc import fdt_util
  17 from patman import tools
  18 from patman import tout
  19 from patman.tools import ToHexSize
  20
  21
  22 class Entry_section(Entry):
  23     """Entry that contains other entries
  24
  25     Properties / Entry arguments: (see binman README for more information)
  26         pad-byte: Pad byte to use when padding
  27         sort-by-offset: True if entries should be sorted by offset, False if
  28             they must be in-order in the device tree description
  29         end-at-4gb: Used to build an x86 ROM which ends at 4GB (2^32)
  30         skip-at-start: Number of bytes before the first entry starts. These
  31             effectively adjust the starting offset of entries. For example,
  32             if this is 16, then the first entry would start at 16. An entry
  33             with offset = 20 would in fact be written at offset 4 in the image
  34             file, since the first 16 bytes are skipped when writing.
  35         name-prefix: Adds a prefix to the name of every entry in the section
  36             when writing out the map
  37
  38     Properties:
  39         allow_missing: True if this section permits external blobs to be
  40             missing their contents. The second will produce an image but of
  41             course it will not work.
  42
  43     Since a section is also an entry, it inherits all the properies of entries
  44     too.
  45
  46     A section is an entry which can contain other entries, thus allowing
  47     hierarchical images to be created. See 'Sections and hierarchical images'
  48     in the binman README for more information.
  49     """
  50     def __init__(self, section, etype, node, test=False):
  51         if not test:
  52             super().__init__(section, etype, node)
  53         self._entries = OrderedDict()
  54         self._pad_byte = 0
  55         self._sort = False
  56         self._skip_at_start = None
  57         self._end_4gb = False
  58
  59     def ReadNode(self):
  60         """Read properties from the section node"""
  61         super().ReadNode()
  62         self._pad_byte = fdt_util.GetInt(self._node, 'pad-byte', 0)
  63         self._sort = fdt_util.GetBool(self._node, 'sort-by-offset')
  64         self._end_4gb = fdt_util.GetBool(self._node, 'end-at-4gb')
  65         self._skip_at_start = fdt_util.GetInt(self._node, 'skip-at-start')
  66         if self._end_4gb:
  67             if not self.size:
  68                 self.Raise("Section size must be provided when using end-at-4gb")
  69             if self._skip_at_start is not None:
  70                 self.Raise("Provide either 'end-at-4gb' or 'skip-at-start'")
  71             else:
  72                 self._skip_at_start = 0x100000000 - self.size
  73         else:
  74             if self._skip_at_start is None:
  75                 self._skip_at_start = 0
  76         self._name_prefix = fdt_util.GetString(self._node, 'name-prefix')
  77         filename = fdt_util.GetString(self._node, 'filename')
  78         if filename:
  79             self._filename = filename
  80
  81         self._ReadEntries()
  82
  83     def _ReadEntries(self):
  84         for node in self._node.subnodes:
  85             if node.name.startswith('hash') or node.name.startswith('signature'):
  86                 continue
  87             entry = Entry.Create(self, node)
  88             entry.ReadNode()
  89             entry.SetPrefix(self._name_prefix)
  90             self._entries[node.name] = entry
  91
  92     def _Raise(self, msg):
  93         """Raises an error for this section
  94
  95         Args:
  96             msg: Error message to use in the raise string
  97         Raises:
  98             ValueError()
  99         """
 100         raise ValueError("Section '%s': %s" % (self._node.path, msg))
 101
 102     def GetFdts(self):
 103         fdts = {}
 104         for entry in self._entries.values():
 105             fdts.update(entry.GetFdts())
 106         return fdts
 107
 108     def ProcessFdt(self, fdt):
 109         """Allow entries to adjust the device tree
 110
 111         Some entries need to adjust the device tree for their purposes. This
 112         may involve adding or deleting properties.
 113         """
 114         todo = self._entries.values()
 115         for passnum in range(3):
 116             next_todo = []
 117             for entry in todo:
 118                 if not entry.ProcessFdt(fdt):
 119                     next_todo.append(entry)
 120             todo = next_todo
 121             if not todo:
 122                 break
 123         if todo:
 124             self.Raise('Internal error: Could not complete processing of Fdt: remaining %s' %
 125                        todo)
 126         return True
 127
 128     def ExpandEntries(self):
 129         """Expand out any entries which have calculated sub-entries
 130
 131         Some entries are expanded out at runtime, e.g. 'files', which produces
 132         a section containing a list of files. Process these entries so that
 133         this information is added to the device tree.
 134         """
 135         super().ExpandEntries()
 136         for entry in self._entries.values():
 137             entry.ExpandEntries()
 138
 139     def AddMissingProperties(self, have_image_pos):
 140         """Add new properties to the device tree as needed for this entry"""
 141         super().AddMissingProperties(have_image_pos)
 142         if self.compress != 'none':
 143             have_image_pos = False
 144         for entry in self._entries.values():
 145             entry.AddMissingProperties(have_image_pos)
 146
 147     def ObtainContents(self):
 148         return self.GetEntryContents()
 149
 150     def GetPaddedDataForEntry(self, entry):
 151         """Get the data for an entry including any padding
 152
 153         Gets the entry data and uses the section pad-byte value to add padding
 154         before and after as defined by the pad-before and pad-after properties.
 155         This does not consider alignment.
 156
 157         Args:
 158             entry: Entry to check
 159
 160         Returns:
 161             Contents of the entry along with any pad bytes before and
 162             after it (bytes)
 163         """
 164         pad_byte = (entry._pad_byte if isinstance(entry, Entry_section)
 165                     else self._pad_byte)
 166
 167         data = b''
 168         # Handle padding before the entry
 169         if entry.pad_before:
 170             data += tools.GetBytes(self._pad_byte, entry.pad_before)
 171
 172         # Add in the actual entry data
 173         data += entry.GetData()
 174
 175         # Handle padding after the entry
 176         if entry.pad_after:
 177             data += tools.GetBytes(self._pad_byte, entry.pad_after)
 178
 179         if entry.size:
 180             data += tools.GetBytes(pad_byte, entry.size - len(data))
 181
 182         self.Detail('GetPaddedDataForEntry: size %s' % ToHexSize(self.data))
 183
 184         return data
 185
 186     def _BuildSectionData(self):
 187         """Build the contents of a section
 188
 189         This places all entries at the right place, dealing with padding before
 190         and after entries. It does not do padding for the section itself (the
 191         pad-before and pad-after properties in the section items) since that is
 192         handled by the parent section.
 193
 194         Returns:
 195             Contents of the section (bytes)
 196         """
 197         section_data = b''
 198
 199         for entry in self._entries.values():
 200             data = self.GetPaddedDataForEntry(entry)
 201             # Handle empty space before the entry
 202             pad = (entry.offset or 0) - self._skip_at_start - len(section_data)
 203             if pad > 0:
 204                 section_data += tools.GetBytes(self._pad_byte, pad)
 205
 206             # Add in the actual entry data
 207             section_data += data
 208
 209         self.Detail('GetData: %d entries, total size %#x' %
 210                     (len(self._entries), len(section_data)))
 211         return self.CompressData(section_data)
 212
 213     def GetPaddedData(self):
 214         """Get the data for a section including any padding
 215
 216         Gets the section data and uses the parent section's pad-byte value to
 217         add padding before and after as defined by the pad-before and pad-after
 218         properties. If this is a top-level section (i.e. an image), this is the
 219         same as GetData(), since padding is not supported.
 220
 221         This does not consider alignment.
 222
 223         Returns:
 224             Contents of the section along with any pad bytes before and
 225             after it (bytes)
 226         """
 227         section = self.section or self
 228         return section.GetPaddedDataForEntry(self)
 229
 230     def GetData(self):
 231         """Get the contents of an entry
 232
 233         This builds the contents of the section, stores this as the contents of
 234         the section and returns it
 235
 236         Returns:
 237             bytes content of the section, made up for all all of its subentries.
 238             This excludes any padding. If the section is compressed, the
 239             compressed data is returned
 240         """
 241         data = self._BuildSectionData()
 242         self.SetContents(data)
 243         return data
 244
 245     def GetOffsets(self):
 246         """Handle entries that want to set the offset/size of other entries
 247
 248         This calls each entry's GetOffsets() method. If it returns a list
 249         of entries to update, it updates them.
 250         """
 251         self.GetEntryOffsets()
 252         return {}
 253
 254     def ResetForPack(self):
 255         """Reset offset/size fields so that packing can be done again"""
 256         super().ResetForPack()
 257         for entry in self._entries.values():
 258             entry.ResetForPack()
 259
 260     def Pack(self, offset):
 261         """Pack all entries into the section"""
 262         self._PackEntries()
 263         if self._sort:
 264             self._SortEntries()
 265         self._ExpandEntries()
 266
 267         return super().Pack(offset)
 268
 269     def _PackEntries(self):
 270         """Pack all entries into the section"""
 271         offset = self._skip_at_start
 272         for entry in self._entries.values():
 273             offset = entry.Pack(offset)
 274         self.size = self.CheckSize()
 275
 276     def _ExpandEntries(self):
 277         """Expand any entries that are permitted to"""
 278         exp_entry = None
 279         for entry in self._entries.values():
 280             if exp_entry:
 281                 exp_entry.ExpandToLimit(entry.offset)
 282                 exp_entry = None
 283             if entry.expand_size:
 284                 exp_entry = entry
 285         if exp_entry:
 286             exp_entry.ExpandToLimit(self.size)
 287
 288     def _SortEntries(self):
 289         """Sort entries by offset"""
 290         entries = sorted(self._entries.values(), key=lambda entry: entry.offset)
 291         self._entries.clear()
 292         for entry in entries:
 293             self._entries[entry._node.name] = entry
 294
 295     def CheckEntries(self):
 296         """Check that entries do not overlap or extend outside the section"""
 297         offset = 0
 298         prev_name = 'None'
 299         for entry in self._entries.values():
 300             entry.CheckEntries()
 301             if (entry.offset < self._skip_at_start or
 302                     entry.offset + entry.size > self._skip_at_start +
 303                     self.size):
 304                 entry.Raise('Offset %#x (%d) size %#x (%d) is outside the '
 305                             "section '%s' starting at %#x (%d) "
 306                             'of size %#x (%d)' %
 307                             (entry.offset, entry.offset, entry.size, entry.size,
 308                              self._node.path, self._skip_at_start,
 309                              self._skip_at_start, self.size, self.size))
 310             if entry.offset < offset and entry.size:
 311                 entry.Raise("Offset %#x (%d) overlaps with previous entry '%s' "
 312                             "ending at %#x (%d)" %
 313                             (entry.offset, entry.offset, prev_name, offset, offset))
 314             offset = entry.offset + entry.size
 315             prev_name = entry.GetPath()
 316
 317     def WriteSymbols(self, section):
 318         """Write symbol values into binary files for access at run time"""
 319         for entry in self._entries.values():
 320             entry.WriteSymbols(self)
 321
 322     def SetCalculatedProperties(self):
 323         super().SetCalculatedProperties()
 324         for entry in self._entries.values():
 325             entry.SetCalculatedProperties()
 326
 327     def SetImagePos(self, image_pos):
 328         super().SetImagePos(image_pos)
 329         if self.compress == 'none':
 330             for entry in self._entries.values():
 331                 entry.SetImagePos(image_pos + self.offset)
 332
 333     def ProcessContents(self):
 334         sizes_ok_base = super(Entry_section, self).ProcessContents()
 335         sizes_ok = True
 336         for entry in self._entries.values():
 337             if not entry.ProcessContents():
 338                 sizes_ok = False
 339         return sizes_ok and sizes_ok_base
 340
 341     def WriteMap(self, fd, indent):
 342         """Write a map of the section to a .map file
 343
 344         Args:
 345             fd: File to write the map to
 346         """
 347         Entry.WriteMapLine(fd, indent, self.name, self.offset or 0,
 348                            self.size, self.image_pos)
 349         for entry in self._entries.values():
 350             entry.WriteMap(fd, indent + 1)
 351
 352     def GetEntries(self):
 353         return self._entries
 354
 355     def GetContentsByPhandle(self, phandle, source_entry):
 356         """Get the data contents of an entry specified by a phandle
 357
 358         This uses a phandle to look up a node and and find the entry
 359         associated with it. Then it returnst he contents of that entry.
 360
 361         Args:
 362             phandle: Phandle to look up (integer)
 363             source_entry: Entry containing that phandle (used for error
 364                 reporting)
 365
 366         Returns:
 367             data from associated entry (as a string), or None if not found
 368         """
 369         node = self._node.GetFdt().LookupPhandle(phandle)
 370         if not node:
 371             source_entry.Raise("Cannot find node for phandle %d" % phandle)
 372         for entry in self._entries.values():
 373             if entry._node == node:
 374                 return entry.GetData()
 375         source_entry.Raise("Cannot find entry for node '%s'" % node.name)
 376
 377     def LookupSymbol(self, sym_name, optional, msg, base_addr):
 378         """Look up a symbol in an ELF file
 379
 380         Looks up a symbol in an ELF file. Only entry types which come from an
 381         ELF image can be used by this function.
 382
 383         At present the only entry properties supported are:
 384             offset
 385             image_pos - 'base_addr' is added if this is not an end-at-4gb image
 386             size
 387
 388         Args:
 389             sym_name: Symbol name in the ELF file to look up in the format
 390                 _binman_<entry>_prop_<property> where <entry> is the name of
 391                 the entry and <property> is the property to find (e.g.
 392                 _binman_u_boot_prop_offset). As a special case, you can append
 393                 _any to <entry> to have it search for any matching entry. E.g.
 394                 _binman_u_boot_any_prop_offset will match entries called u-boot,
 395                 u-boot-img and u-boot-nodtb)
 396             optional: True if the symbol is optional. If False this function
 397                 will raise if the symbol is not found
 398             msg: Message to display if an error occurs
 399             base_addr: Base address of image. This is added to the returned
 400                 image_pos in most cases so that the returned position indicates
 401                 where the targetted entry/binary has actually been loaded. But
 402                 if end-at-4gb is used, this is not done, since the binary is
 403                 already assumed to be linked to the ROM position and using
 404                 execute-in-place (XIP).
 405
 406         Returns:
 407             Value that should be assigned to that symbol, or None if it was
 408                 optional and not found
 409
 410         Raises:
 411             ValueError if the symbol is invalid or not found, or references a
 412                 property which is not supported
 413         """
 414         m = re.match(r'^_binman_(\w+)_prop_(\w+)$', sym_name)
 415         if not m:
 416             raise ValueError("%s: Symbol '%s' has invalid format" %
 417                              (msg, sym_name))
 418         entry_name, prop_name = m.groups()
 419         entry_name = entry_name.replace('_', '-')
 420         entry = self._entries.get(entry_name)
 421         if not entry:
 422             if entry_name.endswith('-any'):
 423                 root = entry_name[:-4]
 424                 for name in self._entries:
 425                     if name.startswith(root):
 426                         rest = name[len(root):]
 427                         if rest in ['', '-img', '-nodtb']:
 428                             entry = self._entries[name]
 429         if not entry:
 430             err = ("%s: Entry '%s' not found in list (%s)" %
 431                    (msg, entry_name, ','.join(self._entries.keys())))
 432             if optional:
 433                 print('Warning: %s' % err, file=sys.stderr)
 434                 return None
 435             raise ValueError(err)
 436         if prop_name == 'offset':
 437             return entry.offset
 438         elif prop_name == 'image_pos':
 439             value = entry.image_pos
 440             if not self.GetImage()._end_4gb:
 441                 value += base_addr
 442             return value
 443         if prop_name == 'size':
 444             return entry.size
 445         else:
 446             raise ValueError("%s: No such property '%s'" % (msg, prop_name))
 447
 448     def GetRootSkipAtStart(self):
 449         """Get the skip-at-start value for the top-level section
 450
 451         This is used to find out the starting offset for root section that
 452         contains this section. If this is a top-level section then it returns
 453         the skip-at-start offset for this section.
 454
 455         This is used to get the absolute position of section within the image.
 456
 457         Returns:
 458             Integer skip-at-start value for the root section containing this
 459                 section
 460         """
 461         if self.section:
 462             return self.section.GetRootSkipAtStart()
 463         return self._skip_at_start
 464
 465     def GetStartOffset(self):
 466         """Get the start offset for this section
 467
 468         Returns:
 469             The first available offset in this section (typically 0)
 470         """
 471         return self._skip_at_start
 472
 473     def GetImageSize(self):
 474         """Get the size of the image containing this section
 475
 476         Returns:
 477             Image size as an integer number of bytes, which may be None if the
 478                 image size is dynamic and its sections have not yet been packed
 479         """
 480         return self.GetImage().size
 481
 482     def FindEntryType(self, etype):
 483         """Find an entry type in the section
 484
 485         Args:
 486             etype: Entry type to find
 487         Returns:
 488             entry matching that type, or None if not found
 489         """
 490         for entry in self._entries.values():
 491             if entry.etype == etype:
 492                 return entry
 493         return None
 494
 495     def GetEntryContents(self):
 496         """Call ObtainContents() for each entry in the section
 497         """
 498         todo = self._entries.values()
 499         for passnum in range(3):
 500             next_todo = []
 501             for entry in todo:
 502                 if not entry.ObtainContents():
 503                     next_todo.append(entry)
 504             todo = next_todo
 505             if not todo:
 506                 break
 507         if todo:
 508             self.Raise('Internal error: Could not complete processing of contents: remaining %s' %
 509                        todo)
 510         return True
 511
 512     def _SetEntryOffsetSize(self, name, offset, size):
 513         """Set the offset and size of an entry
 514
 515         Args:
 516             name: Entry name to update
 517             offset: New offset, or None to leave alone
 518             size: New size, or None to leave alone
 519         """
 520         entry = self._entries.get(name)
 521         if not entry:
 522             self._Raise("Unable to set offset/size for unknown entry '%s'" %
 523                         name)
 524         entry.SetOffsetSize(self._skip_at_start + offset if offset is not None
 525                             else None, size)
 526
 527     def GetEntryOffsets(self):
 528         """Handle entries that want to set the offset/size of other entries
 529
 530         This calls each entry's GetOffsets() method. If it returns a list
 531         of entries to update, it updates them.
 532         """
 533         for entry in self._entries.values():
 534             offset_dict = entry.GetOffsets()
 535             for name, info in offset_dict.items():
 536                 self._SetEntryOffsetSize(name, *info)
 537
 538
 539     def CheckSize(self):
 540         """Check that the section contents does not exceed its size, etc."""
 541         contents_size = 0
 542         for entry in self._entries.values():
 543             contents_size = max(contents_size, entry.offset + entry.size)
 544
 545         contents_size -= self._skip_at_start
 546
 547         size = self.size
 548         if not size:
 549             size = self.pad_before + contents_size + self.pad_after
 550             size = tools.Align(size, self.align_size)
 551
 552         if self.size and contents_size > self.size:
 553             self._Raise("contents size %#x (%d) exceeds section size %#x (%d)" %
 554                         (contents_size, contents_size, self.size, self.size))
 555         if not self.size:
 556             self.size = size
 557         if self.size != tools.Align(self.size, self.align_size):
 558             self._Raise("Size %#x (%d) does not match align-size %#x (%d)" %
 559                         (self.size, self.size, self.align_size,
 560                          self.align_size))
 561         return size
 562
 563     def ListEntries(self, entries, indent):
 564         """List the files in the section"""
 565         Entry.AddEntryInfo(entries, indent, self.name, 'section', self.size,
 566                            self.image_pos, None, self.offset, self)
 567         for entry in self._entries.values():
 568             entry.ListEntries(entries, indent + 1)
 569
 570     def LoadData(self, decomp=True):
 571         for entry in self._entries.values():
 572             entry.LoadData(decomp)
 573         self.Detail('Loaded data')
 574
 575     def GetImage(self):
 576         """Get the image containing this section
 577
 578         Note that a top-level section is actually an Image, so this function may
 579         return self.
 580
 581         Returns:
 582             Image object containing this section
 583         """
 584         if not self.section:
 585             return self
 586         return self.section.GetImage()
 587
 588     def GetSort(self):
 589         """Check if the entries in this section will be sorted
 590
 591         Returns:
 592             True if to be sorted, False if entries will be left in the order
 593                 they appear in the device tree
 594         """
 595         return self._sort
 596
 597     def ReadData(self, decomp=True):
 598         tout.Info("ReadData path='%s'" % self.GetPath())
 599         parent_data = self.section.ReadData(True)
 600         tout.Info('%s: Reading data from offset %#x-%#x, size %#x' %
 601                   (self.GetPath(), self.offset, self.offset + self.size,
 602                    self.size))
 603         data = parent_data[self.offset:self.offset + self.size]
 604         return data
 605
 606     def ReadChildData(self, child, decomp=True):
 607         tout.Debug("ReadChildData for child '%s'" % child.GetPath())
 608         parent_data = self.ReadData(True)
 609         offset = child.offset - self._skip_at_start
 610         tout.Debug("Extract for child '%s': offset %#x, skip_at_start %#x, result %#x" %
 611                    (child.GetPath(), child.offset, self._skip_at_start, offset))
 612         data = parent_data[offset:offset + child.size]
 613         if decomp:
 614             indata = data
 615             data = tools.Decompress(indata, child.compress)
 616             if child.uncomp_size:
 617                 tout.Info("%s: Decompressing data size %#x with algo '%s' to data size %#x" %
 618                             (child.GetPath(), len(indata), child.compress,
 619                             len(data)))
 620         return data
 621
 622     def WriteChildData(self, child):
 623         return True
 624
 625     def SetAllowMissing(self, allow_missing):
 626         """Set whether a section allows missing external blobs
 627
 628         Args:
 629             allow_missing: True if allowed, False if not allowed
 630         """
 631         self.allow_missing = allow_missing
 632         for entry in self._entries.values():
 633             entry.SetAllowMissing(allow_missing)
 634
 635     def CheckMissing(self, missing_list):
 636         """Check if any entries in this section have missing external blobs
 637
 638         If there are missing blobs, the entries are added to the list
 639
 640         Args:
 641             missing_list: List of Entry objects to be added to
 642         """
 643         for entry in self._entries.values():
 644             entry.CheckMissing(missing_list)