X-Git-Url: https://git.proxmox.com/?p=mirror_edk2.git;a=blobdiff_plain;f=EmbeddedPkg%2FInclude%2FLibrary%2FEfiFileLib.h;h=0544b6e2006d51f7a022a395aa2c96787d9096a9;hp=9ec5246358f3eeef998412f8f9c3ec9a27aa144e;hb=HEAD;hpb=208a8330d0029d4025f6f27f182d627bd9d7b38b diff --git a/EmbeddedPkg/Include/Library/EfiFileLib.h b/EmbeddedPkg/Include/Library/EfiFileLib.h index 9ec5246358..bae19ec78a 100644 --- a/EmbeddedPkg/Include/Library/EfiFileLib.h +++ b/EmbeddedPkg/Include/Library/EfiFileLib.h @@ -1,24 +1,18 @@ /** @file - Library functions that perform file IO. Memory buffer, file system, and - fimrware volume operations are supproted. + Library functions that perform file IO. Memory buffer, file system, and + firmware volume operations are supported. Copyright (c) 2007, Intel Corporation. All rights reserved.
Portions copyright (c) 2008 - 2009, Apple Inc. All rights reserved.
- This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php - - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + SPDX-License-Identifier: BSD-2-Clause-Patent Basic support for opening files on different device types. The device string is in the form of DevType:Path. Current DevType is required as there is no current mounted device concept of current working directory concept implement by this library. - Device names are case insensative and only check the leading characters for + Device names are case insensitive and only check the leading characters for unique matches. Thus the following are all the same: LoadFile0: l0: @@ -30,9 +24,9 @@ l1: - EFI LoadFile device one. B0: - EFI BlockIo zero. fs3: - EFI Simple File System device 3 - Fv2: - EFI Firmware VOlume device 2 + Fv2: - EFI Firmware Volume device 2 1.2.3.4:name - TFTP IP and file name - + **/ #ifndef __EFI_FILE_LIB_H__ @@ -48,9 +42,9 @@ #include #include -#define MAX_PATHNAME 0x200 +#define MAX_PATHNAME 0x200 -/// Type of the file that has been opened +/// Type of the file that has been opened typedef enum { EfiOpenLoadFile, EfiOpenMemoryBuffer, @@ -61,51 +55,48 @@ typedef enum { EfiOpenMaxValue } EFI_OPEN_FILE_TYPE; - /// Public information about the open file typedef struct { - UINTN Version; // Common information - EFI_OPEN_FILE_TYPE Type; - EFI_DEVICE_PATH_PROTOCOL *DevicePath; - EFI_STATUS LastError; - EFI_HANDLE EfiHandle; - CHAR8 *DeviceName; - CHAR8 *FileName; - - UINT64 CurrentPosition; // Information for Seek - UINT64 MaxPosition; - - UINTN BaseOffset; // Base offset for hexdump command - - UINTN Size; // Valid for all types other than l#: - UINT8 *Buffer; // Information valid for A#: - - EFI_FIRMWARE_VOLUME2_PROTOCOL *Fv; // Information valid for Fv#: - EFI_GUID FvNameGuid; - EFI_SECTION_TYPE FvSectionType; - EFI_FV_FILETYPE FvType; - EFI_FV_FILE_ATTRIBUTES FvAttributes; - - EFI_PHYSICAL_ADDRESS FvStart; - UINTN FvSize; - UINTN FvHeaderSize; - - EFI_FILE *FsFileHandle; // Information valid for Fs#: - EFI_FILE_SYSTEM_INFO *FsInfo; - EFI_FILE_INFO *FsFileInfo; - EFI_BLOCK_IO_MEDIA *FsBlockIoMedia; // Information valid for Fs#: or B#: - EFI_BLOCK_IO_PROTOCOL *FsBlockIo; // Information valid for Fs#: or B#: - - UINTN DiskOffset; // Information valid for B#: - - EFI_LOAD_FILE_PROTOCOL *LoadFile; // Information valid for l#: - - EFI_IP_ADDRESS ServerIp; // Information valid for t: - BOOLEAN IsDirty; - BOOLEAN IsBufferValid; - -} EFI_OPEN_FILE; + UINTN Version; // Common information + EFI_OPEN_FILE_TYPE Type; + EFI_DEVICE_PATH_PROTOCOL *DevicePath; + EFI_STATUS LastError; + EFI_HANDLE EfiHandle; + CHAR8 *DeviceName; + CHAR8 *FileName; + + UINT64 CurrentPosition; // Information for Seek + UINT64 MaxPosition; + + UINTN BaseOffset; // Base offset for hexdump command + + UINTN Size; // Valid for all types other than l#: + UINT8 *Buffer; // Information valid for A#: + EFI_FIRMWARE_VOLUME2_PROTOCOL *Fv; // Information valid for Fv#: + EFI_GUID FvNameGuid; + EFI_SECTION_TYPE FvSectionType; + EFI_FV_FILETYPE FvType; + EFI_FV_FILE_ATTRIBUTES FvAttributes; + + EFI_PHYSICAL_ADDRESS FvStart; + UINTN FvSize; + UINTN FvHeaderSize; + + EFI_FILE *FsFileHandle; // Information valid for Fs#: + EFI_FILE_SYSTEM_INFO *FsInfo; + EFI_FILE_INFO *FsFileInfo; + EFI_BLOCK_IO_MEDIA *FsBlockIoMedia; // Information valid for Fs#: or B#: + EFI_BLOCK_IO_PROTOCOL *FsBlockIo; // Information valid for Fs#: or B#: + + UINTN DiskOffset; // Information valid for B#: + + EFI_LOAD_FILE_PROTOCOL *LoadFile; // Information valid for l#: + + EFI_IP_ADDRESS ServerIp; // Information valid for t: + BOOLEAN IsDirty; + BOOLEAN IsBufferValid; +} EFI_OPEN_FILE; /// Type of Seek to perform typedef enum { @@ -115,19 +106,18 @@ typedef enum { EfiSeekMax } EFI_SEEK_TYPE; - /** - Open a device named by PathName. The PathName includes a device name and - path seperated by a :. See file header for more details on the PathName + Open a device named by PathName. The PathName includes a device name and + path separated by a :. See file header for more details on the PathName syntax. There is no checking to prevent a file from being opened more than - one type. + one type. SectionType is only used to open an FV. Each file in an FV contains multiple - secitons and only the SectionType section is opened. + sections and only the SectionType section is opened. For any file that is opened with EfiOpen() must be closed with EfiClose(). - @param PathName Path to parse to open + @param PathName Path to parse to open @param OpenMode Same as EFI_FILE.Open() @param SectionType Section in FV to open. @@ -137,15 +127,15 @@ typedef enum { **/ EFI_OPEN_FILE * EfiOpen ( - IN CHAR8 *PathName, - IN CONST UINT64 OpenMode, - IN CONST EFI_SECTION_TYPE SectionType + IN CHAR8 *PathName, + IN CONST UINT64 OpenMode, + IN CONST EFI_SECTION_TYPE SectionType ); EFI_STATUS EfiCopyFile ( - IN CHAR8 *DestinationFile, - IN CHAR8 *SourceFile + IN CHAR8 *DestinationFile, + IN CHAR8 *SourceFile ); /** @@ -160,11 +150,10 @@ EfiCopyFile ( **/ EFI_OPEN_FILE * EfiDeviceOpenByType ( - IN EFI_OPEN_FILE_TYPE DeviceType, - IN UINTN Index + IN EFI_OPEN_FILE_TYPE DeviceType, + IN UINTN Index ); - /** Close a file handle opened by EfiOpen() and free all resources allocated by EfiOpen(). @@ -177,14 +166,13 @@ EfiDeviceOpenByType ( **/ EFI_STATUS EfiClose ( - IN EFI_OPEN_FILE *Stream + IN EFI_OPEN_FILE *Stream ); - /** - Return the size of the file represented by Stream. Also return the current + Return the size of the file represented by Stream. Also return the current Seek position. Opening a file will enable a valid file size to be returned. - LoadFile is an exception as a load file size is set to zero. + LoadFile is an exception as a load file size is set to zero. @param Stream Open File Handle @@ -193,46 +181,44 @@ EfiClose ( **/ UINTN EfiTell ( - IN EFI_OPEN_FILE *Stream, - OUT UINT64 *CurrentPosition OPTIONAL + IN EFI_OPEN_FILE *Stream, + OUT UINT64 *CurrentPosition OPTIONAL ); - /** - Seek to the Offset locaiton in the file. LoadFile and FV device types do - not support EfiSeek(). It is not possible to grow the file size using + Seek to the Offset location in the file. LoadFile and FV device types do + not support EfiSeek(). It is not possible to grow the file size using EfiSeek(). - + SeekType defines how use Offset to calculate the new file position: EfiSeekStart : Position = Offset EfiSeekCurrent: Position is Offset bytes from the current position EfiSeekEnd : Only supported if Offset is zero to seek to end of file. @param Stream Open File Handle - @param Offset Offset to seek too. + @param Offset Offset to seek too. @param SeekType Type of seek to perform @return EFI_INVALID_PARAMETER Stream is not an Open File - @return EFI_UNSUPPORTED LoadFile and FV doe not support Seek + @return EFI_UNSUPPORTED LoadFile and FV does not support Seek @return EFI_NOT_FOUND Seek past the end of the file. @return EFI_SUCCESS Steam closed **/ EFI_STATUS EfiSeek ( - IN EFI_OPEN_FILE *Stream, - IN EFI_LBA Offset, - IN EFI_SEEK_TYPE SeekType + IN EFI_OPEN_FILE *Stream, + IN EFI_LBA Offset, + IN EFI_SEEK_TYPE SeekType ); - /** - Read BufferSize bytes from the current locaiton in the file. For load file - and FV case you must read the entire file. + Read BufferSize bytes from the current location in the file. For load file + and FV case you must read the entire file. @param Stream Open File Handle - @param Buffer Caller allocated buffer. + @param Buffer Caller allocated buffer. @param BufferSize Size of buffer in bytes. @@ -245,21 +231,20 @@ EfiSeek ( **/ EFI_STATUS EfiRead ( - IN EFI_OPEN_FILE *Stream, - OUT VOID *Buffer, - OUT UINTN *BufferSize + IN EFI_OPEN_FILE *Stream, + OUT VOID *Buffer, + OUT UINTN *BufferSize ); - /** Read the entire file into a buffer. This routine allocates the buffer and - returns it to the user full of the read data. + returns it to the user full of the read data. - This is very useful for load flie where it's hard to know how big the buffer + This is very useful for load file where it's hard to know how big the buffer must be. @param Stream Open File Handle - @param Buffer Pointer to buffer to return. + @param Buffer Pointer to buffer to return. @param BufferSize Pointer to Size of buffer return.. @@ -272,17 +257,16 @@ EfiRead ( **/ EFI_STATUS EfiReadAllocatePool ( - IN EFI_OPEN_FILE *Stream, - OUT VOID **Buffer, - OUT UINTN *BufferSize + IN EFI_OPEN_FILE *Stream, + OUT VOID **Buffer, + OUT UINTN *BufferSize ); - /** - Write data back to the file. + Write data back to the file. @param Stream Open File Handle - @param Buffer Pointer to buffer to return. + @param Buffer Pointer to buffer to return. @param BufferSize Pointer to Size of buffer return.. @@ -295,12 +279,11 @@ EfiReadAllocatePool ( **/ EFI_STATUS EfiWrite ( - IN EFI_OPEN_FILE *Stream, - OUT VOID *Buffer, - OUT UINTN *BufferSize + IN EFI_OPEN_FILE *Stream, + OUT VOID *Buffer, + OUT UINTN *BufferSize ); - /** Return the number of devices of the current type active in the system @@ -311,14 +294,13 @@ EfiWrite ( **/ UINTN EfiGetDeviceCounts ( - IN EFI_OPEN_FILE_TYPE Type + IN EFI_OPEN_FILE_TYPE Type ); - /** - Set the Curent Working Directory (CWD). If a call is made to EfiOpen () and + Set the Current Working Directory (CWD). If a call is made to EfiOpen () and the path does not contain a device name, The CWD is prepended to the path. - + @param Cwd Current Working Directory to set @@ -328,23 +310,23 @@ EfiGetDeviceCounts ( **/ EFI_STATUS EfiSetCwd ( - IN CHAR8 *Cwd - ); + IN CHAR8 *Cwd + ); /** - Set the Curent Working Directory (CWD). If a call is made to EfiOpen () and + Set the Current Working Directory (CWD). If a call is made to EfiOpen () and the path does not contain a device name, The CWD is prepended to the path. - - @param Cwd Current Working Directory + + @param Cwd Current Working Directory @return NULL No CWD set @return 'other' malloc'ed buffer contains CWD. - + **/ CHAR8 * EfiGetCwd ( VOID - ); + ); #endif