2 Library functions that perform file IO. Memory buffer, file system, and
3 firmware volume operations are supported.
5 Copyright (c) 2007, Intel Corporation. All rights reserved.<BR>
6 Portions copyright (c) 2008 - 2009, Apple Inc. All rights reserved.<BR>
8 SPDX-License-Identifier: BSD-2-Clause-Patent
10 Basic support for opening files on different device types. The device string
11 is in the form of DevType:Path. Current DevType is required as there is no
12 current mounted device concept of current working directory concept implement
15 Device names are case insensitive and only check the leading characters for
16 unique matches. Thus the following are all the same:
22 Supported Device Names:
23 A0x1234:0x12 - A memory buffer starting at address 0x1234 for 0x12 bytes
24 l1: - EFI LoadFile device one.
25 B0: - EFI BlockIo zero.
26 fs3: - EFI Simple File System device 3
27 Fv2: - EFI Firmware Volume device 2
28 1.2.3.4:name - TFTP IP and file name
32 #ifndef __EFI_FILE_LIB_H__
33 #define __EFI_FILE_LIB_H__
36 #include <Protocol/FirmwareVolume2.h>
37 #include <Protocol/FirmwareVolumeBlock.h>
38 #include <Protocol/BlockIo.h>
39 #include <Protocol/LoadFile.h>
40 #include <Protocol/LoadFile.h>
41 #include <Protocol/SimpleFileSystem.h>
42 #include <Guid/FileInfo.h>
43 #include <Guid/FileSystemInfo.h>
45 #define MAX_PATHNAME 0x200
47 /// Type of the file that has been opened
51 EfiOpenFirmwareVolume
,
59 /// Public information about the open file
61 UINTN Version
; // Common information
62 EFI_OPEN_FILE_TYPE Type
;
63 EFI_DEVICE_PATH_PROTOCOL
*DevicePath
;
69 UINT64 CurrentPosition
; // Information for Seek
72 UINTN BaseOffset
; // Base offset for hexdump command
74 UINTN Size
; // Valid for all types other than l#:
75 UINT8
*Buffer
; // Information valid for A#:
77 EFI_FIRMWARE_VOLUME2_PROTOCOL
*Fv
; // Information valid for Fv#:
79 EFI_SECTION_TYPE FvSectionType
;
80 EFI_FV_FILETYPE FvType
;
81 EFI_FV_FILE_ATTRIBUTES FvAttributes
;
83 EFI_PHYSICAL_ADDRESS FvStart
;
87 EFI_FILE
*FsFileHandle
; // Information valid for Fs#:
88 EFI_FILE_SYSTEM_INFO
*FsInfo
;
89 EFI_FILE_INFO
*FsFileInfo
;
90 EFI_BLOCK_IO_MEDIA
*FsBlockIoMedia
; // Information valid for Fs#: or B#:
91 EFI_BLOCK_IO_PROTOCOL
*FsBlockIo
; // Information valid for Fs#: or B#:
93 UINTN DiskOffset
; // Information valid for B#:
95 EFI_LOAD_FILE_PROTOCOL
*LoadFile
; // Information valid for l#:
97 EFI_IP_ADDRESS ServerIp
; // Information valid for t:
99 BOOLEAN IsBufferValid
;
104 /// Type of Seek to perform
114 Open a device named by PathName. The PathName includes a device name and
115 path separated by a :. See file header for more details on the PathName
116 syntax. There is no checking to prevent a file from being opened more than
119 SectionType is only used to open an FV. Each file in an FV contains multiple
120 sections and only the SectionType section is opened.
122 For any file that is opened with EfiOpen() must be closed with EfiClose().
124 @param PathName Path to parse to open
125 @param OpenMode Same as EFI_FILE.Open()
126 @param SectionType Section in FV to open.
128 @return NULL Open failed
129 @return Valid EFI_OPEN_FILE handle
135 IN CONST UINT64 OpenMode
,
136 IN CONST EFI_SECTION_TYPE SectionType
141 IN CHAR8
*DestinationFile
,
146 Use DeviceType and Index to form a valid PathName and try and open it.
148 @param DeviceType Device type to open
149 @param Index Device Index to use. Zero relative.
151 @return NULL Open failed
152 @return Valid EFI_OPEN_FILE handle
156 EfiDeviceOpenByType (
157 IN EFI_OPEN_FILE_TYPE DeviceType
,
163 Close a file handle opened by EfiOpen() and free all resources allocated by
166 @param Stream Open File Handle
168 @return EFI_INVALID_PARAMETER Stream is not an Open File
169 @return EFI_SUCCESS Steam closed
174 IN EFI_OPEN_FILE
*Stream
179 Return the size of the file represented by Stream. Also return the current
180 Seek position. Opening a file will enable a valid file size to be returned.
181 LoadFile is an exception as a load file size is set to zero.
183 @param Stream Open File Handle
185 @return 0 Stream is not an Open File or a valid LoadFile handle
190 IN EFI_OPEN_FILE
*Stream
,
191 OUT UINT64
*CurrentPosition OPTIONAL
196 Seek to the Offset location in the file. LoadFile and FV device types do
197 not support EfiSeek(). It is not possible to grow the file size using
200 SeekType defines how use Offset to calculate the new file position:
201 EfiSeekStart : Position = Offset
202 EfiSeekCurrent: Position is Offset bytes from the current position
203 EfiSeekEnd : Only supported if Offset is zero to seek to end of file.
205 @param Stream Open File Handle
206 @param Offset Offset to seek too.
207 @param SeekType Type of seek to perform
210 @return EFI_INVALID_PARAMETER Stream is not an Open File
211 @return EFI_UNSUPPORTED LoadFile and FV does not support Seek
212 @return EFI_NOT_FOUND Seek past the end of the file.
213 @return EFI_SUCCESS Steam closed
218 IN EFI_OPEN_FILE
*Stream
,
220 IN EFI_SEEK_TYPE SeekType
225 Read BufferSize bytes from the current location in the file. For load file
226 and FV case you must read the entire file.
228 @param Stream Open File Handle
229 @param Buffer Caller allocated buffer.
230 @param BufferSize Size of buffer in bytes.
233 @return EFI_SUCCESS Stream is not an Open File
234 @return EFI_END_OF_FILE Tried to read past the end of the file
235 @return EFI_INVALID_PARAMETER Stream is not an open file handle
236 @return EFI_BUFFER_TOO_SMALL Buffer is not big enough to do the read
237 @return "other" Error returned from device read
242 IN EFI_OPEN_FILE
*Stream
,
244 OUT UINTN
*BufferSize
249 Read the entire file into a buffer. This routine allocates the buffer and
250 returns it to the user full of the read data.
252 This is very useful for load file where it's hard to know how big the buffer
255 @param Stream Open File Handle
256 @param Buffer Pointer to buffer to return.
257 @param BufferSize Pointer to Size of buffer return..
260 @return EFI_SUCCESS Stream is not an Open File
261 @return EFI_END_OF_FILE Tried to read past the end of the file
262 @return EFI_INVALID_PARAMETER Stream is not an open file handle
263 @return EFI_BUFFER_TOO_SMALL Buffer is not big enough to do the read
264 @return "other" Error returned from device read
268 EfiReadAllocatePool (
269 IN EFI_OPEN_FILE
*Stream
,
271 OUT UINTN
*BufferSize
276 Write data back to the file.
278 @param Stream Open File Handle
279 @param Buffer Pointer to buffer to return.
280 @param BufferSize Pointer to Size of buffer return..
283 @return EFI_SUCCESS Stream is not an Open File
284 @return EFI_END_OF_FILE Tried to read past the end of the file
285 @return EFI_INVALID_PARAMETER Stream is not an open file handle
286 @return EFI_BUFFER_TOO_SMALL Buffer is not big enough to do the read
287 @return "other" Error returned from device write
292 IN EFI_OPEN_FILE
*Stream
,
294 OUT UINTN
*BufferSize
299 Return the number of devices of the current type active in the system
301 @param Type Device type to check
303 @return 0 Invalid type
308 IN EFI_OPEN_FILE_TYPE Type
313 Set the Current Working Directory (CWD). If a call is made to EfiOpen () and
314 the path does not contain a device name, The CWD is prepended to the path.
316 @param Cwd Current Working Directory to set
319 @return EFI_SUCCESS CWD is set
320 @return EFI_INVALID_PARAMETER Cwd is not a valid device:path
329 Set the Current Working Directory (CWD). If a call is made to EfiOpen () and
330 the path does not contain a device name, The CWD is prepended to the path.
332 @param Cwd Current Working Directory
335 @return NULL No CWD set
336 @return 'other' malloc'ed buffer contains CWD.