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 <Guid/FileInfo.h>             // EFI_FILE_INFO
  15 #include <IndustryStandard/VirtioFs.h> // VIRTIO_FS_TAG_BYTES
  16 #include <Library/DebugLib.h>          // CR()
  17 #include <Protocol/SimpleFileSystem.h> // EFI_SIMPLE_FILE_SYSTEM_PROTOCOL
  18 #include <Protocol/VirtioDevice.h>     // VIRTIO_DEVICE_PROTOCOL
  19 #include <Uefi/UefiBaseType.h>         // EFI_EVENT
  20
  21 #define VIRTIO_FS_SIG SIGNATURE_64 ('V', 'I', 'R', 'T', 'I', 'O', 'F', 'S')
  22
  23 #define VIRTIO_FS_FILE_SIG \
  24   SIGNATURE_64 ('V', 'I', 'O', 'F', 'S', 'F', 'I', 'L')
  25
  26 //
  27 // The following limit applies to two kinds of pathnames.
  28 //
  29 // - The length of a POSIX-style, canonical pathname *at rest* never exceeds
  30 //   VIRTIO_FS_MAX_PATHNAME_LENGTH. (Length is defined as the number of CHAR8
  31 //   elements in the canonical pathname, excluding the terminating '\0'.) This
  32 //   is an invariant that is ensured for canonical pathnames created, and that
  33 //   is assumed about canonical pathname inputs (which all originate
  34 //   internally).
  35 //
  36 // - If the length of a UEFI-style pathname *argument*, originating directly or
  37 //   indirectly from the EFI_FILE_PROTOCOL caller, exceeds
  38 //   VIRTIO_FS_MAX_PATHNAME_LENGTH, then the argument is rejected. (Length is
  39 //   defined as the number of CHAR16 elements in the UEFI-style pathname,
  40 //   excluding the terminating L'\0'.) This is a restriction that's checked on
  41 //   external UEFI-style pathname inputs.
  42 //
  43 // The limit is not expected to be a practical limitation; it's only supposed
  44 // to prevent attempts at overflowing size calculations. For both kinds of
  45 // pathnames, separate limits could be used; a common limit is used purely for
  46 // simplicity.
  47 //
  48 #define VIRTIO_FS_MAX_PATHNAME_LENGTH ((UINTN)65535)
  49
  50 //
  51 // Filesystem label encoded in UCS-2, transformed from the UTF-8 representation
  52 // in "VIRTIO_FS_CONFIG.Tag", and NUL-terminated. Only the printable ASCII code
  53 // points (U+0020 through U+007E) are supported.
  54 //
  55 typedef CHAR16 VIRTIO_FS_LABEL[VIRTIO_FS_TAG_BYTES + 1];
  56
  57 //
  58 // Main context structure, expressing an EFI_SIMPLE_FILE_SYSTEM_PROTOCOL
  59 // interface on top of the Virtio Filesystem device.
  60 //
  61 typedef struct {
  62   //
  63   // Parts of this structure are initialized / torn down in various functions
  64   // at various call depths. The table to the right should make it easier to
  65   // track them.
  66   //
  67   //                              field         init function       init depth
  68   //                              -----------   ------------------  ----------
  69   UINT64                          Signature; // DriverBindingStart  0
  70   VIRTIO_DEVICE_PROTOCOL          *Virtio;   // DriverBindingStart  0
  71   VIRTIO_FS_LABEL                 Label;     // VirtioFsInit        1
  72   UINT16                          QueueSize; // VirtioFsInit        1
  73   VRING                           Ring;      // VirtioRingInit      2
  74   VOID                            *RingMap;  // VirtioRingMap       2
  75   UINT64                          RequestId; // FuseInitSession     1
  76   EFI_EVENT                       ExitBoot;  // DriverBindingStart  0
  77   LIST_ENTRY                      OpenFiles; // DriverBindingStart  0
  78   EFI_SIMPLE_FILE_SYSTEM_PROTOCOL SimpleFs;  // DriverBindingStart  0
  79 } VIRTIO_FS;
  80
  81 #define VIRTIO_FS_FROM_SIMPLE_FS(SimpleFsReference) \
  82   CR (SimpleFsReference, VIRTIO_FS, SimpleFs, VIRTIO_FS_SIG);
  83
  84 //
  85 // Structure for describing a contiguous buffer, potentially mapped for Virtio
  86 // transfer.
  87 //
  88 typedef struct {
  89   //
  90   // The following fields originate from the owner of the buffer.
  91   //
  92   VOID  *Buffer;
  93   UINTN Size;
  94   //
  95   // All of the fields below, until the end of the structure, are
  96   // zero-initialized when the structure is initially validated.
  97   //
  98   // Mapped, MappedAddress and Mapping are updated when the buffer is mapped
  99   // for VirtioOperationBusMasterRead or VirtioOperationBusMasterWrite. They
 100   // are again updated when the buffer is unmapped.
 101   //
 102   BOOLEAN              Mapped;
 103   EFI_PHYSICAL_ADDRESS MappedAddress;
 104   VOID                 *Mapping;
 105   //
 106   // Transferred is updated after VirtioFlush() returns successfully:
 107   // - for VirtioOperationBusMasterRead, Transferred is set to Size;
 108   // - for VirtioOperationBusMasterWrite, Transferred is calculated from the
 109   //   UsedLen output parameter of VirtioFlush().
 110   //
 111   UINTN Transferred;
 112 } VIRTIO_FS_IO_VECTOR;
 113
 114 //
 115 // Structure for describing a list of IO Vectors.
 116 //
 117 typedef struct {
 118   //
 119   // The following fields originate from the owner of the buffers.
 120   //
 121   VIRTIO_FS_IO_VECTOR *IoVec;
 122   UINTN               NumVec;
 123   //
 124   // TotalSize is calculated when the scatter-gather list is initially
 125   // validated.
 126   //
 127   UINT32 TotalSize;
 128 } VIRTIO_FS_SCATTER_GATHER_LIST;
 129
 130 //
 131 // Private context structure that exposes EFI_FILE_PROTOCOL on top of an open
 132 // FUSE file reference.
 133 //
 134 typedef struct {
 135   UINT64            Signature;
 136   EFI_FILE_PROTOCOL SimpleFile;
 137   BOOLEAN           IsDirectory;
 138   BOOLEAN           IsOpenForWriting;
 139   VIRTIO_FS         *OwnerFs;
 140   LIST_ENTRY        OpenFilesEntry;
 141   CHAR8             *CanonicalPathname;
 142   UINT64            FilePosition;
 143   //
 144   // In the FUSE wire protocol, every request except FUSE_INIT refers to a
 145   // file, namely by the "VIRTIO_FS_FUSE_REQUEST.NodeId" field; that is, by the
 146   // inode number of the file. However, some of the FUSE requests that we need
 147   // for some of the EFI_FILE_PROTOCOL member functions require an open file
 148   // handle *in addition* to the inode number. For simplicity, whenever a
 149   // VIRTIO_FS_FILE object is created, primarily defined by its NodeId field,
 150   // we also *open* the referenced file at once, and save the returned file
 151   // handle in the FuseHandle field. This way, when an EFI_FILE_PROTOCOL member
 152   // function must send a FUSE request that needs the file handle *in addition*
 153   // to the inode number, FuseHandle will be at our disposal at once.
 154   //
 155   UINT64 NodeId;
 156   UINT64 FuseHandle;
 157 } VIRTIO_FS_FILE;
 158
 159 #define VIRTIO_FS_FILE_FROM_SIMPLE_FILE(SimpleFileReference) \
 160   CR (SimpleFileReference, VIRTIO_FS_FILE, SimpleFile, VIRTIO_FS_FILE_SIG);
 161
 162 #define VIRTIO_FS_FILE_FROM_OPEN_FILES_ENTRY(OpenFilesEntryReference) \
 163   CR (OpenFilesEntryReference, VIRTIO_FS_FILE, OpenFilesEntry, \
 164     VIRTIO_FS_FILE_SIG);
 165
 166 //
 167 // Initialization and helper routines for the Virtio Filesystem device.
 168 //
 169
 170 EFI_STATUS
 171 VirtioFsInit (
 172   IN OUT VIRTIO_FS *VirtioFs
 173   );
 174
 175 VOID
 176 VirtioFsUninit (
 177   IN OUT VIRTIO_FS *VirtioFs
 178   );
 179
 180 VOID
 181 EFIAPI
 182 VirtioFsExitBoot (
 183   IN EFI_EVENT ExitBootEvent,
 184   IN VOID      *VirtioFsAsVoid
 185   );
 186
 187 EFI_STATUS
 188 VirtioFsSgListsValidate (
 189   IN     VIRTIO_FS                     *VirtioFs,
 190   IN OUT VIRTIO_FS_SCATTER_GATHER_LIST *RequestSgList,
 191   IN OUT VIRTIO_FS_SCATTER_GATHER_LIST *ResponseSgList OPTIONAL
 192   );
 193
 194 EFI_STATUS
 195 VirtioFsSgListsSubmit (
 196   IN OUT VIRTIO_FS                     *VirtioFs,
 197   IN OUT VIRTIO_FS_SCATTER_GATHER_LIST *RequestSgList,
 198   IN OUT VIRTIO_FS_SCATTER_GATHER_LIST *ResponseSgList OPTIONAL
 199   );
 200
 201 EFI_STATUS
 202 VirtioFsFuseNewRequest (
 203   IN OUT VIRTIO_FS              *VirtioFs,
 204      OUT VIRTIO_FS_FUSE_REQUEST *Request,
 205   IN     UINT32                 RequestSize,
 206   IN     VIRTIO_FS_FUSE_OPCODE  Opcode,
 207   IN     UINT64                 NodeId
 208   );
 209
 210 EFI_STATUS
 211 VirtioFsFuseCheckResponse (
 212   IN  VIRTIO_FS_SCATTER_GATHER_LIST *ResponseSgList,
 213   IN  UINT64                        RequestId,
 214   OUT UINTN                         *TailBufferFill
 215   );
 216
 217 EFI_STATUS
 218 VirtioFsErrnoToEfiStatus (
 219   IN INT32 Errno
 220   );
 221
 222 EFI_STATUS
 223 VirtioFsAppendPath (
 224   IN     CHAR8   *LhsPath8,
 225   IN     CHAR16  *RhsPath16,
 226      OUT CHAR8   **ResultPath8,
 227      OUT BOOLEAN *RootEscape
 228   );
 229
 230 EFI_STATUS
 231 VirtioFsLookupMostSpecificParentDir (
 232   IN OUT VIRTIO_FS *VirtioFs,
 233   IN OUT CHAR8     *Path,
 234      OUT UINT64    *DirNodeId,
 235      OUT CHAR8     **LastComponent
 236   );
 237
 238 EFI_STATUS
 239 VirtioFsGetBasename (
 240   IN     CHAR8  *Path,
 241      OUT CHAR16 *Basename     OPTIONAL,
 242   IN OUT UINTN  *BasenameSize
 243   );
 244
 245 EFI_STATUS
 246 VirtioFsFuseAttrToEfiFileInfo (
 247   IN     VIRTIO_FS_FUSE_ATTRIBUTES_RESPONSE *FuseAttr,
 248      OUT EFI_FILE_INFO                      *FileInfo
 249   );
 250
 251 EFI_STATUS
 252 VirtioFsFuseDirentPlusToEfiFileInfo (
 253   IN     VIRTIO_FS_FUSE_DIRENTPLUS_RESPONSE *FuseDirent,
 254   IN OUT EFI_FILE_INFO                      *FileInfo
 255   );
 256
 257 //
 258 // Wrapper functions for FUSE commands (primitives).
 259 //
 260
 261 EFI_STATUS
 262 VirtioFsFuseLookup (
 263   IN OUT VIRTIO_FS                          *VirtioFs,
 264   IN     UINT64                             DirNodeId,
 265   IN     CHAR8                              *Name,
 266      OUT UINT64                             *NodeId,
 267      OUT VIRTIO_FS_FUSE_ATTRIBUTES_RESPONSE *FuseAttr
 268   );
 269
 270 EFI_STATUS
 271 VirtioFsFuseForget (
 272   IN OUT VIRTIO_FS *VirtioFs,
 273   IN     UINT64    NodeId
 274   );
 275
 276 EFI_STATUS
 277 VirtioFsFuseGetAttr (
 278   IN OUT VIRTIO_FS                          *VirtioFs,
 279   IN     UINT64                             NodeId,
 280      OUT VIRTIO_FS_FUSE_ATTRIBUTES_RESPONSE *FuseAttr
 281   );
 282
 283 EFI_STATUS
 284 VirtioFsFuseMkDir (
 285   IN OUT VIRTIO_FS *VirtioFs,
 286   IN     UINT64    ParentNodeId,
 287   IN     CHAR8     *Name,
 288      OUT UINT64    *NodeId
 289   );
 290
 291 EFI_STATUS
 292 VirtioFsFuseRemoveFileOrDir (
 293   IN OUT VIRTIO_FS *VirtioFs,
 294   IN     UINT64    ParentNodeId,
 295   IN     CHAR8     *Name,
 296   IN     BOOLEAN   IsDir
 297   );
 298
 299 EFI_STATUS
 300 VirtioFsFuseOpen (
 301   IN OUT VIRTIO_FS *VirtioFs,
 302   IN     UINT64    NodeId,
 303   IN     BOOLEAN   ReadWrite,
 304      OUT UINT64    *FuseHandle
 305   );
 306
 307 EFI_STATUS
 308 VirtioFsFuseReadFileOrDir (
 309   IN OUT VIRTIO_FS *VirtioFs,
 310   IN     UINT64    NodeId,
 311   IN     UINT64    FuseHandle,
 312   IN     BOOLEAN   IsDir,
 313   IN     UINT64    Offset,
 314   IN OUT UINT32    *Size,
 315      OUT VOID      *Data
 316   );
 317
 318 EFI_STATUS
 319 VirtioFsFuseStatFs (
 320   IN OUT VIRTIO_FS                      *VirtioFs,
 321   IN     UINT64                         NodeId,
 322      OUT VIRTIO_FS_FUSE_STATFS_RESPONSE *FilesysAttr
 323      );
 324
 325 EFI_STATUS
 326 VirtioFsFuseReleaseFileOrDir (
 327   IN OUT VIRTIO_FS *VirtioFs,
 328   IN     UINT64    NodeId,
 329   IN     UINT64    FuseHandle,
 330   IN     BOOLEAN   IsDir
 331   );
 332
 333 EFI_STATUS
 334 VirtioFsFuseFsyncFileOrDir (
 335   IN OUT VIRTIO_FS *VirtioFs,
 336   IN     UINT64    NodeId,
 337   IN     UINT64    FuseHandle,
 338   IN     BOOLEAN   IsDir
 339   );
 340
 341 EFI_STATUS
 342 VirtioFsFuseFlush (
 343   IN OUT VIRTIO_FS *VirtioFs,
 344   IN     UINT64    NodeId,
 345   IN     UINT64    FuseHandle
 346   );
 347
 348 EFI_STATUS
 349 VirtioFsFuseInitSession (
 350   IN OUT VIRTIO_FS *VirtioFs
 351   );
 352
 353 EFI_STATUS
 354 VirtioFsFuseOpenDir (
 355   IN OUT VIRTIO_FS *VirtioFs,
 356   IN     UINT64    NodeId,
 357      OUT UINT64    *FuseHandle
 358   );
 359
 360 EFI_STATUS
 361 VirtioFsFuseOpenOrCreate (
 362   IN OUT VIRTIO_FS *VirtioFs,
 363   IN     UINT64    ParentNodeId,
 364   IN     CHAR8     *Name,
 365      OUT UINT64    *NodeId,
 366      OUT UINT64    *FuseHandle
 367   );
 368
 369 //
 370 // EFI_SIMPLE_FILE_SYSTEM_PROTOCOL member functions for the Virtio Filesystem
 371 // driver.
 372 //
 373
 374 EFI_STATUS
 375 EFIAPI
 376 VirtioFsOpenVolume (
 377   IN  EFI_SIMPLE_FILE_SYSTEM_PROTOCOL *This,
 378   OUT EFI_FILE_PROTOCOL               **Root
 379   );
 380
 381 //
 382 // EFI_FILE_PROTOCOL member functions for the Virtio Filesystem driver.
 383 //
 384
 385 EFI_STATUS
 386 EFIAPI
 387 VirtioFsSimpleFileClose (
 388   IN EFI_FILE_PROTOCOL *This
 389   );
 390
 391 EFI_STATUS
 392 EFIAPI
 393 VirtioFsSimpleFileDelete (
 394   IN EFI_FILE_PROTOCOL *This
 395   );
 396
 397 EFI_STATUS
 398 EFIAPI
 399 VirtioFsSimpleFileFlush (
 400   IN EFI_FILE_PROTOCOL *This
 401   );
 402
 403 EFI_STATUS
 404 EFIAPI
 405 VirtioFsSimpleFileGetInfo (
 406   IN     EFI_FILE_PROTOCOL *This,
 407   IN     EFI_GUID          *InformationType,
 408   IN OUT UINTN             *BufferSize,
 409      OUT VOID              *Buffer
 410   );
 411
 412 EFI_STATUS
 413 EFIAPI
 414 VirtioFsSimpleFileGetPosition (
 415   IN     EFI_FILE_PROTOCOL *This,
 416      OUT UINT64            *Position
 417   );
 418
 419 EFI_STATUS
 420 EFIAPI
 421 VirtioFsSimpleFileOpen (
 422   IN     EFI_FILE_PROTOCOL *This,
 423      OUT EFI_FILE_PROTOCOL **NewHandle,
 424   IN     CHAR16            *FileName,
 425   IN     UINT64            OpenMode,
 426   IN     UINT64            Attributes
 427   );
 428
 429 EFI_STATUS
 430 EFIAPI
 431 VirtioFsSimpleFileRead (
 432   IN     EFI_FILE_PROTOCOL *This,
 433   IN OUT UINTN             *BufferSize,
 434      OUT VOID              *Buffer
 435   );
 436
 437 EFI_STATUS
 438 EFIAPI
 439 VirtioFsSimpleFileSetInfo (
 440   IN EFI_FILE_PROTOCOL *This,
 441   IN EFI_GUID          *InformationType,
 442   IN UINTN             BufferSize,
 443   IN VOID              *Buffer
 444   );
 445
 446 EFI_STATUS
 447 EFIAPI
 448 VirtioFsSimpleFileSetPosition (
 449   IN EFI_FILE_PROTOCOL *This,
 450   IN UINT64            Position
 451   );
 452
 453 EFI_STATUS
 454 EFIAPI
 455 VirtioFsSimpleFileWrite (
 456   IN     EFI_FILE_PROTOCOL *This,
 457   IN OUT UINTN             *BufferSize,
 458   IN     VOID              *Buffer
 459   );
 460
 461 #endif // VIRTIO_FS_DXE_H_