ArmPkg: only attempt buildin MmCommunicationDxe for AArch64
[mirror_edk2.git] / EmbeddedPkg / Include / Library / EfiFileLib.h
1 /** @file
2 Library functions that perform file IO. Memory buffer, file system, and
3 firmware volume operations are supported.
4
5 Copyright (c) 2007, Intel Corporation. All rights reserved.<BR>
6 Portions copyright (c) 2008 - 2009, Apple Inc. All rights reserved.<BR>
7
8 SPDX-License-Identifier: BSD-2-Clause-Patent
9
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
13 by this library.
14
15 Device names are case insensitive and only check the leading characters for
16 unique matches. Thus the following are all the same:
17 LoadFile0:
18 l0:
19 L0:
20 Lo0:
21
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
29
30 **/
31
32 #ifndef __EFI_FILE_LIB_H__
33 #define __EFI_FILE_LIB_H__
34
35 #include <PiDxe.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>
44
45 #define MAX_PATHNAME 0x200
46
47 /// Type of the file that has been opened
48 typedef enum {
49 EfiOpenLoadFile,
50 EfiOpenMemoryBuffer,
51 EfiOpenFirmwareVolume,
52 EfiOpenFileSystem,
53 EfiOpenBlockIo,
54 EfiOpenTftp,
55 EfiOpenMaxValue
56 } EFI_OPEN_FILE_TYPE;
57
58
59 /// Public information about the open file
60 typedef struct {
61 UINTN Version; // Common information
62 EFI_OPEN_FILE_TYPE Type;
63 EFI_DEVICE_PATH_PROTOCOL *DevicePath;
64 EFI_STATUS LastError;
65 EFI_HANDLE EfiHandle;
66 CHAR8 *DeviceName;
67 CHAR8 *FileName;
68
69 UINT64 CurrentPosition; // Information for Seek
70 UINT64 MaxPosition;
71
72 UINTN BaseOffset; // Base offset for hexdump command
73
74 UINTN Size; // Valid for all types other than l#:
75 UINT8 *Buffer; // Information valid for A#:
76
77 EFI_FIRMWARE_VOLUME2_PROTOCOL *Fv; // Information valid for Fv#:
78 EFI_GUID FvNameGuid;
79 EFI_SECTION_TYPE FvSectionType;
80 EFI_FV_FILETYPE FvType;
81 EFI_FV_FILE_ATTRIBUTES FvAttributes;
82
83 EFI_PHYSICAL_ADDRESS FvStart;
84 UINTN FvSize;
85 UINTN FvHeaderSize;
86
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#:
92
93 UINTN DiskOffset; // Information valid for B#:
94
95 EFI_LOAD_FILE_PROTOCOL *LoadFile; // Information valid for l#:
96
97 EFI_IP_ADDRESS ServerIp; // Information valid for t:
98 BOOLEAN IsDirty;
99 BOOLEAN IsBufferValid;
100
101 } EFI_OPEN_FILE;
102
103
104 /// Type of Seek to perform
105 typedef enum {
106 EfiSeekStart,
107 EfiSeekCurrent,
108 EfiSeekEnd,
109 EfiSeekMax
110 } EFI_SEEK_TYPE;
111
112
113 /**
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
117 one type.
118
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.
121
122 For any file that is opened with EfiOpen() must be closed with EfiClose().
123
124 @param PathName Path to parse to open
125 @param OpenMode Same as EFI_FILE.Open()
126 @param SectionType Section in FV to open.
127
128 @return NULL Open failed
129 @return Valid EFI_OPEN_FILE handle
130
131 **/
132 EFI_OPEN_FILE *
133 EfiOpen (
134 IN CHAR8 *PathName,
135 IN CONST UINT64 OpenMode,
136 IN CONST EFI_SECTION_TYPE SectionType
137 );
138
139 EFI_STATUS
140 EfiCopyFile (
141 IN CHAR8 *DestinationFile,
142 IN CHAR8 *SourceFile
143 );
144
145 /**
146 Use DeviceType and Index to form a valid PathName and try and open it.
147
148 @param DeviceType Device type to open
149 @param Index Device Index to use. Zero relative.
150
151 @return NULL Open failed
152 @return Valid EFI_OPEN_FILE handle
153
154 **/
155 EFI_OPEN_FILE *
156 EfiDeviceOpenByType (
157 IN EFI_OPEN_FILE_TYPE DeviceType,
158 IN UINTN Index
159 );
160
161
162 /**
163 Close a file handle opened by EfiOpen() and free all resources allocated by
164 EfiOpen().
165
166 @param Stream Open File Handle
167
168 @return EFI_INVALID_PARAMETER Stream is not an Open File
169 @return EFI_SUCCESS Steam closed
170
171 **/
172 EFI_STATUS
173 EfiClose (
174 IN EFI_OPEN_FILE *Stream
175 );
176
177
178 /**
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.
182
183 @param Stream Open File Handle
184
185 @return 0 Stream is not an Open File or a valid LoadFile handle
186
187 **/
188 UINTN
189 EfiTell (
190 IN EFI_OPEN_FILE *Stream,
191 OUT UINT64 *CurrentPosition OPTIONAL
192 );
193
194
195 /**
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
198 EfiSeek().
199
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.
204
205 @param Stream Open File Handle
206 @param Offset Offset to seek too.
207 @param SeekType Type of seek to perform
208
209
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
214
215 **/
216 EFI_STATUS
217 EfiSeek (
218 IN EFI_OPEN_FILE *Stream,
219 IN EFI_LBA Offset,
220 IN EFI_SEEK_TYPE SeekType
221 );
222
223
224 /**
225 Read BufferSize bytes from the current location in the file. For load file
226 and FV case you must read the entire file.
227
228 @param Stream Open File Handle
229 @param Buffer Caller allocated buffer.
230 @param BufferSize Size of buffer in bytes.
231
232
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
238
239 **/
240 EFI_STATUS
241 EfiRead (
242 IN EFI_OPEN_FILE *Stream,
243 OUT VOID *Buffer,
244 OUT UINTN *BufferSize
245 );
246
247
248 /**
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.
251
252 This is very useful for load file where it's hard to know how big the buffer
253 must be.
254
255 @param Stream Open File Handle
256 @param Buffer Pointer to buffer to return.
257 @param BufferSize Pointer to Size of buffer return..
258
259
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
265
266 **/
267 EFI_STATUS
268 EfiReadAllocatePool (
269 IN EFI_OPEN_FILE *Stream,
270 OUT VOID **Buffer,
271 OUT UINTN *BufferSize
272 );
273
274
275 /**
276 Write data back to the file.
277
278 @param Stream Open File Handle
279 @param Buffer Pointer to buffer to return.
280 @param BufferSize Pointer to Size of buffer return..
281
282
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
288
289 **/
290 EFI_STATUS
291 EfiWrite (
292 IN EFI_OPEN_FILE *Stream,
293 OUT VOID *Buffer,
294 OUT UINTN *BufferSize
295 );
296
297
298 /**
299 Return the number of devices of the current type active in the system
300
301 @param Type Device type to check
302
303 @return 0 Invalid type
304
305 **/
306 UINTN
307 EfiGetDeviceCounts (
308 IN EFI_OPEN_FILE_TYPE Type
309 );
310
311
312 /**
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.
315
316 @param Cwd Current Working Directory to set
317
318
319 @return EFI_SUCCESS CWD is set
320 @return EFI_INVALID_PARAMETER Cwd is not a valid device:path
321
322 **/
323 EFI_STATUS
324 EfiSetCwd (
325 IN CHAR8 *Cwd
326 );
327
328 /**
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.
331
332 @param Cwd Current Working Directory
333
334
335 @return NULL No CWD set
336 @return 'other' malloc'ed buffer contains CWD.
337
338 **/
339 CHAR8 *
340 EfiGetCwd (
341 VOID
342 );
343
344 #endif