1 # SPDX-License-Identifier: GPL-2.0+
2 # Copyright (c) 2016 Google, Inc
3 # Written by Simon Glass <sjg@chromium.org>
5 # Creates binary images from input files controlled by a description
8 from __future__ import print_function
10 from collections import OrderedDict
18 from image import Image
22 # List of images we plan to create
23 # Make this global so that it can be referenced from tests
24 images = OrderedDict()
26 def _ReadImageDesc(binman_node):
27 """Read the image descriptions from the /binman node
29 This normally produces a single Image object called 'image'. But if
30 multiple images are present, they will all be returned.
33 binman_node: Node object of the /binman node
35 OrderedDict of Image objects, each of which describes an image
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)
42 images['image'] = Image('image', binman_node)
45 def _FindBinmanNode(dtb):
46 """Find the 'binman' node in the device tree
49 dtb: Fdt object to scan
51 Node object of /binman node, or None if not found
53 for node in dtb.GetRoot().subnodes:
54 if node.name == 'binman':
58 def WriteEntryDocs(modules, test_missing=None):
59 """Write out documentation for all entries
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
67 from entry import Entry
68 Entry.WriteDocs(modules, test_missing)
71 def ListEntries(image_fname, entry_paths):
72 """List the entries in an image
74 This decodes the supplied image and displays a table of entries from that
75 image, preceded by a header.
78 image_fname: Image filename to process
79 entry_paths: List of wildcarded paths (e.g. ['*dtb*', 'u-boot*',
82 image = Image.FromFile(image_fname)
84 entries, lines, widths = image.GetListEntries(entry_paths)
86 num_columns = len(widths)
87 for linenum, line in enumerate(lines):
90 print('-' * (sum(widths) + num_columns * 2))
92 for i, item in enumerate(line):
94 if item.startswith('>'):
97 txt = '%*s ' % (width, item)
102 def ReadEntry(image_fname, entry_path, decomp=True):
103 """Extract an entry from an image
105 This extracts the data from a particular entry in an image
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
114 data extracted from the entry
116 image = Image.FromFile(image_fname)
117 entry = image.FindEntryPath(entry_path)
118 return entry.ReadData(decomp)
121 def ExtractEntries(image_fname, output_fname, outdir, entry_paths,
123 """Extract the data from one or more entries and write it to files
126 image_fname: Image filename to process
127 output_fname: Single output filename to use if extracting one file, None
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
134 List of EntryInfo records that were written
136 image = Image.FromFile(image_fname)
138 # Output an entry to a single file, as a special case
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))
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
153 einfos = image.GetListEntries(entry_paths)[0]
154 tout.Notice('%d entries match and will be written' % len(einfos))
157 data = entry.ReadData(decomp)
158 path = entry.GetPath()[1:]
159 fname = os.path.join(outdir, path)
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):
166 fname = os.path.join(fname, 'root')
167 tout.Notice("Write entry '%s' to '%s'" % (entry.GetPath(), fname))
168 tools.WriteFile(fname, data)
172 def BeforeReplace(image, allow_resize):
173 """Handle getting an image ready for replacing entries in it
176 image: Image to prepare
178 state.PrepareFromLoadedData(image)
181 # If repacking, drop the old offset/size values except for the original
182 # ones, so we are only left with the constraints.
187 def ReplaceOneEntry(image, entry, data, do_compress, allow_resize):
188 """Handle replacing a single entry an an image
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
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')
203 entry.Raise('Entry data size does not match, but resize is disabled')
206 def AfterReplace(image, allow_resize, write_map):
207 """Handle write out an image after replacing entries in it
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
215 tout.Info('Processing image')
216 ProcessImage(image, update_fdt=True, write_map=write_map,
217 get_contents=False, allow_resize=allow_resize)
220 def WriteEntryToImage(image, entry, data, do_compress=True, allow_resize=True,
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)
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
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.
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
246 Image object that was updated
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)
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
262 image_fname: Image filename to process
263 input_fname: Single input ilename to use if replacing one file, None
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
270 write_map: True to write a map file
273 List of EntryInfo records that were written
275 image = Image.FromFile(image_fname)
277 # Replace an entry from a single file, as a special case
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)
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
293 einfos = image.GetListEntries(entry_paths)[0]
294 tout.Notice("Replacing %d matching entries in image '%s'" %
295 (len(einfos), image_fname))
297 BeforeReplace(image, allow_resize)
301 if entry.GetEntries():
302 tout.Info("Skipping section entry '%s'" % entry.GetPath())
305 path = entry.GetPath()[1:]
306 fname = os.path.join(indir, path)
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)
314 tout.Warning("Skipping entry '%s' from missing file '%s'" %
315 (entry.GetPath(), fname))
317 AfterReplace(image, allow_resize=allow_resize, write_map=write_map)
321 def PrepareImagesAndDtbs(dtb_fname, select_images, update_fdt):
322 """Prepare the images to be processed and select the device tree
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,
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.
336 # Import these here in case libfdt.py is not available, in which case
337 # the above help option still works.
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
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)
350 node = _FindBinmanNode(dtb)
352 raise ValueError("Device tree '%s' does not have a 'binman' "
355 images = _ReadImageDesc(node)
359 new_images = OrderedDict()
360 for name, image in images.items():
361 if name in select_images:
362 new_images[name] = image
366 tout.Notice('Skipping images: %s' % ', '.join(skip))
368 state.Prepare(images, dtb)
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()
380 image.AddMissingProperties()
381 image.ProcessFdt(dtb)
383 for dtb_item in state.GetAllFdts():
384 dtb_item.Sync(auto_resize=True)
390 def ProcessImage(image, update_fdt, write_map, get_contents=True,
392 """Perform all steps for this image, including checking and # writing it.
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
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
408 image.GetEntryContents()
409 image.GetEntryOffsets()
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.
423 for pack_pass in range(passes):
428 except Exception as e:
430 fname = image.WriteMap()
431 print("Wrote map file '%s' to show errors" % fname)
435 image.SetCalculatedProperties()
436 for dtb_item in state.GetAllFdts():
439 sizes_ok = image.ProcessEntryContents()
444 image.Raise('Entries changed size after packing (tried %s passes)' %
454 """The main control code for binman
456 This assumes that help and test options have already been dealt with. It
457 deals with the core task of building images.
460 args: Command line arguments Namespace object
463 pager = os.getenv('PAGER')
466 fname = os.path.join(os.path.dirname(os.path.realpath(sys.argv[0])),
468 command.Run(pager, fname)
473 tools.PrepareOutputDir(None)
474 ListEntries(args.image, args.paths)
476 tools.FinaliseOutputDir()
479 if args.cmd == 'extract':
481 tools.PrepareOutputDir(None)
482 ExtractEntries(args.image, args.filename, args.outdir, args.paths,
483 not args.uncompressed)
485 tools.FinaliseOutputDir()
488 if args.cmd == 'replace':
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)
495 tools.FinaliseOutputDir()
498 # Try to figure out which device tree contains our image description
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')
509 args.indir.append(board_pathname)
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
517 tools.SetInputDirs(args.indir)
518 tools.PrepareOutputDir(args.outdir, args.preserve)
519 tools.SetToolPaths(args.toolpath)
520 state.SetEntryArgs(args.entry_arg)
522 images = PrepareImagesAndDtbs(dtb_fname, args.image,
524 for image in images.values():
525 ProcessImage(image, args.update_fdt, args.map)
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())
532 tools.FinaliseOutputDir()