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