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>

6 files changed, 35 insertions, 34 deletions

diff --git a/tools/binman/etype/_testing.py b/tools/binman/etype/_testing.py
index 6a1af57798..31f625c026 100644
--- a/tools/binman/etype/_testing.py
+++ b/tools/binman/etype/_testing.py
@@ -14,7 +14,7 @@ class Entry__testing(Entry):
     """A fake entry used for testing
 
     Properties:
-        return_invalid_entry: Return an invalid entry from GetPositions()
+        return_invalid_entry: Return an invalid entry from GetOffsets()
     """
     def __init__(self, section, etype, node):
         Entry.__init__(self, section, etype, node)
@@ -35,7 +35,7 @@ class Entry__testing(Entry):
         self.contents_size = len(self.data)
         return True
 
-    def GetPositions(self):
+    def GetOffsets(self):
         if self.return_invalid_entry :
             return {'invalid-entry': [1, 2]}
         return {}
diff --git a/tools/binman/etype/intel_descriptor.py b/tools/binman/etype/intel_descriptor.py
index 0e7865521e..0a5151d466 100644
--- a/tools/binman/etype/intel_descriptor.py
+++ b/tools/binman/etype/intel_descriptor.py
@@ -36,12 +36,12 @@ class Entry_intel_descriptor(Entry_blob):
         Entry_blob.__init__(self, section, etype, node)
         self._regions = []
 
-    def GetPositions(self):
-        pos = self.data.find(FD_SIGNATURE)
-        if pos == -1:
+    def GetOffsets(self):
+        offset = self.data.find(FD_SIGNATURE)
+        if offset == -1:
             self.Raise('Cannot find FD signature')
         flvalsig, flmap0, flmap1, flmap2 = struct.unpack('<LLLL',
-                                                    self.data[pos:pos + 16])
+                                                self.data[offset:offset + 16])
         frba = ((flmap0 >> 16) & 0xff) << 4
         for i in range(MAX_REGIONS):
             self._regions.append(Region(self.data, frba, i))
diff --git a/tools/binman/etype/section.py b/tools/binman/etype/section.py
index 787257d3ec..5a0b0b8c70 100644
--- a/tools/binman/etype/section.py
+++ b/tools/binman/etype/section.py
@@ -30,20 +30,20 @@ class Entry_section(Entry):
     def GetData(self):
         return self._section.GetData()
 
-    def GetPositions(self):
-        """Handle entries that want to set the position/size of other entries
+    def GetOffsets(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.
         """
-        self._section.GetEntryPositions()
+        self._section.GetEntryOffsets()
         return {}
 
-    def Pack(self, pos):
+    def Pack(self, offset):
         """Pack all entries into the section"""
         self._section.PackEntries()
         self.size = self._section.CheckSize()
-        return super(Entry_section, self).Pack(pos)
+        return super(Entry_section, self).Pack(offset)
 
     def WriteSymbols(self, section):
         """Write symbol values into binary files for access at run time"""
@@ -57,7 +57,7 @@ class Entry_section(Entry):
         self._section.ProcessEntryContents()
         super(Entry_section, self).ProcessContents()
 
-    def CheckPosition(self):
+    def CheckOffset(self):
         self._section.CheckEntries()
 
     def WriteMap(self, fd, indent):
diff --git a/tools/binman/etype/u_boot_dtb_with_ucode.py b/tools/binman/etype/u_boot_dtb_with_ucode.py
index 3808d6d278..55d3a38a64 100644
--- a/tools/binman/etype/u_boot_dtb_with_ucode.py
+++ b/tools/binman/etype/u_boot_dtb_with_ucode.py
@@ -33,10 +33,10 @@ class Entry_u_boot_dtb_with_ucode(Entry_blob):
         # If the section does not need microcode, there is nothing to do
         ucode_dest_entry = self.section.FindEntryType(
             'u-boot-spl-with-ucode-ptr')
-        if not ucode_dest_entry or not ucode_dest_entry.target_pos:
+        if not ucode_dest_entry or not ucode_dest_entry.target_offset:
             ucode_dest_entry = self.section.FindEntryType(
                 'u-boot-with-ucode-ptr')
-        if not ucode_dest_entry or not ucode_dest_entry.target_pos:
+        if not ucode_dest_entry or not ucode_dest_entry.target_offset:
             return True
 
         # Remove the microcode
diff --git a/tools/binman/etype/u_boot_ucode.py b/tools/binman/etype/u_boot_ucode.py
index ea0c85cc5c..922a607cfe 100644
--- a/tools/binman/etype/u_boot_ucode.py
+++ b/tools/binman/etype/u_boot_ucode.py
@@ -59,8 +59,8 @@ class Entry_u_boot_ucode(Entry_blob):
         ucode_dest_entry = self.section.FindEntryType('u-boot-with-ucode-ptr')
         ucode_dest_entry_spl = self.section.FindEntryType(
             'u-boot-spl-with-ucode-ptr')
