OvmfPkg/Include/IndustryStandard/VirtioFs.h

   1 /** @file
   2   Type and macro definitions specific to the Virtio Filesystem device.
   3
   4   At the time of this writing, the latest released Virtio specification (v1.1)
   5   does not include the virtio-fs device. The development version of the
   6   specification defines it however; see the latest version at
   7   <https://github.com/oasis-tcs/virtio-spec/blob/87fa6b5d8155/virtio-fs.tex>.
   8
   9   This header file is minimal, and only defines the types and macros that are
  10   necessary for the OvmfPkg implementation.
  11
  12   Copyright (C) 2020, Red Hat, Inc.
  13
  14   SPDX-License-Identifier: BSD-2-Clause-Patent
  15 **/
  16
  17 #ifndef VIRTIO_FS_H_
  18 #define VIRTIO_FS_H_
  19
  20 #include <IndustryStandard/Virtio.h>
  21
  22 //
  23 // Lowest numbered queue for sending normal priority requests.
  24 //
  25 #define VIRTIO_FS_REQUEST_QUEUE 1
  26
  27 //
  28 // Number of bytes in the "VIRTIO_FS_CONFIG.Tag" field.
  29 //
  30 #define VIRTIO_FS_TAG_BYTES 36
  31
  32 //
  33 // Device configuration layout.
  34 //
  35 #pragma pack (1)
  36 typedef struct {
  37   //
  38   // The Tag field can be considered the filesystem label, or a mount point
  39   // hint. It is UTF-8 encoded, and padded to full size with NUL bytes. If the
  40   // encoded bytes take up the entire Tag field, then there is no NUL
  41   // terminator.
  42   //
  43   UINT8 Tag[VIRTIO_FS_TAG_BYTES];
  44   //
  45   // The total number of request virtqueues exposed by the device (i.e.,
  46   // excluding the "hiprio" queue).
  47   //
  48   UINT32 NumReqQueues;
  49 } VIRTIO_FS_CONFIG;
  50 #pragma pack ()
  51
  52 //
  53 // FUSE-related definitions follow.
  54 //
  55 // From virtio-v1.1-cs01-87fa6b5d8155, 5.11 File System Device: "[...] The
  56 // driver acts as the FUSE client mounting the file system. The virtio file
  57 // system device provides the mechanism for transporting FUSE requests [...]"
  58 //
  59 // Unfortunately, the documentation of the FUSE wire protocol is lacking. The
  60 // Virtio spec (as of this writing) simply defers to
  61 // "include/uapi/linux/fuse.h" in the Linux kernel source -- see the reference
  62 // in virtio spec file "introduction.tex", at commit 87fa6b5d8155.
  63 //
  64 // Of course, "include/uapi/linux/fuse.h" is a moving target (the virtio spec
  65 // does not specify a particular FUSE interface version). The OvmfPkg code
  66 // targets version 7.31, because that's the lowest version that the QEMU
  67 // virtio-fs daemon supports at this time -- see QEMU commit 72c42e2d6551
  68 // ("virtiofsd: Trim out compatibility code", 2020-01-23).
  69 //
  70 // Correspondingly, Linux's "include/uapi/linux/fuse.h" is consulted as checked
  71 // out at commit (c6ff213fe5b8^) = d78092e4937d ("fuse: fix page dereference
  72 // after free", 2020-09-18); that is, right before commit c6ff213fe5b8 ("fuse:
  73 // add submount support to <uapi/linux/fuse.h>", 2020-09-18) introduces FUSE
  74 // interface version 7.32.
  75 //
  76 #define VIRTIO_FS_FUSE_MAJOR  7
  77 #define VIRTIO_FS_FUSE_MINOR 31
  78
  79 //
  80 // The inode number of the root directory.
  81 //
  82 #define VIRTIO_FS_FUSE_ROOT_DIR_NODE_ID 1
  83
  84 //
  85 // File mode bitmasks.
  86 //
  87 #define VIRTIO_FS_FUSE_MODE_PERM_RWXU 0000700u
  88 #define VIRTIO_FS_FUSE_MODE_PERM_RWXG 0000070u
  89 #define VIRTIO_FS_FUSE_MODE_PERM_RWXO 0000007u
  90
  91 //
  92 // Flags for VirtioFsFuseOpOpen.
  93 //
  94 #define VIRTIO_FS_FUSE_OPEN_REQ_F_RDONLY 0
  95 #define VIRTIO_FS_FUSE_OPEN_REQ_F_RDWR   2
  96
  97 //
  98 // FUSE operation codes.
  99 //
 100 typedef enum {
 101   VirtioFsFuseOpForget      =  2,
 102   VirtioFsFuseOpMkDir       =  9,
 103   VirtioFsFuseOpOpen        = 14,
 104   VirtioFsFuseOpRelease     = 18,
 105   VirtioFsFuseOpFsync       = 20,
 106   VirtioFsFuseOpFlush       = 25,
 107   VirtioFsFuseOpInit        = 26,
 108   VirtioFsFuseOpOpenDir     = 27,
 109   VirtioFsFuseOpReleaseDir  = 29,
 110   VirtioFsFuseOpFsyncDir    = 30,
 111 } VIRTIO_FS_FUSE_OPCODE;
 112
 113 #pragma pack (1)
 114 //
 115 // Request-response headers common to all request types.
 116 //
 117 typedef struct {
 118   UINT32 Len;
 119   UINT32 Opcode;
 120   UINT64 Unique;
 121   UINT64 NodeId;
 122   UINT32 Uid;
 123   UINT32 Gid;
 124   UINT32 Pid;
 125   UINT32 Padding;
 126 } VIRTIO_FS_FUSE_REQUEST;
 127
 128 typedef struct {
 129   UINT32 Len;
 130   INT32  Error;
 131   UINT64 Unique;
 132 } VIRTIO_FS_FUSE_RESPONSE;
 133
 134 //
 135 // Structure with which the Virtio Filesystem device reports a NodeId to the
 136 // FUSE client (i.e., to the Virtio Filesystem driver). This structure is a
 137 // part of the response headers for operations that inform the FUSE client of
 138 // an inode.
 139 //
 140 typedef struct {
 141   UINT64 NodeId;
 142   UINT64 Generation;
 143   UINT64 EntryValid;
 144   UINT64 AttrValid;
 145   UINT32 EntryValidNsec;
 146   UINT32 AttrValidNsec;
 147 } VIRTIO_FS_FUSE_NODE_RESPONSE;
 148
 149 //
 150 // Structure describing the host-side attributes of an inode. This structure is
 151 // a part of the response headers for operations that inform the FUSE client of
 152 // an inode.
 153 //
 154 typedef struct {
 155   UINT64 Ino;
 156   UINT64 Size;
 157   UINT64 Blocks;
 158   UINT64 Atime;
 159   UINT64 Mtime;
 160   UINT64 Ctime;
 161   UINT32 AtimeNsec;
 162   UINT32 MtimeNsec;
 163   UINT32 CtimeNsec;
 164   UINT32 Mode;
 165   UINT32 Nlink;
 166   UINT32 Uid;
 167   UINT32 Gid;
 168   UINT32 Rdev;
 169   UINT32 Blksize;
 170   UINT32 Padding;
 171 } VIRTIO_FS_FUSE_ATTRIBUTES_RESPONSE;
 172
 173 //
 174 // Header for VirtioFsFuseOpForget.
 175 //
 176 typedef struct {
 177   UINT64 NumberOfLookups;
 178 } VIRTIO_FS_FUSE_FORGET_REQUEST;
 179
 180 //
 181 // Header for VirtioFsFuseOpMkDir.
 182 //
 183 typedef struct {
 184   UINT32 Mode;
 185   UINT32 Umask;
 186 } VIRTIO_FS_FUSE_MKDIR_REQUEST;
 187
 188 //
 189 // Headers for VirtioFsFuseOpOpen and VirtioFsFuseOpOpenDir.
 190 //
 191 typedef struct {
 192   UINT32 Flags;
 193   UINT32 Unused;
 194 } VIRTIO_FS_FUSE_OPEN_REQUEST;
 195
 196 typedef struct {
 197   UINT64 FileHandle;
 198   UINT32 OpenFlags;
 199   UINT32 Padding;
 200 } VIRTIO_FS_FUSE_OPEN_RESPONSE;
 201
 202 //
 203 // Header for VirtioFsFuseOpRelease and VirtioFsFuseOpReleaseDir.
 204 //
 205 typedef struct {
 206   UINT64 FileHandle;
 207   UINT32 Flags;
 208   UINT32 ReleaseFlags;
 209   UINT64 LockOwner;
 210 } VIRTIO_FS_FUSE_RELEASE_REQUEST;
 211
 212 //
 213 // Header for VirtioFsFuseOpFsync and VirtioFsFuseOpFsyncDir.
 214 //
 215 typedef struct {
 216   UINT64 FileHandle;
 217   UINT32 FsyncFlags;
 218   UINT32 Padding;
 219 } VIRTIO_FS_FUSE_FSYNC_REQUEST;
 220
 221 //
 222 // Header for VirtioFsFuseOpFlush.
 223 //
 224 typedef struct {
 225   UINT64 FileHandle;
 226   UINT32 Unused;
 227   UINT32 Padding;
 228   UINT64 LockOwner;
 229 } VIRTIO_FS_FUSE_FLUSH_REQUEST;
 230
 231 //
 232 // Headers for VirtioFsFuseOpInit.
 233 //
 234 typedef struct {
 235   UINT32 Major;
 236   UINT32 Minor;
 237   UINT32 MaxReadahead;
 238   UINT32 Flags;
 239 } VIRTIO_FS_FUSE_INIT_REQUEST;
 240
 241 typedef struct {
 242   UINT32 Major;
 243   UINT32 Minor;
 244   UINT32 MaxReadahead;
 245   UINT32 Flags;
 246   UINT16 MaxBackground;
 247   UINT16 CongestionThreshold;
 248   UINT32 MaxWrite;
 249   UINT32 TimeGran;
 250   UINT16 MaxPages;
 251   UINT16 MapAlignment;
 252   UINT32 Unused[8];
 253 } VIRTIO_FS_FUSE_INIT_RESPONSE;
 254 #pragma pack ()
 255
 256 #endif // VIRTIO_FS_H_