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 /// Public information about the open file
  59 typedef struct {
  60   UINTN                            Version;       // Common information
  61   EFI_OPEN_FILE_TYPE               Type;
  62   EFI_DEVICE_PATH_PROTOCOL         *DevicePath;
  63   EFI_STATUS                       LastError;
  64   EFI_HANDLE                       EfiHandle;
  65   CHAR8                            *DeviceName;
  66   CHAR8                            *FileName;
  67
  68   UINT64                           CurrentPosition; // Information for Seek
  69   UINT64                           MaxPosition;
  70
  71   UINTN                            BaseOffset;    // Base offset for hexdump command
  72
  73   UINTN                            Size;          // Valid for all types other than l#:
  74   UINT8                            *Buffer;       // Information valid for A#:
  75
  76   EFI_FIRMWARE_VOLUME2_PROTOCOL    *Fv;           // Information valid for Fv#:
  77   EFI_GUID                         FvNameGuid;
  78   EFI_SECTION_TYPE                 FvSectionType;
  79   EFI_FV_FILETYPE                  FvType;
  80   EFI_FV_FILE_ATTRIBUTES           FvAttributes;
  81
  82   EFI_PHYSICAL_ADDRESS             FvStart;
  83   UINTN                            FvSize;
  84   UINTN                            FvHeaderSize;
  85
  86   EFI_FILE                         *FsFileHandle; // Information valid for Fs#:
  87   EFI_FILE_SYSTEM_INFO             *FsInfo;
  88   EFI_FILE_INFO                    *FsFileInfo;
  89   EFI_BLOCK_IO_MEDIA               *FsBlockIoMedia; // Information valid for Fs#: or B#:
  90   EFI_BLOCK_IO_PROTOCOL            *FsBlockIo;      // Information valid for Fs#: or B#:
  91
  92   UINTN                            DiskOffset;    // Information valid for B#:
  93
  94   EFI_LOAD_FILE_PROTOCOL           *LoadFile;     // Information valid for l#:
  95
  96   EFI_IP_ADDRESS                   ServerIp;      // Information valid for t:
  97   BOOLEAN                          IsDirty;
  98   BOOLEAN                          IsBufferValid;
  99 } EFI_OPEN_FILE;
 100
 101 /// Type of Seek to perform
 102 typedef enum {
 103   EfiSeekStart,
 104   EfiSeekCurrent,
 105   EfiSeekEnd,
 106   EfiSeekMax
 107 } EFI_SEEK_TYPE;
 108
 109 /**
 110   Open a device named by PathName. The PathName includes a device name and
 111   path separated by a :. See file header for more details on the PathName
 112   syntax. There is no checking to prevent a file from being opened more than
 113   one type.
 114
 115   SectionType is only used to open an FV. Each file in an FV contains multiple
 116   sections and only the SectionType section is opened.
 117
 118   For any file that is opened with EfiOpen() must be closed with EfiClose().
 119
 120   @param  PathName    Path to parse to open
 121   @param  OpenMode    Same as EFI_FILE.Open()
 122   @param  SectionType Section in FV to open.
 123
 124   @return NULL  Open failed
 125   @return Valid EFI_OPEN_FILE handle
 126
 127 **/
 128 EFI_OPEN_FILE *
 129 EfiOpen (
 130   IN        CHAR8             *PathName,
 131   IN  CONST UINT64            OpenMode,
 132   IN  CONST EFI_SECTION_TYPE  SectionType
 133   );
 134
 135 EFI_STATUS
 136 EfiCopyFile (
 137   IN        CHAR8  *DestinationFile,
 138   IN        CHAR8  *SourceFile
 139   );
 140
 141 /**
 142   Use DeviceType and Index to form a valid PathName and try and open it.
 143
 144   @param  DeviceType  Device type to open
 145   @param  Index       Device Index to use. Zero relative.
 146
 147   @return NULL  Open failed
 148   @return Valid EFI_OPEN_FILE handle
 149
 150 **/
 151 EFI_OPEN_FILE  *
 152 EfiDeviceOpenByType (
 153   IN  EFI_OPEN_FILE_TYPE  DeviceType,
 154   IN  UINTN               Index
 155   );
 156
 157 /**
 158   Close a file handle opened by EfiOpen() and free all resources allocated by
 159   EfiOpen().
 160
 161   @param  Stream    Open File Handle
 162
 163   @return EFI_INVALID_PARAMETER  Stream is not an Open File
 164   @return EFI_SUCCESS            Steam closed
 165
 166 **/
 167 EFI_STATUS
 168 EfiClose (
 169   IN  EFI_OPEN_FILE  *Stream
 170   );
 171
 172 /**
 173   Return the size of the file represented by Stream. Also return the current
 174   Seek position. Opening a file will enable a valid file size to be returned.
 175   LoadFile is an exception as a load file size is set to zero.
 176
 177   @param  Stream    Open File Handle
 178
 179   @return 0         Stream is not an Open File or a valid LoadFile handle
 180
 181 **/
 182 UINTN
 183 EfiTell (
 184   IN  EFI_OPEN_FILE  *Stream,
 185   OUT UINT64         *CurrentPosition   OPTIONAL
 186   );
 187
 188 /**
 189   Seek to the Offset location in the file. LoadFile and FV device types do
 190   not support EfiSeek(). It is not possible to grow the file size using
 191   EfiSeek().
 192
 193   SeekType defines how use Offset to calculate the new file position:
 194   EfiSeekStart  : Position = Offset
 195   EfiSeekCurrent: Position is Offset bytes from the current position
 196   EfiSeekEnd    : Only supported if Offset is zero to seek to end of file.
 197
 198   @param  Stream    Open File Handle
 199   @param  Offset    Offset to seek too.
 200   @param  SeekType  Type of seek to perform
 201
 202
 203   @return EFI_INVALID_PARAMETER  Stream is not an Open File
 204   @return EFI_UNSUPPORTED        LoadFile and FV does not support Seek
 205   @return EFI_NOT_FOUND          Seek past the end of the file.
 206   @return EFI_SUCCESS            Steam closed
 207
 208 **/
 209 EFI_STATUS
 210 EfiSeek (
 211   IN  EFI_OPEN_FILE  *Stream,
 212   IN  EFI_LBA        Offset,
 213   IN  EFI_SEEK_TYPE  SeekType
 214   );
 215
 216 /**
 217   Read BufferSize bytes from the current location in the file. For load file
 218   and FV case you must read the entire file.
 219
 220   @param  Stream      Open File Handle
 221   @param  Buffer      Caller allocated buffer.
 222   @param  BufferSize  Size of buffer in bytes.
 223
 224
 225   @return EFI_SUCCESS           Stream is not an Open File
 226   @return EFI_END_OF_FILE Tried to read past the end of the file
 227   @return EFI_INVALID_PARAMETER Stream is not an open file handle
 228   @return EFI_BUFFER_TOO_SMALL  Buffer is not big enough to do the read
 229   @return "other"               Error returned from device read
 230
 231 **/
 232 EFI_STATUS
 233 EfiRead (
 234   IN  EFI_OPEN_FILE  *Stream,
 235   OUT VOID           *Buffer,
 236   OUT UINTN          *BufferSize
 237   );
 238
 239 /**
 240   Read the entire file into a buffer. This routine allocates the buffer and
 241   returns it to the user full of the read data.
 242
 243   This is very useful for load file where it's hard to know how big the buffer
 244   must be.
 245
 246   @param  Stream      Open File Handle
 247   @param  Buffer      Pointer to buffer to return.
 248   @param  BufferSize  Pointer to Size of buffer return..
 249
 250
 251   @return EFI_SUCCESS           Stream is not an Open File
 252   @return EFI_END_OF_FILE       Tried to read past the end of the file
 253   @return EFI_INVALID_PARAMETER Stream is not an open file handle
 254   @return EFI_BUFFER_TOO_SMALL  Buffer is not big enough to do the read
 255   @return "other"               Error returned from device read
 256
 257 **/
 258 EFI_STATUS
 259 EfiReadAllocatePool (
 260   IN  EFI_OPEN_FILE  *Stream,
 261   OUT VOID           **Buffer,
 262   OUT UINTN          *BufferSize
 263   );
 264
 265 /**
 266   Write data back to the file.
 267
 268   @param  Stream      Open File Handle
 269   @param  Buffer      Pointer to buffer to return.
 270   @param  BufferSize  Pointer to Size of buffer return..
 271
 272
 273   @return EFI_SUCCESS           Stream is not an Open File
 274   @return EFI_END_OF_FILE       Tried to read past the end of the file
 275   @return EFI_INVALID_PARAMETER Stream is not an open file handle
 276   @return EFI_BUFFER_TOO_SMALL  Buffer is not big enough to do the read
 277   @return "other"               Error returned from device write
 278
 279 **/
 280 EFI_STATUS
 281 EfiWrite (
 282   IN  EFI_OPEN_FILE  *Stream,
 283   OUT VOID           *Buffer,
 284   OUT UINTN          *BufferSize
 285   );
 286
 287 /**
 288   Return the number of devices of the current type active in the system
 289
 290   @param  Type      Device type to check
 291
 292   @return 0         Invalid type
 293
 294 **/
 295 UINTN
 296 EfiGetDeviceCounts (
 297   IN  EFI_OPEN_FILE_TYPE  Type
 298   );
 299
 300 /**
 301   Set the Current Working Directory (CWD). If a call is made to EfiOpen () and
 302   the path does not contain a device name, The CWD is prepended to the path.
 303
 304   @param  Cwd     Current Working Directory to set
 305
 306
 307   @return EFI_SUCCESS           CWD is set
 308   @return EFI_INVALID_PARAMETER Cwd is not a valid device:path
 309
 310 **/
 311 EFI_STATUS
 312 EfiSetCwd (
 313   IN  CHAR8  *Cwd
 314   );
 315
 316 /**
 317   Set the Current Working Directory (CWD). If a call is made to EfiOpen () and
 318   the path does not contain a device name, The CWD is prepended to the path.
 319
 320   @param  Cwd     Current Working Directory
 321
 322
 323   @return NULL    No CWD set
 324   @return 'other' malloc'ed buffer contains CWD.
 325
 326 **/
 327 CHAR8 *
 328 EfiGetCwd (
 329   VOID
 330   );
 331
 332 #endif