=encoding utf8

=head1 NAME

qemu-sanity-check - run a simple sanity check on qemu and the Linux kernel

=head1 SUMMARY

qemu-sanity-check [options]

=head1 DESCRIPTION

B<qemu-sanity-check> is a short shell script that test-boots a Linux
kernel under qemu, making sure it boots up to userspace.  The idea is
to test the Linux kernel and/or qemu to make sure they are working.

You can use the command on its own:

 qemu-sanity-check

In this case, the script will look for a suitable qemu binary on the
C<$PATH> and the latest Linux kernel in C</boot> and try to boot that
kernel on that qemu.

You can also specify a qemu binary or a Linux kernel (either or both
options can be omitted):

 qemu-sanity-check --qemu=/path/to/qemu --kernel=/path/to/vmlinuz

=head2 KVM

KVM (C<kvm> or C<qemu-kvm>) can be used in place of qemu.

=head2 KERNEL DRIVERS

No kernel modules or special drivers are required except as noted
below.  The test uses an initramfs containing a static binary, so the
kernel is B<not> required to locate block devices, use virtio, mount
filesystems, etc.

The kernel B<must> support only the following, compiled in (not as
modules):

=over 4

=item *

A serial port (usually: C<CONFIG_SERIAL_8250=y>)

=item *

Initrd/initramfs (C<CONFIG_BLK_DEV_INITRD=y>)

=back

=head1 OPTIONS

=over 4

=item B<--help>

Display short help message and exit.

=item B<--accel>=kvm

=item B<--accel>=tcg

=item B<--accel>=kvm:tcg

This sets the C<-machine accel=...> parameter which is passed to
qemu.

If not set, then C<kvm:tcg> is the default, which means to try to use
KVM (hardware-assisted virtualization), and fall back to software
emulation if KVM is not possible.

Other typical values of this parameter are: C<tcg>, which means to
force software emulation.  C<kvm>, which means to force KVM and fail
if KVM is unavailable.

=item B<-i> INITRD

=item B<--initrd>=INITRD

Use the initramfs image named C<INITRD> instead of the default.

=item B<-k> VMLINUZ

=item B<--kernel>=VMLINUZ

Use the kernel image C<VMLINUZ> instead of searching for the latest
kernel installed in C</boot>.

=item B<-m> MACHINE

=item B<--machine>=MACHINE

Set the qemu I<-m> (machine type) option.  If not set then a suitable
default is picked depending on the architecture.  You can also use
I<--machine=> to let qemu pick the default.

=item B<-q> QEMU

=item B<--qemu>=QEMU

Use the qemu (or KVM) binary C<QEMU> instead of searching C<$PATH> for
a suitable binary.

=item B<-t> TIMEOUT

=item B<--timeout>=TIMEOUT

Specify a timeout instead of the default which is C<10m> (10 minutes).

The syntax for the C<TIMEOUT> is described in full in the man page for
L<timeout(1)>.

=item B<-V>

=item B<--version>

Display version and exit.

=back

=head1 EXIT STATUS

The exit status is 0 if the Linux kernel booted as far as userspace
under qemu; or if the I<--help> or I<--version> options were used.

The exit status is 1 if the kernel boot failed under qemu.

The exit status is 2 if the script itself failed (eg. incorrect
command line options were used, a suitable kernel could not be found).

=head1 FILES

=over 4

=item B<@libdir@/qemu-sanity-check/initrd>

The default location for the small initramfs image that is used to
test that userspace has been reached.

=back

=head1 SEE ALSO

L<http://qemu.org>,
L<http://kernel.org>

=head1 AUTHORS

Richard W.M. Jones <rjones@redhat.com>

=head1 COPYRIGHT

(C) Copyright 2013-2020 Red Hat Inc.

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License along
with this program; if not, write to the Free Software Foundation, Inc.,
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.