qemu-sanity-check.pod.in

   1 =encoding utf8
   2
   3 =head1 NAME
   4
   5 qemu-sanity-check - run a simple sanity check on qemu and the Linux kernel
   6
   7 =head1 SUMMARY
   8
   9 qemu-sanity-check [options]
  10
  11 =head1 DESCRIPTION
  12
  13 B<qemu-sanity-check> is a short shell script that test-boots a Linux
  14 kernel under qemu, making sure it boots up to userspace.  The idea is
  15 to test the Linux kernel and/or qemu to make sure they are working.
  16
  17 You can use the command on its own:
  18
  19  qemu-sanity-check
  20
  21 In this case, the script will look for a suitable qemu binary on the
  22 C<$PATH> and the latest Linux kernel in F</boot> (or
  23 F</lib/modules/VERSION/vmlinuz> on some distros) and try to boot that
  24 kernel on that qemu.
  25
  26 You can also specify a qemu binary or a Linux kernel (either or both
  27 options can be omitted):
  28
  29  qemu-sanity-check --qemu=/path/to/qemu --kernel=/path/to/vmlinuz
  30
  31 =head2 KVM
  32
  33 KVM (C<kvm> or C<qemu-kvm>) can be used in place of qemu.
  34
  35 =head2 KERNEL DRIVERS
  36
  37 No kernel modules or special drivers are required except as noted
  38 below.  The test uses an initramfs containing a static binary, so the
  39 kernel is B<not> required to locate block devices, use virtio, mount
  40 filesystems, etc.
  41
  42 The kernel B<must> support only the following, compiled in (not as
  43 modules):
  44
  45 =over 4
  46
  47 =item *
  48
  49 A serial port (usually: C<CONFIG_SERIAL_8250=y>)
  50
  51 =item *
  52
  53 Initrd/initramfs (C<CONFIG_BLK_DEV_INITRD=y>)
  54
  55 =back
  56
  57 =head1 OPTIONS
  58
  59 =over 4
  60
  61 =item B<--help>
  62
  63 Display short help message and exit.
  64
  65 =item B<--accel>=kvm
  66
  67 =item B<--accel>=tcg
  68
  69 =item B<--accel>=kvm:tcg
  70
  71 This sets the C<-machine accel=...> parameter which is passed to
  72 qemu.
  73
  74 If not set, then C<kvm:tcg> is the default, which means to try to use
  75 KVM (hardware-assisted virtualization), and fall back to software
  76 emulation if KVM is not possible.
  77
  78 Other typical values of this parameter are: C<tcg>, which means to
  79 force software emulation.  C<kvm>, which means to force KVM and fail
  80 if KVM is unavailable.
  81
  82 =item B<--cpu>=CPU
  83
  84 Set the qemu I<--cpu> option.  If not set then a suitable default is
  85 picked depending on the architecture and whether KVM is available.
  86 You can also use I<--cpu=> to let qemu pick the default.
  87
  88 =item B<-i> INITRD
  89
  90 =item B<--initrd>=INITRD
  91
  92 Use the initramfs image named F<INITRD> instead of the default.
  93
  94 =item B<-k> VMLINUZ
  95
  96 =item B<--kernel>=VMLINUZ
  97
  98 Use the kernel image F<VMLINUZ> instead of searching for the latest
  99 kernel installed in F</boot>.
 100
 101 =item B<-m> MACHINE
 102
 103 =item B<--machine>=MACHINE
 104
 105 Set the qemu I<-m> (machine type) option.  If not set then a suitable
 106 default is picked depending on the architecture.  You can also use
 107 I<--machine=> to let qemu pick the default.
 108
 109 =item B<-q> QEMU
 110
 111 =item B<--qemu>=QEMU
 112
 113 Use the qemu (or KVM) binary F<QEMU> instead of searching C<$PATH> for
 114 a suitable binary.
 115
 116 =item B<-t> TIMEOUT
 117
 118 =item B<--timeout>=TIMEOUT
 119
 120 Specify a timeout instead of the default which is C<10m> (10 minutes).
 121
 122 The syntax for the C<TIMEOUT> is described in full in the man page for
 123 L<timeout(1)>.
 124
 125 =item B<-v>
 126
 127 =item B<--verbose>
 128
 129 Print extra debugging information.
 130
 131 =item B<-V>
 132
 133 =item B<--version>
 134
 135 Display version and exit.
 136
 137 =back
 138
 139 =head1 EXIT STATUS
 140
 141 The exit status is 0 if the Linux kernel booted as far as userspace
 142 under qemu; or if the I<--help> or I<--version> options were used.
 143
 144 The exit status is 1 if the kernel boot failed under qemu.
 145
 146 The exit status is 2 if the script itself failed (eg. incorrect
 147 command line options were used, a suitable kernel could not be found).
 148
 149 =head1 FILES
 150
 151 =over 4
 152
 153 =item B<@libdir@/qemu-sanity-check/initrd>
 154
 155 The default location for the small initramfs image that is used to
 156 test that userspace has been reached.
 157
 158 =back
 159
 160 =head1 SEE ALSO
 161
 162 L<http://qemu.org>,
 163 L<http://kernel.org>
 164
 165 =head1 AUTHORS
 166
 167 Richard W.M. Jones <rjones@redhat.com>
 168
 169 =head1 COPYRIGHT
 170
 171 (C) Copyright 2013-2020 Red Hat Inc.
 172
 173 This program is free software; you can redistribute it and/or modify
 174 it under the terms of the GNU General Public License as published by
 175 the Free Software Foundation; either version 2 of the License, or
 176 (at your option) any later version.
 177
 178 This program is distributed in the hope that it will be useful,
 179 but WITHOUT ANY WARRANTY; without even the implied warranty of
 180 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 181 GNU General Public License for more details.
 182
 183 You should have received a copy of the GNU General Public License along
 184 with this program; if not, write to the Free Software Foundation, Inc.,
 185 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.