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