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, 45 insertions, 43 deletions

diff --git a/tools/binman/bsection.py b/tools/binman/bsection.py
index de439ef625..d78a25e83d 100644
--- a/tools/binman/bsection.py
+++ b/tools/binman/bsection.py
@@ -25,22 +25,21 @@ class Section(object):
         _size: Section size in bytes, or None if not known yet
         _align_size: Section size alignment, or None
         _pad_before: Number of bytes before the first entry starts. This
-            effectively changes the place where entry position 0 starts
+            effectively changes the place where entry offset 0 starts
         _pad_after: Number of bytes after the last entry ends. The last
             entry will finish on or before this boundary
         _pad_byte: Byte to use to pad the section where there is no entry
-        _sort: True if entries should be sorted by position, False if they
+        _sort: True if entries should be sorted by offset, False if they
             must be in-order in the device tree description
         _skip_at_start: Number of bytes before the first entry starts. These
-            effectively adjust the starting position of entries. For example,
+            effectively adjust the starting offset of entries. For example,
             if _pad_before is 16, then the first entry would start at 16.
-            An entry with pos = 20 would in fact be written at position 4
+            An entry with offset = 20 would in fact be written at offset 4
             in the image file.
         _end_4gb: Indicates that the section ends at the 4GB boundary. This is
-            used for x86 images, which want to use positions such that a
-             memory address (like 0xff800000) is the first entry position.
-             This causes _skip_at_start to be set to the starting memory
-             address.
+            used for x86 images, which want to use offsets such that a memory
+            address (like 0xff800000) is the first entry offset. This causes
+            _skip_at_start to be set to the starting memory address.
         _name_prefix: Prefix to add to the name of all entries within this
             section
         _entries: OrderedDict() of entries
@@ -52,6 +51,7 @@ class Section(object):
         from entry import Entry
 
         self._node = node
+        self._offset = 0
         self._size = None
         self._align_size = None
         self._pad_before = 0
@@ -76,7 +76,7 @@ class Section(object):
         self._pad_before = fdt_util.GetInt(self._node, 'pad-before', 0)
         self._pad_after = fdt_util.GetInt(self._node, 'pad-after', 0)
         self._pad_byte = fdt_util.GetInt(self._node, 'pad-byte', 0)
-        self._sort = fdt_util.GetBool(self._node, 'sort-by-pos')
+        self._sort = fdt_util.GetBool(self._node, 'sort-by-offset')
         self._end_4gb = fdt_util.GetBool(self._node, 'end-at-4gb')
         if self._end_4gb and not self._size:
             self._Raise("Section size must be provided when using end-at-4gb")
@@ -117,7 +117,7 @@ class Section(object):
         """Check that the section contents does not exceed its size, etc."""
         contents_size = 0
         for entry in self._entries.values():
-            contents_size = max(contents_size, entry.pos + entry.size)
+            contents_size = max(contents_size, entry.offset + entry.size)
 
         contents_size -= self._skip_at_start
 
@@ -190,39 +190,41 @@ class Section(object):
                         'contents: remaining %s' % todo)
         return True
 
-    def _SetEntryPosSize(self, name, pos, size):
-        """Set the position and size of an entry
+    def _SetEntryOffsetSize(self, name, offset, size):
+        """Set the offset and size of an entry
 
         Args:
             name: Entry name to update
-            pos: New position
+            offset: New offset
             size: New size
         """
         entry = self._entries.get(name)
         if not entry:
-            self._Raise("Unable to set pos/size for unknown entry '%s'" % name)
-        entry.SetPositionSize(self._skip_at_start + pos, size)
+            self._Raise("Unable to set offset/size for unknown entry '%s'" %
+                        name)
+        entry.SetOffsetSize(self._skip_at_start + offset, size)
 
-    def GetEntryPositions(self):
-        """Handle entries that want to set the position/size of other entries
+    def GetEntryOffsets(self):
+        """Handle entries that want to set the offset/size of other entries
 
-        This calls each entry's GetPositions() method. If it returns a list
+        This calls each entry's GetOffsets() method. If it returns a list
         of entries to update, it updates them.
         """
         for entry in self._entries.values():
