docs: update Vsock documentation

Signed-off-by: Adrian Catangiu <[email protected]>

docs/design.md

@@ -73,10 +73,10 @@ runs the following threads: API, VMM and vCPU(s). The API thread is responsible
 for Firecracker's API server and associated control plane. It's never in the
 fast path of the virtual machine. The VMM thread exposes the machine model,
 minimal legacy device model, microVM metadata service (MMDS) and VirtIO device
-emulated Net and Block devices, complete with I/O rate limiting. In addition to
-them, there are one or more vCPU threads (one per guest CPU core). They are
-created via KVM and run the `KVM_RUN` main loop. They execute synchronous I/O
-and memory-mapped I/O operations on devices models.
+emulated Net, Block and Vsock devices, complete with I/O rate limiting. In
+addition to them, there are one or more vCPU threads (one per guest CPU core).
+They are created via KVM and run the `KVM_RUN` main loop. They execute
+synchronous I/O and memory-mapped I/O operations on devices models.
 
 ### Threat Containment
 

docs/vsock.md

@@ -24,9 +24,9 @@ host. To that end, Firecracker implements the virtio-vsock device model, and
 mediates communication between AF_UNIX sockets (on the host end) and AF_VSOCK
 sockets (on the guest end).
 
-In order to provide channel multiplexing, AF_VSOCK ports are translated into
-multiple AF_UNIX sockets (one Unix socket per vsock port). The virtio-vsock
-device must be configured with a file path to an AF_UNIX socket (e.g.
+In order to provide channel multiplexing the guest `AF_VSOCK` ports are mapped
+1:1 to `AF_UNIX` sockets on the host. The virtio-vsock device must be
+configured with a path to an `AF_UNIX` socket on the host (e.g.
 `/path/to/v.sock`). There are two scenarios to be considered, depending on
 where the connection is initiated.
 
@@ -45,6 +45,8 @@ acknowledgement message to the connecting end (host-side), in the form
 the host end. If no one is listening, Firecracker will terminate the host
 connection.
 
+Client A initiates connection to Server A in [figure below](#vsock-connections):
+
 1. Host: At VM configuration time, add a virtio-vsock device, with some path
    specified in `uds_path`;
 2. Guest: create an AF_VSOCK socket and `listen()` on `<port_num>`;
@@ -67,8 +69,7 @@ decimal), as specified in the connection request packet. If no such socket
 exists, or no one is listening on it, a connection cannot be established, and a
 VIRTIO_VSOCK_OP_RST packet will be sent back to the guest.
 
-From the user perspective, these would be the steps taken to establish a
-communication channel:
+Client B initiates connection to Server B in [figure below](#vsock-connections):
 
 1. Host: At VM configuration time, add a virtio-vsock device, with some
    `uds_path` (e.g. `/path/to/v.sock`).
@@ -80,6 +81,10 @@ communication channel:
 The channel is established between the sockets obtained at steps 4 (host)
 and 3 (guest).
 
+![Vsock Connections](
+images/vsock-connections.png?raw=true
+"Vsock Connections")
+
 ## Setting up the virtio-vsock device
 
 The virtio-vsock device will require an ID, a CID, and the path to a backing