2 Internal macro definitions, type definitions, and function declarations for
3 the Virtio Filesystem device driver.
5 Copyright (C) 2020, Red Hat, Inc.
7 SPDX-License-Identifier: BSD-2-Clause-Patent
10 #ifndef VIRTIO_FS_DXE_H_
11 #define VIRTIO_FS_DXE_H_
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
21 #define VIRTIO_FS_SIG SIGNATURE_64 ('V', 'I', 'R', 'T', 'I', 'O', 'F', 'S')
23 #define VIRTIO_FS_FILE_SIG \
24 SIGNATURE_64 ('V', 'I', 'O', 'F', 'S', 'F', 'I', 'L')
27 // The following limit applies to two kinds of pathnames.
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
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.
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
48 #define VIRTIO_FS_MAX_PATHNAME_LENGTH ((UINTN)65535)
51 // Maximum value for VIRTIO_FS_FILE.NumFileInfo.
53 #define VIRTIO_FS_FILE_MAX_FILE_INFO 256
56 // Filesystem label encoded in UCS-2, transformed from the UTF-8 representation
57 // in "VIRTIO_FS_CONFIG.Tag", and NUL-terminated. Only the printable ASCII code
58 // points (U+0020 through U+007E) are supported.
60 typedef CHAR16 VIRTIO_FS_LABEL
[VIRTIO_FS_TAG_BYTES
+ 1];
63 // Main context structure, expressing an EFI_SIMPLE_FILE_SYSTEM_PROTOCOL
64 // interface on top of the Virtio Filesystem device.
68 // Parts of this structure are initialized / torn down in various functions
69 // at various call depths. The table to the right should make it easier to
72 // field init function init depth
73 // ----------- ------------------ ----------
74 UINT64 Signature
; // DriverBindingStart 0
75 VIRTIO_DEVICE_PROTOCOL
*Virtio
; // DriverBindingStart 0
76 VIRTIO_FS_LABEL Label
; // VirtioFsInit 1
77 UINT16 QueueSize
; // VirtioFsInit 1
78 VRING Ring
; // VirtioRingInit 2
79 VOID
*RingMap
; // VirtioRingMap 2
80 UINT64 RequestId
; // FuseInitSession 1
81 UINT32 MaxWrite
; // FuseInitSession 1
82 EFI_EVENT ExitBoot
; // DriverBindingStart 0
83 LIST_ENTRY OpenFiles
; // DriverBindingStart 0
84 EFI_SIMPLE_FILE_SYSTEM_PROTOCOL SimpleFs
; // DriverBindingStart 0
87 #define VIRTIO_FS_FROM_SIMPLE_FS(SimpleFsReference) \
88 CR (SimpleFsReference, VIRTIO_FS, SimpleFs, VIRTIO_FS_SIG);
91 // Structure for describing a contiguous buffer, potentially mapped for Virtio
96 // The following fields originate from the owner of the buffer.
101 // All of the fields below, until the end of the structure, are
102 // zero-initialized when the structure is initially validated.
104 // Mapped, MappedAddress and Mapping are updated when the buffer is mapped
105 // for VirtioOperationBusMasterRead or VirtioOperationBusMasterWrite. They
106 // are again updated when the buffer is unmapped.
109 EFI_PHYSICAL_ADDRESS MappedAddress
;
112 // Transferred is updated after VirtioFlush() returns successfully:
113 // - for VirtioOperationBusMasterRead, Transferred is set to Size;
114 // - for VirtioOperationBusMasterWrite, Transferred is calculated from the
115 // UsedLen output parameter of VirtioFlush().
118 } VIRTIO_FS_IO_VECTOR
;
121 // Structure for describing a list of IO Vectors.
125 // The following fields originate from the owner of the buffers.
127 VIRTIO_FS_IO_VECTOR
*IoVec
;
130 // TotalSize is calculated when the scatter-gather list is initially
134 } VIRTIO_FS_SCATTER_GATHER_LIST
;
137 // Private context structure that exposes EFI_FILE_PROTOCOL on top of an open
138 // FUSE file reference.
142 EFI_FILE_PROTOCOL SimpleFile
;
144 BOOLEAN IsOpenForWriting
;
146 LIST_ENTRY OpenFilesEntry
;
147 CHAR8
*CanonicalPathname
;
150 // In the FUSE wire protocol, every request except FUSE_INIT refers to a
151 // file, namely by the "VIRTIO_FS_FUSE_REQUEST.NodeId" field; that is, by the
152 // inode number of the file. However, some of the FUSE requests that we need
153 // for some of the EFI_FILE_PROTOCOL member functions require an open file
154 // handle *in addition* to the inode number. For simplicity, whenever a
155 // VIRTIO_FS_FILE object is created, primarily defined by its NodeId field,
156 // we also *open* the referenced file at once, and save the returned file
157 // handle in the FuseHandle field. This way, when an EFI_FILE_PROTOCOL member
158 // function must send a FUSE request that needs the file handle *in addition*
159 // to the inode number, FuseHandle will be at our disposal at once.
164 // EFI_FILE_INFO objects cached for an in-flight directory read.
166 // For reading through a directory stream with tolerable performance, we have
167 // to call FUSE_READDIRPLUS each time with such a buffer that can deliver a
168 // good number of variable size records (VIRTIO_FS_FUSE_DIRENTPLUS_RESPONSE
169 // elements). Every time we do that, we turn the whole bunch into an array of
170 // EFI_FILE_INFOs immediately. EFI_FILE_PROTOCOL.Read() invocations (on
171 // directories) will be served from this EFI_FILE_INFO cache.
173 UINT8
*FileInfoArray
;
174 UINTN SingleFileInfoSize
;
179 #define VIRTIO_FS_FILE_FROM_SIMPLE_FILE(SimpleFileReference) \
180 CR (SimpleFileReference, VIRTIO_FS_FILE, SimpleFile, VIRTIO_FS_FILE_SIG);
182 #define VIRTIO_FS_FILE_FROM_OPEN_FILES_ENTRY(OpenFilesEntryReference) \
183 CR (OpenFilesEntryReference, VIRTIO_FS_FILE, OpenFilesEntry, \
187 // Initialization and helper routines for the Virtio Filesystem device.
192 IN OUT VIRTIO_FS
*VirtioFs
197 IN OUT VIRTIO_FS
*VirtioFs
203 IN EFI_EVENT ExitBootEvent
,
204 IN VOID
*VirtioFsAsVoid
208 VirtioFsSgListsValidate (
209 IN VIRTIO_FS
*VirtioFs
,
210 IN OUT VIRTIO_FS_SCATTER_GATHER_LIST
*RequestSgList
,
211 IN OUT VIRTIO_FS_SCATTER_GATHER_LIST
*ResponseSgList OPTIONAL
215 VirtioFsSgListsSubmit (
216 IN OUT VIRTIO_FS
*VirtioFs
,
217 IN OUT VIRTIO_FS_SCATTER_GATHER_LIST
*RequestSgList
,
218 IN OUT VIRTIO_FS_SCATTER_GATHER_LIST
*ResponseSgList OPTIONAL
222 VirtioFsFuseNewRequest (
223 IN OUT VIRTIO_FS
*VirtioFs
,
224 OUT VIRTIO_FS_FUSE_REQUEST
*Request
,
225 IN UINT32 RequestSize
,
226 IN VIRTIO_FS_FUSE_OPCODE Opcode
,
231 VirtioFsFuseCheckResponse (
232 IN VIRTIO_FS_SCATTER_GATHER_LIST
*ResponseSgList
,
234 OUT UINTN
*TailBufferFill
238 VirtioFsErrnoToEfiStatus (
245 IN CHAR16
*RhsPath16
,
246 OUT CHAR8
**ResultPath8
,
247 OUT BOOLEAN
*RootEscape
251 VirtioFsLookupMostSpecificParentDir (
252 IN OUT VIRTIO_FS
*VirtioFs
,
254 OUT UINT64
*DirNodeId
,
255 OUT CHAR8
**LastComponent
259 VirtioFsGetBasename (
261 OUT CHAR16
*Basename OPTIONAL
,
262 IN OUT UINTN
*BasenameSize
266 VirtioFsComposeRenameDestination (
268 IN CHAR16
*RhsPath16
,
269 OUT CHAR8
**ResultPath8
,
270 OUT BOOLEAN
*RootEscape
274 VirtioFsFuseAttrToEfiFileInfo (
275 IN VIRTIO_FS_FUSE_ATTRIBUTES_RESPONSE
*FuseAttr
,
276 OUT EFI_FILE_INFO
*FileInfo
280 VirtioFsFuseDirentPlusToEfiFileInfo (
281 IN VIRTIO_FS_FUSE_DIRENTPLUS_RESPONSE
*FuseDirent
,
282 IN OUT EFI_FILE_INFO
*FileInfo
286 VirtioFsGetFuseSizeUpdate (
287 IN EFI_FILE_INFO
*Info
,
288 IN EFI_FILE_INFO
*NewInfo
,
294 VirtioFsGetFuseTimeUpdates (
295 IN EFI_FILE_INFO
*Info
,
296 IN EFI_FILE_INFO
*NewInfo
,
297 OUT BOOLEAN
*UpdateAtime
,
298 OUT BOOLEAN
*UpdateMtime
,
304 // Wrapper functions for FUSE commands (primitives).
309 IN OUT VIRTIO_FS
*VirtioFs
,
313 OUT VIRTIO_FS_FUSE_ATTRIBUTES_RESPONSE
*FuseAttr
318 IN OUT VIRTIO_FS
*VirtioFs
,
323 VirtioFsFuseGetAttr (
324 IN OUT VIRTIO_FS
*VirtioFs
,
326 OUT VIRTIO_FS_FUSE_ATTRIBUTES_RESPONSE
*FuseAttr
330 VirtioFsFuseSetAttr (
331 IN OUT VIRTIO_FS
*VirtioFs
,
333 IN UINT64
*Size OPTIONAL
,
334 IN UINT64
*Atime OPTIONAL
,
335 IN UINT64
*Mtime OPTIONAL
,
336 IN UINT32
*Mode OPTIONAL
341 IN OUT VIRTIO_FS
*VirtioFs
,
342 IN UINT64 ParentNodeId
,
348 VirtioFsFuseRemoveFileOrDir (
349 IN OUT VIRTIO_FS
*VirtioFs
,
350 IN UINT64 ParentNodeId
,
357 IN OUT VIRTIO_FS
*VirtioFs
,
359 IN BOOLEAN ReadWrite
,
360 OUT UINT64
*FuseHandle
364 VirtioFsFuseReadFileOrDir (
365 IN OUT VIRTIO_FS
*VirtioFs
,
367 IN UINT64 FuseHandle
,
376 IN OUT VIRTIO_FS
*VirtioFs
,
378 IN UINT64 FuseHandle
,
386 IN OUT VIRTIO_FS
*VirtioFs
,
388 OUT VIRTIO_FS_FUSE_STATFS_RESPONSE
*FilesysAttr
392 VirtioFsFuseReleaseFileOrDir (
393 IN OUT VIRTIO_FS
*VirtioFs
,
395 IN UINT64 FuseHandle
,
400 VirtioFsFuseFsyncFileOrDir (
401 IN OUT VIRTIO_FS
*VirtioFs
,
403 IN UINT64 FuseHandle
,
409 IN OUT VIRTIO_FS
*VirtioFs
,
415 VirtioFsFuseInitSession (
416 IN OUT VIRTIO_FS
*VirtioFs
420 VirtioFsFuseOpenDir (
421 IN OUT VIRTIO_FS
*VirtioFs
,
423 OUT UINT64
*FuseHandle
427 VirtioFsFuseOpenOrCreate (
428 IN OUT VIRTIO_FS
*VirtioFs
,
429 IN UINT64 ParentNodeId
,
432 OUT UINT64
*FuseHandle
437 IN OUT VIRTIO_FS
*VirtioFs
,
438 IN UINT64 OldParentNodeId
,
440 IN UINT64 NewParentNodeId
,
445 // EFI_SIMPLE_FILE_SYSTEM_PROTOCOL member functions for the Virtio Filesystem
452 IN EFI_SIMPLE_FILE_SYSTEM_PROTOCOL
*This
,
453 OUT EFI_FILE_PROTOCOL
**Root
457 // EFI_FILE_PROTOCOL member functions for the Virtio Filesystem driver.
462 VirtioFsSimpleFileClose (
463 IN EFI_FILE_PROTOCOL
*This
468 VirtioFsSimpleFileDelete (
469 IN EFI_FILE_PROTOCOL
*This
474 VirtioFsSimpleFileFlush (
475 IN EFI_FILE_PROTOCOL
*This
480 VirtioFsSimpleFileGetInfo (
481 IN EFI_FILE_PROTOCOL
*This
,
482 IN EFI_GUID
*InformationType
,
483 IN OUT UINTN
*BufferSize
,
489 VirtioFsSimpleFileGetPosition (
490 IN EFI_FILE_PROTOCOL
*This
,
496 VirtioFsSimpleFileOpen (
497 IN EFI_FILE_PROTOCOL
*This
,
498 OUT EFI_FILE_PROTOCOL
**NewHandle
,
506 VirtioFsSimpleFileRead (
507 IN EFI_FILE_PROTOCOL
*This
,
508 IN OUT UINTN
*BufferSize
,
514 VirtioFsSimpleFileSetInfo (
515 IN EFI_FILE_PROTOCOL
*This
,
516 IN EFI_GUID
*InformationType
,
523 VirtioFsSimpleFileSetPosition (
524 IN EFI_FILE_PROTOCOL
*This
,
530 VirtioFsSimpleFileWrite (
531 IN EFI_FILE_PROTOCOL
*This
,
532 IN OUT UINTN
*BufferSize
,
536 #endif // VIRTIO_FS_DXE_H_