ArmPkg: only attempt buildin MmCommunicationDxe for AArch64
[mirror_edk2.git] / EmbeddedPkg / Include / Library / EfiFileLib.h
CommitLineData
2ef2b01e 1/** @file\r
3402aac7 2 Library functions that perform file IO. Memory buffer, file system, and\r
c6a72cd7 3 firmware volume operations are supported.\r
2ef2b01e 4\r
60274cca
HT
5 Copyright (c) 2007, Intel Corporation. All rights reserved.<BR>\r
6 Portions copyright (c) 2008 - 2009, Apple Inc. All rights reserved.<BR>\r
2ef2b01e 7\r
878b807a 8 SPDX-License-Identifier: BSD-2-Clause-Patent\r
2ef2b01e
A
9\r
10 Basic support for opening files on different device types. The device string\r
11 is in the form of DevType:Path. Current DevType is required as there is no\r
12 current mounted device concept of current working directory concept implement\r
13 by this library.\r
14\r
c6a72cd7 15 Device names are case insensitive and only check the leading characters for\r
2ef2b01e
A
16 unique matches. Thus the following are all the same:\r
17 LoadFile0:\r
18 l0:\r
19 L0:\r
20 Lo0:\r
21\r
22 Supported Device Names:\r
23 A0x1234:0x12 - A memory buffer starting at address 0x1234 for 0x12 bytes\r
24 l1: - EFI LoadFile device one.\r
25 B0: - EFI BlockIo zero.\r
26 fs3: - EFI Simple File System device 3\r
c6a72cd7 27 Fv2: - EFI Firmware Volume device 2\r
2ef2b01e 28 1.2.3.4:name - TFTP IP and file name\r
3402aac7 29\r
2ef2b01e
A
30**/\r
31\r
32#ifndef __EFI_FILE_LIB_H__\r
33#define __EFI_FILE_LIB_H__\r
34\r
35#include <PiDxe.h>\r
36#include <Protocol/FirmwareVolume2.h>\r
37#include <Protocol/FirmwareVolumeBlock.h>\r
38#include <Protocol/BlockIo.h>\r
39#include <Protocol/LoadFile.h>\r
40#include <Protocol/LoadFile.h>\r
41#include <Protocol/SimpleFileSystem.h>\r
42#include <Guid/FileInfo.h>\r
43#include <Guid/FileSystemInfo.h>\r
44\r
45#define MAX_PATHNAME 0x200\r
46\r
3402aac7 47/// Type of the file that has been opened\r
2ef2b01e
A
48typedef enum {\r
49 EfiOpenLoadFile,\r
50 EfiOpenMemoryBuffer,\r
51 EfiOpenFirmwareVolume,\r
52 EfiOpenFileSystem,\r
53 EfiOpenBlockIo,\r
54 EfiOpenTftp,\r
55 EfiOpenMaxValue\r
56} EFI_OPEN_FILE_TYPE;\r
57\r
58\r
59/// Public information about the open file\r
60typedef struct {\r
3402aac7 61 UINTN Version; // Common information\r
2ef2b01e
A
62 EFI_OPEN_FILE_TYPE Type;\r
63 EFI_DEVICE_PATH_PROTOCOL *DevicePath;\r
64 EFI_STATUS LastError;\r
3402aac7 65 EFI_HANDLE EfiHandle;\r
2ef2b01e
A
66 CHAR8 *DeviceName;\r
67 CHAR8 *FileName;\r
68\r
69 UINT64 CurrentPosition; // Information for Seek\r
70 UINT64 MaxPosition;\r
71\r
72 UINTN BaseOffset; // Base offset for hexdump command\r
3402aac7 73\r
2ef2b01e
A
74 UINTN Size; // Valid for all types other than l#:\r
75 UINT8 *Buffer; // Information valid for A#:\r
76\r
3402aac7
RC
77 EFI_FIRMWARE_VOLUME2_PROTOCOL *Fv; // Information valid for Fv#:\r
78 EFI_GUID FvNameGuid;\r
79 EFI_SECTION_TYPE FvSectionType;\r
80 EFI_FV_FILETYPE FvType;\r
81 EFI_FV_FILE_ATTRIBUTES FvAttributes;\r
2ef2b01e 82\r
3402aac7
RC
83 EFI_PHYSICAL_ADDRESS FvStart;\r
84 UINTN FvSize;\r
60428d00 85 UINTN FvHeaderSize;\r
2ef2b01e
A
86\r
87 EFI_FILE *FsFileHandle; // Information valid for Fs#:\r
88 EFI_FILE_SYSTEM_INFO *FsInfo;\r
89 EFI_FILE_INFO *FsFileInfo;\r
0a0951ea 90 EFI_BLOCK_IO_MEDIA *FsBlockIoMedia; // Information valid for Fs#: or B#:\r
208a8330 91 EFI_BLOCK_IO_PROTOCOL *FsBlockIo; // Information valid for Fs#: or B#:\r
2ef2b01e
A
92\r
93 UINTN DiskOffset; // Information valid for B#:\r
94\r
95 EFI_LOAD_FILE_PROTOCOL *LoadFile; // Information valid for l#:\r
3402aac7 96\r
2ef2b01e
A
97 EFI_IP_ADDRESS ServerIp; // Information valid for t:\r
98 BOOLEAN IsDirty;\r
99 BOOLEAN IsBufferValid;\r
3402aac7 100\r
2ef2b01e
A
101} EFI_OPEN_FILE;\r
102\r
103\r
104/// Type of Seek to perform\r
105typedef enum {\r
106 EfiSeekStart,\r
107 EfiSeekCurrent,\r
108 EfiSeekEnd,\r
109 EfiSeekMax\r
110} EFI_SEEK_TYPE;\r
111\r
112\r
113/**\r
3402aac7 114 Open a device named by PathName. The PathName includes a device name and\r
7ca9e5a4 115 path separated by a :. See file header for more details on the PathName\r
2ef2b01e 116 syntax. There is no checking to prevent a file from being opened more than\r
3402aac7 117 one type.\r
2ef2b01e
A
118\r
119 SectionType is only used to open an FV. Each file in an FV contains multiple\r
7ca9e5a4 120 sections and only the SectionType section is opened.\r
2ef2b01e
A
121\r
122 For any file that is opened with EfiOpen() must be closed with EfiClose().\r
123\r
3402aac7 124 @param PathName Path to parse to open\r
2ef2b01e
A
125 @param OpenMode Same as EFI_FILE.Open()\r
126 @param SectionType Section in FV to open.\r
127\r
128 @return NULL Open failed\r
129 @return Valid EFI_OPEN_FILE handle\r
130\r
131**/\r
132EFI_OPEN_FILE *\r
133EfiOpen (\r
134 IN CHAR8 *PathName,\r
135 IN CONST UINT64 OpenMode,\r
136 IN CONST EFI_SECTION_TYPE SectionType\r
137 );\r
138\r
139EFI_STATUS\r
140EfiCopyFile (\r
141 IN CHAR8 *DestinationFile,\r
142 IN CHAR8 *SourceFile\r
143 );\r
144\r
145/**\r
146 Use DeviceType and Index to form a valid PathName and try and open it.\r
147\r
148 @param DeviceType Device type to open\r
149 @param Index Device Index to use. Zero relative.\r
150\r
151 @return NULL Open failed\r
152 @return Valid EFI_OPEN_FILE handle\r
153\r
154**/\r
155EFI_OPEN_FILE *\r
156EfiDeviceOpenByType (\r
157 IN EFI_OPEN_FILE_TYPE DeviceType,\r
158 IN UINTN Index\r
159 );\r
160\r
161\r
162/**\r
163 Close a file handle opened by EfiOpen() and free all resources allocated by\r
164 EfiOpen().\r
165\r
166 @param Stream Open File Handle\r
167\r
168 @return EFI_INVALID_PARAMETER Stream is not an Open File\r
169 @return EFI_SUCCESS Steam closed\r
170\r
171**/\r
172EFI_STATUS\r
173EfiClose (\r
174 IN EFI_OPEN_FILE *Stream\r
175 );\r
176\r
177\r
178/**\r
3402aac7 179 Return the size of the file represented by Stream. Also return the current\r
2ef2b01e 180 Seek position. Opening a file will enable a valid file size to be returned.\r
3402aac7 181 LoadFile is an exception as a load file size is set to zero.\r
2ef2b01e
A
182\r
183 @param Stream Open File Handle\r
184\r
185 @return 0 Stream is not an Open File or a valid LoadFile handle\r
186\r
187**/\r
188UINTN\r
189EfiTell (\r
190 IN EFI_OPEN_FILE *Stream,\r
191 OUT UINT64 *CurrentPosition OPTIONAL\r
192 );\r
193\r
194\r
195/**\r
7ca9e5a4 196 Seek to the Offset location in the file. LoadFile and FV device types do\r
3402aac7 197 not support EfiSeek(). It is not possible to grow the file size using\r
2ef2b01e 198 EfiSeek().\r
3402aac7 199\r
2ef2b01e
A
200 SeekType defines how use Offset to calculate the new file position:\r
201 EfiSeekStart : Position = Offset\r
202 EfiSeekCurrent: Position is Offset bytes from the current position\r
203 EfiSeekEnd : Only supported if Offset is zero to seek to end of file.\r
204\r
205 @param Stream Open File Handle\r
3402aac7 206 @param Offset Offset to seek too.\r
2ef2b01e
A
207 @param SeekType Type of seek to perform\r
208\r
209\r
210 @return EFI_INVALID_PARAMETER Stream is not an Open File\r
7ca9e5a4 211 @return EFI_UNSUPPORTED LoadFile and FV does not support Seek\r
2ef2b01e
A
212 @return EFI_NOT_FOUND Seek past the end of the file.\r
213 @return EFI_SUCCESS Steam closed\r
214\r
215**/\r
216EFI_STATUS\r
217EfiSeek (\r
218 IN EFI_OPEN_FILE *Stream,\r
219 IN EFI_LBA Offset,\r
220 IN EFI_SEEK_TYPE SeekType\r
221 );\r
222\r
223\r
224/**\r
7ca9e5a4 225 Read BufferSize bytes from the current location in the file. For load file\r
3402aac7 226 and FV case you must read the entire file.\r
2ef2b01e
A
227\r
228 @param Stream Open File Handle\r
3402aac7 229 @param Buffer Caller allocated buffer.\r
2ef2b01e
A
230 @param BufferSize Size of buffer in bytes.\r
231\r
232\r
233 @return EFI_SUCCESS Stream is not an Open File\r
234 @return EFI_END_OF_FILE Tried to read past the end of the file\r
235 @return EFI_INVALID_PARAMETER Stream is not an open file handle\r
236 @return EFI_BUFFER_TOO_SMALL Buffer is not big enough to do the read\r
237 @return "other" Error returned from device read\r
238\r
239**/\r
240EFI_STATUS\r
241EfiRead (\r
242 IN EFI_OPEN_FILE *Stream,\r
243 OUT VOID *Buffer,\r
244 OUT UINTN *BufferSize\r
245 );\r
246\r
247\r
248/**\r
249 Read the entire file into a buffer. This routine allocates the buffer and\r
3402aac7 250 returns it to the user full of the read data.\r
2ef2b01e 251\r
7ca9e5a4 252 This is very useful for load file where it's hard to know how big the buffer\r
2ef2b01e
A
253 must be.\r
254\r
255 @param Stream Open File Handle\r
3402aac7 256 @param Buffer Pointer to buffer to return.\r
2ef2b01e
A
257 @param BufferSize Pointer to Size of buffer return..\r
258\r
259\r
260 @return EFI_SUCCESS Stream is not an Open File\r
261 @return EFI_END_OF_FILE Tried to read past the end of the file\r
262 @return EFI_INVALID_PARAMETER Stream is not an open file handle\r
263 @return EFI_BUFFER_TOO_SMALL Buffer is not big enough to do the read\r
264 @return "other" Error returned from device read\r
265\r
266**/\r
267EFI_STATUS\r
268EfiReadAllocatePool (\r
269 IN EFI_OPEN_FILE *Stream,\r
270 OUT VOID **Buffer,\r
271 OUT UINTN *BufferSize\r
272 );\r
273\r
274\r
275/**\r
3402aac7 276 Write data back to the file.\r
2ef2b01e
A
277\r
278 @param Stream Open File Handle\r
3402aac7 279 @param Buffer Pointer to buffer to return.\r
2ef2b01e
A
280 @param BufferSize Pointer to Size of buffer return..\r
281\r
282\r
283 @return EFI_SUCCESS Stream is not an Open File\r
284 @return EFI_END_OF_FILE Tried to read past the end of the file\r
285 @return EFI_INVALID_PARAMETER Stream is not an open file handle\r
286 @return EFI_BUFFER_TOO_SMALL Buffer is not big enough to do the read\r
287 @return "other" Error returned from device write\r
288\r
289**/\r
290EFI_STATUS\r
291EfiWrite (\r
292 IN EFI_OPEN_FILE *Stream,\r
293 OUT VOID *Buffer,\r
294 OUT UINTN *BufferSize\r
295 );\r
296\r
297\r
298/**\r
299 Return the number of devices of the current type active in the system\r
300\r
301 @param Type Device type to check\r
302\r
303 @return 0 Invalid type\r
304\r
305**/\r
306UINTN\r
307EfiGetDeviceCounts (\r
308 IN EFI_OPEN_FILE_TYPE Type\r
309 );\r
3402aac7 310\r
85e385f4 311\r
312/**\r
7ca9e5a4 313 Set the Current Working Directory (CWD). If a call is made to EfiOpen () and\r
85e385f4 314 the path does not contain a device name, The CWD is prepended to the path.\r
3402aac7 315\r
85e385f4 316 @param Cwd Current Working Directory to set\r
317\r
318\r
319 @return EFI_SUCCESS CWD is set\r
320 @return EFI_INVALID_PARAMETER Cwd is not a valid device:path\r
321\r
322**/\r
323EFI_STATUS\r
324EfiSetCwd (\r
325 IN CHAR8 *Cwd\r
3402aac7 326 );\r
85e385f4 327\r
328/**\r
7ca9e5a4 329 Set the Current Working Directory (CWD). If a call is made to EfiOpen () and\r
85e385f4 330 the path does not contain a device name, The CWD is prepended to the path.\r
3402aac7
RC
331\r
332 @param Cwd Current Working Directory\r
85e385f4 333\r
334\r
335 @return NULL No CWD set\r
336 @return 'other' malloc'ed buffer contains CWD.\r
3402aac7 337\r
85e385f4 338**/\r
339CHAR8 *\r
16ccac42 340EfiGetCwd (\r
85e385f4 341 VOID\r
3402aac7 342 );\r
2ef2b01e
A
343\r
344#endif\r