diff --git a/vhost-device-vsock/CHANGELOG.md b/vhost-device-vsock/CHANGELOG.md index ff938a8..235c199 100644 --- a/vhost-device-vsock/CHANGELOG.md +++ b/vhost-device-vsock/CHANGELOG.md @@ -2,6 +2,7 @@ ## Unreleased ### Added +- [#698](https://github.com/rust-vmm/vhost-device/pull/698) vsock: add mdoc page ### Changed diff --git a/vhost-device-vsock/vhost-device-vsock.1 b/vhost-device-vsock/vhost-device-vsock.1 new file mode 100644 index 0000000..8e30b38 --- /dev/null +++ b/vhost-device-vsock/vhost-device-vsock.1 @@ -0,0 +1,197 @@ +.Dd July 24, 2024 +.Dt VHOST-DEVICE-VSOCK 1 +.Os +.Sh NAME +.Nm vhost-device-vsock +.Nd A virtio-vsock device using the vhost-user protocol +.Sh SYNOPSIS +.Nm +.Fl \-socket Ar SOCKET +.Fl \-uds-path Ar UDS_PATH +.Sh DESCRIPTION +The +.Nm +utility launches a daemon listening to +.Ar SOCKET +for incoming connections from +.Em vhost-user +front-ends. +Upon successful connection and protocol negotiation, +it starts a vhost-user backend instance. +The functionality of a VIRTIO vsock device is provided +using the specified unix socket, +.Ar UDS_PATH Ns +, to which a host-side application connects to. +.Bl -tag -width Ds +.It Fl -help | h +Print help information. +.It Fl -version | V +Print version information. +.It Fl \-guest-cid Pa GUEST_CID +Context identifier of the guest which uniquely identifies the +device for its lifetime +.Bq default: 3 +.It Fl \-socket Pa SOCKET +Unix socket to which a hypervisor connects to and sets up the +control path with the device +.It Fl \-uds-path Pa UDS_PATH +Unix socket to which a host-side application connects to +.It Fl \-tx-buffer-size Pa TX_BUFFER_SIZE +The size of the buffer used for the TX virtqueue +.Bq default: 65536 +.It Fl \-queue-size Pa QUEUE_SIZE +The size of the vring queue +.Bq default: 1024 +.It Fl \-groups Pa GROUPS +The list of group names to which the device belongs. +A group is a set of devices that allow sibling communication between their +guests. +.Bq default: Qq default +.It Fl \-config Pa CONFIG +Load from a given configuration file +.sp +.Sy NOTE : +conflicts with +.Li --vm +.It Fl \-vm Pa VM +Device parameters corresponding to a VM in the form of comma +separated +.Li key=value +pairs. +Multiple instances of this option +can be provided to configure devices for multiple guests. +The allowed keys are: +.Bl -enum -compact -width 0 -offset 1n +.It +.Li guest_cid +.It +.Li socket +.It +.Li uds_path +.It +.Li tx_buffer_size +.It +.Li queue_size +.It +.Li group +.El +.Sy NOTE : +conflicts with +.Li --config +.El +.Sh EXIT STATUS +.Ex -std +.Sh EXAMPLES +.Ss Run the vhost-device-vsock device +.Bd -literal +vhost-device-vsock \\ + --vm \\ +guest_cid=,\\ +socket=,\\ +uds-path=\\ +[,tx-buffer-size=][,queue-size=][,groups=] +.Ed +.sp +Specify the +.Fa `--vm` +argument multiple times to specify multiple devices like this: +.Bd -literal +vhost-device-vsock \\ +--vm guest-cid=3,socket=/tmp/vhost3.socket,uds-path=/tmp/vm3.vsock,groups=group1+groupA \\ +--vm guest-cid=4,socket=/tmp/vhost4.socket,uds-path=/tmp/vm4.vsock,tx-buffer-size=32768,queue-size=256 +.Ed +Or use a configuration file: +.Bd -literal +vhost-device-vsock --config= +.Ed +Configuration file example in yaml format: +.Bd -literal +vms: + - guest_cid: 3 + socket: /tmp/vhost3.socket + uds_path: /tmp/vm3.sock + tx_buffer_size: 65536 + queue_size: 1024 + groups: group1+groupA + - guest_cid: 4 + socket: /tmp/vhost4.socket + uds_path: /tmp/vm4.sock + tx_buffer_size: 32768 + queue_size: 256 + groups: group2+groupB +.Ed +.sp +.Ss Run VMM (e.g. QEMU) +.Bd -literal +qemu-system-x86_64 \\ + \\ + -object memory-backend-memfd,id=mem0,size= \\ # size == -m size + -machine ,memory-backend=mem0 \\ + -chardev socket,id=char0,reconnect=0,path= \\ + -device vhost-user-vsock-pci,chardev=char0 +.Ed +.sp +.Sy NOTE : +With QEMU you have to use a shareable memory-backend such as +.Li memory-backend-memfd +.sp +.Ss Working example +.Bd -literal +shell1$ vhost-device-vsock --vm guest-cid=4,uds-path=/tmp/vm4.vsock,socket=/tmp/vhost4.socket +.Ed +.sp +or if you want to configure the TX buffer size and vring queue size +.Bd -literal +shell1$ vhost-device-vsock --vm guest-cid=4,uds-path=/tmp/vm4.vsock,socket=/tmp/vhost4.socket,tx-buffer-size=65536,queue-size=1024 +.Ed +.Bd -literal +shell2$ qemu-system-x86_64 \\ + -drive file=vm.qcow2,format=qcow2,if=virtio -smp 2 \\ + -object memory-backend-memfd,id=mem0,size=512M \\ + -machine q35,accel=kvm,memory-backend=mem0 \\ + -chardev socket,id=char0,reconnect=0,path=/tmp/vhost4.socket \\ + -device vhost-user-vsock-pci,chardev=char0 +.Ed +.Sh STANDARDS +.Bl -dash -compact +.It +.Rs +.%B Virtual I/O Device (VIRTIO) +.%O Version 1.2 +.%A OASIS +.%U https://docs.oasis-open.org/virtio/virtio/v1.2/virtio-v1.2.html +.%D July 01, 2022 +.Re +.It +.Rs +.%B Vhost-user Protocol +.%O Unversioned +.%A QEMU Project +.%U https://qemu.readthedocs.io/en/v9.0.0/interop/vhost-user.html +.%D Undated +.Re +.El +.Sh AUTHORS +Copyright 2023\(en2024 +.Bl -item -compact +.It +.An Harshavardhan Unnibhavi Aq Mt harshanavkis@gmail.com> +.It +.An Stefano Garzarella Aq Mt sgarzare@redhat.com> +.El +.Pp +Released under Apache-2.0 OR BSD-3-Clause. +.Po +See files +.Pa LICENSE-APACHE Ns +, +.Pa LICENSE-BSD-3-Clause +for full copyright and warranty notices. +.Pc +.Ss Links +.Bl -item -compact +.It +.Lk https://github.com/rust-vmm/vhost-device "Main\ repository" +.It +.Lk https://crates.io/crates/vhost-device-vsock "on\ crates.io" +.El