* [PATCH 1/2] Add a rudimentary manpage
2015-12-22 14:00 [PATCH 0/2] kvmtool: replace documentations stubs with manpage Andre Przywara
@ 2015-12-22 14:00 ` Andre Przywara
2015-12-22 15:11 ` Will Deacon
2015-12-22 14:00 ` [PATCH 2/2] Documentation: remove documentation stubs and common-cmds.h generation Andre Przywara
1 sibling, 1 reply; 4+ messages in thread
From: Andre Przywara @ 2015-12-22 14:00 UTC (permalink / raw)
To: will.deacon; +Cc: dimitri.j.ledkov, sasha.levin, penberg, kvmarm, kvm
The kvmtool documentation is somewhat lacking, also it is not easily
accessible when living in the source tree only.
Add a good ol' manpage to document at least the basic commands and
their options.
This level of documentation matches the one that is already there in
the Documentation directory and should be subject to extension.
Signed-off-by: Andre Przywara <andre.przywara@arm.com>
---
Documentation/kvmtool.1 | 222 ++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 222 insertions(+)
create mode 100644 Documentation/kvmtool.1
diff --git a/Documentation/kvmtool.1 b/Documentation/kvmtool.1
new file mode 100644
index 0000000..aecb2dc
--- /dev/null
+++ b/Documentation/kvmtool.1
@@ -0,0 +1,222 @@
+.\" Manpage for kvmtool
+.\" Copyright (C) 2015 by Andre Przywara <andre.przywara@arm.com>
+.TH kvmtool 1 "11 Nov 2015" "0.1" "kvmtool man page"
+.SH NAME
+kvmtool \- running KVM guests
+.SH SYNOPSIS
+lkvm COMMAND [ARGS]
+.SH DESCRIPTION
+kvmtool is a userland tool for creating and controlling KVM guests.
+.SH "KVMTOOL COMMANDS"
+.sp
+.PP
+.B run -k <kernel-image> ...
+.RS 4
+Run a guest.
+.sp
+.B \-k, \-\-kernel <image file>
+.RS 4
+The virtual machine kernel.
+.RE
+.sp
+.B \-c, \-\-cpus <n>
+.RS 4
+The number of virtual CPUs to run.
+.RE
+.sp
+.B \-m, \-\-mem <n>
+.RS 4
+Virtual machine memory size in MiB.
+.RE
+.sp
+.B \-p, \-\-params <parameters>
+.RS 4
+Additional kernel command line arguments.
+.RE
+.sp
+.B \-i, \-\-initrd <image file>
+.RS 4
+Initial RAM disk image.
+.RE
+.sp
+.B \-d, \-\-disk <image file|directory>
+.RS 4
+A disk image file or a rootfs directory.
+.RE
+.sp
+.B \-\-console serial|virtio|hv
+.RS 4
+Console to use.
+.RE
+.sp
+.B \-\-dev <device node>
+.RS 4
+KVM device file (instead of the default /dev/kvm).
+.RE
+.sp
+.B \-\-debug
+.RS 4
+Enable debug messages.
+.RE
+.sp
+.B \-\-debug-single-step
+.RS 4
+Enable single stepping.
+.RE
+.sp
+.B \-\-debug-ioport
+.RS 4
+Enable ioport debugging.
+.RE
+.RE
+.PP
+.B setup <name>
+.RS 4
+Setup a new virtual machine. This creates a new rootfs in the .lkvm
+folder of your home directory.
+.RE
+.PP
+.B pause \-\-all|\-\-name <name>
+.RS 4
+Pause a virtual machine.
+.sp
+.B \-a, \-\-all
+.RS 4
+Pause all running instances.
+.RE
+.sp
+.B \-n, \-\-name <name>
+.RS 4
+Pause that specified instance. For a list of running instances, see \fI lkvm list\fR.
+.RE
+.RE
+.PP
+.B resume --all|--name <name>
+.RS 4
+Resume a previously paused virtual machine.
+.sp
+.B \-a, \-\-all
+.RS 4
+Resume all running instances.
+.RE
+.sp
+.B \-n, \-\-name <name>
+.RS 4
+Resume that specified instance. For a list of running instances, see \fI lkvm list\fR.
+.RE
+.RE
+.PP
+.B list [\-i] [\-r]
+.RS 4
+Print a list of running instances on the host. This is restricted to instances
+started by the current user, as it looks in the .lkvm folder in your home
+directory to find the socket files.
+.sp
+.B \-i, \-\-run
+.RS 4
+List all running instances.
+.RE
+.sp
+.B \-r, \-\-rootfs
+.RS 4
+List rootfs instances.
+.RE
+.RE
+.PP
+.B debug --all|--name <guest name> [--dump] [--nmi <n>] [--sysrq <rq>]
+.RS 4
+Print debug information from a running VM instance.
+.sp
+.B \-a, \-\-all
+.RS 4
+Debug all running instances.
+.RE
+.PP
+.B \-n, \-\-name <guest name>
+.RS 4
+Debug the specified instance.
+.RE
+.sp
+.B \-d, \-\-dump
+.RS 4
+Generate a debug dump from guest.
+.RE
+.PP
+.B \-m, \-\-nmi <VCPU nr>
+.RS 4
+Generate an NMI on the specified virtual CPU.
+.RE
+.PP
+.B \-s, \-\-sysrq <sysrq>
+.RS 4
+Inject a Linux sysrq into the guest.
+.RE
+.RE
+.PP
+.B balloon \-\-name <guest name> \-\-inflate|\-\-deflate <amount in MB>
+.RS 4
+This command inflates or deflates the virtio balloon located in the
+specified instance.
+\-\-inflate increases the size of the balloon, thus \fIdecreasing\fR the
+amount of virtual RAM available for the guest. \-\-deflate returns previously
+inflated memory back to the guest.
+.sp
+.B \-n, \-\-name <guest name>
+.RS 4
+Ballon the specified instance. For a list of all instances, see \fI"lkvm list"\fR.
+.RE
+.PP
+.B \-i, \-\-inflate <n>
+.RS 4
+Inflates the ballon by the specified number of Megabytes. This decreases the
+amount of usable memory in the guest.
+.RE
+.PP
+.B \-d, \-\-deflate <n>
+.RS 4
+Deflates the ballon by the specified number of Megabytes. This increases the
+amount of usable memory in the guest.
+.RE
+.RE
+.PP
+.B stop --all|--name <name>
+.RS 4
+Stop a running instance.
+.sp
+.B \-a, \-\-all
+.RS 4
+Stop all running instances.
+.RE
+.sp
+.B \-n, \-\-name <name>
+.RS 4
+Stop the specified instance. For a list of running instances, see \fI lkvm list\fR.
+.RE
+.RE
+.PP
+.B stat \-\-all|\-\-name <name> [\-m]
+.RS 4
+Print statistics about a running instance.
+.sp
+.B \-m, \-\-memory
+.RS 4
+Display memory statistics.
+.RE
+.RE
+.PP
+.B sandbox (\fIlkvm run arguments\fR) \-\- [sandboxed command]
+.RS 4
+Run a command in a sandboxed guest. Kvmtool will inject a special init
+binary which will do an initial setup of the guest Linux and then
+lauch a shell script with the specified command. Upon this command ending,
+the guest will be shutdown.
+.RE
+.SH EXAMPLES
+.RS 4
+\fB$\fR lkvm run -k bzImage
+.RE
+.SH SEE ALSO
+qemu(1), kvm(4)
+.SH BUGS
+.SH AUTHOR
+Andre Przywara <andre.przywara@arm.com>
--
2.5.1
^ permalink raw reply related [flat|nested] 4+ messages in thread
* [PATCH 2/2] Documentation: remove documentation stubs and common-cmds.h generation
2015-12-22 14:00 [PATCH 0/2] kvmtool: replace documentations stubs with manpage Andre Przywara
2015-12-22 14:00 ` [PATCH 1/2] Add a rudimentary manpage Andre Przywara
@ 2015-12-22 14:00 ` Andre Przywara
1 sibling, 0 replies; 4+ messages in thread
From: Andre Przywara @ 2015-12-22 14:00 UTC (permalink / raw)
To: will.deacon; +Cc: dimitri.j.ledkov, sasha.levin, penberg, kvmarm, kvm
Now that we have a manpage in place, we can get rid of the manpage
style text files in the Documentation directory.
This allows us also to get rid of the crude common-cmds.h generation,
which relied on these files and on a command-list.txt file.
Instead include the version of that header file generated with the
current HEAD into the source tree.
Signed-off-by: Andre Przywara <andre.przywara@arm.com>
---
.gitignore | 1 -
Documentation/kvm-balloon.txt | 24 -----------------
Documentation/kvm-debug.txt | 16 -----------
Documentation/kvm-list.txt | 16 -----------
Documentation/kvm-pause.txt | 16 -----------
Documentation/kvm-resume.txt | 16 -----------
Documentation/kvm-run.txt | 62 -------------------------------------------
Documentation/kvm-sandbox.txt | 16 -----------
Documentation/kvm-setup.txt | 15 -----------
Documentation/kvm-stat.txt | 19 -------------
Documentation/kvm-stop.txt | 16 -----------
Documentation/kvm-version.txt | 21 ---------------
Makefile | 10 -------
command-list.txt | 15 -----------
include/common-cmds.h | 19 +++++++++++++
15 files changed, 19 insertions(+), 263 deletions(-)
delete mode 100644 Documentation/kvm-balloon.txt
delete mode 100644 Documentation/kvm-debug.txt
delete mode 100644 Documentation/kvm-list.txt
delete mode 100644 Documentation/kvm-pause.txt
delete mode 100644 Documentation/kvm-resume.txt
delete mode 100644 Documentation/kvm-run.txt
delete mode 100644 Documentation/kvm-sandbox.txt
delete mode 100644 Documentation/kvm-setup.txt
delete mode 100644 Documentation/kvm-stat.txt
delete mode 100644 Documentation/kvm-stop.txt
delete mode 100644 Documentation/kvm-version.txt
delete mode 100644 command-list.txt
create mode 100644 include/common-cmds.h
diff --git a/.gitignore b/.gitignore
index a16a97f..f21a0bd 100644
--- a/.gitignore
+++ b/.gitignore
@@ -6,7 +6,6 @@
*.swp
.cscope
tags
-include/common-cmds.h
tests/boot/boot_test.iso
tests/boot/rootfs/
guest/init
diff --git a/Documentation/kvm-balloon.txt b/Documentation/kvm-balloon.txt
deleted file mode 100644
index efc0a87..0000000
--- a/Documentation/kvm-balloon.txt
+++ /dev/null
@@ -1,24 +0,0 @@
-lkvm-balloon(1)
-================
-
-NAME
-----
-lkvm-balloon - Inflate or deflate the virtio balloon
-
-SYNOPSIS
---------
-[verse]
-'lkvm balloon [command] [size] [instance]'
-
-DESCRIPTION
------------
-The command inflates or deflates the virtio balloon located in the
-specified instance.
-For a list of running instances see 'lkvm list'.
-
-Command can be either 'inflate' or 'deflate'. Inflate increases the
-size of the balloon, thus decreasing the amount of virtual RAM available
-for the guest. Deflation returns previously inflated memory back to the
-guest.
-
-size is specified in Mb.
diff --git a/Documentation/kvm-debug.txt b/Documentation/kvm-debug.txt
deleted file mode 100644
index a8eb2c0..0000000
--- a/Documentation/kvm-debug.txt
+++ /dev/null
@@ -1,16 +0,0 @@
-lkvm-debug(1)
-================
-
-NAME
-----
-lkvm-debug - Print debug information from a running instance
-
-SYNOPSIS
---------
-[verse]
-'lkvm debug [instance]'
-
-DESCRIPTION
------------
-The command prints debug information from a running instance.
-For a list of running instances see 'lkvm list'.
diff --git a/Documentation/kvm-list.txt b/Documentation/kvm-list.txt
deleted file mode 100644
index a245607..0000000
--- a/Documentation/kvm-list.txt
+++ /dev/null
@@ -1,16 +0,0 @@
-lkvm-list(1)
-================
-
-NAME
-----
-lkvm-list - Print a list of running instances on the host.
-
-SYNOPSIS
---------
-[verse]
-'lkvm list'
-
-DESCRIPTION
------------
-This command prints a list of running instances on the host which
-belong to the user who currently ran 'lkvm list'.
diff --git a/Documentation/kvm-pause.txt b/Documentation/kvm-pause.txt
deleted file mode 100644
index 1ea2a23..0000000
--- a/Documentation/kvm-pause.txt
+++ /dev/null
@@ -1,16 +0,0 @@
-lkvm-pause(1)
-================
-
-NAME
-----
-lkvm-pause - Pause the virtual machine
-
-SYNOPSIS
---------
-[verse]
-'lkvm pause [instance]'
-
-DESCRIPTION
------------
-The command pauses a virtual machine.
-For a list of running instances see 'lkvm list'.
diff --git a/Documentation/kvm-resume.txt b/Documentation/kvm-resume.txt
deleted file mode 100644
index a36c4df..0000000
--- a/Documentation/kvm-resume.txt
+++ /dev/null
@@ -1,16 +0,0 @@
-lkvm-resume(1)
-================
-
-NAME
-----
-lkvm-resume - Resume the virtual machine
-
-SYNOPSIS
---------
-[verse]
-'lkvm resume [instance]'
-
-DESCRIPTION
------------
-The command resumes a virtual machine.
-For a list of running instances see 'lkvm list'.
diff --git a/Documentation/kvm-run.txt b/Documentation/kvm-run.txt
deleted file mode 100644
index 8ddf470..0000000
--- a/Documentation/kvm-run.txt
+++ /dev/null
@@ -1,62 +0,0 @@
-lkvm-run(1)
-================
-
-NAME
-----
-lkvm-run - Start the virtual machine
-
-SYNOPSIS
---------
-[verse]
-'lkvm run' [-k <kernel image> | --kernel <kernel image>]
-
-DESCRIPTION
------------
-The command starts a virtual machine.
-
-OPTIONS
--------
--m::
---mem=::
- Virtual machine memory size in MiB.
-
--p::
---params::
- Additional kernel command line arguments.
-
--r::
---initrd=::
- Initial RAM disk image.
-
--k::
---kernel=::
- The virtual machine kernel.
-
---dev=::
- KVM device file.
-
--i::
---image=::
- A disk image file.
-
--s::
---single-step::
- Enable single stepping.
-
--g::
---ioport-debug::
- Enable ioport debugging.
-
--c::
---enable-virtio-console::
- Enable the virtual IO console.
-
---cpus::
- The number of virtual CPUs to run.
-
---debug::
- Enable debug messages.
-
-SEE ALSO
---------
-linkkvm:
diff --git a/Documentation/kvm-sandbox.txt b/Documentation/kvm-sandbox.txt
deleted file mode 100644
index 2d7f558..0000000
--- a/Documentation/kvm-sandbox.txt
+++ /dev/null
@@ -1,16 +0,0 @@
-lkvm-sandbox(1)
-================
-
-NAME
-----
-lkvm-sandbox - Run a command in a sandboxed guest
-
-SYNOPSIS
---------
-[verse]
-'lkvm sandbox ['lkvm run' arguments] -- [sandboxed command]'
-
-DESCRIPTION
------------
-The sandboxed command will run in a guest as part of it's init
-command.
diff --git a/Documentation/kvm-setup.txt b/Documentation/kvm-setup.txt
deleted file mode 100644
index 4b6e331..0000000
--- a/Documentation/kvm-setup.txt
+++ /dev/null
@@ -1,15 +0,0 @@
-lkvm-setup(1)
-================
-
-NAME
-----
-lkvm-setup - Setup a new virtual machine
-
-SYNOPSIS
---------
-[verse]
-'lkvm setup <name>'
-
-DESCRIPTION
------------
-The command setups a virtual machine.
diff --git a/Documentation/kvm-stat.txt b/Documentation/kvm-stat.txt
deleted file mode 100644
index 101ce7a..0000000
--- a/Documentation/kvm-stat.txt
+++ /dev/null
@@ -1,19 +0,0 @@
-lkvm-stat(1)
-================
-
-NAME
-----
-lkvm-stat - Print statistics about a running instance
-
-SYNOPSIS
---------
-[verse]
-'lkvm [command] [-n instance] [-p instance pid] [--all]'
-
-DESCRIPTION
------------
-The command prints statistics about a running instance.
-For a list of running instances see 'lkvm list'.
-
-Commands:
- --memory, -m Display memory statistics
diff --git a/Documentation/kvm-stop.txt b/Documentation/kvm-stop.txt
deleted file mode 100644
index 6e4bc83..0000000
--- a/Documentation/kvm-stop.txt
+++ /dev/null
@@ -1,16 +0,0 @@
-lkvm-stop(1)
-================
-
-NAME
-----
-lkvm-stop - Stop a running instance
-
-SYNOPSIS
---------
-[verse]
-'lkvm stop [instance]'
-
-DESCRIPTION
------------
-The command stops a running instance.
-For a list of running instances see 'lkvm list'.
diff --git a/Documentation/kvm-version.txt b/Documentation/kvm-version.txt
deleted file mode 100644
index 41003d2..0000000
--- a/Documentation/kvm-version.txt
+++ /dev/null
@@ -1,21 +0,0 @@
-lkvm-version(1)
-================
-
-NAME
-----
-lkvm-version - Print the version of the kernel tree kvm tools
-was built on.
-
-SYNOPSIS
---------
-[verse]
-'lkvm version'
-
-DESCRIPTION
------------
-The command prints the version of the kernel that was used to build
-kvm tools.
-
-Note that the version is not the version of the kernel which is currently
-running on the host, but is the version of the kernel tree from which kvm
-tools was built.
diff --git a/Makefile b/Makefile
index 59622c3..99ebbb2 100644
--- a/Makefile
+++ b/Makefile
@@ -399,9 +399,6 @@ $(GUEST_INIT): guest/init.c
%.s: %.c
$(Q) $(CC) -o $@ -S $(CFLAGS) -fverbose-asm $<
-# The header file common-cmds.h is needed for compilation of builtin-help.c.
-builtin-help.static.o builtin-help.o: $(KVM_INCLUDE)/common-cmds.h
-
$(OBJS):
util/rbtree.static.o util/rbtree.o: util/rbtree.c
@@ -429,12 +426,6 @@ endif
$(Q) $(CC) -c $(c_flags) $(CFLAGS_DYNOPT) $< -o $@
-$(KVM_INCLUDE)/common-cmds.h: util/generate-cmdlist.sh command-list.txt
-
-$(KVM_INCLUDE)/common-cmds.h: $(wildcard Documentation/kvm-*.txt)
- $(E) " GEN " $@
- $(Q) util/generate-cmdlist.sh > $@+ && mv $@+ $@
-
#
# BIOS assembly weirdness
#
@@ -496,7 +487,6 @@ clean:
$(Q) rm -f cscope.*
$(Q) rm -f tags
$(Q) rm -f TAGS
- $(Q) rm -f $(KVM_INCLUDE)/common-cmds.h
$(Q) rm -f KVMTOOLS-VERSION-FILE
.PHONY: clean
diff --git a/command-list.txt b/command-list.txt
deleted file mode 100644
index d93597d..0000000
--- a/command-list.txt
+++ /dev/null
@@ -1,15 +0,0 @@
-#
-# List of known perf commands.
-# command name category [deprecated] [common]
-#
-lkvm-run mainporcelain common
-lkvm-setup mainporcelain common
-lkvm-pause common
-lkvm-resume common
-lkvm-version common
-lkvm-list common
-lkvm-debug common
-lkvm-balloon common
-lkvm-stop common
-lkvm-stat common
-lkvm-sandbox common
diff --git a/include/common-cmds.h b/include/common-cmds.h
new file mode 100644
index 0000000..5b95676
--- /dev/null
+++ b/include/common-cmds.h
@@ -0,0 +1,19 @@
+struct cmdname_help
+{
+ char name[16];
+ char help[80];
+};
+
+static struct cmdname_help common_cmds[] = {
+ {"run", "Start the virtual machine"},
+ {"setup", "Setup a new virtual machine"},
+ {"pause", "Pause the virtual machine"},
+ {"resume", "Resume the virtual machine"},
+ {"version", "Print the version of the kernel tree kvm tools"},
+ {"list", "Print a list of running instances on the host."},
+ {"debug", "Print debug information from a running instance"},
+ {"balloon", "Inflate or deflate the virtio balloon"},
+ {"stop", "Stop a running instance"},
+ {"stat", "Print statistics about a running instance"},
+ {"sandbox", "Run a command in a sandboxed guest"},
+};
--
2.5.1
^ permalink raw reply related [flat|nested] 4+ messages in thread