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