1 # SPDX-License-Identifier: GPL-2.0+
2 # Copyright (c) 2016 Google, Inc
3 # Written by Simon Glass <sjg@chromium.org>
5 # Class for an image, the output of binman
8 from __future__ import print_function
10 from collections import OrderedDict
11 from operator import attrgetter
20 """A Image, representing an output from binman
22 An image is comprised of a collection of entries each containing binary
23 data. The image size must be large enough to hold all of this data.
25 This class implements the various operations needed for images.
28 _node: Node object that contains the image definition in device tree
30 _size: Image size in bytes, or None if not known yet
31 _filename: Output filename for image
32 _sections: Sections present in this image (may be one or more)
35 test: True if this is being called from a test of Images. This this case
36 there is no device tree defining the structure of the section, so
37 we create a section manually.
39 def __init__(self, name, node, test=False):
43 self._filename = '%s.bin' % self._name
45 self._section = bsection.Section('main-section', None, self._node,
51 """Read properties from the image node"""
52 self._size = fdt_util.GetInt(self._node, 'size')
53 filename = fdt_util.GetString(self._node, 'filename')
55 self._filename = filename
56 self._section = bsection.Section('main-section', None, self._node, self)
59 """Convenience function to raise an error referencing an image"""
60 raise ValueError("Image '%s': %s" % (self._node.path, msg))
63 """Get the set of device tree files used by this image"""
64 return self._section.GetFdtSet()
66 def ExpandEntries(self):
67 """Expand out any entries which have calculated sub-entries
69 Some entries are expanded out at runtime, e.g. 'files', which produces
70 a section containing a list of files. Process these entries so that
71 this information is added to the device tree.
73 self._section.ExpandEntries()
75 def AddMissingProperties(self):
76 """Add properties that are not present in the device tree
78 When binman has completed packing the entries the offset and size of
79 each entry are known. But before this the device tree may not specify
80 these. Add any missing properties, with a dummy value, so that the
81 size of the entry is correct. That way we can insert the correct values
84 self._section.AddMissingProperties()
86 def ProcessFdt(self, fdt):
87 """Allow entries to adjust the device tree
89 Some entries need to adjust the device tree for their purposes. This
90 may involve adding or deleting properties.
92 return self._section.ProcessFdt(fdt)
94 def GetEntryContents(self):
95 """Call ObtainContents() for the section
97 self._section.GetEntryContents()
99 def GetEntryOffsets(self):
100 """Handle entries that want to set the offset/size of other entries
102 This calls each entry's GetOffsets() method. If it returns a list
103 of entries to update, it updates them.
105 self._section.GetEntryOffsets()
107 def ResetForPack(self):
108 """Reset offset/size fields so that packing can be done again"""
109 self._section.ResetForPack()
111 def PackEntries(self):
112 """Pack all entries into the image"""
113 self._section.PackEntries()
116 """Check that the image contents does not exceed its size, etc."""
117 self._size = self._section.CheckSize()
119 def CheckEntries(self):
120 """Check that entries do not overlap or extend outside the image"""
121 self._section.CheckEntries()
123 def SetCalculatedProperties(self):
124 self._section.SetCalculatedProperties()
126 def SetImagePos(self):
127 self._section.SetImagePos(0)
129 def ProcessEntryContents(self):
130 """Call the ProcessContents() method for each entry
132 This is intended to adjust the contents as needed by the entry type.
135 True if the new data size is OK, False if expansion is needed
137 return self._section.ProcessEntryContents()
139 def WriteSymbols(self):
140 """Write symbol values into binary files for access at run time"""
141 self._section.WriteSymbols()
143 def BuildImage(self):
144 """Write the image to a file"""
145 fname = tools.GetOutputFilename(self._filename)
146 with open(fname, 'wb') as fd:
147 self._section.BuildSection(fd, 0)
149 def GetEntries(self):
150 return self._section.GetEntries()
153 """Write a map of the image to a .map file
156 Filename of map file written
158 filename = '%s.map' % self._name
159 fname = tools.GetOutputFilename(filename)
160 with open(fname, 'w') as fd:
161 print('%8s %8s %8s %s' % ('ImagePos', 'Offset', 'Size', 'Name'),
163 self._section.WriteMap(fd, 0)