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 // Distinguished errno values.
  86 //
  87 #define VIRTIO_FS_FUSE_ERRNO_ENOENT (-2)
  88
  89 //
  90 // File mode bitmasks.
  91 //
  92 #define VIRTIO_FS_FUSE_MODE_TYPE_MASK 0170000u
  93 #define VIRTIO_FS_FUSE_MODE_TYPE_REG  0100000u
  94 #define VIRTIO_FS_FUSE_MODE_TYPE_DIR  0040000u
  95 #define VIRTIO_FS_FUSE_MODE_PERM_RWXU 0000700u
  96 #define VIRTIO_FS_FUSE_MODE_PERM_RUSR 0000400u
  97 #define VIRTIO_FS_FUSE_MODE_PERM_WUSR 0000200u
  98 #define VIRTIO_FS_FUSE_MODE_PERM_RWXG 0000070u
  99 #define VIRTIO_FS_FUSE_MODE_PERM_RGRP 0000040u
 100 #define VIRTIO_FS_FUSE_MODE_PERM_WGRP 0000020u
 101 #define VIRTIO_FS_FUSE_MODE_PERM_RWXO 0000007u
 102 #define VIRTIO_FS_FUSE_MODE_PERM_ROTH 0000004u
 103 #define VIRTIO_FS_FUSE_MODE_PERM_WOTH 0000002u
 104
 105 //
 106 // Flags for VirtioFsFuseOpOpen.
 107 //
 108 #define VIRTIO_FS_FUSE_OPEN_REQ_F_RDONLY 0
 109 #define VIRTIO_FS_FUSE_OPEN_REQ_F_RDWR   2
 110
 111 //
 112 // FUSE operation codes.
 113 //
 114 typedef enum {
 115   VirtioFsFuseOpLookup      =  1,
 116   VirtioFsFuseOpForget      =  2,
 117   VirtioFsFuseOpGetAttr     =  3,
 118   VirtioFsFuseOpMkDir       =  9,
 119   VirtioFsFuseOpUnlink      = 10,
 120   VirtioFsFuseOpRmDir       = 11,
 121   VirtioFsFuseOpOpen        = 14,
 122   VirtioFsFuseOpStatFs      = 17,
 123   VirtioFsFuseOpRelease     = 18,
 124   VirtioFsFuseOpFsync       = 20,
 125   VirtioFsFuseOpFlush       = 25,
 126   VirtioFsFuseOpInit        = 26,
 127   VirtioFsFuseOpOpenDir     = 27,
 128   VirtioFsFuseOpReleaseDir  = 29,
 129   VirtioFsFuseOpFsyncDir    = 30,
 130   VirtioFsFuseOpCreate      = 35,
 131 } VIRTIO_FS_FUSE_OPCODE;
 132
 133 #pragma pack (1)
 134 //
 135 // Request-response headers common to all request types.
 136 //
 137 typedef struct {
 138   UINT32 Len;
 139   UINT32 Opcode;
 140   UINT64 Unique;
 141   UINT64 NodeId;
 142   UINT32 Uid;
 143   UINT32 Gid;
 144   UINT32 Pid;
 145   UINT32 Padding;
 146 } VIRTIO_FS_FUSE_REQUEST;
 147
 148 typedef struct {
 149   UINT32 Len;
 150   INT32  Error;
 151   UINT64 Unique;
 152 } VIRTIO_FS_FUSE_RESPONSE;
 153
 154 //
 155 // Structure with which the Virtio Filesystem device reports a NodeId to the
 156 // FUSE client (i.e., to the Virtio Filesystem driver). This structure is a
 157 // part of the response headers for operations that inform the FUSE client of
 158 // an inode.
 159 //
 160 typedef struct {
 161   UINT64 NodeId;
 162   UINT64 Generation;
 163   UINT64 EntryValid;
 164   UINT64 AttrValid;
 165   UINT32 EntryValidNsec;
 166   UINT32 AttrValidNsec;
 167 } VIRTIO_FS_FUSE_NODE_RESPONSE;
 168
 169 //
 170 // Structure describing the host-side attributes of an inode. This structure is
 171 // a part of the response headers for operations that inform the FUSE client of
 172 // an inode.
 173 //
 174 typedef struct {
 175   UINT64 Ino;
 176   UINT64 Size;
 177   UINT64 Blocks;
 178   UINT64 Atime;
 179   UINT64 Mtime;
 180   UINT64 Ctime;
 181   UINT32 AtimeNsec;
 182   UINT32 MtimeNsec;
 183   UINT32 CtimeNsec;
 184   UINT32 Mode;
 185   UINT32 Nlink;
 186   UINT32 Uid;
 187   UINT32 Gid;
 188   UINT32 Rdev;
 189   UINT32 Blksize;
 190   UINT32 Padding;
 191 } VIRTIO_FS_FUSE_ATTRIBUTES_RESPONSE;
 192
 193 //
 194 // Header for VirtioFsFuseOpForget.
 195 //
 196 typedef struct {
 197   UINT64 NumberOfLookups;
 198 } VIRTIO_FS_FUSE_FORGET_REQUEST;
 199
 200 //
 201 // Headers for VirtioFsFuseOpGetAttr.
 202 //
 203 typedef struct {
 204   UINT32 GetAttrFlags;
 205   UINT32 Dummy;
 206   UINT64 FileHandle;
 207 } VIRTIO_FS_FUSE_GETATTR_REQUEST;
 208
 209 typedef struct {
 210   UINT64 AttrValid;
 211   UINT32 AttrValidNsec;
 212   UINT32 Dummy;
 213 } VIRTIO_FS_FUSE_GETATTR_RESPONSE;
 214
 215 //
 216 // Header for VirtioFsFuseOpMkDir.
 217 //
 218 typedef struct {
 219   UINT32 Mode;
 220   UINT32 Umask;
 221 } VIRTIO_FS_FUSE_MKDIR_REQUEST;
 222
 223 //
 224 // Headers for VirtioFsFuseOpOpen and VirtioFsFuseOpOpenDir.
 225 //
 226 typedef struct {
 227   UINT32 Flags;
 228   UINT32 Unused;
 229 } VIRTIO_FS_FUSE_OPEN_REQUEST;
 230
 231 typedef struct {
 232   UINT64 FileHandle;
 233   UINT32 OpenFlags;
 234   UINT32 Padding;
 235 } VIRTIO_FS_FUSE_OPEN_RESPONSE;
 236
 237 //
 238 // Header for VirtioFsFuseOpStatFs.
 239 //
 240 typedef struct {
 241   UINT64 Blocks;
 242   UINT64 Bfree;
 243   UINT64 Bavail;
 244   UINT64 Files;
 245   UINT64 Ffree;
 246   UINT32 Bsize;
 247   UINT32 Namelen;
 248   UINT32 Frsize;
 249   UINT32 Padding;
 250   UINT32 Spare[6];
 251 } VIRTIO_FS_FUSE_STATFS_RESPONSE;
 252
 253 //
 254 // Header for VirtioFsFuseOpRelease and VirtioFsFuseOpReleaseDir.
 255 //
 256 typedef struct {
 257   UINT64 FileHandle;
 258   UINT32 Flags;
 259   UINT32 ReleaseFlags;
 260   UINT64 LockOwner;
 261 } VIRTIO_FS_FUSE_RELEASE_REQUEST;
 262
 263 //
 264 // Header for VirtioFsFuseOpFsync and VirtioFsFuseOpFsyncDir.
 265 //
 266 typedef struct {
 267   UINT64 FileHandle;
 268   UINT32 FsyncFlags;
 269   UINT32 Padding;
 270 } VIRTIO_FS_FUSE_FSYNC_REQUEST;
 271
 272 //
 273 // Header for VirtioFsFuseOpFlush.
 274 //
 275 typedef struct {
 276   UINT64 FileHandle;
 277   UINT32 Unused;
 278   UINT32 Padding;
 279   UINT64 LockOwner;
 280 } VIRTIO_FS_FUSE_FLUSH_REQUEST;
 281
 282 //
 283 // Headers for VirtioFsFuseOpInit.
 284 //
 285 typedef struct {
 286   UINT32 Major;
 287   UINT32 Minor;
 288   UINT32 MaxReadahead;
 289   UINT32 Flags;
 290 } VIRTIO_FS_FUSE_INIT_REQUEST;
 291
 292 typedef struct {
 293   UINT32 Major;
 294   UINT32 Minor;
 295   UINT32 MaxReadahead;
 296   UINT32 Flags;
 297   UINT16 MaxBackground;
 298   UINT16 CongestionThreshold;
 299   UINT32 MaxWrite;
 300   UINT32 TimeGran;
 301   UINT16 MaxPages;
 302   UINT16 MapAlignment;
 303   UINT32 Unused[8];
 304 } VIRTIO_FS_FUSE_INIT_RESPONSE;
 305
 306 //
 307 // Header for VirtioFsFuseOpCreate.
 308 //
 309 typedef struct {
 310   UINT32 Flags;
 311   UINT32 Mode;
 312   UINT32 Umask;
 313   UINT32 Padding;
 314 } VIRTIO_FS_FUSE_CREATE_REQUEST;
 315 #pragma pack ()
 316
 317 #endif // VIRTIO_FS_H_