From aa4a31e3489b73623372656572c50f84a8044404 Mon Sep 17 00:00:00 2001 From: lgao4 Date: Thu, 2 Jul 2009 08:52:18 +0000 Subject: [PATCH] Update code comments according to intel framework specification. git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@8724 6f19259b-4bc3-4df7-8a09-765794883524 --- IntelFrameworkPkg/Include/Guid/Capsule.h | 80 ++++++++++++++++--- .../Include/Ppi/SectionExtraction.h | 2 +- .../Include/Protocol/FrameworkFormCallback.h | 48 +++++------ 3 files changed, 91 insertions(+), 39 deletions(-) diff --git a/IntelFrameworkPkg/Include/Guid/Capsule.h b/IntelFrameworkPkg/Include/Guid/Capsule.h index dc9d2be42b..90c82cb20e 100644 --- a/IntelFrameworkPkg/Include/Guid/Capsule.h +++ b/IntelFrameworkPkg/Include/Guid/Capsule.h @@ -1,5 +1,5 @@ /** @file - GUIDs used for EFI Capsule + Framework Capule related Definition. Copyright (c) 2007 - 2009, Intel Corporation All rights reserved. This program and the accompanying materials @@ -10,11 +10,8 @@ THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. - Module Name: Capsule.h - @par Revision Reference: - GUIDs defined in Capsule Spec Version 0.9 - + Capsule Spec Version 0.9 **/ #ifndef _CAPSULE_GUID_H__ @@ -39,11 +36,11 @@ 0x98B8D59B, 0xE8BA, 0x48EE, {0x98, 0xDD, 0xC2, 0x95, 0x39, 0x2F, 0x1E, 0xDB } \ } -// -// Bits in the flags field of the capsule header -// -#define EFI_CAPSULE_HEADER_FLAG_SETUP 0x00000001 // supports setup changes - +/// +/// Bits in the flags field of the capsule header +/// This flag is set if the capsule can support setup changes and clear if it cannot. +/// +#define EFI_CAPSULE_HEADER_FLAG_SETUP 0x00000001 #define CAPSULE_BLOCK_DESCRIPTOR_SIGNATURE SIGNATURE_32 ('C', 'B', 'D', 'S') @@ -67,19 +64,82 @@ typedef struct { } EFI_CAPSULE_OEM_HEADER; typedef struct { + /// + /// A defined GUID that indicates the start of a capsule. + /// EFI_GUID CapsuleGuid; + /// + /// The size of the EFI_CAPSULE_HEADER structure. + /// UINT32 HeaderSize; + /// + /// A bit-mapped list describing the capsule¡¯s attributes. + /// All undefined bits should be written as zero (0) + /// UINT32 Flags; + /// + /// The length in bytes (27,415 for an image containing 27,415 bytes) of the entire image + /// including all headers. If the this value is greater than the size of the data presented in + /// the capsule body, this means that the image is separated across multiple media. If this + /// value is less than the size of the data, it is an error. + /// UINT32 CapsuleImageSize; + /// + /// A zero-based number that enables a capsule to be split into pieces and then + /// recombined for easier transfer across media with limited size. The lower the + /// SequenceNumber, the earlier in the final image that the part of the capsule is to + /// appear. In capsules that are not split, this value shall be zero. + /// UINT32 SequenceNumber; + /// + /// Used to group the various pieces of a split capsule to ensure that they comprise the + /// same base image. It is valid for this item to be zero, in which case the capsule cannot + /// be split into components. + /// EFI_GUID InstanceId; + /// + /// The offset in bytes from the beginning of the header to the start of an EFI string that + /// contains a description of the identity of the subcapsules that make up the capsule. If + /// the capsule is not split, this value should be zero. The same string should be + /// presented for all subcapsules that constitute the same capsule. + /// UINT32 OffsetToSplitInformation; + /// + /// The offset in bytes from the beginning of the header to the start of the part of the + /// capsule that is to be transferred to DXE. + /// UINT32 OffsetToCapsuleBody; + /// + /// The offset in bytes from the beginning of the header to the start of the OEM-defined + /// header. This value must be less than OffsetToCapsuleBody. + /// UINT32 OffsetToOemDefinedHeader; + /// + /// The offset in bytes from the beginning of the header to the start of human-readable + /// text that describes the entity that created the capsule. This value must be less than OffsetToCapsuleBody. + /// UINT32 OffsetToAuthorInformation; + /// + /// The offset in bytes from the beginning of the header to the start of human-readable + /// text that describes the revision of the capsule and/or the capsule¡¯s contents. This + /// value must be less than OffsetToCapsuleBody. + /// UINT32 OffsetToRevisionInformation; + /// + /// The offset in bytes from the beginning of the header to the start of a one-line (less + /// than 40 Unicode characters in any language) description of the capsule. It is intended + /// to be used by OS-present applications when providing a list of capsules from which + /// the user can choose. This value must be less than OffsetToCapsuleBody. + /// UINT32 OffsetToShortDescription; + /// + /// The offset in bytes from the beginning of the header to the start of an EFI string + /// UINT32 OffsetToLongDescription; + /// + /// This field is reserved for future use by this specification. For future compatibility, + /// this field must be set to zero + /// UINT32 OffsetToApplicableDevices; } FRAMEWORK_EFI_CAPSULE_HEADER; diff --git a/IntelFrameworkPkg/Include/Ppi/SectionExtraction.h b/IntelFrameworkPkg/Include/Ppi/SectionExtraction.h index 53e3d387cc..6ba75b7fc1 100644 --- a/IntelFrameworkPkg/Include/Ppi/SectionExtraction.h +++ b/IntelFrameworkPkg/Include/Ppi/SectionExtraction.h @@ -99,7 +99,7 @@ EFI_STATUS authenticate the file encapsulation of other domain-specific wrapping. **/ struct _EFI_PEI_SECTION_EXTRACTION_PPI { - EFI_PEI_GET_SECTION PeiGetSection; ///< Retrieves a section from within a section file. + EFI_PEI_GET_SECTION GetSection; ///< Retrieves a section from within a section file. }; extern EFI_GUID gEfiPeiSectionExtractionPpiGuid; diff --git a/IntelFrameworkPkg/Include/Protocol/FrameworkFormCallback.h b/IntelFrameworkPkg/Include/Protocol/FrameworkFormCallback.h index e42459dd90..d762ad48d0 100644 --- a/IntelFrameworkPkg/Include/Protocol/FrameworkFormCallback.h +++ b/IntelFrameworkPkg/Include/Protocol/FrameworkFormCallback.h @@ -14,8 +14,6 @@ THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. - Module Name: FrameworkFormCallback.h - @par Revision Reference: This protocol is defined in HII spec 0.92. @@ -39,32 +37,26 @@ // typedef struct _EFI_FORM_CALLBACK_PROTOCOL EFI_FORM_CALLBACK_PROTOCOL; - -#define RESET_REQUIRED 1 // Flags setting to signify that the callback operation resulted in an eventual -// reset to be done upon exit of the browser -// -#define EXIT_REQUIRED 2 // Flags setting to signify that after the processing of the callback results - exit the browser -#define SAVE_REQUIRED 4 // Flags setting to signify that after the processing of the callback results - save the NV data -#define NV_CHANGED 8 // Flags setting to signify that after the processing of the callback results - turn the NV flag on -#define NV_NOT_CHANGED 16 // Flags setting to signify that after the processing of the callback results - turn the NV flag off #pragma pack(1) typedef struct { - UINT8 OpCode; // Likely a string, numeric, or one-of - UINT8 Length; // Length of the FRAMEWORK_EFI_IFR_DATA_ENTRY packet - UINT16 Flags; // Flags settings to determine what behavior is desired from the browser after the callback - VOID *Data; // The data in the form based on the op-code type - this is not a pointer to the data, the data follows immediately - // If the OpCode is a OneOf or Numeric type - Data is a UINT16 value - // If the OpCode is a String type - Data is a CHAR16[x] type - // If the OpCode is a Checkbox type - Data is a UINT8 value - // If the OpCode is a NV Access type - Data is a FRAMEWORK_EFI_IFR_NV_DATA structure - // + UINT8 OpCode; ///< Likely a string, numeric, or one-of + UINT8 Length; ///< Length of the FRAMEWORK_EFI_IFR_DATA_ENTRY packet + UINT16 Flags; ///< Flags settings to determine what behavior is desired from the browser after the callback + VOID *Data; ///< The data in the form based on the op-code type - this is not a pointer to the data, the data follows immediately + /// + /// If the OpCode is a OneOf or Numeric type - Data is a UINT16 value + /// If the OpCode is a String type - Data is a CHAR16[x] type + /// If the OpCode is a Checkbox type - Data is a UINT8 value + /// If the OpCode is a NV Access type - Data is a FRAMEWORK_EFI_IFR_NV_DATA structure + /// } FRAMEWORK_EFI_IFR_DATA_ENTRY; typedef struct { - VOID *NvRamMap; // If the flag of the op-code specified retrieval of a copy of the NVRAM map, + VOID *NvRamMap; ///< If the flag of the op-code specified retrieval of a copy of the NVRAM map, + // // this is a pointer to a buffer copy // - UINT32 EntryCount; // How many FRAMEWORK_EFI_IFR_DATA_ENTRY entries + UINT32 EntryCount; ///< How many FRAMEWORK_EFI_IFR_DATA_ENTRY entries // // FRAMEWORK_EFI_IFR_DATA_ENTRY Data[1]; // The in-line Data entries. // @@ -72,15 +64,15 @@ typedef struct { typedef union { - FRAMEWORK_EFI_IFR_DATA_ARRAY DataArray; // Primarily used by those who call back to their drivers and use HII as a repository - FRAMEWORK_EFI_IFR_PACKET DataPacket; // Primarily used by those which do not use HII as a repository - CHAR16 String[1]; // If returning an error - fill the string with null-terminated contents -} EFI_HII_CALLBACK_PACKET; + FRAMEWORK_EFI_IFR_DATA_ARRAY DataArray; ///< Primarily used by those who call back to their drivers and use HII as a repository + FRAMEWORK_EFI_IFR_PACKET DataPacket; ///< Primarily used by those which do not use HII as a repository + CHAR16 String[1]; ///< If returning an error - fill the string with null-terminated contents +} FRAMEWORK_EFI_HII_CALLBACK_PACKET; typedef struct { FRAMEWORK_EFI_IFR_OP_HEADER Header; - UINT16 QuestionId; // Offset into the map - UINT8 StorageWidth; // Width of the value + UINT16 QuestionId; ///< Offset into the map + UINT8 StorageWidth; ///< Width of the value // // CHAR8 Data[1]; // The Data itself // @@ -179,7 +171,7 @@ EFI_STATUS IN EFI_FORM_CALLBACK_PROTOCOL *This, IN UINT16 KeyValue, IN FRAMEWORK_EFI_IFR_DATA_ARRAY *Data, - OUT EFI_HII_CALLBACK_PACKET **Packet + OUT FRAMEWORK_EFI_HII_CALLBACK_PACKET **Packet ); /** -- 2.39.2