Eric Lee / smarc-uboot | Embedian Git Server

Commit bf7fd50b3ba56b53dc13a681d19c845be903c3e0

Authored by Simon Glass 2016-11-26 11:15:51 +0800

Exists in v2017.01-smarct4x and in 25 other branches

binman: Introduce binman, a tool for building binary images

This adds the basic code for binman, including command parsing, processing
of entries and generation of images.

So far no entry types are supported. These will be added in future commits
as examples of how to add new types.

See the README for documentation.

Signed-off-by: Simon Glass <sjg@chromium.org>
Tested-by: Bin Meng <bmeng.cn@gmail.com>

Showing 9 changed files with 1255 additions and 0 deletions Side-by-side Diff

tools/binman/.gitignore
tools/binman/README
tools/binman/binman
tools/binman/binman.py
tools/binman/cmdline.py
tools/binman/control.py
tools/binman/etype/entry.py
tools/binman/fdt_test.py
tools/binman/image.py

tools/binman/.gitignore

Diff comments View file @ bf7fd50

+*.pyc

tools/binman/README

Diff comments View file @ bf7fd50

	1	+# Copyright (c) 2016 Google, Inc
	2	+#
	3	+# SPDX-License-Identifier: GPL-2.0+
	4	+#
	5	+
	6	+Introduction
	7	+------------
	8	+
	9	+Firmware often consists of several components which must be packaged together.
	10	+For example, we may have SPL, U-Boot, a device tree and an environment area
	11	+grouped together and placed in MMC flash. When the system starts, it must be
	12	+able to find these pieces.
	13	+
	14	+So far U-Boot has not provided a way to handle creating such images in a
	15	+general way. Each SoC does what it needs to build an image, often packing or
	16	+concatenating images in the U-Boot build system.
	17	+
	18	+Binman aims to provide a mechanism for building images, from simple
	19	+SPL + U-Boot combinations, to more complex arrangements with many parts.
	20	+
	21	+
	22	+What it does
	23	+------------
	24	+
	25	+Binman reads your board's device tree and finds a node which describes the
	26	+required image layout. It uses this to work out what to place where. The
	27	+output file normally contains the device tree, so it is in principle possible
	28	+to read an image and extract its constituent parts.
	29	+
	30	+
	31	+Features
	32	+--------
	33	+
	34	+So far binman is pretty simple. It supports binary blobs, such as 'u-boot',
	35	+'spl' and 'fdt'. It supports empty entries (such as setting to 0xff). It can
	36	+place entries at a fixed location in the image, or fit them together with
	37	+suitable padding and alignment. It provides a way to process binaries before
	38	+they are included, by adding a Python plug-in. The device tree is available
	39	+to U-Boot at run-time so that the images can be interpreted.
	40	+
	41	+Binman does not yet update the device tree with the final location of
	42	+everything when it is done. A simple C structure could be generated for
	43	+constrained environments like SPL (using dtoc) but this is also not
	44	+implemented.
	45	+
	46	+Binman can also support incorporating filesystems in the image if required.
	47	+For example x86 platforms may use CBFS in some cases.
	48	+
	49	+Binman is intended for use with U-Boot but is designed to be general enough
	50	+to be useful in other image-packaging situations.
	51	+
	52	+
	53	+Motivation
	54	+----------
	55	+
	56	+Packaging of firmware is quite a different task from building the various
	57	+parts. In many cases the various binaries which go into the image come from
	58	+separate build systems. For example, ARM Trusted Firmware is used on ARMv8
	59	+devices but is not built in the U-Boot tree. If a Linux kernel is included
	60	+in the firmware image, it is built elsewhere.
	61	+
	62	+It is of course possible to add more and more build rules to the U-Boot
	63	+build system to cover these cases. It can shell out to other Makefiles and
	64	+build scripts. But it seems better to create a clear divide between building
	65	+software and packaging it.
	66	+
	67	+At present this is handled by manual instructions, different for each board,
	68	+on how to create images that will boot. By turning these instructions into a
	69	+standard format, we can support making valid images for any board without
	70	+manual effort, lots of READMEs, etc.
	71	+
	72	+Benefits:
	73	+- Each binary can have its own build system and tool chain without creating
	74	+any dependencies between them
	75	+- Avoids the need for a single-shot build: individual parts can be updated
	76	+and brought in as needed
	77	+- Provides for a standard image description available in the build and at
	78	+run-time
	79	+- SoC-specific image-signing tools can be accomodated
	80	+- Avoids cluttering the U-Boot build system with image-building code
	81	+- The image description is automatically available at run-time in U-Boot,
	82	+SPL. It can be made available to other software also
	83	+- The image description is easily readable (it's a text file in device-tree
	84	+format) and permits flexible packing of binaries
	85	+
	86	+
	87	+Terminology
	88	+-----------
	89	+
	90	+Binman uses the following terms:
	91	+
	92	+- image - an output file containing a firmware image
	93	+- binary - an input binary that goes into the image
	94	+
	95	+
	96	+Relationship to FIT
	97	+-------------------
	98	+
	99	+FIT is U-Boot's official image format. It supports multiple binaries with
	100	+load / execution addresses, compression. It also supports verification
	101	+through hashing and RSA signatures.
	102	+
	103	+FIT was originally designed to support booting a Linux kernel (with an
	104	+optional ramdisk) and device tree chosen from various options in the FIT.
	105	+Now that U-Boot supports configuration via device tree, it is possible to
	106	+load U-Boot from a FIT, with the device tree chosen by SPL.
	107	+
	108	+Binman considers FIT to be one of the binaries it can place in the image.
	109	+
	110	+Where possible it is best to put as much as possible in the FIT, with binman
	111	+used to deal with cases not covered by FIT. Examples include initial
	112	+execution (since FIT itself does not have an executable header) and dealing
	113	+with device boundaries, such as the read-only/read-write separation in SPI
	114	+flash.
	115	+
	116	+For U-Boot, binman should not be used to create ad-hoc images in place of
	117	+FIT.
	118	+
	119	+
	120	+Relationship to mkimage
	121	+-----------------------
	122	+
	123	+The mkimage tool provides a means to create a FIT. Traditionally it has
	124	+needed an image description file: a device tree, like binman, but in a
	125	+different format. More recently it has started to support a '-f auto' mode
	126	+which can generate that automatically.
	127	+
	128	+More relevant to binman, mkimage also permits creation of many SoC-specific
	129	+image types. These can be listed by running 'mkimage -T list'. Examples
	130	+include 'rksd', the Rockchip SD/MMC boot format. The mkimage tool is often
	131	+called from the U-Boot build system for this reason.
	132	+
	133	+Binman considers the output files created by mkimage to be binary blobs
	134	+which it can place in an image. Binman does not replace the mkimage tool or
	135	+this purpose. It would be possible in some situtions to create a new entry
	136	+type for the images in mkimage, but this would not add functionality. It
	137	+seems better to use the mkiamge tool to generate binaries and avoid blurring
	138	+the boundaries between building input files (mkimage) and packaging then
	139	+into a final image (binman).
	140	+
	141	+
	142	+Example use of binman in U-Boot
	143	+-------------------------------
	144	+
	145	+Binman aims to replace some of the ad-hoc image creation in the U-Boot
	146	+build system.
	147	+
	148	+Consider sunxi. It has the following steps:
	149	+
	150	+1. It uses a custom mksunxiboot tool to build an SPL image called
	151	+sunxi-spl.bin. This should probably move into mkimage.
	152	+
	153	+2. It uses mkimage to package U-Boot into a legacy image file (so that it can
	154	+hold the load and execution address) called u-boot.img.
	155	+
	156	+3. It builds a final output image called u-boot-sunxi-with-spl.bin which
	157	+consists of sunxi-spl.bin, some padding and u-boot.img.
	158	+
	159	+Binman is intended to replace the last step. The U-Boot build system builds
	160	+u-boot.bin and sunxi-spl.bin. Binman can then take over creation of
	161	+sunxi-spl.bin (by calling mksunxiboot, or hopefully one day mkimage). In any
	162	+case, it would then create the image from the component parts.
	163	+
	164	+This simplifies the U-Boot Makefile somewhat, since various pieces of logic
	165	+can be replaced by a call to binman.
	166	+
	167	+
	168	+Example use of binman for x86
	169	+-----------------------------
	170	+
	171	+In most cases x86 images have a lot of binary blobs, 'black-box' code
	172	+provided by Intel which must be run for the platform to work. Typically
	173	+these blobs are not relocatable and must be placed at fixed areas in the
	174	+firmare image.
	175	+
	176	+Currently this is handled by ifdtool, which places microcode, FSP, MRC, VGA
	177	+BIOS, reference code and Intel ME binaries into a u-boot.rom file.
	178	+
	179	+Binman is intended to replace all of this, with ifdtool left to handle only
	180	+the configuration of the Intel-format descriptor.
	181	+
	182	+
	183	+Running binman
	184	+--------------
	185	+
	186	+Type:
	187	+
	188	+ binman -b <board_name>
	189	+
	190	+to build an image for a board. The board name is the same name used when
	191	+configuring U-Boot (e.g. for sandbox_defconfig the board name is 'sandbox').
	192	+Binman assumes that the input files for the build are in ../b/<board_name>.
	193	+
	194	+Or you can specify this explicitly:
	195	+
	196	+ binman -I <build_path>
	197	+
	198	+where <build_path> is the build directory containing the output of the U-Boot
	199	+build.
	200	+
	201	+(Future work will make this more configurable)
	202	+
	203	+In either case, binman picks up the device tree file (u-boot.dtb) and looks
	204	+for its instructions in the 'binman' node.
	205	+
	206	+Binman has a few other options which you can see by running 'binman -h'.
	207	+
	208	+
	209	+Image description format
	210	+------------------------
	211	+
	212	+The binman node is called 'binman'. An example image description is shown
	213	+below:
	214	+
	215	+ binman {
	216	+ filename = "u-boot-sunxi-with-spl.bin";
	217	+ pad-byte = <0xff>;
	218	+ blob {
	219	+ filename = "spl/sunxi-spl.bin";
	220	+ };
	221	+ u-boot {
	222	+ pos = <CONFIG_SPL_PAD_TO>;
	223	+ };
	224	+ };
	225	+
	226	+
	227	+This requests binman to create an image file called u-boot-sunxi-with-spl.bin
	228	+consisting of a specially formatted SPL (spl/sunxi-spl.bin, built by the
	229	+normal U-Boot Makefile), some 0xff padding, and a U-Boot legacy image. The
	230	+padding comes from the fact that the second binary is placed at
	231	+CONFIG_SPL_PAD_TO. If that line were omitted then the U-Boot binary would
	232	+immediately follow the SPL binary.
	233	+
	234	+The binman node describes an image. The sub-nodes describe entries in the
	235	+image. Each entry represents a region within the overall image. The name of
	236	+the entry (blob, u-boot) tells binman what to put there. For 'blob' we must
	237	+provide a filename. For 'u-boot', binman knows that this means 'u-boot.bin'.
	238	+
	239	+Entries are normally placed into the image sequentially, one after the other.
	240	+The image size is the total size of all entries. As you can see, you can
	241	+specify the start position of an entry using the 'pos' property.
	242	+
	243	+Note that due to a device tree requirement, all entries must have a unique
	244	+name. If you want to put the same binary in the image multiple times, you can
	245	+use any unique name, with the 'type' property providing the type.
	246	+
	247	+The attributes supported for entries are described below.
	248	+
	249	+pos:
	250	+ This sets the position of an entry within the image. The first byte
	251	+ of the image is normally at position 0. If 'pos' is not provided,
	252	+ binman sets it to the end of the previous region, or the start of
	253	+ the image's entry area (normally 0) if there is no previous region.
	254	+
	255	+align:
	256	+ This sets the alignment of the entry. The entry position is adjusted
	257	+ so that the entry starts on an aligned boundary within the image. For
	258	+ example 'align = <16>' means that the entry will start on a 16-byte
	259	+ boundary. Alignment shold be a power of 2. If 'align' is not
	260	+ provided, no alignment is performed.
	261	+
	262	+size:
	263	+ This sets the size of the entry. The contents will be padded out to
	264	+ this size. If this is not provided, it will be set to the size of the
	265	+ contents.
	266	+
	267	+pad-before:
	268	+ Padding before the contents of the entry. Normally this is 0, meaning
	269	+ that the contents start at the beginning of the entry. This can be
	270	+ offset the entry contents a little. Defaults to 0.
	271	+
	272	+pad-after:
	273	+ Padding after the contents of the entry. Normally this is 0, meaning
	274	+ that the entry ends at the last byte of content (unless adjusted by
	275	+ other properties). This allows room to be created in the image for
	276	+ this entry to expand later. Defaults to 0.
	277	+
	278	+align-size:
	279	+ This sets the alignment of the entry size. For example, to ensure
	280	+ that the size of an entry is a multiple of 64 bytes, set this to 64.
	281	+ If 'align-size' is not provided, no alignment is performed.
	282	+
	283	+align-end:
	284	+ This sets the alignment of the end of an entry. Some entries require
	285	+ that they end on an alignment boundary, regardless of where they
	286	+ start. If 'align-end' is not provided, no alignment is performed.
	287	+
	288	+ Note: This is not yet implemented in binman.
	289	+
	290	+filename:
	291	+ For 'blob' types this provides the filename containing the binary to
	292	+ put into the entry. If binman knows about the entry type (like
	293	+ u-boot-bin), then there is no need to specify this.
	294	+
	295	+type:
	296	+ Sets the type of an entry. This defaults to the entry name, but it is
	297	+ possible to use any name, and then add (for example) 'type = "u-boot"'
	298	+ to specify the type.
	299	+
	300	+
	301	+The attributes supported for images are described below. Several are similar
	302	+to those for entries.
	303	+
	304	+size:
	305	+ Sets the image size in bytes, for example 'size = <0x100000>' for a
	306	+ 1MB image.
	307	+
	308	+align-size:
	309	+ This sets the alignment of the image size. For example, to ensure
	310	+ that the image ends on a 512-byte boundary, use 'align-size = <512>'.
	311	+ If 'align-size' is not provided, no alignment is performed.
	312	+
	313	+pad-before:
	314	+ This sets the padding before the image entries. The first entry will
	315	+ be positionad after the padding. This defaults to 0.
	316	+
	317	+pad-after:
	318	+ This sets the padding after the image entries. The padding will be
	319	+ placed after the last entry. This defaults to 0.
	320	+
	321	+pad-byte:
	322	+ This specifies the pad byte to use when padding in the image. It
	323	+ defaults to 0. To use 0xff, you would add 'pad-byte = <0xff>'.
	324	+
	325	+filename:
	326	+ This specifies the image filename. It defaults to 'image.bin'.
	327	+
	328	+sort-by-pos:
	329	+ This causes binman to reorder the entries as needed to make sure they
	330	+ are in increasing positional order. This can be used when your entry
	331	+ order may not match the positional order. A common situation is where
	332	+ the 'pos' properties are set by CONFIG options, so their ordering is
	333	+ not known a priori.
	334	+
	335	+ This is a boolean property so needs no value. To enable it, add a
	336	+ line 'sort-by-pos;' to your description.
	337	+
	338	+multiple-images:
	339	+ Normally only a single image is generated. To create more than one
	340	+ image, put this property in the binman node. For example, this will
	341	+ create image1.bin containing u-boot.bin, and image2.bin containing
	342	+ both spl/u-boot-spl.bin and u-boot.bin:
	343	+
	344	+ binman {
	345	+ multiple-images;
	346	+ image1 {
	347	+ u-boot {
	348	+ };
	349	+ };
	350	+
	351	+ image2 {
	352	+ spl {
	353	+ };
	354	+ u-boot {
	355	+ };
	356	+ };
	357	+ };
	358	+
	359	+end-at-4gb:
	360	+ For x86 machines the ROM positions start just before 4GB and extend
	361	+ up so that the image finished at the 4GB boundary. This boolean
	362	+ option can be enabled to support this. The image size must be
	363	+ provided so that binman knows when the image should start. For an
	364	+ 8MB ROM, the position of the first entry would be 0xfff80000 with
	365	+ this option, instead of 0 without this option.
	366	+
	367	+
	368	+Examples of the above options can be found in the tests. See the
	369	+tools/binman/test directory.
	370	+
	371	+
	372	+Order of image creation
	373	+-----------------------
	374	+
	375	+Image creation proceeds in the following order, for each entry in the image.
	376	+
	377	+1. GetEntryContents() - the contents of each entry are obtained, normally by
	378	+reading from a file. This calls the Entry.ObtainContents() to read the
	379	+contents. The default version of Entry.ObtainContents() calls
	380	+Entry.GetDefaultFilename() and then reads that file. So a common mechanism
	381	+to select a file to read is to override that function in the subclass. The
	382	+functions must return True when they have read the contents. Binman will
	383	+retry calling the functions a few times if False is returned, allowing
	384	+dependencies between the contents of different entries.
	385	+
	386	+2. GetEntryPositions() - calls Entry.GetPositions() for each entry. This can
	387	+return a dict containing entries that need updating. The key should be the
	388	+entry name and the value is a tuple (pos, size). This allows an entry to
	389	+provide the position and size for other entries. The default implementation
	390	+of GetEntryPositions() returns {}.
	391	+
	392	+3. PackEntries() - calls Entry.Pack() which figures out the position and
	393	+size of an entry. The 'current' image position is passed in, and the function
	394	+returns the position immediately after the entry being packed. The default
	395	+implementation of Pack() is usually sufficient.
	396	+
	397	+4. CheckSize() - checks that the contents of all the entries fits within
	398	+the image size. If the image does not have a defined size, the size is set
	399	+large enough to hold all the entries.
	400	+
	401	+5. CheckEntries() - checks that the entries do not overlap, nor extend
	402	+outside the image.
	403	+
	404	+6. ProcessEntryContents() - this calls Entry.ProcessContents() on each entry.
	405	+The default implementatoin does nothing. This can be overriden to adjust the
	406	+contents of an entry in some way. For example, it would be possible to create
	407	+an entry containing a hash of the contents of some other entries. At this
	408	+stage the position and size of entries should not be adjusted.
	409	+
	410	+7. BuildImage() - builds the image and writes it to a file. This is the final
	411	+step.
	412	+
	413	+
	414	+Advanced Features / Technical docs
	415	+----------------------------------
	416	+
	417	+The behaviour of entries is defined by the Entry class. All other entries are
	418	+a subclass of this. An important subclass is Entry_blob which takes binary
	419	+data from a file and places it in the entry. In fact most entry types are
	420	+subclasses of Entry_blob.
	421	+
	422	+Each entry type is a separate file in the tools/binman/etype directory. Each
	423	+file contains a class called Entry_<type> where <type> is the entry type.
	424	+New entry types can be supported by adding new files in that directory.
	425	+These will automatically be detected by binman when needed.
	426	+
	427	+Entry properties are documented in entry.py. The entry subclasses are free
	428	+to change the values of properties to support special behaviour. For example,
	429	+when Entry_blob loads a file, it sets content_size to the size of the file.
	430	+Entry classes can adjust other entries. For example, an entry that knows
	431	+where other entries should be positioned can set up those entries' positions
	432	+so they don't need to be set in the binman decription. It can also adjust
	433	+entry contents.
	434	+
	435	+Most of the time such essoteric behaviour is not needed, but it can be
	436	+essential for complex images.
	437	+
	438	+
	439	+History / Credits
	440	+-----------------
	441	+
	442	+Binman takes a lot of inspiration from a Chrome OS tool called
	443	+'cros_bundle_firmware', which I wrote some years ago. That tool was based on
	444	+a reasonably simple and sound design but has expanded greatly over the
	445	+years. In particular its handling of x86 images is convoluted.
	446	+
	447	+Quite a few lessons have been learned which are hopefully be applied here.
	448	+
	449	+
	450	+Design notes
	451	+------------
	452	+
	453	+On the face of it, a tool to create firmware images should be fairly simple:
	454	+just find all the input binaries and place them at the right place in the
	455	+image. The difficulty comes from the wide variety of input types (simple
	456	+flat binaries containing code, packaged data with various headers), packing
	457	+requirments (alignment, spacing, device boundaries) and other required
	458	+features such as hierarchical images.
	459	+
	460	+The design challenge is to make it easy to create simple images, while
	461	+allowing the more complex cases to be supported. For example, for most
	462	+images we don't much care exactly where each binary ends up, so we should
	463	+not have to specify that unnecessarily.
	464	+
	465	+New entry types should aim to provide simple usage where possible. If new
	466	+core features are needed, they can be added in the Entry base class.
	467	+
	468	+
	469	+To do
	470	+-----
	471	+
	472	+Some ideas:
	473	+- Fill out the device tree to include the final position and size of each
	474	+ entry (since the input file may not always specify these)
	475	+- Use of-platdata to make the information available to code that is unable
	476	+ to use device tree (such as a very small SPL image)
	477	+- Write an image map to a text file
	478	+- Allow easy building of images by specifying just the board name
	479	+- Produce a full Python binding for libfdt (for upstream)
	480	+- Add an option to decode an image into the constituent binaries
	481	+- Suppoort hierarchical images (packing of binaries into another binary
	482	+ which is then placed in the image)
	483	+- Support building an image for a board (-b) more completely, with a
	484	+ configurable build directory
	485	+- Consider making binman work with buildman, although if it is used in the
	486	+ Makefile, this will be automatic
	487	+- Implement align-end
	488	+
	489	+--
	490	+Simon Glass <sjg@chromium.org>
	491	+7/7/2016

