]>
git.ipfire.org Git - thirdparty/u-boot.git/blob - tools/binman/etype/section.py
1 # SPDX-License-Identifier: GPL-2.0+
2 # Copyright (c) 2018 Google, Inc
3 # Written by Simon Glass <sjg@chromium.org>
5 """Entry-type module for sections (groups of entries)
7 Sections are entries which can contain other entries. This allows hierarchical
11 from collections
import OrderedDict
15 from binman
.entry
import Entry
16 from dtoc
import fdt_util
17 from patman
import tools
18 from patman
import tout
19 from patman
.tools
import ToHexSize
22 class Entry_section(Entry
):
23 """Entry that contains other entries
25 Properties / Entry arguments: (see binman README for more information)
26 pad-byte: Pad byte to use when padding
27 sort-by-offset: True if entries should be sorted by offset, False if
28 they must be in-order in the device tree description
29 end-at-4gb: Used to build an x86 ROM which ends at 4GB (2^32)
30 skip-at-start: Number of bytes before the first entry starts. These
31 effectively adjust the starting offset of entries. For example,
32 if this is 16, then the first entry would start at 16. An entry
33 with offset = 20 would in fact be written at offset 4 in the image
34 file, since the first 16 bytes are skipped when writing.
35 name-prefix: Adds a prefix to the name of every entry in the section
36 when writing out the map
39 allow_missing: True if this section permits external blobs to be
40 missing their contents. The second will produce an image but of
41 course it will not work.
43 Since a section is also an entry, it inherits all the properies of entries
46 A section is an entry which can contain other entries, thus allowing
47 hierarchical images to be created. See 'Sections and hierarchical images'
48 in the binman README for more information.
50 def __init__(self
, section
, etype
, node
, test
=False):
52 super().__init
__(section
, etype
, node
)
53 self
._entries
= OrderedDict()
56 self
._skip
_at
_start
= None
60 """Read properties from the section node"""
62 self
._pad
_byte
= fdt_util
.GetInt(self
._node
, 'pad-byte', 0)
63 self
._sort
= fdt_util
.GetBool(self
._node
, 'sort-by-offset')
64 self
._end
_4gb
= fdt_util
.GetBool(self
._node
, 'end-at-4gb')
65 self
._skip
_at
_start
= fdt_util
.GetInt(self
._node
, 'skip-at-start')
68 self
.Raise("Section size must be provided when using end-at-4gb")
69 if self
._skip
_at
_start
is not None:
70 self
.Raise("Provide either 'end-at-4gb' or 'skip-at-start'")
72 self
._skip
_at
_start
= 0x100000000 - self
.size
74 if self
._skip
_at
_start
is None:
75 self
._skip
_at
_start
= 0
76 self
._name
_prefix
= fdt_util
.GetString(self
._node
, 'name-prefix')
77 filename
= fdt_util
.GetString(self
._node
, 'filename')
79 self
._filename
= filename
83 def _ReadEntries(self
):
84 for node
in self
._node
.subnodes
:
85 if node
.name
.startswith('hash') or node
.name
.startswith('signature'):
87 entry
= Entry
.Create(self
, node
)
89 entry
.SetPrefix(self
._name
_prefix
)
90 self
._entries
[node
.name
] = entry
92 def _Raise(self
, msg
):
93 """Raises an error for this section
96 msg: Error message to use in the raise string
100 raise ValueError("Section '%s': %s" % (self
._node
.path
, msg
))
104 for entry
in self
._entries
.values():
105 fdts
.update(entry
.GetFdts())
108 def ProcessFdt(self
, fdt
):
109 """Allow entries to adjust the device tree
111 Some entries need to adjust the device tree for their purposes. This
112 may involve adding or deleting properties.
114 todo
= self
._entries
.values()
115 for passnum
in range(3):
118 if not entry
.ProcessFdt(fdt
):
119 next_todo
.append(entry
)
124 self
.Raise('Internal error: Could not complete processing of Fdt: remaining %s' %
128 def ExpandEntries(self
):
129 """Expand out any entries which have calculated sub-entries
131 Some entries are expanded out at runtime, e.g. 'files', which produces
132 a section containing a list of files. Process these entries so that
133 this information is added to the device tree.
135 super().ExpandEntries()
136 for entry
in self
._entries
.values():
137 entry
.ExpandEntries()
139 def AddMissingProperties(self
, have_image_pos
):
140 """Add new properties to the device tree as needed for this entry"""
141 super().AddMissingProperties(have_image_pos
)
142 if self
.compress
!= 'none':
143 have_image_pos
= False
144 for entry
in self
._entries
.values():
145 entry
.AddMissingProperties(have_image_pos
)
147 def ObtainContents(self
):
148 return self
.GetEntryContents()
150 def GetPaddedDataForEntry(self
, entry
):
151 """Get the data for an entry including any padding
153 Gets the entry data and uses the section pad-byte value to add padding
154 before and after as defined by the pad-before and pad-after properties.
155 This does not consider alignment.
158 entry: Entry to check
161 Contents of the entry along with any pad bytes before and
164 pad_byte
= (entry
._pad
_byte
if isinstance(entry
, Entry_section
)
168 # Handle padding before the entry
170 data
+= tools
.GetBytes(self
._pad
_byte
, entry
.pad_before
)
172 # Add in the actual entry data
173 data
+= entry
.GetData()
175 # Handle padding after the entry
177 data
+= tools
.GetBytes(self
._pad
_byte
, entry
.pad_after
)
180 data
+= tools
.GetBytes(pad_byte
, entry
.size
- len(data
))
182 self
.Detail('GetPaddedDataForEntry: size %s' % ToHexSize(self
.data
))
186 def _BuildSectionData(self
):
187 """Build the contents of a section
189 This places all entries at the right place, dealing with padding before
190 and after entries. It does not do padding for the section itself (the
191 pad-before and pad-after properties in the section items) since that is
192 handled by the parent section.
195 Contents of the section (bytes)
199 for entry
in self
._entries
.values():
200 data
= self
.GetPaddedDataForEntry(entry
)
201 # Handle empty space before the entry
202 pad
= (entry
.offset
or 0) - self
._skip
_at
_start
- len(section_data
)
204 section_data
+= tools
.GetBytes(self
._pad
_byte
, pad
)
206 # Add in the actual entry data
209 self
.Detail('GetData: %d entries, total size %#x' %
210 (len(self
._entries
), len(section_data
)))
211 return self
.CompressData(section_data
)
213 def GetPaddedData(self
):
214 """Get the data for a section including any padding
216 Gets the section data and uses the parent section's pad-byte value to
217 add padding before and after as defined by the pad-before and pad-after
218 properties. If this is a top-level section (i.e. an image), this is the
219 same as GetData(), since padding is not supported.
221 This does not consider alignment.
224 Contents of the section along with any pad bytes before and
227 section
= self
.section
or self
228 return section
.GetPaddedDataForEntry(self
)
231 """Get the contents of an entry
233 This builds the contents of the section, stores this as the contents of
234 the section and returns it
237 bytes content of the section, made up for all all of its subentries.
238 This excludes any padding. If the section is compressed, the
239 compressed data is returned
241 data
= self
._BuildSectionData
()
242 self
.SetContents(data
)
245 def GetOffsets(self
):
246 """Handle entries that want to set the offset/size of other entries
248 This calls each entry's GetOffsets() method. If it returns a list
249 of entries to update, it updates them.
251 self
.GetEntryOffsets()
254 def ResetForPack(self
):
255 """Reset offset/size fields so that packing can be done again"""
256 super().ResetForPack()
257 for entry
in self
._entries
.values():
260 def Pack(self
, offset
):
261 """Pack all entries into the section"""
265 self
._ExpandEntries
()
267 size
= self
.CheckSize()
270 offset
= super().Pack(offset
)
274 def _PackEntries(self
):
275 """Pack all entries into the section"""
276 offset
= self
._skip
_at
_start
277 for entry
in self
._entries
.values():
278 offset
= entry
.Pack(offset
)
281 def _ExpandEntries(self
):
282 """Expand any entries that are permitted to"""
284 for entry
in self
._entries
.values():
286 exp_entry
.ExpandToLimit(entry
.offset
)
288 if entry
.expand_size
:
291 exp_entry
.ExpandToLimit(self
.size
)
293 def _SortEntries(self
):
294 """Sort entries by offset"""
295 entries
= sorted(self
._entries
.values(), key
=lambda entry
: entry
.offset
)
296 self
._entries
.clear()
297 for entry
in entries
:
298 self
._entries
[entry
._node
.name
] = entry
300 def CheckEntries(self
):
301 """Check that entries do not overlap or extend outside the section"""
302 max_size
= self
.size
if self
.uncomp_size
is None else self
.uncomp_size
306 for entry
in self
._entries
.values():
308 if (entry
.offset
< self
._skip
_at
_start
or
309 entry
.offset
+ entry
.size
> self
._skip
_at
_start
+
311 entry
.Raise('Offset %#x (%d) size %#x (%d) is outside the '
312 "section '%s' starting at %#x (%d) "
314 (entry
.offset
, entry
.offset
, entry
.size
, entry
.size
,
315 self
._node
.path
, self
._skip
_at
_start
,
316 self
._skip
_at
_start
, max_size
, max_size
))
317 if entry
.offset
< offset
and entry
.size
:
318 entry
.Raise("Offset %#x (%d) overlaps with previous entry '%s' "
319 "ending at %#x (%d)" %
320 (entry
.offset
, entry
.offset
, prev_name
, offset
, offset
))
321 offset
= entry
.offset
+ entry
.size
322 prev_name
= entry
.GetPath()
324 def WriteSymbols(self
, section
):
325 """Write symbol values into binary files for access at run time"""
326 for entry
in self
._entries
.values():
327 entry
.WriteSymbols(self
)
329 def SetCalculatedProperties(self
):
330 super().SetCalculatedProperties()
331 for entry
in self
._entries
.values():
332 entry
.SetCalculatedProperties()
334 def SetImagePos(self
, image_pos
):
335 super().SetImagePos(image_pos
)
336 if self
.compress
== 'none':
337 for entry
in self
._entries
.values():
338 entry
.SetImagePos(image_pos
+ self
.offset
)
340 def ProcessContents(self
):
341 sizes_ok_base
= super(Entry_section
, self
).ProcessContents()
343 for entry
in self
._entries
.values():
344 if not entry
.ProcessContents():
346 return sizes_ok
and sizes_ok_base
348 def WriteMap(self
, fd
, indent
):
349 """Write a map of the section to a .map file
352 fd: File to write the map to
354 Entry
.WriteMapLine(fd
, indent
, self
.name
, self
.offset
or 0,
355 self
.size
, self
.image_pos
)
356 for entry
in self
._entries
.values():
357 entry
.WriteMap(fd
, indent
+ 1)
359 def GetEntries(self
):
362 def GetContentsByPhandle(self
, phandle
, source_entry
):
363 """Get the data contents of an entry specified by a phandle
365 This uses a phandle to look up a node and and find the entry
366 associated with it. Then it returnst he contents of that entry.
369 phandle: Phandle to look up (integer)
370 source_entry: Entry containing that phandle (used for error
374 data from associated entry (as a string), or None if not found
376 node
= self
._node
.GetFdt().LookupPhandle(phandle
)
378 source_entry
.Raise("Cannot find node for phandle %d" % phandle
)
379 for entry
in self
._entries
.values():
380 if entry
._node
== node
:
381 return entry
.GetData()
382 source_entry
.Raise("Cannot find entry for node '%s'" % node
.name
)
384 def LookupSymbol(self
, sym_name
, optional
, msg
, base_addr
):
385 """Look up a symbol in an ELF file
387 Looks up a symbol in an ELF file. Only entry types which come from an
388 ELF image can be used by this function.
390 At present the only entry properties supported are:
392 image_pos - 'base_addr' is added if this is not an end-at-4gb image
396 sym_name: Symbol name in the ELF file to look up in the format
397 _binman_<entry>_prop_<property> where <entry> is the name of
398 the entry and <property> is the property to find (e.g.
399 _binman_u_boot_prop_offset). As a special case, you can append
400 _any to <entry> to have it search for any matching entry. E.g.
401 _binman_u_boot_any_prop_offset will match entries called u-boot,
402 u-boot-img and u-boot-nodtb)
403 optional: True if the symbol is optional. If False this function
404 will raise if the symbol is not found
405 msg: Message to display if an error occurs
406 base_addr: Base address of image. This is added to the returned
407 image_pos in most cases so that the returned position indicates
408 where the targetted entry/binary has actually been loaded. But
409 if end-at-4gb is used, this is not done, since the binary is
410 already assumed to be linked to the ROM position and using
411 execute-in-place (XIP).
414 Value that should be assigned to that symbol, or None if it was
415 optional and not found
418 ValueError if the symbol is invalid or not found, or references a
419 property which is not supported
421 m
= re
.match(r
'^_binman_(\w+)_prop_(\w+)$', sym_name
)
423 raise ValueError("%s: Symbol '%s' has invalid format" %
425 entry_name
, prop_name
= m
.groups()
426 entry_name
= entry_name
.replace('_', '-')
427 entry
= self
._entries
.get(entry_name
)
429 if entry_name
.endswith('-any'):
430 root
= entry_name
[:-4]
431 for name
in self
._entries
:
432 if name
.startswith(root
):
433 rest
= name
[len(root
):]
434 if rest
in ['', '-img', '-nodtb']:
435 entry
= self
._entries
[name
]
437 err
= ("%s: Entry '%s' not found in list (%s)" %
438 (msg
, entry_name
, ','.join(self
._entries
.keys())))
440 print('Warning: %s' % err
, file=sys
.stderr
)
442 raise ValueError(err
)
443 if prop_name
== 'offset':
445 elif prop_name
== 'image_pos':
446 value
= entry
.image_pos
447 if not self
.GetImage()._end
_4gb
:
450 if prop_name
== 'size':
453 raise ValueError("%s: No such property '%s'" % (msg
, prop_name
))
455 def GetRootSkipAtStart(self
):
456 """Get the skip-at-start value for the top-level section
458 This is used to find out the starting offset for root section that
459 contains this section. If this is a top-level section then it returns
460 the skip-at-start offset for this section.
462 This is used to get the absolute position of section within the image.
465 Integer skip-at-start value for the root section containing this
469 return self
.section
.GetRootSkipAtStart()
470 return self
._skip
_at
_start
472 def GetStartOffset(self
):
473 """Get the start offset for this section
476 The first available offset in this section (typically 0)
478 return self
._skip
_at
_start
480 def GetImageSize(self
):
481 """Get the size of the image containing this section
484 Image size as an integer number of bytes, which may be None if the
485 image size is dynamic and its sections have not yet been packed
487 return self
.GetImage().size
489 def FindEntryType(self
, etype
):
490 """Find an entry type in the section
493 etype: Entry type to find
495 entry matching that type, or None if not found
497 for entry
in self
._entries
.values():
498 if entry
.etype
== etype
:
502 def GetEntryContents(self
):
503 """Call ObtainContents() for each entry in the section
505 todo
= self
._entries
.values()
506 for passnum
in range(3):
509 if not entry
.ObtainContents():
510 next_todo
.append(entry
)
515 self
.Raise('Internal error: Could not complete processing of contents: remaining %s' %
519 def _SetEntryOffsetSize(self
, name
, offset
, size
):
520 """Set the offset and size of an entry
523 name: Entry name to update
524 offset: New offset, or None to leave alone
525 size: New size, or None to leave alone
527 entry
= self
._entries
.get(name
)
529 self
._Raise
("Unable to set offset/size for unknown entry '%s'" %
531 entry
.SetOffsetSize(self
._skip
_at
_start
+ offset
if offset
is not None
534 def GetEntryOffsets(self
):
535 """Handle entries that want to set the offset/size of other entries
537 This calls each entry's GetOffsets() method. If it returns a list
538 of entries to update, it updates them.
540 for entry
in self
._entries
.values():
541 offset_dict
= entry
.GetOffsets()
542 for name
, info
in offset_dict
.items():
543 self
._SetEntryOffsetSize
(name
, *info
)
547 data
= self
._BuildSectionData
()
548 contents_size
= len(data
)
552 data
= self
.GetPaddedData()
554 size
= tools
.Align(size
, self
.align_size
)
556 if self
.size
and contents_size
> self
.size
:
557 self
._Raise
("contents size %#x (%d) exceeds section size %#x (%d)" %
558 (contents_size
, contents_size
, self
.size
, self
.size
))
561 if self
.size
!= tools
.Align(self
.size
, self
.align_size
):
562 self
._Raise
("Size %#x (%d) does not match align-size %#x (%d)" %
563 (self
.size
, self
.size
, self
.align_size
,
567 def ListEntries(self
, entries
, indent
):
568 """List the files in the section"""
569 Entry
.AddEntryInfo(entries
, indent
, self
.name
, 'section', self
.size
,
570 self
.image_pos
, None, self
.offset
, self
)
571 for entry
in self
._entries
.values():
572 entry
.ListEntries(entries
, indent
+ 1)
574 def LoadData(self
, decomp
=True):
575 for entry
in self
._entries
.values():
576 entry
.LoadData(decomp
)
577 self
.Detail('Loaded data')
580 """Get the image containing this section
582 Note that a top-level section is actually an Image, so this function may
586 Image object containing this section
590 return self
.section
.GetImage()
593 """Check if the entries in this section will be sorted
596 True if to be sorted, False if entries will be left in the order
597 they appear in the device tree
601 def ReadData(self
, decomp
=True):
602 tout
.Info("ReadData path='%s'" % self
.GetPath())
603 parent_data
= self
.section
.ReadData(True)
604 tout
.Info('%s: Reading data from offset %#x-%#x, size %#x' %
605 (self
.GetPath(), self
.offset
, self
.offset
+ self
.size
,
607 data
= parent_data
[self
.offset
:self
.offset
+ self
.size
]
610 def ReadChildData(self
, child
, decomp
=True):
611 tout
.Debug("ReadChildData for child '%s'" % child
.GetPath())
612 parent_data
= self
.ReadData(True)
613 offset
= child
.offset
- self
._skip
_at
_start
614 tout
.Debug("Extract for child '%s': offset %#x, skip_at_start %#x, result %#x" %
615 (child
.GetPath(), child
.offset
, self
._skip
_at
_start
, offset
))
616 data
= parent_data
[offset
:offset
+ child
.size
]
619 data
= tools
.Decompress(indata
, child
.compress
)
620 if child
.uncomp_size
:
621 tout
.Info("%s: Decompressing data size %#x with algo '%s' to data size %#x" %
622 (child
.GetPath(), len(indata
), child
.compress
,
626 def WriteChildData(self
, child
):
629 def SetAllowMissing(self
, allow_missing
):
630 """Set whether a section allows missing external blobs
633 allow_missing: True if allowed, False if not allowed
635 self
.allow_missing
= allow_missing
636 for entry
in self
._entries
.values():
637 entry
.SetAllowMissing(allow_missing
)
639 def CheckMissing(self
, missing_list
):
640 """Check if any entries in this section have missing external blobs
642 If there are missing blobs, the entries are added to the list
645 missing_list: List of Entry objects to be added to
647 for entry
in self
._entries
.values():
648 entry
.CheckMissing(missing_list
)