git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@8511 6f19259b...
authorjcarsey <jcarsey@6f19259b-4bc3-4df7-8a09-765794883524>
Wed, 10 Jun 2009 17:41:25 +0000 (17:41 +0000)
committerjcarsey <jcarsey@6f19259b-4bc3-4df7-8a09-765794883524>
Wed, 10 Jun 2009 17:41:25 +0000 (17:41 +0000)
IntelFrameworkPkg/Include/Protocol/FirmwareVolume.h

index b144e9657931ced403c48d4f339177b7328a5c7a..98f2909b188812050c46c1c1796dd2aa1dcf7ae6 100644 (file)
@@ -1,10 +1,12 @@
 /** @file\r
-  This file declares Firmware Volume protocol.\r
-  The Firmware Volume Protocol provides file-level access to the firmware volume.E ach firmware\r
-  volume driver must produce an instance of the Firmware Volume Protocol if the firmware volume\r
-  is to be visible to the system.T he Firmware Volume Protocol also provides mechanisms for\r
-  determining and modifying some attributes of the firmware volume.\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
   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
@@ -85,12 +87,10 @@ typedef UINT64  FRAMEWORK_EFI_FV_ATTRIBUTES;
   Retrieves attributes, insures positive polarity of attribute bits, returns\r
   resulting attributes in output parameter\r
 \r
-  @param  This                  Calling context\r
+  @param  This                  Indicates the EFI_FIRMWARE_VOLUME_PROTOCOL instance.\r
   @param  Attributes            output buffer which contains attributes\r
 \r
-  @retval EFI_INVALID_PARAMETER\r
-  @retval EFI_SUCCESS\r
-\r
+  @retval EFI_SUCCESS           The firmware volume attributes were returned.\r
 **/\r
 typedef\r
 EFI_STATUS\r
@@ -102,26 +102,34 @@ EFI_STATUS
 /**\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.O n 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 *FRAMEWORK_EFI_FV_SET_ATTRIBUTES)(\r
-  IN EFI_FIRMWARE_VOLUME_PROTOCOL   *This,\r
-  IN OUT FRAMEWORK_EFI_FV_ATTRIBUTES          *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  This                  Indicates the EFI_FIRMWARE_VOLUME_PROTOCOL instance.\r
+  @param  NameGuid              pointer to EFI_GUID which is the filename identifying which file to read\r
   @param  Buffer                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
@@ -134,15 +142,17 @@ EFI_STATUS
                                 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
+  @param  FoundType             pointer to type of the file who's data is returned\r
+  @param  FileAttributes        pointer to attributes of the file who's data is resturned\r
+  @param  AuthenticationStatus  pointer to 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_NOT_FOUND             NameGuid was not found int he firmware volume.\r
+  @retval EFI_DEVICE_ERROR          A hardware error occurred when attempting to access the firmware volume.\r
+  @retval EFI_ACCESS_DENIED         The firmware volumen is configured to disallow reads.\r
+  @retval EFI_OUT_OF_RESOURCES      An allocation failure occurred.\r
 \r
 **/\r
 typedef\r
@@ -160,7 +170,7 @@ EFI_STATUS
 /**\r
   Read the requested section from the specified file and returns data in Buffer.\r
 \r
-  @param  This                  Calling context\r
+  @param  This                  Indicates the EFI_FIRMWARE_VOLUME_PROTOCOL instance.\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
@@ -174,9 +184,9 @@ EFI_STATUS
                                 <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
+  @param  BufferSize            pointer to 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
+  @param  AuthenticationStatus  pointer to the authentication status of the data\r
 \r
   @retval EFI_SUCCESS\r
   @retval EFI_WARN_BUFFER_TOO_SMALL\r
@@ -214,7 +224,7 @@ typedef struct {
 /**\r
   Write the supplied file (NameGuid) to the FV.\r
 \r
-  @param  This                  Calling context\r
+  @param  This                  Indicates the EFI_FIRMWARE_VOLUME_PROTOCOL instance.\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
@@ -242,14 +252,14 @@ EFI_STATUS
 /**\r
   Given the input key, search for the next matching file in the volume.\r
 \r
-  @param  This                  Calling context\r
+  @param  This                  Indicates the EFI_FIRMWARE_VOLUME_PROTOCOL instance.\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
+  @param  FileType              pointer to the file type to filter for\r
+  @param  NameGuid              pointer to Guid filename of the file found\r
+  @param  Attributes            pointer to Attributes of the file found\r
+  @param  Size                  pointer to Size in bytes of the file found\r
 \r
   @retval EFI_SUCCESS\r
   @retval EFI_NOT_FOUND\r
@@ -268,48 +278,42 @@ EFI_STATUS
   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
+///\r
+/// Retrieves volume capabilities and current settings.\r
+///\r
   FRAMEWORK_EFI_FV_GET_ATTRIBUTES GetVolumeAttributes;\r
+///\r
+/// Modifies the current settings of the firmware volume.\r
+///\r
   FRAMEWORK_EFI_FV_SET_ATTRIBUTES SetVolumeAttributes;\r
+///\r
+/// Reads an entire file from the firmware volume.\r
+///\r
   FRAMEWORK_EFI_FV_READ_FILE      ReadFile;\r
+///\r
+/// Reads a single section from a file into a buffer.\r
+///\r
   FRAMEWORK_EFI_FV_READ_SECTION   ReadSection;\r
+///\r
+/// Writes an entire file into the firmware volume.\r
+///\r
   FRAMEWORK_EFI_FV_WRITE_FILE     WriteFile;\r
+///\r
+/// Provides service to allow searching the firmware volume.\r
+///\r
   FRAMEWORK_EFI_FV_GET_NEXT_FILE  GetNextFile;\r
-  UINT32                KeySize;\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
+///  Handle of the parent firmware volume.\r
+///\r
   EFI_HANDLE            ParentHandle;\r
 };\r
 \r