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
28 our_path = os.path.dirname(os.path.realpath(__file__))
31 # An argument which can be passed to entries on the command line, in lieu of
32 # device-tree properties.
33 EntryArg = namedtuple('EntryArg', ['name', 'datatype'])
37 """An Entry in the section
39 An entry corresponds to a single node in the device-tree description
40 of the section. Each entry ends up being a part of the final section.
41 Entries can be placed either right next to each other, or with padding
42 between them. The type of the entry determines the data that is in it.
44 This class is not used by itself. All entry objects are subclasses of
48 section: Section object containing this entry
49 node: The node that created this entry
50 offset: Offset of entry within the section, None if not known yet (in
51 which case it will be calculated by Pack())
52 size: Entry size in bytes, None if not known
53 contents_size: Size of contents in bytes, 0 by default
54 align: Entry start offset alignment, or None
55 align_size: Entry size alignment, or None
56 align_end: Entry end offset alignment, or None
57 pad_before: Number of pad bytes before the contents, 0 if none
58 pad_after: Number of pad bytes after the contents, 0 if none
59 data: Contents of entry (string of bytes)
61 def __init__(self, section, etype, node, read_node=True, name_prefix=''):
62 self.section = section
65 self.name = node and (name_prefix + node.name) or 'none'
69 self.contents_size = 0
71 self.align_size = None
75 self.offset_unset = False
81 def Lookup(section, node_path, etype):
82 """Look up the entry class for a node.
85 section: Section object containing this node
86 node_node: Path name of Node object containing information about
87 the entry to create (used for errors)
88 etype: Entry type to use
91 The entry class object if found, else None
93 # Convert something like 'u-boot@0' to 'u_boot' since we are only
94 # interested in the type.
95 module_name = etype.replace('-', '_')
96 if '@' in module_name:
97 module_name = module_name.split('@')[0]
98 module = modules.get(module_name)
100 # Also allow entry-type modules to be brought in from the etype directory.
102 # Import the module if we have not already done so.
105 sys.path.insert(0, os.path.join(our_path, 'etype'))
108 module = importlib.import_module(module_name)
110 module = __import__(module_name)
111 except ImportError as e:
112 raise ValueError("Unknown entry type '%s' in node '%s' (expected etype/%s.py, error '%s'" %
113 (etype, node_path, module_name, e))
116 modules[module_name] = module
118 # Look up the expected class name
119 return getattr(module, 'Entry_%s' % module_name)
122 def Create(section, node, etype=None):
123 """Create a new entry for a node.
126 section: Section object containing this node
127 node: Node object containing information about the entry to
129 etype: Entry type to use, or None to work it out (used for tests)
132 A new Entry object of the correct type (a subclass of Entry)
135 etype = fdt_util.GetString(node, 'type', node.name)
136 obj = Entry.Lookup(section, node.path, etype)
138 # Call its constructor to get the object we want.
139 return obj(section, etype, node)
142 """Read entry information from the node
144 This reads all the fields we recognise from the node, ready for use.
146 if 'pos' in self._node.props:
147 self.Raise("Please use 'offset' instead of 'pos'")
148 self.offset = fdt_util.GetInt(self._node, 'offset')
149 self.size = fdt_util.GetInt(self._node, 'size')
150 self.align = fdt_util.GetInt(self._node, 'align')
151 if tools.NotPowerOfTwo(self.align):
152 raise ValueError("Node '%s': Alignment %s must be a power of two" %
153 (self._node.path, self.align))
154 self.pad_before = fdt_util.GetInt(self._node, 'pad-before', 0)
155 self.pad_after = fdt_util.GetInt(self._node, 'pad-after', 0)
156 self.align_size = fdt_util.GetInt(self._node, 'align-size')
157 if tools.NotPowerOfTwo(self.align_size):
158 raise ValueError("Node '%s': Alignment size %s must be a power "
159 "of two" % (self._node.path, self.align_size))
160 self.align_end = fdt_util.GetInt(self._node, 'align-end')
161 self.offset_unset = fdt_util.GetBool(self._node, 'offset-unset')
163 def AddMissingProperties(self):
164 """Add new properties to the device tree as needed for this entry"""
165 for prop in ['offset', 'size', 'image-pos']:
166 if not prop in self._node.props:
167 self._node.AddZeroProp(prop)
169 def SetCalculatedProperties(self):
170 """Set the value of device-tree properties calculated by binman"""
171 self._node.SetInt('offset', self.offset)
172 self._node.SetInt('size', self.size)
173 self._node.SetInt('image-pos', self.image_pos)
175 def ProcessFdt(self, fdt):
178 def SetPrefix(self, prefix):
179 """Set the name prefix for a node
182 prefix: Prefix to set, or '' to not use a prefix
185 self.name = prefix + self.name
187 def SetContents(self, data):
188 """Set the contents of an entry
190 This sets both the data and content_size properties
193 data: Data to set to the contents (string)
196 self.contents_size = len(self.data)
198 def ProcessContentsUpdate(self, data):
199 """Update the contens of an entry, after the size is fixed
201 This checks that the new data is the same size as the old.
204 data: Data to set to the contents (string)
207 ValueError if the new data size is not the same as the old
209 if len(data) != self.contents_size:
210 self.Raise('Cannot update entry size from %d to %d' %
211 (len(data), self.contents_size))
212 self.SetContents(data)
214 def ObtainContents(self):
215 """Figure out the contents of an entry.
218 True if the contents were found, False if another call is needed
219 after the other entries are processed.
221 # No contents by default: subclasses can implement this
224 def Pack(self, offset):
225 """Figure out how to pack the entry into the section
227 Most of the time the entries are not fully specified. There may be
228 an alignment but no size. In that case we take the size from the
229 contents of the entry.
231 If an entry has no hard-coded offset, it will be placed at @offset.
233 Once this function is complete, both the offset and size of the
237 Current section offset pointer
240 New section offset pointer (after this entry)
242 if self.offset is None:
243 if self.offset_unset:
244 self.Raise('No offset set with offset-unset: should another '
245 'entry provide this correct offset?')
246 self.offset = tools.Align(offset, self.align)
247 needed = self.pad_before + self.contents_size + self.pad_after
248 needed = tools.Align(needed, self.align_size)
252 new_offset = self.offset + size
253 aligned_offset = tools.Align(new_offset, self.align_end)
254 if aligned_offset != new_offset:
255 size = aligned_offset - self.offset
256 new_offset = aligned_offset
261 if self.size < needed:
262 self.Raise("Entry contents size is %#x (%d) but entry size is "
263 "%#x (%d)" % (needed, needed, self.size, self.size))
264 # Check that the alignment is correct. It could be wrong if the
265 # and offset or size values were provided (i.e. not calculated), but
266 # conflict with the provided alignment values
267 if self.size != tools.Align(self.size, self.align_size):
268 self.Raise("Size %#x (%d) does not match align-size %#x (%d)" %
269 (self.size, self.size, self.align_size, self.align_size))
270 if self.offset != tools.Align(self.offset, self.align):
271 self.Raise("Offset %#x (%d) does not match align %#x (%d)" %
272 (self.offset, self.offset, self.align, self.align))
276 def Raise(self, msg):
277 """Convenience function to raise an error referencing a node"""
278 raise ValueError("Node '%s': %s" % (self._node.path, msg))
280 def GetEntryArgsOrProps(self, props, required=False):
281 """Return the values of a set of properties
284 props: List of EntryArg objects
287 ValueError if a property is not found
292 python_prop = prop.name.replace('-', '_')
293 if hasattr(self, python_prop):
294 value = getattr(self, python_prop)
298 value = self.GetArg(prop.name, prop.datatype)
299 if value is None and required:
300 missing.append(prop.name)
303 self.Raise('Missing required properties/entry args: %s' %
304 (', '.join(missing)))
308 """Get the path of a node
311 Full path of the node for this entry
313 return self._node.path
318 def GetOffsets(self):
321 def SetOffsetSize(self, pos, size):
325 def SetImagePos(self, image_pos):
326 """Set the position in the image
329 image_pos: Position of this entry in the image
331 self.image_pos = image_pos + self.offset
333 def ProcessContents(self):
336 def WriteSymbols(self, section):
337 """Write symbol values into binary files for access at run time
340 section: Section containing the entry
344 def CheckOffset(self):
345 """Check that the entry offsets are correct
347 This is used for entries which have extra offset requirements (other
348 than having to be fully inside their section). Sub-classes can implement
349 this function and raise if there is a problem.
354 def WriteMapLine(fd, indent, name, offset, size, image_pos):
355 print('%08x %s%08x %08x %s' % (image_pos, ' ' * indent, offset,
356 size, name), file=fd)
358 def WriteMap(self, fd, indent):
359 """Write a map of the entry to a .map file
362 fd: File to write the map to
363 indent: Curent indent level of map (0=none, 1=one level, etc.)
365 self.WriteMapLine(fd, indent, self.name, self.offset, self.size,
368 def GetEntries(self):
369 """Return a list of entries contained by this entry
372 List of entries, or None if none. A normal entry has no entries
373 within it so will return None
377 def GetArg(self, name, datatype=str):
378 """Get the value of an entry argument or device-tree-node property
380 Some node properties can be provided as arguments to binman. First check
381 the entry arguments, and fall back to the device tree if not found
385 datatype: Data type (str or int)
388 Value of argument as a string or int, or None if no value
391 ValueError if the argument cannot be converted to in
393 value = control.GetEntryArg(name)
394 if value is not None:
399 self.Raise("Cannot convert entry arg '%s' (value '%s') to integer" %
401 elif datatype == str:
404 raise ValueError("GetArg() internal error: Unknown data type '%s'" %
407 value = fdt_util.GetDatatype(self._node, name, datatype)
411 def WriteDocs(modules, test_missing=None):
412 """Write out documentation about the various entry types to stdout
415 modules: List of modules to include
416 test_missing: Used for testing. This is a module to report
419 print('''Binman Entry Documentation
420 ===========================
422 This file describes the entry types supported by binman. These entry types can
423 be placed in an image one by one to build up a final firmware image. It is
424 fairly easy to create new entry types. Just add a new file to the 'etype'
425 directory. You can use the existing entries as examples.
427 Note that some entries are subclasses of others, using and extending their
428 features to produce new behaviours.
432 modules = sorted(modules)
434 # Don't show the test entry
435 if '_testing' in modules:
436 modules.remove('_testing')
439 module = Entry.Lookup(name, name, name)
440 docs = getattr(module, '__doc__')
441 if test_missing == name:
444 lines = docs.splitlines()
445 first_line = lines[0]
446 rest = [line[4:] for line in lines[1:]]
447 hdr = 'Entry: %s: %s' % (name.replace('_', '-'), first_line)
449 print('-' * len(hdr))
450 print('\n'.join(rest))
457 raise ValueError('Documentation is missing for modules: %s' %
460 def GetUniqueName(self):
461 """Get a unique name for a node
464 String containing a unique name for a node, consisting of the name
465 of all ancestors (starting from within the 'binman' node) separated
466 by a dot ('.'). This can be useful for generating unique filesnames
467 in the output directory.
473 if node.name == 'binman':
475 name = '%s.%s' % (node.name, name)