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