Re: [PATCH] vsock.7: document VSOCK socket address family

["Jorgen S. Hansen" <jhansen-pghWNbHTmq7QT0dZR+AlfA@public.gmane.org>]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain; charset="utf-8", Size: 6702 bytes --]


> On Nov 30, 2017, at 12:21 PM, Stefan Hajnoczi <stefanha@redhat.com> wrote:
> 
> The AF_VSOCK address family has been available since Linux 3.9 without a
> corresponding man page.
> 
> This patch adds vsock.7 and describes its use along the same lines as
> existing ip.7, unix.7, and netlink.7 man pages.
> 
> CC: Jorgen Hansen <jhansen@vmware.com>
> CC: Dexuan Cui <decui@microsoft.com>
> Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
> ---
> man7/vsock.7 | 175 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
> 1 file changed, 175 insertions(+)
> create mode 100644 man7/vsock.7
> 
> diff --git a/man7/vsock.7 b/man7/vsock.7
> new file mode 100644
> index 000000000..48c6c2e1e
> --- /dev/null
> +++ b/man7/vsock.7
> @@ -0,0 +1,175 @@
> +.TH VSOCK 7 2017-11-30 "Linux" "Linux Programmer's Manual"
> +.SH NAME
> +vsock \- Linux VSOCK address family
> +.SH SYNOPSIS
> +.B #include <sys/socket.h>
> +.br
> +.B #include <linux/vm_sockets.h>
> +.PP
> +.IB stream_socket " = socket(AF_VSOCK, SOCK_STREAM, 0);"
> +.br
> +.IB datagram_socket " = socket(AF_VSOCK, SOCK_DGRAM, 0);"
> +.SH DESCRIPTION
> +The VSOCK address family facilitates communication between virtual machines and
> +the host they are running on.  This address family is used by guest agents and
> +hypervisor services that need a communications channel that is independent of
> +virtual machine network configuration.
> +.PP
> +Valid socket types are
> +.B SOCK_STREAM
> +and
> +.B SOCK_DGRAM .

The space here results in a space between SOCK_DGRAM and the “.” in the formatted text. Is that intentional?

> +.B SOCK_STREAM
> +provides connection-oriented byte streams with guaranteed, in-order delivery.
> +.B SOCK_DGRAM
> +provides a connectionless datagram packet service.  Availability of these
> +socket types is dependent on the underlying hypervisor.
> +.PP
> +A new socket is created with
> +.PP
> +    socket(AF_VSOCK, socket_type, 0);
> +.PP
> +When a process wants to establish a connection it calls
> +.BR connect (2)
> +with a given destination socket address.  The socket is automatically bound to
> +a free port if unbound.
> +.PP
> +A process can listen for incoming connections by first binding to a socket address using
> +.BR bind (2)
> +and then calling
> +.BR listen (2).
> +.PP
> +Data is transferred using the usual
> +.BR send (2)
> +and
> +.BR recv (2)
> +family of socket system calls.
> +.SS Address format
> +A socket address is defined as a combination of a 32-bit Context Identifier (CID) and a 32-bit port number.  The CID identifies the source or destination, which is either a virtual machine or the host.  The port number differentiates between multiple services running on a single machine.
> +.PP
> +.in +4n
> +.EX
> +struct sockaddr_vm {
> +    sa_family_t     svm_family;     /* address family: AF_VSOCK */
> +    unsigned short  svm_reserved1;
> +    unsigned int    svm_port;       /* port in native byte order */
> +    unsigned int    svm_cid;        /* address in native byte order */
> +};
> +.EE
> +.in
> +.PP
> +.I svm_family
> +is always set to
> +.BR AF_VSOCK .

Again the space before “."

> +.I svm_reserved1
> +is always set to 0.
> +.I svm_port
> +contains the port in native byte order.
> +The port numbers below 1024 are called
> +.IR "privileged ports" .
> +Only a process with
> +.B CAP_NET_BIND_SERVER
> +capability may
> +.BR bind (2)
> +to these port numbers.
> +.PP
> +There are several special addresses:
> +.B VMADDR_CID_ANY
> +(-1U)
> +means any address for binding;
> +.B VMADDR_CID_HYPERVISOR

