1.. SPDX-License-Identifier: GPL-2.0
2
3===================================================
4virtiofs: virtio-fs host<->guest shared file system
5===================================================
6
7- Copyright (C) 2019 Red Hat, Inc.
8
9Introduction
10============
11The virtiofs file system for Linux implements a driver for the paravirtualized
12VIRTIO "virtio-fs" device for guest<->host file system sharing.  It allows a
13guest to mount a directory that has been exported on the host.
14
15Guests often require access to files residing on the host or remote systems.
16Use cases include making files available to new guests during installation,
17booting from a root file system located on the host, persistent storage for
18stateless or ephemeral guests, and sharing a directory between guests.
19
20Although it is possible to use existing network file systems for some of these
21tasks, they require configuration steps that are hard to automate and they
22expose the storage network to the guest.  The virtio-fs device was designed to
23solve these problems by providing file system access without networking.
24
25Furthermore the virtio-fs device takes advantage of the co-location of the
26guest and host to increase performance and provide semantics that are not
27possible with network file systems.
28
29Usage
30=====
31Mount file system with tag ``myfs`` on ``/mnt``:
32
33.. code-block:: sh
34
35  guest# mount -t virtiofs myfs /mnt
36
37Please see https://virtio-fs.gitlab.io/ for details on how to configure QEMU
38and the virtiofsd daemon.
39
40Internals
41=========
42Since the virtio-fs device uses the FUSE protocol for file system requests, the
43virtiofs file system for Linux is integrated closely with the FUSE file system
44client.  The guest acts as the FUSE client while the host acts as the FUSE
45server.  The /dev/fuse interface between the kernel and userspace is replaced
46with the virtio-fs device interface.
47
48FUSE requests are placed into a virtqueue and processed by the host.  The
49response portion of the buffer is filled in by the host and the guest handles
50the request completion.
51
52Mapping /dev/fuse to virtqueues requires solving differences in semantics
53between /dev/fuse and virtqueues.  Each time the /dev/fuse device is read, the
54FUSE client may choose which request to transfer, making it possible to
55prioritize certain requests over others.  Virtqueues have queue semantics and
56it is not possible to change the order of requests that have been enqueued.
57This is especially important if the virtqueue becomes full since it is then
58impossible to add high priority requests.  In order to address this difference,
59the virtio-fs device uses a "hiprio" virtqueue specifically for requests that
60have priority over normal requests.
61