tools/binman/control.py

   1 # SPDX-License-Identifier: GPL-2.0+
   2 # Copyright (c) 2016 Google, Inc
   3 # Written by Simon Glass <sjg@chromium.org>
   4 #
   5 # Creates binary images from input files controlled by a description
   6 #
   7
   8 from __future__ import print_function
   9
  10 from collections import OrderedDict
  11 import os
  12 import sys
  13 import tools
  14
  15 import cbfs_util
  16 import command
  17 import elf
  18 from image import Image
  19 import state
  20 import tout
  21
  22 # List of images we plan to create
  23 # Make this global so that it can be referenced from tests
  24 images = OrderedDict()
  25
  26 def _ReadImageDesc(binman_node):
  27     """Read the image descriptions from the /binman node
  28
  29     This normally produces a single Image object called 'image'. But if
  30     multiple images are present, they will all be returned.
  31
  32     Args:
  33         binman_node: Node object of the /binman node
  34     Returns:
  35         OrderedDict of Image objects, each of which describes an image
  36     """
  37     images = OrderedDict()
  38     if 'multiple-images' in binman_node.props:
  39         for node in binman_node.subnodes:
  40             images[node.name] = Image(node.name, node)
  41     else:
  42         images['image'] = Image('image', binman_node)
  43     return images
  44
  45 def _FindBinmanNode(dtb):
  46     """Find the 'binman' node in the device tree
  47
  48     Args:
  49         dtb: Fdt object to scan
  50     Returns:
  51         Node object of /binman node, or None if not found
  52     """
  53     for node in dtb.GetRoot().subnodes:
  54         if node.name == 'binman':
  55             return node
  56     return None
  57
  58 def WriteEntryDocs(modules, test_missing=None):
  59     """Write out documentation for all entries
  60
  61     Args:
  62         modules: List of Module objects to get docs for
  63         test_missing: Used for testing only, to force an entry's documeentation
  64             to show as missing even if it is present. Should be set to None in
  65             normal use.
  66     """
  67     from entry import Entry
  68     Entry.WriteDocs(modules, test_missing)
  69
  70
  71 def ListEntries(image_fname, entry_paths):
  72     """List the entries in an image
  73
  74     This decodes the supplied image and displays a table of entries from that
  75     image, preceded by a header.
  76
  77     Args:
  78         image_fname: Image filename to process
  79         entry_paths: List of wildcarded paths (e.g. ['*dtb*', 'u-boot*',
  80                                                      'section/u-boot'])
  81     """
  82     image = Image.FromFile(image_fname)
  83
  84     entries, lines, widths = image.GetListEntries(entry_paths)
  85
  86     num_columns = len(widths)
  87     for linenum, line in enumerate(lines):
  88         if linenum == 1:
  89             # Print header line
  90             print('-' * (sum(widths) + num_columns * 2))
  91         out = ''
  92         for i, item in enumerate(line):
  93             width = -widths[i]
  94             if item.startswith('>'):
  95                 width = -width
  96                 item = item[1:]
  97             txt = '%*s  ' % (width, item)
  98             out += txt
  99         print(out.rstrip())
 100
 101
 102 def ReadEntry(image_fname, entry_path, decomp=True):
 103     """Extract an entry from an image
 104
 105     This extracts the data from a particular entry in an image
 106
 107     Args:
 108         image_fname: Image filename to process
 109         entry_path: Path to entry to extract
 110         decomp: True to return uncompressed data, if the data is compress
 111             False to return the raw data
 112
 113     Returns:
 114         data extracted from the entry
 115     """
 116     image = Image.FromFile(image_fname)
 117     entry = image.FindEntryPath(entry_path)
 118     return entry.ReadData(decomp)
 119
 120
 121 def ExtractEntries(image_fname, output_fname, outdir, entry_paths,
 122                    decomp=True):
 123     """Extract the data from one or more entries and write it to files
 124
 125     Args:
 126         image_fname: Image filename to process
 127         output_fname: Single output filename to use if extracting one file, None
 128             otherwise
 129         outdir: Output directory to use (for any number of files), else None
 130         entry_paths: List of entry paths to extract
 131         decomp: True to decompress the entry data
 132
 133     Returns:
 134         List of EntryInfo records that were written
 135     """
 136     image = Image.FromFile(image_fname)
 137
 138     # Output an entry to a single file, as a special case
 139     if output_fname:
 140         if not entry_paths:
 141             raise ValueError('Must specify an entry path to write with -f')
 142         if len(entry_paths) != 1:
 143             raise ValueError('Must specify exactly one entry path to write with -f')
 144         entry = image.FindEntryPath(entry_paths[0])
 145         data = entry.ReadData(decomp)
 146         tools.WriteFile(output_fname, data)
 147         tout.Notice("Wrote %#x bytes to file '%s'" % (len(data), output_fname))
 148         return
 149
 150     # Otherwise we will output to a path given by the entry path of each entry.
 151     # This means that entries will appear in subdirectories if they are part of
 152     # a sub-section.
 153     einfos = image.GetListEntries(entry_paths)[0]
 154     tout.Notice('%d entries match and will be written' % len(einfos))
 155     for einfo in einfos:
 156         entry = einfo.entry
 157         data = entry.ReadData(decomp)
 158         path = entry.GetPath()[1:]
 159         fname = os.path.join(outdir, path)
 160
 161         # If this entry has children, create a directory for it and put its
 162         # data in a file called 'root' in that directory
 163         if entry.GetEntries():
 164             if not os.path.exists(fname):
 165                 os.makedirs(fname)
 166             fname = os.path.join(fname, 'root')
 167         tout.Notice("Write entry '%s' to '%s'" % (entry.GetPath(), fname))
 168         tools.WriteFile(fname, data)
 169     return einfos
 170
 171
 172 def BeforeReplace(image, allow_resize):
 173     """Handle getting an image ready for replacing entries in it
 174
 175     Args:
 176         image: Image to prepare
 177     """
 178     state.PrepareFromLoadedData(image)
 179     image.LoadData()
 180
 181     # If repacking, drop the old offset/size values except for the original
 182     # ones, so we are only left with the constraints.
 183     if allow_resize:
 184         image.ResetForPack()
 185
 186
 187 def ReplaceOneEntry(image, entry, data, do_compress, allow_resize):
 188     """Handle replacing a single entry an an image
 189
 190     Args:
 191         image: Image to update
 192         entry: Entry to write
 193         data: Data to replace with
 194         do_compress: True to compress the data if needed, False if data is
 195             already compressed so should be used as is
 196         allow_resize: True to allow entries to change size (this does a re-pack
 197             of the entries), False to raise an exception
 198     """
 199     if not entry.WriteData(data, do_compress):
 200         if not image.allow_repack:
 201             entry.Raise('Entry data size does not match, but allow-repack is not present for this image')
 202         if not allow_resize:
 203             entry.Raise('Entry data size does not match, but resize is disabled')
 204
 205
 206 def AfterReplace(image, allow_resize, write_map):
 207     """Handle write out an image after replacing entries in it
 208
 209     Args:
 210         image: Image to write
 211         allow_resize: True to allow entries to change size (this does a re-pack
 212             of the entries), False to raise an exception
 213         write_map: True to write a map file
 214     """
 215     tout.Info('Processing image')
 216     ProcessImage(image, update_fdt=True, write_map=write_map,
 217                  get_contents=False, allow_resize=allow_resize)
 218
 219
 220 def WriteEntryToImage(image, entry, data, do_compress=True, allow_resize=True,
 221                       write_map=False):
 222     BeforeReplace(image, allow_resize)
 223     tout.Info('Writing data to %s' % entry.GetPath())
 224     ReplaceOneEntry(image, entry, data, do_compress, allow_resize)
 225     AfterReplace(image, allow_resize=allow_resize, write_map=write_map)
 226
 227
 228 def WriteEntry(image_fname, entry_path, data, do_compress=True,
 229                allow_resize=True, write_map=False):
 230     """Replace an entry in an image
 231
 232     This replaces the data in a particular entry in an image. This size of the
 233     new data must match the size of the old data unless allow_resize is True.
 234
 235     Args:
 236         image_fname: Image filename to process
 237         entry_path: Path to entry to extract
 238         data: Data to replace with
 239         do_compress: True to compress the data if needed, False if data is
 240             already compressed so should be used as is
 241         allow_resize: True to allow entries to change size (this does a re-pack
 242             of the entries), False to raise an exception
 243         write_map: True to write a map file
 244
 245     Returns:
 246         Image object that was updated
 247     """
 248     tout.Info("Write entry '%s', file '%s'" % (entry_path, image_fname))
 249     image = Image.FromFile(image_fname)
 250     entry = image.FindEntryPath(entry_path)
 251     WriteEntryToImage(image, entry, data, do_compress=do_compress,
 252                       allow_resize=allow_resize, write_map=write_map)
 253
 254     return image
 255
 256
 257 def ReplaceEntries(image_fname, input_fname, indir, entry_paths,
 258                    do_compress=True, allow_resize=True, write_map=False):
 259     """Replace the data from one or more entries from input files
 260
 261     Args:
 262         image_fname: Image filename to process
 263         input_fname: Single input ilename to use if replacing one file, None
 264             otherwise
 265         indir: Input directory to use (for any number of files), else None
 266         entry_paths: List of entry paths to extract
 267         do_compress: True if the input data is uncompressed and may need to be
 268             compressed if the entry requires it, False if the data is already
 269             compressed.
 270         write_map: True to write a map file
 271
 272     Returns:
 273         List of EntryInfo records that were written
 274     """
 275     image = Image.FromFile(image_fname)
 276
 277     # Replace an entry from a single file, as a special case
 278     if input_fname:
 279         if not entry_paths:
 280             raise ValueError('Must specify an entry path to read with -f')
 281         if len(entry_paths) != 1:
 282             raise ValueError('Must specify exactly one entry path to write with -f')
 283         entry = image.FindEntryPath(entry_paths[0])
 284         data = tools.ReadFile(input_fname)
 285         tout.Notice("Read %#x bytes from file '%s'" % (len(data), input_fname))
 286         WriteEntryToImage(image, entry, data, do_compress=do_compress,
 287                           allow_resize=allow_resize, write_map=write_map)
 288         return
 289
 290     # Otherwise we will input from a path given by the entry path of each entry.
 291     # This means that files must appear in subdirectories if they are part of
 292     # a sub-section.
 293     einfos = image.GetListEntries(entry_paths)[0]
 294     tout.Notice("Replacing %d matching entries in image '%s'" %
 295                 (len(einfos), image_fname))
 296
 297     BeforeReplace(image, allow_resize)
 298
 299     for einfo in einfos:
 300         entry = einfo.entry
 301         if entry.GetEntries():
 302             tout.Info("Skipping section entry '%s'" % entry.GetPath())
 303             continue
 304
 305         path = entry.GetPath()[1:]
 306         fname = os.path.join(indir, path)
 307
 308         if os.path.exists(fname):
 309             tout.Notice("Write entry '%s' from file '%s'" %
 310                         (entry.GetPath(), fname))
 311             data = tools.ReadFile(fname)
 312             ReplaceOneEntry(image, entry, data, do_compress, allow_resize)
 313         else:
 314             tout.Warning("Skipping entry '%s' from missing file '%s'" %
 315                          (entry.GetPath(), fname))
 316
 317     AfterReplace(image, allow_resize=allow_resize, write_map=write_map)
 318     return image
 319
 320
 321 def PrepareImagesAndDtbs(dtb_fname, select_images, update_fdt):
 322     """Prepare the images to be processed and select the device tree
 323
 324     This function:
 325     - reads in the device tree
 326     - finds and scans the binman node to create all entries
 327     - selects which images to build
 328     - Updates the device tress with placeholder properties for offset,
 329         image-pos, etc.
 330
 331     Args:
 332         dtb_fname: Filename of the device tree file to use (.dts or .dtb)
 333         selected_images: List of images to output, or None for all
 334         update_fdt: True to update the FDT wth entry offsets, etc.
 335     """
 336     # Import these here in case libfdt.py is not available, in which case
 337     # the above help option still works.
 338     import fdt
 339     import fdt_util
 340     global images
 341
 342     # Get the device tree ready by compiling it and copying the compiled
 343     # output into a file in our output directly. Then scan it for use
 344     # in binman.
 345     dtb_fname = fdt_util.EnsureCompiled(dtb_fname)
 346     fname = tools.GetOutputFilename('u-boot.dtb.out')
 347     tools.WriteFile(fname, tools.ReadFile(dtb_fname))
 348     dtb = fdt.FdtScan(fname)
 349
 350     node = _FindBinmanNode(dtb)
 351     if not node:
 352         raise ValueError("Device tree '%s' does not have a 'binman' "
 353                             "node" % dtb_fname)
 354
 355     images = _ReadImageDesc(node)
 356
 357     if select_images:
 358         skip = []
 359         new_images = OrderedDict()
 360         for name, image in images.items():
 361             if name in select_images:
 362                 new_images[name] = image
 363             else:
 364                 skip.append(name)
 365         images = new_images
 366         tout.Notice('Skipping images: %s' % ', '.join(skip))
 367
 368     state.Prepare(images, dtb)
 369
 370     # Prepare the device tree by making sure that any missing
 371     # properties are added (e.g. 'pos' and 'size'). The values of these
 372     # may not be correct yet, but we add placeholders so that the
 373     # size of the device tree is correct. Later, in
 374     # SetCalculatedProperties() we will insert the correct values
 375     # without changing the device-tree size, thus ensuring that our
 376     # entry offsets remain the same.
 377     for image in images.values():
 378         image.ExpandEntries()
 379         if update_fdt:
 380             image.AddMissingProperties()
 381         image.ProcessFdt(dtb)
 382
 383     for dtb_item in state.GetAllFdts():
 384         dtb_item.Sync(auto_resize=True)
 385         dtb_item.Pack()
 386         dtb_item.Flush()
 387     return images
 388
 389
 390 def ProcessImage(image, update_fdt, write_map, get_contents=True,
 391                  allow_resize=True):
 392     """Perform all steps for this image, including checking and # writing it.
 393
 394     This means that errors found with a later image will be reported after
 395     earlier images are already completed and written, but that does not seem
 396     important.
 397
 398     Args:
 399         image: Image to process
 400         update_fdt: True to update the FDT wth entry offsets, etc.
 401         write_map: True to write a map file
 402         get_contents: True to get the image contents from files, etc., False if
 403             the contents is already present
 404         allow_resize: True to allow entries to change size (this does a re-pack
 405             of the entries), False to raise an exception
 406     """
 407     if get_contents:
 408         image.GetEntryContents()
 409     image.GetEntryOffsets()
 410
 411     # We need to pack the entries to figure out where everything
 412     # should be placed. This sets the offset/size of each entry.
 413     # However, after packing we call ProcessEntryContents() which
 414     # may result in an entry changing size. In that case we need to
 415     # do another pass. Since the device tree often contains the
 416     # final offset/size information we try to make space for this in
 417     # AddMissingProperties() above. However, if the device is
 418     # compressed we cannot know this compressed size in advance,
 419     # since changing an offset from 0x100 to 0x104 (for example) can
 420     # alter the compressed size of the device tree. So we need a
 421     # third pass for this.
 422     passes = 5
 423     for pack_pass in range(passes):
 424         try:
 425             image.PackEntries()
 426             image.CheckSize()
 427             image.CheckEntries()
 428         except Exception as e:
 429             if write_map:
 430                 fname = image.WriteMap()
 431                 print("Wrote map file '%s' to show errors"  % fname)
 432             raise
 433         image.SetImagePos()
 434         if update_fdt:
 435             image.SetCalculatedProperties()
 436             for dtb_item in state.GetAllFdts():
 437                 dtb_item.Sync()
 438                 dtb_item.Flush()
 439         sizes_ok = image.ProcessEntryContents()
 440         if sizes_ok:
 441             break
 442         image.ResetForPack()
 443     if not sizes_ok:
 444         image.Raise('Entries changed size after packing (tried %s passes)' %
 445                     passes)
 446
 447     image.WriteSymbols()
 448     image.BuildImage()
 449     if write_map:
 450         image.WriteMap()
 451
 452
 453 def Binman(args):
 454     """The main control code for binman
 455
 456     This assumes that help and test options have already been dealt with. It
 457     deals with the core task of building images.
 458
 459     Args:
 460         args: Command line arguments Namespace object
 461     """
 462     if args.full_help:
 463         pager = os.getenv('PAGER')
 464         if not pager:
 465             pager = 'more'
 466         fname = os.path.join(os.path.dirname(os.path.realpath(sys.argv[0])),
 467                             'README')
 468         command.Run(pager, fname)
 469         return 0
 470
 471     if args.cmd == 'ls':
 472         try:
 473             tools.PrepareOutputDir(None)
 474             ListEntries(args.image, args.paths)
 475         finally:
 476             tools.FinaliseOutputDir()
 477         return 0
 478
 479     if args.cmd == 'extract':
 480         try:
 481             tools.PrepareOutputDir(None)
 482             ExtractEntries(args.image, args.filename, args.outdir, args.paths,
 483                            not args.uncompressed)
 484         finally:
 485             tools.FinaliseOutputDir()
 486         return 0
 487
 488     if args.cmd == 'replace':
 489         try:
 490             tools.PrepareOutputDir(None)
 491             ReplaceEntries(args.image, args.filename, args.indir, args.paths,
 492                            do_compress=not args.compressed,
 493                            allow_resize=not args.fix_size, write_map=args.map)
 494         finally:
 495             tools.FinaliseOutputDir()
 496         return 0
 497
 498     # Try to figure out which device tree contains our image description
 499     if args.dt:
 500         dtb_fname = args.dt
 501     else:
 502         board = args.board
 503         if not board:
 504             raise ValueError('Must provide a board to process (use -b <board>)')
 505         board_pathname = os.path.join(args.build_dir, board)
 506         dtb_fname = os.path.join(board_pathname, 'u-boot.dtb')
 507         if not args.indir:
 508             args.indir = ['.']
 509         args.indir.append(board_pathname)
 510
 511     try:
 512         tout.Init(args.verbosity)
 513         elf.debug = args.debug
 514         cbfs_util.VERBOSE = args.verbosity > 2
 515         state.use_fake_dtb = args.fake_dtb
 516         try:
 517             tools.SetInputDirs(args.indir)
 518             tools.PrepareOutputDir(args.outdir, args.preserve)
 519             tools.SetToolPaths(args.toolpath)
 520             state.SetEntryArgs(args.entry_arg)
 521
 522             images = PrepareImagesAndDtbs(dtb_fname, args.image,
 523                                           args.update_fdt)
 524             for image in images.values():
 525                 ProcessImage(image, args.update_fdt, args.map)
 526
 527             # Write the updated FDTs to our output files
 528             for dtb_item in state.GetAllFdts():
 529                 tools.WriteFile(dtb_item._fname, dtb_item.GetContents())
 530
 531         finally:
 532             tools.FinaliseOutputDir()
 533     finally:
 534         tout.Uninit()
 535
 536     return 0