We use VMADDR_CID_HYPERVISOR for communicating with services in the hypervisor, so you could describe this as “an address reserved for services built into the hypervisor”.

> +(0) and
> +.B VMADDR_CID_RESERVED
> +(1) are unused addresses;
> +.B VMADDR_CID_HOST
> +(2)
> +is the well-known address of the host.
> +.PP
> +The special constant
> +.B VMADDR_PORT_ANY
> +(-1U)
> +means any port number for binding.
> +.SS Live migration
> +Sockets are affected by live migration of virtual machines.  Connected
> +.B SOCK_STREAM
> +sockets become disconnected when the virtual machine migrates to a new host.
> +Applications must reconnect when this happens.
> +.PP
> +The local CID may change across live migration if the old CID is not available
> +on the new host.  Bound sockets are automatically updated to the new CID.
> +.SS Ioctls
> +.TP
> +.B IOCTL_VM_SOCKETS_GET_LOCAL_CID
> +Get the CID of the local machine.  The argument is a pointer to an unsigned int.
> +.IP
> +.in +4n
> +.EX
> +.IB error " = ioctl(" socket ", " IOCTL_VM_SOCKETS_GET_LOCAL_CID ", " &cid ");"
> +.EE
> +.in
> +.IP
> +Consider using
> +.B VMADDR_CID_ANY
> +when binding instead of getting the local CID with
> +.B IOCTL_VM_SOCKETS_GET_LOCAL_CID .

space before “.”

> +.SH ERRORS
> +.TP
> +.B EACCES
> +Unable to bind to a privileged port without the
> +.B CAP_NET_BIND_SERVICE
> +capability.
> +.TP
> +.B EINVAL
> +Invalid parameters.  This includes:
> +attempting to bind a socket that is already bound, providing an invalid struct
> +.B sockaddr_vm ,

space before “,”

> +and other input validation errors.
> +.TP
> +.B EOPNOTSUPP
> +Operation not supported.  This includes:
> +the
> +.B MSG_OOB
> +flag that is not implemented for
> +.B sendmsg (2)
> +and
> +.B MSG_PEEK
> +for
> +.B recvmsg (2).
> +.TP
> +.B EADDRINUSE
> +Unable to bind to a port that is already in use.
> +.TP
> +.B EADDRNOTAVAIL
> +Unable to find a free port for binding or unable to bind to a non-local CID.
> +.TP
> +.B ENOTCONN
> +Unable to perform operation on an unconnected socket.
> +.TP
> +.B ENOPROTOOPT
> +Invalid socket option in
> +.B setsockopt (2)
> +or
> +.B getsockopt (2).
> +.TP
> +.B EPROTONOSUPPORT
> +Invalid socket protocol number.  Protocol should always be 0.
> +.TP
> +.B ESOCKTNOSUPPORT
> +Unsupported socket type in
> +.B socket (2).
> +Only
> +.B SOCK_STREAM
> +and
> +.B SOCK_DGRAM
> +are valid.
> +.SH VERSIONS
> +Support for VMware has been available since Linux 3.9.  KVM (virtio) is

VMware (VMCI) for clarity.

> +supported since Linux 4.8.  Hyper-V is supported since 4.14.
> +.SH SEE ALSO
> +.BR socket (2),
> +.BR bind (2),
> +.BR connect (2),
> +.BR listen (2),
> +.BR send (2),
> +.BR recv (2),
> +.BR capabilities (7)
> -- 
> 2.14.3
> 

Apart from the nits, this looks great.

Thanks,
Jorgen

N‹§²æìr¸›yúèšØb²X¬¶Ç§vØ^–)Þº{.nÇ+‰·¥Š{±™©âžØ^n‡r¡ö¦zË\x1aëh™¨è­Ú&¢îý»\x05ËÛÔØï¦v¬Îf\x1dp)¹¹br	šê+€Ê+zf£¢·hšˆ§~†­†Ûiÿûàz¹\x1e®w¥¢¸?™¨è­Ú&¢)ߢ^[f