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 // Flags for VirtioFsFuseOpOpen.
  86 //
  87 #define VIRTIO_FS_FUSE_OPEN_REQ_F_RDONLY 0
  88 #define VIRTIO_FS_FUSE_OPEN_REQ_F_RDWR   2
  89
  90 //
  91 // FUSE operation codes.
  92 //
  93 typedef enum {
  94   VirtioFsFuseOpForget      =  2,
  95   VirtioFsFuseOpOpen        = 14,
  96   VirtioFsFuseOpRelease     = 18,
  97   VirtioFsFuseOpFsync       = 20,
  98   VirtioFsFuseOpFlush       = 25,
  99   VirtioFsFuseOpInit        = 26,
 100   VirtioFsFuseOpOpenDir     = 27,
 101   VirtioFsFuseOpReleaseDir  = 29,
 102   VirtioFsFuseOpFsyncDir    = 30,
 103 } VIRTIO_FS_FUSE_OPCODE;
 104
 105 #pragma pack (1)
 106 //
 107 // Request-response headers common to all request types.
 108 //
 109 typedef struct {
 110   UINT32 Len;
 111   UINT32 Opcode;
 112   UINT64 Unique;
 113   UINT64 NodeId;
 114   UINT32 Uid;
 115   UINT32 Gid;
 116   UINT32 Pid;
 117   UINT32 Padding;
 118 } VIRTIO_FS_FUSE_REQUEST;
 119
 120 typedef struct {
 121   UINT32 Len;
 122   INT32  Error;
 123   UINT64 Unique;
 124 } VIRTIO_FS_FUSE_RESPONSE;
 125
 126 //
 127 // Header for VirtioFsFuseOpForget.
 128 //
 129 typedef struct {
 130   UINT64 NumberOfLookups;
 131 } VIRTIO_FS_FUSE_FORGET_REQUEST;
 132
 133 //
 134 // Headers for VirtioFsFuseOpOpen and VirtioFsFuseOpOpenDir.
 135 //
 136 typedef struct {
 137   UINT32 Flags;
 138   UINT32 Unused;
 139 } VIRTIO_FS_FUSE_OPEN_REQUEST;
 140
 141 typedef struct {
 142   UINT64 FileHandle;
 143   UINT32 OpenFlags;
 144   UINT32 Padding;
 145 } VIRTIO_FS_FUSE_OPEN_RESPONSE;
 146
 147 //
 148 // Header for VirtioFsFuseOpRelease and VirtioFsFuseOpReleaseDir.
 149 //
 150 typedef struct {
 151   UINT64 FileHandle;
 152   UINT32 Flags;
 153   UINT32 ReleaseFlags;
 154   UINT64 LockOwner;
 155 } VIRTIO_FS_FUSE_RELEASE_REQUEST;
 156
 157 //
 158 // Header for VirtioFsFuseOpFsync and VirtioFsFuseOpFsyncDir.
 159 //
 160 typedef struct {
 161   UINT64 FileHandle;
 162   UINT32 FsyncFlags;
 163   UINT32 Padding;
 164 } VIRTIO_FS_FUSE_FSYNC_REQUEST;
 165
 166 //
 167 // Header for VirtioFsFuseOpFlush.
 168 //
 169 typedef struct {
 170   UINT64 FileHandle;
 171   UINT32 Unused;
 172   UINT32 Padding;
 173   UINT64 LockOwner;
 174 } VIRTIO_FS_FUSE_FLUSH_REQUEST;
 175
 176 //
 177 // Headers for VirtioFsFuseOpInit.
 178 //
 179 typedef struct {
 180   UINT32 Major;
 181   UINT32 Minor;
 182   UINT32 MaxReadahead;
 183   UINT32 Flags;
 184 } VIRTIO_FS_FUSE_INIT_REQUEST;
 185
 186 typedef struct {
 187   UINT32 Major;
 188   UINT32 Minor;
 189   UINT32 MaxReadahead;
 190   UINT32 Flags;
 191   UINT16 MaxBackground;
 192   UINT16 CongestionThreshold;
 193   UINT32 MaxWrite;
 194   UINT32 TimeGran;
 195   UINT16 MaxPages;
 196   UINT16 MapAlignment;
 197   UINT32 Unused[8];
 198 } VIRTIO_FS_FUSE_INIT_RESPONSE;
 199 #pragma pack ()
 200
 201 #endif // VIRTIO_FS_H_