diff --git a/Include/Protocol/FirmwareVolume.h b/Include/Protocol/FirmwareVolume.h new file mode 100644 index 00000000..48d53953 --- /dev/null +++ b/Include/Protocol/FirmwareVolume.h @@ -0,0 +1,346 @@ +/** @file + 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 - 2018, 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 that accompanies this distribution. +The full text of the license may be found at +http://opensource.org/licenses/bsd-license.php. + +THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, +WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + + @par Revision Reference: + This protocol is defined in Firmware Volume specification. + Version 0.9. + +**/ + +#ifndef _FIRMWARE_VOLUME_H_ +#define _FIRMWARE_VOLUME_H_ + + +// +// Firmware Volume Protocol GUID definition +// +#define EFI_FIRMWARE_VOLUME_PROTOCOL_GUID \ + { \ + 0x389F751F, 0x1838, 0x4388, {0x83, 0x90, 0xCD, 0x81, 0x54, 0xBD, 0x27, 0xF8 } \ + } + +#define FV_DEVICE_SIGNATURE SIGNATURE_32 ('_', 'F', 'V', '_') + +typedef struct _EFI_FIRMWARE_VOLUME_PROTOCOL EFI_FIRMWARE_VOLUME_PROTOCOL; + +// +// FRAMEWORK_EFI_FV_ATTRIBUTES bit definitions +// +typedef UINT64 FRAMEWORK_EFI_FV_ATTRIBUTES; + +// +// ************************************************************ +// FRAMEWORK_EFI_FV_ATTRIBUTES bit definitions +// ************************************************************ +// +#define EFI_FV_READ_DISABLE_CAP 0x0000000000000001ULL +#define EFI_FV_READ_ENABLE_CAP 0x0000000000000002ULL +#define EFI_FV_READ_STATUS 0x0000000000000004ULL + +#define EFI_FV_WRITE_DISABLE_CAP 0x0000000000000008ULL +#define EFI_FV_WRITE_ENABLE_CAP 0x0000000000000010ULL +#define EFI_FV_WRITE_STATUS 0x0000000000000020ULL + +#define EFI_FV_LOCK_CAP 0x0000000000000040ULL +#define EFI_FV_LOCK_STATUS 0x0000000000000080ULL +#define EFI_FV_WRITE_POLICY_RELIABLE 0x0000000000000100ULL + +#define EFI_FV_ALIGNMENT_CAP 0x0000000000008000ULL +#define EFI_FV_ALIGNMENT_2 0x0000000000010000ULL +#define EFI_FV_ALIGNMENT_4 0x0000000000020000ULL +#define EFI_FV_ALIGNMENT_8 0x0000000000040000ULL +#define EFI_FV_ALIGNMENT_16 0x0000000000080000ULL +#define EFI_FV_ALIGNMENT_32 0x0000000000100000ULL +#define EFI_FV_ALIGNMENT_64 0x0000000000200000ULL +#define EFI_FV_ALIGNMENT_128 0x0000000000400000ULL +#define EFI_FV_ALIGNMENT_256 0x0000000000800000ULL +#define EFI_FV_ALIGNMENT_512 0x0000000001000000ULL +#define EFI_FV_ALIGNMENT_1K 0x0000000002000000ULL +#define EFI_FV_ALIGNMENT_2K 0x0000000004000000ULL +#define EFI_FV_ALIGNMENT_4K 0x0000000008000000ULL +#define EFI_FV_ALIGNMENT_8K 0x0000000010000000ULL +#define EFI_FV_ALIGNMENT_16K 0x0000000020000000ULL +#define EFI_FV_ALIGNMENT_32K 0x0000000040000000ULL +#define EFI_FV_ALIGNMENT_64K 0x0000000080000000ULL + +// +// Protocol API definitions +// + +/** + Retrieves attributes, insures positive polarity of attribute bits, and returns + resulting attributes in an output parameter. + + @param This Indicates the EFI_FIRMWARE_VOLUME_PROTOCOL instance. + @param Attributes Output buffer containing attributes. + + @retval EFI_SUCCESS The firmware volume attributes were returned. +**/ +typedef +EFI_STATUS +(EFIAPI *FRAMEWORK_EFI_FV_GET_ATTRIBUTES)( + IN EFI_FIRMWARE_VOLUME_PROTOCOL *This, + OUT FRAMEWORK_EFI_FV_ATTRIBUTES *Attributes + ); + +/** + Sets volume 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. On 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 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 + ); + +/** + Read the requested file (NameGuid) or file information from the firmware volume + and returns data in Buffer. + + @param This The EFI_FIRMWARE_VOLUME_PROTOCOL instance. + @param NameGuid The pointer to EFI_GUID, which is the filename of + the file to read. + @param Buffer The pointer to pointer to buffer in which contents of file are returned. +
+ If Buffer is NULL, only type, attributes, and size + are returned as there is no output buffer. +
+ If Buffer != NULL and *Buffer == NULL, the output + buffer is allocated from BS pool by ReadFile. +
+ If Buffer != NULL and *Buffer != NULL, the output + buffer has been allocated by the caller and is being + passed in. + @param BufferSize On input: The buffer size. On output: The size + required to complete the read. + @param FoundType The pointer to the type of the file whose data + is returned. + @param FileAttributes The pointer to attributes of the file whose data + is returned. + @param AuthenticationStatus The pointer to the authentication status of the data. + + @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 filled, and the output is truncated. + @retval EFI_NOT_FOUND NameGuid was not found in the firmware volume. + @retval EFI_DEVICE_ERROR A hardware error occurred when attempting to + access the firmware volume. + @retval EFI_ACCESS_DENIED The firmware volume is configured to disallow reads. + @retval EFI_OUT_OF_RESOURCES An allocation failure occurred. + +**/ +typedef +EFI_STATUS +(EFIAPI *FRAMEWORK_EFI_FV_READ_FILE)( + IN EFI_FIRMWARE_VOLUME_PROTOCOL *This, + IN EFI_GUID *NameGuid, + IN OUT VOID **Buffer, + IN OUT UINTN *BufferSize, + OUT EFI_FV_FILETYPE *FoundType, + OUT EFI_FV_FILE_ATTRIBUTES *FileAttributes, + OUT UINT32 *AuthenticationStatus + ); + +/** + Read the requested section from the specified file and returns data in Buffer. + + @param This Indicates the EFI_FIRMWARE_VOLUME_PROTOCOL instance. + @param NameGuid Filename identifying the file from which to read. + @param SectionType The section type to retrieve. + @param SectionInstance The instance of SectionType to retrieve. + @param Buffer Pointer to pointer to buffer in which contents of + a file are returned. +
+ If Buffer is NULL, only type, attributes, and size + are returned as there is no output buffer. +
+ If Buffer != NULL and *Buffer == NULL, the output + buffer is allocated from BS pool by ReadFile. +
+ If Buffer != NULL and *Buffer != NULL, the output + buffer has been allocated by the caller and is being + passed in. + @param BufferSize The pointer to the buffer size passed in, and on + output the size required to complete the read. + @param AuthenticationStatus The pointer to the authentication status of the data. + + @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_OUT_OF_RESOURCES An allocation failure occurred. + @retval EFI_NOT_FOUND The name was not found in the firmware volume. + @retval EFI_DEVICE_ERROR A hardware error occurred when attempting to + access the firmware volume. + @retval EFI_ACCESS_DENIED The firmware volume is configured to disallow reads. + +**/ +typedef +EFI_STATUS +(EFIAPI *FRAMEWORK_EFI_FV_READ_SECTION)( + IN EFI_FIRMWARE_VOLUME_PROTOCOL *This, + IN EFI_GUID *NameGuid, + IN EFI_SECTION_TYPE SectionType, + IN UINTN SectionInstance, + IN OUT VOID **Buffer, + IN OUT UINTN *BufferSize, + OUT UINT32 *AuthenticationStatus + ); + +typedef UINT32 FRAMEWORK_EFI_FV_WRITE_POLICY; + +#define FRAMEWORK_EFI_FV_UNRELIABLE_WRITE 0x00000000 +#define FRAMEWORK_EFI_FV_RELIABLE_WRITE 0x00000001 + +typedef struct { + EFI_GUID *NameGuid; + EFI_FV_FILETYPE Type; + EFI_FV_FILE_ATTRIBUTES FileAttributes; + VOID *Buffer; + UINT32 BufferSize; +} FRAMEWORK_EFI_FV_WRITE_FILE_DATA; + +/** + Write the supplied file (NameGuid) to the FV. + + @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. + @param FileData A pointer to an array of EFI_FV_WRITE_FILE_DATA + structures. Each element in the array indicates + a file to write, and there are NumberOfFiles + elements in the input array. + + @retval EFI_SUCCESS The write completed successfully. + @retval EFI_OUT_OF_RESOURCES The firmware volume does not have enough free + space to store file(s). + @retval EFI_DEVICE_ERROR A hardware error occurred when attempting to + access the firmware volume. + @retval EFI_WRITE_PROTECTED The firmware volume is configured to disallow writes. + @retval EFI_NOT_FOUND A delete was requested, but the requested file was + not found in the firmware volume. + @retval EFI_INVALID_PARAMETER A delete was requested with a multiple file write. + An unsupported WritePolicy was requested. + An unknown file type was specified. + A file system specific error has occurred. +**/ +typedef +EFI_STATUS +(EFIAPI *FRAMEWORK_EFI_FV_WRITE_FILE)( + IN EFI_FIRMWARE_VOLUME_PROTOCOL *This, + IN UINT32 NumberOfFiles, + IN FRAMEWORK_EFI_FV_WRITE_POLICY WritePolicy, + IN FRAMEWORK_EFI_FV_WRITE_FILE_DATA *FileData + ); + +/** + Given the input key, search for the next matching file in the volume. + + @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 The pointer to the file type to filter for. + @param NameGuid The pointer to Guid filename of the file found. + @param Attributes The pointer to Attributes of the file found. + @param Size The pointer to Size in bytes of the file found. + + @retval EFI_SUCCESS The output parameters are filled with data obtained from + the first matching file that was found. + @retval EFI_NOT_FOUND No files of type FileType were found. + @retval EFI_DEVICE_ERROR A hardware error occurred when attempting to access + the firmware volume. + @retval EFI_ACCESS_DENIED The firmware volume is configured to disallow reads. + +**/ +typedef +EFI_STATUS +(EFIAPI *FRAMEWORK_EFI_FV_GET_NEXT_FILE)( + IN EFI_FIRMWARE_VOLUME_PROTOCOL *This, + IN OUT VOID *Key, + IN OUT EFI_FV_FILETYPE *FileType, + OUT EFI_GUID *NameGuid, + OUT EFI_FV_FILE_ATTRIBUTES *Attributes, + OUT UINTN *Size + ); + +// +// 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; + + /// + /// 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; +}; + +extern EFI_GUID gEfiFirmwareVolumeProtocolGuid; + +#endif diff --git a/OcSupportPkg.dec b/OcSupportPkg.dec index 9f3c1e32..263811c1 100644 --- a/OcSupportPkg.dec +++ b/OcSupportPkg.dec @@ -41,6 +41,9 @@ ## Include/Protocol/LegacyRegion.h gEfiLegacyRegionProtocolGuid = { 0x0fc9013a, 0x0568, 0x4ba9, { 0x9b, 0x7e, 0xc9, 0xc3, 0x90, 0xa6, 0x60, 0x9b }} + ## Include/Protocol/FirmwareVolume.h + gEfiFirmwareVolumeProtocolGuid = { 0x389F751F, 0x1838, 0x4388, { 0x83, 0x90, 0xcd, 0x81, 0x54, 0xbd, 0x27, 0xf8 }} + [PcdsFeatureFlag] ## Indicates if Apple Thunderbolt NHI protocol is called during device property export.

# TRUE - Apple Thunderbolt NHI protocol will be called.