tools/binman/etype/cbfs.py

   1 # SPDX-License-Identifier: GPL-2.0+
   2 # Copyright 2019 Google LLC
   3 # Written by Simon Glass <sjg@chromium.org>
   4 #
   5 # Entry-type module for a Coreboot Filesystem (CBFS)
   6 #
   7
   8 from collections import OrderedDict
   9
  10 import cbfs_util
  11 from cbfs_util import CbfsWriter
  12 from entry import Entry
  13 import fdt_util
  14 import state
  15
  16 class Entry_cbfs(Entry):
  17     """Entry containing a Coreboot Filesystem (CBFS)
  18
  19     A CBFS provides a way to group files into a group. It has a simple directory
  20     structure and allows the position of individual files to be set, since it is
  21     designed to support execute-in-place in an x86 SPI-flash device. Where XIP
  22     is not used, it supports compression and storing ELF files.
  23
  24     CBFS is used by coreboot as its way of orgnanising SPI-flash contents.
  25
  26     The contents of the CBFS are defined by subnodes of the cbfs entry, e.g.:
  27
  28         cbfs {
  29             size = <0x100000>;
  30             u-boot {
  31                 cbfs-type = "raw";
  32             };
  33             u-boot-dtb {
  34                 cbfs-type = "raw";
  35             };
  36         };
  37
  38     This creates a CBFS 1MB in size two files in it: u-boot.bin and u-boot.dtb.
  39     Note that the size is required since binman does not support calculating it.
  40     The contents of each entry is just what binman would normally provide if it
  41     were not a CBFS node. A blob type can be used to import arbitrary files as
  42     with the second subnode below:
  43
  44         cbfs {
  45             size = <0x100000>;
  46             u-boot {
  47                 cbfs-name = "BOOT";
  48                 cbfs-type = "raw";
  49             };
  50
  51             dtb {
  52                 type = "blob";
  53                 filename = "u-boot.dtb";
  54                 cbfs-type = "raw";
  55                 cbfs-compress = "lz4";
  56                 cbfs-offset = <0x100000>;
  57             };
  58         };
  59
  60     This creates a CBFS 1MB in size with u-boot.bin (named "BOOT") and
  61     u-boot.dtb (named "dtb") and compressed with the lz4 algorithm.
  62
  63
  64     Properties supported in the top-level CBFS node:
  65
  66     cbfs-arch:
  67         Defaults to "x86", but you can specify the architecture if needed.
  68
  69
  70     Properties supported in the CBFS entry subnodes:
  71
  72     cbfs-name:
  73         This is the name of the file created in CBFS. It defaults to the entry
  74         name (which is the node name), but you can override it with this
  75         property.
  76
  77     cbfs-type:
  78         This is the CBFS file type. The following are supported:
  79
  80         raw:
  81             This is a 'raw' file, although compression is supported. It can be
  82             used to store any file in CBFS.
  83
  84         stage:
  85             This is an ELF file that has been loaded (i.e. mapped to memory), so
  86             appears in the CBFS as a flat binary. The input file must be an ELF
  87             image, for example this puts "u-boot" (the ELF image) into a 'stage'
  88             entry:
  89
  90                 cbfs {
  91                     size = <0x100000>;
  92                     u-boot-elf {
  93                         cbfs-name = "BOOT";
  94                         cbfs-type = "stage";
  95                     };
  96                 };
  97
  98             You can use your own ELF file with something like:
  99
 100                 cbfs {
 101                     size = <0x100000>;
 102                     something {
 103                         type = "blob";
 104                         filename = "cbfs-stage.elf";
 105                         cbfs-type = "stage";
 106                     };
 107                 };
 108
 109             As mentioned, the file is converted to a flat binary, so it is
 110             equivalent to adding "u-boot.bin", for example, but with the load and
 111             start addresses specified by the ELF. At present there is no option
 112             to add a flat binary with a load/start address, similar to the
 113             'add-flat-binary' option in cbfstool.
 114
 115     cbfs-offset:
 116         This is the offset of the file's data within the CBFS. It is used to
 117         specify where the file should be placed in cases where a fixed position
 118         is needed. Typical uses are for code which is not relocatable and must
 119         execute in-place from a particular address. This works because SPI flash
 120         is generally mapped into memory on x86 devices. The file header is
 121         placed before this offset so that the data start lines up exactly with
 122         the chosen offset. If this property is not provided, then the file is
 123         placed in the next available spot.
 124
 125     The current implementation supports only a subset of CBFS features. It does
 126     not support other file types (e.g. payload), adding multiple files (like the
 127     'files' entry with a pattern supported by binman), putting files at a
 128     particular offset in the CBFS and a few other things.
 129
 130     Of course binman can create images containing multiple CBFSs, simply by
 131     defining these in the binman config:
 132
 133
 134         binman {
 135             size = <0x800000>;
 136             cbfs {
 137                 offset = <0x100000>;
 138                 size = <0x100000>;
 139                 u-boot {
 140                     cbfs-type = "raw";
 141                 };
 142                 u-boot-dtb {
 143                     cbfs-type = "raw";
 144                 };
 145             };
 146
 147             cbfs2 {
 148                 offset = <0x700000>;
 149                 size = <0x100000>;
 150                 u-boot {
 151                     cbfs-type = "raw";
 152                 };
 153                 u-boot-dtb {
 154                     cbfs-type = "raw";
 155                 };
 156                 image {
 157                     type = "blob";
 158                     filename = "image.jpg";
 159                 };
 160             };
 161         };
 162
 163     This creates an 8MB image with two CBFSs, one at offset 1MB, one at 7MB,
 164     both of size 1MB.
 165     """
 166     def __init__(self, section, etype, node):
 167         Entry.__init__(self, section, etype, node)
 168         self._cbfs_arg = fdt_util.GetString(node, 'cbfs-arch', 'x86')
 169         self._cbfs_entries = OrderedDict()
 170         self._ReadSubnodes()
 171
 172     def ObtainContents(self):
 173         arch = cbfs_util.find_arch(self._cbfs_arg)
 174         if arch is None:
 175             self.Raise("Invalid architecture '%s'" % self._cbfs_arg)
 176         if self.size is None:
 177             self.Raise("'cbfs' entry must have a size property")
 178         cbfs = CbfsWriter(self.size, arch)
 179         for entry in self._cbfs_entries.values():
 180             # First get the input data and put it in a file. If not available,
 181             # try later.
 182             if not entry.ObtainContents():
 183                 return False
 184             data = entry.GetData()
 185             cfile = None
 186             if entry._type == 'raw':
 187                 cfile = cbfs.add_file_raw(entry._cbfs_name, data,
 188                                           entry._cbfs_offset,
 189                                           entry._cbfs_compress)
 190             elif entry._type == 'stage':
 191                 cfile = cbfs.add_file_stage(entry._cbfs_name, data,
 192                                             entry._cbfs_offset)
 193             else:
 194                 entry.Raise("Unknown cbfs-type '%s' (use 'raw', 'stage')" %
 195                             entry._type)
 196             if cfile:
 197                 entry._cbfs_file = cfile
 198         data = cbfs.get_data()
 199         self.SetContents(data)
 200         return True
 201
 202     def _ReadSubnodes(self):
 203         """Read the subnodes to find out what should go in this IFWI"""
 204         for node in self._node.subnodes:
 205             entry = Entry.Create(self.section, node)
 206             entry.ReadNode()
 207             entry._cbfs_name = fdt_util.GetString(node, 'cbfs-name', entry.name)
 208             entry._type = fdt_util.GetString(node, 'cbfs-type')
 209             compress = fdt_util.GetString(node, 'cbfs-compress', 'none')
 210             entry._cbfs_offset = fdt_util.GetInt(node, 'cbfs-offset')
 211             entry._cbfs_compress = cbfs_util.find_compress(compress)
 212             if entry._cbfs_compress is None:
 213                 self.Raise("Invalid compression in '%s': '%s'" %
 214                            (node.name, compress))
 215             self._cbfs_entries[entry._cbfs_name] = entry
 216
 217     def SetImagePos(self, image_pos):
 218         """Override this function to set all the entry properties from CBFS
 219
 220         We can only do this once image_pos is known
 221
 222         Args:
 223             image_pos: Position of this entry in the image
 224         """
 225         Entry.SetImagePos(self, image_pos)
 226
 227         # Now update the entries with info from the CBFS entries
 228         for entry in self._cbfs_entries.values():
 229             cfile = entry._cbfs_file
 230             entry.size = cfile.data_len
 231             entry.offset = cfile.calced_cbfs_offset
 232             entry.image_pos = self.image_pos + entry.offset
 233             if entry._cbfs_compress:
 234                 entry.uncomp_size = cfile.memlen
 235
 236     def AddMissingProperties(self):
 237         Entry.AddMissingProperties(self)
 238         for entry in self._cbfs_entries.values():
 239             entry.AddMissingProperties()
 240             if entry._cbfs_compress:
 241                 state.AddZeroProp(entry._node, 'uncomp-size')
 242                 # Store the 'compress' property, since we don't look at
 243                 # 'cbfs-compress' in Entry.ReadData()
 244                 state.AddString(entry._node, 'compress',
 245                                 cbfs_util.compress_name(entry._cbfs_compress))
 246
 247     def SetCalculatedProperties(self):
 248         """Set the value of device-tree properties calculated by binman"""
 249         Entry.SetCalculatedProperties(self)
 250         for entry in self._cbfs_entries.values():
 251             state.SetInt(entry._node, 'offset', entry.offset)
 252             state.SetInt(entry._node, 'size', entry.size)
 253             state.SetInt(entry._node, 'image-pos', entry.image_pos)
 254             if entry.uncomp_size is not None:
 255                 state.SetInt(entry._node, 'uncomp-size', entry.uncomp_size)
 256
 257     def ListEntries(self, entries, indent):
 258         """Override this method to list all files in the section"""
 259         Entry.ListEntries(self, entries, indent)
 260         for entry in self._cbfs_entries.values():
 261             entry.ListEntries(entries, indent + 1)
 262
 263     def GetEntries(self):
 264         return self._cbfs_entries