svn commit: r341160 - in head/stand/i386: common gptboot zfsboot

[Ian Lepore]

Author: ian
Date: Wed Nov 28 18:09:42 2018
New Revision: 341160
URL: https://svnweb.freebsd.org/changeset/base/341160

Log:
  Add comments describing the bootargs handoff between loader(8) and gptboot
  or zfsboot, when loader(8) is the BTX loader.  No functional changes.

Modified:
  head/stand/i386/common/bootargs.h
  head/stand/i386/gptboot/gptboot.c
  head/stand/i386/zfsboot/zfsboot.c

Modified: head/stand/i386/common/bootargs.h
==============================================================================
--- head/stand/i386/common/bootargs.h	Wed Nov 28 18:06:16 2018	(r341159)
+++ head/stand/i386/common/bootargs.h	Wed Nov 28 18:09:42 2018	(r341160)
@@ -43,6 +43,24 @@
 
 #ifndef __ASSEMBLER__
 
+/*
+ * This struct describes the contents of the stack on entry to btxldr.S.  This
+ * is the data that follows the return address, so it begins at 4(%esp).  On
+ * the sending side, this data is passed as individual args to __exec().  On the
+ * receiving side, code in btxldr.S copies the data from the entry stack to a
+ * known fixed location in the new address space.  Then, btxcsu.S sets the
+ * global variable __args to point to that known fixed location before calling
+ * main(), which casts __args to a struct bootargs pointer to access the data.
+ * The btxldr.S code is aware of KARGS_FLAGS_EXTARG, and if it's set, the extra
+ * args data is copied along with the other bootargs from the entry stack to the
+ * fixed location in the new address space.
+ *
+ * The bootinfo field is actually a pointer to a bootinfo struct that has been
+ * converted to uint32_t using VTOP().  On the receiving side it must be
+ * converted back to a pointer using PTOV().  Code in btxldr.S is aware of this
+ * field and if it's non-NULL it copies the data it points to into another known
+ * fixed location, and adjusts the bootinfo field to point to that new location.
+ */
 struct bootargs
 {
 	uint32_t			howto;

Modified: head/stand/i386/gptboot/gptboot.c
==============================================================================
--- head/stand/i386/gptboot/gptboot.c	Wed Nov 28 18:06:16 2018	(r341159)
+++ head/stand/i386/gptboot/gptboot.c	Wed Nov 28 18:09:42 2018	(r341160)
@@ -487,6 +487,12 @@ load(void)
 	geliargs.keybuf_sentinel = KEYBUF_SENTINEL;
 	geliargs.keybuf = gelibuf;
 #endif
+	/*
+	 * Note that the geliargs struct is passed by value, not by pointer.
+	 * Code in btxldr.S copies the values from the entry stack to a fixed
+	 * location within loader(8) at startup due to the presence of the
+	 * KARGS_FLAGS_EXTARG flag.
+	 */
 	__exec((caddr_t)addr, RB_BOOTINFO | (opts & RBX_MASK),
 	    MAKEBOOTDEV(dev_maj[gdsk.dsk.type], gdsk.dsk.part + 1, gdsk.dsk.unit, 0xff),
 #ifdef LOADER_GELI_SUPPORT

Modified: head/stand/i386/zfsboot/zfsboot.c
==============================================================================
--- head/stand/i386/zfsboot/zfsboot.c	Wed Nov 28 18:06:16 2018	(r341159)
+++ head/stand/i386/zfsboot/zfsboot.c	Wed Nov 28 18:09:42 2018	(r341160)
@@ -1005,6 +1005,11 @@ load(void)
 	zfsargs.primary_vdev = primary_vdev->v_guid;
     else
 	printf("failed to detect primary vdev\n");
+    /*
+     * Note that the zfsargs struct is passed by value, not by pointer.  Code in
+     * btxldr.S copies the values from the entry stack to a fixed location
+     * within loader(8) at startup due to the presence of KARGS_FLAGS_EXTARG.
+     */
     __exec((caddr_t)addr, RB_BOOTINFO | (opts & RBX_MASK),
 	   bootdev,
 	   KARGS_FLAGS_ZFS | KARGS_FLAGS_EXTARG,