binman: Rename 'position' to 'offset'
After some thought, I believe there is an unfortunate naming flaw in
binman. Entries have a position and size, but now that we support
hierarchical sections it is unclear whether a position should be an
absolute position within the image, or a relative position within its
parent section.
At present 'position' actually means the relative position. This indicates
a need for an 'image position' for code that wants to find the location of
an entry without having to do calculations back through parents to
discover this image position.
A better name for the current 'position' or 'pos' is 'offset'. It is not
always an absolute position, but it is always an offset from its parent
offset.
It is unfortunate to rename this concept now, 18 months after binman was
introduced. However I believe it is the right thing to do. The impact is
mostly limited to binman itself and a few changes to in-tree users to
binman:
tegra
sunxi
x86
The change makes old binman definitions (e.g. downstream or out-of-tree)
incompatible if they use the 'pos = <...>' property. Later work will
adjust binman to generate an error when it is used.
Signed-off-by: Simon Glass <sjg@chromium.org>
diff --git a/tools/binman/entry.py b/tools/binman/entry.py
index 6a173e6..c9529d8 100644
--- a/tools/binman/entry.py
+++ b/tools/binman/entry.py
@@ -38,12 +38,13 @@
Attributes:
section: The section containing this entry
node: The node that created this entry
- pos: Absolute position of entry within the section, None if not known
+ offset: Offset of entry within the section, None if not known yet (in
+ which case it will be calculated by Pack())
size: Entry size in bytes, None if not known
contents_size: Size of contents in bytes, 0 by default
- align: Entry start position alignment, or None
+ align: Entry start offset alignment, or None
align_size: Entry size alignment, or None
- align_end: Entry end position alignment, or None
+ align_end: Entry end offset alignment, or None
pad_before: Number of pad bytes before the contents, 0 if none
pad_after: Number of pad bytes after the contents, 0 if none
data: Contents of entry (string of bytes)
@@ -53,7 +54,7 @@
self.etype = etype
self._node = node
self.name = node and (name_prefix + node.name) or 'none'
- self.pos = None
+ self.offset = None
self.size = None
self.data = ''
self.contents_size = 0
@@ -62,7 +63,7 @@
self.align_end = None
self.pad_before = 0
self.pad_after = 0
- self.pos_unset = False
+ self.offset_unset = False
if read_node:
self.ReadNode()
@@ -115,7 +116,7 @@
This reads all the fields we recognise from the node, ready for use.
"""
- self.pos = fdt_util.GetInt(self._node, 'pos')
+ self.offset = fdt_util.GetInt(self._node, 'offset')
self.size = fdt_util.GetInt(self._node, 'size')
self.align = fdt_util.GetInt(self._node, 'align')
if tools.NotPowerOfTwo(self.align):
@@ -128,17 +129,17 @@
raise ValueError("Node '%s': Alignment size %s must be a power "
"of two" % (self._node.path, self.align_size))
self.align_end = fdt_util.GetInt(self._node, 'align-end')
- self.pos_unset = fdt_util.GetBool(self._node, 'pos-unset')
+ self.offset_unset = fdt_util.GetBool(self._node, 'offset-unset')
def AddMissingProperties(self):
"""Add new properties to the device tree as needed for this entry"""
- for prop in ['pos', 'size']:
+ for prop in ['offset', 'size', 'global-pos']:
if not prop in self._node.props:
self._node.AddZeroProp(prop)
def SetCalculatedProperties(self):
"""Set the value of device-tree properties calculated by binman"""
- self._node.SetInt('pos', self.pos)
+ self._node.SetInt('offset', self.offset)
self._node.SetInt('size', self.size)
def ProcessFdt(self, fdt):
@@ -190,39 +191,39 @@
# No contents by default: subclasses can implement this
return True
- def Pack(self, pos):
+ def Pack(self, offset):
"""Figure out how to pack the entry into the section
Most of the time the entries are not fully specified. There may be
an alignment but no size. In that case we take the size from the
contents of the entry.
- If an entry has no hard-coded position, it will be placed at @pos.
+ If an entry has no hard-coded offset, it will be placed at @offset.
- Once this function is complete, both the position and size of the
+ Once this function is complete, both the offset and size of the
entry will be know.
Args:
- Current section position pointer
+ Current section offset pointer
Returns:
- New section position pointer (after this entry)
+ New section offset pointer (after this entry)
"""
- if self.pos is None:
- if self.pos_unset:
- self.Raise('No position set with pos-unset: should another '
- 'entry provide this correct position?')
- self.pos = tools.Align(pos, self.align)
+ if self.offset is None:
+ if self.offset_unset:
+ self.Raise('No offset set with offset-unset: should another '
+ 'entry provide this correct offset?')
+ self.offset = tools.Align(offset, self.align)
needed = self.pad_before + self.contents_size + self.pad_after
needed = tools.Align(needed, self.align_size)
size = self.size
if not size:
size = needed
- new_pos = self.pos + size
- aligned_pos = tools.Align(new_pos, self.align_end)
- if aligned_pos != new_pos:
- size = aligned_pos - self.pos
- new_pos = aligned_pos
+ new_offset = self.offset + size
+ aligned_offset = tools.Align(new_offset, self.align_end)
+ if aligned_offset != new_offset:
+ size = aligned_offset - self.offset
+ new_offset = aligned_offset
if not self.size:
self.size = size
@@ -231,16 +232,16 @@
self.Raise("Entry contents size is %#x (%d) but entry size is "
"%#x (%d)" % (needed, needed, self.size, self.size))
# Check that the alignment is correct. It could be wrong if the
- # and pos or size values were provided (i.e. not calculated), but
+ # and offset or size values were provided (i.e. not calculated), but
# conflict with the provided alignment values
if self.size != tools.Align(self.size, self.align_size):
self.Raise("Size %#x (%d) does not match align-size %#x (%d)" %
(self.size, self.size, self.align_size, self.align_size))
- if self.pos != tools.Align(self.pos, self.align):
- self.Raise("Position %#x (%d) does not match align %#x (%d)" %
- (self.pos, self.pos, self.align, self.align))
+ if self.offset != tools.Align(self.offset, self.align):
+ self.Raise("Offset %#x (%d) does not match align %#x (%d)" %
+ (self.offset, self.offset, self.align, self.align))
- return new_pos
+ return new_offset
def Raise(self, msg):
"""Convenience function to raise an error referencing a node"""
@@ -257,11 +258,11 @@
def GetData(self):
return self.data
- def GetPositions(self):
+ def GetOffsets(self):
return {}
- def SetPositionSize(self, pos, size):
- self.pos = pos
+ def SetOffsetSize(self, pos, size):
+ self.offset = pos
self.size = size
def ProcessContents(self):
@@ -275,10 +276,10 @@
"""
pass
- def CheckPosition(self):
- """Check that the entry positions are correct
+ def CheckOffset(self):
+ """Check that the entry offsets are correct
- This is used for entries which have extra position requirements (other
+ This is used for entries which have extra offset requirements (other
than having to be fully inside their section). Sub-classes can implement
this function and raise if there is a problem.
"""
@@ -291,5 +292,5 @@
fd: File to write the map to
indent: Curent indent level of map (0=none, 1=one level, etc.)
"""
- print('%s%08x %08x %s' % (' ' * indent, self.pos, self.size,
+ print('%s%08x %08x %s' % (' ' * indent, self.offset, self.size,
self.name), file=fd)