-            pos_dict = entry.GetPositions()
-            for name, info in pos_dict.iteritems():
-                self._SetEntryPosSize(name, *info)
+            offset_dict = entry.GetOffsets()
+            for name, info in offset_dict.iteritems():
+                self._SetEntryOffsetSize(name, *info)
 
     def PackEntries(self):
         """Pack all entries into the section"""
-        pos = self._skip_at_start
+        offset = self._skip_at_start
         for entry in self._entries.values():
-            pos = entry.Pack(pos)
+            offset = entry.Pack(offset)
+        self._size = self.CheckSize()
 
     def _SortEntries(self):
-        """Sort entries by position"""
-        entries = sorted(self._entries.values(), key=lambda entry: entry.pos)
+        """Sort entries by offset"""
+        entries = sorted(self._entries.values(), key=lambda entry: entry.offset)
         self._entries.clear()
         for entry in entries:
             self._entries[entry._node.name] = entry
@@ -231,21 +233,21 @@ class Section(object):
         """Check that entries do not overlap or extend outside the section"""
         if self._sort:
             self._SortEntries()
-        pos = 0
+        offset = 0
         prev_name = 'None'
         for entry in self._entries.values():
-            entry.CheckPosition()
-            if (entry.pos < self._skip_at_start or
-                entry.pos >= self._skip_at_start + self._size):
-                entry.Raise("Position %#x (%d) is outside the section starting "
+            entry.CheckOffset()
+            if (entry.offset < self._skip_at_start or
+                entry.offset >= self._skip_at_start + self._size):
+                entry.Raise("Offset %#x (%d) is outside the section starting "
                             "at %#x (%d)" %
-                            (entry.pos, entry.pos, self._skip_at_start,
+                            (entry.offset, entry.offset, self._skip_at_start,
                              self._skip_at_start))
-            if entry.pos < pos:
-                entry.Raise("Position %#x (%d) overlaps with previous entry '%s' "
+            if entry.offset < offset:
+                entry.Raise("Offset %#x (%d) overlaps with previous entry '%s' "
                             "ending at %#x (%d)" %
-                            (entry.pos, entry.pos, prev_name, pos, pos))
-            pos = entry.pos + entry.size
+                            (entry.offset, entry.offset, prev_name, offset, offset))
+            offset = entry.offset + entry.size
             prev_name = entry.GetPath()
 
     def ProcessEntryContents(self):
@@ -261,9 +263,9 @@ class Section(object):
         for entry in self._entries.values():
             entry.WriteSymbols(self)
 
-    def BuildSection(self, fd, base_pos):
+    def BuildSection(self, fd, base_offset):
         """Write the section to a file"""
-        fd.seek(base_pos)
+        fd.seek(base_offset)
         fd.write(self.GetData())
 
     def GetData(self):
@@ -272,7 +274,7 @@ class Section(object):
 
         for entry in self._entries.values():
             data = entry.GetData()
-            base = self._pad_before + entry.pos - self._skip_at_start
+            base = self._pad_before + entry.offset - self._skip_at_start
             section_data = (section_data[:base] + data +
                             section_data[base + len(data):])
         return section_data
@@ -283,15 +285,15 @@ class Section(object):
         Looks up a symbol in an ELF file. Only entry types which come from an
         ELF image can be used by this function.
 
-        At present the only entry property supported is pos.
+        At present the only entry property supported is offset.
 
         Args:
             sym_name: Symbol name in the ELF file to look up in the format
                 _binman_<entry>_prop_<property> where <entry> is the name of
                 the entry and <property> is the property to find (e.g.
-                _binman_u_boot_prop_pos). As a special case, you can append
+                _binman_u_boot_prop_offset). As a special case, you can append
                 _any to <entry> to have it search for any matching entry. E.g.
-                _binman_u_boot_any_prop_pos will match entries called u-boot,
+                _binman_u_boot_any_prop_offset will match entries called u-boot,
                 u-boot-img and u-boot-nodtb)
             optional: True if the symbol is optional. If False this function
                 will raise if the symbol is not found
@@ -327,8 +329,8 @@ class Section(object):
                 print('Warning: %s' % err, file=sys.stderr)
                 return None
             raise ValueError(err)
-        if prop_name == 'pos':
-            return entry.pos
+        if prop_name == 'offset':
+            return entry.offset
         else:
             raise ValueError("%s: No such property '%s'" % (msg, prop_name))