tools/binman/binman

Diff comments View file @ bf7fd50

+binman.py

tools/binman/binman.py

Diff comments View file @ bf7fd50

	1	+#!/usr/bin/python
	2	+
	3	+# Copyright (c) 2016 Google, Inc
	4	+# Written by Simon Glass <sjg@chromium.org>
	5	+#
	6	+# SPDX-License-Identifier: GPL-2.0+
	7	+#
	8	+# Creates binary images from input files controlled by a description
	9	+#
	10	+
	11	+"""See README for more information"""
	12	+
	13	+import os
	14	+import sys
	15	+import traceback
	16	+import unittest
	17	+
	18	+# Bring in the patman and dtoc libraries
	19	+our_path = os.path.dirname(os.path.realpath(__file__))
	20	+sys.path.append(os.path.join(our_path, '../patman'))
	21	+sys.path.append(os.path.join(our_path, '../dtoc'))
	22	+
	23	+# Also allow entry-type modules to be brought in from the etype directory.
	24	+sys.path.append(os.path.join(our_path, 'etype'))
	25	+
	26	+import cmdline
	27	+import command
	28	+import control
	29	+
	30	+def RunTests():
	31	+ """Run the functional tests and any embedded doctests"""
	32	+ import entry_test
	33	+ import fdt_test
	34	+ import func_test
	35	+ import test
	36	+ import doctest
	37	+
	38	+ result = unittest.TestResult()
	39	+ for module in []:
	40	+ suite = doctest.DocTestSuite(module)
	41	+ suite.run(result)
	42	+
	43	+ sys.argv = [sys.argv[0]]
	44	+ for module in (func_test.TestFunctional, fdt_test.TestFdt,
	45	+ entry_test.TestEntry):
	46	+ suite = unittest.TestLoader().loadTestsFromTestCase(module)
	47	+ suite.run(result)
	48	+
	49	+ print result
	50	+ for test, err in result.errors:
	51	+ print test.id(), err
	52	+ for test, err in result.failures:
	53	+ print err
	54	+
	55	+def RunTestCoverage():
	56	+ """Run the tests and check that we get 100% coverage"""
	57	+ # This uses the build output from sandbox_spl to get _libfdt.so
	58	+ cmd = ('PYTHONPATH=%s/sandbox_spl/tools coverage run '
	59	+ '--include "tools/binman/.py" --omit "test,binman.py" '
	60	+ 'tools/binman/binman.py -t' % options.build_dir)
	61	+ os.system(cmd)
	62	+ stdout = command.Output('coverage', 'report')
	63	+ coverage = stdout.splitlines()[-1].split(' ')[-1]
	64	+ if coverage != '100%':
	65	+ print stdout
	66	+ print "Type 'coverage html' to get a report in htmlcov/index.html"
	67	+ raise ValueError('Coverage error: %s, but should be 100%%' % coverage)
	68	+
	69	+
	70	+def RunBinman(options, args):
	71	+ """Main entry point to binman once arguments are parsed
	72	+
	73	+ Args:
	74	+ options: Command-line options
	75	+ args: Non-option arguments
	76	+ """
	77	+ ret_code = 0
	78	+
	79	+ # For testing: This enables full exception traces.
	80	+ #options.debug = True
	81	+
	82	+ if not options.debug:
	83	+ sys.tracebacklimit = 0
	84	+
	85	+ if options.test:
	86	+ RunTests()
	87	+
	88	+ elif options.test_coverage:
	89	+ RunTestCoverage()
	90	+
	91	+ elif options.full_help:
	92	+ pager = os.getenv('PAGER')
	93	+ if not pager:
	94	+ pager = 'more'
	95	+ fname = os.path.join(os.path.dirname(os.path.realpath(sys.argv[0])),
	96	+ 'README')
	97	+ command.Run(pager, fname)
	98	+
	99	+ else:
	100	+ try:
	101	+ ret_code = control.Binman(options, args)
	102	+ except Exception as e:
	103	+ print 'binman: %s' % e
	104	+ if options.debug:
	105	+ print
	106	+ traceback.print_exc()
	107	+ ret_code = 1
	108	+ return ret_code
	109	+
	110	+
	111	+if __name__ == "__main__":
	112	+ (options, args) = cmdline.ParseArgs(sys.argv)
	113	+ ret_code = RunBinman(options, args)
	114	+ sys.exit(ret_code)

