From 38db75072ffa2108872d2db6d8e65658aab0ed0d Mon Sep 17 00:00:00 2001 From: jcarsey Date: Wed, 10 Jun 2009 17:41:25 +0000 Subject: [PATCH] git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@8511 6f19259b-4bc3-4df7-8a09-765794883524 --- .../Include/Protocol/FirmwareVolume.h | 146 +++++++++--------- 1 file changed, 75 insertions(+), 71 deletions(-) diff --git a/IntelFrameworkPkg/Include/Protocol/FirmwareVolume.h b/IntelFrameworkPkg/Include/Protocol/FirmwareVolume.h index b144e96579..98f2909b18 100644 --- a/IntelFrameworkPkg/Include/Protocol/FirmwareVolume.h +++ b/IntelFrameworkPkg/Include/Protocol/FirmwareVolume.h @@ -1,10 +1,12 @@ /** @file - This file declares Firmware Volume protocol. - The Firmware Volume Protocol provides file-level access to the firmware volume.E ach firmware - volume driver must produce an instance of the Firmware Volume Protocol if the firmware volume - is to be visible to the system.T he Firmware Volume Protocol also provides mechanisms for - determining and modifying some attributes of the firmware volume. + 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, Intel Corporation All rights reserved. This program and the accompanying materials are licensed and made available under the terms and conditions of the BSD License @@ -85,12 +87,10 @@ typedef UINT64 FRAMEWORK_EFI_FV_ATTRIBUTES; Retrieves attributes, insures positive polarity of attribute bits, returns resulting attributes in output parameter - @param This Calling context + @param This Indicates the EFI_FIRMWARE_VOLUME_PROTOCOL instance. @param Attributes output buffer which contains attributes - @retval EFI_INVALID_PARAMETER - @retval EFI_SUCCESS - + @retval EFI_SUCCESS The firmware volume attributes were returned. **/ typedef EFI_STATUS @@ -102,26 +102,34 @@ EFI_STATUS /** Sets volume attributes - @param This Calling context - @param Attributes Buffer which contains 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.O n 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 - @retval EFI_DEVICE_ERROR - @retval EFI_SUCCESS + @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 + IN EFI_FIRMWARE_VOLUME_PROTOCOL *This, + IN OUT FRAMEWORK_EFI_FV_ATTRIBUTES *Attributes ); /** - Read the requested file (NameGuid) and returns data in Buffer. + Read the requested file (NameGuid) or file information from the firmware volume + and returns data in Buffer. - @param This Calling context - @param NameGuid Filename identifying which file to read + @param This Indicates the EFI_FIRMWARE_VOLUME_PROTOCOL instance. + @param NameGuid pointer to EFI_GUID which is the filename identifying which file to read @param Buffer Pointer to pointer to buffer in which contents of file are returned.
If Buffer is NULL, only type, attributes, and size are returned as @@ -134,15 +142,17 @@ EFI_STATUS allocated by the caller and is being passed in. @param BufferSize Indicates the buffer size passed in, and on output the size required to complete the read - @param FoundType Indicates the type of the file who's data is returned - @param FileAttributes Indicates the attributes of the file who's data is resturned - @param AuthenticationStatus Indicates the authentication status of the data + @param FoundType pointer to type of the file who's data is returned + @param FileAttributes pointer to attributes of the file who's data is resturned + @param AuthenticationStatus pointer to authentication status of the data - @retval EFI_SUCCESS - @retval EFI_WARN_BUFFER_TOO_SMALL - @retval EFI_NOT_FOUND - @retval EFI_DEVICE_ERROR - @retval EFI_ACCESS_DENIED + @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_NOT_FOUND NameGuid was not found int he firmware volume. + @retval EFI_DEVICE_ERROR A hardware error occurred when attempting to access the firmware volume. + @retval EFI_ACCESS_DENIED The firmware volumen is configured to disallow reads. + @retval EFI_OUT_OF_RESOURCES An allocation failure occurred. **/ typedef @@ -160,7 +170,7 @@ EFI_STATUS /** Read the requested section from the specified file and returns data in Buffer. - @param This Calling context + @param This Indicates the EFI_FIRMWARE_VOLUME_PROTOCOL instance. @param NameGuid Filename identifying the file from which to read @param SectionType Indicates what section type to retrieve @param SectionInstance Indicates which instance of SectionType to retrieve @@ -174,9 +184,9 @@ EFI_STATUS
If Buffer != NULL and *Buffer != NULL, the output buffer has been allocated by the caller and is being passed in. - @param BufferSize Indicates the buffer size passed in, and on output the size + @param BufferSize pointer to the buffer size passed in, and on output the size required to complete the read - @param AuthenticationStatus Indicates the authentication status of the data + @param AuthenticationStatus pointer to the authentication status of the data @retval EFI_SUCCESS @retval EFI_WARN_BUFFER_TOO_SMALL @@ -214,7 +224,7 @@ typedef struct { /** Write the supplied file (NameGuid) to the FV. - @param This Calling context + @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. @@ -242,14 +252,14 @@ EFI_STATUS /** Given the input key, search for the next matching file in the volume. - @param This Calling context + @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 Indicates the file type to filter for - @param NameGuid Guid filename of the file found - @param Attributes Attributes of the file found - @param Size Size in bytes of the file found + @param FileType pointer to the file type to filter for + @param NameGuid pointer to Guid filename of the file found + @param Attributes pointer to Attributes of the file found + @param Size pointer to Size in bytes of the file found @retval EFI_SUCCESS @retval EFI_NOT_FOUND @@ -268,48 +278,42 @@ EFI_STATUS OUT UINTN *Size ); -/** - @par Protocol Description: - 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. - - @param GetVolumeAttributes - Retrieves volume capabilities and current settings. - - @param SetVolumeAttributes - Modifies the current settings of the firmware volume. - - @param ReadFile - Reads an entire file from the firmware volume. - - @param ReadSection - Reads a single section from a file into a buffer. - - @param WriteFile - Writes an entire file into the firmware volume. - - @param GetNextFile - Provides service to allow searching the firmware volume. - - @param KeySize - Data field that indicates the size in bytes of the Key input buffer for - the GetNextFile() API. - - @param ParentHandle - Handle of the parent firmware volume. - -**/ +// +// 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; - UINT32 KeySize; +/// +/// 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; };