tools/binman/image.py

   1 # SPDX-License-Identifier: GPL-2.0+
   2 # Copyright (c) 2016 Google, Inc
   3 # Written by Simon Glass <sjg@chromium.org>
   4 #
   5 # Class for an image, the output of binman
   6 #
   7
   8 from __future__ import print_function
   9
  10 from collections import OrderedDict
  11 from operator import attrgetter
  12 import re
  13 import sys
  14
  15 import fdt_util
  16 import bsection
  17 import tools
  18
  19 class Image:
  20     """A Image, representing an output from binman
  21
  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.
  24
  25     This class implements the various operations needed for images.
  26
  27     Atrtributes:
  28         _node: Node object that contains the image definition in device tree
  29         _name: Image name
  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)
  33
  34     Args:
  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.
  38     """
  39     def __init__(self, name, node, test=False):
  40         self._node = node
  41         self._name = name
  42         self._size = None
  43         self._filename = '%s.bin' % self._name
  44         if test:
  45             self._section = bsection.Section('main-section', None, self._node,
  46                                              self, True)
  47         else:
  48             self._ReadNode()
  49
  50     def _ReadNode(self):
  51         """Read properties from the image node"""
  52         self._size = fdt_util.GetInt(self._node, 'size')
  53         filename = fdt_util.GetString(self._node, 'filename')
  54         if filename:
  55             self._filename = filename
  56         self._section = bsection.Section('main-section', None, self._node, self)
  57
  58     def Raise(self, msg):
  59         """Convenience function to raise an error referencing an image"""
  60         raise ValueError("Image '%s': %s" % (self._node.path, msg))
  61
  62     def GetFdtSet(self):
  63         """Get the set of device tree files used by this image"""
  64         return self._section.GetFdtSet()
  65
  66     def ExpandEntries(self):
  67         """Expand out any entries which have calculated sub-entries
  68
  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.
  72         """
  73         self._section.ExpandEntries()
  74
  75     def AddMissingProperties(self):
  76         """Add properties that are not present in the device tree
  77
  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
  82         later.
  83         """
  84         self._section.AddMissingProperties()
  85
  86     def ProcessFdt(self, fdt):
  87         """Allow entries to adjust the device tree
  88
  89         Some entries need to adjust the device tree for their purposes. This
  90         may involve adding or deleting properties.
  91         """
  92         return self._section.ProcessFdt(fdt)
  93
  94     def GetEntryContents(self):
  95         """Call ObtainContents() for the section
  96         """
  97         self._section.GetEntryContents()
  98
  99     def GetEntryOffsets(self):
 100         """Handle entries that want to set the offset/size of other entries
 101
 102         This calls each entry's GetOffsets() method. If it returns a list
 103         of entries to update, it updates them.
 104         """
 105         self._section.GetEntryOffsets()
 106
 107     def ResetForPack(self):
 108         """Reset offset/size fields so that packing can be done again"""
 109         self._section.ResetForPack()
 110
 111     def PackEntries(self):
 112         """Pack all entries into the image"""
 113         self._section.PackEntries()
 114
 115     def CheckSize(self):
 116         """Check that the image contents does not exceed its size, etc."""
 117         self._size = self._section.CheckSize()
 118
 119     def CheckEntries(self):
 120         """Check that entries do not overlap or extend outside the image"""
 121         self._section.CheckEntries()
 122
 123     def SetCalculatedProperties(self):
 124         self._section.SetCalculatedProperties()
 125
 126     def SetImagePos(self):
 127         self._section.SetImagePos(0)
 128
 129     def ProcessEntryContents(self):
 130         """Call the ProcessContents() method for each entry
 131
 132         This is intended to adjust the contents as needed by the entry type.
 133
 134         Returns:
 135             True if the new data size is OK, False if expansion is needed
 136         """
 137         return self._section.ProcessEntryContents()
 138
 139     def WriteSymbols(self):
 140         """Write symbol values into binary files for access at run time"""
 141         self._section.WriteSymbols()
 142
 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)
 148
 149     def GetEntries(self):
 150         return self._section.GetEntries()
 151
 152     def WriteMap(self):
 153         """Write a map of the image to a .map file
 154
 155         Returns:
 156             Filename of map file written
 157         """
 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'),
 162                   file=fd)
 163             self._section.WriteMap(fd, 0)
 164         return fname