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<BR>
   6   Portions copyright (c) 2008-2009 Apple Inc. All rights reserved.<BR>
   7
   8   All rights reserved. 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
  92   EFI_FILE                      *FsFileHandle;    // Information valid for Fs#:
  93   EFI_FILE_SYSTEM_INFO          *FsInfo;
  94   EFI_FILE_INFO                 *FsFileInfo;
  95   EFI_BLOCK_IO_MEDIA            FsBlockIoMedia;   // Information valid for Fs#: or B#:
  96
  97   UINTN                         DiskOffset;       // Information valid for B#:
  98
  99   EFI_LOAD_FILE_PROTOCOL        *LoadFile;        // Information valid for l#:
 100
 101   EFI_IP_ADDRESS                ServerIp;         // Information valid for t:
 102   BOOLEAN                       IsDirty;
 103   BOOLEAN                       IsBufferValid;
 104
 105 } EFI_OPEN_FILE;
 106
 107
 108 /// Type of Seek to perform
 109 typedef enum {
 110   EfiSeekStart,
 111   EfiSeekCurrent,
 112   EfiSeekEnd,
 113   EfiSeekMax
 114 } EFI_SEEK_TYPE;
 115
 116
 117 /**
 118   Open a device named by PathName. The PathName includes a device name and
 119   path seperated by a :. See file header for more details on the PathName
 120   syntax. There is no checking to prevent a file from being opened more than
 121   one type.
 122
 123   SectionType is only used to open an FV. Each file in an FV contains multiple
 124   secitons and only the SectionType section is opened.
 125
 126   For any file that is opened with EfiOpen() must be closed with EfiClose().
 127
 128   @param  PathName    Path to parse to open
 129   @param  OpenMode    Same as EFI_FILE.Open()
 130   @param  SectionType Section in FV to open.
 131
 132   @return NULL  Open failed
 133   @return Valid EFI_OPEN_FILE handle
 134
 135 **/
 136 EFI_OPEN_FILE *
 137 EfiOpen (
 138   IN        CHAR8               *PathName,
 139   IN  CONST UINT64              OpenMode,
 140   IN  CONST EFI_SECTION_TYPE    SectionType
 141   );
 142
 143 EFI_STATUS
 144 EfiCopyFile (
 145   IN        CHAR8               *DestinationFile,
 146   IN        CHAR8               *SourceFile
 147   );
 148
 149 /**
 150   Use DeviceType and Index to form a valid PathName and try and open it.
 151
 152   @param  DeviceType  Device type to open
 153   @param  Index       Device Index to use. Zero relative.
 154
 155   @return NULL  Open failed
 156   @return Valid EFI_OPEN_FILE handle
 157
 158 **/
 159 EFI_OPEN_FILE  *
 160 EfiDeviceOpenByType (
 161   IN  EFI_OPEN_FILE_TYPE    DeviceType,
 162   IN  UINTN                 Index
 163   );
 164
 165
 166 /**
 167   Close a file handle opened by EfiOpen() and free all resources allocated by
 168   EfiOpen().
 169
 170   @param  Stream    Open File Handle
 171
 172   @return EFI_INVALID_PARAMETER  Stream is not an Open File
 173   @return EFI_SUCCESS            Steam closed
 174
 175 **/
 176 EFI_STATUS
 177 EfiClose (
 178   IN  EFI_OPEN_FILE     *Stream
 179   );
 180
 181
 182 /**
 183   Return the size of the file represented by Stream. Also return the current
 184   Seek position. Opening a file will enable a valid file size to be returned.
 185   LoadFile is an exception as a load file size is set to zero.
 186
 187   @param  Stream    Open File Handle
 188
 189   @return 0         Stream is not an Open File or a valid LoadFile handle
 190
 191 **/
 192 UINTN
 193 EfiTell (
 194   IN  EFI_OPEN_FILE     *Stream,
 195   OUT UINT64            *CurrentPosition   OPTIONAL
 196   );
 197
 198
 199 /**
 200   Seek to the Offset locaiton in the file. LoadFile and FV device types do
 201   not support EfiSeek(). It is not possible to grow the file size using
 202   EfiSeek().
 203
 204   SeekType defines how use Offset to calculate the new file position:
 205   EfiSeekStart  : Position = Offset
 206   EfiSeekCurrent: Position is Offset bytes from the current position
 207   EfiSeekEnd    : Only supported if Offset is zero to seek to end of file.
 208
 209   @param  Stream    Open File Handle
 210   @param  Offset    Offset to seek too.
 211   @param  SeekType  Type of seek to perform
 212
 213
 214   @return EFI_INVALID_PARAMETER  Stream is not an Open File
 215   @return EFI_UNSUPPORTED        LoadFile and FV doe not support Seek
 216   @return EFI_NOT_FOUND          Seek past the end of the file.
 217   @return EFI_SUCCESS            Steam closed
 218
 219 **/
 220 EFI_STATUS
 221 EfiSeek (
 222   IN  EFI_OPEN_FILE     *Stream,
 223   IN  EFI_LBA           Offset,
 224   IN  EFI_SEEK_TYPE     SeekType
 225   );
 226
 227
 228 /**
 229   Read BufferSize bytes from the current locaiton in the file. For load file
 230   and FV case you must read the entire file.
 231
 232   @param  Stream      Open File Handle
 233   @param  Buffer      Caller allocated buffer.
 234   @param  BufferSize  Size of buffer in bytes.
 235
 236
 237   @return EFI_SUCCESS           Stream is not an Open File
 238   @return EFI_END_OF_FILE Tried to read past the end of the file
 239   @return EFI_INVALID_PARAMETER Stream is not an open file handle
 240   @return EFI_BUFFER_TOO_SMALL  Buffer is not big enough to do the read
 241   @return "other"               Error returned from device read
 242
 243 **/
 244 EFI_STATUS
 245 EfiRead (
 246   IN  EFI_OPEN_FILE     *Stream,
 247   OUT VOID              *Buffer,
 248   OUT UINTN             *BufferSize
 249   );
 250
 251
 252 /**
 253   Read the entire file into a buffer. This routine allocates the buffer and
 254   returns it to the user full of the read data.
 255
 256   This is very useful for load flie where it's hard to know how big the buffer
 257   must be.
 258
 259   @param  Stream      Open File Handle
 260   @param  Buffer      Pointer to buffer to return.
 261   @param  BufferSize  Pointer to Size of buffer return..
 262
 263
 264   @return EFI_SUCCESS           Stream is not an Open File
 265   @return EFI_END_OF_FILE       Tried to read past the end of the file
 266   @return EFI_INVALID_PARAMETER Stream is not an open file handle
 267   @return EFI_BUFFER_TOO_SMALL  Buffer is not big enough to do the read
 268   @return "other"               Error returned from device read
 269
 270 **/
 271 EFI_STATUS
 272 EfiReadAllocatePool (
 273   IN  EFI_OPEN_FILE     *Stream,
 274   OUT VOID              **Buffer,
 275   OUT UINTN             *BufferSize
 276   );
 277
 278
 279 /**
 280   Write data back to the file.
 281
 282   @param  Stream      Open File Handle
 283   @param  Buffer      Pointer to buffer to return.
 284   @param  BufferSize  Pointer to Size of buffer return..
 285
 286
 287   @return EFI_SUCCESS           Stream is not an Open File
 288   @return EFI_END_OF_FILE       Tried to read past the end of the file
 289   @return EFI_INVALID_PARAMETER Stream is not an open file handle
 290   @return EFI_BUFFER_TOO_SMALL  Buffer is not big enough to do the read
 291   @return "other"               Error returned from device write
 292
 293 **/
 294 EFI_STATUS
 295 EfiWrite (
 296   IN  EFI_OPEN_FILE   *Stream,
 297   OUT VOID            *Buffer,
 298   OUT UINTN           *BufferSize
 299   );
 300
 301
 302 /**
 303   Return the number of devices of the current type active in the system
 304
 305   @param  Type      Device type to check
 306
 307   @return 0         Invalid type
 308
 309 **/
 310 UINTN
 311 EfiGetDeviceCounts (
 312   IN  EFI_OPEN_FILE_TYPE     Type
 313   );
 314
 315 #endif