book: Add a section about pmem-ext2

Bug: none
Test: mdbook serve

Change-Id: I323ccd29eb0f54b2d940900924935826d6bb217e
Reviewed-on: https://chromium-review.googlesource.com/c/crosvm/crosvm/+/6099776
Commit-Queue: Keiichi Watanabe <keiichiw@chromium.org>
Reviewed-by: Takaya Saeki <takayas@chromium.org>

docs/book/src/SUMMARY.md

@@ -22,7 +22,9 @@
   - [SCSI (experimental)](./devices/scsi.md)
   - [Fs](./devices/fs.md)
   - [Vsock](./devices/vsock.md)
-  - [Pmem](./devices/pmem.md)
+  - [Pmem](./devices/pmem/README.md)
+    - [VirtIO Pmem](./devices/pmem/basic.md)
+    - [Sharing host directory with virtio-pmem (experimental)](./devices/pmem/pmem_ext2.md)
   - [USB](./devices/usb.md)
   - [Wayland](./devices/wayland.md)
   - [Video (experimental)](./devices/video.md)

docs/book/src/devices/index.md

@@ -77,7 +77,7 @@ Currently, only network devices are supported.
 [`iommu`]: https://chromium.googlesource.com/crosvm/crosvm/+/refs/heads/main/devices/src/virtio/iommu.rs
 [`net`]: net.md
 [`p9`]: https://chromium.googlesource.com/crosvm/crosvm/+/refs/heads/main/devices/src/virtio/p9.rs
-[`pmem`]: pmem.md
+[`pmem`]: pmem/README.md
 [`rng`]: https://chromium.googlesource.com/crosvm/crosvm/+/refs/heads/main/devices/src/virtio/rng.rs
 [`scsi`]: scsi.md
 [`serial`]: https://chromium.googlesource.com/crosvm/crosvm/+/refs/heads/main/devices/src/serial.rs

docs/book/src/devices/pmem/README.md

@@ -0,0 +1,11 @@
+# Pmem
+
+This section contains the following sub pages:
+
+- **[VirtIO Pmem]** describes the basic usage of virtio-pmem device to provide a disk device with
+  the guest.
+- **[Sharing host directory via virtio-pmem]** describes crosvm's virtual ext2 feature on
+  virtio-pmem, which allow sharing a host directory with the guest as read-only.
+
+[sharing host directory via virtio-pmem]: pmem_ext2.md
+[virtio pmem]: basic.md

docs/book/src/devices/pmem/basic.md

@@ -1,4 +1,4 @@
-# Pmem
+# VirtIO Pmem
 
 crosvm supports `virtio-pmem` to provide a virtual device emulating a byte-addressable persistent
 memory device. The disk image is provided to the guest using a memory-mapped view of the image file,
@@ -32,5 +32,5 @@ the guest page cache. This can result in lower memory overhead versus `virtio-bl
 
 The file backing a persistent memory device is mapped directly into the guest's address space, which
 means that only the raw disk image format is supported; disk images in qcow2 or other formats may
-not be used as a pmem device. See the [`block`](block.md) device for an alternative that supports
+not be used as a pmem device. See the [`block`](../block.md) device for an alternative that supports
 more file formats.

docs/book/src/devices/pmem/pmem_ext2.md

@@ -0,0 +1,55 @@
+# Sharing host directory with virtio-pmem
+
+crosvm has an experimental feature to share a host directory with the guest as read-only via
+virtio-pmem device.
+
+## How it works
+
+When this feature is enabled, `crosvm` creates a virtual ext2 filesystem in memory. This filesystem
+contains the contents of the specified host directory. When creating the file system, `crosvm` do
+`mmap` each file instead of data copy. As a result, the actual file data is read from disk only when
+it's accessed by the guest.
+
+## Usage
+
+To share a host directory with the guest, you'll need to start `crosvm` with the device enabled, and
+mount the device in the guest.
+
+### Host
+
+You can use `--pmem-ext2` flag to enable the device.
+
+```console
+$ mkdir host_shared_dir
+$ HOST_SHARED_DIR=$(pwd)/host_shared_dir
+$ echo "Hello!" > $HOST_SHARED_DIR/test.txt
+$ crosvm run \
+    --pmem-ext2 "$HOST_SHARED_DIR" \
+    # usual crosvm args
+```
+
+You can check a full list of parameters for `--pmem-ext2` with `crosvm run --help`.
+
+### Guest
+
+Then, you can mount the ext2 file system from the guest. With `-o dax`, we can avoid duplicated page
+caches between the guest and the host.
+
+```console
+$ mkdir /tmp/shared
+$ mount -t ext2 -o dax /dev/pmem0 /tmp/shared
+$ ls /tmp/shared
+lost+found  test.txt
+$ cat /tmp/shared/test.txt
+Hello!
+```
+
+## Comparison with other methods
+
+Since access to files provided by this device is through pmem, it is done as a host OS page fault.
+This can reduce the number of context switches to the host userspace compared to virtio-blk or
+virtio-fs.
+
+This feature is similar to
+[the VVFAT (Virtual FAT filesystem)](https://github.com/qemu/qemu/blob/master/block/vvfat.c) device
+in QEMU, but our pmem-ext2 uses the ext2 filesystem and supports read-only accesses only.