tools/binman/cmdline.py

Diff comments View file @ bf7fd50

	1	+# Copyright (c) 2016 Google, Inc
	2	+# Written by Simon Glass <sjg@chromium.org>
	3	+#
	4	+# SPDX-License-Identifier: GPL-2.0+
	5	+#
	6	+# Command-line parser for binman
	7	+#
	8	+
	9	+from optparse import OptionParser
	10	+
	11	+def ParseArgs(argv):
	12	+ """Parse the binman command-line arguments
	13	+
	14	+ Args:
	15	+ argv: List of string arguments
	16	+ Returns:
	17	+ Tuple (options, args) with the command-line options and arugments.
	18	+ options provides access to the options (e.g. option.debug)
	19	+ args is a list of string arguments
	20	+ """
	21	+ parser = OptionParser()
	22	+ parser.add_option('-b', '--board', type='string',
	23	+ help='Board name to build')
	24	+ parser.add_option('-B', '--build-dir', type='string', default='b',
	25	+ help='Directory containing the build output')
	26	+ parser.add_option('-d', '--dt', type='string',
	27	+ help='Configuration file (.dtb) to use')
	28	+ parser.add_option('-D', '--debug', action='store_true',
	29	+ help='Enabling debugging (provides a full traceback on error)')
	30	+ parser.add_option('-I', '--indir', action='append',
	31	+ help='Add a path to a directory to use for input files')
	32	+ parser.add_option('-H', '--full-help', action='store_true',
	33	+ default=False, help='Display the README file')
	34	+ parser.add_option('-O', '--outdir', type='string',
	35	+ action='store', help='Path to directory to use for intermediate and '
	36	+ 'output files')
	37	+ parser.add_option('-p', '--preserve', action='store_true',\
	38	+ help='Preserve temporary output directory even if option -O is not '
	39	+ 'given')
	40	+ parser.add_option('-t', '--test', action='store_true',
	41	+ default=False, help='run tests')
	42	+ parser.add_option('-T', '--test-coverage', action='store_true',
	43	+ default=False, help='run tests and check for 100% coverage')
	44	+ parser.add_option('-v', '--verbosity', default=1,
	45	+ type='int', help='Control verbosity: 0=silent, 1=progress, 3=full, '
	46	+ '4=debug')
	47	+
	48	+ parser.usage += """
	49	+
	50	+Create images for a board from a set of binaries. It is controlled by a
	51	+description in the board device tree."""
	52	+
	53	+ return parser.parse_args(argv)

