Re: vmm.4: document supported ioctls
On Fri, Apr 02, 2021 at 03:24:55AM +0200, Klemens Nanni wrote: > On Thu, Apr 01, 2021 at 08:34:37PM -0400, Dave Voutila wrote: > > I've updated the diff using your feedback. See below. > Thanks, OK kn > ok mlarkin@ also
Re: vmm.4: document supported ioctls
On Thu, Apr 01, 2021 at 08:34:37PM -0400, Dave Voutila wrote: > I've updated the diff using your feedback. See below. Thanks, OK kn
Re: vmm.4: document supported ioctls
Klemens Nanni writes: > On Thu, Apr 01, 2021 at 06:49:07AM -0400, Dave Voutila wrote: >> This diff documents the ioctl(2) values supported by vmm(4). Besides >> vmd(8) there's at least one application I've seen (Solo5) directly using >> vmm(4). >> >> For now I've tried to have short summary-level details, enough to >> provide a general idea of purpose. The data structures aren't included >> in the doc, but the mention of at least points to >> where they're defined for now. > That seems fair. > >> Feedback on my mdoc macro usage or verbiage? OK? > See inline, but you can also use `mandoc -T lint ./vmm.4' and any > warnings and errors. > Very cool, did not know that. I've updated the diff using your feedback. See below. >> Index: share/man/man4/man4.amd64/vmm.4 >> === >> RCS file: /cvs/src/share/man/man4/man4.amd64/vmm.4,v >> retrieving revision 1.5 >> diff -u -p -r1.5 vmm.4 >> --- share/man/man4/man4.amd64/vmm.4 6 Dec 2015 19:06:17 - 1.5 >> +++ share/man/man4/man4.amd64/vmm.4 1 Apr 2021 10:36:50 - >> @@ -22,6 +22,8 @@ >> .Nd virtual machine monitor >> .Sh SYNOPSIS >> .Cd "vmm0at mainbus0" >> +.Pp >> +.In machine/vmmvar.h >> .Sh DESCRIPTION >> The >> .Nm >> @@ -67,6 +69,45 @@ driver requires at least one CPU with ha >> capabilities and nested or extended paging capabilities to be >> present on the host. >> For more information, consult the CPU vendor's documentation. >> +.Pp >> +The following >> +.Xr ioctl 2 >> +commands are provided for managing >> +.Nm >> +guests: >> +.Pp >> +.Bl -tag -width Ds -offset indent >> +.It Dv VMM_IOC_CREATE Fa "struct vm_create_params *" >> +Create a VM, initializing >> +.Xr vmm 4 > That's the page itself, just use .Nm here like you did in the last > sentence. > >> +if not yet started. (Does not start the VCPU.) >> +.It Dv VMM_IOC_RUN Fa "struct vm_run_params *" >> +Run a VCPU for a defined VM. Returns on VM-exit, the VCPU stopped, or > I'd use imperative mood, i.e. omit "s"^ and add^ "when", I guess. > Good idea. It reads better like that. >> +an error occurred > New sentences go to new lines. Got it. > >> +.It Dv VMM_IOC_INFO Fa "struct vm_info_params *" >> +Get information about the VMs currently hosted by >> +.Xr vmm 4 > This and all following sentences lack punctuation; with .Nm as per > above that'd be ".Nm ." (mind the space between macro and dot if the > line ends with a macro). > >> +.It Dv VMM_IOC_TERM Fa "struct vm_terminate_params *" >> +Terminate a given VM >> +.It Dv VMM_IOC_RESETCPU Fa "struct vm_resetcpu_params *" >> +Reset a VCPU to power-on-init state using the provided register state >> +.It Dv VMM_IOC_INTR Fa "struct vm_intr_params *" >> +Signal a pending interrupt for a VCPU >> +.It Dv VMM_IOC_READREGS Fa "struct vm_rwregs_params *" >> +Read registers of a VCPU >> +.It Dv VMM_IOC_WRITEREGS Fa "struct vm_rwregs_params *" >> +Write registers values of a VCPU >> +.It Dv VMM_IOC_READVMPARAMS Fa "struct vm_revmparams_params *" >> +Read paravirtualized hardware parameters (such as >> +.Xr pvclock 4 >> +version) for a VM >> +.It Dv VMM_IOC_WRITEVMPARAMS Fa "struct vm_rwvmparams_params *" >> +Write paravirtualized hardware parameters (such as >> +.Xr pvclock 4 >> +guest physical addresss) for a VM >> +.It Dv VMM_IOC_MPROTECT_EPT Fa "struct vm_mprotect_ept_params *" >> +Set access protections on guest page table entries >> +(only supported on hosts providing EPT or RVI) > Missing .El here. Done. > >> .Sh SEE ALSO >> .Xr cpu 4 , >> .Xr intro 4 , >> OK? -dv Index: share/man/man4/man4.amd64/vmm.4 === RCS file: /cvs/src/share/man/man4/man4.amd64/vmm.4,v retrieving revision 1.5 diff -u -p -r1.5 vmm.4 --- share/man/man4/man4.amd64/vmm.4 6 Dec 2015 19:06:17 - 1.5 +++ share/man/man4/man4.amd64/vmm.4 2 Apr 2021 00:28:26 - @@ -22,6 +22,8 @@ .Nd virtual machine monitor .Sh SYNOPSIS .Cd "vmm0at mainbus0" +.Pp +.In machine/vmmvar.h .Sh DESCRIPTION The .Nm @@ -67,6 +69,45 @@ driver requires at least one CPU with ha capabilities and nested or extended paging capabilities to be present on the host. For more information, consult the CPU vendor's documentation. +.Pp +The following +.Xr ioctl 2 +commands are provided for managing +.Nm +guests: +.Bl -tag -width Ds -offset indent +.It Dv VMM_IOC_CREATE Fa "struct vm_create_params *" +Create a VM, initializing +.Nm +if not yet started. (Does not start the VCPU.) +.It Dv VMM_IOC_RUN Fa "struct vm_run_params *" +Run a VCPU for a defined VM. +Return on VM-exit, when the VCPU stopped, or an error occurred +.It Dv VMM_IOC_INFO Fa "struct vm_info_params *" +Get information about the VMs currently hosted by +.Nm . +.It Dv VMM_IOC_TERM Fa "struct vm_terminate_params *" +Terminate a given VM. +.It Dv VMM_IOC_RESETCPU Fa "struct vm_resetcpu_params *" +Reset a VCPU to power-on-init state using the provided register state. +.It Dv VMM_IOC
Re: vmm.4: document supported ioctls
Thanks Dave, I like the description and listing the ioctl, and referencing vmmvar.h is a good idea Cheers Adam On Thu, Apr 1, 2021 at 18:49, Dave Voutila wrote: > This diff documents the ioctl(2) values supported by vmm(4). Besides > vmd(8) there's at least one application I've seen (Solo5) directly using > vmm(4). > > For now I've tried to have short summary-level details, enough to > provide a general idea of purpose. The data structures aren't included > in the doc, but the mention of at least points to > where they're defined for now. > > Feedback on my mdoc macro usage or verbiage? OK? > > -dv > > Index: share/man/man4/man4.amd64/vmm.4 > === > RCS file: /cvs/src/share/man/man4/man4.amd64/vmm.4,v > retrieving revision 1.5 > diff -u -p -r1.5 vmm.4 > --- share/man/man4/man4.amd64/vmm.4 6 Dec 2015 19:06:17 - 1.5 > +++ share/man/man4/man4.amd64/vmm.4 1 Apr 2021 10:36:50 - > @@ -22,6 +22,8 @@ > .Nd virtual machine monitor > .Sh SYNOPSIS > .Cd "vmm0 at mainbus0" > +.Pp > +.In machine/vmmvar.h > .Sh DESCRIPTION > The > .Nm > @@ -67,6 +69,45 @@ driver requires at least one CPU with ha > capabilities and nested or extended paging capabilities to be > present on the host. > For more information, consult the CPU vendor's documentation. > +.Pp > +The following > +.Xr ioctl 2 > +commands are provided for managing > +.Nm > +guests: > +.Pp > +.Bl -tag -width Ds -offset indent > +.It Dv VMM_IOC_CREATE Fa "struct vm_create_params *" > +Create a VM, initializing > +.Xr vmm 4 > +if not yet started. (Does not start the VCPU.) > +.It Dv VMM_IOC_RUN Fa "struct vm_run_params *" > +Run a VCPU for a defined VM. Returns on VM-exit, the VCPU stopped, or > +an error occurred > +.It Dv VMM_IOC_INFO Fa "struct vm_info_params *" > +Get information about the VMs currently hosted by > +.Xr vmm 4 > +.It Dv VMM_IOC_TERM Fa "struct vm_terminate_params *" > +Terminate a given VM > +.It Dv VMM_IOC_RESETCPU Fa "struct vm_resetcpu_params *" > +Reset a VCPU to power-on-init state using the provided register state > +.It Dv VMM_IOC_INTR Fa "struct vm_intr_params *" > +Signal a pending interrupt for a VCPU > +.It Dv VMM_IOC_READREGS Fa "struct vm_rwregs_params *" > +Read registers of a VCPU > +.It Dv VMM_IOC_WRITEREGS Fa "struct vm_rwregs_params *" > +Write registers values of a VCPU > +.It Dv VMM_IOC_READVMPARAMS Fa "struct vm_revmparams_params *" > +Read paravirtualized hardware parameters (such as > +.Xr pvclock 4 > +version) for a VM > +.It Dv VMM_IOC_WRITEVMPARAMS Fa "struct vm_rwvmparams_params *" > +Write paravirtualized hardware parameters (such as > +.Xr pvclock 4 > +guest physical addresss) for a VM > +.It Dv VMM_IOC_MPROTECT_EPT Fa "struct vm_mprotect_ept_params *" > +Set access protections on guest page table entries > +(only supported on hosts providing EPT or RVI) > .Sh SEE ALSO > .Xr cpu 4 , > .Xr intro 4 ,
Re: vmm.4: document supported ioctls
On Thu, Apr 01, 2021 at 06:49:07AM -0400, Dave Voutila wrote: > This diff documents the ioctl(2) values supported by vmm(4). Besides > vmd(8) there's at least one application I've seen (Solo5) directly using > vmm(4). > > For now I've tried to have short summary-level details, enough to > provide a general idea of purpose. The data structures aren't included > in the doc, but the mention of at least points to > where they're defined for now. That seems fair. > Feedback on my mdoc macro usage or verbiage? OK? See inline, but you can also use `mandoc -T lint ./vmm.4' and any warnings and errors. > Index: share/man/man4/man4.amd64/vmm.4 > === > RCS file: /cvs/src/share/man/man4/man4.amd64/vmm.4,v > retrieving revision 1.5 > diff -u -p -r1.5 vmm.4 > --- share/man/man4/man4.amd64/vmm.4 6 Dec 2015 19:06:17 - 1.5 > +++ share/man/man4/man4.amd64/vmm.4 1 Apr 2021 10:36:50 - > @@ -22,6 +22,8 @@ > .Nd virtual machine monitor > .Sh SYNOPSIS > .Cd "vmm0at mainbus0" > +.Pp > +.In machine/vmmvar.h > .Sh DESCRIPTION > The > .Nm > @@ -67,6 +69,45 @@ driver requires at least one CPU with ha > capabilities and nested or extended paging capabilities to be > present on the host. > For more information, consult the CPU vendor's documentation. > +.Pp > +The following > +.Xr ioctl 2 > +commands are provided for managing > +.Nm > +guests: > +.Pp > +.Bl -tag -width Ds -offset indent > +.It Dv VMM_IOC_CREATE Fa "struct vm_create_params *" > +Create a VM, initializing > +.Xr vmm 4 That's the page itself, just use .Nm here like you did in the last sentence. > +if not yet started. (Does not start the VCPU.) > +.It Dv VMM_IOC_RUN Fa "struct vm_run_params *" > +Run a VCPU for a defined VM. Returns on VM-exit, the VCPU stopped, or I'd use imperative mood, i.e. omit "s"^ and add^ "when", I guess. > +an error occurred New sentences go to new lines. > +.It Dv VMM_IOC_INFO Fa "struct vm_info_params *" > +Get information about the VMs currently hosted by > +.Xr vmm 4 This and all following sentences lack punctuation; with .Nm as per above that'd be ".Nm ." (mind the space between macro and dot if the line ends with a macro). > +.It Dv VMM_IOC_TERM Fa "struct vm_terminate_params *" > +Terminate a given VM > +.It Dv VMM_IOC_RESETCPU Fa "struct vm_resetcpu_params *" > +Reset a VCPU to power-on-init state using the provided register state > +.It Dv VMM_IOC_INTR Fa "struct vm_intr_params *" > +Signal a pending interrupt for a VCPU > +.It Dv VMM_IOC_READREGS Fa "struct vm_rwregs_params *" > +Read registers of a VCPU > +.It Dv VMM_IOC_WRITEREGS Fa "struct vm_rwregs_params *" > +Write registers values of a VCPU > +.It Dv VMM_IOC_READVMPARAMS Fa "struct vm_revmparams_params *" > +Read paravirtualized hardware parameters (such as > +.Xr pvclock 4 > +version) for a VM > +.It Dv VMM_IOC_WRITEVMPARAMS Fa "struct vm_rwvmparams_params *" > +Write paravirtualized hardware parameters (such as > +.Xr pvclock 4 > +guest physical addresss) for a VM > +.It Dv VMM_IOC_MPROTECT_EPT Fa "struct vm_mprotect_ept_params *" > +Set access protections on guest page table entries > +(only supported on hosts providing EPT or RVI) Missing .El here. > .Sh SEE ALSO > .Xr cpu 4 , > .Xr intro 4 , >
vmm.4: document supported ioctls
This diff documents the ioctl(2) values supported by vmm(4). Besides vmd(8) there's at least one application I've seen (Solo5) directly using vmm(4). For now I've tried to have short summary-level details, enough to provide a general idea of purpose. The data structures aren't included in the doc, but the mention of at least points to where they're defined for now. Feedback on my mdoc macro usage or verbiage? OK? -dv Index: share/man/man4/man4.amd64/vmm.4 === RCS file: /cvs/src/share/man/man4/man4.amd64/vmm.4,v retrieving revision 1.5 diff -u -p -r1.5 vmm.4 --- share/man/man4/man4.amd64/vmm.4 6 Dec 2015 19:06:17 - 1.5 +++ share/man/man4/man4.amd64/vmm.4 1 Apr 2021 10:36:50 - @@ -22,6 +22,8 @@ .Nd virtual machine monitor .Sh SYNOPSIS .Cd "vmm0at mainbus0" +.Pp +.In machine/vmmvar.h .Sh DESCRIPTION The .Nm @@ -67,6 +69,45 @@ driver requires at least one CPU with ha capabilities and nested or extended paging capabilities to be present on the host. For more information, consult the CPU vendor's documentation. +.Pp +The following +.Xr ioctl 2 +commands are provided for managing +.Nm +guests: +.Pp +.Bl -tag -width Ds -offset indent +.It Dv VMM_IOC_CREATE Fa "struct vm_create_params *" +Create a VM, initializing +.Xr vmm 4 +if not yet started. (Does not start the VCPU.) +.It Dv VMM_IOC_RUN Fa "struct vm_run_params *" +Run a VCPU for a defined VM. Returns on VM-exit, the VCPU stopped, or +an error occurred +.It Dv VMM_IOC_INFO Fa "struct vm_info_params *" +Get information about the VMs currently hosted by +.Xr vmm 4 +.It Dv VMM_IOC_TERM Fa "struct vm_terminate_params *" +Terminate a given VM +.It Dv VMM_IOC_RESETCPU Fa "struct vm_resetcpu_params *" +Reset a VCPU to power-on-init state using the provided register state +.It Dv VMM_IOC_INTR Fa "struct vm_intr_params *" +Signal a pending interrupt for a VCPU +.It Dv VMM_IOC_READREGS Fa "struct vm_rwregs_params *" +Read registers of a VCPU +.It Dv VMM_IOC_WRITEREGS Fa "struct vm_rwregs_params *" +Write registers values of a VCPU +.It Dv VMM_IOC_READVMPARAMS Fa "struct vm_revmparams_params *" +Read paravirtualized hardware parameters (such as +.Xr pvclock 4 +version) for a VM +.It Dv VMM_IOC_WRITEVMPARAMS Fa "struct vm_rwvmparams_params *" +Write paravirtualized hardware parameters (such as +.Xr pvclock 4 +guest physical addresss) for a VM +.It Dv VMM_IOC_MPROTECT_EPT Fa "struct vm_mprotect_ept_params *" +Set access protections on guest page table entries +(only supported on hosts providing EPT or RVI) .Sh SEE ALSO .Xr cpu 4 , .Xr intro 4 ,
