vmx(1), vmx(3): update manpages

sys/man/1/vmx

@@ -39,7 +39,7 @@ kernel
 .I Vmx
 uses Intel VT-x through
 .IR vmx (3)
-to simulate a virtual PC, running the specified kernel (which must be Multiboot compliant).
+to simulate a virtual PC, running the specified kernel (see below for supported formats).
 .PP
 By default the virtual PC has 64 MB of memory.
 The amount of memory can be changed with the
@@ -60,15 +60,24 @@ argument.
 .PP
 If
 .B -v
-is specified, a graphics device is simulated.
-The argument to
-.B -v
-is either
-.IR text,
-which simulates a CGA text-mode console, or
-"\fIwidth\fLx\fIheight\fLx\fIchan\fL@\fIaddr\fR",
-which simulates a framebuffer at address \fIaddr\fR of the specified size and channel format \fIchan\fR (see
+is specified, a graphics device, PS/2 keyboard and mouse are simulated.
+Clicking on the screen "grabs" the mouse; pressing Ctrl and Alt simultaneously releases the grab.
+Valid values for the argument are
+.TP
+.B text
+Simulate a VGA text-mode console.
+.TP
+\fIwidth\fLx\fIheight\fR [ \fLx\fIchan\fR ] [ \fL@\fIaddr\fR ]
+Simulate a framebuffer at address \fIaddr\fR of the specified size and channel format \fIchan\fR (see
 .IR image (6)).
+\fLx\fIchan\fR and \fL@\fIaddr\fR are optional, in which case they default to \fLx8r8g8b8\fR and \fL0xf0000000\fR, respectively
+(in this mode there is no way to change the resolution and accesses to VGA registers have no effect).
+.TP
+\fLvesa:\fImodes\fR [ \fL@\fIaddr\fR ]
+(\fImodes\fR is a comma separated list of modes of the format \fIwidth\fLx\fIheight\fLx\fIchan\fR with the \fLchan\fR optional as before.)
+Simulate a VESA-compatible PCI graphics adapter, initially in text mode.
+The guest can use VESA functions to switch the mode to one of those listed, which are assigned consecutive mode numbers starting with \fL0x120\fR.
+The first mode is indicated as the preferred mode of the monitor.
 .PP
 The
 .B -c
@@ -87,6 +96,10 @@ The argument to
 specifies a physical network device (such as
 .BR ether0 )
 to use.
+Alternatively, a dial string such as \fLudp!\fIhost\fL!\fIport\fR can be used.
+It can also be prefixed by \fLfile!\fR to interpret the argument as a file instead and it can be prefixed by \fLhdr!\fR to enable headers matching the binary
+.IR snoopy (8)
+format.
 .PP
 A
 .B -d
@@ -94,6 +107,23 @@ option adds a
 .I virtio
 block device (a hard disk)
 with the argument as a disk image.
+.SS "Multiboot kernels"
+.PP
+If the specified kernel complies with the Multiboot specification, then \fIargs\fR is concatenated with spaces and passed as the \fIcmdline\fR; the \fL-m\fR modules are passed as boot modules.
+.PP
+Note that 9front is Multiboot compliant and interprets the first boot module as
+.IR plan9.ini (8).
+.SS "OpenBSD kernels"
+.PP
+If the specified kernel is an OpenBSD kernel, the boot modules are ignored and the \fIcmdline\fR is interpreted as
+.IP
+[ \fL-asdc\fR ] [ \fIvar\fL=\fIvalue\fR ... ]
+.PP
+where the options correspond to the \fLboot\fR options and the assignments to the boot variables, which are defined in the OpenBSD manpage \fIboot\fR(8).
+.SS "Linux kernels"
+.PP
+If the specified kernel is a Linux kernel (which must be 2.6.22 or newer and in \fLbzImage\fR format), \fIargs\fR are concatenated with spaces and passed as the \fIcmdline\fR (see \fLDocumentation/admin-guide/kernel-parameters.txt\fR).
+The first boot module is passed as the \fIinitrd\fR; any further boot modules are ignored.
 .SH SOURCE
 .B /sys/src/cmd/vmx
 .SH SEE ALSO
@@ -104,6 +134,8 @@ with the argument as a disk image.
 can and will crash your kernel.
 .PP
 Currently only one core and only one VM at a time is supported.
+.PP
+The Linux \fLvga=\fR option is not supported, as well as many of the OpenBSD boot variables.
 .SH HISTORY
 .I Vmx
 first appeared in 9front (June, 2017).

sys/man/3/vmx

@@ -37,10 +37,10 @@ No virtual CPU.
 The virtual CPU is being initialized.
 .TP
 \fLready\fR
-The virtual CPU is idle and waiting for commands from user space.
+The virtual CPU is idle.
 .TP
 \fLrunning\fR
-The virtual CPU is busy.
+The virtual CPU is executing code.
 .TP
 \fLdead\fR
 The virtual CPU suffered a fatal error.
@@ -83,6 +83,12 @@ file contains the registers of the virtual CPU in the format \fIname value\fR.
 Writes to the file (in the same format) write to the referenced registers (if possible).
 Multiple lines can be written at once but all lines written must be newline terminated.
 
+.PP
+Some registers (\fLCR0\fR and \fLCR4\fR) are split into three registers, suffixed \fLreal\fR, \fLfake\fR and \fLmask\fR.
+In this case, \fLreal\fR corresponds to the bits that affect actual CPU execution, \fLfake\fR corresponds to the bits read back by the guest and the bits set in \fLmask\fR are those "owned" by the host.
+The guest is free to modify the bits that it owns (in which case it always has the same value in both \fLreal\fR and \fLfake\fR), but attempting to change a host-owned bit from the status in \fLfake\fR causes a VM exit.
+Certain bits are owned by the kernel, which means they are fixed in both \fLmask\fR and \fLreal\fR.
+
 .PP
 Reading the
 .B wait
@@ -99,12 +105,16 @@ Some notable exit causes are (see kernel source code for a complete list)
 .TP
 \fL#\fR\fIexception\fR
 Exception of the specified type (e.g. \fL#gp\fR for general protection fault).
+Currently only debug exceptions are configured to cause VM exits.
 .TP
 \fLtriplef\fR
 Triple fault.
 .TP
 \fLeptfault\fR
-The virtual CPU attempted a memory access that does not match any entry in the \Lmap\fR file.
+The virtual CPU attempted a memory access that does not match any entry in the \fLmap\fR file.
+.TP
+\fLmovcr\fR
+Illegal access to a control register (see above).
 .IP "\fL.\fR\fIinstr\fR"
 The virtual CPU attempted to execute the instruction \fIinstr\fR.
 .TP
@@ -118,7 +128,7 @@ file contains the virtual CPU's floating point registers, in the same binary for
 .IR proc (3).
 
 .SS Control messages
-.TF "\fLexc\fR \fI[excep]\fR"
+.TF "\fLirq\fR [ \fIexcep\fR ]"
 .TP
 .B init
 Create a new virtual CPU.
@@ -126,22 +136,25 @@ Create a new virtual CPU.
 .B quit
 Destroy the current virtual CPU.
 .TP
-.BI go [regs]
+\fLgo\fR [ \fIregs\fR ]
 Launch the virtual CPU.
 \fIRegs\fR is an optional list of register changes in the format \fIname\fL=\fIvalue\fL;\fR that will be applied before launching.
 .TP
-\fLstep\fR [ \fL-map\fR \fIaddr segment offset\fR \fB]\fR
+.B stop
+Stop the virtual CPU.
+.TP
+\fLstep\fR [ \fL-map\fR \fIaddr segment offset\fR ]\fR
 Executes a single instruction with the virtual CPU.
 If the \fL-map\fR option is specified, a 4 KB page at address \fIaddr\fR will be temporarily (for the duration of the step) mapped to the spceified \fIsegment\fR and \fIoffset\fR.
 A step can fail, in which case a VM exit message is sent to
 .BR wait .
 .TP
-.BI exc excep
+\fLexc\fR \fIexcep\fR
 The exception \fIexcep\fR is triggered in the virtual CPU.
 \fIExcep\fR can either be a named exception (such as \fL#gp\fR, in lower case) or an exception number.
 A number may be preeded by \fL#\fR to mark it as an exception, otherwise it is delivered as an interrupt (but always disregarding whether interrupts are enabled).
 .TP
-.BI irq [excep]
+\fLirq\fR [ \fIexcep\fR ]
 An Interrupt is posted, i.e. the exception \fIexcep\fR will be triggered the next time interrupts are enabled in the virtual CPU, at which point a
 .B *ack
 message is sent to