OvmfPkg/VirtioFsDxe/VirtioFsDxe.h

   1 /** @file
   2   Internal macro definitions, type definitions, and function declarations for
   3   the Virtio Filesystem device driver.
   4
   5   Copyright (C) 2020, Red Hat, Inc.
   6
   7   SPDX-License-Identifier: BSD-2-Clause-Patent
   8 **/
   9
  10 #ifndef VIRTIO_FS_DXE_H_
  11 #define VIRTIO_FS_DXE_H_
  12
  13 #include <Base.h>                      // SIGNATURE_64()
  14 #include <IndustryStandard/VirtioFs.h> // VIRTIO_FS_TAG_BYTES
  15 #include <Library/DebugLib.h>          // CR()
  16 #include <Protocol/SimpleFileSystem.h> // EFI_SIMPLE_FILE_SYSTEM_PROTOCOL
  17 #include <Protocol/VirtioDevice.h>     // VIRTIO_DEVICE_PROTOCOL
  18 #include <Uefi/UefiBaseType.h>         // EFI_EVENT
  19
  20 #define VIRTIO_FS_SIG SIGNATURE_64 ('V', 'I', 'R', 'T', 'I', 'O', 'F', 'S')
  21
  22 #define VIRTIO_FS_FILE_SIG \
  23   SIGNATURE_64 ('V', 'I', 'O', 'F', 'S', 'F', 'I', 'L')
  24
  25 //
  26 // Filesystem label encoded in UCS-2, transformed from the UTF-8 representation
  27 // in "VIRTIO_FS_CONFIG.Tag", and NUL-terminated. Only the printable ASCII code
  28 // points (U+0020 through U+007E) are supported.
  29 //
  30 typedef CHAR16 VIRTIO_FS_LABEL[VIRTIO_FS_TAG_BYTES + 1];
  31
  32 //
  33 // Main context structure, expressing an EFI_SIMPLE_FILE_SYSTEM_PROTOCOL
  34 // interface on top of the Virtio Filesystem device.
  35 //
  36 typedef struct {
  37   //
  38   // Parts of this structure are initialized / torn down in various functions
  39   // at various call depths. The table to the right should make it easier to
  40   // track them.
  41   //
  42   //                              field         init function       init depth
  43   //                              -----------   ------------------  ----------
  44   UINT64                          Signature; // DriverBindingStart  0
  45   VIRTIO_DEVICE_PROTOCOL          *Virtio;   // DriverBindingStart  0
  46   VIRTIO_FS_LABEL                 Label;     // VirtioFsInit        1
  47   UINT16                          QueueSize; // VirtioFsInit        1
  48   VRING                           Ring;      // VirtioRingInit      2
  49   VOID                            *RingMap;  // VirtioRingMap       2
  50   UINT64                          RequestId; // FuseInitSession     1
  51   EFI_EVENT                       ExitBoot;  // DriverBindingStart  0
  52   LIST_ENTRY                      OpenFiles; // DriverBindingStart  0
  53   EFI_SIMPLE_FILE_SYSTEM_PROTOCOL SimpleFs;  // DriverBindingStart  0
  54 } VIRTIO_FS;
  55
  56 #define VIRTIO_FS_FROM_SIMPLE_FS(SimpleFsReference) \
  57   CR (SimpleFsReference, VIRTIO_FS, SimpleFs, VIRTIO_FS_SIG);
  58
  59 //
  60 // Structure for describing a contiguous buffer, potentially mapped for Virtio
  61 // transfer.
  62 //
  63 typedef struct {
  64   //
  65   // The following fields originate from the owner of the buffer.
  66   //
  67   VOID  *Buffer;
  68   UINTN Size;
  69   //
  70   // All of the fields below, until the end of the structure, are
  71   // zero-initialized when the structure is initially validated.
  72   //
  73   // Mapped, MappedAddress and Mapping are updated when the buffer is mapped
  74   // for VirtioOperationBusMasterRead or VirtioOperationBusMasterWrite. They
  75   // are again updated when the buffer is unmapped.
  76   //
  77   BOOLEAN              Mapped;
  78   EFI_PHYSICAL_ADDRESS MappedAddress;
  79   VOID                 *Mapping;
  80   //
  81   // Transferred is updated after VirtioFlush() returns successfully:
  82   // - for VirtioOperationBusMasterRead, Transferred is set to Size;
  83   // - for VirtioOperationBusMasterWrite, Transferred is calculated from the
  84   //   UsedLen output parameter of VirtioFlush().
  85   //
  86   UINTN Transferred;
  87 } VIRTIO_FS_IO_VECTOR;
  88
  89 //
  90 // Structure for describing a list of IO Vectors.
  91 //
  92 typedef struct {
  93   //
  94   // The following fields originate from the owner of the buffers.
  95   //
  96   VIRTIO_FS_IO_VECTOR *IoVec;
  97   UINTN               NumVec;
  98   //
  99   // TotalSize is calculated when the scatter-gather list is initially
 100   // validated.
 101   //
 102   UINT32 TotalSize;
 103 } VIRTIO_FS_SCATTER_GATHER_LIST;
 104
 105 //
 106 // Private context structure that exposes EFI_FILE_PROTOCOL on top of an open
 107 // FUSE file reference.
 108 //
 109 typedef struct {
 110   UINT64            Signature;
 111   EFI_FILE_PROTOCOL SimpleFile;
 112   BOOLEAN           IsDirectory;
 113   VIRTIO_FS         *OwnerFs;
 114   LIST_ENTRY        OpenFilesEntry;
 115   //
 116   // In the FUSE wire protocol, every request except FUSE_INIT refers to a
 117   // file, namely by the "VIRTIO_FS_FUSE_REQUEST.NodeId" field; that is, by the
 118   // inode number of the file. However, some of the FUSE requests that we need
 119   // for some of the EFI_FILE_PROTOCOL member functions require an open file
 120   // handle *in addition* to the inode number. For simplicity, whenever a
 121   // VIRTIO_FS_FILE object is created, primarily defined by its NodeId field,
 122   // we also *open* the referenced file at once, and save the returned file
 123   // handle in the FuseHandle field. This way, when an EFI_FILE_PROTOCOL member
 124   // function must send a FUSE request that needs the file handle *in addition*
 125   // to the inode number, FuseHandle will be at our disposal at once.
 126   //
 127   UINT64 NodeId;
 128   UINT64 FuseHandle;
 129 } VIRTIO_FS_FILE;
 130
 131 #define VIRTIO_FS_FILE_FROM_SIMPLE_FILE(SimpleFileReference) \
 132   CR (SimpleFileReference, VIRTIO_FS_FILE, SimpleFile, VIRTIO_FS_FILE_SIG);
 133
 134 #define VIRTIO_FS_FILE_FROM_OPEN_FILES_ENTRY(OpenFilesEntryReference) \
 135   CR (OpenFilesEntryReference, VIRTIO_FS_FILE, OpenFilesEntry, \
 136     VIRTIO_FS_FILE_SIG);
 137
 138 //
 139 // Initialization and helper routines for the Virtio Filesystem device.
 140 //
 141
 142 EFI_STATUS
 143 VirtioFsInit (
 144   IN OUT VIRTIO_FS *VirtioFs
 145   );
 146
 147 VOID
 148 VirtioFsUninit (
 149   IN OUT VIRTIO_FS *VirtioFs
 150   );
 151
 152 VOID
 153 EFIAPI
 154 VirtioFsExitBoot (
 155   IN EFI_EVENT ExitBootEvent,
 156   IN VOID      *VirtioFsAsVoid
 157   );
 158
 159 EFI_STATUS
 160 VirtioFsSgListsValidate (
 161   IN     VIRTIO_FS                     *VirtioFs,
 162   IN OUT VIRTIO_FS_SCATTER_GATHER_LIST *RequestSgList,
 163   IN OUT VIRTIO_FS_SCATTER_GATHER_LIST *ResponseSgList OPTIONAL
 164   );
 165
 166 EFI_STATUS
 167 VirtioFsSgListsSubmit (
 168   IN OUT VIRTIO_FS                     *VirtioFs,
 169   IN OUT VIRTIO_FS_SCATTER_GATHER_LIST *RequestSgList,
 170   IN OUT VIRTIO_FS_SCATTER_GATHER_LIST *ResponseSgList OPTIONAL
 171   );
 172
 173 EFI_STATUS
 174 VirtioFsFuseNewRequest (
 175   IN OUT VIRTIO_FS              *VirtioFs,
 176      OUT VIRTIO_FS_FUSE_REQUEST *Request,
 177   IN     UINT32                 RequestSize,
 178   IN     VIRTIO_FS_FUSE_OPCODE  Opcode,
 179   IN     UINT64                 NodeId
 180   );
 181
 182 EFI_STATUS
 183 VirtioFsFuseCheckResponse (
 184   IN  VIRTIO_FS_SCATTER_GATHER_LIST *ResponseSgList,
 185   IN  UINT64                        RequestId,
 186   OUT UINTN                         *TailBufferFill
 187   );
 188
 189 EFI_STATUS
 190 VirtioFsErrnoToEfiStatus (
 191   IN INT32 Errno
 192   );
 193
 194 //
 195 // Wrapper functions for FUSE commands (primitives).
 196 //
 197
 198 EFI_STATUS
 199 VirtioFsFuseForget (
 200   IN OUT VIRTIO_FS *VirtioFs,
 201   IN     UINT64    NodeId
 202   );
 203
 204 EFI_STATUS
 205 VirtioFsFuseReleaseFileOrDir (
 206   IN OUT VIRTIO_FS *VirtioFs,
 207   IN     UINT64    NodeId,
 208   IN     UINT64    FuseHandle,
 209   IN     BOOLEAN   IsDir
 210   );
 211
 212 EFI_STATUS
 213 VirtioFsFuseFsyncFileOrDir (
 214   IN OUT VIRTIO_FS *VirtioFs,
 215   IN     UINT64    NodeId,
 216   IN     UINT64    FuseHandle,
 217   IN     BOOLEAN   IsDir
 218   );
 219
 220 EFI_STATUS
 221 VirtioFsFuseInitSession (
 222   IN OUT VIRTIO_FS *VirtioFs
 223   );
 224
 225 EFI_STATUS
 226 VirtioFsFuseOpenDir (
 227   IN OUT VIRTIO_FS *VirtioFs,
 228   IN     UINT64    NodeId,
 229      OUT UINT64    *FuseHandle
 230   );
 231
 232 //
 233 // EFI_SIMPLE_FILE_SYSTEM_PROTOCOL member functions for the Virtio Filesystem
 234 // driver.
 235 //
 236
 237 EFI_STATUS
 238 EFIAPI
 239 VirtioFsOpenVolume (
 240   IN  EFI_SIMPLE_FILE_SYSTEM_PROTOCOL *This,
 241   OUT EFI_FILE_PROTOCOL               **Root
 242   );
 243
 244 //
 245 // EFI_FILE_PROTOCOL member functions for the Virtio Filesystem driver.
 246 //
 247
 248 EFI_STATUS
 249 EFIAPI
 250 VirtioFsSimpleFileClose (
 251   IN EFI_FILE_PROTOCOL *This
 252   );
 253
 254 EFI_STATUS
 255 EFIAPI
 256 VirtioFsSimpleFileDelete (
 257   IN EFI_FILE_PROTOCOL *This
 258   );
 259
 260 EFI_STATUS
 261 EFIAPI
 262 VirtioFsSimpleFileFlush (
 263   IN EFI_FILE_PROTOCOL *This
 264   );
 265
 266 EFI_STATUS
 267 EFIAPI
 268 VirtioFsSimpleFileGetInfo (
 269   IN     EFI_FILE_PROTOCOL *This,
 270   IN     EFI_GUID          *InformationType,
 271   IN OUT UINTN             *BufferSize,
 272      OUT VOID              *Buffer
 273   );
 274
 275 EFI_STATUS
 276 EFIAPI
 277 VirtioFsSimpleFileGetPosition (
 278   IN     EFI_FILE_PROTOCOL *This,
 279      OUT UINT64            *Position
 280   );
 281
 282 EFI_STATUS
 283 EFIAPI
 284 VirtioFsSimpleFileOpen (
 285   IN     EFI_FILE_PROTOCOL *This,
 286      OUT EFI_FILE_PROTOCOL **NewHandle,
 287   IN     CHAR16            *FileName,
 288   IN     UINT64            OpenMode,
 289   IN     UINT64            Attributes
 290   );
 291
 292 EFI_STATUS
 293 EFIAPI
 294 VirtioFsSimpleFileRead (
 295   IN     EFI_FILE_PROTOCOL *This,
 296   IN OUT UINTN             *BufferSize,
 297      OUT VOID              *Buffer
 298   );
 299
 300 EFI_STATUS
 301 EFIAPI
 302 VirtioFsSimpleFileSetInfo (
 303   IN EFI_FILE_PROTOCOL *This,
 304   IN EFI_GUID          *InformationType,
 305   IN UINTN             BufferSize,
 306   IN VOID              *Buffer
 307   );
 308
 309 EFI_STATUS
 310 EFIAPI
 311 VirtioFsSimpleFileSetPosition (
 312   IN EFI_FILE_PROTOCOL *This,
 313   IN UINT64            Position
 314   );
 315
 316 EFI_STATUS
 317 EFIAPI
 318 VirtioFsSimpleFileWrite (
 319   IN     EFI_FILE_PROTOCOL *This,
 320   IN OUT UINTN             *BufferSize,
 321   IN     VOID              *Buffer
 322   );
 323
 324 #endif // VIRTIO_FS_DXE_H_