From: vanjeff Date: Thu, 11 Jun 2009 01:46:51 +0000 (+0000) Subject: update codes per MdePkg doxgen review comments. X-Git-Tag: edk2-stable201903~17761 X-Git-Url: https://git.proxmox.com/?p=mirror_edk2.git;a=commitdiff_plain;h=f754f721bf10508ca15c5c9243caa39c765662cf update codes per MdePkg doxgen review comments. git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@8526 6f19259b-4bc3-4df7-8a09-765794883524 --- diff --git a/MdePkg/Include/Base.h b/MdePkg/Include/Base.h index 4eedffde0b..f429acd658 100644 --- a/MdePkg/Include/Base.h +++ b/MdePkg/Include/Base.h @@ -489,7 +489,7 @@ typedef UINTN *BASE_LIST; This function rounds the pointer specified by Pointer to the next alignment boundary specified by Alignment. The pointer to the aligned address is returned. - @param Value The value to round up. + @param Pointer The pointer to round up. @param Alignment The alignment boundary to use to return an aligned pointer. @return Pointer to the aligned address. @@ -518,7 +518,6 @@ typedef UINTN *BASE_LIST; This macro returns the maximum of two operand specified by a and b. Both a and b must be the same numerical types, signed or unsigned. - @param TYPE Any numerical data types. @param a The first operand with any numerical type. @param b The second operand. It should be the same any numerical type with a. @@ -534,7 +533,6 @@ typedef UINTN *BASE_LIST; This macro returns the minimal of two operand specified by a and b. Both a and b must be the same numerical types, signed or unsigned. - @param TYPE Any numerical data types. @param a The first operand with any numerical type. @param b The second operand. It should be the same any numerical type with a. diff --git a/MdePkg/Include/IndustryStandard/Tpm12.h b/MdePkg/Include/IndustryStandard/Tpm12.h index 398f5956dd..f0e307ba4d 100644 --- a/MdePkg/Include/IndustryStandard/Tpm12.h +++ b/MdePkg/Include/IndustryStandard/Tpm12.h @@ -1601,18 +1601,12 @@ typedef struct tdTPM_CONTEXT_SENSITIVE { #define TPM_NV_INDEX_PERIPHERAL_BASE ((UINT32)0x00011500) #define TPM_NV_INDEX_GROUP_RESV_BASE ((UINT32)0x00010000) -/// -/// The typedefs TPM_NV_PER_ATTRIBUTES (not present in TPM 1.2 Spec. have been added -/// and structure fields that were to hold the following values -/// -typedef UINT32 TPM_NV_PER_ATTRIBUTES; - /// /// Part 2, section 19.2: TPM_NV_ATTRIBUTES /// typedef struct tdTPM_NV_ATTRIBUTES { TPM_STRUCTURE_TAG tag; - TPM_NV_PER_ATTRIBUTES attributes; + UINT32 attributes; } TPM_NV_ATTRIBUTES; #define TPM_NV_PER_READ_STCLEAR (BIT31) diff --git a/MdePkg/Include/Library/HobLib.h b/MdePkg/Include/Library/HobLib.h index 1590524493..d17de0b35e 100644 --- a/MdePkg/Include/Library/HobLib.h +++ b/MdePkg/Include/Library/HobLib.h @@ -8,7 +8,7 @@ allows the PEI phase to pass information to the DXE phase. HOBs are position independent and can be relocated easily to different memory memory locations. -Copyright (c) 2006 - 2008, Intel Corporation
+Copyright (c) 2006 - 2009, 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 which accompanies this distribution. The full text of the license may be found at @@ -419,9 +419,9 @@ BuildMemoryAllocationHob ( Returns the type of a HOB. This macro returns the HobType field from the HOB header for the - HOB specified by Hob. + HOB specified by HobStart. - @param Hob A pointer to a HOB. + @param HobStart A pointer to a HOB. @return HobType. @@ -433,9 +433,9 @@ BuildMemoryAllocationHob ( Returns the length, in bytes, of a HOB. This macro returns the HobLength field from the HOB header for the - HOB specified by Hob. + HOB specified by HobStart. - @param Hob A pointer to a HOB. + @param HobStart A pointer to a HOB. @return HobLength. @@ -447,9 +447,9 @@ BuildMemoryAllocationHob ( Returns a pointer to the next HOB in the HOB list. This macro returns a pointer to HOB that follows the - HOB specified by Hob in the HOB List. + HOB specified by HobStart in the HOB List. - @param Hob A pointer to a HOB. + @param HobStart A pointer to a HOB. @return A pointer to the next HOB in the HOB list. @@ -460,23 +460,23 @@ BuildMemoryAllocationHob ( /** Determines if a HOB is the last HOB in the HOB list. - This macro determine if the HOB specified by Hob is the - last HOB in the HOB list. If Hob is last HOB in the HOB list, + This macro determine if the HOB specified by HobStart is the + last HOB in the HOB list. If HobStart is last HOB in the HOB list, then TRUE is returned. Otherwise, FALSE is returned. - @param Hob A pointer to a HOB. + @param HobStart A pointer to a HOB. - @retval TRUE The HOB specified by Hob is the last HOB in the HOB list. - @retval FALSE The HOB specified by Hob is not the last HOB in the HOB list. + @retval TRUE The HOB specified by HobStart is the last HOB in the HOB list. + @retval FALSE The HOB specified by HobStart is not the last HOB in the HOB list. **/ -#define END_OF_HOB_LIST(Hob) (GET_HOB_TYPE (Hob) == (UINT16)EFI_HOB_TYPE_END_OF_HOB_LIST) +#define END_OF_HOB_LIST(HobStart) (GET_HOB_TYPE (HobStart) == (UINT16)EFI_HOB_TYPE_END_OF_HOB_LIST) /** Returns a pointer to data buffer from a HOB of type EFI_HOB_TYPE_GUID_EXTENSION. - This macro returns a pointer to the data buffer in a HOB specified by Hob. - Hob is assumed to be a HOB of type EFI_HOB_TYPE_GUID_EXTENSION. + This macro returns a pointer to the data buffer in a HOB specified by HobStart. + HobStart is assumed to be a HOB of type EFI_HOB_TYPE_GUID_EXTENSION. @param GuidHob A pointer to a HOB. @@ -489,8 +489,8 @@ BuildMemoryAllocationHob ( /** Returns the size of the data buffer from a HOB of type EFI_HOB_TYPE_GUID_EXTENSION. - This macro returns the size, in bytes, of the data buffer in a HOB specified by Hob. - Hob is assumed to be a HOB of type EFI_HOB_TYPE_GUID_EXTENSION. + This macro returns the size, in bytes, of the data buffer in a HOB specified by HobStart. + HobStart is assumed to be a HOB of type EFI_HOB_TYPE_GUID_EXTENSION. @param GuidHob A pointer to a HOB. diff --git a/MdePkg/Include/Library/PcdLib.h b/MdePkg/Include/Library/PcdLib.h index 3b0f830e7f..00548bebc4 100644 --- a/MdePkg/Include/Library/PcdLib.h +++ b/MdePkg/Include/Library/PcdLib.h @@ -6,7 +6,7 @@ PCD, module should be linked to a PEIM/DXE library instance to access that PCD. If a module uses PatchableInModule type PCD, it also needs the library instance to produce LibPatchPcdSetPtr() interface. For FeatureFlag/Fixed PCD, the macro interface is - translated to n variable or macro that is auto-generated by build tool in + translated to a variable or macro that is auto-generated by build tool in module's autogen.h/autogen.c. The PcdGetXX(), PcdSetXX(), PcdToken(), and PcdGetNextTokenSpace() operations are only available prior to ExitBootServices(). If access to PCD values are required diff --git a/MdePkg/Include/Library/PciLib.h b/MdePkg/Include/Library/PciLib.h index 708571bfd3..b15f69b0da 100644 --- a/MdePkg/Include/Library/PciLib.h +++ b/MdePkg/Include/Library/PciLib.h @@ -10,7 +10,7 @@ these three libraries is identical. The PCI CF8 Library and PCI Express Library simply use explicit access methods. -Copyright (c) 2006 - 2008, Intel Corporation
+Copyright (c) 2006 - 2009, 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 which accompanies this distribution. The full text of the license may be found at @@ -37,8 +37,8 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. @return The encoded PCI address. **/ -#define PCI_LIB_ADDRESS(Bus,Device,Function,Offset) \ - (((Offset) & 0xfff) | (((Function) & 0x07) << 12) | (((Device) & 0x1f) << 15) | (((Bus) & 0xff) << 20)) +#define PCI_LIB_ADDRESS(Bus,Device,Function,Register) \ + (((Register) & 0xfff) | (((Function) & 0x07) << 12) | (((Device) & 0x1f) << 15) | (((Bus) & 0xff) << 20)) /** Registers a PCI device so PCI configuration registers may be accessed after @@ -167,7 +167,7 @@ PciAnd8 ( /** Performs a bitwise AND of an 8-bit PCI configuration register with an 8-bit - value, followed by a bitwise OR with another 8-bit value. + value, followed by a bitwise OR with another 8-bit value. Reads the 8-bit PCI configuration register specified by Address, performs a bitwise AND between the read result and the value specified by AndData, diff --git a/MdePkg/Include/Protocol/ComponentName.h b/MdePkg/Include/Protocol/ComponentName.h index f7f2871375..1f0f5f1749 100644 --- a/MdePkg/Include/Protocol/ComponentName.h +++ b/MdePkg/Include/Protocol/ComponentName.h @@ -1,6 +1,6 @@ /** @file EFI Component Name Protocol as defined in the EFI 1.1 specification. - This protocol is used to retrieve user-readable names of EFI Drivers + This protocol is used to retrieve user readable names of EFI Drivers and controllers managed by EFI Drivers. Copyright (c) 2006 - 2008, Intel Corporation @@ -29,7 +29,7 @@ typedef struct _EFI_COMPONENT_NAME_PROTOCOL EFI_COMPONENT_NAME_PROTOCOL; /** - Retrieves a Unicode string that is the user-readable name of the EFI Driver. + Retrieves a Unicode string that is the user readable name of the EFI Driver. @param This A pointer to the EFI_COMPONENT_NAME_PROTOCOL instance. @param Language A pointer to a three character ISO 639-2 language identifier. diff --git a/MdePkg/Include/Protocol/ComponentName2.h b/MdePkg/Include/Protocol/ComponentName2.h index 45b2a8a881..08efec6b8d 100644 --- a/MdePkg/Include/Protocol/ComponentName2.h +++ b/MdePkg/Include/Protocol/ComponentName2.h @@ -27,7 +27,7 @@ typedef struct _EFI_COMPONENT_NAME2_PROTOCOL EFI_COMPONENT_NAME2_PROTOCOL; /** - Retrieves a Unicode string that is the user-readable name of + Retrieves a Unicode string that is the user readable name of the EFI Driver. @param This A pointer to the diff --git a/MdePkg/Include/Protocol/DeviceIo.h b/MdePkg/Include/Protocol/DeviceIo.h index fc68603b34..99a48cdccb 100644 --- a/MdePkg/Include/Protocol/DeviceIo.h +++ b/MdePkg/Include/Protocol/DeviceIo.h @@ -135,7 +135,7 @@ typedef enum { @param Operation Indicates if the bus master is going to read or write to system memory. @param HostAddress The system memory address to map to the device. @param NumberOfBytes On input, the number of bytes to map. - On output the number of bytes that were mapped. + On output, the number of bytes that were mapped. @param DeviceAddress The resulting map address for the bus master device to use to access the hosts HostAddress. @param Mapping A resulting value to pass to Unmap(). diff --git a/MdePkg/Include/Protocol/DriverSupportedEfiVersion.h b/MdePkg/Include/Protocol/DriverSupportedEfiVersion.h index dc72ecb756..9f4d199c88 100644 --- a/MdePkg/Include/Protocol/DriverSupportedEfiVersion.h +++ b/MdePkg/Include/Protocol/DriverSupportedEfiVersion.h @@ -32,7 +32,7 @@ typedef struct _EFI_DRIVER_SUPPORTED_EFI_VERSION_PROTOCOL { /// /// The size, in bytes, of the entire structure. Future versions of this - /// specification may increase the size of the structure. + /// specification may grow the size of the structure. /// UINT32 Length; /// diff --git a/MdePkg/Include/Protocol/Ebc.h b/MdePkg/Include/Protocol/Ebc.h index 13ece4a227..6266eb5531 100644 --- a/MdePkg/Include/Protocol/Ebc.h +++ b/MdePkg/Include/Protocol/Ebc.h @@ -42,7 +42,7 @@ typedef struct _EFI_EBC_PROTOCOL EFI_EBC_PROTOCOL; @param This A pointer to the EFI_EBC_PROTOCOL instance. @param ImageHandle Handle of image for which the thunk is being created. @param EbcEntryPoint Address of the actual EBC entry point or protocol service the thunk should call. - @param Thunk Returned pointer to a created thunk. + @param Thunk Returned pointer to a thunk created. @retval EFI_SUCCESS The function completed successfully. @retval EFI_INVALID_PARAMETER Image entry point is not 2-byte aligned. @@ -119,7 +119,7 @@ EFI_STATUS returned version is identical to that returned by the EBC BREAK 1 instruction. @param This A pointer to the EFI_EBC_PROTOCOL instance. - @param Version Pointer to the location to store the returned version of the interpreter. + @param Version Pointer to where to store the returned version of the interpreter. @retval EFI_SUCCESS The function completed successfully. @retval EFI_INVALID_PARAMETER Version pointer is NULL. diff --git a/MdePkg/Include/Protocol/FirmwareVolumeBlock.h b/MdePkg/Include/Protocol/FirmwareVolumeBlock.h index d25a2a0fa0..0f9a9c1f7a 100644 --- a/MdePkg/Include/Protocol/FirmwareVolumeBlock.h +++ b/MdePkg/Include/Protocol/FirmwareVolumeBlock.h @@ -208,7 +208,7 @@ EFI_STATUS volume, a write may negate a bit in the EFI_FVB_ERASE_POLARITY state but cannot flip it back again. In general, before calling the Write() function, the caller should call the - EraseBlocks() function first to erase the block it intends to + EraseBlocks() function first to erase the specified block to write. A block erase cycle will transition bits from the (NOT)EFI_FVB_ERASE_POLARITY state back to the EFI_FVB_ERASE_POLARITY state. Implementations should be @@ -276,7 +276,7 @@ EFI_STATUS /** Erases and initializes a firmware volume block. - The EraseBlocks() function erases one or more blocks, as denoted + The EraseBlocks() function erases one or more blocks as denoted by the variable argument list. The entire parameter list of blocks must be verified before erasing any blocks. If a block is requested that does not exist within the associated firmware diff --git a/MdePkg/Include/Protocol/FormBrowser2.h b/MdePkg/Include/Protocol/FormBrowser2.h index 43589c1399..9cb3f9657c 100644 --- a/MdePkg/Include/Protocol/FormBrowser2.h +++ b/MdePkg/Include/Protocol/FormBrowser2.h @@ -29,10 +29,12 @@ typedef struct _EFI_FORM_BROWSER2_PROTOCOL EFI_FORM_BROWSER2_PROTOCOL; /** @param LeftColumn Value that designates the text column - at which the browser window will begin (left-most column). + where the browser window will begin from + the left-hand side of the screen @param RightColumn Value that designates the text - column at which the browser window will end (right-most column). + column where the browser window will end + on the right-hand side of the screen. @param TopRow Value that designates the text row from the top of the screen where the browser window diff --git a/MdePkg/Include/Protocol/GraphicsOutput.h b/MdePkg/Include/Protocol/GraphicsOutput.h index 5f2e6e1746..8d63f9787e 100644 --- a/MdePkg/Include/Protocol/GraphicsOutput.h +++ b/MdePkg/Include/Protocol/GraphicsOutput.h @@ -33,7 +33,7 @@ typedef struct { typedef enum { /// - /// A pixel is 32-bits. Byte zero represents red, byte one represents green, + /// A pixel is 32-bits and byte zero represents red, byte one represents green, /// byte two represents blue, and byte three is reserved. This is the definition /// for the physical frame buffer. The byte values for the red, green, and blue /// components represent the color intensity. This color intensity value range @@ -41,7 +41,7 @@ typedef enum { /// PixelRedGreenBlueReserved8BitPerColor, /// - /// A pixel is 32-bits. Byte zero represents blue, byte one represents green, + /// A pixel is 32-bits and byte zero represents blue, byte one represents green, /// byte two represents red, and byte three is reserved. This is the definition /// for the physical frame buffer. The byte values for the red, green, and blue /// components represent the color intensity. This color intensity value range diff --git a/MdePkg/Include/Protocol/Hash.h b/MdePkg/Include/Protocol/Hash.h index e5cc8ded3a..6441bfe7a8 100644 --- a/MdePkg/Include/Protocol/Hash.h +++ b/MdePkg/Include/Protocol/Hash.h @@ -79,7 +79,7 @@ typedef union { } EFI_HASH_OUTPUT; /** - Returns the size of the hash that results from a specific algorithm. + Returns the size of the hash which results from a specific algorithm. @param This Points to this instance of EFI_HASH_PROTOCOL. @param HashAlgorithm Points to the EFI_GUID which identifies the algorithm to use. @@ -100,7 +100,7 @@ EFI_STATUS ); /** - Returns the size of the hash that results from a specific algorithm. + Returns the size of the hash which results from a specific algorithm. @param This Points to this instance of EFI_HASH_PROTOCOL. @param HashAlgorithm Points to the EFI_GUID which identifies the algorithm to use. diff --git a/MdePkg/Include/Protocol/HiiConfigRouting.h b/MdePkg/Include/Protocol/HiiConfigRouting.h index dbdaca3827..3cbca370f1 100644 --- a/MdePkg/Include/Protocol/HiiConfigRouting.h +++ b/MdePkg/Include/Protocol/HiiConfigRouting.h @@ -402,7 +402,7 @@ struct _EFI_HII_CONFIG_ROUTING_PROTOCOL { EFI_HII_ROUTE_CONFIG RouteConfig; EFI_HII_BLOCK_TO_CONFIG BlockToConfig; EFI_HII_CONFIG_TO_BLOCK ConfigToBlock; - EFI_HII_GET_ALT_CFG GetAltConfig; + EFI_HII_GET_ALT_CFG GetAltConfig; }; extern EFI_GUID gEfiHiiConfigRoutingProtocolGuid; diff --git a/MdePkg/Include/Protocol/HiiDatabase.h b/MdePkg/Include/Protocol/HiiDatabase.h index 4fb26134bc..45012717fc 100644 --- a/MdePkg/Include/Protocol/HiiDatabase.h +++ b/MdePkg/Include/Protocol/HiiDatabase.h @@ -147,7 +147,8 @@ EFI_STATUS EFI_HII_PACKAGE_TYPE_GUID, the Guid field, as defined in EFI_HII_PACKAGE_GUID_HEADER. Iterate through the packages within the existing package list in the HII database specified by - Handle. If a package's type matches one of the collected types, then perform the following steps: + Handle. If a package's type matches one of the collected types collected + in step 1, then perform the following steps: - Call any functions registered with the notification type REMOVE_PACK. - Remove the package from the package list and the HII diff --git a/MdePkg/Include/Protocol/HiiFont.h b/MdePkg/Include/Protocol/HiiFont.h index 2b836158d9..607964c7e2 100644 --- a/MdePkg/Include/Protocol/HiiFont.h +++ b/MdePkg/Include/Protocol/HiiFont.h @@ -90,10 +90,10 @@ typedef struct { /** Describes font output-related information. - This structure is used for describing the way a string + This structure is used for describing the way in which a string should be rendered in a particular font. FontInfo specifies the - basic font information, and ForegroundColor and BackgroundColor - specify the color in which the characters should be displayed. The flags + basic font information and ForegroundColor and BackgroundColor + specify the color in which they should be displayed. The flags in FontInfoMask describe where the system default should be supplied instead of the specified information. The flags also describe what options can be used to make a match between the diff --git a/MdePkg/Include/Protocol/Ip4.h b/MdePkg/Include/Protocol/Ip4.h index 5dc2dc69e7..beb114a6e5 100644 --- a/MdePkg/Include/Protocol/Ip4.h +++ b/MdePkg/Include/Protocol/Ip4.h @@ -512,7 +512,7 @@ EFI_STATUS Abort an asynchronous transmit or receive request. The Cancel() function is used to abort a pending transmit or receive request. - If the token is in the transmit or receive request queues, then after calling this + If the token is in the transmit or receive request queues, after calling this function, Token->Status will be set to EFI_ABORTED and then Token->Event will be signaled. If the token is not in one of the queues, which usually means the asynchronous operation has completed, this function will not signal the token diff --git a/MdePkg/Include/Protocol/Metronome.h b/MdePkg/Include/Protocol/Metronome.h index bef64a5963..2383c73046 100644 --- a/MdePkg/Include/Protocol/Metronome.h +++ b/MdePkg/Include/Protocol/Metronome.h @@ -33,7 +33,7 @@ typedef struct _EFI_METRONOME_ARCH_PROTOCOL EFI_METRONOME_ARCH_PROTOCOL; TickNumber from a known time source in the platform. If TickNumber of ticks are detected, then EFI_SUCCESS is returned. The actual time passed between entry of this function and the first tick is between 0 and - TickPeriod 100 nS units. To guarantee that at least TickPeriod + TickPeriod 100 nS units. If you want to guarantee that at least TickPeriod time has elapsed, wait for two ticks. This function waits for a hardware event to determine when a tick occurs. It is possible for interrupt processing, or exception processing to interrupt the execution of the diff --git a/MdePkg/Include/Protocol/Mtftp4.h b/MdePkg/Include/Protocol/Mtftp4.h index 149c6270e0..988cbe1627 100644 --- a/MdePkg/Include/Protocol/Mtftp4.h +++ b/MdePkg/Include/Protocol/Mtftp4.h @@ -184,7 +184,7 @@ typedef struct { /** A callback function that is provided by the caller to intercept the EFI_MTFTP4_OPCODE_DATA or EFI_MTFTP4_OPCODE_DATA8 packets processed in the - EFI_MTFTP4_PROTOCOL.ReadFile() function, or alternatively to intercept + EFI_MTFTP4_PROTOCOL.ReadFile() function, and alternatively to intercept EFI_MTFTP4_OPCODE_OACK or EFI_MTFTP4_OPCODE_ERROR packets during a call to EFI_MTFTP4_PROTOCOL.ReadFile(), WriteFile() or ReadDirectory(). diff --git a/MdePkg/Include/Protocol/PlatformToDriverConfiguration.h b/MdePkg/Include/Protocol/PlatformToDriverConfiguration.h index 6c974caf64..628873c59e 100644 --- a/MdePkg/Include/Protocol/PlatformToDriverConfiguration.h +++ b/MdePkg/Include/Protocol/PlatformToDriverConfiguration.h @@ -76,7 +76,7 @@ typedef struct _EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOCOL EFI_PLATFORM_TO_DR should not attempt to free ParameterTypeGuid. @param ParameterBlock The platform returns a pointer to the - ParameterBlock structure, which + ParameterBlock structure which contains details about the configuration parameters specific to the ParameterTypeGuid. This structure @@ -85,7 +85,7 @@ typedef struct _EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOCOL EFI_PLATFORM_TO_DR protocols. UEFI driver decodes this structure and its contents based on ProtocolGuid. ParameterBlock is - allocated by the platform. The + allocated by the platform and the platform is responsible for freeing the ParameterBlock after Result is called. @@ -201,33 +201,33 @@ typedef enum { ParameterTypeGuid. The platform is responsible for freeing ParameterBlock and the UEFI driver must not try to free it. - @param This A pointer to the EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOCOL instance. + @param This A pointer to the EFI_PLATFORM_TO_DRIVER_CONFIGURATION_PROTOCOL instance. - @param ControllerHandle The handle the driver is returning - configuration information about. + @param ControllerHandle The handle the driver is returning + configuration information about. - @param ChildHandle The handle of the child controller to - return information on. This is an optional - parameter that may be NULL. It will be - NULL for device drivers, and for bus - drivers that attempt to get options for - the bus controller. It will not be NULL - for a bus driver that attempts to get - options for one of its child controllers. - Instance Instance data returned from - Query(). + @param ChildHandle The handle of the child controller to + return information on. This is an optional + parameter that may be NULL. It will be + NULL for device drivers, and for bus + drivers that attempt to get options for + the bus controller. It will not be NULL + for a bus driver that attempts to get + options for one of its child controllers. + Instance Instance data returned from + Query(). - @param Instance Instance data passed to Query(). + @param Instance Instance data passed to Query(). - @param ParameterTypeGuid ParameterTypeGuid returned from Query. + @param ParameterTypeGuid ParameterTypeGuid returned from Query. - @param ParameterBlock ParameterBlock returned from Query. + @param ParameterBlock ParameterBlock returned from Query. - @param ParameterBlockSize The ParameterBlock size returned from Query. + @param ParameterBlockSize The ParameterBlock size returned from Query. - @param ConfigurationAction The driver tells the platform what - action is required for ParameterBlock to - take effect. + @param ConfigurationAction The driver tells the platform what + action is required for ParameterBlock to + take effect. @retval EFI_SUCCESS The platform return parameter information diff --git a/MdePkg/Include/Protocol/ScsiPassThruExt.h b/MdePkg/Include/Protocol/ScsiPassThruExt.h index 176db59aee..611e8a2887 100644 --- a/MdePkg/Include/Protocol/ScsiPassThruExt.h +++ b/MdePkg/Include/Protocol/ScsiPassThruExt.h @@ -153,8 +153,8 @@ typedef struct { nonblocking I/O functionality is optional. @param This A pointer to the EFI_EXT_SCSI_PASS_THRU_PROTOCOL instance. - @param Target The Target is an array of size TARGET_MAX_BYTES. It represents - the id of the SCSI device that will send the SCSI Request Packet. Each + @param Target The Target is an array of size TARGET_MAX_BYTES and it represents + the id of the SCSI device to send the SCSI Request Packet. Each transport driver may choose to utilize a subset of this size to suit the needs of transport target representation. For example, a Fibre Channel driver may use only 8 bytes (WWN) to represent an FC target. @@ -201,7 +201,7 @@ EFI_STATUS /** Used to retrieve the list of legal Target IDs and LUNs for SCSI devices on a SCSI channel. These can either be the list SCSI devices that are actually present on the SCSI channel, or the list of legal - Target Ids and LUNs for the SCSI channel. Either way, the caller of this function must probe the + Target Ids and LUNs for the SCSI channel. Regardless, the caller of this function must probe the Target ID and LUN returned to see if a SCSI device is actually present at that location on the SCSI channel. @@ -317,7 +317,7 @@ EFI_STATUS Resets a SCSI logical unit that is connected to a SCSI channel. @param This A pointer to the EFI_EXT_SCSI_PASS_THRU_PROTOCOL instance. - @param Target The Target is an array of size TARGET_MAX_BYTE. It represents the + @param Target The Target is an array of size TARGET_MAX_BYTE and it represents the target port ID of the SCSI device containing the SCSI logical unit to reset. Transport drivers may chose to utilize a subset of this array to suit the representation of their targets. diff --git a/MdePkg/Include/Protocol/SerialIo.h b/MdePkg/Include/Protocol/SerialIo.h index 4fbfe027eb..aca2cac188 100644 --- a/MdePkg/Include/Protocol/SerialIo.h +++ b/MdePkg/Include/Protocol/SerialIo.h @@ -104,13 +104,8 @@ EFI_STATUS ); /** - Sets the following attributes for a serial device: - * baud rate - * receive FIFO depth - * transmit/receive time out - * parity - * data bits - * stop bits + Sets the baud rate, receive FIFO depth, transmit/receice time out, parity, + data buts, and stop bits on a serial device. @param This Protocol instance pointer. @param BaudRate The requested baud rate. A BaudRate value of 0 will use the @@ -208,7 +203,7 @@ EFI_STATUS @param This Protocol instance pointer. @param BufferSize On input, the size of the Buffer. On output, the amount of data returned in Buffer. - @param Buffer The buffer to which to return the data. + @param Buffer The buffer to return the data into. @retval EFI_SUCCESS The data was read. @retval EFI_DEVICE_ERROR The device reported an error. @@ -277,8 +272,8 @@ typedef struct { /// /// The Serial I/O protocol is used to communicate with UART-style serial devices. -/// These can be standard UART serial ports in PC-AT systems, or serial ports attached -/// to a USB interface or any character-based I/O device. +/// These can be standard UART serial ports in PC-AT systems, serial ports attached +/// to a USB interface, or potentially any character-based I/O device. /// struct _EFI_SERIAL_IO_PROTOCOL { /// diff --git a/MdePkg/Include/Protocol/SimpleFileSystem.h b/MdePkg/Include/Protocol/SimpleFileSystem.h index 0733235180..6396e4df36 100644 --- a/MdePkg/Include/Protocol/SimpleFileSystem.h +++ b/MdePkg/Include/Protocol/SimpleFileSystem.h @@ -181,16 +181,17 @@ EFI_STATUS ); /** - Write data from or to the file. + Write data to a file. @param This Protocol instance pointer. - @param BufferSize On input: size of buffer. On output: amount of data in buffer. - @param Buffer The buffer in which to write data. + @param BufferSize On input size of buffer, on output amount of data in buffer. + @param Buffer The buffer in which data to write. @retval EFI_SUCCESS Data was written. @retval EFI_UNSUPPORT Writes to Open directory are not supported @retval EFI_NO_MEDIA The device has no media @retval EFI_DEVICE_ERROR The device reported an error + @retval EFI_DEVICE_ERROR An attempt was made to write to a deleted file @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted @retval EFI_WRITE_PROTECTED The device is write protected @retval EFI_ACCESS_DENIED The file was open for read only @@ -209,7 +210,7 @@ EFI_STATUS Set a files current position @param This Protocol instance pointer. - @param Position Byte position, from the start of the file + @param Position Byte position from the start of the file @retval EFI_SUCCESS Data was written. @retval EFI_UNSUPPORTED Seek request for non-zero is not valid on open. @@ -226,7 +227,7 @@ EFI_STATUS Get a file's current position @param This Protocol instance pointer. - @param Position Byte position, from the start of the file + @param Position Byte position from the start of the file @retval EFI_SUCCESS Data was written. @retval EFI_UNSUPPORTED Seek request for non-zero is not valid on open. @@ -244,7 +245,7 @@ EFI_STATUS @param This Protocol instance pointer. @param InformationType Type of info to return in Buffer - @param BufferSize On input: size of buffer. On output: amount of data in buffer. + @param BufferSize On input size of buffer, on output amount of data in buffer. @param Buffer The buffer to return data. @retval EFI_SUCCESS Data was returned. diff --git a/MdePkg/Include/Protocol/SimpleTextInEx.h b/MdePkg/Include/Protocol/SimpleTextInEx.h index 98d0c583dc..5baede162f 100644 --- a/MdePkg/Include/Protocol/SimpleTextInEx.h +++ b/MdePkg/Include/Protocol/SimpleTextInEx.h @@ -151,27 +151,28 @@ typedef struct { EFI_NOT_READY. If there is a pending keystroke, then KeyData.Key.ScanCode is the EFI scan code defined in Error! Reference source not found. The KeyData.Key.UnicodeChar is the - actual printable character, or is zero if the key does not + actual printable character or is zero if the key does not represent a printable character (control key, function key, etc.). The KeyData.KeyState is shift state for the character reflected in KeyData.Key.UnicodeChar or KeyData.Key.ScanCode . - When interpreting the data from this function, printable characters that are + When interpreting the data from this function, it should be + noted that if a class of printable characters that are normally adjusted by shift modifiers (e.g. Shift Key + "f" - key) are presented solely as a KeyData.Key.UnicodeChar - without the associated shift state. For example, - if Shift Key + "f" key are pressed, the only pertinent + key) would be presented solely as a KeyData.Key.UnicodeChar + without the associated shift state. So in the previous example + of a Shift Key + "f" key being pressed, the only pertinent data returned would be KeyData.Key.UnicodeChar with the value - of "F". This would not typically be the case for - non-printable characters such as pressing the Right - Shift Key + F10 key, since the corresponding returned data + of "F". This of course would not typically be the case for + non-printable characters such as the pressing of the Right + Shift Key + F10 key since the corresponding returned data would be reflected both in the KeyData.KeyState.KeyShiftState and KeyData.Key.ScanCode values. UEFI drivers which implement the EFI_SIMPLE_TEXT_INPUT_EX protocol are required to return KeyData.Key and KeyData.KeyState values. These drivers must always return the most current state of KeyData.KeyState.KeyShiftState and - KeyData.KeyState.KeyToggleState. - Certain input devices may not be able to produce shift or toggle + KeyData.KeyState.KeyToggleState. It should also be noted that + certain input devices may not be able to produce shift or toggle state information, and in those cases the high order bit in the respective Toggle and Shift state fields should not be active. @@ -238,7 +239,7 @@ EFI_STATUS /** The RegisterKeystrokeNotify() function registers a function - to be called when a specified keystroke will occur. + which will be called when a specified keystroke will occur. @param This A pointer to the EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL instance. @@ -271,8 +272,8 @@ EFI_STATUS ); /** - The UnregisterKeystrokeNotify() function removes a - notification that was previously registered. + The UnregisterKeystrokeNotify() function removes the + notification which was previously registered. @param This A pointer to the EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL instance. diff --git a/MdePkg/Include/Protocol/SimpleTextOut.h b/MdePkg/Include/Protocol/SimpleTextOut.h index f2d22030ed..b75e52a696 100644 --- a/MdePkg/Include/Protocol/SimpleTextOut.h +++ b/MdePkg/Include/Protocol/SimpleTextOut.h @@ -262,9 +262,9 @@ EFI_STATUS bits 4..6 are the background color. All other bits are undefined and must be zero. The valid Attributes are defined in this file. - @retval EFI_SUCCESS The attribute was set. + @retval EFI_SUCCESS The attribute was set. @retval EFI_DEVICE_ERROR The device had an error and could not complete the request. - @retval EFI_UNSUPPORTED The attribute requested is not defined. + @retval EFI_UNSUPPORTED The attribute requested is not defined. **/ typedef @@ -342,35 +342,34 @@ EFI_STATUS Mode Structure pointed to by Simple Text Out protocol. **/ typedef struct { -/// -/// The number of modes supported by QueryMode () and SetMode (). -/// + /// + /// The number of modes supported by QueryMode () and SetMode (). + /// INT32 MaxMode; // // current settings // -/// -/// The text mode of the output device(s). -/// + /// + /// The text mode of the output device(s). + /// INT32 Mode; - -/// -/// The current character output attribute -/// + /// + /// The current character output attribute + /// INT32 Attribute; -/// -/// The cursor's column. -/// + /// + /// The cursor's column. + /// INT32 CursorColumn; -/// -/// The cursor's row. -/// + /// + /// The cursor's row. + /// INT32 CursorRow; -/// -/// The cursor is currently visbile or not. -/// + /// + /// The cursor is currently visbile or not. + /// BOOLEAN CursorVisible; } EFI_SIMPLE_TEXT_OUTPUT_MODE; diff --git a/MdePkg/Include/Protocol/SmbusHc.h b/MdePkg/Include/Protocol/SmbusHc.h index 067ebb2b0a..ffa7cff50e 100644 --- a/MdePkg/Include/Protocol/SmbusHc.h +++ b/MdePkg/Include/Protocol/SmbusHc.h @@ -51,6 +51,7 @@ typedef struct _EFI_SMBUS_HC_PROTOCOL EFI_SMBUS_HC_PROTOCOL; EFI_SMBUS_DEVICE_COMMAND is defined in EFI_PEI_SMBUS_PPI.Execute() in the Platform Initialization SMBus PPI Specification. + @param Operation Signifies the particular SMBus hardware protocol instance it will use to execute the SMBus transactions. This SMBus @@ -249,10 +250,10 @@ EFI_STATUS @param This A pointer to the EFI_SMBUS_HC_PROTOCOL instance. @param SlaveAddress Address that the host controller detects - as sending a message, and that calls all the registered function. + as sending a message and calls all the registered function. @param Data Data that the host controller detects as sending - message, and that calls all the registered function. + message and calls all the registered function. @param NotifyFunction The function to call when the bus diff --git a/MdePkg/Include/Protocol/Tcp4.h b/MdePkg/Include/Protocol/Tcp4.h index 544236b10d..d750fe9c78 100644 --- a/MdePkg/Include/Protocol/Tcp4.h +++ b/MdePkg/Include/Protocol/Tcp4.h @@ -279,7 +279,7 @@ EFI_STATUS - This is NULL. - ConnectionToken is NULL. - ConnectionToken->CompletionToken.Event is NULL. - @retval EFI_OUT_OF_RESOURCES The driver can't allocate enough resources to initiate the activeopen. + @retval EFI_OUT_OF_RESOURCES The driver can't allocate enough resource to initiate the activeopen. @retval EFI_DEVICE_ERROR An unexpected system or network error occurred. **/ @@ -308,8 +308,8 @@ EFI_STATUS - This is NULL. - ListenToken is NULL. - ListentToken->CompletionToken.Event is NULL. - @retval EFI_OUT_OF_RESOURCES Could not allocate enough resources to finish the operation. - @retval EFI_DEVICE_ERROR Any unexpected error not covered by another error. + @retval EFI_OUT_OF_RESOURCES Could not allocate enough resource to finish the operation. + @retval EFI_DEVICE_ERROR Any unexpected and not belonged to above category error. **/ typedef @@ -389,7 +389,7 @@ EFI_STATUS Tcp4StateListen state. - User has called Close() to disconnect this connection. @retval EFI_CONNECTION_FIN The communication peer has closed the connection and there is - no buffered data in the receive buffer of this instance. + no any buffered data in the receive buffer of this instance. @retval EFI_NOT_READY The receive request could not be queued because the receive queue is full. **/ @@ -419,8 +419,8 @@ EFI_STATUS - This is NULL. - CloseToken is NULL. - CloseToken->CompletionToken.Event is NULL. - @retval EFI_OUT_OF_RESOURCES Could not allocate enough resources to finish the operation. - @retval EFI_DEVICE_ERROR Any unexpected error not covered by another error. + @retval EFI_OUT_OF_RESOURCES Could not allocate enough resource to finish the operation. + @retval EFI_DEVICE_ERROR Any unexpected and not belonged to above category error. **/ typedef diff --git a/MdePkg/Include/Protocol/WatchdogTimer.h b/MdePkg/Include/Protocol/WatchdogTimer.h index efe898765f..2727862038 100644 --- a/MdePkg/Include/Protocol/WatchdogTimer.h +++ b/MdePkg/Include/Protocol/WatchdogTimer.h @@ -108,7 +108,8 @@ EFI_STATUS will wait before the watchdog timer is fired. If TimerPeriod of zero is returned, then the watchdog timer is disabled. - @retval EFI_SUCCESS The function successfully returned TimerPeriod with the amount of time that the system will wait before firing the watchdog timer. + @retval EFI_SUCCESS The amount of time that the system will wait before + firing the watchdog timer was returned in TimerPeriod. @retval EFI_INVALID_PARAMETER TimerPeriod is NULL. **/ diff --git a/MdePkg/Include/Uefi/UefiBaseType.h b/MdePkg/Include/Uefi/UefiBaseType.h index 405e9bbed3..c500a0fc1f 100644 --- a/MdePkg/Include/Uefi/UefiBaseType.h +++ b/MdePkg/Include/Uefi/UefiBaseType.h @@ -224,7 +224,7 @@ typedef union { /// /// This is just to make sure you can cross compile with the EBC compiler. /// It does not make sense to have a PE loader coded in EBC. You need to -/// understand the basic +/// understand the basic. /// #define EFI_IMAGE_MACHINE_TYPE_SUPPORTED(Machine) ((Machine) == EFI_IMAGE_MACHINE_EBC) diff --git a/MdePkg/Include/Uefi/UefiSpec.h b/MdePkg/Include/Uefi/UefiSpec.h index 65153fa185..a555350527 100644 --- a/MdePkg/Include/Uefi/UefiSpec.h +++ b/MdePkg/Include/Uefi/UefiSpec.h @@ -964,7 +964,7 @@ typedef enum { /// EfiResetWarm, /// - /// Used to induce an entry into the power state equivalent to the ACPI G2/S5 or G3 + /// Used to induce an entry into a power state equivalent to the ACPI G2/S5 or G3 /// state. If the system does not support this reset type, then when the system /// is rebooted, it should exhibit the EfiResetCold attributes. ///