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>

arch/arm/dts/sunxi-u-boot.dtsi

@@ -8,7 +8,7 @@
 			filename = "spl/sunxi-spl.bin";
 		};
 		u-boot-img {
-			pos = <CONFIG_SPL_PAD_TO>;
+			offset = <CONFIG_SPL_PAD_TO>;
 		};
 	};
 };

arch/arm/dts/tegra-u-boot.dtsi

@@ -15,7 +15,7 @@
 			u-boot-spl {
 			};
 			u-boot {
-				pos = <(U_BOOT_OFFSET)>;
+				offset = <(U_BOOT_OFFSET)>;
 			};
 		};
 
@@ -26,7 +26,7 @@
 			u-boot-spl {
 			};
 			u-boot {
-				pos = <(U_BOOT_OFFSET)>;
+				offset = <(U_BOOT_OFFSET)>;
 			};
 		};
 
@@ -36,7 +36,7 @@
 			u-boot-spl {
 			};
 			u-boot-nodtb {
-				pos = <(U_BOOT_OFFSET)>;
+				offset = <(U_BOOT_OFFSET)>;
 			};
 		};
 	};

arch/x86/dts/u-boot.dtsi

@@ -11,7 +11,7 @@
 	binman {
 		filename = "u-boot.rom";
 		end-at-4gb;
-		sort-by-pos;
+		sort-by-offset;
 		pad-byte = <0xff>;
 		size = <CONFIG_ROM_SIZE>;
 #ifdef CONFIG_HAVE_INTEL_ME
@@ -24,18 +24,18 @@
 #endif
 #ifdef CONFIG_SPL
 		u-boot-spl-with-ucode-ptr {
-			pos = <CONFIG_SPL_TEXT_BASE>;
+			offset = <CONFIG_SPL_TEXT_BASE>;
 		};
 
 		u-boot-dtb-with-ucode2 {
 			type = "u-boot-dtb-with-ucode";
 		};
 		u-boot {
-			pos = <0xfff00000>;
+			offset = <0xfff00000>;
 		};
 #else
 		u-boot-with-ucode-ptr {
-			pos = <CONFIG_SYS_TEXT_BASE>;
+			offset = <CONFIG_SYS_TEXT_BASE>;
 		};
 #endif
 		u-boot-dtb-with-ucode {
@@ -45,45 +45,45 @@
 		};
 #ifdef CONFIG_HAVE_MRC
 		intel-mrc {
-			pos = <CONFIG_X86_MRC_ADDR>;
+			offset = <CONFIG_X86_MRC_ADDR>;
 		};
 #endif
 #ifdef CONFIG_HAVE_FSP
 		intel-fsp {
 			filename = CONFIG_FSP_FILE;
-			pos = <CONFIG_FSP_ADDR>;
+			offset = <CONFIG_FSP_ADDR>;
 		};
 #endif
 #ifdef CONFIG_HAVE_CMC
 		intel-cmc {
 			filename = CONFIG_CMC_FILE;
-			pos = <CONFIG_CMC_ADDR>;
+			offset = <CONFIG_CMC_ADDR>;
 		};
 #endif
 #ifdef CONFIG_HAVE_VGA_BIOS
 		intel-vga {
 			filename = CONFIG_VGA_BIOS_FILE;
-			pos = <CONFIG_VGA_BIOS_ADDR>;
+			offset = <CONFIG_VGA_BIOS_ADDR>;
 		};
 #endif
 #ifdef CONFIG_HAVE_VBT
 		intel-vbt {
 			filename = CONFIG_VBT_FILE;
-			pos = <CONFIG_VBT_ADDR>;
+			offset = <CONFIG_VBT_ADDR>;
 		};
 #endif
 #ifdef CONFIG_HAVE_REFCODE
 		intel-refcode {
-			pos = <CONFIG_X86_REFCODE_ADDR>;
+			offset = <CONFIG_X86_REFCODE_ADDR>;
 		};
 #endif
 #ifdef CONFIG_SPL
 		x86-start16-spl {
-			pos = <CONFIG_SYS_X86_START16>;
+			offset = <CONFIG_SYS_X86_START16>;
 		};
 #else
 		x86-start16 {
-			pos = <CONFIG_SYS_X86_START16>;
+			offset = <CONFIG_SYS_X86_START16>;
 		};
 #endif
 	};

common/spl/spl.c

@@ -34,7 +34,7 @@ DECLARE_GLOBAL_DATA_PTR;
 u32 *boot_params_ptr = NULL;
 
 /* See spl.h for information about this */
-binman_sym_declare(ulong, u_boot_any, pos);
+binman_sym_declare(ulong, u_boot_any, offset);
 
 /* Define board data structure */
 static bd_t bdata __attribute__ ((section(".data")));
