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