Orange Pi5 kernel

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