X-Git-Url: https://git.proxmox.com/?p=mirror_edk2.git;a=blobdiff_plain;f=MdeModulePkg%2FCore%2FDxe%2FFwVolDriver.h;h=d89043e6b5ba6668e6ef6e28d135c0bef5e62e48;hp=6469670d0496afd0fcd89f8ad2b8691ee1ed92cd;hb=162ed594438ab8d39f89b43e6d645ca24e1e1e65;hpb=dc2e539a344115537c1d3883ba96eaade345827b diff --git a/MdeModulePkg/Core/Dxe/FwVolDriver.h b/MdeModulePkg/Core/Dxe/FwVolDriver.h index 6469670d04..d89043e6b5 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