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 compress 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 -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))
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)
173 """The main control code for binman
175 This assumes that help and test options have already been dealt with. It
176 deals with the core task of building images.
179 args: Command line arguments Namespace object
184 pager = os.getenv('PAGER')
187 fname = os.path.join(os.path.dirname(os.path.realpath(sys.argv[0])),
189 command.Run(pager, fname)
193 ListEntries(args.image, args.paths)
196 if args.cmd == 'extract':
198 tools.PrepareOutputDir(None)
199 ExtractEntries(args.image, args.filename, args.outdir, args.paths,
200 not args.uncompressed)
202 tools.FinaliseOutputDir()
205 # Try to figure out which device tree contains our image description
211 raise ValueError('Must provide a board to process (use -b <board>)')
212 board_pathname = os.path.join(args.build_dir, board)
213 dtb_fname = os.path.join(board_pathname, 'u-boot.dtb')
216 args.indir.append(board_pathname)
219 # Import these here in case libfdt.py is not available, in which case
220 # the above help option still works.
224 tout.Init(args.verbosity)
225 elf.debug = args.debug
226 cbfs_util.VERBOSE = args.verbosity > 2
227 state.use_fake_dtb = args.fake_dtb
229 tools.SetInputDirs(args.indir)
230 tools.PrepareOutputDir(args.outdir, args.preserve)
231 tools.SetToolPaths(args.toolpath)
232 state.SetEntryArgs(args.entry_arg)
234 # Get the device tree ready by compiling it and copying the compiled
235 # output into a file in our output directly. Then scan it for use
237 dtb_fname = fdt_util.EnsureCompiled(dtb_fname)
238 fname = tools.GetOutputFilename('u-boot.dtb.out')
239 tools.WriteFile(fname, tools.ReadFile(dtb_fname))
240 dtb = fdt.FdtScan(fname)
242 node = _FindBinmanNode(dtb)
244 raise ValueError("Device tree '%s' does not have a 'binman' "
247 images = _ReadImageDesc(node)
251 new_images = OrderedDict()
252 for name, image in images.items():
253 if name in args.image:
254 new_images[name] = image
258 if skip and args.verbosity >= 2:
259 print('Skipping images: %s' % ', '.join(skip))
261 state.Prepare(images, dtb)
263 # Prepare the device tree by making sure that any missing
264 # properties are added (e.g. 'pos' and 'size'). The values of these
265 # may not be correct yet, but we add placeholders so that the
266 # size of the device tree is correct. Later, in
267 # SetCalculatedProperties() we will insert the correct values
268 # without changing the device-tree size, thus ensuring that our
269 # entry offsets remain the same.
270 for image in images.values():
271 image.ExpandEntries()
273 image.AddMissingProperties()
274 image.ProcessFdt(dtb)
276 for dtb_item in state.GetFdts():
277 dtb_item.Sync(auto_resize=True)
281 for image in images.values():
282 # Perform all steps for this image, including checking and
283 # writing it. This means that errors found with a later
284 # image will be reported after earlier images are already
285 # completed and written, but that does not seem important.
286 image.GetEntryContents()
287 image.GetEntryOffsets()
289 # We need to pack the entries to figure out where everything
290 # should be placed. This sets the offset/size of each entry.
291 # However, after packing we call ProcessEntryContents() which
292 # may result in an entry changing size. In that case we need to
293 # do another pass. Since the device tree often contains the
294 # final offset/size information we try to make space for this in
295 # AddMissingProperties() above. However, if the device is
296 # compressed we cannot know this compressed size in advance,
297 # since changing an offset from 0x100 to 0x104 (for example) can
298 # alter the compressed size of the device tree. So we need a
299 # third pass for this.
301 for pack_pass in range(passes):
306 except Exception as e:
308 fname = image.WriteMap()
309 print("Wrote map file '%s' to show errors" % fname)
313 image.SetCalculatedProperties()
314 for dtb_item in state.GetFdts():
316 sizes_ok = image.ProcessEntryContents()
321 image.Raise('Entries expanded after packing (tried %s passes)' %
329 # Write the updated FDTs to our output files
330 for dtb_item in state.GetFdts():
331 tools.WriteFile(dtb_item._fname, dtb_item.GetContents())
334 tools.FinaliseOutputDir()