tools/binman/control.py

Diff comments View file @ bf7fd50

	1	+# Copyright (c) 2016 Google, Inc
	2	+# Written by Simon Glass <sjg@chromium.org>
	3	+#
	4	+# SPDX-License-Identifier: GPL-2.0+
	5	+#
	6	+# Creates binary images from input files controlled by a description
	7	+#
	8	+
	9	+from collections import OrderedDict
	10	+import os
	11	+import sys
	12	+import tools
	13	+
	14	+import command
	15	+import fdt_select
	16	+import fdt_util
	17	+from image import Image
	18	+import tout
	19	+
	20	+# List of images we plan to create
	21	+# Make this global so that it can be referenced from tests
	22	+images = OrderedDict()
	23	+
	24	+def _ReadImageDesc(binman_node):
	25	+ """Read the image descriptions from the /binman node
	26	+
	27	+ This normally produces a single Image object called 'image'. But if
	28	+ multiple images are present, they will all be returned.
	29	+
	30	+ Args:
	31	+ binman_node: Node object of the /binman node
	32	+ Returns:
	33	+ OrderedDict of Image objects, each of which describes an image
	34	+ """
	35	+ images = OrderedDict()
	36	+ if 'multiple-images' in binman_node.props:
	37	+ for node in binman_node.subnodes:
	38	+ images[node.name] = Image(node.name, node)
	39	+ else:
	40	+ images['image'] = Image('image', binman_node)
	41	+ return images
	42	+
	43	+def _FindBinmanNode(fdt):
	44	+ """Find the 'binman' node in the device tree
	45	+
	46	+ Args:
	47	+ fdt: Fdt object to scan
	48	+ Returns:
	49	+ Node object of /binman node, or None if not found
	50	+ """
	51	+ for node in fdt.GetRoot().subnodes:
	52	+ if node.name == 'binman':
	53	+ return node
	54	+ return None
	55	+
	56	+def Binman(options, args):
	57	+ """The main control code for binman
	58	+
	59	+ This assumes that help and test options have already been dealt with. It
	60	+ deals with the core task of building images.
	61	+
	62	+ Args:
	63	+ options: Command line options object
	64	+ args: Command line arguments (list of strings)
	65	+ """
	66	+ global images
	67	+
	68	+ if options.full_help:
	69	+ pager = os.getenv('PAGER')
	70	+ if not pager:
	71	+ pager = 'more'
	72	+ fname = os.path.join(os.path.dirname(os.path.realpath(sys.argv[0])),
	73	+ 'README')
	74	+ command.Run(pager, fname)
	75	+ return 0
	76	+
	77	+ # Try to figure out which device tree contains our image description
	78	+ if options.dt:
	79	+ dtb_fname = options.dt
	80	+ else:
	81	+ board = options.board
	82	+ if not board:
	83	+ raise ValueError('Must provide a board to process (use -b <board>)')
	84	+ board_pathname = os.path.join(options.build_dir, board)
	85	+ dtb_fname = os.path.join(board_pathname, 'u-boot.dtb')
	86	+ if not options.indir:
	87	+ options.indir = ['.']
	88	+ options.indir.append(board_pathname)
	89	+
	90	+ try:
	91	+ tout.Init(options.verbosity)
	92	+ try:
	93	+ tools.SetInputDirs(options.indir)
	94	+ tools.PrepareOutputDir(options.outdir, options.preserve)
	95	+ fdt = fdt_select.FdtScan(dtb_fname)
	96	+ node = _FindBinmanNode(fdt)
	97	+ if not node:
	98	+ raise ValueError("Device tree '%s' does not have a 'binman' "
	99	+ "node" % dtb_fname)
	100	+ images = _ReadImageDesc(node)
	101	+ for image in images.values():
	102	+ # Perform all steps for this image, including checking and
	103	+ # writing it. This means that errors found with a later
	104	+ # image will be reported after earlier images are already
	105	+ # completed and written, but that does not seem important.
	106	+ image.GetEntryContents()
	107	+ image.GetEntryPositions()
	108	+ image.PackEntries()
	109	+ image.CheckSize()
	110	+ image.CheckEntries()
	111	+ image.ProcessEntryContents()
	112	+ image.BuildImage()
	113	+ finally:
	114	+ tools.FinaliseOutputDir()
	115	+ finally:
	116	+ tout.Uninit()
	117	+
	118	+ return 0

