xref: /openbmc/u-boot/tools/binman/entry.py (revision 592cd5de)
1# SPDX-License-Identifier: GPL-2.0+
2# Copyright (c) 2016 Google, Inc
3#
4# Base class for all entries
5#
6
7from __future__ import print_function
8
9from collections import namedtuple
10
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
14try:
15    import importlib
16    have_importlib = True
17except:
18    have_importlib = False
19
20import os
21from sets import Set
22import sys
23
24import fdt_util
25import state
26import tools
27
28modules = {}
29
30our_path = os.path.dirname(os.path.realpath(__file__))
31
32
33# An argument which can be passed to entries on the command line, in lieu of
34# device-tree properties.
35EntryArg = namedtuple('EntryArg', ['name', 'datatype'])
36
37
38class Entry(object):
39    """An Entry in the section
40
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.
45
46    This class is not used by itself. All entry objects are subclasses of
47    Entry.
48
49    Attributes:
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)
62    """
63    def __init__(self, section, etype, node, read_node=True, name_prefix=''):
64        self.section = section
65        self.etype = etype
66        self._node = node
67        self.name = node and (name_prefix + node.name) or 'none'
68        self.offset = None
69        self.size = None
70        self.data = None
71        self.contents_size = 0
72        self.align = None
73        self.align_size = None
74        self.align_end = None
75        self.pad_before = 0
76        self.pad_after = 0
77        self.offset_unset = False
78        self.image_pos = None
79        self._expand_size = False
80        if read_node:
81            self.ReadNode()
82
83    @staticmethod
84    def Lookup(section, node_path, etype):
85        """Look up the entry class for a node.
86
87        Args:
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
92
93        Returns:
94            The entry class object if found, else None
95        """
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)
102
103        # Also allow entry-type modules to be brought in from the etype directory.
104
105        # Import the module if we have not already done so.
106        if not module:
107            old_path = sys.path
108            sys.path.insert(0, os.path.join(our_path, 'etype'))
109            try:
110                if have_importlib:
111                    module = importlib.import_module(module_name)
112                else:
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))
117            finally:
118                sys.path = old_path
119            modules[module_name] = module
120
121        # Look up the expected class name
122        return getattr(module, 'Entry_%s' % module_name)
123
124    @staticmethod
125    def Create(section, node, etype=None):
126        """Create a new entry for a node.
127
128        Args:
129            section: Section object containing this node
130            node:    Node object containing information about the entry to
131                     create
132            etype:   Entry type to use, or None to work it out (used for tests)
133
134        Returns:
135            A new Entry object of the correct type (a subclass of Entry)
136        """
137        if not etype:
138            etype = fdt_util.GetString(node, 'type', node.name)
139        obj = Entry.Lookup(section, node.path, etype)
140
141        # Call its constructor to get the object we want.
142        return obj(section, etype, node)
143
144    def ReadNode(self):
145        """Read entry information from the node
146
147        This reads all the fields we recognise from the node, ready for use.
148        """
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')
166
167    def GetDefaultFilename(self):
168        return None
169
170    def GetFdtSet(self):
171        """Get the set of device trees used by this entry
172
173        Returns:
174            Set containing the filename from this entry, if it is a .dtb, else
175            an empty set
176        """
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'):
181            return Set([fname])
182        return Set()
183
184    def ExpandEntries(self):
185        pass
186
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)
193        if err:
194            self.Raise(err)
195
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)
203
204    def ProcessFdt(self, fdt):
205        """Allow entries to adjust the device tree
206
207        Some entries need to adjust the device tree for their purposes. This
208        may involve adding or deleting properties.
209
210        Returns:
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
214                called
215        """
216        return True
217
218    def SetPrefix(self, prefix):
219        """Set the name prefix for a node
220
221        Args:
222            prefix: Prefix to set, or '' to not use a prefix
223        """
224        if prefix:
225            self.name = prefix + self.name
226
227    def SetContents(self, data):
228        """Set the contents of an entry
229
230        This sets both the data and content_size properties
231
232        Args:
233            data: Data to set to the contents (string)
234        """
235        self.data = data
236        self.contents_size = len(self.data)
237
238    def ProcessContentsUpdate(self, data):
239        """Update the contens of an entry, after the size is fixed
240
241        This checks that the new data is the same size as the old.
242
243        Args:
244            data: Data to set to the contents (string)
245
246        Raises:
247            ValueError if the new data size is not the same as the old
248        """
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)
253
254    def ObtainContents(self):
255        """Figure out the contents of an entry.
256
257        Returns:
258            True if the contents were found, False if another call is needed
259            after the other entries are processed.
260        """
261        # No contents by default: subclasses can implement this
262        return True
263
264    def Pack(self, offset):
265        """Figure out how to pack the entry into the section
266
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.
270
271        If an entry has no hard-coded offset, it will be placed at @offset.
272
273        Once this function is complete, both the offset and size of the
274        entry will be know.
275
276        Args:
277            Current section offset pointer
278
279        Returns:
280            New section offset pointer (after this entry)
281        """
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)
289        size = self.size
290        if not size:
291            size = needed
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
297
298        if not self.size:
299            self.size = size
300
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))
313
314        return new_offset
315
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))
319
320    def GetEntryArgsOrProps(self, props, required=False):
321        """Return the values of a set of properties
322
323        Args:
324            props: List of EntryArg objects
325
326        Raises:
327            ValueError if a property is not found
328        """
329        values = []
330        missing = []
331        for prop in props:
332            python_prop = prop.name.replace('-', '_')
333            if hasattr(self, python_prop):
334                value = getattr(self, python_prop)
335            else:
336                value = None
337            if value is None:
338                value = self.GetArg(prop.name, prop.datatype)
339            if value is None and required:
340                missing.append(prop.name)
341            values.append(value)
342        if missing:
343            self.Raise('Missing required properties/entry args: %s' %
344                       (', '.join(missing)))
345        return values
346
347    def GetPath(self):
348        """Get the path of a node
349
350        Returns:
351            Full path of the node for this entry
352        """
353        return self._node.path
354
355    def GetData(self):
356        return self.data
357
358    def GetOffsets(self):
359        return {}
360
361    def SetOffsetSize(self, pos, size):
362        self.offset = pos
363        self.size = size
364
365    def SetImagePos(self, image_pos):
366        """Set the position in the image
367
368        Args:
369            image_pos: Position of this entry in the image
370        """
371        self.image_pos = image_pos + self.offset
372
373    def ProcessContents(self):
374        pass
375
376    def WriteSymbols(self, section):
377        """Write symbol values into binary files for access at run time
378
379        Args:
380          section: Section containing the entry
381        """
382        pass
383
384    def CheckOffset(self):
385        """Check that the entry offsets are correct
386
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.
390        """
391        pass
392
393    @staticmethod
394    def GetStr(value):
395        if value is None:
396            return '<none>  '
397        return '%08x' % value
398
399    @staticmethod
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),
403                                    name), file=fd)
404
405    def WriteMap(self, fd, indent):
406        """Write a map of the entry to a .map file
407
408        Args:
409            fd: File to write the map to
410            indent: Curent indent level of map (0=none, 1=one level, etc.)
411        """
412        self.WriteMapLine(fd, indent, self.name, self.offset, self.size,
413                          self.image_pos)
414
415    def GetEntries(self):
416        """Return a list of entries contained by this entry
417
418        Returns:
419            List of entries, or None if none. A normal entry has no entries
420                within it so will return None
421        """
422        return None
423
424    def GetArg(self, name, datatype=str):
425        """Get the value of an entry argument or device-tree-node property
426
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
429
430        Args:
431            name: Argument name
432            datatype: Data type (str or int)
433
434        Returns:
435            Value of argument as a string or int, or None if no value
436
437        Raises:
438            ValueError if the argument cannot be converted to in
439        """
440        value = state.GetEntryArg(name)
441        if value is not None:
442            if datatype == int:
443                try:
444                    value = int(value)
445                except ValueError:
446                    self.Raise("Cannot convert entry arg '%s' (value '%s') to integer" %
447                               (name, value))
448            elif datatype == str:
449                pass
450            else:
451                raise ValueError("GetArg() internal error: Unknown data type '%s'" %
452                                 datatype)
453        else:
454            value = fdt_util.GetDatatype(self._node, name, datatype)
455        return value
456
457    @staticmethod
458    def WriteDocs(modules, test_missing=None):
459        """Write out documentation about the various entry types to stdout
460
461        Args:
462            modules: List of modules to include
463            test_missing: Used for testing. This is a module to report
464                as missing
465        """
466        print('''Binman Entry Documentation
467===========================
468
469This file describes the entry types supported by binman. These entry types can
470be placed in an image one by one to build up a final firmware image. It is
471fairly easy to create new entry types. Just add a new file to the 'etype'
472directory. You can use the existing entries as examples.
473
474Note that some entries are subclasses of others, using and extending their
475features to produce new behaviours.
476
477
478''')
479        modules = sorted(modules)
480
481        # Don't show the test entry
482        if '_testing' in modules:
483            modules.remove('_testing')
484        missing = []
485        for name in modules:
486            module = Entry.Lookup(name, name, name)
487            docs = getattr(module, '__doc__')
488            if test_missing == name:
489                docs = None
490            if docs:
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)
495                print(hdr)
496                print('-' * len(hdr))
497                print('\n'.join(rest))
498                print()
499                print()
500            else:
501                missing.append(name)
502
503        if missing:
504            raise ValueError('Documentation is missing for modules: %s' %
505                             ', '.join(missing))
506
507    def GetUniqueName(self):
508        """Get a unique name for a node
509
510        Returns:
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.
515        """
516        name = self.name
517        node = self._node
518        while node.parent:
519            node = node.parent
520            if node.name == 'binman':
521                break
522            name = '%s.%s' % (node.name, name)
523        return name
524
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')
533