/** @file\r
- This file declares Firmware Volume protocol.\r
-\r
- Copyright (c) 2007, Intel Corporation\r
- All rights reserved. This program and the accompanying materials\r
- are licensed and made available under the terms and conditions of the BSD License\r
- which accompanies this distribution. The full text of the license may be found at\r
- http://opensource.org/licenses/bsd-license.php\r
-\r
- THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
- WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
+ This file declares the Firmware Volume Protocol.\r
+ \r
+ The Firmware Volume Protocol provides file-level access to the firmware volume.\r
+ Each firmware volume driver must produce an instance of the Firmware Volume\r
+ Protocol if the firmware volume is to be visible to the system. The Firmware\r
+ Volume Protocol also provides mechanisms for determining and modifying some\r
+ attributes of the firmware volume.\r
\r
- Module Name: FirmwareVolume.h\r
+Copyright (c) 2007 - 2010, Intel Corporation. All rights reserved<BR>\r
+This program and the accompanying materials are licensed and made available under \r
+the terms and conditions of the BSD License that accompanies this distribution. \r
+The full text of the license may be found at\r
+http://opensource.org/licenses/bsd-license.php. \r
+ \r
+THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, \r
+WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
\r
@par Revision Reference:\r
This protocol is defined in Firmware Volume specification.\r
- Version 0.9\r
+ Version 0.9.\r
\r
**/\r
\r
#ifndef _FIRMWARE_VOLUME_H_\r
#define _FIRMWARE_VOLUME_H_\r
\r
-#include <PiDxe.h>\r
\r
//\r
// Firmware Volume Protocol GUID definition\r
0x389F751F, 0x1838, 0x4388, {0x83, 0x90, 0xCD, 0x81, 0x54, 0xBD, 0x27, 0xF8 } \\r
}\r
\r
-#define FV_DEVICE_SIGNATURE EFI_SIGNATURE_32 ('_', 'F', 'V', '_')\r
+#define FV_DEVICE_SIGNATURE SIGNATURE_32 ('_', 'F', 'V', '_')\r
\r
typedef struct _EFI_FIRMWARE_VOLUME_PROTOCOL EFI_FIRMWARE_VOLUME_PROTOCOL;\r
\r
//\r
-// EFI_FV_ATTRIBUTES bit definitions\r
+// FRAMEWORK_EFI_FV_ATTRIBUTES bit definitions\r
//\r
-typedef UINT64 EFI_FV_ATTRIBUTES;\r
+typedef UINT64 FRAMEWORK_EFI_FV_ATTRIBUTES;\r
\r
//\r
// ************************************************************\r
-// EFI_FV_ATTRIBUTES bit definitions\r
+// FRAMEWORK_EFI_FV_ATTRIBUTES bit definitions\r
// ************************************************************\r
//\r
#define EFI_FV_READ_DISABLE_CAP 0x0000000000000001ULL\r
//\r
\r
/**\r
- Retrieves attributes, insures positive polarity of attribute bits, returns\r
- resulting attributes in output parameter\r
-\r
- @param This Calling context\r
- @param Attributes output buffer which contains attributes\r
+ Retrieves attributes, insures positive polarity of attribute bits, and returns\r
+ resulting attributes in an output parameter.\r
\r
- @retval EFI_INVALID_PARAMETER\r
- @retval EFI_SUCCESS\r
+ @param This Indicates the EFI_FIRMWARE_VOLUME_PROTOCOL instance.\r
+ @param Attributes Output buffer containing attributes.\r
\r
+ @retval EFI_SUCCESS The firmware volume attributes were returned.\r
**/\r
typedef\r
EFI_STATUS\r
-(EFIAPI *EFI_FV_GET_ATTRIBUTES) (\r
- IN EFI_FIRMWARE_VOLUME_PROTOCOL *This,\r
- OUT EFI_FV_ATTRIBUTES *Attributes\r
+(EFIAPI *FRAMEWORK_EFI_FV_GET_ATTRIBUTES)(\r
+ IN EFI_FIRMWARE_VOLUME_PROTOCOL *This,\r
+ OUT FRAMEWORK_EFI_FV_ATTRIBUTES *Attributes\r
);\r
\r
/**\r
Sets volume attributes\r
\r
- @param This Calling context\r
- @param Attributes Buffer which contains attributes\r
+ @param This Indicates the EFI_FIRMWARE_VOLUME_PROTOCOL instance.\r
+ @param Attributes On input, Attributes is a pointer to an \r
+ EFI_FV_ATTRIBUTES containing the desired firmware \r
+ volume settings. On successful return, it contains \r
+ the new settings of the firmware volume. On \r
+ unsuccessful return, Attributes is not modified \r
+ and the firmware volume settings are not changed.\r
\r
- @retval EFI_INVALID_PARAMETER\r
- @retval EFI_DEVICE_ERROR\r
- @retval EFI_SUCCESS\r
+ @retval EFI_INVALID_PARAMETER A bit in Attributes was invalid.\r
+ @retval EFI_SUCCESS The requested firmware volume attributes were set \r
+ and the resulting EFI_FV_ATTRIBUTES is returned in\r
+ Attributes.\r
+ @retval EFI_ACCESS_DENIED The Device is locked and does not permit modification. \r
\r
**/\r
typedef\r
EFI_STATUS\r
-(EFIAPI *EFI_FV_SET_ATTRIBUTES) (\r
- IN EFI_FIRMWARE_VOLUME_PROTOCOL *This,\r
- IN OUT EFI_FV_ATTRIBUTES *Attributes\r
+(EFIAPI *FRAMEWORK_EFI_FV_SET_ATTRIBUTES)(\r
+ IN EFI_FIRMWARE_VOLUME_PROTOCOL *This,\r
+ IN OUT FRAMEWORK_EFI_FV_ATTRIBUTES *Attributes\r
);\r
\r
/**\r
- Read the requested file (NameGuid) and returns data in Buffer.\r
+ Read the requested file (NameGuid) or file information from the firmware volume \r
+ and returns data in Buffer.\r
\r
- @param This Calling context\r
- @param NameGuid Filename identifying which file to read\r
- @param Buffer Pointer to pointer to buffer in which contents of file are returned.\r
+ @param This The EFI_FIRMWARE_VOLUME_PROTOCOL instance.\r
+ @param NameGuid The pointer to EFI_GUID, which is the filename of \r
+ the file to read.\r
+ @param Buffer The pointer to pointer to buffer in which contents of file are returned.\r
<br>\r
- If Buffer is NULL, only type, attributes, and size are returned as\r
- there is no output buffer.\r
+ If Buffer is NULL, only type, attributes, and size \r
+ are returned as there is no output buffer.\r
<br>\r
- If Buffer != NULL and *Buffer == NULL, the output buffer is allocated\r
- from BS pool by ReadFile\r
+ If Buffer != NULL and *Buffer == NULL, the output \r
+ buffer is allocated from BS pool by ReadFile.\r
<br>\r
- If Buffer != NULL and *Buffer != NULL, the output buffer has been\r
- allocated by the caller and is being passed in.\r
- @param BufferSize Indicates the buffer size passed in, and on output the size\r
- required to complete the read\r
- @param FoundType Indicates the type of the file who's data is returned\r
- @param FileAttributes Indicates the attributes of the file who's data is resturned\r
- @param AuthenticationStatus Indicates the authentication status of the data\r
-\r
- @retval EFI_SUCCESS\r
- @retval EFI_WARN_BUFFER_TOO_SMALL\r
- @retval EFI_NOT_FOUND\r
- @retval EFI_DEVICE_ERROR\r
- @retval EFI_ACCESS_DENIED\r
+ If Buffer != NULL and *Buffer != NULL, the output \r
+ buffer has been allocated by the caller and is being \r
+ passed in.\r
+ @param BufferSize On input: The buffer size. On output: The size\r
+ required to complete the read.\r
+ @param FoundType The pointer to the type of the file whose data \r
+ is returned.\r
+ @param FileAttributes The pointer to attributes of the file whose data\r
+ is returned.\r
+ @param AuthenticationStatus The pointer to the authentication status of the data.\r
+\r
+ @retval EFI_SUCCESS The call completed successfully.\r
+ @retval EFI_WARN_BUFFER_TOO_SMALL The buffer is too small to contain the requested output.\r
+ The buffer filled, and the output is truncated.\r
+ @retval EFI_NOT_FOUND NameGuid was not found in the firmware volume.\r
+ @retval EFI_DEVICE_ERROR A hardware error occurred when attempting to \r
+ access the firmware volume.\r
+ @retval EFI_ACCESS_DENIED The firmware volume is configured to disallow reads.\r
+ @retval EFI_OUT_OF_RESOURCES An allocation failure occurred.\r
\r
**/\r
typedef\r
EFI_STATUS\r
-(EFIAPI *EFI_FV_READ_FILE) (\r
+(EFIAPI *FRAMEWORK_EFI_FV_READ_FILE)(\r
IN EFI_FIRMWARE_VOLUME_PROTOCOL *This,\r
IN EFI_GUID *NameGuid,\r
IN OUT VOID **Buffer,\r
/**\r
Read the requested section from the specified file and returns data in Buffer.\r
\r
- @param This Calling context\r
- @param NameGuid Filename identifying the file from which to read\r
- @param SectionType Indicates what section type to retrieve\r
- @param SectionInstance Indicates which instance of SectionType to retrieve\r
- @param Buffer Pointer to pointer to buffer in which contents of file are returned.\r
+ @param This Indicates the EFI_FIRMWARE_VOLUME_PROTOCOL instance.\r
+ @param NameGuid Filename identifying the file from which to read.\r
+ @param SectionType The section type to retrieve.\r
+ @param SectionInstance The instance of SectionType to retrieve.\r
+ @param Buffer Pointer to pointer to buffer in which contents of \r
+ a file are returned.\r
<br>\r
- If Buffer is NULL, only type, attributes, and size are returned as\r
- there is no output buffer.\r
+ If Buffer is NULL, only type, attributes, and size\r
+ are returned as there is no output buffer.\r
<br>\r
- If Buffer != NULL and *Buffer == NULL, the output buffer is allocated\r
- from BS pool by ReadFile\r
+ If Buffer != NULL and *Buffer == NULL, the output \r
+ buffer is allocated from BS pool by ReadFile.\r
<br>\r
- If Buffer != NULL and *Buffer != NULL, the output buffer has been\r
- allocated by the caller and is being passed in.\r
- @param BufferSize Indicates the buffer size passed in, and on output the size\r
- required to complete the read\r
- @param AuthenticationStatus Indicates the authentication status of the data\r
-\r
- @retval EFI_SUCCESS\r
- @retval EFI_WARN_BUFFER_TOO_SMALL\r
- @retval EFI_OUT_OF_RESOURCES\r
- @retval EFI_NOT_FOUND\r
- @retval EFI_DEVICE_ERROR\r
- @retval EFI_ACCESS_DENIED\r
+ If Buffer != NULL and *Buffer != NULL, the output \r
+ buffer has been allocated by the caller and is being \r
+ passed in.\r
+ @param BufferSize The pointer to the buffer size passed in, and on \r
+ output the size required to complete the read.\r
+ @param AuthenticationStatus The pointer to the authentication status of the data.\r
+\r
+ @retval EFI_SUCCESS The call completed successfully.\r
+ @retval EFI_WARN_BUFFER_TOO_SMALL The buffer is too small to contain the requested output. \r
+ The buffer is filled and the output is truncated.\r
+ @retval EFI_OUT_OF_RESOURCES An allocation failure occurred.\r
+ @retval EFI_NOT_FOUND The name was not found in the firmware volume.\r
+ @retval EFI_DEVICE_ERROR A hardware error occurred when attempting to \r
+ access the firmware volume.\r
+ @retval EFI_ACCESS_DENIED The firmware volume is configured to disallow reads.\r
\r
**/\r
typedef\r
EFI_STATUS\r
-(EFIAPI *EFI_FV_READ_SECTION) (\r
+(EFIAPI *FRAMEWORK_EFI_FV_READ_SECTION)(\r
IN EFI_FIRMWARE_VOLUME_PROTOCOL *This,\r
IN EFI_GUID *NameGuid,\r
IN EFI_SECTION_TYPE SectionType,\r
OUT UINT32 *AuthenticationStatus\r
);\r
\r
-typedef UINT32 EFI_FV_WRITE_POLICY;\r
+typedef UINT32 FRAMEWORK_EFI_FV_WRITE_POLICY;\r
\r
-#define EFI_FV_UNRELIABLE_WRITE 0x00000000\r
-#define EFI_FV_RELIABLE_WRITE 0x00000001\r
+#define FRAMEWORK_EFI_FV_UNRELIABLE_WRITE 0x00000000\r
+#define FRAMEWORK_EFI_FV_RELIABLE_WRITE 0x00000001\r
\r
typedef struct {\r
EFI_GUID *NameGuid;\r
EFI_FV_FILE_ATTRIBUTES FileAttributes;\r
VOID *Buffer;\r
UINT32 BufferSize;\r
-} EFI_FV_WRITE_FILE_DATA;\r
+} FRAMEWORK_EFI_FV_WRITE_FILE_DATA;\r
\r
/**\r
Write the supplied file (NameGuid) to the FV.\r
\r
- @param This Calling context\r
- @param NumberOfFiles Indicates the number of file records pointed to by FileData\r
- @param WritePolicy Indicates the level of reliability of the write with respect to\r
- things like power failure events.\r
- @param FileData A pointer to an array of EFI_FV_WRITE_FILE_DATA structures. Each\r
- element in the array indicates a file to write, and there are\r
- NumberOfFiles elements in the input array.\r
-\r
- @retval EFI_SUCCESS\r
- @retval EFI_OUT_OF_RESOURCES\r
- @retval EFI_DEVICE_ERROR\r
- @retval EFI_WRITE_PROTECTED\r
- @retval EFI_NOT_FOUND\r
- @retval EFI_INVALID_PARAMETER\r
-\r
+ @param This Indicates the EFI_FIRMWARE_VOLUME_PROTOCOL instance.\r
+ @param NumberOfFiles Indicates the number of file records pointed to \r
+ by FileData.\r
+ @param WritePolicy Indicates the level of reliability of the write \r
+ with respect to things like power failure events.\r
+ @param FileData A pointer to an array of EFI_FV_WRITE_FILE_DATA \r
+ structures. Each element in the array indicates \r
+ a file to write, and there are NumberOfFiles\r
+ elements in the input array.\r
+\r
+ @retval EFI_SUCCESS The write completed successfully.\r
+ @retval EFI_OUT_OF_RESOURCES The firmware volume does not have enough free \r
+ space to store file(s).\r
+ @retval EFI_DEVICE_ERROR A hardware error occurred when attempting to \r
+ access the firmware volume.\r
+ @retval EFI_WRITE_PROTECTED The firmware volume is configured to disallow writes.\r
+ @retval EFI_NOT_FOUND A delete was requested, but the requested file was \r
+ not found in the firmware volume.\r
+ @retval EFI_INVALID_PARAMETER A delete was requested with a multiple file write.\r
+ An unsupported WritePolicy was requested.\r
+ An unknown file type was specified.\r
+ A file system specific error has occurred.\r
**/\r
typedef\r
EFI_STATUS\r
-(EFIAPI *EFI_FV_WRITE_FILE) (\r
- IN EFI_FIRMWARE_VOLUME_PROTOCOL *This,\r
- IN UINT32 NumberOfFiles,\r
- IN EFI_FV_WRITE_POLICY WritePolicy,\r
- IN EFI_FV_WRITE_FILE_DATA *FileData\r
+(EFIAPI *FRAMEWORK_EFI_FV_WRITE_FILE)(\r
+ IN EFI_FIRMWARE_VOLUME_PROTOCOL *This,\r
+ IN UINT32 NumberOfFiles,\r
+ IN FRAMEWORK_EFI_FV_WRITE_POLICY WritePolicy,\r
+ IN FRAMEWORK_EFI_FV_WRITE_FILE_DATA *FileData\r
);\r
\r
/**\r
Given the input key, search for the next matching file in the volume.\r
\r
- @param This Calling context\r
- @param Key Pointer to a caller allocated buffer that contains an implementation\r
- specific key that is used to track where to begin searching on\r
- successive calls.\r
- @param FileType Indicates the file type to filter for\r
- @param NameGuid Guid filename of the file found\r
- @param Attributes Attributes of the file found\r
- @param Size Size in bytes of the file found\r
-\r
- @retval EFI_SUCCESS\r
- @retval EFI_NOT_FOUND\r
- @retval EFI_DEVICE_ERROR\r
- @retval EFI_ACCESS_DENIED\r
+ @param This Indicates the EFI_FIRMWARE_VOLUME_PROTOCOL instance.\r
+ @param Key Pointer to a caller allocated buffer that contains \r
+ an implementation-specific key that is used to track \r
+ where to begin searching on successive calls.\r
+ @param FileType The pointer to the file type to filter for.\r
+ @param NameGuid The pointer to Guid filename of the file found.\r
+ @param Attributes The pointer to Attributes of the file found.\r
+ @param Size The pointer to Size in bytes of the file found.\r
+\r
+ @retval EFI_SUCCESS The output parameters are filled with data obtained from \r
+ the first matching file that was found.\r
+ @retval EFI_NOT_FOUND No files of type FileType were found.\r
+ @retval EFI_DEVICE_ERROR A hardware error occurred when attempting to access \r
+ the firmware volume.\r
+ @retval EFI_ACCESS_DENIED The firmware volume is configured to disallow reads.\r
\r
**/\r
typedef\r
EFI_STATUS\r
-(EFIAPI *EFI_FV_GET_NEXT_FILE) (\r
+(EFIAPI *FRAMEWORK_EFI_FV_GET_NEXT_FILE)(\r
IN EFI_FIRMWARE_VOLUME_PROTOCOL *This,\r
IN OUT VOID *Key,\r
IN OUT EFI_FV_FILETYPE *FileType,\r
OUT UINTN *Size\r
);\r
\r
-/**\r
- @par Protocol Description:\r
- The Firmware Volume Protocol provides file-level access to the firmware volume.\r
- Each firmware volume driver must produce an instance of the Firmware Volume\r
- Protocol if the firmware volume is to be visible to the system. The Firmware\r
- Volume Protocol also provides mechanisms for determining and modifying some\r
- attributes of the firmware volume.\r
-\r
- @param GetVolumeAttributes\r
- Retrieves volume capabilities and current settings.\r
-\r
- @param SetVolumeAttributes\r
- Modifies the current settings of the firmware volume.\r
-\r
- @param ReadFile\r
- Reads an entire file from the firmware volume.\r
-\r
- @param ReadSection\r
- Reads a single section from a file into a buffer.\r
-\r
- @param WriteFile\r
- Writes an entire file into the firmware volume.\r
-\r
- @param GetNextFile\r
- Provides service to allow searching the firmware volume.\r
-\r
- @param KeySize\r
- Data field that indicates the size in bytes of the Key input buffer for\r
- the GetNextFile() API.\r
-\r
- @param ParentHandle\r
- Handle of the parent firmware volume.\r
-\r
-**/\r
+//\r
+// Protocol interface structure\r
+//\r
struct _EFI_FIRMWARE_VOLUME_PROTOCOL {\r
- EFI_FV_GET_ATTRIBUTES GetVolumeAttributes;\r
- EFI_FV_SET_ATTRIBUTES SetVolumeAttributes;\r
- EFI_FV_READ_FILE ReadFile;\r
- EFI_FV_READ_SECTION ReadSection;\r
- EFI_FV_WRITE_FILE WriteFile;\r
- EFI_FV_GET_NEXT_FILE GetNextFile;\r
+ ///\r
+ /// Retrieves volume capabilities and current settings.\r
+ ///\r
+ FRAMEWORK_EFI_FV_GET_ATTRIBUTES GetVolumeAttributes;\r
+\r
+ ///\r
+ /// Modifies the current settings of the firmware volume.\r
+ ///\r
+ FRAMEWORK_EFI_FV_SET_ATTRIBUTES SetVolumeAttributes;\r
+\r
+ ///\r
+ /// Reads an entire file from the firmware volume.\r
+ ///\r
+ FRAMEWORK_EFI_FV_READ_FILE ReadFile;\r
+\r
+ ///\r
+ /// Reads a single section from a file into a buffer.\r
+ ///\r
+ FRAMEWORK_EFI_FV_READ_SECTION ReadSection;\r
+\r
+ ///\r
+ /// Writes an entire file into the firmware volume.\r
+ ///\r
+ FRAMEWORK_EFI_FV_WRITE_FILE WriteFile;\r
+\r
+ ///\r
+ /// Provides service to allow searching the firmware volume.\r
+ ///\r
+ FRAMEWORK_EFI_FV_GET_NEXT_FILE GetNextFile;\r
+\r
+ ///\r
+ /// Data field that indicates the size in bytes of the Key input buffer for\r
+ /// the GetNextFile() API.\r
+ ///\r
UINT32 KeySize;\r
+\r
+ ///\r
+ /// Handle of the parent firmware volume.\r
+ ///\r
EFI_HANDLE ParentHandle;\r
};\r
\r
projects / mirror_edk2.git / blobdiff