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>

1 files changed, 37 insertions, 36 deletions

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 @@ class Entry(object):
     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 @@ class Entry(object):
         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 @@ class Entry(object):
         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 @@ class Entry(object):
 
         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 @@ class Entry(object):
             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 @@ class Entry(object):
         # 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 @@ class Entry(object):
             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 @@ class Entry(object):
     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 @@ class Entry(object):
         """
         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 @@ class Entry(object):
             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)