From d1a1397542f2e190fa4a30f103bfc625505f7c91 Mon Sep 17 00:00:00 2001
From: Ryuichiro Chiba <chibar@chromium.org>
Date: Fri, 30 Sep 2022 16:25:47 +0900
Subject: [PATCH] docs: add a vsock document to the book

Add a document which describes how to use the vsock device.

BUG=b:235965219
TEST=`mdformat --wrap 100 --check docs/book/src/SUMMARY.md docs/book/src/devices/vsock.md`
TEST=`mdbook build`

Change-Id: I7c444e84f14f5505a159358f8f5008eb231333f6
Reviewed-on: https://chromium-review.googlesource.com/c/crosvm/crosvm/+/3925333
Reviewed-by: Keiichi Watanabe <keiichiw@chromium.org>
Reviewed-by: Takaya Saeki <takayas@chromium.org>
Commit-Queue: Ryuichiro Chiba <chibar@chromium.org>
---
 docs/book/src/SUMMARY.md       |  1 +
 docs/book/src/devices/vsock.md | 49 ++++++++++++++++++++++++++++++++++
 2 files changed, 50 insertions(+)
 create mode 100644 docs/book/src/devices/vsock.md

diff --git a/docs/book/src/SUMMARY.md b/docs/book/src/SUMMARY.md
index 2f3cfd303f..bc74b75793 100644
--- a/docs/book/src/SUMMARY.md
+++ b/docs/book/src/SUMMARY.md
@@ -13,6 +13,7 @@
   - [Block](./devices/block.md)
   - [Network](./devices/net.md)
   - [Balloon](./devices/balloon.md)
+  - [Vsock](./devices/vsock.md)
   - [Pmem](./devices/pmem.md)
   - [Wayland](./devices/wayland.md)
   - [Video (experimental)](./devices/video.md)
diff --git a/docs/book/src/devices/vsock.md b/docs/book/src/devices/vsock.md
new file mode 100644
index 0000000000..bef504d2a2
--- /dev/null
+++ b/docs/book/src/devices/vsock.md
@@ -0,0 +1,49 @@
+# Vsock device
+
+crosvm supports [virtio-vsock] device for communication between the host and a guest VM.
+
+Assign a context id to a guest VM by passing it with `--cid` flag.
+
+```sh
+GUEST_CID=3
+
+crosvm run \
+  --cid "${GUEST_CID}" \
+  <usual crosvm arguments>
+  vmlinux
+```
+
+Then, the guest and the host can communicate with each other via vsock. Host always has 2 as its
+context id.
+
+crosvm assumes that the host has a vsock device at `/dev/vhost-vsock`. If you want to use a device
+at a different path or one given as an fd, you can use `--vhost-vsock-device` flag or
+`--vhost-vsock-fd` flag respectively.
+
+## Example usage
+
+At host shell:
+
+```sh
+PORT=11111
+
+# Listen at host
+ncat -l --vsock ${PORT}
+```
+
+At guest shell:
+
+```sh
+HOST_CID=2
+PORT=11111
+
+# Make a connection to the host
+ncat --vsock ${HOST_CID} ${PORT}
+```
+
+If a vsock device is configured properly in the guest VM, a connection between the host and the
+guest can be established and packets can be sent from both side. In the above example, your inputs
+to a shell on one's side should be shown at the shell on the other side if a connection is
+successfully established.
+
+[virtio-vsock]: https://docs.oasis-open.org/virtio/virtio/v1.1/csprd01/virtio-v1.1-csprd01.html#x1-389001r356