add vmx documentation
This commit is contained in:
aiju
parent
d5e55f5140
commit
3b123799ab
3 changed files with 290 additions and 1 deletions
109
sys/man/1/vmx
Normal file
109
sys/man/1/vmx
Normal file
|
|
@ -0,0 +1,109 @@
|
|||
.TH VMX 1
|
||||
.SH NAME
|
||||
vmx \- virtual PC
|
||||
.SH SYNOPSIS
|
||||
.B vmx
|
||||
[
|
||||
.B -M
|
||||
.I mem
|
||||
]
|
||||
[
|
||||
.B -c
|
||||
.I com1
|
||||
]
|
||||
[
|
||||
.B -C
|
||||
.I com2
|
||||
]
|
||||
[
|
||||
.B -n
|
||||
.I nic
|
||||
]
|
||||
[
|
||||
.B -d
|
||||
.I blockfile
|
||||
]
|
||||
[
|
||||
.B -v
|
||||
.I vga
|
||||
]
|
||||
[
|
||||
.B -m
|
||||
.I bootmod
|
||||
]
|
||||
kernel
|
||||
[
|
||||
.I args ...
|
||||
]
|
||||
.SH DESCRIPTION
|
||||
.I Vmx
|
||||
uses Intel VT-x through
|
||||
.IR vmx (3)
|
||||
to simulate a virtual PC, running the specified kernel (which must be Multiboot compliant).
|
||||
.PP
|
||||
By default the virtual PC has 64 MB of memory.
|
||||
The amount of memory can be changed with the
|
||||
.B -M
|
||||
option,
|
||||
the argument of which is interpreted in bytes unless suffixed by
|
||||
.BR K ,
|
||||
.BR M ,
|
||||
or
|
||||
.B G
|
||||
to change the unit to kilobytes, megabytes or gigabytes, respectively.
|
||||
.PP
|
||||
.I Args
|
||||
is passed to the kernel as its command line.
|
||||
Boot modules can be specified with the
|
||||
.B -m
|
||||
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
|
||||
.IR image (6)).
|
||||
.PP
|
||||
The
|
||||
.B -c
|
||||
and
|
||||
.B -C
|
||||
options specify the targets for the COM1 and COM2 devices.
|
||||
The argument consists of two fields separated by a comma, which specify the file to be used for input and output, respectively.
|
||||
Either field can be left empty.
|
||||
If there is no comma in the argument, the same value is used for both fields.
|
||||
.PP
|
||||
A
|
||||
.B -n
|
||||
option adds a network card.
|
||||
The argument to
|
||||
.B -n
|
||||
specifies a physical network device (such as
|
||||
.BR ether0 )
|
||||
to use.
|
||||
.PP
|
||||
A
|
||||
.B -d
|
||||
option adds a
|
||||
.I virtio
|
||||
block device (a hard disk)
|
||||
with the argument as a disk image.
|
||||
.SH SOURCE
|
||||
.B /sys/src/cmd/vmx
|
||||
.SH SEE ALSO
|
||||
.IR vmx (3),
|
||||
.IR cpuid (8)
|
||||
.SH BUGS
|
||||
.I Vmx
|
||||
can and will crash your kernel.
|
||||
.PP
|
||||
Currently only one core and only one VM at a time is supported.
|
||||
.SH HISTORY
|
||||
.I Vmx
|
||||
first appeared in 9front (June, 2017).
|
||||
168
sys/man/3/vmx
Normal file
168
sys/man/3/vmx
Normal file
|
|
@ -0,0 +1,168 @@
|
|||
.TH VMX 3
|
||||
.SH NAME
|
||||
vmx \- x86 virtualization interface
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
.B #X/ctl
|
||||
.B #X/fpregs
|
||||
.B #X/map
|
||||
.B #X/regs
|
||||
.B #X/status
|
||||
.B #X/wait
|
||||
.fi
|
||||
.SH DESCRIPTION
|
||||
The
|
||||
.I vmx
|
||||
device supports "virtual CPUs" using the Intel VT-x extension (a.k.a. VMX instruction set).
|
||||
This is used by
|
||||
.IR vmx (3)
|
||||
to implement virtual machines.
|
||||
Access to the
|
||||
.I vmx
|
||||
device is restricted to the hostowner.
|
||||
.PP
|
||||
The
|
||||
.B ctl
|
||||
file provides the main control interface.
|
||||
See below for a list of commands.
|
||||
The
|
||||
.B status
|
||||
file contains the current status of the virtual CPU, which is one of
|
||||
.TF \fLinactive\fR
|
||||
.TP
|
||||
\fLinactive\fR
|
||||
No virtual CPU.
|
||||
.TP
|
||||
\fLinit\fR
|
||||
The virtual CPU is being initialized.
|
||||
.TP
|
||||
\fLready\fR
|
||||
The virtual CPU is idle and waiting for commands from user space.
|
||||
.TP
|
||||
\fLrunning\fR
|
||||
The virtual CPU is busy.
|
||||
.TP
|
||||
\fLdead\fR
|
||||
The virtual CPU suffered a fatal error.
|
||||
This state may be followed by an error message.
|
||||
.TP
|
||||
\fLending\fR
|
||||
The virtual CPU is shutting down.
|
||||
|
||||
.LP
|
||||
The
|
||||
.B map
|
||||
file contains the memory map that the virtual CPU will see.
|
||||
It consists of lines of the form
|
||||
.IP
|
||||
\fIaccess\fR \fIcache\fR \fIlowaddr\fR \fIhighaddr\fR \fIsegment\fR \fIoffset\fR
|
||||
.LP
|
||||
\fILowaddr\fR specifies the lowest address in the region and \fIhighaddr\fR one past the highest address.
|
||||
The region is mapped to a region of the same size in the global segment \fIsegment\fR (see
|
||||
.IR segment (3)),
|
||||
starting at \fIoffset\fR.
|
||||
The \fIaccess\fR field specifies the permitted types of access using the characters \fLr\fR (read), \fLw\fR (write), \fLx\fR (execute) and \fL-\fR (padding character).
|
||||
The \fIcache\fR field specifies the cacheability of the region, it must be one of \fLuc\fR, \fLwc\fR, \fLwt\fR, \fLwp\fR and \fLwb\fR (as defined in the Intel SDM).
|
||||
|
||||
.PP
|
||||
Writes to the
|
||||
.B map
|
||||
file append lines to the end.
|
||||
Multiple lines can be written at once but all lines written must be newline terminated.
|
||||
Regions can be overlapping, in which case later definitions always override earlier ones.
|
||||
The map can be cleared by opening the file with
|
||||
.B OTRUNC
|
||||
(see
|
||||
.IB open
|
||||
(2)).
|
||||
|
||||
.PP
|
||||
The
|
||||
.B regs
|
||||
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
|
||||
Reading the
|
||||
.B wait
|
||||
file will stall the reading process until the virtual CPU reaches a point where it cannot continue (a "VM exit").
|
||||
This may be due to the an access to hardware or a software exception.
|
||||
Each exit is indicated by a single line in a format compatible with
|
||||
.IR tokenize (2).
|
||||
The first column contains the cause of the exit and the second column contains the "exit qualification" field that may contain more details on the exit (see Intel SDM).
|
||||
The remaining columns come in pairs and contain further info and the values of relevant registers.
|
||||
|
||||
.LP
|
||||
Some notable exit causes are (see kernel source code for a complete list)
|
||||
.TF ".\fL#\fR\fIexception\fR"
|
||||
.TP
|
||||
\fL#\fR\fIexception\fR
|
||||
Exception of the specified type (e.g. \fL#gp\fR for general protection fault).
|
||||
.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.
|
||||
.IP "\fL.\fR\fIinstr\fR"
|
||||
The virtual CPU attempted to execute the instruction \fIinstr\fR.
|
||||
.TP
|
||||
\fL*ack\fR
|
||||
Not an actual exit, but acknowledgement that an interrupt request (IRQ) was posted.
|
||||
|
||||
.PP
|
||||
The
|
||||
.B fpregs
|
||||
file contains the virtual CPU's floating point registers, in the same binary format used by
|
||||
.IR proc (3).
|
||||
|
||||
.SS Control messages
|
||||
.TF "\fLexc\fR \fI[excep]\fR"
|
||||
.TP
|
||||
.B init
|
||||
Create a new virtual CPU.
|
||||
.TP
|
||||
.B quit
|
||||
Destroy the current virtual CPU.
|
||||
.TP
|
||||
.BI go [regs]
|
||||
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
|
||||
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
|
||||
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]
|
||||
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
|
||||
.BR wait.
|
||||
.IExcep\fR uses the same format as the argument of \fBexc\fR.
|
||||
.B Irq
|
||||
cancels any interrupts that have been previously posted but not yet delivered and it can be called with no argument to cancel an interrupt.
|
||||
.SH SOURCE
|
||||
.B /sys/src/9/pc/devvmx.c
|
||||
.SH "SEE ALSO"
|
||||
.IR vmx (1),
|
||||
.IR cpuid (8)
|
||||
|
||||
Intel 64 and IA-32 Architectures Software Developer's Manual, Volume 3B, Chapters 23-33.
|
||||
.SH BUGS
|
||||
Currently only one virtual CPU is supported and it is tied to the bootstrap processor.
|
||||
.PP
|
||||
The interface will almost certainly change in the future.
|
||||
.PP
|
||||
.I Devvmx
|
||||
can and will crash your kernel.
|
||||
.SH HISTORY
|
||||
.I Devvmx
|
||||
first appeared in 9front (June, 2017).
|
||||
|
|
@ -1,11 +1,16 @@
|
|||
.TH CPUID 8
|
||||
.SH NAME
|
||||
cpuid \- print processor information
|
||||
cpuid, icanhasvmx \- print processor information
|
||||
.SH SYNOPSIS
|
||||
.B aux/cpuid
|
||||
[
|
||||
.B -ar
|
||||
]
|
||||
|
||||
.B aux/icanhasvmx
|
||||
[
|
||||
.B -r
|
||||
]
|
||||
.SH DESCRIPTION
|
||||
Intel and compatible processors since the
|
||||
.SM Pentium™
|
||||
|
|
@ -52,6 +57,13 @@ Processor name string
|
|||
.TP
|
||||
.B physbits, virtbits, guestbits
|
||||
Address lines, decimal in bits
|
||||
.PP
|
||||
.I Icanhasvmx
|
||||
queries the virtual machine extension (VMX) capabilities.
|
||||
If
|
||||
.B -r
|
||||
is specified, it prints the results in raw hexadecimal; otherwise it produces a human-readable format.
|
||||
In any case it prints a summary on fd 2.
|
||||
.SH EXAMPLE
|
||||
.EX
|
||||
term% aux/cpuid
|
||||
|
|
|
|||
Loading…
Reference in a new issue