Module Name: src
Committed By: maxv
Date: Fri Oct 25 09:09:24 UTC 2019
Modified Files:
src/lib/libnvmm: libnvmm.3
Log Message:
Update the libnvmm man page:
- Sync the naming with reality.
- Replace "relevant" by "desired" and "virtualizer" by "emulator", closer
to what I meant.
- Add a "VCPU Configuration" section.
- Add a "Machine Ownership" section.
To generate a diff of this commit:
cvs rdiff -u -r1.19 -r1.20 src/lib/libnvmm/libnvmm.3
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/lib/libnvmm/libnvmm.3
diff -u src/lib/libnvmm/libnvmm.3:1.19 src/lib/libnvmm/libnvmm.3:1.20
--- src/lib/libnvmm/libnvmm.3:1.19 Sat Jun 8 07:27:44 2019
+++ src/lib/libnvmm/libnvmm.3 Fri Oct 25 09:09:24 2019
@@ -1,4 +1,4 @@
-.\" $NetBSD: libnvmm.3,v 1.19 2019/06/08 07:27:44 maxv Exp $
+.\" $NetBSD: libnvmm.3,v 1.20 2019/10/25 09:09:24 maxv Exp $
.\"
.\" Copyright (c) 2018, 2019 The NetBSD Foundation, Inc.
.\" All rights reserved.
@@ -27,7 +27,7 @@
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
-.Dd May 30, 2019
+.Dd October 25, 2019
.Dt LIBNVMM 3
.Os
.Sh NAME
@@ -52,6 +52,9 @@
.Ft int
.Fn nvmm_vcpu_destroy "struct nvmm_machine *mach" "struct nvmm_vcpu *vcpu"
.Ft int
+.Fn nvmm_vcpu_configure "struct nvmm_machine *mach" "struct nvmm_vcpu *vcpu" \
+ "uint64_t op" "void *conf"
+.Ft int
.Fn nvmm_vcpu_getstate "struct nvmm_machine *mach" "struct nvmm_vcpu *vcpu" \
"uint64_t flags"
.Ft int
@@ -133,6 +136,16 @@ destroys the virtual CPU identified by
in the machine
.Fa mach .
.Pp
+.Fn nvmm_vcpu_configure
+configures, on the VCPU
+.Fa vcpu
+of machine
+.Fa mach ,
+the parameter indicated in
+.Fa op .
+.Fa conf
+describes the value of the parameter.
+.Pp
.Fn nvmm_vcpu_getstate
gets the state of the virtual CPU identified by
.Fa vcpu
@@ -287,12 +300,28 @@ For example, the
field indicates the maximum number of virtual machines supported, while
.Cd max_vcpus
indicates the maximum number of VCPUs supported per virtual machine.
+.Ss Machine Ownership
+When a process creates a virtual machine via
+.Fn nvmm_machine_create ,
+it is considered the owner of this machine.
+No other processes than the owner can operate a virtual machine.
+.Pp
+When an owner exits, all the virtual machines associated with it are destroyed,
+if they were not already destroyed by the owner itself via
+.Fn nvmm_machine_destroy .
+.Pp
+Virtual machines are not inherited across
+.Xr fork 9
+operations.
.Ss Machine Configuration
Emulator software can configure several parameters of a virtual machine by using
-.Fn nvmm_machine_configure ,
-which can take the following operations:
+.Fn nvmm_machine_configure .
+Currently, no parameters are implemented.
+.Ss VCPU Configuration
+Emulator software can configure several parameters of a VCPU by using
+.Fn nvmm_vcpu_configure , which can take the following operations:
.Bd -literal
-#define NVMM_MACH_CONF_CALLBACKS 0
+#define NVMM_VCPU_CONF_CALLBACKS 0
...
.Ed
.Pp
@@ -386,8 +415,8 @@ A VCPU is described by a public structur
struct nvmm_vcpu {
nvmm_cpuid_t cpuid;
struct nvmm_vcpu_state *state;
- struct nvmm_event *event;
- struct nvmm_exit *exit;
+ struct nvmm_vcpu_event *event;
+ struct nvmm_vcpu_exit *exit;
};
.Ed
.Pp
@@ -399,11 +428,11 @@ they are initialized to special values b
.Pp
A call to
.Fn nvmm_vcpu_getstate
-will fetch the relevant parts of the VCPU state and put them in
+will fetch the desired parts of the VCPU state and put them in
.Fa vcpu->state .
A call to
.Fn nvmm_vcpu_setstate
-will install in the VCPU the relevant parts of
+will install in the VCPU the desired parts of
.Fa vcpu->state .
A call to
.Fn nvmm_vcpu_inject
@@ -421,22 +450,28 @@ Emulator software should not modify the
different threads.
.Ss Exit Reasons
The
-.Cd nvmm_exit
+.Cd nvmm_vcpu_exit
structure is used to handle VM exits:
.Bd -literal
-/* Exit Reasons */
-#define NVMM_EXIT_NONE 0x0000000000000000ULL
-#define NVMM_EXIT_MEMORY 0x0000000000000001ULL
-#define NVMM_EXIT_IO 0x0000000000000002ULL
-#define NVMM_EXIT_MSR 0x0000000000000003ULL
-#define NVMM_EXIT_INT_READY 0x0000000000000004ULL
-#define NVMM_EXIT_NMI_READY 0x0000000000000005ULL
-#define NVMM_EXIT_HALTED 0x0000000000000006ULL
-#define NVMM_EXIT_SHUTDOWN 0x0000000000000007ULL
- ...
-#define NVMM_EXIT_INVALID 0xFFFFFFFFFFFFFFFFULL
+/* Generic. */
+#define NVMM_VCPU_EXIT_NONE 0x0000000000000000ULL
+#define NVMM_VCPU_EXIT_INVALID 0xFFFFFFFFFFFFFFFFULL
+/* x86: operations. */
+#define NVMM_VCPU_EXIT_MEMORY 0x0000000000000001ULL
+#define NVMM_VCPU_EXIT_IO 0x0000000000000002ULL
+/* x86: changes in VCPU state. */
+#define NVMM_VCPU_EXIT_SHUTDOWN 0x0000000000001000ULL
+#define NVMM_VCPU_EXIT_INT_READY 0x0000000000001001ULL
+#define NVMM_VCPU_EXIT_NMI_READY 0x0000000000001002ULL
+#define NVMM_VCPU_EXIT_HALTED 0x0000000000001003ULL
+/* x86: instructions. */
+#define NVMM_VCPU_EXIT_RDMSR 0x0000000000002000ULL
+#define NVMM_VCPU_EXIT_WRMSR 0x0000000000002001ULL
+#define NVMM_VCPU_EXIT_MONITOR 0x0000000000002002ULL
+#define NVMM_VCPU_EXIT_MWAIT 0x0000000000002003ULL
+#define NVMM_VCPU_EXIT_CPUID 0x0000000000002004ULL
-struct nvmm_exit {
+struct nvmm_vcpu_exit {
uint64_t reason;
union {
...
@@ -457,7 +492,7 @@ to retrieve certain state values.
It is possible that a VM exit was caused by a reason internal to the host
kernel, and that emulator software should not be concerned with.
In this case, the exit reason is set to
-.Cd NVMM_EXIT_NONE .
+.Cd NVMM_VCPU_EXIT_NONE .
This gives a chance for emulator software to halt the VM in its tracks.
.Pp
Refer to functional examples to see precisely how to handle VM exits.
@@ -466,18 +501,16 @@ It is possible to inject an event into a
An event can be a hardware interrupt, a software interrupt, or a software
exception, defined by:
.Bd -literal
-enum nvmm_event_type {
- NVMM_EVENT_INTERRUPT_HW,
- NVMM_EVENT_INTERRUPT_SW,
- NVMM_EVENT_EXCEPTION
-};
+#define NVMM_VCPU_EVENT_EXCP 0
+#define NVMM_VCPU_EVENT_INTR 1
-struct nvmm_event {
- enum nvmm_event_type type;
- uint64_t vector;
+struct nvmm_vcpu_event {
+ u_int type;
+ uint8_t vector;
union {
- uint64_t error;
- uint64_t prio;
+ struct {
+ uint64_t error;
+ } excp;
} u;
};
.Ed
@@ -488,8 +521,6 @@ to be sent to vector number
.Va vector ,
with a possible additional
.Va error
-or
-.Va prio
code that is implementation-specific.
.Pp
It is possible that the VCPU is in a state where it cannot receive this
@@ -508,19 +539,19 @@ Emulator software can manage interrupt a
.Va intr
component of the VCPU state.
When such window-exiting is enabled, NVMM will cause a VM exit with reason
-.Cd NVMM_EXIT_INT_READY
+.Cd NVMM_VCPU_EXIT_INT_READY
or
-.Cd NVMM_EXIT_NMI_READY
+.Cd NVMM_VCPU_EXIT_NMI_READY
to indicate that the guest is now able to handle the corresponding class
of interrupts.
.Ss Assist Callbacks
In order to assist emulation of certain operations,
.Nm
requires emulator software to register, via
-.Fn nvmm_machine_configure ,
+.Fn nvmm_vcpu_configure ,
a set of callbacks described in the following structure:
.Bd -literal
-struct nvmm_callbacks {
+struct nvmm_assist_callbacks {
void (*io)(struct nvmm_io *);
void (*mem)(struct nvmm_mem *);
};
@@ -538,7 +569,7 @@ Emulator software that does not intend t
in the callbacks.
.Ss I/O Assist
When a VM exit occurs with reason
-.Cd NVMM_EXIT_IO ,
+.Cd NVMM_VCPU_EXIT_IO ,
it is necessary for emulator software to emulate the associated I/O operation.
.Nm
provides an easy way for emulator software to perform that.
@@ -552,6 +583,8 @@ structure as argument.
This structure describes an I/O transaction:
.Bd -literal
struct nvmm_io {
+ struct nvmm_machine *mach;
+ struct nvmm_vcpu *vcpu;
uint64_t port;
bool in;
size_t size;
@@ -584,7 +617,7 @@ will indicate if the operation is an inp
will indicate the size of the access.
.Ss Mem Assist
When a VM exit occurs with reason
-.Cd NVMM_EXIT_MEMORY ,
+.Cd NVMM_VCPU_EXIT_MEMORY ,
it is necessary for emulator software to emulate the associated memory
operation.
.Nm
@@ -600,6 +633,8 @@ structure as argument.
This structure describes a Mem transaction:
.Bd -literal
struct nvmm_mem {
+ struct nvmm_machine *mach;
+ struct nvmm_vcpu *vcpu;
gpaddr_t gpa;
bool write;
size_t size;
@@ -640,9 +675,9 @@ is set to indicate the error.
.Bl -tag -width XXXX -compact
.It Lk https://www.netbsd.org/~maxv/nvmm/nvmm-demo.zip
Functional example (demonstrator).
-Contains a virtualizer that uses the
+Contains an emulator that uses the
.Nm
-API, and a small kernel that exercises this virtualizer.
+API, and a small kernel that exercises this emulator.
.It Pa src/sys/dev/nvmm/
Source code of the kernel NVMM driver.
.It Pa src/lib/libnvmm/
