Skip to contentSkip to conversation

kern/xen: Add Xen command line parsing

PATCH RESEND Superseded Aaron Rainbolt 2 participants 5 messages Jul 21, 2025 – Jul 25, 2025

v3 of 5 Superseded Latest is v5 →

lore
Share & tools
lore
#0 lore raw

v3 cover kern/xen: Add Xen command line parsing

The purpose of this patch is to allow the Xen hypervisor to pass extra data to GRUB in the form of a kernel command line, allowing the host to customize the boot process of the guest. The command line from Xen is parsed, and any variables within that start with the string xen_grub_env_ are exposed as environment variables. The grub.cfg script can then use those environment variables as it sees fit.

The main reason for doing this is to allow implementing boot modes in Qubes OS while also using in-VM kernels. For more context on Qubes boot modes, see [1]. In order for this to work with in-VM kernels, it is necessary for dom0 to pass kernel parameters to the guest without modifying the guest's grub.cfg manually. This patch allows this to be done, by allowing dom0 to pass kernel parameters to GRUB, which then provides them to grub.cfg as an environment variable. The grub.cfg script within the VM can then append those variables to the kernel command line.

The patch's code is unchanged from the last time I sent it [2], I've simply rebased it on top of the latest commit at the time of this writing (0e36779). I have not run it through the full test suite used previously, but I have ensured that both PV and PVH bootloaders build successfully and can boot an Arch Linux virtual machine on an Arch Linux host.

Changes from the version 2 of the patch:

