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