vsock: add mdoc page

Co-authored-by: Manos Pitsidianakis <manos@pitsidianak.is>
Signed-off-by: Sandro Bonazzola <sbonazzo@redhat.com>

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
 

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=<GUEST_CID>,\\
+socket=<SOCKET_PATH>,\\
+uds-path=<UDS_PATH>\\
+[,tx-buffer-size=<TX_SIZE>][,queue-size=<QUEUE_SIZE>][,groups=<GROUPS_LIST>]
+.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=<path to the local yaml configuration file>
+.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 \\
+  <normal QEMU options> \\
+  -object memory-backend-memfd,id=mem0,size=<Guest RAM size> \\ # size == -m size
+  -machine <machine options>,memory-backend=mem0 \\
+  -chardev socket,id=char0,reconnect=0,path=<vhost-user socket 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