tools/binman/etype/entry.py

Diff comments View file @ bf7fd50

	1	+# Copyright (c) 2016 Google, Inc
	2	+#
	3	+# SPDX-License-Identifier: GPL-2.0+
	4	+#
	5	+# Base class for all entries
	6	+#
	7	+
	8	+# importlib was introduced in Python 2.7 but there was a report of it not
	9	+# working in 2.7.12, so we work around this:
	10	+# http://lists.denx.de/pipermail/u-boot/2016-October/269729.html
	11	+try:
	12	+ import importlib
	13	+ have_importlib = True
	14	+except:
	15	+ have_importlib = False
	16	+
	17	+import fdt_util
	18	+import tools
	19	+
	20	+modules = {}
	21	+
	22	+class Entry(object):
	23	+ """An Entry in the image
	24	+
	25	+ An entry corresponds to a single node in the device-tree description
	26	+ of the image. Each entry ends up being a part of the final image.
	27	+ Entries can be placed either right next to each other, or with padding
	28	+ between them. The type of the entry determines the data that is in it.
	29	+
	30	+ This class is not used by itself. All entry objects are subclasses of
	31	+ Entry.
	32	+
	33	+ Attributes:
	34	+ image: The image containing this entry
	35	+ node: The node that created this entry
	36	+ pos: Absolute position of entry within the image, None if not known
	37	+ size: Entry size in bytes, None if not known
	38	+ contents_size: Size of contents in bytes, 0 by default
	39	+ align: Entry start position alignment, or None
	40	+ align_size: Entry size alignment, or None
	41	+ align_end: Entry end position alignment, or None
	42	+ pad_before: Number of pad bytes before the contents, 0 if none
	43	+ pad_after: Number of pad bytes after the contents, 0 if none
	44	+ data: Contents of entry (string of bytes)
	45	+ """
	46	+ def __init__(self, image, etype, node, read_node=True):
	47	+ self.image = image
	48	+ self.etype = etype
	49	+ self._node = node
	50	+ self.pos = None
	51	+ self.size = None
	52	+ self.contents_size = 0
	53	+ self.align = None
	54	+ self.align_size = None
	55	+ self.align_end = None
	56	+ self.pad_before = 0
	57	+ self.pad_after = 0
	58	+ self.pos_unset = False
	59	+ if read_node:
	60	+ self.ReadNode()
	61	+
	62	+ @staticmethod
	63	+ def Create(image, node, etype=None):
	64	+ """Create a new entry for a node.
	65	+
	66	+ Args:
	67	+ image: Image object containing this node
	68	+ node: Node object containing information about the entry to create
	69	+ etype: Entry type to use, or None to work it out (used for tests)
	70	+
	71	+ Returns:
	72	+ A new Entry object of the correct type (a subclass of Entry)
	73	+ """
	74	+ if not etype:
	75	+ etype = fdt_util.GetString(node, 'type', node.name)
	76	+ module_name = etype.replace('-', '_')
	77	+ module = modules.get(module_name)
	78	+
	79	+ # Import the module if we have not already done so.
	80	+ if not module:
	81	+ try:
	82	+ if have_importlib:
	83	+ module = importlib.import_module(module_name)
	84	+ else:
	85	+ module = __import__(module_name)
	86	+ except ImportError:
	87	+ raise ValueError("Unknown entry type '%s' in node '%s'" %
	88	+ (etype, node.path))
	89	+ modules[module_name] = module
	90	+
	91	+ # Call its constructor to get the object we want.
	92	+ obj = getattr(module, 'Entry_%s' % module_name)
	93	+ return obj(image, etype, node)
	94	+
	95	+ def ReadNode(self):
	96	+ """Read entry information from the node
	97	+
	98	+ This reads all the fields we recognise from the node, ready for use.
	99	+ """
	100	+ self.pos = fdt_util.GetInt(self._node, 'pos')
	101	+ self.size = fdt_util.GetInt(self._node, 'size')
	102	+ self.align = fdt_util.GetInt(self._node, 'align')
	103	+ if tools.NotPowerOfTwo(self.align):
	104	+ raise ValueError("Node '%s': Alignment %s must be a power of two" %
	105	+ (self._node.path, self.align))
	106	+ self.pad_before = fdt_util.GetInt(self._node, 'pad-before', 0)
	107	+ self.pad_after = fdt_util.GetInt(self._node, 'pad-after', 0)
	108	+ self.align_size = fdt_util.GetInt(self._node, 'align-size')
	109	+ if tools.NotPowerOfTwo(self.align_size):
	110	+ raise ValueError("Node '%s': Alignment size %s must be a power "
	111	+ "of two" % (self._node.path, self.align_size))
	112	+ self.align_end = fdt_util.GetInt(self._node, 'align-end')
	113	+ self.pos_unset = fdt_util.GetBool(self._node, 'pos-unset')
	114	+
	115	+ def ObtainContents(self):
	116	+ """Figure out the contents of an entry.
	117	+
	118	+ Returns:
	119	+ True if the contents were found, False if another call is needed
	120	+ after the other entries are processed.
	121	+ """
	122	+ # No contents by default: subclasses can implement this
	123	+ return True
	124	+
	125	+ def Pack(self, pos):
	126	+ """Figure out how to pack the entry into the image
	127	+
	128	+ Most of the time the entries are not fully specified. There may be
	129	+ an alignment but no size. In that case we take the size from the
	130	+ contents of the entry.
	131	+
	132	+ If an entry has no hard-coded position, it will be placed at @pos.
	133	+
	134	+ Once this function is complete, both the position and size of the
	135	+ entry will be know.
	136	+
	137	+ Args:
	138	+ Current image position pointer
	139	+
	140	+ Returns:
	141	+ New image position pointer (after this entry)
	142	+ """
	143	+ if self.pos is None:
	144	+ if self.pos_unset:
	145	+ self.Raise('No position set with pos-unset: should another '
	146	+ 'entry provide this correct position?')
	147	+ self.pos = tools.Align(pos, self.align)
	148	+ needed = self.pad_before + self.contents_size + self.pad_after
	149	+ needed = tools.Align(needed, self.align_size)
	150	+ size = self.size
	151	+ if not size:
	152	+ size = needed
	153	+ new_pos = self.pos + size
	154	+ aligned_pos = tools.Align(new_pos, self.align_end)
	155	+ if aligned_pos != new_pos:
	156	+ size = aligned_pos - self.pos
	157	+ new_pos = aligned_pos
	158	+
	159	+ if not self.size:
	160	+ self.size = size
	161	+
	162	+ if self.size < needed:
	163	+ self.Raise("Entry contents size is %#x (%d) but entry size is "
	164	+ "%#x (%d)" % (needed, needed, self.size, self.size))
	165	+ # Check that the alignment is correct. It could be wrong if the
	166	+ # and pos or size values were provided (i.e. not calculated), but
	167	+ # conflict with the provided alignment values
	168	+ if self.size != tools.Align(self.size, self.align_size):
	169	+ self.Raise("Size %#x (%d) does not match align-size %#x (%d)" %
	170	+ (self.size, self.size, self.align_size, self.align_size))
	171	+ if self.pos != tools.Align(self.pos, self.align):
	172	+ self.Raise("Position %#x (%d) does not match align %#x (%d)" %
	173	+ (self.pos, self.pos, self.align, self.align))
	174	+
	175	+ return new_pos
	176	+
	177	+ def Raise(self, msg):
	178	+ """Convenience function to raise an error referencing a node"""
	179	+ raise ValueError("Node '%s': %s" % (self._node.path, msg))
	180	+
	181	+ def GetPath(self):
	182	+ """Get the path of a node
	183	+
	184	+ Returns:
	185	+ Full path of the node for this entry
	186	+ """
	187	+ return self._node.path
	188	+
	189	+ def GetData(self):
	190	+ return self.data
	191	+
	192	+ def GetPositions(self):
	193	+ return {}
	194	+
	195	+ def SetPositionSize(self, pos, size):
	196	+ self.pos = pos
	197	+ self.size = size
	198	+
	199	+ def ProcessContents(self):
	200	+ pass

