search

rust-vmm / vhost-device

'vhost-user' device backends workspace
Apache License 2.0
67 stars 46 forks source link

vsock: add mdoc page #698

Closed sandrobonazzola closed 1 month ago

sandrobonazzola commented 1 month ago

Summary of the PR

Add manual page in mdoc format for vhost-device-vsock command

Requirements

Before submitting your PR, please make sure you addressed the following requirements:

sandrobonazzola commented 1 month ago

I verified the syntax of the man page with mandoc -T lint.

rendered with mandoc -I os=General -Tutf8 ~/vhost-device-sound.1 | col -b

as plain text: 

VHOST-DEVICE-VSOCK(1)       General Commands Manual  VHOST-DEVICE-VSOCK(1)

NAME
     vhost-device-vsock – A virtio-vsock device using the vhost-user protocol

SYNOPSIS
     vhost-device-vsock [OPTIONS] --socket SOCKET --uds-path UDS_PATH

DESCRIPTION
     The vhost-device-vsock utility launches a daemon listening to SOCKET for
     incoming connections from 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, UDS_PATH, to which a host-side application
     connects to.

     --help | -h
         Print help information.

     --version | -V
         Print version information.

     --guest-cid GUEST_CID
         Context identifier of the guest which uniquely identifies the
         device for its lifetime [default: 3]

     --socket SOCKET
         Unix socket to which a hypervisor connects to and sets up the
         control path with the device

     --uds-path UDS_PATH
         Unix socket to which a host-side application connects to

     --tx-buffer-size TX_BUFFER_SIZE
         The size of the buffer used for the TX virtqueue [default: 65536]

     --queue-size QUEUE_SIZE
         The size of the vring queue [default: 1024]

     --groups 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.  [default: default]

     --config CONFIG
         Load from a given configuration file

     --vm VM
         Device parameters corresponding to a VM in the form of comma
         separated key=value pairs.  Multiple instances of this option can
         be provided to configure devices for multiple guests.  The
         allowed keys are:
          1. guest_cid
          2. socket
          3. uds_path
          4. tx_buffer_size
          5. queue_size
          6. group

EXIT STATUS
     The vhost-device-vsock utility exits 0 on success, and >0 if an error
     occurs.

EXAMPLES
     Launch the backend on the host machine:

     host# vhost-device-vsock --socket=/tmp/vhost-user-vsock.sock --uds-path=/tmp/vhost-user-vsock.uds

     Launch the backend for multiple VMs:

     host# vhost-device-vsock \
       --vm guest-cid=3,socket=/tmp/vhost3.socket,uds-path=/tmp/vm3.vsock,tx-buffer-size=65536,queue-size=1024,groups=group1+group2 \
       --vm guest-cid=4,socket=/tmp/vhost4.socket,uds-path=/tmp/vm4.vsock,tx-buffer-size=65536,queue-size=1024,groups=group1+group2

     With QEMU, you can add a virtio device that uses the backend's socket
     with the following flags:

     -chardev socket,id=char0,reconnect=0,path=/tmp/vhost-user-vsock.sock \
     -device vhost-user-vsock-pci,chardev=char0"

STANDARDS
     -   OASIS, Virtual I/O Device (VIRTIO),
     https://docs.oasis-open.org/virtio/virtio/v1.2/virtio-v1.2.html, July
     01, 2022, Version 1.2.
     -   QEMU Project, Vhost-user Protocol,
     https://qemu.readthedocs.io/en/v9.0.0/interop/vhost-user.html,
     Undated, Unversioned.

AUTHORS
     Copyright 2023–2024
     Dorinda Bassey <dbassey@redhat.com>
     Dorjoy Chowdhury <dorjoychy111@gmail.com>
     Erik Schilling <erik.schilling@linaro.org>
     Jeongik Cha <jeongik@google.com>
     Manos Pitsidianakis <manos.pitsidianakis@linaro.org>
     Ramyak Mehra <ramyak@dyte.io>
     Stefano Garzarella <sgarzare@redhat.com>
     Viresh Kumar <viresh.kumar@linaro.org>

     Released under Apache-2.0 OR BSD-3-Clause.  (See files LICENSE-APACHE,
     LICENSE-BSD-3-Clause for full copyright and warranty notices.)

   Links
     Main repository: https://github.com/rust-vmm/vhost-device
     on crates.io: https://crates.io/crates/vhost-device-vsock

General              July 24, 2024                 General
sandrobonazzola commented 1 month ago

Thanks for the PR!

I'm adding comments inline, but first can you please change the commit message to replace mandoc with mdoc? (mdoc is the markup language, mandoc is the command line utility)

Done

stefano-garzarella commented 1 month ago

LGTM, I'd just squash the fixup patch with the first one if it is okay with you.

sandrobonazzola commented 1 month ago

LGTM, I'd just squash the fixup patch with the first one if it is okay with you.

Done

epilys commented 1 month ago

@sandrobonazzola thank you! :)

sandrobonazzola commented 1 month ago

you're welcome :-)