Initial version of qemu-sanity-check.

[qemu-sanity-check.git] / qemu-sanity-check.pod.in

diff --git a/qemu-sanity-check.pod.in b/qemu-sanity-check.pod.in
new file mode 100644 (file)
index 0000000..836fb1f
--- /dev/null
+++ b/qemu-sanity-check.pod.in
@@ -0,0 +1,138 @@
+=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<-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<-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<-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 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., 675 Mass Ave, Cambridge, MA 02139, USA.