diff options
Diffstat (limited to 'MdeModulePkg/Core/Dxe/FwVolDriver.h')
| -rw-r--r-- | MdeModulePkg/Core/Dxe/FwVolDriver.h | 564 |
1 files changed, 269 insertions, 295 deletions
diff --git a/MdeModulePkg/Core/Dxe/FwVolDriver.h b/MdeModulePkg/Core/Dxe/FwVolDriver.h index 6469670..d89043e 100644 --- a/MdeModulePkg/Core/Dxe/FwVolDriver.h +++ b/MdeModulePkg/Core/Dxe/FwVolDriver.h @@ -1,4 +1,4 @@ -/**@file
+/** @file
Firmware File System protocol. Layers on top of Firmware
Block protocol to produce a file abstraction of FV based files.
@@ -14,8 +14,8 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. **/
-#ifndef __FWVOL_H
-#define __FWVOL_H
+#ifndef __FW_VOL_DRIVER_H_
+#define __FW_VOL_DRIVER_H_
#define FV2_DEVICE_SIGNATURE EFI_SIGNATURE_32 ('_', 'F', 'V', '2')
@@ -48,50 +48,90 @@ typedef struct { #define FV_DEVICE_FROM_THIS(a) CR(a, FV_DEVICE, Fv, FV2_DEVICE_SIGNATURE)
+/**
+ Retrieves attributes, insures positive polarity of attribute bits, returns
+ resulting attributes in output parameter.
+ @param This Calling context
+ @param Attributes output buffer which contains attributes
+
+ @retval EFI_SUCCESS Successfully got volume attributes
+
+**/
EFI_STATUS
EFIAPI
FvGetVolumeAttributes (
IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This,
OUT EFI_FV_ATTRIBUTES *Attributes
)
-/*++
+;
-Routine Description:
- Retrieves attributes, insures positive polarity of attribute bits, returns
- resulting attributes in output parameter
-Arguments:
- This - Calling context
- Attributes - output buffer which contains attributes
+/**
+ Sets current attributes for volume
-Returns:
- EFI_SUCCESS - Successfully got volume attributes
+ @param This Calling context
+ @param Attributes At input, contains attributes to be set. At output
+ contains new value of FV
---*/
-;
+ @retval EFI_UNSUPPORTED Could not be set.
+**/
EFI_STATUS
EFIAPI
FvSetVolumeAttributes (
IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This,
IN OUT EFI_FV_ATTRIBUTES *Attributes
)
-/*++
-
-Routine Description:
- Sets current attributes for volume
+;
-Arguments:
- This - Calling context
- Attributes - At input, contains attributes to be set. At output contains
- new value of FV
-Returns:
- EFI_UNSUPPORTED - Could not be set.
---*/
-;
+/**
+ Given the input key, search for the next matching file in the volume.
+
+ @param This Indicates the calling context.
+ @param Key Key is a pointer to a caller allocated
+ buffer that contains implementation specific
+ data that is used to track where to begin
+ the search for the next file. The size of
+ the buffer must be at least This->KeySize
+ bytes long. To reinitialize the search and
+ begin from the beginning of the firmware
+ volume, the entire buffer must be cleared to
+ zero. Other than clearing the buffer to
+ initiate a new search, the caller must not
+ modify the data in the buffer between calls
+ to GetNextFile().
+ @param FileType FileType is a pointer to a caller allocated
+ EFI_FV_FILETYPE. The GetNextFile() API can
+ filter it's search for files based on the
+ value of *FileType input. A *FileType input
+ of 0 causes GetNextFile() to search for
+ files of all types. If a file is found, the
+ file's type is returned in *FileType.
+ *FileType is not modified if no file is
+ found.
+ @param NameGuid NameGuid is a pointer to a caller allocated
+ EFI_GUID. If a file is found, the file's
+ name is returned in *NameGuid. *NameGuid is
+ not modified if no file is found.
+ @param Attributes Attributes is a pointer to a caller
+ allocated EFI_FV_FILE_ATTRIBUTES. If a file
+ is found, the file's attributes are returned
+ in *Attributes. *Attributes is not modified
+ if no file is found.
+ @param Size Size is a pointer to a caller allocated
+ UINTN. If a file is found, the file's size
+ is returned in *Size. *Size is not modified
+ if no file is found.
+
+ @retval EFI_SUCCESS Successfully find the file.
+ @retval EFI_DEVICE_ERROR Device error.
+ @retval EFI_ACCESS_DENIED Fv could not read.
+ @retval EFI_NOT_FOUND No matching file found.
+ @retval EFI_INVALID_PARAMETER Invalid parameter
+**/
EFI_STATUS
EFIAPI
FvGetNextFile (
@@ -102,52 +142,50 @@ FvGetNextFile ( OUT EFI_FV_FILE_ATTRIBUTES *Attributes,
OUT UINTN *Size
)
-/*++
-
-Routine Description:
- Given the input key, search for the next matching file in the volume.
-
-Arguments:
- This - Indicates the calling context.
- FileType - FileType is a pointer to a caller allocated
- EFI_FV_FILETYPE. The GetNextFile() API can filter it's
- search for files based on the value of *FileType input.
- A *FileType input of 0 causes GetNextFile() to search for
- files of all types. If a file is found, the file's type
- is returned in *FileType. *FileType is not modified if
- no file is found.
- Key - Key is a pointer to a caller allocated buffer that
- contains implementation specific data that is used to
- track where to begin the search for the next file.
- The size of the buffer must be at least This->KeySize
- bytes long. To reinitialize the search and begin from
- the beginning of the firmware volume, the entire buffer
- must be cleared to zero. Other than clearing the buffer
- to initiate a new search, the caller must not modify the
- data in the buffer between calls to GetNextFile().
- NameGuid - NameGuid is a pointer to a caller allocated EFI_GUID.
- If a file is found, the file's name is returned in
- *NameGuid. *NameGuid is not modified if no file is
- found.
- Attributes - Attributes is a pointer to a caller allocated
- EFI_FV_FILE_ATTRIBUTES. If a file is found, the file's
- attributes are returned in *Attributes. *Attributes is
- not modified if no file is found.
- Size - Size is a pointer to a caller allocated UINTN.
- If a file is found, the file's size is returned in *Size.
- *Size is not modified if no file is found.
-
-Returns:
- EFI_SUCCESS - Successfully find the file.
- EFI_DEVICE_ERROR - Device error.
- EFI_ACCESS_DENIED - Fv could not read.
- EFI_NOT_FOUND - No matching file found.
- EFI_INVALID_PARAMETER - Invalid parameter
-
---*/
;
+
+/**
+ Locates a file in the firmware volume and
+ copies it to the supplied buffer.
+
+ @param This Indicates the calling context.
+ @param NameGuid Pointer to an EFI_GUID, which is the
+ filename.
+ @param Buffer Buffer is a pointer to pointer to a buffer
+ in which the file or section contents or are
+ returned.
+ @param BufferSize BufferSize is a pointer to caller allocated
+ UINTN. On input *BufferSize indicates the
+ size in bytes of the memory region pointed
+ to by Buffer. On output, *BufferSize
+ contains the number of bytes required to
+ read the file.
+ @param FoundType FoundType is a pointer to a caller allocated
+ EFI_FV_FILETYPE that on successful return
+ from Read() contains the type of file read.
+ This output reflects the file type
+ irrespective of the value of the SectionType
+ input.
+ @param FileAttributes FileAttributes is a pointer to a caller
+ allocated EFI_FV_FILE_ATTRIBUTES. On
+ successful return from Read(),
+ *FileAttributes contains the attributes of
+ the file read.
+ @param AuthenticationStatus AuthenticationStatus is a pointer to a
+ caller allocated UINTN in which the
+ authentication status is returned.
+
+ @retval EFI_SUCCESS Successfully read to memory buffer.
+ @retval EFI_WARN_BUFFER_TOO_SMALL Buffer too small.
+ @retval EFI_NOT_FOUND Not found.
+ @retval EFI_DEVICE_ERROR Device error.
+ @retval EFI_ACCESS_DENIED Could not read.
+ @retval EFI_INVALID_PARAMETER Invalid parameter.
+ @retval EFI_OUT_OF_RESOURCES Not enough buffer to be allocated.
+
+**/
EFI_STATUS
EFIAPI
FvReadFile (
@@ -159,46 +197,37 @@ FvReadFile ( OUT EFI_FV_FILE_ATTRIBUTES *FileAttributes,
OUT UINT32 *AuthenticationStatus
)
-/*++
-
-Routine Description:
- Locates a file in the firmware volume and
- copies it to the supplied buffer.
-
-Arguments:
- This - Indicates the calling context.
- NameGuid - Pointer to an EFI_GUID, which is the filename.
- Buffer - Buffer is a pointer to pointer to a buffer in
- which the file or section contents or are returned.
- BufferSize - BufferSize is a pointer to caller allocated
- UINTN. On input *BufferSize indicates the size
- in bytes of the memory region pointed to by
- Buffer. On output, *BufferSize contains the number
- of bytes required to read the file.
- FoundType - FoundType is a pointer to a caller allocated
- EFI_FV_FILETYPE that on successful return from Read()
- contains the type of file read. This output reflects
- the file type irrespective of the value of the
- SectionType input.
- FileAttributes - FileAttributes is a pointer to a caller allocated
- EFI_FV_FILE_ATTRIBUTES. On successful return from
- Read(), *FileAttributes contains the attributes of
- the file read.
- AuthenticationStatus - AuthenticationStatus is a pointer to a caller
- allocated UINTN in which the authentication status
- is returned.
-Returns:
- EFI_SUCCESS - Successfully read to memory buffer.
- EFI_WARN_BUFFER_TOO_SMALL - Buffer too small.
- EFI_NOT_FOUND - Not found.
- EFI_DEVICE_ERROR - Device error.
- EFI_ACCESS_DENIED - Could not read.
- EFI_INVALID_PARAMETER - Invalid parameter.
- EFI_OUT_OF_RESOURCES - Not enough buffer to be allocated.
-
---*/
;
+
+/**
+ Locates a section in a given FFS File and
+ copies it to the supplied buffer (not including section header).
+
+ @param This Indicates the calling context.
+ @param NameGuid Pointer to an EFI_GUID, which is the
+ filename.
+ @param SectionType Indicates the section type to return.
+ @param SectionInstance Indicates which instance of sections with a
+ type of SectionType to return.
+ @param Buffer Buffer is a pointer to pointer to a buffer
+ in which the file or section contents or are
+ returned.
+ @param BufferSize BufferSize is a pointer to caller allocated
+ UINTN.
+ @param AuthenticationStatus AuthenticationStatus is a pointer to a
+ caller allocated UINT32 in which the
+ authentication status is returned.
+
+ @retval EFI_SUCCESS Successfully read the file section into
+ buffer.
+ @retval EFI_WARN_BUFFER_TOO_SMALL Buffer too small.
+ @retval EFI_NOT_FOUND Section not found.
+ @retval EFI_DEVICE_ERROR Device error.
+ @retval EFI_ACCESS_DENIED Could not read.
+ @retval EFI_INVALID_PARAMETER Invalid parameter.
+
+**/
EFI_STATUS
EFIAPI
FvReadFileSection (
@@ -210,36 +239,30 @@ FvReadFileSection ( IN OUT UINTN *BufferSize,
OUT UINT32 *AuthenticationStatus
)
-/*++
-
- Routine Description:
- Locates a section in a given FFS File and
- copies it to the supplied buffer (not including section header).
-
- Arguments:
- This - Indicates the calling context.
- NameGuid - Pointer to an EFI_GUID, which is the filename.
- SectionType - Indicates the section type to return.
- SectionInstance - Indicates which instance of sections with a type of
- SectionType to return.
- Buffer - Buffer is a pointer to pointer to a buffer in which
- the file or section contents or are returned.
- BufferSize - BufferSize is a pointer to caller allocated UINTN.
- AuthenticationStatus -AuthenticationStatus is a pointer to a caller
- allocated UINT32 in which the authentication status
- is returned.
-
- Returns:
- EFI_SUCCESS - Successfully read the file section into buffer.
- EFI_WARN_BUFFER_TOO_SMALL - Buffer too small.
- EFI_NOT_FOUND - Section not found.
- EFI_DEVICE_ERROR - Device error.
- EFI_ACCESS_DENIED - Could not read.
- EFI_INVALID_PARAMETER - Invalid parameter.
-
---*/
;
+
+/**
+ Writes one or more files to the firmware volume.
+
+ @param This Indicates the calling context.
+ @param NumberOfFiles Number of files.
+ @param WritePolicy WritePolicy indicates the level of reliability
+ for the write in the event of a power failure or
+ other system failure during the write operation.
+ @param FileData FileData is an pointer to an array of
+ EFI_FV_WRITE_DATA. Each element of array
+ FileData represents a file to be written.
+
+ @retval EFI_SUCCESS Files successfully written to firmware volume
+ @retval EFI_OUT_OF_RESOURCES Not enough buffer to be allocated.
+ @retval EFI_DEVICE_ERROR Device error.
+ @retval EFI_WRITE_PROTECTED Write protected.
+ @retval EFI_NOT_FOUND Not found.
+ @retval EFI_INVALID_PARAMETER Invalid parameter.
+ @retval EFI_UNSUPPORTED This function not supported.
+
+**/
EFI_STATUS
EFIAPI
FvWriteFile (
@@ -248,31 +271,22 @@ FvWriteFile ( IN EFI_FV_WRITE_POLICY WritePolicy,
IN EFI_FV_WRITE_FILE_DATA *FileData
)
-/*++
-
- Routine Description:
- Writes one or more files to the firmware volume.
-
- Arguments:
- This - Indicates the calling context.
- WritePolicy - WritePolicy indicates the level of reliability for
- the write in the event of a power failure or other
- system failure during the write operation.
- FileData - FileData is an pointer to an array of EFI_FV_WRITE_DATA.
- Each element of FileData[] represents a file to be written.
-
- Returns:
- EFI_SUCCESS - Files successfully written to firmware volume
- EFI_OUT_OF_RESOURCES - Not enough buffer to be allocated.
- EFI_DEVICE_ERROR - Device error.
- EFI_WRITE_PROTECTED - Write protected.
- EFI_NOT_FOUND - Not found.
- EFI_INVALID_PARAMETER - Invalid parameter.
- EFI_UNSUPPORTED - This function not supported.
-
---*/
;
+
+/**
+ Return information of type InformationType for the requested firmware
+ volume.
+
+ @param This Pointer to EFI_FIRMWARE_VOLUME2_PROTOCOL.
+ @param InformationType InformationType for requested.
+ @param BufferSize On input, size of Buffer.On output, the amount of data
+ returned in Buffer.
+ @param Buffer A poniter to the data buffer to return.
+
+ @retval EFI_SUCCESS Successfully got volume Information.
+
+**/
EFI_STATUS
EFIAPI
FvGetVolumeInfo (
@@ -281,25 +295,23 @@ FvGetVolumeInfo ( IN OUT UINTN *BufferSize,
OUT VOID *Buffer
)
-/*++
+;
-Routine Description:
- Return information of type InformationType for the requested firmware
+
+
+/**
+ Set information of type InformationType for the requested firmware
volume.
-
-Arguments:
- This - Pointer to EFI_FIRMWARE_VOLUME2_PROTOCOL.
- InformationType - InformationType for requested.
- BufferSize - On input, size of Buffer.On output, the amount of
- data returned in Buffer.
- Buffer - A poniter to the data buffer to return.
-Returns:
- EFI_SUCCESS - Successfully got volume Information.
-
---*/
-;
+ @param This Pointer to EFI_FIRMWARE_VOLUME2_PROTOCOL.
+ @param InformationType InformationType for requested.
+ @param BufferSize On input, size of Buffer.On output, the amount of data
+ returned in Buffer.
+ @param Buffer A poniter to the data buffer to return.
+
+ @retval EFI_SUCCESS Successfully set volume Information.
+**/
EFI_STATUS
EFIAPI
FvSetVolumeInfo (
@@ -308,22 +320,6 @@ FvSetVolumeInfo ( IN UINTN BufferSize,
IN CONST VOID *Buffer
)
-/*++
-
-Routine Description:
- Set information of type InformationType for the requested firmware
- volume.
-
-Arguments:
- This - Pointer to EFI_FIRMWARE_VOLUME2_PROTOCOL.
- InformationType - InformationType for requested.
- BufferSize - On input, size of Buffer.On output, the amount of
- data returned in Buffer.
- Buffer - A poniter to the data buffer to return.
-Returns:
- EFI_SUCCESS - Successfully set volume Information.
-
---*/
;
//
@@ -338,175 +334,153 @@ typedef enum { } EFI_CHECKSUM_TYPE;
+
+/**
+ Check if a block of buffer is erased.
+
+ @param ErasePolarity Erase polarity attribute of the firmware volume
+ @param InBuffer The buffer to be checked
+ @param BufferSize Size of the buffer in bytes
+
+ @retval TRUE The block of buffer is erased
+ @retval FALSE The block of buffer is not erased
+
+**/
BOOLEAN
IsBufferErased (
IN UINT8 ErasePolarity,
IN VOID *Buffer,
IN UINTN BufferSize
)
-/*++
+;
-Routine Description:
- Check if a block of buffer is erased
-Arguments:
- ErasePolarity - Erase polarity attribute of the firmware volume
- Buffer - The buffer to be checked
- BufferSize - Size of the buffer in bytes
-
-Returns:
- TRUE - The block of buffer is erased
- FALSE - The block of buffer is not erased
-
---*/
-;
+/**
+ Get the FFS file state by checking the highest bit set in the header's state field.
+ @param ErasePolarity Erase polarity attribute of the firmware volume
+ @param FfsHeader Points to the FFS file header
+
+ @return FFS File state
+
+**/
EFI_FFS_FILE_STATE
GetFileState (
IN UINT8 ErasePolarity,
IN EFI_FFS_FILE_HEADER *FfsHeader
)
-/*++
+;
-Routine Description:
- Get the FFS file state by checking the highest bit set in the header's state field
-Arguments:
- ErasePolarity - Erase polarity attribute of the firmware volume
- FfsHeader - Points to the FFS file header
-
-Returns:
- FFS File state
-
---*/
-;
+/**
+ Set the FFS file state.
+
+ @param State The state to be set.
+ @param FfsHeader Points to the FFS file header
+
+ @return None.
+**/
VOID
SetFileState (
IN UINT8 State,
IN EFI_FFS_FILE_HEADER *FfsHeader
)
-/*++
+;
-Routine Description:
- Set the FFS file state.
-Arguments:
- State - The state to be set.
- FfsHeader - Points to the FFS file header
-
-Returns:
- None.
-
---*/
-;
+/**
+ Verify checksum of the firmware volume header.
+
+ @param FvHeader Points to the firmware volume header to be checked
+ @retval TRUE Checksum verification passed
+ @retval FALSE Checksum verification failed
+
+**/
BOOLEAN
VerifyFvHeaderChecksum (
IN EFI_FIRMWARE_VOLUME_HEADER *FvHeader
)
-/*++
-
-Routine Description:
- Verify checksum of the firmware volume header
-
-Arguments:
- FvHeader - Points to the firmware volume header to be checked
-
-Returns:
- TRUE - Checksum verification passed
- FALSE - Checksum verification failed
-
---*/
;
+
+/**
+ Check if it's a valid FFS file header.
+
+ @param ErasePolarity Erase polarity attribute of the firmware volume
+ @param FfsHeader Points to the FFS file header to be checked
+ @param FileState FFS file state to be returned
+
+ @retval TRUE Valid FFS file header
+ @retval FALSE Invalid FFS file header
+
+**/
BOOLEAN
IsValidFfsHeader (
IN UINT8 ErasePolarity,
IN EFI_FFS_FILE_HEADER *FfsHeader,
OUT EFI_FFS_FILE_STATE *FileState
)
-/*++
+;
-Routine Description:
- Check if it's a valid FFS file header
-Arguments:
- ErasePolarity - Erase polarity attribute of the firmware volume
- FfsHeader - Points to the FFS file header to be checked
- FileState - FFS file state to be returned
-
-Returns:
- TRUE - Valid FFS file header
- FALSE - Invalid FFS file header
-
---*/
-;
+/**
+ Check if it's a valid FFS file.
+ Here we are sure that it has a valid FFS file header since we must call IsValidFfsHeader() first.
+
+ @param ErasePolarity Erase polarity attribute of the firmware volume
+ @param FfsHeader Points to the FFS file to be checked
+ @retval TRUE Valid FFS file
+ @retval FALSE Invalid FFS file
+
+**/
BOOLEAN
IsValidFfsFile (
IN UINT8 ErasePolarity,
IN EFI_FFS_FILE_HEADER *FfsHeader
)
-/*++
+;
-Routine Description:
- Check if it's a valid FFS file.
- Here we are sure that it has a valid FFS file header since we must call IsValidFfsHeader() first.
-Arguments:
- ErasePolarity - Erase polarity attribute of the firmware volume
- FfsHeader - Points to the FFS file to be checked
-
-Returns:
- TRUE - Valid FFS file
- FALSE - Invalid FFS file
-
---*/
-;
+/**
+ given the supplied FW_VOL_BLOCK_PROTOCOL, allocate a buffer for output and
+ copy the volume header into it.
+
+ @param Fvb The FW_VOL_BLOCK_PROTOCOL instance from which to
+ read the volume header
+ @param FwVolHeader Pointer to pointer to allocated buffer in which
+ the volume header is returned.
+ @retval EFI_OUT_OF_RESOURCES No enough buffer could be allocated.
+ @retval EFI_SUCCESS Successfully read volume header to the allocated
+ buffer.
+
+**/
EFI_STATUS
GetFwVolHeader (
IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *Fvb,
OUT EFI_FIRMWARE_VOLUME_HEADER **FwVolHeader
)
-/*++
+;
-Routine Description:
- given the supplied FW_VOL_BLOCK_PROTOCOL, allocate a buffer for output and
- copy the volume header into it.
-Arguments:
- Fvb - The FW_VOL_BLOCK_PROTOCOL instance from which to read the volume
- header
- FwVolHeader - Pointer to pointer to allocated buffer in which the volume
- header is returned.
-Returns:
- Status code.
+/**
+ Check if a FV is consistent and allocate cache
---*/
-;
+ @param FvDevice pointer to the FvDevice to be checked.
+ @retval EFI_OUT_OF_RESOURCES No enough buffer could be allocated.
+ @retval EFI_SUCCESS FV is consistent and cache is allocated.
+ @retval EFI_VOLUME_CORRUPTED File system is corrupted.
+**/
EFI_STATUS
FvCheck (
IN OUT FV_DEVICE *FvDevice
)
-/*++
-
-Routine Description:
- Check if a FV is consistent and allocate cache
-
-Arguments:
- FvDevice - pointer to the FvDevice to be checked.
-
-Returns:
- EFI_OUT_OF_RESOURCES - Not enough buffer to be allocated.
- EFI_SUCCESS - FV is consistent and cache is allocated.
- EFI_VOLUME_CORRUPTED - File system is corrupted.
-
---*/
;
#endif
|