* Added documentation for the future to the GRUB manual.
* Fixed error checking when allocating memory.
* Enhanced coding style, code efficiency, and comments based on Daniel Kiper's previous review and my own re-review.
* Added an explicit null termination check on the Xen-provided kernel command line before parsing.
* Fixed some memory management issues that could result in unnecessary memory consumption (one memory leak and a couple of places where an extra byte was allocated that didn't need to be).

[1] https://github.com/QubesOS/qubes-linux-pvgrub2/pull/16
[2] https://lists.gnu.org/archive/html/grub-devel/2025-06/msg00011.html

Aaron Rainbolt (1):
kern/xen: Add Xen command line parsing

 docs/grub.texi                |  50 +++++
 grub-core/Makefile.core.def   |   2 +
 grub-core/kern/i386/xen/pvh.c |  14 ++
 grub-core/kern/main.c         |  12 ++
 grub-core/kern/xen/cmdline.c  | 343 ++++++++++++++++++++++++++++++++++
 include/grub/xen.h            |   2 +
 6 files changed, 423 insertions(+)
 create mode 100644 grub-core/kern/xen/cmdline.c
Signature · 1 line
2.50.1

_______________________________________________
Grub-devel mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/grub-devel

#1 lore raw

PATCH RESEND v3 1/1 kern/xen: Add Xen command line parsing

Xen traditionally allows customizing guest behavior by passing arguments to the VM kernel via the kernel command line. This is no longer possible when using GRUB with Xen, as the kernel command line is decided by the GRUB configuration file within the guest, not data passed to the guest by Xen.

To work around this limitation, enable GRUB to parse a command line passed to it by Xen, and expose data from the command line to the GRUB configuration as environment variables. These variables can be used in the GRUB configuration for any desired purpose, such as extending the kernel command line passed to the guest. The command line format is inspired by the Linux kernel's command line format.

To reduce the risk of misuse, abuse, or accidents in production, the command line will only be parsed if it consists entirely of 7-bit ASCII characters, only alphabetical characters and underscores are permitted in variable names, and all variable names must start with the string "xen_grub_env_". This also allows room for expanding the command line arguments accepted by GRUB in the future, should other arguments end up becoming desirable in the future.

---
 docs/grub.texi                |  50 +++++
 grub-core/Makefile.core.def   |   2 +
 grub-core/kern/i386/xen/pvh.c |  14 ++
 grub-core/kern/main.c         |  12 ++
 grub-core/kern/xen/cmdline.c  | 343 ++++++++++++++++++++++++++++++++++
 include/grub/xen.h            |   2 +
 6 files changed, 423 insertions(+)
 create mode 100644 grub-core/kern/xen/cmdline.c
docs/grub.texi +50 -0
index 34b3484..ce82483 100644
@@ -3271,6 +3271,7 @@ GRUB.  Others may be used freely in GRUB configuration files.
 @menu
 * Special environment variables::
 * Environment block::
+* Passing environment variables through Xen::
 @end menu
 
 
@@ -3871,6 +3872,55 @@ using BIOS or EFI functions (no ATA, USB or IEEE1275).
 @command{grub-mkconfig} uses this facility to implement
 @samp{GRUB_SAVEDEFAULT} (@pxref{Simple configuration}).
 
+@node Passing environment variables through Xen
+@section Passing environment variables through Xen
+
+If you are using a GRUB image as the kernel for a PV or PVH Xen virtual
+machine, you can pass environment variables from Xen's dom0 to the VM through
+the Xen-provided kernel command line. When combined with a properly configured
+guest, this can be used to customize the guest's behavior on bootup via the
+VM's Xen configuration file.
+
+GRUB will parse the kernel command line passed to it by Xen during bootup.
+The command line will be split into space-delimited words. Single and
+double quotes may be used to quote words or portions of words that contain
+spaces. Arbitrary characters may be backslash-escaped to make them a literal
+component of a word rather than being parsed as quotes or word separators. The
+command line must consist entirely of printable 7-bit ASCII characters and
+spaces. If a non-printing ASCII character is found anywhere in the command
+line, the entire command line will be ignored by GRUB.
+
+Each word should be a variable assignment in the format ``variable'' or
+``variable=value''. Variable names must contain only the characters A-Z, a-z,
+and underscore (``_''). Variable names must begin with the string
+``xen_grub_env_''. Variable values can contain arbitrary printable 7-bit
+ASCII characters and space. If any variable contains an illegal name, that
+variable will be ignored.
+
+If a variable name and value are both specified, the variable will be set to
+the specified value. If only a variable name is specified, the variable's
+value will be set to ``1''.
+
+The following is a simple example of how to use this functionality to append
+arbitrary variables to a guest's kernel command line:
+
+@example
+# In the Xen configuration file for the guest
+name = "linux_vm"
+type = "pvh"
+kernel = "/path/to/grub-i386-xen_pvh.bin"
+extra = "xen_grub_env_kernelappend='loglevel=3'"
+memory = 1024
+disk = [ "file:/srv/vms/linux_vm.img,sda,w" ]
+
+# In the guest's GRUB configuration file
+menuentry "Linux VM with dom0-specified kernel parameters" @{
+    search --set=root --label linux_vm --hint hd0,msdos1
+    linux /boot/vmlinuz root=LABEL=linux_vm $@{xen_grub_env_kernelappend@}
+    initrd /boot/initrd.img
+@}
+@end example
+
 @node Modules
 @chapter Modules
 
grub-core/Makefile.core.def +2 -0
index b3f7119..df0f266 100644
@@ -248,6 +248,7 @@ kernel = {
   xen = term/xen/console.c;
   xen = disk/xen/xendisk.c;
   xen = commands/boot.c;
+  xen = kern/xen/cmdline.c;
 
   i386_xen_pvh = commands/boot.c;
   i386_xen_pvh = disk/xen/xendisk.c;
@@ -255,6 +256,7 @@ kernel = {
   i386_xen_pvh = kern/i386/xen/tsc.c;
   i386_xen_pvh = kern/i386/xen/pvh.c;
   i386_xen_pvh = kern/xen/init.c;
+  i386_xen_pvh = kern/xen/cmdline.c;
   i386_xen_pvh = term/xen/console.c;
 
   ia64_efi = kern/ia64/efi/startup.S;
grub-core/kern/i386/xen/pvh.c +14 -0
index 91fbca8..12df2d8 100644
@@ -321,6 +321,8 @@ void
 grub_xen_setup_pvh (void)
 {
   grub_addr_t par;
+  const char *xen_cmdline;
+  int i;
 
   grub_xen_cpuid_base ();
   grub_xen_setup_hypercall_page ();
@@ -352,6 +354,18 @@ grub_xen_setup_pvh (void)
   grub_xen_mm_init_regions ();
 
   grub_rsdp_addr = pvh_start_info->rsdp_paddr;
+
+  xen_cmdline = (const char *) pvh_start_info->cmdline_paddr;
+  for (i = 0; i < MAX_GUEST_CMDLINE; i++)
+    {
+      if (xen_cmdline[i] == '\0')
+        {
+          grub_strncpy ((char *) grub_xen_start_page_addr->cmd_line,
+			(char *) pvh_start_info->cmdline_paddr,
+			MAX_GUEST_CMDLINE);
+          break;
+        }
+    }
 }
 
 grub_err_t
grub-core/kern/main.c +12 -0
index 143a232..b4377d3 100644
@@ -37,6 +37,10 @@
 #include <grub/machine/memory.h>
 #endif
 
+#if defined (GRUB_MACHINE_XEN) || defined (GRUB_MACHINE_XEN_PVH)
+#include <grub/xen.h>
+#endif
+
 static bool cli_disabled = false;
 static bool cli_need_auth = false;
 
@@ -351,6 +355,14 @@ grub_main (void)
   grub_env_export ("root");
   grub_env_export ("prefix");
 
+  /*
+   * Parse command line parameters from Xen and export them as environment
+   * variables
+   */
+#if defined (GRUB_MACHINE_XEN) || defined (GRUB_MACHINE_XEN_PVH)
+  grub_parse_xen_cmdline ();
+#endif
+
   /* Reclaim space used for modules.  */
   reclaim_module_space ();
 
grub-core/kern/xen/cmdline.c new file +343 -0

343 lines not on this page · raw message

include/grub/xen.h +2 -0
index 91cb7cf..7f9efee 100644
@@ -89,6 +89,8 @@ void grub_console_init (void);
 void grub_xendisk_fini (void);
 void grub_xendisk_init (void);
 
+void grub_parse_xen_cmdline (void);
+
 #ifdef __x86_64__
 typedef grub_uint64_t grub_xen_mfn_t;
 #else
Signature · 1 line
2.50.1

_______________________________________________
Grub-devel mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/grub-devel

#2 lore raw
In reply to Aaron Rainbolt

Hey,

I will review this patch set when you CC Xen-devel ML. I have asked about this last time...

Daniel

Quoted 17 lines · Aaron Rainbolt

The purpose of this patch is to allow the Xen hypervisor to pass extra data to GRUB in the form of a kernel command line, allowing the host to customize the boot process of the guest. The command line from Xen is parsed, and any variables within that start with the string xen_grub_env_ are exposed as environment variables. The grub.cfg script can then use those environment variables as it sees fit.

The main reason for doing this is to allow implementing boot modes in Qubes OS while also using in-VM kernels. For more context on Qubes boot modes, see [1]. In order for this to work with in-VM kernels, it is necessary for dom0 to pass kernel parameters to the guest without modifying the guest's grub.cfg manually. This patch allows this to be done, by allowing dom0 to pass kernel parameters to GRUB, which then provides them to grub.cfg as an environment variable. The grub.cfg script within the VM can then append those variables to the kernel command line.

Quoted 6 lines

The patch's code is unchanged from the last time I sent it [2], I've simply rebased it on top of the latest commit at the time of this writing (0e36779). I have not run it through the full test suite used previously, but I have ensured that both PV and PVH bootloaders build successfully and can boot an Arch Linux virtual machine on an Arch Linux host.

_______________________________________________
Grub-devel mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/grub-devel

#3 lore raw
Quoted 5 lines · Daniel Kiper

Hey,

I will review this patch set when you CC Xen-devel ML. I have asked about this last time...

Hi Daniel, the V3 version of this patch (which is the same as this version, just based on a now-older commit) was already sent to the Xen-devel ML, as can be seen at [1], [2]. I did forget to resend the patch to the Xen-devel ML when I resent it to Grub-devel, but it has already had well over a month to be reviewed by the Xen team with no response. If you wish for me to resend it again, I will do so (but not copy the Grub-devel ML on it so as to avoid excessive noise).

[1] https://lists.xenproject.org/archives/html/xen-devel/2025-06/msg00298.html
[2] https://lists.xenproject.org/archives/html/xen-devel/2025-06/msg00299.html

--
Aaron

Quoted 26 lines

Daniel

Quoted 23 lines · Aaron Rainbolt

The purpose of this patch is to allow the Xen hypervisor to pass extra data to GRUB in the form of a kernel command line, allowing the host to customize the boot process of the guest. The command line from Xen is parsed, and any variables within that start with the string xen_grub_env_ are exposed as environment variables. The grub.cfg script can then use those environment variables as it sees fit.

The main reason for doing this is to allow implementing boot modes in Qubes OS while also using in-VM kernels. For more context on Qubes boot modes, see [1]. In order for this to work with in-VM kernels, it is necessary for dom0 to pass kernel parameters to the guest without modifying the guest's grub.cfg manually. This patch allows this to be done, by allowing dom0 to pass kernel parameters to GRUB, which then provides them to grub.cfg as an environment variable. The grub.cfg script within the VM can then append those variables to the kernel command line.

The patch's code is unchanged from the last time I sent it [2], I've simply rebased it on top of the latest commit at the time of this writing (0e36779). I have not run it through the full test suite used previously, but I have ensured that both PV and PVH bootloaders build successfully and can boot an Arch Linux virtual machine on an Arch Linux host.

_______________________________________________
Grub-devel mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/grub-devel

#4 lore raw
Quoted 7 lines · Aaron Rainbolt
Quoted 5 lines · Daniel Kiper

Hey,

I will review this patch set when you CC Xen-devel ML. I have asked about this last time...

Quoted 7 lines

Hi Daniel, the V3 version of this patch (which is the same as this version, just based on a now-older commit) was already sent to the Xen-devel ML, as can be seen at [1], [2]. I did forget to resend the patch to the Xen-devel ML when I resent it to Grub-devel, but it has already had well over a month to be reviewed by the Xen team with no response. If you wish for me to resend it again, I will do so (but not copy the Grub-devel ML on it so as to avoid excessive noise).

Please resend the same patch/email to grub-devel and Xen-devel at the same time. There is a chance somebody will jump in if he sees some interest on the GRUB side.

Quoted 2 lines

[1] https://lists.xenproject.org/archives/html/xen-devel/2025-06/msg00298.html
[2] https://lists.xenproject.org/archives/html/xen-devel/2025-06/msg00299.html

Daniel

_______________________________________________
Grub-devel mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/grub-devel