tools/binman/fdt_test.py

Diff comments View file @ bf7fd50

	1	+#
	2	+# Copyright (c) 2016 Google, Inc
	3	+# Written by Simon Glass <sjg@chromium.org>
	4	+#
	5	+# SPDX-License-Identifier: GPL-2.0+
	6	+#
	7	+# Test for the fdt modules
	8	+
	9	+import os
	10	+import sys
	11	+import tempfile
	12	+import unittest
	13	+
	14	+from fdt_select import FdtScan
	15	+import fdt_util
	16	+import tools
	17	+
	18	+class TestFdt(unittest.TestCase):
	19	+ @classmethod
	20	+ def setUpClass(self):
	21	+ self._binman_dir = os.path.dirname(os.path.realpath(sys.argv[0]))
	22	+ self._indir = tempfile.mkdtemp(prefix='binmant.')
	23	+ tools.PrepareOutputDir(self._indir, True)
	24	+
	25	+ def TestFile(self, fname):
	26	+ return os.path.join(self._binman_dir, 'test', fname)
	27	+
	28	+ def GetCompiled(self, fname):
	29	+ return fdt_util.EnsureCompiled(self.TestFile(fname))
	30	+
	31	+ def _DeleteProp(self, fdt):
	32	+ node = fdt.GetNode('/microcode/update@0')
	33	+ node.DeleteProp('data')
	34	+
	35	+ def testFdtNormal(self):
	36	+ fname = self.GetCompiled('34_x86_ucode.dts')
	37	+ fdt = FdtScan(fname)
	38	+ self._DeleteProp(fdt)
	39	+
	40	+ def testFdtFallback(self):
	41	+ fname = self.GetCompiled('34_x86_ucode.dts')
	42	+ fdt = FdtScan(fname, True)
	43	+ fdt.GetProp('/microcode/update@0', 'data')
	44	+ self.assertEqual('fred',
	45	+ fdt.GetProp('/microcode/update@0', 'none', default='fred'))
	46	+ self.assertEqual('12345678 12345679',
	47	+ fdt.GetProp('/microcode/update@0', 'data', typespec='x'))
	48	+ self._DeleteProp(fdt)

