blob: 70222718ea9303760eff69665e297454c9dc7bdd [file] [log] [blame]
Tom Rini83d290c2018-05-06 17:58:06 -04001# SPDX-License-Identifier: GPL-2.0+
Simon Glassbf7fd502016-11-25 20:15:51 -07002# Copyright (c) 2016 Google, Inc
3#
Simon Glassbf7fd502016-11-25 20:15:51 -07004# Base class for all entries
5#
6
Simon Glass53af22a2018-07-17 13:25:32 -06007from collections import namedtuple
Simon Glassb4cf5f12019-10-31 07:42:59 -06008import importlib
Simon Glassbadf0ec2018-06-01 09:38:15 -06009import os
10import sys
Simon Glassc55a50f2018-09-14 04:57:19 -060011
Simon Glass16287932020-04-17 18:09:03 -060012from dtoc import fdt_util
Simon Glassbf776672020-04-17 18:09:04 -060013from patman import tools
Simon Glass16287932020-04-17 18:09:03 -060014from patman.tools import ToHex, ToHexSize
Simon Glassbf776672020-04-17 18:09:04 -060015from patman import tout
Simon Glassbf7fd502016-11-25 20:15:51 -070016
17modules = {}
18
Simon Glass53af22a2018-07-17 13:25:32 -060019
20# An argument which can be passed to entries on the command line, in lieu of
21# device-tree properties.
22EntryArg = namedtuple('EntryArg', ['name', 'datatype'])
23
Simon Glass41b8ba02019-07-08 14:25:43 -060024# Information about an entry for use when displaying summaries
25EntryInfo = namedtuple('EntryInfo', ['indent', 'name', 'etype', 'size',
26 'image_pos', 'uncomp_size', 'offset',
27 'entry'])
Simon Glass53af22a2018-07-17 13:25:32 -060028
Simon Glassbf7fd502016-11-25 20:15:51 -070029class Entry(object):
Simon Glass25ac0e62018-06-01 09:38:14 -060030 """An Entry in the section
Simon Glassbf7fd502016-11-25 20:15:51 -070031
32 An entry corresponds to a single node in the device-tree description
Simon Glass25ac0e62018-06-01 09:38:14 -060033 of the section. Each entry ends up being a part of the final section.
Simon Glassbf7fd502016-11-25 20:15:51 -070034 Entries can be placed either right next to each other, or with padding
35 between them. The type of the entry determines the data that is in it.
36
37 This class is not used by itself. All entry objects are subclasses of
38 Entry.
39
40 Attributes:
Simon Glass8122f392018-07-17 13:25:28 -060041 section: Section object containing this entry
Simon Glassbf7fd502016-11-25 20:15:51 -070042 node: The node that created this entry
Simon Glass3ab95982018-08-01 15:22:37 -060043 offset: Offset of entry within the section, None if not known yet (in
44 which case it will be calculated by Pack())
Simon Glassbf7fd502016-11-25 20:15:51 -070045 size: Entry size in bytes, None if not known
Simon Glass9a5d3dc2019-10-31 07:43:02 -060046 pre_reset_size: size as it was before ResetForPack(). This allows us to
47 keep track of the size we started with and detect size changes
Simon Glass8287ee82019-07-08 14:25:30 -060048 uncomp_size: Size of uncompressed data in bytes, if the entry is
49 compressed, else None
Simon Glassbf7fd502016-11-25 20:15:51 -070050 contents_size: Size of contents in bytes, 0 by default
Simon Glass4eec34c2020-10-26 17:40:10 -060051 align: Entry start offset alignment relative to the start of the
52 containing section, or None
Simon Glassbf7fd502016-11-25 20:15:51 -070053 align_size: Entry size alignment, or None
Simon Glass4eec34c2020-10-26 17:40:10 -060054 align_end: Entry end offset alignment relative to the start of the
55 containing section, or None
Simon Glassf90d9062020-10-26 17:40:09 -060056 pad_before: Number of pad bytes before the contents when it is placed
57 in the containing section, 0 if none. The pad bytes become part of
58 the entry.
59 pad_after: Number of pad bytes after the contents when it is placed in
60 the containing section, 0 if none. The pad bytes become part of
61 the entry.
62 data: Contents of entry (string of bytes). This does not include
Simon Glass97c3e9a2020-10-26 17:40:15 -060063 padding created by pad_before or pad_after. If the entry is
64 compressed, this contains the compressed data.
65 uncomp_data: Original uncompressed data, if this entry is compressed,
66 else None
Simon Glass8287ee82019-07-08 14:25:30 -060067 compress: Compression algoithm used (e.g. 'lz4'), 'none' if none
Simon Glassc52c9e72019-07-08 14:25:37 -060068 orig_offset: Original offset value read from node
69 orig_size: Original size value read from node
Simon Glass87958982020-09-01 05:13:57 -060070 missing: True if this entry is missing its contents
71 allow_missing: Allow children of this entry to be missing (used by
72 subclasses such as Entry_section)
73 external: True if this entry contains an external binary blob
Simon Glassbf7fd502016-11-25 20:15:51 -070074 """
Simon Glassc6bd6e22019-07-20 12:23:45 -060075 def __init__(self, section, etype, node, name_prefix=''):
Simon Glass8dbb7442019-08-24 07:22:44 -060076 # Put this here to allow entry-docs and help to work without libfdt
77 global state
Simon Glass16287932020-04-17 18:09:03 -060078 from binman import state
Simon Glass8dbb7442019-08-24 07:22:44 -060079
Simon Glass25ac0e62018-06-01 09:38:14 -060080 self.section = section
Simon Glassbf7fd502016-11-25 20:15:51 -070081 self.etype = etype
82 self._node = node
Simon Glassc8d48ef2018-06-01 09:38:21 -060083 self.name = node and (name_prefix + node.name) or 'none'
Simon Glass3ab95982018-08-01 15:22:37 -060084 self.offset = None
Simon Glassbf7fd502016-11-25 20:15:51 -070085 self.size = None
Simon Glass9a5d3dc2019-10-31 07:43:02 -060086 self.pre_reset_size = None
Simon Glass8287ee82019-07-08 14:25:30 -060087 self.uncomp_size = None
Simon Glass24d0d3c2018-07-17 13:25:47 -060088 self.data = None
Simon Glass97c3e9a2020-10-26 17:40:15 -060089 self.uncomp_data = None
Simon Glassbf7fd502016-11-25 20:15:51 -070090 self.contents_size = 0
91 self.align = None
92 self.align_size = None
93 self.align_end = None
94 self.pad_before = 0
95 self.pad_after = 0
Simon Glass3ab95982018-08-01 15:22:37 -060096 self.offset_unset = False
Simon Glassdbf6be92018-08-01 15:22:42 -060097 self.image_pos = None
Simon Glassba64a0b2018-09-14 04:57:29 -060098 self._expand_size = False
Simon Glass8287ee82019-07-08 14:25:30 -060099 self.compress = 'none'
Simon Glassb1cca952020-07-09 18:39:40 -0600100 self.missing = False
Simon Glass87958982020-09-01 05:13:57 -0600101 self.external = False
102 self.allow_missing = False
Simon Glassbf7fd502016-11-25 20:15:51 -0700103
104 @staticmethod
Simon Glassb35fb172021-03-18 20:25:04 +1300105 def Lookup(node_path, etype, expanded):
Simon Glassfd8d1f72018-07-17 13:25:36 -0600106 """Look up the entry class for a node.
Simon Glassbf7fd502016-11-25 20:15:51 -0700107
108 Args:
Simon Glassfd8d1f72018-07-17 13:25:36 -0600109 node_node: Path name of Node object containing information about
110 the entry to create (used for errors)
111 etype: Entry type to use
Simon Glassb35fb172021-03-18 20:25:04 +1300112 expanded: Use the expanded version of etype
Simon Glassbf7fd502016-11-25 20:15:51 -0700113
114 Returns:
Simon Glassb35fb172021-03-18 20:25:04 +1300115 The entry class object if found, else None if not found and expanded
116 is True
117
118 Raise:
119 ValueError if expanded is False and the class is not found
Simon Glassbf7fd502016-11-25 20:15:51 -0700120 """
Simon Glassdd57c132018-06-01 09:38:11 -0600121 # Convert something like 'u-boot@0' to 'u_boot' since we are only
122 # interested in the type.
Simon Glassbf7fd502016-11-25 20:15:51 -0700123 module_name = etype.replace('-', '_')
Simon Glassb35fb172021-03-18 20:25:04 +1300124
Simon Glassdd57c132018-06-01 09:38:11 -0600125 if '@' in module_name:
126 module_name = module_name.split('@')[0]
Simon Glassb35fb172021-03-18 20:25:04 +1300127 if expanded:
128 module_name += '_expanded'
Simon Glassbf7fd502016-11-25 20:15:51 -0700129 module = modules.get(module_name)
130
Simon Glassbadf0ec2018-06-01 09:38:15 -0600131 # Also allow entry-type modules to be brought in from the etype directory.
132
Simon Glassbf7fd502016-11-25 20:15:51 -0700133 # Import the module if we have not already done so.
134 if not module:
135 try:
Simon Glass16287932020-04-17 18:09:03 -0600136 module = importlib.import_module('binman.etype.' + module_name)
Simon Glassfd8d1f72018-07-17 13:25:36 -0600137 except ImportError as e:
Simon Glassb35fb172021-03-18 20:25:04 +1300138 if expanded:
139 return None
Simon Glassfd8d1f72018-07-17 13:25:36 -0600140 raise ValueError("Unknown entry type '%s' in node '%s' (expected etype/%s.py, error '%s'" %
141 (etype, node_path, module_name, e))
Simon Glassbf7fd502016-11-25 20:15:51 -0700142 modules[module_name] = module
143
Simon Glassfd8d1f72018-07-17 13:25:36 -0600144 # Look up the expected class name
145 return getattr(module, 'Entry_%s' % module_name)
146
147 @staticmethod
Simon Glassb35fb172021-03-18 20:25:04 +1300148 def Create(section, node, etype=None, expanded=False):
Simon Glassfd8d1f72018-07-17 13:25:36 -0600149 """Create a new entry for a node.
150
151 Args:
Simon Glassb35fb172021-03-18 20:25:04 +1300152 section: Section object containing this node
153 node: Node object containing information about the entry to
154 create
155 etype: Entry type to use, or None to work it out (used for tests)
156 expanded: True to use expanded versions of entries, where available
Simon Glassfd8d1f72018-07-17 13:25:36 -0600157
158 Returns:
159 A new Entry object of the correct type (a subclass of Entry)
160 """
161 if not etype:
162 etype = fdt_util.GetString(node, 'type', node.name)
Simon Glassb35fb172021-03-18 20:25:04 +1300163 obj = Entry.Lookup(node.path, etype, expanded)
164 if obj and expanded:
165 # Check whether to use the expanded entry
166 new_etype = etype + '-expanded'
Simon Glass3d433382021-03-21 18:24:30 +1300167 can_expand = not fdt_util.GetBool(node, 'no-expanded')
168 if can_expand and obj.UseExpanded(node, etype, new_etype):
Simon Glassb35fb172021-03-18 20:25:04 +1300169 etype = new_etype
170 else:
171 obj = None
172 if not obj:
173 obj = Entry.Lookup(node.path, etype, False)
Simon Glassfd8d1f72018-07-17 13:25:36 -0600174
Simon Glassbf7fd502016-11-25 20:15:51 -0700175 # Call its constructor to get the object we want.
Simon Glass25ac0e62018-06-01 09:38:14 -0600176 return obj(section, etype, node)
Simon Glassbf7fd502016-11-25 20:15:51 -0700177
178 def ReadNode(self):
179 """Read entry information from the node
180
Simon Glassc6bd6e22019-07-20 12:23:45 -0600181 This must be called as the first thing after the Entry is created.
182
Simon Glassbf7fd502016-11-25 20:15:51 -0700183 This reads all the fields we recognise from the node, ready for use.
184 """
Simon Glass15a587c2018-07-17 13:25:51 -0600185 if 'pos' in self._node.props:
186 self.Raise("Please use 'offset' instead of 'pos'")
Simon Glass3ab95982018-08-01 15:22:37 -0600187 self.offset = fdt_util.GetInt(self._node, 'offset')
Simon Glassbf7fd502016-11-25 20:15:51 -0700188 self.size = fdt_util.GetInt(self._node, 'size')
Simon Glass12bb1a92019-07-20 12:23:51 -0600189 self.orig_offset = fdt_util.GetInt(self._node, 'orig-offset')
190 self.orig_size = fdt_util.GetInt(self._node, 'orig-size')
191 if self.GetImage().copy_to_orig:
192 self.orig_offset = self.offset
193 self.orig_size = self.size
Simon Glassc52c9e72019-07-08 14:25:37 -0600194
Simon Glassffded752019-07-08 14:25:46 -0600195 # These should not be set in input files, but are set in an FDT map,
196 # which is also read by this code.
197 self.image_pos = fdt_util.GetInt(self._node, 'image-pos')
198 self.uncomp_size = fdt_util.GetInt(self._node, 'uncomp-size')
199
Simon Glassbf7fd502016-11-25 20:15:51 -0700200 self.align = fdt_util.GetInt(self._node, 'align')
201 if tools.NotPowerOfTwo(self.align):
202 raise ValueError("Node '%s': Alignment %s must be a power of two" %
203 (self._node.path, self.align))
Simon Glass5ff9fed2021-03-21 18:24:33 +1300204 if self.section and self.align is None:
205 self.align = self.section.align_default
Simon Glassbf7fd502016-11-25 20:15:51 -0700206 self.pad_before = fdt_util.GetInt(self._node, 'pad-before', 0)
207 self.pad_after = fdt_util.GetInt(self._node, 'pad-after', 0)
208 self.align_size = fdt_util.GetInt(self._node, 'align-size')
209 if tools.NotPowerOfTwo(self.align_size):
Simon Glass8beb11e2019-07-08 14:25:47 -0600210 self.Raise("Alignment size %s must be a power of two" %
211 self.align_size)
Simon Glassbf7fd502016-11-25 20:15:51 -0700212 self.align_end = fdt_util.GetInt(self._node, 'align-end')
Simon Glass3ab95982018-08-01 15:22:37 -0600213 self.offset_unset = fdt_util.GetBool(self._node, 'offset-unset')
Simon Glassba64a0b2018-09-14 04:57:29 -0600214 self.expand_size = fdt_util.GetBool(self._node, 'expand-size')
Simon Glassb2381432020-09-06 10:39:09 -0600215 self.missing_msg = fdt_util.GetString(self._node, 'missing-msg')
Simon Glassbf7fd502016-11-25 20:15:51 -0700216
Simon Glass87c96292020-10-26 17:40:06 -0600217 # This is only supported by blobs and sections at present
218 self.compress = fdt_util.GetString(self._node, 'compress', 'none')
219
Simon Glass6c234bf2018-09-14 04:57:18 -0600220 def GetDefaultFilename(self):
221 return None
222
Simon Glassa8adb6d2019-07-20 12:23:28 -0600223 def GetFdts(self):
224 """Get the device trees used by this entry
Simon Glass539aece2018-09-14 04:57:22 -0600225
226 Returns:
Simon Glassa8adb6d2019-07-20 12:23:28 -0600227 Empty dict, if this entry is not a .dtb, otherwise:
228 Dict:
229 key: Filename from this entry (without the path)
Simon Glass4bdd3002019-07-20 12:23:31 -0600230 value: Tuple:
Simon Glassadb67bb2021-03-18 20:25:02 +1300231 Entry object for this dtb
Simon Glass4bdd3002019-07-20 12:23:31 -0600232 Filename of file containing this dtb
Simon Glass539aece2018-09-14 04:57:22 -0600233 """
Simon Glassa8adb6d2019-07-20 12:23:28 -0600234 return {}
Simon Glass539aece2018-09-14 04:57:22 -0600235
Simon Glass0a98b282018-09-14 04:57:28 -0600236 def ExpandEntries(self):
Simon Glassa01d1a22021-03-18 20:24:52 +1300237 """Expand out entries which produce other entries
238
239 Some entries generate subnodes automatically, from which sub-entries
240 are then created. This method allows those to be added to the binman
241 definition for the current image. An entry which implements this method
242 should call state.AddSubnode() to add a subnode and can add properties
243 with state.AddString(), etc.
244
245 An example is 'files', which produces a section containing a list of
246 files.
247 """
Simon Glass0a98b282018-09-14 04:57:28 -0600248 pass
249
Simon Glassa9fad072020-10-26 17:40:17 -0600250 def AddMissingProperties(self, have_image_pos):
251 """Add new properties to the device tree as needed for this entry
252
253 Args:
254 have_image_pos: True if this entry has an image position. This can
255 be False if its parent section is compressed, since compression
256 groups all entries together into a compressed block of data,
257 obscuring the start of each individual child entry
258 """
259 for prop in ['offset', 'size']:
Simon Glass078ab1a2018-07-06 10:27:41 -0600260 if not prop in self._node.props:
Simon Glassf46621d2018-09-14 04:57:21 -0600261 state.AddZeroProp(self._node, prop)
Simon Glassa9fad072020-10-26 17:40:17 -0600262 if have_image_pos and 'image-pos' not in self._node.props:
263 state.AddZeroProp(self._node, 'image-pos')
Simon Glass12bb1a92019-07-20 12:23:51 -0600264 if self.GetImage().allow_repack:
265 if self.orig_offset is not None:
266 state.AddZeroProp(self._node, 'orig-offset', True)
267 if self.orig_size is not None:
268 state.AddZeroProp(self._node, 'orig-size', True)
269
Simon Glass8287ee82019-07-08 14:25:30 -0600270 if self.compress != 'none':
271 state.AddZeroProp(self._node, 'uncomp-size')
Simon Glasse0e5df92018-09-14 04:57:31 -0600272 err = state.CheckAddHashProp(self._node)
273 if err:
274 self.Raise(err)
Simon Glass078ab1a2018-07-06 10:27:41 -0600275
276 def SetCalculatedProperties(self):
277 """Set the value of device-tree properties calculated by binman"""
Simon Glassf46621d2018-09-14 04:57:21 -0600278 state.SetInt(self._node, 'offset', self.offset)
279 state.SetInt(self._node, 'size', self.size)
Simon Glass8beb11e2019-07-08 14:25:47 -0600280 base = self.section.GetRootSkipAtStart() if self.section else 0
Simon Glassa9fad072020-10-26 17:40:17 -0600281 if self.image_pos is not None:
Simon Glass08594d42020-11-02 12:55:44 -0700282 state.SetInt(self._node, 'image-pos', self.image_pos - base)
Simon Glass12bb1a92019-07-20 12:23:51 -0600283 if self.GetImage().allow_repack:
284 if self.orig_offset is not None:
285 state.SetInt(self._node, 'orig-offset', self.orig_offset, True)
286 if self.orig_size is not None:
287 state.SetInt(self._node, 'orig-size', self.orig_size, True)
Simon Glass8287ee82019-07-08 14:25:30 -0600288 if self.uncomp_size is not None:
289 state.SetInt(self._node, 'uncomp-size', self.uncomp_size)
Simon Glasse0e5df92018-09-14 04:57:31 -0600290 state.CheckSetHashValue(self._node, self.GetData)
Simon Glass078ab1a2018-07-06 10:27:41 -0600291
Simon Glassecab8972018-07-06 10:27:40 -0600292 def ProcessFdt(self, fdt):
Simon Glass6ed45ba2018-09-14 04:57:24 -0600293 """Allow entries to adjust the device tree
294
295 Some entries need to adjust the device tree for their purposes. This
296 may involve adding or deleting properties.
297
298 Returns:
299 True if processing is complete
300 False if processing could not be completed due to a dependency.
301 This will cause the entry to be retried after others have been
302 called
303 """
Simon Glassecab8972018-07-06 10:27:40 -0600304 return True
305
Simon Glassc8d48ef2018-06-01 09:38:21 -0600306 def SetPrefix(self, prefix):
307 """Set the name prefix for a node
308
309 Args:
310 prefix: Prefix to set, or '' to not use a prefix
311 """
312 if prefix:
313 self.name = prefix + self.name
314
Simon Glass5c890232018-07-06 10:27:19 -0600315 def SetContents(self, data):
316 """Set the contents of an entry
317
318 This sets both the data and content_size properties
319
320 Args:
Simon Glass5b463fc2019-07-08 14:25:33 -0600321 data: Data to set to the contents (bytes)
Simon Glass5c890232018-07-06 10:27:19 -0600322 """
323 self.data = data
324 self.contents_size = len(self.data)
325
326 def ProcessContentsUpdate(self, data):
Simon Glass5b463fc2019-07-08 14:25:33 -0600327 """Update the contents of an entry, after the size is fixed
Simon Glass5c890232018-07-06 10:27:19 -0600328
Simon Glassa0dcaf22019-07-08 14:25:35 -0600329 This checks that the new data is the same size as the old. If the size
330 has changed, this triggers a re-run of the packing algorithm.
Simon Glass5c890232018-07-06 10:27:19 -0600331
332 Args:
Simon Glass5b463fc2019-07-08 14:25:33 -0600333 data: Data to set to the contents (bytes)
Simon Glass5c890232018-07-06 10:27:19 -0600334
335 Raises:
336 ValueError if the new data size is not the same as the old
337 """
Simon Glassa0dcaf22019-07-08 14:25:35 -0600338 size_ok = True
Simon Glassc52c9e72019-07-08 14:25:37 -0600339 new_size = len(data)
Simon Glass61ec04f2019-07-20 12:23:58 -0600340 if state.AllowEntryExpansion() and new_size > self.contents_size:
341 # self.data will indicate the new size needed
342 size_ok = False
343 elif state.AllowEntryContraction() and new_size < self.contents_size:
344 size_ok = False
345
346 # If not allowed to change, try to deal with it or give up
347 if size_ok:
Simon Glassc52c9e72019-07-08 14:25:37 -0600348 if new_size > self.contents_size:
Simon Glass61ec04f2019-07-20 12:23:58 -0600349 self.Raise('Cannot update entry size from %d to %d' %
350 (self.contents_size, new_size))
351
352 # Don't let the data shrink. Pad it if necessary
353 if size_ok and new_size < self.contents_size:
354 data += tools.GetBytes(0, self.contents_size - new_size)
355
356 if not size_ok:
357 tout.Debug("Entry '%s' size change from %s to %s" % (
358 self._node.path, ToHex(self.contents_size),
359 ToHex(new_size)))
Simon Glass5c890232018-07-06 10:27:19 -0600360 self.SetContents(data)
Simon Glassa0dcaf22019-07-08 14:25:35 -0600361 return size_ok
Simon Glass5c890232018-07-06 10:27:19 -0600362
Simon Glassbf7fd502016-11-25 20:15:51 -0700363 def ObtainContents(self):
364 """Figure out the contents of an entry.
365
366 Returns:
367 True if the contents were found, False if another call is needed
368 after the other entries are processed.
369 """
370 # No contents by default: subclasses can implement this
371 return True
372
Simon Glassc52c9e72019-07-08 14:25:37 -0600373 def ResetForPack(self):
374 """Reset offset/size fields so that packing can be done again"""
Simon Glass9f297b02019-07-20 12:23:36 -0600375 self.Detail('ResetForPack: offset %s->%s, size %s->%s' %
376 (ToHex(self.offset), ToHex(self.orig_offset),
377 ToHex(self.size), ToHex(self.orig_size)))
Simon Glass9a5d3dc2019-10-31 07:43:02 -0600378 self.pre_reset_size = self.size
Simon Glassc52c9e72019-07-08 14:25:37 -0600379 self.offset = self.orig_offset
380 self.size = self.orig_size
381
Simon Glass3ab95982018-08-01 15:22:37 -0600382 def Pack(self, offset):
Simon Glass25ac0e62018-06-01 09:38:14 -0600383 """Figure out how to pack the entry into the section
Simon Glassbf7fd502016-11-25 20:15:51 -0700384
385 Most of the time the entries are not fully specified. There may be
386 an alignment but no size. In that case we take the size from the
387 contents of the entry.
388
Simon Glass3ab95982018-08-01 15:22:37 -0600389 If an entry has no hard-coded offset, it will be placed at @offset.
Simon Glassbf7fd502016-11-25 20:15:51 -0700390
Simon Glass3ab95982018-08-01 15:22:37 -0600391 Once this function is complete, both the offset and size of the
Simon Glassbf7fd502016-11-25 20:15:51 -0700392 entry will be know.
393
394 Args:
Simon Glass3ab95982018-08-01 15:22:37 -0600395 Current section offset pointer
Simon Glassbf7fd502016-11-25 20:15:51 -0700396
397 Returns:
Simon Glass3ab95982018-08-01 15:22:37 -0600398 New section offset pointer (after this entry)
Simon Glassbf7fd502016-11-25 20:15:51 -0700399 """
Simon Glass9f297b02019-07-20 12:23:36 -0600400 self.Detail('Packing: offset=%s, size=%s, content_size=%x' %
401 (ToHex(self.offset), ToHex(self.size),
402 self.contents_size))
Simon Glass3ab95982018-08-01 15:22:37 -0600403 if self.offset is None:
404 if self.offset_unset:
405 self.Raise('No offset set with offset-unset: should another '
406 'entry provide this correct offset?')
407 self.offset = tools.Align(offset, self.align)
Simon Glassbf7fd502016-11-25 20:15:51 -0700408 needed = self.pad_before + self.contents_size + self.pad_after
409 needed = tools.Align(needed, self.align_size)
410 size = self.size
411 if not size:
412 size = needed
Simon Glass3ab95982018-08-01 15:22:37 -0600413 new_offset = self.offset + size
414 aligned_offset = tools.Align(new_offset, self.align_end)
415 if aligned_offset != new_offset:
416 size = aligned_offset - self.offset
417 new_offset = aligned_offset
Simon Glassbf7fd502016-11-25 20:15:51 -0700418
419 if not self.size:
420 self.size = size
421
422 if self.size < needed:
423 self.Raise("Entry contents size is %#x (%d) but entry size is "
424 "%#x (%d)" % (needed, needed, self.size, self.size))
425 # Check that the alignment is correct. It could be wrong if the
Simon Glass3ab95982018-08-01 15:22:37 -0600426 # and offset or size values were provided (i.e. not calculated), but
Simon Glassbf7fd502016-11-25 20:15:51 -0700427 # conflict with the provided alignment values
428 if self.size != tools.Align(self.size, self.align_size):
429 self.Raise("Size %#x (%d) does not match align-size %#x (%d)" %
430 (self.size, self.size, self.align_size, self.align_size))
Simon Glass3ab95982018-08-01 15:22:37 -0600431 if self.offset != tools.Align(self.offset, self.align):
432 self.Raise("Offset %#x (%d) does not match align %#x (%d)" %
433 (self.offset, self.offset, self.align, self.align))
Simon Glass9f297b02019-07-20 12:23:36 -0600434 self.Detail(' - packed: offset=%#x, size=%#x, content_size=%#x, next_offset=%x' %
435 (self.offset, self.size, self.contents_size, new_offset))
Simon Glassbf7fd502016-11-25 20:15:51 -0700436
Simon Glass3ab95982018-08-01 15:22:37 -0600437 return new_offset
Simon Glassbf7fd502016-11-25 20:15:51 -0700438
439 def Raise(self, msg):
440 """Convenience function to raise an error referencing a node"""
441 raise ValueError("Node '%s': %s" % (self._node.path, msg))
442
Simon Glass189f2912021-03-21 18:24:31 +1300443 def Info(self, msg):
444 """Convenience function to log info referencing a node"""
445 tag = "Info '%s'" % self._node.path
446 tout.Detail('%30s: %s' % (tag, msg))
447
Simon Glass9f297b02019-07-20 12:23:36 -0600448 def Detail(self, msg):
449 """Convenience function to log detail referencing a node"""
450 tag = "Node '%s'" % self._node.path
451 tout.Detail('%30s: %s' % (tag, msg))
452
Simon Glass53af22a2018-07-17 13:25:32 -0600453 def GetEntryArgsOrProps(self, props, required=False):
454 """Return the values of a set of properties
455
456 Args:
457 props: List of EntryArg objects
458
459 Raises:
460 ValueError if a property is not found
461 """
462 values = []
463 missing = []
464 for prop in props:
465 python_prop = prop.name.replace('-', '_')
466 if hasattr(self, python_prop):
467 value = getattr(self, python_prop)
468 else:
469 value = None
470 if value is None:
471 value = self.GetArg(prop.name, prop.datatype)
472 if value is None and required:
473 missing.append(prop.name)
474 values.append(value)
475 if missing:
Simon Glass939d1062021-01-06 21:35:16 -0700476 self.GetImage().MissingArgs(self, missing)
Simon Glass53af22a2018-07-17 13:25:32 -0600477 return values
478
Simon Glassbf7fd502016-11-25 20:15:51 -0700479 def GetPath(self):
480 """Get the path of a node
481
482 Returns:
483 Full path of the node for this entry
484 """
485 return self._node.path
486
Simon Glass631f7522021-03-21 18:24:32 +1300487 def GetData(self, required=True):
Simon Glass63e7ba62020-10-26 17:40:16 -0600488 """Get the contents of an entry
489
Simon Glass631f7522021-03-21 18:24:32 +1300490 Args:
491 required: True if the data must be present, False if it is OK to
492 return None
493
Simon Glass63e7ba62020-10-26 17:40:16 -0600494 Returns:
495 bytes content of the entry, excluding any padding. If the entry is
496 compressed, the compressed data is returned
497 """
Simon Glass9f297b02019-07-20 12:23:36 -0600498 self.Detail('GetData: size %s' % ToHexSize(self.data))
Simon Glassbf7fd502016-11-25 20:15:51 -0700499 return self.data
500
Simon Glass271a0832020-11-02 12:55:43 -0700501 def GetPaddedData(self, data=None):
502 """Get the data for an entry including any padding
503
504 Gets the entry data and uses its section's pad-byte value to add padding
505 before and after as defined by the pad-before and pad-after properties.
506
507 This does not consider alignment.
508
509 Returns:
510 Contents of the entry along with any pad bytes before and
511 after it (bytes)
512 """
513 if data is None:
514 data = self.GetData()
515 return self.section.GetPaddedDataForEntry(self, data)
516
Simon Glass3ab95982018-08-01 15:22:37 -0600517 def GetOffsets(self):
Simon Glassed7dd5e2019-07-08 13:18:30 -0600518 """Get the offsets for siblings
519
520 Some entry types can contain information about the position or size of
521 other entries. An example of this is the Intel Flash Descriptor, which
522 knows where the Intel Management Engine section should go.
523
524 If this entry knows about the position of other entries, it can specify
525 this by returning values here
526
527 Returns:
528 Dict:
529 key: Entry type
530 value: List containing position and size of the given entry
Simon Glasscf549042019-07-08 13:18:39 -0600531 type. Either can be None if not known
Simon Glassed7dd5e2019-07-08 13:18:30 -0600532 """
Simon Glassbf7fd502016-11-25 20:15:51 -0700533 return {}
534
Simon Glasscf549042019-07-08 13:18:39 -0600535 def SetOffsetSize(self, offset, size):
536 """Set the offset and/or size of an entry
537
538 Args:
539 offset: New offset, or None to leave alone
540 size: New size, or None to leave alone
541 """
542 if offset is not None:
543 self.offset = offset
544 if size is not None:
545 self.size = size
Simon Glassbf7fd502016-11-25 20:15:51 -0700546
Simon Glassdbf6be92018-08-01 15:22:42 -0600547 def SetImagePos(self, image_pos):
548 """Set the position in the image
549
550 Args:
551 image_pos: Position of this entry in the image
552 """
553 self.image_pos = image_pos + self.offset
554
Simon Glassbf7fd502016-11-25 20:15:51 -0700555 def ProcessContents(self):
Simon Glassa0dcaf22019-07-08 14:25:35 -0600556 """Do any post-packing updates of entry contents
557
558 This function should call ProcessContentsUpdate() to update the entry
559 contents, if necessary, returning its return value here.
560
561 Args:
562 data: Data to set to the contents (bytes)
563
564 Returns:
565 True if the new data size is OK, False if expansion is needed
566
567 Raises:
568 ValueError if the new data size is not the same as the old and
569 state.AllowEntryExpansion() is False
570 """
571 return True
Simon Glass19790632017-11-13 18:55:01 -0700572
Simon Glassf55382b2018-06-01 09:38:13 -0600573 def WriteSymbols(self, section):
Simon Glass19790632017-11-13 18:55:01 -0700574 """Write symbol values into binary files for access at run time
575
576 Args:
Simon Glassf55382b2018-06-01 09:38:13 -0600577 section: Section containing the entry
Simon Glass19790632017-11-13 18:55:01 -0700578 """
579 pass
Simon Glass18546952018-06-01 09:38:16 -0600580
Simon Glass6ddd6112020-10-26 17:40:18 -0600581 def CheckEntries(self):
Simon Glass3ab95982018-08-01 15:22:37 -0600582 """Check that the entry offsets are correct
Simon Glass18546952018-06-01 09:38:16 -0600583
Simon Glass3ab95982018-08-01 15:22:37 -0600584 This is used for entries which have extra offset requirements (other
Simon Glass18546952018-06-01 09:38:16 -0600585 than having to be fully inside their section). Sub-classes can implement
586 this function and raise if there is a problem.
587 """
588 pass
Simon Glass3b0c3822018-06-01 09:38:20 -0600589
Simon Glass8122f392018-07-17 13:25:28 -0600590 @staticmethod
Simon Glass163ed6c2018-09-14 04:57:36 -0600591 def GetStr(value):
592 if value is None:
593 return '<none> '
594 return '%08x' % value
595
596 @staticmethod
Simon Glass1be70d22018-07-17 13:25:49 -0600597 def WriteMapLine(fd, indent, name, offset, size, image_pos):
Simon Glass163ed6c2018-09-14 04:57:36 -0600598 print('%s %s%s %s %s' % (Entry.GetStr(image_pos), ' ' * indent,
599 Entry.GetStr(offset), Entry.GetStr(size),
600 name), file=fd)
Simon Glass8122f392018-07-17 13:25:28 -0600601
Simon Glass3b0c3822018-06-01 09:38:20 -0600602 def WriteMap(self, fd, indent):
603 """Write a map of the entry to a .map file
604
605 Args:
606 fd: File to write the map to
607 indent: Curent indent level of map (0=none, 1=one level, etc.)
608 """
Simon Glass1be70d22018-07-17 13:25:49 -0600609 self.WriteMapLine(fd, indent, self.name, self.offset, self.size,
610 self.image_pos)
Simon Glass53af22a2018-07-17 13:25:32 -0600611
Simon Glass11e36cc2018-07-17 13:25:38 -0600612 def GetEntries(self):
613 """Return a list of entries contained by this entry
614
615 Returns:
616 List of entries, or None if none. A normal entry has no entries
617 within it so will return None
618 """
619 return None
620
Simon Glass53af22a2018-07-17 13:25:32 -0600621 def GetArg(self, name, datatype=str):
622 """Get the value of an entry argument or device-tree-node property
623
624 Some node properties can be provided as arguments to binman. First check
625 the entry arguments, and fall back to the device tree if not found
626
627 Args:
628 name: Argument name
629 datatype: Data type (str or int)
630
631 Returns:
632 Value of argument as a string or int, or None if no value
633
634 Raises:
635 ValueError if the argument cannot be converted to in
636 """
Simon Glassc55a50f2018-09-14 04:57:19 -0600637 value = state.GetEntryArg(name)
Simon Glass53af22a2018-07-17 13:25:32 -0600638 if value is not None:
639 if datatype == int:
640 try:
641 value = int(value)
642 except ValueError:
643 self.Raise("Cannot convert entry arg '%s' (value '%s') to integer" %
644 (name, value))
645 elif datatype == str:
646 pass
647 else:
648 raise ValueError("GetArg() internal error: Unknown data type '%s'" %
649 datatype)
650 else:
651 value = fdt_util.GetDatatype(self._node, name, datatype)
652 return value
Simon Glassfd8d1f72018-07-17 13:25:36 -0600653
654 @staticmethod
655 def WriteDocs(modules, test_missing=None):
656 """Write out documentation about the various entry types to stdout
657
658 Args:
659 modules: List of modules to include
660 test_missing: Used for testing. This is a module to report
661 as missing
662 """
663 print('''Binman Entry Documentation
664===========================
665
666This file describes the entry types supported by binman. These entry types can
667be placed in an image one by one to build up a final firmware image. It is
668fairly easy to create new entry types. Just add a new file to the 'etype'
669directory. You can use the existing entries as examples.
670
671Note that some entries are subclasses of others, using and extending their
672features to produce new behaviours.
673
674
675''')
676 modules = sorted(modules)
677
678 # Don't show the test entry
679 if '_testing' in modules:
680 modules.remove('_testing')
681 missing = []
682 for name in modules:
Simon Glassb35fb172021-03-18 20:25:04 +1300683 module = Entry.Lookup('WriteDocs', name, False)
Simon Glassfd8d1f72018-07-17 13:25:36 -0600684 docs = getattr(module, '__doc__')
685 if test_missing == name:
686 docs = None
687 if docs:
688 lines = docs.splitlines()
689 first_line = lines[0]
690 rest = [line[4:] for line in lines[1:]]
691 hdr = 'Entry: %s: %s' % (name.replace('_', '-'), first_line)
692 print(hdr)
693 print('-' * len(hdr))
694 print('\n'.join(rest))
695 print()
696 print()
697 else:
698 missing.append(name)
699
700 if missing:
701 raise ValueError('Documentation is missing for modules: %s' %
702 ', '.join(missing))
Simon Glassa326b492018-09-14 04:57:11 -0600703
704 def GetUniqueName(self):
705 """Get a unique name for a node
706
707 Returns:
708 String containing a unique name for a node, consisting of the name
709 of all ancestors (starting from within the 'binman' node) separated
710 by a dot ('.'). This can be useful for generating unique filesnames
711 in the output directory.
712 """
713 name = self.name
714 node = self._node
715 while node.parent:
716 node = node.parent
717 if node.name == 'binman':
718 break
719 name = '%s.%s' % (node.name, name)
720 return name
Simon Glassba64a0b2018-09-14 04:57:29 -0600721
722 def ExpandToLimit(self, limit):
723 """Expand an entry so that it ends at the given offset limit"""
724 if self.offset + self.size < limit:
725 self.size = limit - self.offset
726 # Request the contents again, since changing the size requires that
727 # the data grows. This should not fail, but check it to be sure.
728 if not self.ObtainContents():
729 self.Raise('Cannot obtain contents when expanding entry')
Simon Glassfa1c9372019-07-08 13:18:38 -0600730
731 def HasSibling(self, name):
732 """Check if there is a sibling of a given name
733
734 Returns:
735 True if there is an entry with this name in the the same section,
736 else False
737 """
738 return name in self.section.GetEntries()
Simon Glasscf228942019-07-08 14:25:28 -0600739
740 def GetSiblingImagePos(self, name):
741 """Return the image position of the given sibling
742
743 Returns:
744 Image position of sibling, or None if the sibling has no position,
745 or False if there is no such sibling
746 """
747 if not self.HasSibling(name):
748 return False
749 return self.section.GetEntries()[name].image_pos
Simon Glass41b8ba02019-07-08 14:25:43 -0600750
751 @staticmethod
752 def AddEntryInfo(entries, indent, name, etype, size, image_pos,
753 uncomp_size, offset, entry):
754 """Add a new entry to the entries list
755
756 Args:
757 entries: List (of EntryInfo objects) to add to
758 indent: Current indent level to add to list
759 name: Entry name (string)
760 etype: Entry type (string)
761 size: Entry size in bytes (int)
762 image_pos: Position within image in bytes (int)
763 uncomp_size: Uncompressed size if the entry uses compression, else
764 None
765 offset: Entry offset within parent in bytes (int)
766 entry: Entry object
767 """
768 entries.append(EntryInfo(indent, name, etype, size, image_pos,
769 uncomp_size, offset, entry))
770
771 def ListEntries(self, entries, indent):
772 """Add files in this entry to the list of entries
773
774 This can be overridden by subclasses which need different behaviour.
775
776 Args:
777 entries: List (of EntryInfo objects) to add to
778 indent: Current indent level to add to list
779 """
780 self.AddEntryInfo(entries, indent, self.name, self.etype, self.size,
781 self.image_pos, self.uncomp_size, self.offset, self)
Simon Glassf667e452019-07-08 14:25:50 -0600782
783 def ReadData(self, decomp=True):
784 """Read the data for an entry from the image
785
786 This is used when the image has been read in and we want to extract the
787 data for a particular entry from that image.
788
789 Args:
790 decomp: True to decompress any compressed data before returning it;
791 False to return the raw, uncompressed data
792
793 Returns:
794 Entry data (bytes)
795 """
796 # Use True here so that we get an uncompressed section to work from,
797 # although compressed sections are currently not supported
Simon Glass2d553c02019-09-25 08:56:21 -0600798 tout.Debug("ReadChildData section '%s', entry '%s'" %
799 (self.section.GetPath(), self.GetPath()))
Simon Glassa9cd39e2019-07-20 12:24:04 -0600800 data = self.section.ReadChildData(self, decomp)
801 return data
Simon Glassd5079332019-07-20 12:23:41 -0600802
Simon Glass4e185e82019-09-25 08:56:20 -0600803 def ReadChildData(self, child, decomp=True):
Simon Glass2d553c02019-09-25 08:56:21 -0600804 """Read the data for a particular child entry
Simon Glass4e185e82019-09-25 08:56:20 -0600805
806 This reads data from the parent and extracts the piece that relates to
807 the given child.
808
809 Args:
Simon Glass2d553c02019-09-25 08:56:21 -0600810 child: Child entry to read data for (must be valid)
Simon Glass4e185e82019-09-25 08:56:20 -0600811 decomp: True to decompress any compressed data before returning it;
812 False to return the raw, uncompressed data
813
814 Returns:
815 Data for the child (bytes)
816 """
817 pass
818
Simon Glassd5079332019-07-20 12:23:41 -0600819 def LoadData(self, decomp=True):
820 data = self.ReadData(decomp)
Simon Glass10f9d002019-07-20 12:23:50 -0600821 self.contents_size = len(data)
Simon Glassd5079332019-07-20 12:23:41 -0600822 self.ProcessContentsUpdate(data)
823 self.Detail('Loaded data size %x' % len(data))
Simon Glassc5ad04b2019-07-20 12:23:46 -0600824
825 def GetImage(self):
826 """Get the image containing this entry
827
828 Returns:
829 Image object containing this entry
830 """
831 return self.section.GetImage()
Simon Glass10f9d002019-07-20 12:23:50 -0600832
833 def WriteData(self, data, decomp=True):
834 """Write the data to an entry in the image
835
836 This is used when the image has been read in and we want to replace the
837 data for a particular entry in that image.
838
839 The image must be re-packed and written out afterwards.
840
841 Args:
842 data: Data to replace it with
843 decomp: True to compress the data if needed, False if data is
844 already compressed so should be used as is
845
846 Returns:
847 True if the data did not result in a resize of this entry, False if
848 the entry must be resized
849 """
Simon Glass9a5d3dc2019-10-31 07:43:02 -0600850 if self.size is not None:
851 self.contents_size = self.size
852 else:
853 self.contents_size = self.pre_reset_size
Simon Glass10f9d002019-07-20 12:23:50 -0600854 ok = self.ProcessContentsUpdate(data)
855 self.Detail('WriteData: size=%x, ok=%s' % (len(data), ok))
Simon Glass7210c892019-07-20 12:24:05 -0600856 section_ok = self.section.WriteChildData(self)
857 return ok and section_ok
858
859 def WriteChildData(self, child):
860 """Handle writing the data in a child entry
861
862 This should be called on the child's parent section after the child's
863 data has been updated. It
864
865 This base-class implementation does nothing, since the base Entry object
866 does not have any children.
867
868 Args:
869 child: Child Entry that was written
870
871 Returns:
872 True if the section could be updated successfully, False if the
873 data is such that the section could not updat
874 """
875 return True
Simon Glasseba1f0c2019-07-20 12:23:55 -0600876
877 def GetSiblingOrder(self):
878 """Get the relative order of an entry amoung its siblings
879
880 Returns:
881 'start' if this entry is first among siblings, 'end' if last,
882 otherwise None
883 """
884 entries = list(self.section.GetEntries().values())
885 if entries:
886 if self == entries[0]:
887 return 'start'
888 elif self == entries[-1]:
889 return 'end'
890 return 'middle'
Simon Glass4f9f1052020-07-09 18:39:38 -0600891
892 def SetAllowMissing(self, allow_missing):
893 """Set whether a section allows missing external blobs
894
895 Args:
896 allow_missing: True if allowed, False if not allowed
897 """
898 # This is meaningless for anything other than sections
899 pass
Simon Glassb1cca952020-07-09 18:39:40 -0600900
901 def CheckMissing(self, missing_list):
902 """Check if any entries in this section have missing external blobs
903
904 If there are missing blobs, the entries are added to the list
905
906 Args:
907 missing_list: List of Entry objects to be added to
908 """
909 if self.missing:
910 missing_list.append(self)
Simon Glass87958982020-09-01 05:13:57 -0600911
912 def GetAllowMissing(self):
913 """Get whether a section allows missing external blobs
914
915 Returns:
916 True if allowed, False if not allowed
917 """
918 return self.allow_missing
Simon Glassb2381432020-09-06 10:39:09 -0600919
920 def GetHelpTags(self):
921 """Get the tags use for missing-blob help
922
923 Returns:
924 list of possible tags, most desirable first
925 """
926 return list(filter(None, [self.missing_msg, self.name, self.etype]))
Simon Glass87c96292020-10-26 17:40:06 -0600927
928 def CompressData(self, indata):
929 """Compress data according to the entry's compression method
930
931 Args:
932 indata: Data to compress
933
934 Returns:
935 Compressed data (first word is the compressed size)
936 """
Simon Glass97c3e9a2020-10-26 17:40:15 -0600937 self.uncomp_data = indata
Simon Glass87c96292020-10-26 17:40:06 -0600938 if self.compress != 'none':
939 self.uncomp_size = len(indata)
940 data = tools.Compress(indata, self.compress)
941 return data
Simon Glassb35fb172021-03-18 20:25:04 +1300942
943 @classmethod
944 def UseExpanded(cls, node, etype, new_etype):
945 """Check whether to use an expanded entry type
946
947 This is called by Entry.Create() when it finds an expanded version of
948 an entry type (e.g. 'u-boot-expanded'). If this method returns True then
949 it will be used (e.g. in place of 'u-boot'). If it returns False, it is
950 ignored.
951
952 Args:
953 node: Node object containing information about the entry to
954 create
955 etype: Original entry type being used
956 new_etype: New entry type proposed
957
958 Returns:
959 True to use this entry type, False to use the original one
960 """
961 tout.Info("Node '%s': etype '%s': %s selected" %
962 (node.path, etype, new_etype))
963 return True