@@ -129,7 +129,7 @@ __weak void spl_board_prepare_for_boot(void)
 
 void spl_set_header_raw_uboot(struct spl_image_info *spl_image)
 {
-	ulong u_boot_pos = binman_sym(ulong, u_boot_any, pos);
+	ulong u_boot_pos = binman_sym(ulong, u_boot_any, offset);
 
 	spl_image->size = CONFIG_SYS_MONITOR_LEN;
 

common/spl/spl_ram.c

@@ -49,7 +49,7 @@ static int spl_ram_load_image(struct spl_image_info *spl_image,
 		load.read = spl_ram_load_read;
 		spl_load_simple_fit(spl_image, &load, 0, header);
 	} else {
-		ulong u_boot_pos = binman_sym(ulong, u_boot_any, pos);
+		ulong u_boot_pos = binman_sym(ulong, u_boot_any, offset);
 
 		debug("Legacy image\n");
 		/*

include/spl.h

@@ -60,7 +60,7 @@ struct spl_load_info {
  * image is found. For * example if u-boot.img is used we don't check that
  * spl_parse_image_header() can parse a valid header.
  */
-binman_sym_extern(ulong, u_boot_any, pos);
+binman_sym_extern(ulong, u_boot_any, offset);
 
 /**
  * spl_load_simple_fit() - Loads a fit image from a device.

tools/binman/README

@@ -238,7 +238,7 @@ below:
 			filename = "spl/sunxi-spl.bin";
 		};
 		u-boot {
-			pos = <CONFIG_SPL_PAD_TO>;
+			offset = <CONFIG_SPL_PAD_TO>;
 		};
 	};
 
@@ -257,7 +257,7 @@ provide a filename. For 'u-boot', binman knows that this means 'u-boot.bin'.
 
 Entries are normally placed into the image sequentially, one after the other.
 The image size is the total size of all entries. As you can see, you can
-specify the start position of an entry using the 'pos' property.
+specify the start offset of an entry using the 'offset' property.
 
 Note that due to a device tree requirement, all entries must have a unique
 name. If you want to put the same binary in the image multiple times, you can
@@ -265,14 +265,15 @@ use any unique name, with the 'type' property providing the type.
 
 The attributes supported for entries are described below.
 
-pos:
-	This sets the position of an entry within the image. The first byte
-	of the image is normally at position 0. If 'pos' is not provided,
-	binman sets it to the end of the previous region, or the start of
-	the image's entry area (normally 0) if there is no previous region.
+offset:
+	This sets the offset of an entry within the image or section containing
+	it. The first byte of the image is normally at offset 0. If 'offset' is
+	not provided, binman sets it to the end of the previous region, or the
+	start of the image's entry area (normally 0) if there is no previous
+	region.
 
 align:
-	This sets the alignment of the entry. The entry position is adjusted
+	This sets the alignment of the entry. The entry offset is adjusted
 	so that the entry starts on an aligned boundary within the image. For
 	example 'align = <16>' means that the entry will start on a 16-byte
 	boundary. Alignment shold be a power of 2. If 'align' is not
@@ -316,12 +317,12 @@ type:
 	possible to use any name, and then add (for example) 'type = "u-boot"'
 	to specify the type.
 
-pos-unset:
-	Indicates that the position of this entry should not be set by placing
+offset-unset:
+	Indicates that the offset of this entry should not be set by placing
 	it immediately after the entry before. Instead, is set by another
 	entry which knows where this entry should go. When this boolean
 	property is present, binman will give an error if another entry does
-	not set the position (with the GetPositions() method).
+	not set the offset (with the GetOffsets() method).
 
 
 The attributes supported for images are described below. Several are similar
@@ -338,7 +339,7 @@ align-size:
 
 pad-before:
 	This sets the padding before the image entries. The first entry will
-	be positionad after the padding. This defaults to 0.
+	be positioned after the padding. This defaults to 0.
 
 pad-after:
 	This sets the padding after the image entries. The padding will be
@@ -351,15 +352,15 @@ pad-byte:
 filename:
 	This specifies the image filename. It defaults to 'image.bin'.
 
-sort-by-pos:
+sort-by-offset:
 	This causes binman to reorder the entries as needed to make sure they
 	are in increasing positional order. This can be used when your entry
 	order may not match the positional order. A common situation is where
-	the 'pos' properties are set by CONFIG options, so their ordering is
+	the 'offset' properties are set by CONFIG options, so their ordering is
 	not known a priori.
 
 	This is a boolean property so needs no value. To enable it, add a
-	line 'sort-by-pos;' to your description.
+	line 'sort-by-offset;' to your description.
 
 multiple-images:
 	Normally only a single image is generated. To create more than one
@@ -383,11 +384,11 @@ multiple-images:
 	};
 
 end-at-4gb:
-	For x86 machines the ROM positions start just before 4GB and extend
+	For x86 machines the ROM offsets start just before 4GB and extend
 	up so that the image finished at the 4GB boundary. This boolean
 	option can be enabled to support this. The image size must be
 	provided so that binman knows when the image should start. For an
-	8MB ROM, the position of the first entry would be 0xfff80000 with
+	8MB ROM, the offset of the first entry would be 0xfff80000 with
 	this option, instead of 0 without this option.
 
 
@@ -463,7 +464,7 @@ Order of image creation
 Image creation proceeds in the following order, for each entry in the image.
 
 1. AddMissingProperties() - binman can add calculated values to the device
-tree as part of its processing, for example the position and size of each
+tree as part of its processing, for example the offset and size of each
 entry. This method adds any properties associated with this, expanding the
 device tree as needed. These properties can have placeholder values which are
 set later by SetCalculatedProperties(). By that stage the size of sections
@@ -486,15 +487,15 @@ functions must return True when they have read the contents. Binman will
 retry calling the functions a few times if False is returned, allowing
 dependencies between the contents of different entries.
 
-4. GetEntryPositions() - calls Entry.GetPositions() for each entry. This can
+4. GetEntryOffsets() - calls Entry.GetOffsets() for each entry. This can
 return a dict containing entries that need updating. The key should be the
-entry name and the value is a tuple (pos, size). This allows an entry to
-provide the position and size for other entries. The default implementation
-of GetEntryPositions() returns {}.
+entry name and the value is a tuple (offset, size). This allows an entry to
+provide the offset and size for other entries. The default implementation
+of GetEntryOffsets() returns {}.
 
-5. PackEntries() - calls Entry.Pack() which figures out the position and
-size of an entry. The 'current' image position is passed in, and the function
-returns the position immediately after the entry being packed. The default
+5. PackEntries() - calls Entry.Pack() which figures out the offset and
+size of an entry. The 'current' image offset is passed in, and the function
+returns the offset immediately after the entry being packed. The default
 implementation of Pack() is usually sufficient.
 
 6. CheckSize() - checks that the contents of all the entries fits within
@@ -505,16 +506,16 @@ large enough to hold all the entries.
 outside the image.
 
 8. SetCalculatedProperties() - update any calculated properties in the device
-tree. This sets the correct 'pos' and 'size' vaues, for example.
+tree. This sets the correct 'offset' and 'size' vaues, for example.
 
 9. ProcessEntryContents() - this calls Entry.ProcessContents() on each entry.
 The default implementatoin does nothing. This can be overriden to adjust the
 contents of an entry in some way. For example, it would be possible to create
 an entry containing a hash of the contents of some other entries. At this
-stage the position and size of entries should not be adjusted.
+stage the offset and size of entries should not be adjusted.
 
 10. WriteSymbols() - write the value of symbols into the U-Boot SPL binary.
-See 'Access to binman entry positions at run time' below for a description of
+See 'Access to binman entry offsets at run time' below for a description of
 what happens in this stage.
 
 11. BuildImage() - builds the image and writes it to a file. This is the final
@@ -549,8 +550,8 @@ the 'warning' line in scripts/Makefile.lib to see what it has found:
    # u_boot_dtsi_options_debug = $(u_boot_dtsi_options_raw)
 
 
-Access to binman entry positions at run time
---------------------------------------------
+Access to binman entry offsets at run time
+------------------------------------------
 
 Binman assembles images and determines where each entry is placed in the image.
 This information may be useful to U-Boot at run time. For example, in SPL it
@@ -560,15 +561,15 @@ when SPL is finished.
 Binman allows you to declare symbols in the SPL image which are filled in
 with their correct values during the build. For example:
 
-    binman_sym_declare(ulong, u_boot_any, pos);
+    binman_sym_declare(ulong, u_boot_any, offset);
 
-declares a ulong value which will be assigned to the position of any U-Boot
+declares a ulong value which will be assigned to the offset of any U-Boot
 image (u-boot.bin, u-boot.img, u-boot-nodtb.bin) that is present in the image.
 You can access this value with something like:
 
-    ulong u_boot_pos = binman_sym(ulong, u_boot_any, pos);
+    ulong u_boot_offset = binman_sym(ulong, u_boot_any, offset);
 
-Thus u_boot_pos will be set to the position of U-Boot in memory, assuming that
+Thus u_boot_offset will be set to the offset of U-Boot in memory, assuming that
 the whole image has been loaded, or is available in flash. You can then jump to
 that address to start U-Boot.
 
@@ -580,17 +581,17 @@ Map files
 ---------
 
 The -m option causes binman to output a .map file for each image that it
-generates. This shows the position and size of each entry. For example:
+generates. This shows the offset and size of each entry. For example:
 
-    Position      Size  Name
+      Offset      Size  Name
     00000000  00000010  section@0
      00000000  00000004  u-boot
     00000010  00000010  section@1
      00000000  00000004  u-boot
 
 This shows a hierarchical image with two sections, each with a single entry. The
-positions of the sections are absolute hex byte offsets within the image. The
-positions of the entries are relative to their respective sections. The size of
+offsets of the sections are absolute hex byte offsets within the image. The
+offsets of the entries are relative to their respective sections. The size of
 each entry is also shown, in bytes (hex). The indentation shows the entries
 nested inside their sections.
 
@@ -623,7 +624,7 @@ Entry properties are documented in entry.py. The entry subclasses are free
 to change the values of properties to support special behaviour. For example,
 when Entry_blob loads a file, it sets content_size to the size of the file.
 Entry classes can adjust other entries. For example, an entry that knows
-where other entries should be positioned can set up those entries' positions
+where other entries should be positioned can set up those entries' offsets
 so they don't need to be set in the binman decription. It can also adjust
 entry contents.
 

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))
 

tools/binman/cmdline.py

@@ -43,7 +43,7 @@ def ParseArgs(argv):
     parser.add_option('-T', '--test-coverage', action='store_true',
                     default=False, help='run tests and check for 100% coverage')
     parser.add_option('-u', '--update-fdt', action='store_true',
-        default=False, help='Update the binman node with position/size info')
+        default=False, help='Update the binman node with offset/size info')
     parser.add_option('-v', '--verbosity', default=1,
         type='int', help='Control verbosity: 0=silent, 1=progress, 3=full, '
         '4=debug')

tools/binman/control.py

@@ -142,7 +142,7 @@ def Binman(options, args):
             # size of the device tree is correct. Later, in
             # SetCalculatedProperties() we will insert the correct values
             # without changing the device-tree size, thus ensuring that our
-            # entry positions remain the same.
+            # entry offsets remain the same.
             for image in images.values():
                 if options.update_fdt:
                     image.AddMissingProperties()
@@ -157,7 +157,7 @@ def Binman(options, args):
                 # image will be reported after earlier images are already
                 # completed and written, but that does not seem important.
                 image.GetEntryContents()
-                image.GetEntryPositions()
+                image.GetEntryOffsets()
                 image.PackEntries()
                 image.CheckSize()
                 image.CheckEntries()

tools/binman/elf.py

@@ -81,9 +81,9 @@ def LookupAndWriteSymbols(elf_fname, entry, section):
     """Replace all symbols in an entry with their correct values
 
     The entry contents is updated so that values for referenced symbols will be
-    visible at run time. This is done by finding out the symbols positions in
-    the entry (using the ELF file) and replacing them with values from binman's
-    data structures.
+    visible at run time. This is done by finding out the symbols offsets in the
+    entry (using the ELF file) and replacing them with values from binman's data
+    structures.
 
     Args:
         elf_fname: Filename of ELF image containing the symbol information for

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)

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 {}

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))

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):

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

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
 

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:])

tools/binman/ftest.py

@@ -153,7 +153,7 @@ class TestFunctional(unittest.TestCase):
             fname: Device-tree source filename to use (e.g. 05_simple.dts)
             debug: True to enable debugging output
             map: True to output map files for the images
-            update_dtb: Update the position and size of each entry in the device
+            update_dtb: Update the offset and size of each entry in the device
                 tree before packing it into the image
         """
         args = ['-p', '-I', self._indir, '-d', self.TestFile(fname)]
@@ -204,7 +204,7 @@ class TestFunctional(unittest.TestCase):
                 test contents (the U_BOOT_DTB_DATA string) can be used.
                 But in some test we need the real contents.
             map: True to output map files for the images
-            update_dtb: Update the position and size of each entry in the device
+            update_dtb: Update the offset and size of each entry in the device
                 tree before packing it into the image
 
         Returns:
@@ -257,7 +257,7 @@ class TestFunctional(unittest.TestCase):
         """Create a new test input file, creating directories as needed
 
         Args:
-            fname: Filenaem to create
+            fname: Filename to create
             contents: File contents to write in to the file
         Returns:
             Full pathname of file created
@@ -292,10 +292,10 @@ class TestFunctional(unittest.TestCase):
         Args:
             entries: List of entries to check
         """
-        pos = 0
+        offset = 0
         for entry in entries.values():
-            self.assertEqual(pos, entry.pos)
-            pos += entry.size
+            self.assertEqual(offset, entry.offset)
+            offset += entry.size
 
     def GetFdtLen(self, dtb):
         """Get the totalsize field from a device-tree binary
@@ -319,7 +319,6 @@ class TestFunctional(unittest.TestCase):
                         prop_path = path + '/' + subnode.name + ':' + prop.name
                         tree[prop_path[len('/binman/'):]] = fdt_util.fdt32_to_cpu(
                             prop.value)
-                    #print '   ', prop.name
                 AddNode(subnode, path)
 
         tree = {}
@@ -467,32 +466,32 @@ class TestFunctional(unittest.TestCase):
         # First u-boot
         self.assertIn('u-boot', entries)
         entry = entries['u-boot']
-        self.assertEqual(0, entry.pos)
+        self.assertEqual(0, entry.offset)
         self.assertEqual(len(U_BOOT_DATA), entry.size)
 
         # Second u-boot, aligned to 16-byte boundary
         self.assertIn('u-boot-align', entries)
         entry = entries['u-boot-align']
-        self.assertEqual(16, entry.pos)
+        self.assertEqual(16, entry.offset)
         self.assertEqual(len(U_BOOT_DATA), entry.size)
 
         # Third u-boot, size 23 bytes
         self.assertIn('u-boot-size', entries)
         entry = entries['u-boot-size']
-        self.assertEqual(20, entry.pos)
+        self.assertEqual(20, entry.offset)
         self.assertEqual(len(U_BOOT_DATA), entry.contents_size)
         self.assertEqual(23, entry.size)
 
         # Fourth u-boot, placed immediate after the above
         self.assertIn('u-boot-next', entries)
         entry = entries['u-boot-next']
-        self.assertEqual(43, entry.pos)
+        self.assertEqual(43, entry.offset)
         self.assertEqual(len(U_BOOT_DATA), entry.size)
 
-        # Fifth u-boot, placed at a fixed position
+        # Fifth u-boot, placed at a fixed offset
         self.assertIn('u-boot-fixed', entries)
         entry = entries['u-boot-fixed']
-        self.assertEqual(61, entry.pos)
+        self.assertEqual(61, entry.offset)
         self.assertEqual(len(U_BOOT_DATA), entry.size)
 
         self.assertEqual(65, image._size)
@@ -510,32 +509,32 @@ class TestFunctional(unittest.TestCase):
         # First u-boot with padding before and after
         self.assertIn('u-boot', entries)
         entry = entries['u-boot']
-        self.assertEqual(0, entry.pos)
+        self.assertEqual(0, entry.offset)
         self.assertEqual(3, entry.pad_before)
         self.assertEqual(3 + 5 + len(U_BOOT_DATA), entry.size)
 
         # Second u-boot has an aligned size, but it has no effect
         self.assertIn('u-boot-align-size-nop', entries)
         entry = entries['u-boot-align-size-nop']
-        self.assertEqual(12, entry.pos)
+        self.assertEqual(12, entry.offset)
         self.assertEqual(4, entry.size)
 
         # Third u-boot has an aligned size too
         self.assertIn('u-boot-align-size', entries)
         entry = entries['u-boot-align-size']
-        self.assertEqual(16, entry.pos)
+        self.assertEqual(16, entry.offset)
         self.assertEqual(32, entry.size)
 
         # Fourth u-boot has an aligned end
         self.assertIn('u-boot-align-end', entries)
         entry = entries['u-boot-align-end']
-        self.assertEqual(48, entry.pos)
+        self.assertEqual(48, entry.offset)
         self.assertEqual(16, entry.size)
 
         # Fifth u-boot immediately afterwards
         self.assertIn('u-boot-align-both', entries)
         entry = entries['u-boot-align-both']
-        self.assertEqual(64, entry.pos)
+        self.assertEqual(64, entry.offset)
         self.assertEqual(64, entry.size)
 
         self.CheckNoGaps(entries)
@@ -556,10 +555,10 @@ class TestFunctional(unittest.TestCase):
                       "power of two", str(e.exception))
 
     def testPackInvalidAlign(self):
-        """Test detection of an position that does not match its alignment"""
+        """Test detection of an offset that does not match its alignment"""
         with self.assertRaises(ValueError) as e:
             self._DoTestFile('12_pack_inv_align.dts')
-        self.assertIn("Node '/binman/u-boot': Position 0x5 (5) does not match "
+        self.assertIn("Node '/binman/u-boot': Offset 0x5 (5) does not match "
                       "align 0x4 (4)", str(e.exception))
 
     def testPackInvalidSizeAlign(self):
@@ -573,7 +572,7 @@ class TestFunctional(unittest.TestCase):
         """Test that overlapping regions are detected"""
         with self.assertRaises(ValueError) as e:
             self._DoTestFile('14_pack_overlap.dts')
-        self.assertIn("Node '/binman/u-boot-align': Position 0x3 (3) overlaps "
+        self.assertIn("Node '/binman/u-boot-align': Offset 0x3 (3) overlaps "
                       "with previous entry '/binman/u-boot' ending at 0x4 (4)",
                       str(e.exception))
 
@@ -651,11 +650,11 @@ class TestFunctional(unittest.TestCase):
         self.assertEqual(chr(0) * 1 + U_BOOT_SPL_DATA + chr(0) * 2 +
                          U_BOOT_DATA, data)
 
-    def testPackZeroPosition(self):
-        """Test that an entry at position 0 is not given a new position"""
+    def testPackZeroOffset(self):
+        """Test that an entry at offset 0 is not given a new offset"""
         with self.assertRaises(ValueError) as e:
             self._DoTestFile('25_pack_zero_size.dts')
-        self.assertIn("Node '/binman/u-boot-spl': Position 0x0 (0) overlaps "
+        self.assertIn("Node '/binman/u-boot-spl': Offset 0x0 (0) overlaps "
                       "with previous entry '/binman/u-boot' ending at 0x4 (4)",
                       str(e.exception))
 
@@ -672,10 +671,10 @@ class TestFunctional(unittest.TestCase):
                       "using end-at-4gb", str(e.exception))
 
     def testPackX86RomOutside(self):
-        """Test that the end-at-4gb property checks for position boundaries"""
+        """Test that the end-at-4gb property checks for offset boundaries"""
         with self.assertRaises(ValueError) as e:
             self._DoTestFile('28_pack_4gb_outside.dts')
-        self.assertIn("Node '/binman/u-boot': Position 0x0 (0) is outside "
+        self.assertIn("Node '/binman/u-boot': Offset 0x0 (0) is outside "
                       "the section starting at 0xffffffe0 (4294967264)",
                       str(e.exception))
 
@@ -697,9 +696,9 @@ class TestFunctional(unittest.TestCase):
         """Test that the Intel requires a descriptor entry"""
         with self.assertRaises(ValueError) as e:
             self._DoTestFile('30_x86-rom-me-no-desc.dts')
-        self.assertIn("Node '/binman/intel-me': No position set with "
-                      "pos-unset: should another entry provide this correct "
-                      "position?", str(e.exception))
+        self.assertIn("Node '/binman/intel-me': No offset set with "
+                      "offset-unset: should another entry provide this correct "
+                      "offset?", str(e.exception))
 
     def testPackX86RomMe(self):
         """Test that an x86 ROM with an ME region can be created"""
@@ -728,7 +727,7 @@ class TestFunctional(unittest.TestCase):
         Returns:
             Tuple:
                 Contents of first region (U-Boot or SPL)
-                Position and size components of microcode pointer, as inserted
+                Offset and size components of microcode pointer, as inserted
                     in the above (two 4-byte words)
         """
         data = self._DoReadFile(dts_fname, True)
@@ -761,7 +760,7 @@ class TestFunctional(unittest.TestCase):
         self.assertEqual(ucode_data, ucode_content[:len(ucode_data)])
 
         # Check that the microcode pointer was inserted. It should match the
-        # expected position and size
+        # expected offset and size
         pos_and_size = struct.pack('<2L', 0xfffffe00 + ucode_pos,
                                    len(ucode_data))
         u_boot = data[:len(nodtb_data)]
@@ -806,7 +805,7 @@ class TestFunctional(unittest.TestCase):
         ucode_pos = second.find(ucode_data) + len(U_BOOT_NODTB_DATA)
 
         # Check that the microcode pointer was inserted. It should match the
-        # expected position and size
+        # expected offset and size
         pos_and_size = struct.pack('<2L', 0xfffffe00 + ucode_pos,
                                    len(ucode_data))
         first = data[:len(U_BOOT_NODTB_DATA)]
@@ -890,7 +889,7 @@ class TestFunctional(unittest.TestCase):
         """Test that microcode must be placed within the image"""
         with self.assertRaises(ValueError) as e:
             self._DoReadFile('41_unknown_pos_size.dts', True)
-        self.assertIn("Section '/binman': Unable to set pos/size for unknown "
+        self.assertIn("Section '/binman': Unable to set offset/size for unknown "
                 "entry 'invalid-entry'", str(e.exception))
 
     def testPackFsp(self):
@@ -984,7 +983,7 @@ class TestFunctional(unittest.TestCase):
         elf_fname = self.TestFile('u_boot_binman_syms')
         syms = elf.GetSymbols(elf_fname, ['binman', 'image'])
         addr = elf.GetSymbolAddress(elf_fname, '__image_copy_start')
-        self.assertEqual(syms['_binman_u_boot_spl_prop_pos'].address, addr)
+        self.assertEqual(syms['_binman_u_boot_spl_prop_offset'].address, addr)
 
         with open(self.TestFile('u_boot_binman_syms')) as fd:
             TestFunctional._MakeInputFile('spl/u-boot-spl', fd.read())
@@ -1009,7 +1008,7 @@ class TestFunctional(unittest.TestCase):
     def testMap(self):
         """Tests outputting a map of the images"""
         _, _, map_data, _ = self._DoReadFileDtb('55_sections.dts', map=True)
-        self.assertEqual('''Position      Size  Name
+        self.assertEqual('''  Offset      Size  Name
 00000000  00000010  section@0
  00000000  00000004  u-boot
 00000010  00000010  section@1
@@ -1019,7 +1018,7 @@ class TestFunctional(unittest.TestCase):
     def testNamePrefix(self):
         """Tests that name prefixes are used"""
         _, _, map_data, _ = self._DoReadFileDtb('56_name_prefix.dts', map=True)
-        self.assertEqual('''Position      Size  Name
+        self.assertEqual('''  Offset      Size  Name
 00000000  00000010  section@0
  00000000  00000004  ro-u-boot
 00000010  00000010  section@1
@@ -1042,24 +1041,24 @@ class TestFunctional(unittest.TestCase):
                       '2 to 1', str(e.exception))
 
     def testUpdateFdt(self):
-        """Test that we can update the device tree with pos/size info"""
+        """Test that we can update the device tree with offset/size info"""
         _, _, _, out_dtb_fname = self._DoReadFileDtb('60_fdt_update.dts',
                                                      update_dtb=True)
-        props = self._GetPropTree(out_dtb_fname, ['pos', 'size'])
+        props = self._GetPropTree(out_dtb_fname, ['offset', 'size'])
         with open('/tmp/x.dtb', 'wb') as outf:
             with open(out_dtb_fname) as inf:
                 outf.write(inf.read())
         self.assertEqual({
-            '_testing:pos': 32,
+            '_testing:offset': 32,
             '_testing:size': 1,
-            'section@0/u-boot:pos': 0,
+            'section@0/u-boot:offset': 0,
             'section@0/u-boot:size': len(U_BOOT_DATA),
-            'section@0:pos': 0,
+            'section@0:offset': 0,
             'section@0:size': 16,
 
-            'section@1/u-boot:pos': 0,
+            'section@1/u-boot:offset': 0,
             'section@1/u-boot:size': len(U_BOOT_DATA),
-            'section@1:pos': 16,
+            'section@1:offset': 16,
             'section@1:size': 16,
             'size': 40
         }, props)

tools/binman/image.py

@@ -57,7 +57,7 @@ class Image:
     def AddMissingProperties(self):
         """Add properties that are not present in the device tree
 
-        When binman has completed packing the entries the position and size of
+        When binman has completed packing the entries the offset and size of
         each entry are known. But before this the device tree may not specify
         these. Add any missing properties, with a dummy value, so that the
         size of the entry is correct. That way we can insert the correct values
@@ -73,13 +73,13 @@ class Image:
         """
         self._section.GetEntryContents()
 
-    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.
         """
-        self._section.GetEntryPositions()
+        self._section.GetEntryOffsets()
 
     def PackEntries(self):
         """Pack all entries into the image"""
@@ -121,5 +121,5 @@ class Image:
         filename = '%s.map' % self._name
         fname = tools.GetOutputFilename(filename)
         with open(fname, 'w') as fd:
-            print('%8s  %8s  %s' % ('Position', 'Size', 'Name'), file=fd)
+            print('%8s  %8s  %s' % ('Offset', 'Size', 'Name'), file=fd)
             self._section.WriteMap(fd, 0)

tools/binman/test/08_pack.dts

@@ -24,7 +24,7 @@
 
 		u-boot-fixed {
 			type = "u-boot";
-			pos = <61>;
+			offset = <61>;
 		};
 	};
 };

tools/binman/test/12_pack_inv_align.dts

@@ -6,7 +6,7 @@
 
 	binman {
 		u-boot {
-			pos = <5>;
+			offset = <5>;
 			align = <4>;
 		};
 	};

tools/binman/test/14_pack_overlap.dts

@@ -10,7 +10,7 @@
 
 		u-boot-align {
 			type = "u-boot";
-			pos = <3>;
+			offset = <3>;
 		};
 	};
 };

tools/binman/test/21_image_pad.dts

@@ -10,7 +10,7 @@
 		};
 
 		u-boot {
-			pos = <20>;
+			offset = <20>;
 		};
 	};
 };

tools/binman/test/24_sorted.dts

@@ -5,13 +5,13 @@
 	#size-cells = <1>;
 
 	binman {
-		sort-by-pos;
+		sort-by-offset;
 		u-boot {
-			pos = <22>;
+			offset = <22>;
 		};
 
 		u-boot-spl {
-			pos = <1>;
+			offset = <1>;
 		};
 	};
 };

tools/binman/test/25_pack_zero_size.dts

@@ -9,7 +9,7 @@
 		};
 
 		u-boot-spl {
-			pos = <0>;
+			offset = <0>;
 		};
 	};
 };

tools/binman/test/27_pack_4gb_no_size.dts

@@ -5,14 +5,14 @@
 	#size-cells = <1>;
 
 	binman {
-		sort-by-pos;
+		sort-by-offset;
 		end-at-4gb;
 		u-boot {
-			pos = <0xfffffff0>;
+			offset = <0xfffffff0>;
 		};
 
 		u-boot-spl {
-			pos = <0xfffffff7>;
+			offset = <0xfffffff7>;
 		};
 	};
 };

tools/binman/test/28_pack_4gb_outside.dts

@@ -5,15 +5,15 @@
 	#size-cells = <1>;
 
 	binman {
-		sort-by-pos;
+		sort-by-offset;
 		end-at-4gb;
 		size = <32>;
 		u-boot {
-			pos = <0>;
+			offset = <0>;
 		};
 
 		u-boot-spl {
-			pos = <0xffffffeb>;
+			offset = <0xffffffeb>;
 		};
 	};
 };

tools/binman/test/29_x86-rom.dts

@@ -5,15 +5,15 @@
 	#size-cells = <1>;
 
 	binman {
-		sort-by-pos;
+		sort-by-offset;
 		end-at-4gb;
 		size = <32>;
 		u-boot {
-			pos = <0xffffffe0>;
+			offset = <0xffffffe0>;
 		};
 
 		u-boot-spl {
-			pos = <0xffffffeb>;
+			offset = <0xffffffeb>;
 		};
 	};
 };

tools/binman/test/30_x86-rom-me-no-desc.dts

@@ -5,12 +5,12 @@
 	#size-cells = <1>;
 
 	binman {
-		sort-by-pos;
+		sort-by-offset;
 		end-at-4gb;
 		size = <16>;
 		intel-me {
 			filename = "me.bin";
-			pos-unset;
+			offset-unset;
 		};
 	};
 };

tools/binman/test/31_x86-rom-me.dts

@@ -5,7 +5,7 @@
 	#size-cells = <1>;
 
 	binman {
-		sort-by-pos;
+		sort-by-offset;
 		end-at-4gb;
 		size = <0x800000>;
 		intel-descriptor {
@@ -14,7 +14,7 @@
 
 		intel-me {
 			filename = "me.bin";
-			pos-unset;
+			offset-unset;
 		};
 	};
 };

tools/binman/test/34_x86_ucode.dts

@@ -5,7 +5,7 @@
 	#size-cells = <1>;
 
 	binman {
-		sort-by-pos;
+		sort-by-offset;
 		end-at-4gb;
 		size = <0x200>;
 		u-boot-with-ucode-ptr {

tools/binman/test/35_x86_single_ucode.dts

@@ -5,7 +5,7 @@
 	#size-cells = <1>;
 
 	binman {
-		sort-by-pos;
+		sort-by-offset;
 		end-at-4gb;
 		size = <0x200>;
 		u-boot-with-ucode-ptr {

tools/binman/test/37_x86_no_ucode.dts

@@ -5,7 +5,7 @@
 	#size-cells = <1>;
 
 	binman {
-		sort-by-pos;
+		sort-by-offset;
 		end-at-4gb;
 		size = <0x200>;
 		u-boot-with-ucode-ptr {

tools/binman/test/38_x86_ucode_missing_node.dts

@@ -5,7 +5,7 @@
 	#size-cells = <1>;
 
 	binman {
-		sort-by-pos;
+		sort-by-offset;
 		end-at-4gb;
 		size = <0x200>;
 		u-boot-with-ucode-ptr {

tools/binman/test/39_x86_ucode_missing_node2.dts

@@ -5,7 +5,7 @@
 	#size-cells = <1>;
 
 	binman {
-		sort-by-pos;
+		sort-by-offset;
 		end-at-4gb;
 		size = <0x200>;
 		u-boot-with-ucode-ptr {

tools/binman/test/40_x86_ucode_not_in_image.dts

@@ -5,7 +5,7 @@
 	#size-cells = <1>;
 
 	binman {
-		sort-by-pos;
+		sort-by-offset;
 		size = <0x200>;
 		u-boot-with-ucode-ptr {
 		};

tools/binman/test/44_x86_optional_ucode.dts

@@ -5,7 +5,7 @@
 	#size-cells = <1>;
 
 	binman {
-		sort-by-pos;
+		sort-by-offset;
 		end-at-4gb;
 		size = <0x200>;
 		u-boot-with-ucode-ptr {

tools/binman/test/45_prop_test.dts

@@ -5,12 +5,12 @@
 	#size-cells = <1>;
 
 	binman {
-		sort-by-pos;
+		sort-by-offset;
 		end-at-4gb;
 		size = <16>;
 		intel-me {
 			filename = "me.bin";
-			pos-unset;
+			offset-unset;
 			intval = <3>;
 			intarray = <5 6>;
 			byteval = [08];

tools/binman/test/49_x86_ucode_spl.dts

@@ -5,7 +5,7 @@
 	#size-cells = <1>;
 
 	binman {
-		sort-by-pos;
+		sort-by-offset;
 		end-at-4gb;
 		size = <0x200>;
 		u-boot-spl-with-ucode-ptr {

tools/binman/test/53_symbols.dts

@@ -10,7 +10,7 @@
 		};
 
 		u-boot {
-			pos = <20>;
+			offset = <20>;
 		};
 
 		u-boot-spl2 {

tools/binman/test/58_x86_ucode_spl_needs_retry.dts

@@ -7,7 +7,7 @@
 	#size-cells = <1>;
 
 	binman {
-		sort-by-pos;
+		sort-by-offset;
 		end-at-4gb;
 		size = <0x200>;
 		u-boot-spl-with-ucode-ptr {

tools/binman/test/u_boot_binman_syms.c

@@ -8,6 +8,6 @@
 #define CONFIG_BINMAN
 #include <binman_sym.h>
 
-binman_sym_declare(unsigned long, u_boot_spl, pos);
-binman_sym_declare(unsigned long long, u_boot_spl2, pos);
-binman_sym_declare(unsigned long, u_boot_any, pos);
+binman_sym_declare(unsigned long, u_boot_spl, offset);
+binman_sym_declare(unsigned long long, u_boot_spl2, offset);
+binman_sym_declare(unsigned long, u_boot_any, offset);