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 compress 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 -o')
 142         if len(entry_paths) != 1:
 143             raise ValueError('Must specify exactly one entry path to write with -o')
 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 ProcessImage(image, update_fdt, write_map):
 173     """Perform all steps for this image, including checking and # writing it.
 174
 175     This means that errors found with a later image will be reported after
 176     earlier images are already completed and written, but that does not seem
 177     important.
 178
 179     Args:
 180         image: Image to process
 181         update_fdt: True to update the FDT wth entry offsets, etc.
 182         write_map: True to write a map file
 183     """
 184     image.GetEntryContents()
 185     image.GetEntryOffsets()
 186
 187     # We need to pack the entries to figure out where everything
 188     # should be placed. This sets the offset/size of each entry.
 189     # However, after packing we call ProcessEntryContents() which
 190     # may result in an entry changing size. In that case we need to
 191     # do another pass. Since the device tree often contains the
 192     # final offset/size information we try to make space for this in
 193     # AddMissingProperties() above. However, if the device is
 194     # compressed we cannot know this compressed size in advance,
 195     # since changing an offset from 0x100 to 0x104 (for example) can
 196     # alter the compressed size of the device tree. So we need a
 197     # third pass for this.
 198     passes = 3
 199     for pack_pass in range(passes):
 200         try:
 201             image.PackEntries()
 202             image.CheckSize()
 203             image.CheckEntries()
 204         except Exception as e:
 205             if write_map:
 206                 fname = image.WriteMap()
 207                 print("Wrote map file '%s' to show errors"  % fname)
 208             raise
 209         image.SetImagePos()
 210         if update_fdt:
 211             image.SetCalculatedProperties()
 212             for dtb_item in state.GetFdts():
 213                 dtb_item.Sync()
 214         sizes_ok = image.ProcessEntryContents()
 215         if sizes_ok:
 216             break
 217         image.ResetForPack()
 218     if not sizes_ok:
 219         image.Raise('Entries expanded after packing (tried %s passes)' %
 220                     passes)
 221
 222     image.WriteSymbols()
 223     image.BuildImage()
 224     if write_map:
 225         image.WriteMap()
 226
 227
 228 def Binman(args):
 229     """The main control code for binman
 230
 231     This assumes that help and test options have already been dealt with. It
 232     deals with the core task of building images.
 233
 234     Args:
 235         args: Command line arguments Namespace object
 236     """
 237     global images
 238
 239     if args.full_help:
 240         pager = os.getenv('PAGER')
 241         if not pager:
 242             pager = 'more'
 243         fname = os.path.join(os.path.dirname(os.path.realpath(sys.argv[0])),
 244                             'README')
 245         command.Run(pager, fname)
 246         return 0
 247
 248     if args.cmd == 'ls':
 249         ListEntries(args.image, args.paths)
 250         return 0
 251
 252     if args.cmd == 'extract':
 253         try:
 254             tools.PrepareOutputDir(None)
 255             ExtractEntries(args.image, args.filename, args.outdir, args.paths,
 256                            not args.uncompressed)
 257         finally:
 258             tools.FinaliseOutputDir()
 259         return 0
 260
 261     # Try to figure out which device tree contains our image description
 262     if args.dt:
 263         dtb_fname = args.dt
 264     else:
 265         board = args.board
 266         if not board:
 267             raise ValueError('Must provide a board to process (use -b <board>)')
 268         board_pathname = os.path.join(args.build_dir, board)
 269         dtb_fname = os.path.join(board_pathname, 'u-boot.dtb')
 270         if not args.indir:
 271             args.indir = ['.']
 272         args.indir.append(board_pathname)
 273
 274     try:
 275         # Import these here in case libfdt.py is not available, in which case
 276         # the above help option still works.
 277         import fdt
 278         import fdt_util
 279
 280         tout.Init(args.verbosity)
 281         elf.debug = args.debug
 282         cbfs_util.VERBOSE = args.verbosity > 2
 283         state.use_fake_dtb = args.fake_dtb
 284         try:
 285             tools.SetInputDirs(args.indir)
 286             tools.PrepareOutputDir(args.outdir, args.preserve)
 287             tools.SetToolPaths(args.toolpath)
 288             state.SetEntryArgs(args.entry_arg)
 289
 290             # Get the device tree ready by compiling it and copying the compiled
 291             # output into a file in our output directly. Then scan it for use
 292             # in binman.
 293             dtb_fname = fdt_util.EnsureCompiled(dtb_fname)
 294             fname = tools.GetOutputFilename('u-boot.dtb.out')
 295             tools.WriteFile(fname, tools.ReadFile(dtb_fname))
 296             dtb = fdt.FdtScan(fname)
 297
 298             node = _FindBinmanNode(dtb)
 299             if not node:
 300                 raise ValueError("Device tree '%s' does not have a 'binman' "
 301                                  "node" % dtb_fname)
 302
 303             images = _ReadImageDesc(node)
 304
 305             if args.image:
 306                 skip = []
 307                 new_images = OrderedDict()
 308                 for name, image in images.items():
 309                     if name in args.image:
 310                         new_images[name] = image
 311                     else:
 312                         skip.append(name)
 313                 images = new_images
 314                 if skip and args.verbosity >= 2:
 315                     print('Skipping images: %s' % ', '.join(skip))
 316
 317             state.Prepare(images, dtb)
 318
 319             # Prepare the device tree by making sure that any missing
 320             # properties are added (e.g. 'pos' and 'size'). The values of these
 321             # may not be correct yet, but we add placeholders so that the
 322             # size of the device tree is correct. Later, in
 323             # SetCalculatedProperties() we will insert the correct values
 324             # without changing the device-tree size, thus ensuring that our
 325             # entry offsets remain the same.
 326             for image in images.values():
 327                 image.ExpandEntries()
 328                 if args.update_fdt:
 329                     image.AddMissingProperties()
 330                 image.ProcessFdt(dtb)
 331
 332             for dtb_item in state.GetFdts():
 333                 dtb_item.Sync(auto_resize=True)
 334                 dtb_item.Pack()
 335                 dtb_item.Flush()
 336
 337             for image in images.values():
 338                 ProcessImage(image, args.update_fdt, args.map)
 339
 340             # Write the updated FDTs to our output files
 341             for dtb_item in state.GetFdts():
 342                 tools.WriteFile(dtb_item._fname, dtb_item.GetContents())
 343
 344         finally:
 345             tools.FinaliseOutputDir()
 346     finally:
 347         tout.Uninit()
 348
 349     return 0