EmbeddedPkg/Include/Library/EfiFileLib.h

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