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 C</boot> and try to boot that
  23 kernel on that qemu.
  24
  25 You can also specify a qemu binary or a Linux kernel (either or both
  26 options can be omitted):
  27
  28  qemu-sanity-check --qemu=/path/to/qemu --kernel=/path/to/vmlinuz
  29
  30 =head2 KVM
  31
  32 KVM (C<kvm> or C<qemu-kvm>) can be used in place of qemu.
  33
  34 =head2 KERNEL DRIVERS
  35
  36 No kernel modules or special drivers are required except as noted
  37 below.  The test uses an initramfs containing a static binary, so the
  38 kernel is B<not> required to locate block devices, use virtio, mount
  39 filesystems, etc.
  40
  41 The kernel B<must> support only the following, compiled in (not as
  42 modules):
  43
  44 =over 4
  45
  46 =item *
  47
  48 A serial port (usually: C<CONFIG_SERIAL_8250=y>)
  49
  50 =item *
  51
  52 Initrd/initramfs (C<CONFIG_BLK_DEV_INITRD=y>)
  53
  54 =back
  55
  56 =head1 OPTIONS
  57
  58 =over 4
  59
  60 =item B<--help>
  61
  62 Display short help message and exit.
  63
  64 =item B<-i> INITRD
  65
  66 =item B<--initrd>=INITRD
  67
  68 Use the initramfs image named C<INITRD> instead of the default.
  69
  70 =item B<-k> VMLINUZ
  71
  72 =item B<--kernel>=VMLINUZ
  73
  74 Use the kernel image C<VMLINUZ> instead of searching for the latest
  75 kernel installed in C</boot>.
  76
  77 =item B<-q> QEMU
  78
  79 =item B<--qemu>=QEMU
  80
  81 Use the qemu (or KVM) binary C<QEMU> instead of searching C<$PATH> for
  82 a suitable binary.
  83
  84 =item B<-V>
  85
  86 =item B<--version>
  87
  88 Display version and exit.
  89
  90 =back
  91
  92 =head1 EXIT STATUS
  93
  94 The exit status is 0 if the Linux kernel booted as far as userspace
  95 under qemu; or if the I<--help> or I<--version> options were used.
  96
  97 The exit status is 1 if the kernel boot failed under qemu.
  98
  99 The exit status is 2 if the script itself failed (eg. incorrect
 100 command line options were used, a suitable kernel could not be found).
 101
 102 =head1 FILES
 103
 104 =over 4
 105
 106 =item B<@libdir@/qemu-sanity-check/initrd>
 107
 108 The default location for the small initramfs image that is used to
 109 test that userspace has been reached.
 110
 111 =back
 112
 113 =head1 BUGS
 114
 115 =head2 TIMEOUTS
 116
 117 Timeouts don't currently work because of some oddness with the
 118 coreutils L<timeout(1)> program and qemu.  Instead you should run the
 119 whole script with a timeout, like this:
 120
 121  timeout 10m qemu-sanity-check
 122
 123 =head1 SEE ALSO
 124
 125 L<http://qemu.org>,
 126 L<http://kernel.org>
 127
 128 =head1 AUTHORS
 129
 130 Richard W.M. Jones <rjones@redhat.com>
 131
 132 =head1 COPYRIGHT
 133
 134 (C) Copyright 2013 Red Hat Inc.
 135
 136 This program is free software; you can redistribute it and/or modify
 137 it under the terms of the GNU General Public License as published by
 138 the Free Software Foundation; either version 2 of the License, or
 139 (at your option) any later version.
 140
 141 This program is distributed in the hope that it will be useful,
 142 but WITHOUT ANY WARRANTY; without even the implied warranty of
 143 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 144 GNU General Public License for more details.
 145
 146 You should have received a copy of the GNU General Public License
 147 along with this program; if not, write to the Free Software
 148 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.