2b3687dbb5
git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@10404 6f19259b-4bc3-4df7-8a09-765794883524
347 lines
15 KiB
C
347 lines
15 KiB
C
/** @file
|
|
This file declares the Firmware Volume Protocol.
|
|
|
|
The Firmware Volume Protocol provides file-level access to the firmware volume.
|
|
Each firmware volume driver must produce an instance of the Firmware Volume
|
|
Protocol if the firmware volume is to be visible to the system. The Firmware
|
|
Volume Protocol also provides mechanisms for determining and modifying some
|
|
attributes of the firmware volume.
|
|
|
|
Copyright (c) 2007 - 2010, Intel Corporation. All rights reserved.<BR>
|
|
This program and the accompanying materials are licensed and made available under
|
|
the terms and conditions of the BSD License that 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.
|
|
|
|
@par Revision Reference:
|
|
This protocol is defined in Firmware Volume specification.
|
|
Version 0.9.
|
|
|
|
**/
|
|
|
|
#ifndef _FIRMWARE_VOLUME_H_
|
|
#define _FIRMWARE_VOLUME_H_
|
|
|
|
|
|
//
|
|
// Firmware Volume Protocol GUID definition
|
|
//
|
|
#define EFI_FIRMWARE_VOLUME_PROTOCOL_GUID \
|
|
{ \
|
|
0x389F751F, 0x1838, 0x4388, {0x83, 0x90, 0xCD, 0x81, 0x54, 0xBD, 0x27, 0xF8 } \
|
|
}
|
|
|
|
#define FV_DEVICE_SIGNATURE SIGNATURE_32 ('_', 'F', 'V', '_')
|
|
|
|
typedef struct _EFI_FIRMWARE_VOLUME_PROTOCOL EFI_FIRMWARE_VOLUME_PROTOCOL;
|
|
|
|
//
|
|
// FRAMEWORK_EFI_FV_ATTRIBUTES bit definitions
|
|
//
|
|
typedef UINT64 FRAMEWORK_EFI_FV_ATTRIBUTES;
|
|
|
|
//
|
|
// ************************************************************
|
|
// FRAMEWORK_EFI_FV_ATTRIBUTES bit definitions
|
|
// ************************************************************
|
|
//
|
|
#define EFI_FV_READ_DISABLE_CAP 0x0000000000000001ULL
|
|
#define EFI_FV_READ_ENABLE_CAP 0x0000000000000002ULL
|
|
#define EFI_FV_READ_STATUS 0x0000000000000004ULL
|
|
|
|
#define EFI_FV_WRITE_DISABLE_CAP 0x0000000000000008ULL
|
|
#define EFI_FV_WRITE_ENABLE_CAP 0x0000000000000010ULL
|
|
#define EFI_FV_WRITE_STATUS 0x0000000000000020ULL
|
|
|
|
#define EFI_FV_LOCK_CAP 0x0000000000000040ULL
|
|
#define EFI_FV_LOCK_STATUS 0x0000000000000080ULL
|
|
#define EFI_FV_WRITE_POLICY_RELIABLE 0x0000000000000100ULL
|
|
|
|
#define EFI_FV_ALIGNMENT_CAP 0x0000000000008000ULL
|
|
#define EFI_FV_ALIGNMENT_2 0x0000000000010000ULL
|
|
#define EFI_FV_ALIGNMENT_4 0x0000000000020000ULL
|
|
#define EFI_FV_ALIGNMENT_8 0x0000000000040000ULL
|
|
#define EFI_FV_ALIGNMENT_16 0x0000000000080000ULL
|
|
#define EFI_FV_ALIGNMENT_32 0x0000000000100000ULL
|
|
#define EFI_FV_ALIGNMENT_64 0x0000000000200000ULL
|
|
#define EFI_FV_ALIGNMENT_128 0x0000000000400000ULL
|
|
#define EFI_FV_ALIGNMENT_256 0x0000000000800000ULL
|
|
#define EFI_FV_ALIGNMENT_512 0x0000000001000000ULL
|
|
#define EFI_FV_ALIGNMENT_1K 0x0000000002000000ULL
|
|
#define EFI_FV_ALIGNMENT_2K 0x0000000004000000ULL
|
|
#define EFI_FV_ALIGNMENT_4K 0x0000000008000000ULL
|
|
#define EFI_FV_ALIGNMENT_8K 0x0000000010000000ULL
|
|
#define EFI_FV_ALIGNMENT_16K 0x0000000020000000ULL
|
|
#define EFI_FV_ALIGNMENT_32K 0x0000000040000000ULL
|
|
#define EFI_FV_ALIGNMENT_64K 0x0000000080000000ULL
|
|
|
|
//
|
|
// Protocol API definitions
|
|
//
|
|
|
|
/**
|
|
Retrieves attributes, insures positive polarity of attribute bits, and returns
|
|
resulting attributes in an output parameter.
|
|
|
|
@param This Indicates the EFI_FIRMWARE_VOLUME_PROTOCOL instance.
|
|
@param Attributes Output buffer containing attributes.
|
|
|
|
@retval EFI_SUCCESS The firmware volume attributes were returned.
|
|
**/
|
|
typedef
|
|
EFI_STATUS
|
|
(EFIAPI *FRAMEWORK_EFI_FV_GET_ATTRIBUTES)(
|
|
IN EFI_FIRMWARE_VOLUME_PROTOCOL *This,
|
|
OUT FRAMEWORK_EFI_FV_ATTRIBUTES *Attributes
|
|
);
|
|
|
|
/**
|
|
Sets volume attributes
|
|
|
|
@param This Indicates the EFI_FIRMWARE_VOLUME_PROTOCOL instance.
|
|
@param Attributes On input, Attributes is a pointer to an
|
|
EFI_FV_ATTRIBUTES containing the desired firmware
|
|
volume settings. On successful return, it contains
|
|
the new settings of the firmware volume. On
|
|
unsuccessful return, Attributes is not modified
|
|
and the firmware volume settings are not changed.
|
|
|
|
@retval EFI_INVALID_PARAMETER A bit in Attributes was invalid.
|
|
@retval EFI_SUCCESS The requested firmware volume attributes were set
|
|
and the resulting EFI_FV_ATTRIBUTES is returned in
|
|
Attributes.
|
|
@retval EFI_ACCESS_DENIED The Device is locked and does not permit modification.
|
|
|
|
**/
|
|
typedef
|
|
EFI_STATUS
|
|
(EFIAPI *FRAMEWORK_EFI_FV_SET_ATTRIBUTES)(
|
|
IN EFI_FIRMWARE_VOLUME_PROTOCOL *This,
|
|
IN OUT FRAMEWORK_EFI_FV_ATTRIBUTES *Attributes
|
|
);
|
|
|
|
/**
|
|
Read the requested file (NameGuid) or file information from the firmware volume
|
|
and returns data in Buffer.
|
|
|
|
@param This The EFI_FIRMWARE_VOLUME_PROTOCOL instance.
|
|
@param NameGuid The pointer to EFI_GUID, which is the filename of
|
|
the file to read.
|
|
@param Buffer The pointer to pointer to buffer in which contents of file are returned.
|
|
<br>
|
|
If Buffer is NULL, only type, attributes, and size
|
|
are returned as there is no output buffer.
|
|
<br>
|
|
If Buffer != NULL and *Buffer == NULL, the output
|
|
buffer is allocated from BS pool by ReadFile.
|
|
<br>
|
|
If Buffer != NULL and *Buffer != NULL, the output
|
|
buffer has been allocated by the caller and is being
|
|
passed in.
|
|
@param BufferSize On input: The buffer size. On output: The size
|
|
required to complete the read.
|
|
@param FoundType The pointer to the type of the file whose data
|
|
is returned.
|
|
@param FileAttributes The pointer to attributes of the file whose data
|
|
is returned.
|
|
@param AuthenticationStatus The pointer to the authentication status of the data.
|
|
|
|
@retval EFI_SUCCESS The call completed successfully.
|
|
@retval EFI_WARN_BUFFER_TOO_SMALL The buffer is too small to contain the requested output.
|
|
The buffer filled, and the output is truncated.
|
|
@retval EFI_NOT_FOUND NameGuid was not found in the firmware volume.
|
|
@retval EFI_DEVICE_ERROR A hardware error occurred when attempting to
|
|
access the firmware volume.
|
|
@retval EFI_ACCESS_DENIED The firmware volume is configured to disallow reads.
|
|
@retval EFI_OUT_OF_RESOURCES An allocation failure occurred.
|
|
|
|
**/
|
|
typedef
|
|
EFI_STATUS
|
|
(EFIAPI *FRAMEWORK_EFI_FV_READ_FILE)(
|
|
IN EFI_FIRMWARE_VOLUME_PROTOCOL *This,
|
|
IN EFI_GUID *NameGuid,
|
|
IN OUT VOID **Buffer,
|
|
IN OUT UINTN *BufferSize,
|
|
OUT EFI_FV_FILETYPE *FoundType,
|
|
OUT EFI_FV_FILE_ATTRIBUTES *FileAttributes,
|
|
OUT UINT32 *AuthenticationStatus
|
|
);
|
|
|
|
/**
|
|
Read the requested section from the specified file and returns data in Buffer.
|
|
|
|
@param This Indicates the EFI_FIRMWARE_VOLUME_PROTOCOL instance.
|
|
@param NameGuid Filename identifying the file from which to read.
|
|
@param SectionType The section type to retrieve.
|
|
@param SectionInstance The instance of SectionType to retrieve.
|
|
@param Buffer Pointer to pointer to buffer in which contents of
|
|
a file are returned.
|
|
<br>
|
|
If Buffer is NULL, only type, attributes, and size
|
|
are returned as there is no output buffer.
|
|
<br>
|
|
If Buffer != NULL and *Buffer == NULL, the output
|
|
buffer is allocated from BS pool by ReadFile.
|
|
<br>
|
|
If Buffer != NULL and *Buffer != NULL, the output
|
|
buffer has been allocated by the caller and is being
|
|
passed in.
|
|
@param BufferSize The pointer to the buffer size passed in, and on
|
|
output the size required to complete the read.
|
|
@param AuthenticationStatus The pointer to the authentication status of the data.
|
|
|
|
@retval EFI_SUCCESS The call completed successfully.
|
|
@retval EFI_WARN_BUFFER_TOO_SMALL The buffer is too small to contain the requested output.
|
|
The buffer is filled and the output is truncated.
|
|
@retval EFI_OUT_OF_RESOURCES An allocation failure occurred.
|
|
@retval EFI_NOT_FOUND The name was not found in the firmware volume.
|
|
@retval EFI_DEVICE_ERROR A hardware error occurred when attempting to
|
|
access the firmware volume.
|
|
@retval EFI_ACCESS_DENIED The firmware volume is configured to disallow reads.
|
|
|
|
**/
|
|
typedef
|
|
EFI_STATUS
|
|
(EFIAPI *FRAMEWORK_EFI_FV_READ_SECTION)(
|
|
IN EFI_FIRMWARE_VOLUME_PROTOCOL *This,
|
|
IN EFI_GUID *NameGuid,
|
|
IN EFI_SECTION_TYPE SectionType,
|
|
IN UINTN SectionInstance,
|
|
IN OUT VOID **Buffer,
|
|
IN OUT UINTN *BufferSize,
|
|
OUT UINT32 *AuthenticationStatus
|
|
);
|
|
|
|
typedef UINT32 FRAMEWORK_EFI_FV_WRITE_POLICY;
|
|
|
|
#define FRAMEWORK_EFI_FV_UNRELIABLE_WRITE 0x00000000
|
|
#define FRAMEWORK_EFI_FV_RELIABLE_WRITE 0x00000001
|
|
|
|
typedef struct {
|
|
EFI_GUID *NameGuid;
|
|
EFI_FV_FILETYPE Type;
|
|
EFI_FV_FILE_ATTRIBUTES FileAttributes;
|
|
VOID *Buffer;
|
|
UINT32 BufferSize;
|
|
} FRAMEWORK_EFI_FV_WRITE_FILE_DATA;
|
|
|
|
/**
|
|
Write the supplied file (NameGuid) to the FV.
|
|
|
|
@param This Indicates the EFI_FIRMWARE_VOLUME_PROTOCOL instance.
|
|
@param NumberOfFiles Indicates the number of file records pointed to
|
|
by FileData.
|
|
@param WritePolicy Indicates the level of reliability of the write
|
|
with respect to things like power failure events.
|
|
@param FileData A pointer to an array of EFI_FV_WRITE_FILE_DATA
|
|
structures. Each element in the array indicates
|
|
a file to write, and there are NumberOfFiles
|
|
elements in the input array.
|
|
|
|
@retval EFI_SUCCESS The write completed successfully.
|
|
@retval EFI_OUT_OF_RESOURCES The firmware volume does not have enough free
|
|
space to store file(s).
|
|
@retval EFI_DEVICE_ERROR A hardware error occurred when attempting to
|
|
access the firmware volume.
|
|
@retval EFI_WRITE_PROTECTED The firmware volume is configured to disallow writes.
|
|
@retval EFI_NOT_FOUND A delete was requested, but the requested file was
|
|
not found in the firmware volume.
|
|
@retval EFI_INVALID_PARAMETER A delete was requested with a multiple file write.
|
|
An unsupported WritePolicy was requested.
|
|
An unknown file type was specified.
|
|
A file system specific error has occurred.
|
|
**/
|
|
typedef
|
|
EFI_STATUS
|
|
(EFIAPI *FRAMEWORK_EFI_FV_WRITE_FILE)(
|
|
IN EFI_FIRMWARE_VOLUME_PROTOCOL *This,
|
|
IN UINT32 NumberOfFiles,
|
|
IN FRAMEWORK_EFI_FV_WRITE_POLICY WritePolicy,
|
|
IN FRAMEWORK_EFI_FV_WRITE_FILE_DATA *FileData
|
|
);
|
|
|
|
/**
|
|
Given the input key, search for the next matching file in the volume.
|
|
|
|
@param This Indicates the EFI_FIRMWARE_VOLUME_PROTOCOL instance.
|
|
@param Key Pointer to a caller allocated buffer that contains
|
|
an implementation-specific key that is used to track
|
|
where to begin searching on successive calls.
|
|
@param FileType The pointer to the file type to filter for.
|
|
@param NameGuid The pointer to Guid filename of the file found.
|
|
@param Attributes The pointer to Attributes of the file found.
|
|
@param Size The pointer to Size in bytes of the file found.
|
|
|
|
@retval EFI_SUCCESS The output parameters are filled with data obtained from
|
|
the first matching file that was found.
|
|
@retval EFI_NOT_FOUND No files of type FileType were found.
|
|
@retval EFI_DEVICE_ERROR A hardware error occurred when attempting to access
|
|
the firmware volume.
|
|
@retval EFI_ACCESS_DENIED The firmware volume is configured to disallow reads.
|
|
|
|
**/
|
|
typedef
|
|
EFI_STATUS
|
|
(EFIAPI *FRAMEWORK_EFI_FV_GET_NEXT_FILE)(
|
|
IN EFI_FIRMWARE_VOLUME_PROTOCOL *This,
|
|
IN OUT VOID *Key,
|
|
IN OUT EFI_FV_FILETYPE *FileType,
|
|
OUT EFI_GUID *NameGuid,
|
|
OUT EFI_FV_FILE_ATTRIBUTES *Attributes,
|
|
OUT UINTN *Size
|
|
);
|
|
|
|
//
|
|
// Protocol interface structure
|
|
//
|
|
struct _EFI_FIRMWARE_VOLUME_PROTOCOL {
|
|
///
|
|
/// Retrieves volume capabilities and current settings.
|
|
///
|
|
FRAMEWORK_EFI_FV_GET_ATTRIBUTES GetVolumeAttributes;
|
|
|
|
///
|
|
/// Modifies the current settings of the firmware volume.
|
|
///
|
|
FRAMEWORK_EFI_FV_SET_ATTRIBUTES SetVolumeAttributes;
|
|
|
|
///
|
|
/// Reads an entire file from the firmware volume.
|
|
///
|
|
FRAMEWORK_EFI_FV_READ_FILE ReadFile;
|
|
|
|
///
|
|
/// Reads a single section from a file into a buffer.
|
|
///
|
|
FRAMEWORK_EFI_FV_READ_SECTION ReadSection;
|
|
|
|
///
|
|
/// Writes an entire file into the firmware volume.
|
|
///
|
|
FRAMEWORK_EFI_FV_WRITE_FILE WriteFile;
|
|
|
|
///
|
|
/// Provides service to allow searching the firmware volume.
|
|
///
|
|
FRAMEWORK_EFI_FV_GET_NEXT_FILE GetNextFile;
|
|
|
|
///
|
|
/// Data field that indicates the size in bytes of the Key input buffer for
|
|
/// the GetNextFile() API.
|
|
///
|
|
UINT32 KeySize;
|
|
|
|
///
|
|
/// Handle of the parent firmware volume.
|
|
///
|
|
EFI_HANDLE ParentHandle;
|
|
};
|
|
|
|
extern EFI_GUID gEfiFirmwareVolumeProtocolGuid;
|
|
|
|
#endif
|