EfiFileLib.h 9.8 KB

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