1 # SPDX-License-Identifier: GPL-2.0+
2 # Copyright (c) 2016 Google, Inc
4 # Base class for all entries
7 from __future__ import print_function
9 from collections import namedtuple
11 # importlib was introduced in Python 2.7 but there was a report of it not
12 # working in 2.7.12, so we work around this:
13 # http://lists.denx.de/pipermail/u-boot/2016-October/269729.html
18 have_importlib = False
30 our_path = os.path.dirname(os.path.realpath(__file__))
33 # An argument which can be passed to entries on the command line, in lieu of
34 # device-tree properties.
35 EntryArg = namedtuple('EntryArg', ['name', 'datatype'])
39 """An Entry in the section
41 An entry corresponds to a single node in the device-tree description
42 of the section. Each entry ends up being a part of the final section.
43 Entries can be placed either right next to each other, or with padding
44 between them. The type of the entry determines the data that is in it.
46 This class is not used by itself. All entry objects are subclasses of
50 section: Section object containing this entry
51 node: The node that created this entry
52 offset: Offset of entry within the section, None if not known yet (in
53 which case it will be calculated by Pack())
54 size: Entry size in bytes, None if not known
55 contents_size: Size of contents in bytes, 0 by default
56 align: Entry start offset alignment, or None
57 align_size: Entry size alignment, or None
58 align_end: Entry end offset alignment, or None
59 pad_before: Number of pad bytes before the contents, 0 if none
60 pad_after: Number of pad bytes after the contents, 0 if none
61 data: Contents of entry (string of bytes)
63 def __init__(self, section, etype, node, read_node=True, name_prefix=''):
64 self.section = section
67 self.name = node and (name_prefix + node.name) or 'none'
71 self.contents_size = 0
73 self.align_size = None
77 self.offset_unset = False
79 self._expand_size = False
84 def Lookup(section, node_path, etype):
85 """Look up the entry class for a node.
88 section: Section object containing this node
89 node_node: Path name of Node object containing information about
90 the entry to create (used for errors)
91 etype: Entry type to use
94 The entry class object if found, else None
96 # Convert something like 'u-boot@0' to 'u_boot' since we are only
97 # interested in the type.
98 module_name = etype.replace('-', '_')
99 if '@' in module_name:
100 module_name = module_name.split('@')[0]
101 module = modules.get(module_name)
103 # Also allow entry-type modules to be brought in from the etype directory.
105 # Import the module if we have not already done so.
108 sys.path.insert(0, os.path.join(our_path, 'etype'))
111 module = importlib.import_module(module_name)
113 module = __import__(module_name)
114 except ImportError as e:
115 raise ValueError("Unknown entry type '%s' in node '%s' (expected etype/%s.py, error '%s'" %
116 (etype, node_path, module_name, e))
119 modules[module_name] = module
121 # Look up the expected class name
122 return getattr(module, 'Entry_%s' % module_name)
125 def Create(section, node, etype=None):
126 """Create a new entry for a node.
129 section: Section object containing this node
130 node: Node object containing information about the entry to
132 etype: Entry type to use, or None to work it out (used for tests)
135 A new Entry object of the correct type (a subclass of Entry)
138 etype = fdt_util.GetString(node, 'type', node.name)
139 obj = Entry.Lookup(section, node.path, etype)
141 # Call its constructor to get the object we want.
142 return obj(section, etype, node)
145 """Read entry information from the node
147 This reads all the fields we recognise from the node, ready for use.
149 if 'pos' in self._node.props:
150 self.Raise("Please use 'offset' instead of 'pos'")
151 self.offset = fdt_util.GetInt(self._node, 'offset')
152 self.size = fdt_util.GetInt(self._node, 'size')
153 self.align = fdt_util.GetInt(self._node, 'align')
154 if tools.NotPowerOfTwo(self.align):
155 raise ValueError("Node '%s': Alignment %s must be a power of two" %
156 (self._node.path, self.align))
157 self.pad_before = fdt_util.GetInt(self._node, 'pad-before', 0)
158 self.pad_after = fdt_util.GetInt(self._node, 'pad-after', 0)
159 self.align_size = fdt_util.GetInt(self._node, 'align-size')
160 if tools.NotPowerOfTwo(self.align_size):
161 raise ValueError("Node '%s': Alignment size %s must be a power "
162 "of two" % (self._node.path, self.align_size))
163 self.align_end = fdt_util.GetInt(self._node, 'align-end')
164 self.offset_unset = fdt_util.GetBool(self._node, 'offset-unset')
165 self.expand_size = fdt_util.GetBool(self._node, 'expand-size')
167 def GetDefaultFilename(self):
171 """Get the set of device trees used by this entry
174 Set containing the filename from this entry, if it is a .dtb, else
177 fname = self.GetDefaultFilename()
178 # It would be better to use isinstance(self, Entry_blob_dtb) here but
179 # we cannot access Entry_blob_dtb
180 if fname and fname.endswith('.dtb'):
184 def ExpandEntries(self):
187 def AddMissingProperties(self):
188 """Add new properties to the device tree as needed for this entry"""
189 for prop in ['offset', 'size', 'image-pos']:
190 if not prop in self._node.props:
191 state.AddZeroProp(self._node, prop)
192 err = state.CheckAddHashProp(self._node)
196 def SetCalculatedProperties(self):
197 """Set the value of device-tree properties calculated by binman"""
198 state.SetInt(self._node, 'offset', self.offset)
199 state.SetInt(self._node, 'size', self.size)
200 state.SetInt(self._node, 'image-pos',
201 self.image_pos - self.section.GetRootSkipAtStart())
202 state.CheckSetHashValue(self._node, self.GetData)
204 def ProcessFdt(self, fdt):
205 """Allow entries to adjust the device tree
207 Some entries need to adjust the device tree for their purposes. This
208 may involve adding or deleting properties.
211 True if processing is complete
212 False if processing could not be completed due to a dependency.
213 This will cause the entry to be retried after others have been
218 def SetPrefix(self, prefix):
219 """Set the name prefix for a node
222 prefix: Prefix to set, or '' to not use a prefix
225 self.name = prefix + self.name
227 def SetContents(self, data):
228 """Set the contents of an entry
230 This sets both the data and content_size properties
233 data: Data to set to the contents (string)
236 self.contents_size = len(self.data)
238 def ProcessContentsUpdate(self, data):
239 """Update the contens of an entry, after the size is fixed
241 This checks that the new data is the same size as the old.
244 data: Data to set to the contents (string)
247 ValueError if the new data size is not the same as the old
249 if len(data) != self.contents_size:
250 self.Raise('Cannot update entry size from %d to %d' %
251 (len(data), self.contents_size))
252 self.SetContents(data)
254 def ObtainContents(self):
255 """Figure out the contents of an entry.
258 True if the contents were found, False if another call is needed
259 after the other entries are processed.
261 # No contents by default: subclasses can implement this
264 def Pack(self, offset):
265 """Figure out how to pack the entry into the section
267 Most of the time the entries are not fully specified. There may be
268 an alignment but no size. In that case we take the size from the
269 contents of the entry.
271 If an entry has no hard-coded offset, it will be placed at @offset.
273 Once this function is complete, both the offset and size of the
277 Current section offset pointer
280 New section offset pointer (after this entry)
282 if self.offset is None:
283 if self.offset_unset:
284 self.Raise('No offset set with offset-unset: should another '
285 'entry provide this correct offset?')
286 self.offset = tools.Align(offset, self.align)
287 needed = self.pad_before + self.contents_size + self.pad_after
288 needed = tools.Align(needed, self.align_size)
292 new_offset = self.offset + size
293 aligned_offset = tools.Align(new_offset, self.align_end)
294 if aligned_offset != new_offset:
295 size = aligned_offset - self.offset
296 new_offset = aligned_offset
301 if self.size < needed:
302 self.Raise("Entry contents size is %#x (%d) but entry size is "
303 "%#x (%d)" % (needed, needed, self.size, self.size))
304 # Check that the alignment is correct. It could be wrong if the
305 # and offset or size values were provided (i.e. not calculated), but
306 # conflict with the provided alignment values
307 if self.size != tools.Align(self.size, self.align_size):
308 self.Raise("Size %#x (%d) does not match align-size %#x (%d)" %
309 (self.size, self.size, self.align_size, self.align_size))
310 if self.offset != tools.Align(self.offset, self.align):
311 self.Raise("Offset %#x (%d) does not match align %#x (%d)" %
312 (self.offset, self.offset, self.align, self.align))
316 def Raise(self, msg):
317 """Convenience function to raise an error referencing a node"""
318 raise ValueError("Node '%s': %s" % (self._node.path, msg))
320 def GetEntryArgsOrProps(self, props, required=False):
321 """Return the values of a set of properties
324 props: List of EntryArg objects
327 ValueError if a property is not found
332 python_prop = prop.name.replace('-', '_')
333 if hasattr(self, python_prop):
334 value = getattr(self, python_prop)
338 value = self.GetArg(prop.name, prop.datatype)
339 if value is None and required:
340 missing.append(prop.name)
343 self.Raise('Missing required properties/entry args: %s' %
344 (', '.join(missing)))
348 """Get the path of a node
351 Full path of the node for this entry
353 return self._node.path
358 def GetOffsets(self):
361 def SetOffsetSize(self, pos, size):
365 def SetImagePos(self, image_pos):
366 """Set the position in the image
369 image_pos: Position of this entry in the image
371 self.image_pos = image_pos + self.offset
373 def ProcessContents(self):
376 def WriteSymbols(self, section):
377 """Write symbol values into binary files for access at run time
380 section: Section containing the entry
384 def CheckOffset(self):
385 """Check that the entry offsets are correct
387 This is used for entries which have extra offset requirements (other
388 than having to be fully inside their section). Sub-classes can implement
389 this function and raise if there is a problem.
397 return '%08x' % value
400 def WriteMapLine(fd, indent, name, offset, size, image_pos):
401 print('%s %s%s %s %s' % (Entry.GetStr(image_pos), ' ' * indent,
402 Entry.GetStr(offset), Entry.GetStr(size),
405 def WriteMap(self, fd, indent):
406 """Write a map of the entry to a .map file
409 fd: File to write the map to
410 indent: Curent indent level of map (0=none, 1=one level, etc.)
412 self.WriteMapLine(fd, indent, self.name, self.offset, self.size,
415 def GetEntries(self):
416 """Return a list of entries contained by this entry
419 List of entries, or None if none. A normal entry has no entries
420 within it so will return None
424 def GetArg(self, name, datatype=str):
425 """Get the value of an entry argument or device-tree-node property
427 Some node properties can be provided as arguments to binman. First check
428 the entry arguments, and fall back to the device tree if not found
432 datatype: Data type (str or int)
435 Value of argument as a string or int, or None if no value
438 ValueError if the argument cannot be converted to in
440 value = state.GetEntryArg(name)
441 if value is not None:
446 self.Raise("Cannot convert entry arg '%s' (value '%s') to integer" %
448 elif datatype == str:
451 raise ValueError("GetArg() internal error: Unknown data type '%s'" %
454 value = fdt_util.GetDatatype(self._node, name, datatype)
458 def WriteDocs(modules, test_missing=None):
459 """Write out documentation about the various entry types to stdout
462 modules: List of modules to include
463 test_missing: Used for testing. This is a module to report
466 print('''Binman Entry Documentation
467 ===========================
469 This file describes the entry types supported by binman. These entry types can
470 be placed in an image one by one to build up a final firmware image. It is
471 fairly easy to create new entry types. Just add a new file to the 'etype'
472 directory. You can use the existing entries as examples.
474 Note that some entries are subclasses of others, using and extending their
475 features to produce new behaviours.
479 modules = sorted(modules)
481 # Don't show the test entry
482 if '_testing' in modules:
483 modules.remove('_testing')
486 module = Entry.Lookup(name, name, name)
487 docs = getattr(module, '__doc__')
488 if test_missing == name:
491 lines = docs.splitlines()
492 first_line = lines[0]
493 rest = [line[4:] for line in lines[1:]]
494 hdr = 'Entry: %s: %s' % (name.replace('_', '-'), first_line)
496 print('-' * len(hdr))
497 print('\n'.join(rest))
504 raise ValueError('Documentation is missing for modules: %s' %
507 def GetUniqueName(self):
508 """Get a unique name for a node
511 String containing a unique name for a node, consisting of the name
512 of all ancestors (starting from within the 'binman' node) separated
513 by a dot ('.'). This can be useful for generating unique filesnames
514 in the output directory.
520 if node.name == 'binman':
522 name = '%s.%s' % (node.name, name)
525 def ExpandToLimit(self, limit):
526 """Expand an entry so that it ends at the given offset limit"""
527 if self.offset + self.size < limit:
528 self.size = limit - self.offset
529 # Request the contents again, since changing the size requires that
530 # the data grows. This should not fail, but check it to be sure.
531 if not self.ObtainContents():
532 self.Raise('Cannot obtain contents when expanding entry')