-        if ((not ucode_dest_entry or not ucode_dest_entry.target_pos) and
-            (not ucode_dest_entry_spl or not ucode_dest_entry_spl.target_pos)):
+        if ((not ucode_dest_entry or not ucode_dest_entry.target_offset) and
+            (not ucode_dest_entry_spl or not ucode_dest_entry_spl.target_offset)):
             self.data = ''
             return True
 
diff --git a/tools/binman/etype/u_boot_with_ucode_ptr.py b/tools/binman/etype/u_boot_with_ucode_ptr.py
index 8b1e41152e..97e58a0bfc 100644
--- a/tools/binman/etype/u_boot_with_ucode_ptr.py
+++ b/tools/binman/etype/u_boot_with_ucode_ptr.py
@@ -23,7 +23,7 @@ class Entry_u_boot_with_ucode_ptr(Entry_blob):
     def __init__(self, section, etype, node):
         Entry_blob.__init__(self, section, etype, node)
         self.elf_fname = 'u-boot'
-        self.target_pos = None
+        self.target_offset = None
 
     def GetDefaultFilename(self):
         return 'u-boot-nodtb.bin'
@@ -33,52 +33,53 @@ class Entry_u_boot_with_ucode_ptr(Entry_blob):
         fname = tools.GetInputFilename(self.elf_fname)
         sym = elf.GetSymbolAddress(fname, '_dt_ucode_base_size')
         if sym:
-           self.target_pos = sym
+           self.target_offset = sym
         elif not fdt_util.GetBool(self._node, 'optional-ucode'):
             self.Raise('Cannot locate _dt_ucode_base_size symbol in u-boot')
         return True
 
     def ProcessContents(self):
         # If the image does not need microcode, there is nothing to do
-        if not self.target_pos:
+        if not self.target_offset:
             return
 
-        # Get the position of the microcode
+        # Get the offset of the microcode
         ucode_entry = self.section.FindEntryType('u-boot-ucode')
         if not ucode_entry:
             self.Raise('Cannot find microcode region u-boot-ucode')
 
         # Check the target pos is in the section. If it is not, then U-Boot is
-        # being linked incorrectly, or is being placed at the wrong position
+        # being linked incorrectly, or is being placed at the wrong offset
         # in the section.
         #
         # The section must be set up so that U-Boot is placed at the
         # flash address to which it is linked. For example, if
         # CONFIG_SYS_TEXT_BASE is 0xfff00000, and the ROM is 8MB, then
-        # the U-Boot region must start at position 7MB in the section. In this
-        # case the ROM starts at 0xff800000, so the position of the first
+        # the U-Boot region must start at offset 7MB in the section. In this
+        # case the ROM starts at 0xff800000, so the offset of the first
         # entry in the section corresponds to that.
-        if (self.target_pos < self.pos or
-                self.target_pos >= self.pos + self.size):
+        if (self.target_offset < self.offset or
+                self.target_offset >= self.offset + self.size):
             self.Raise('Microcode pointer _dt_ucode_base_size at %08x is '
                 'outside the section ranging from %08x to %08x' %
-                (self.target_pos, self.pos, self.pos + self.size))
+                (self.target_offset, self.offset, self.offset + self.size))
 
         # Get the microcode, either from u-boot-ucode or u-boot-dtb-with-ucode.
         # If we have left the microcode in the device tree, then it will be
         # in the former. If we extracted the microcode from the device tree
         # and collated it in one place, it will be in the latter.
         if ucode_entry.size:
-            pos, size = ucode_entry.pos, ucode_entry.size
+            offset, size = ucode_entry.offset, ucode_entry.size
         else:
             dtb_entry = self.section.FindEntryType('u-boot-dtb-with-ucode')
             if not dtb_entry or not dtb_entry.ready:
                 self.Raise('Cannot find microcode region u-boot-dtb-with-ucode')
-            pos = dtb_entry.pos + dtb_entry.ucode_offset
+            offset = dtb_entry.offset + dtb_entry.ucode_offset
             size = dtb_entry.ucode_size
 
-        # Write the microcode position and size into the entry
-        pos_and_size = struct.pack('<2L', pos, size)
-        self.target_pos -= self.pos
-        self.ProcessContentsUpdate(self.data[:self.target_pos] + pos_and_size +
-                                   self.data[self.target_pos + 8:])
+        # Write the microcode offset and size into the entry
+        offset_and_size = struct.pack('<2L', offset, size)
+        self.target_offset -= self.offset
+        self.ProcessContentsUpdate(self.data[:self.target_offset] +
+                                   offset_and_size +
+                                   self.data[self.target_offset + 8:])