tools/binman/image.py

Diff comments View file @ bf7fd50

	1	+# Copyright (c) 2016 Google, Inc
	2	+# Written by Simon Glass <sjg@chromium.org>
	3	+#
	4	+# SPDX-License-Identifier: GPL-2.0+
	5	+#
	6	+# Class for an image, the output of binman
	7	+#
	8	+
	9	+from collections import OrderedDict
	10	+from operator import attrgetter
	11	+
	12	+import entry
	13	+from entry import Entry
	14	+import fdt_util
	15	+import tools
	16	+
	17	+class Image:
	18	+ """A Image, representing an output from binman
	19	+
	20	+ An image is comprised of a collection of entries each containing binary
	21	+ data. The image size must be large enough to hold all of this data.
	22	+
	23	+ This class implements the various operations needed for images.
	24	+
	25	+ Atrtributes:
	26	+ _node: Node object that contains the image definition in device tree
	27	+ _name: Image name
	28	+ _size: Image size in bytes, or None if not known yet
	29	+ _align_size: Image size alignment, or None
	30	+ _pad_before: Number of bytes before the first entry starts. This
	31	+ effectively changes the place where entry position 0 starts
	32	+ _pad_after: Number of bytes after the last entry ends. The last
	33	+ entry will finish on or before this boundary
	34	+ _pad_byte: Byte to use to pad the image where there is no entry
	35	+ _filename: Output filename for image
	36	+ _sort: True if entries should be sorted by position, False if they
	37	+ must be in-order in the device tree description
	38	+ _skip_at_start: Number of bytes before the first entry starts. These
	39	+ effecively adjust the starting position of entries. For example,
	40	+ if _pad_before is 16, then the first entry would start at 16.
	41	+ An entry with pos = 20 would in fact be written at position 4
	42	+ in the image file.
	43	+ _end_4gb: Indicates that the image ends at the 4GB boundary. This is
	44	+ used for x86 images, which want to use positions such that a
	45	+ memory address (like 0xff800000) is the first entry position.
	46	+ This causes _skip_at_start to be set to the starting memory
	47	+ address.
	48	+ _entries: OrderedDict() of entries
	49	+ """
	50	+ def __init__(self, name, node):
	51	+ self._node = node
	52	+ self._name = name
	53	+ self._size = None
	54	+ self._align_size = None
	55	+ self._pad_before = 0
	56	+ self._pad_after = 0
	57	+ self._pad_byte = 0
	58	+ self._filename = '%s.bin' % self._name
	59	+ self._sort = False
	60	+ self._skip_at_start = 0
	61	+ self._end_4gb = False
	62	+ self._entries = OrderedDict()
	63	+
	64	+ self._ReadNode()
	65	+ self._ReadEntries()
	66	+
	67	+ def _ReadNode(self):
	68	+ """Read properties from the image node"""
	69	+ self._size = fdt_util.GetInt(self._node, 'size')
	70	+ self._align_size = fdt_util.GetInt(self._node, 'align-size')
	71	+ if tools.NotPowerOfTwo(self._align_size):
	72	+ self._Raise("Alignment size %s must be a power of two" %
	73	+ self._align_size)
	74	+ self._pad_before = fdt_util.GetInt(self._node, 'pad-before', 0)
	75	+ self._pad_after = fdt_util.GetInt(self._node, 'pad-after', 0)
	76	+ self._pad_byte = fdt_util.GetInt(self._node, 'pad-byte', 0)
	77	+ filename = fdt_util.GetString(self._node, 'filename')
	78	+ if filename:
	79	+ self._filename = filename
	80	+ self._sort = fdt_util.GetBool(self._node, 'sort-by-pos')
	81	+ self._end_4gb = fdt_util.GetBool(self._node, 'end-at-4gb')
	82	+ if self._end_4gb and not self._size:
	83	+ self._Raise("Image size must be provided when using end-at-4gb")
	84	+ if self._end_4gb:
	85	+ self._skip_at_start = 0x100000000 - self._size
	86	+
	87	+ def CheckSize(self):
	88	+ """Check that the image contents does not exceed its size, etc."""
	89	+ contents_size = 0
	90	+ for entry in self._entries.values():
	91	+ contents_size = max(contents_size, entry.pos + entry.size)
	92	+
	93	+ contents_size -= self._skip_at_start
	94	+
	95	+ size = self._size
	96	+ if not size:
	97	+ size = self._pad_before + contents_size + self._pad_after
	98	+ size = tools.Align(size, self._align_size)
	99	+
	100	+ if self._size and contents_size > self._size:
	101	+ self._Raise("contents size %#x (%d) exceeds image size %#x (%d)" %
	102	+ (contents_size, contents_size, self._size, self._size))
	103	+ if not self._size:
	104	+ self._size = size
	105	+ if self._size != tools.Align(self._size, self._align_size):
	106	+ self._Raise("Size %#x (%d) does not match align-size %#x (%d)" %
	107	+ (self._size, self._size, self._align_size, self._align_size))
	108	+
	109	+ def _Raise(self, msg):
	110	+ """Raises an error for this image
	111	+
	112	+ Args:
	113	+ msg: Error message to use in the raise string
	114	+ Raises:
	115	+ ValueError()
	116	+ """
	117	+ raise ValueError("Image '%s': %s" % (self._node.path, msg))
	118	+
	119	+ def _ReadEntries(self):
	120	+ for node in self._node.subnodes:
	121	+ self._entries[node.name] = Entry.Create(self, node)
	122	+
	123	+ def FindEntryType(self, etype):
	124	+ """Find an entry type in the image
	125	+
	126	+ Args:
	127	+ etype: Entry type to find
	128	+ Returns:
	129	+ entry matching that type, or None if not found
	130	+ """
	131	+ for entry in self._entries.values():
	132	+ if entry.etype == etype:
	133	+ return entry
	134	+ return None
	135	+
	136	+ def GetEntryContents(self):
	137	+ """Call ObtainContents() for each entry
	138	+
	139	+ This calls each entry's ObtainContents() a few times until they all
	140	+ return True. We stop calling an entry's function once it returns
	141	+ True. This allows the contents of one entry to depend on another.
	142	+
	143	+ After 3 rounds we give up since it's likely an error.
	144	+ """
	145	+ todo = self._entries.values()
	146	+ for passnum in range(3):
	147	+ next_todo = []
	148	+ for entry in todo:
	149	+ if not entry.ObtainContents():
	150	+ next_todo.append(entry)
	151	+ todo = next_todo
	152	+ if not todo:
	153	+ break
	154	+
	155	+ def _SetEntryPosSize(self, name, pos, size):
	156	+ """Set the position and size of an entry
	157	+
	158	+ Args:
	159	+ name: Entry name to update
	160	+ pos: New position
	161	+ size: New size
	162	+ """
	163	+ entry = self._entries.get(name)
	164	+ if not entry:
	165	+ self._Raise("Unable to set pos/size for unknown entry '%s'" % name)
	166	+ entry.SetPositionSize(self._skip_at_start + pos, size)
	167	+
	168	+ def GetEntryPositions(self):
	169	+ """Handle entries that want to set the position/size of other entries
	170	+
	171	+ This calls each entry's GetPositions() method. If it returns a list
	172	+ of entries to update, it updates them.
	173	+ """
	174	+ for entry in self._entries.values():
	175	+ pos_dict = entry.GetPositions()
	176	+ for name, info in pos_dict.iteritems():
	177	+ self._SetEntryPosSize(name, *info)
	178	+
	179	+ def PackEntries(self):
	180	+ """Pack all entries into the image"""
	181	+ pos = self._skip_at_start
	182	+ for entry in self._entries.values():
	183	+ pos = entry.Pack(pos)
	184	+
	185	+ def _SortEntries(self):
	186	+ """Sort entries by position"""
	187	+ entries = sorted(self._entries.values(), key=lambda entry: entry.pos)
	188	+ self._entries.clear()
	189	+ for entry in entries:
	190	+ self._entries[entry._node.name] = entry
	191	+
	192	+ def CheckEntries(self):
	193	+ """Check that entries do not overlap or extend outside the image"""
	194	+ if self._sort:
	195	+ self._SortEntries()
	196	+ pos = 0
	197	+ prev_name = 'None'
	198	+ for entry in self._entries.values():
	199	+ if (entry.pos < self._skip_at_start or
	200	+ entry.pos >= self._skip_at_start + self._size):
	201	+ entry.Raise("Position %#x (%d) is outside the image starting "
	202	+ "at %#x (%d)" %
	203	+ (entry.pos, entry.pos, self._skip_at_start,
	204	+ self._skip_at_start))
	205	+ if entry.pos < pos:
	206	+ entry.Raise("Position %#x (%d) overlaps with previous entry '%s' "
	207	+ "ending at %#x (%d)" %
	208	+ (entry.pos, entry.pos, prev_name, pos, pos))
	209	+ pos = entry.pos + entry.size
	210	+ prev_name = entry.GetPath()
	211	+
	212	+ def ProcessEntryContents(self):
	213	+ """Call the ProcessContents() method for each entry
	214	+
	215	+ This is intended to adjust the contents as needed by the entry type.
	216	+ """
	217	+ for entry in self._entries.values():
	218	+ entry.ProcessContents()
	219	+
	220	+ def BuildImage(self):
	221	+ """Write the image to a file"""
	222	+ fname = tools.GetOutputFilename(self._filename)
	223	+ with open(fname, 'wb') as fd:
	224	+ fd.write(chr(self._pad_byte) * self._size)
	225	+
	226	+ for entry in self._entries.values():
	227	+ data = entry.GetData()
	228	+ fd.seek(self._pad_before + entry.pos - self._skip_at_start)
	229	+ fd.write(data)