Add comments for IntelFrameworkModulePkg Header file.

git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@8539 6f19259b-4bc3-4df7-8a09-765794883524

IntelFrameworkModulePkg/Include/Guid/DataHubStatusCodeRecord.h

@@ -13,8 +13,8 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
 **/
 
 
-#ifndef __STATUS_CODE_H__
+#ifndef __DATA_HUB_STATUS_CODE_RECORD_H__
-#define __STATUS_CODE_H__
+#define __DATA_HUB_STATUS_CODE_RECORD_H__
 
 #define EFI_DATA_HUB_STATUS_CODE_RECORD_GUID \
   { \
@@ -22,14 +22,34 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
   }
 
 typedef struct {
+  ///
+  /// Status Code type to be reported.
+  ///
   EFI_STATUS_CODE_TYPE  CodeType;
+
+  ///
+  /// Valu information about the class and subclass is used to
+  /// classify the hardware and software entity as well as an operation.
+  ///
   EFI_STATUS_CODE_VALUE Value;
+
+  ///
+  /// The enumeration of a hardware or software entity within
+  /// the system. Valid instance numbers start with 1
+  ///
   UINT32                Instance;
+
+  ///
+  /// Identify the caller.
+  ///
   EFI_GUID              CallerId;
+
+  ///
+  /// Additional status code data
+  ///
   EFI_STATUS_CODE_DATA  Data;
 } DATA_HUB_STATUS_CODE_DATA_RECORD;
 
 extern EFI_GUID gEfiDataHubStatusCodeRecordGuid;
 
-#endif // __STATUS_CODE_H__
+#endif
-

IntelFrameworkModulePkg/Include/Guid/MemoryStatusCodeRecord.h

@@ -1,7 +1,7 @@
 /** @file
   GUID used to identify status code records HOB that originate from the PEI status code    
   
-Copyright (c) 2006, 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        
@@ -30,15 +30,28 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
                   +---------------- MaxRecordsNumber----------------------+
 **/
 typedef struct {
-  UINT16                  PacketIndex;          // Index of the Packet.
+  UINT16                  PacketIndex;          ///< Index of the Packet.
-  UINT16                  RecordIndex;          // Index of record in the packet.
+  UINT16                  RecordIndex;          ///< Index of record in the packet.
-  UINT32                  MaxRecordsNumber;     // Max number of records in the packet.
+  UINT32                  MaxRecordsNumber;     ///< Max number of records in the packet.
 } MEMORY_STATUSCODE_PACKET_HEADER;
 
 typedef struct {
-  EFI_STATUS_CODE_TYPE    CodeType;
+  ///
-  EFI_STATUS_CODE_VALUE   Value;
+  /// Status Code type to be reported.
-  UINT32                  Instance;
+  ///
+  EFI_STATUS_CODE_TYPE  CodeType;
+
+  ///
+  /// Valu information about the class and subclass is used to
+  /// classify the hardware and software entity as well as an operation.
+  ///
+  EFI_STATUS_CODE_VALUE Value;
+
+  ///
+  /// The enumeration of a hardware or software entity within
+  /// the system. Valid instance numbers start with 1
+  ///
+  UINT32                Instance;
 } MEMORY_STATUSCODE_RECORD;
 
 

IntelFrameworkModulePkg/Include/Protocol/DiskInfo.h

@@ -1,8 +1,8 @@
 /** @file
-  Disk Info protocol is used to export Inquiry Data for a drive.
+  Disk Info protocol Provides the basic interfaces to abstract 
-  It supports low level formating of drives in a DOS compatible manner.
+  platform information regarding an IDE controller.
 
-Copyright (c) 2006 - 2008, Intel Corporation. <BR>
+Copyright (c) 2006 - 2009, Intel Corporation. <BR>
 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
@@ -27,14 +27,14 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
 typedef struct _EFI_DISK_INFO_PROTOCOL  EFI_DISK_INFO_PROTOCOL;
 
 /**
-  Return the results of the Inquiry command to a drive in InquiryData.
+  This function is used by the IDE bus driver to get inquiry data. 
-  Data format of Inquiry data is defined by the Interface GUID.
+  Data format of Identify data is defined by the Interface GUID.
 
   @param  This                  Protocol instance pointer. 
-  @param  InquiryData           Results of Inquiry command to device 
+  @param  InquiryData           Pointer to a buffer for the inquiry data.
-  @param  InquiryDataSize       Size of InquiryData in bytes. 
+  @param  InquiryDataSize       Pointer to the value for the inquiry data size.
 
-  @retval EFI_SUCCESS           InquiryData valid 
+  @retval EFI_SUCCESS           The command was accepted without any errors.
   @retval EFI_NOT_FOUND         Device does not support this data class 
   @retval EFI_DEVICE_ERROR      Error reading InquiryData from device 
   @retval EFI_BUFFER_TOO_SMALL  IntquiryDataSize not big enough 
@@ -50,14 +50,14 @@ EFI_STATUS
 
 
 /**
-  Return the results of the Identify command to a drive in IdentifyData.
+  This function is used by the IDE bus driver to get identify data. 
   Data format of Identify data is defined by the Interface GUID.
 
   @param  This                  Protocol instance pointer. 
-  @param  IdentifyData          Results of Identify command to device 
+  @param  IdentifyData          Pointer to a buffer for the identify data.
-  @param  IdentifyDataSize      Size of IdentifyData in bytes. 
+  @param  IdentifyDataSize      Pointer to the value for the identify data size.
 
-  @retval EFI_SUCCESS           IdentifyData valid 
+  @retval EFI_SUCCESS           The command was accepted without any errors.
   @retval EFI_NOT_FOUND         Device does not support this data class 
   @retval EFI_DEVICE_ERROR      Error reading IdentifyData from device 
   @retval EFI_BUFFER_TOO_SMALL  IdentifyDataSize not big enough 
@@ -73,15 +73,15 @@ EFI_STATUS
 
 
 /**
-  Return the results of the Request Sense command to a drive in SenseData.
+  This function is used by the IDE bus driver to get sense data. 
   Data format of Sense data is defined by the Interface GUID.
 
   @param  This                  Protocol instance pointer. 
-  @param  SenseData             Results of Request Sense command to device 
+  @param  SenseData             Pointer to the SenseData. 
   @param  SenseDataSize         Size of SenseData in bytes. 
-  @param  SenseDataNumber       Type of SenseData 
+  @param  SenseDataNumber       Pointer to the value for the identify data size.
 
-  @retval EFI_SUCCESS           InquiryData valid 
+  @retval EFI_SUCCESS           The command was accepted without any errors.
   @retval EFI_NOT_FOUND         Device does not support this data class 
   @retval EFI_DEVICE_ERROR      Error reading InquiryData from device 
   @retval EFI_BUFFER_TOO_SMALL  SenseDataSize not big enough 
@@ -97,11 +97,11 @@ EFI_STATUS
   );
 
 /**
-  Return the IDE device information.
+  This function is used by the IDE bus driver to get controller information.
 
   @param  This                  Protocol instance pointer. 
-  @param  IdeChannel            Primary or Secondary 
+  @param  IdeChannel            Pointer to the Ide Channel number. Primary or secondary.
-  @param  IdeDevice             Master or Slave 
+  @param  IdeDevice             Pointer to the Ide Device number. Master or slave.
 
   @retval EFI_SUCCESS           IdeChannel and IdeDevice are valid 
   @retval EFI_UNSUPPORTED       This is not an IDE device 
@@ -116,8 +116,7 @@ EFI_STATUS
   );
 
 //
-// GUIDs for EFI_DISK_INFO_PROTOCOL.Interface. Defines the format of the
+// GUID of the type of interfaces
-// buffers returned by member functions.
 //
 #define EFI_DISK_INFO_IDE_INTERFACE_GUID \
   { \
@@ -144,7 +143,10 @@ extern EFI_GUID gEfiDiskInfoUsbInterfaceGuid;
 extern EFI_GUID gEfiDiskInfoAhciInterfaceGuid;
 
 struct _EFI_DISK_INFO_PROTOCOL {
-  EFI_GUID                  Interface;  ///> The format of the buffers returned by member functions.
+  ///
+  /// A GUID that defines the format of buffers for the other member functions of this protocol.
+  ///
+  EFI_GUID                  Interface;
   EFI_DISK_INFO_INQUIRY     Inquiry;
   EFI_DISK_INFO_IDENTIFY    Identify;
   EFI_DISK_INFO_SENSE_DATA  SenseData;

IntelFrameworkModulePkg/Include/Protocol/PciHotPlugRequest.h

@@ -1,5 +1,7 @@
 /** @file
-  This protocol is used to add or remove all PCI child devices on the PCI root bridge.
+  Provides services to notify PCI bus driver that some events have happened in a hot-plug controller
+  (for example, PC Card socket, or PHPC), and ask PCI bus driver to create or destroy handles for the
+  PCI-like devices.
 
 Copyright (c) 2006 - 2009, Intel Corporation                                                         
 All rights reserved. This program and the accompanying materials                          
@@ -16,27 +18,45 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
 #define __PCI_HOTPLUG_REQUEST_H_
 
 #define EFI_PCI_HOTPLUG_REQUEST_PROTOCOL_GUID \
-{0x19cb87ab,0x2cb9,{0x4665,0x83,0x60,0xdd,0xcf,0x60,0x54,0xf7,0x9d}}
+  {0x19cb87ab,0x2cb9,{0x4665,0x83,0x60,0xdd,0xcf,0x60,0x54,0xf7,0x9d}}
 
 typedef enum {
+  ///
+  /// The PCI bus driver is requested to create handles for the specified devices. An array of
+  /// EFI_HANDLE is returned, a NULL element marks the end of the array.
+  ///
   EfiPciHotPlugRequestAdd,
+
+  ///
+  /// The PCI bus driver is requested to destroy handles for the specified devices.
+  ///
   EfiPciHotplugRequestRemove
 } EFI_PCI_HOTPLUG_OPERATION;
 
 typedef struct _EFI_PCI_HOTPLUG_REQUEST_PROTOCOL  EFI_PCI_HOTPLUG_REQUEST_PROTOCOL;
 
 /**
-  Hot plug request notify.
+  This function allows the PCI bus driver to be notified to act as requested when a hot-plug event has
+  happened on the hot-plug controller. Currently, the operations include add operation and remove operation..
   
   @param This                 A pointer to the hot plug request protocol.
-  @param Operation            The operation.
+  @param Operation            The operation the PCI bus driver is requested to make.
-  @param Controller           A pointer to the controller.
+  @param Controller           The handle of the hot-plug controller.
-  @param RemainingDevicePath  A pointer to the device path.
+  @param RemainingDevicePath  The remaining device path for the PCI-like hot-plug device.
-  @param NumberOfChildren     A the number of child handle in the ChildHandleBuffer.
+  @param NumberOfChildren     The number of child handles. 
-  @param ChildHandleBuffer    A pointer to the array contain the child handle.
+                              For a add operation, it is an output parameter. 
+                              For a remove operation, it<69><74>s an input parameter.
+  @param ChildHandleBuffer    The buffer which contains the child handles.
   
-  @retval EFI_NOT_FOUND Can not find bridge according to controller handle.
+  @retval EFI_INVALID_PARAMETER  Operation is not a legal value.
-  @retval EFI_SUCCESS   Success operating.
+                                 Controller is NULL or not a valid handle.
+                                 NumberOfChildren is NULL.
+                                 ChildHandleBuffer is NULL while Operation is add.
+  @retval EFI_OUT_OF_RESOURCES   There are no enough resources to start the devices.
+  @retval EFI_NOT_FOUND          Can not find bridge according to controller handle.
+  @retval EFI_SUCCESS            The handles for the specified device have been created or destroyed
+                                 as requested, and for an add operation, the new handles are
+                                 returned in ChildHandleBuffer.
 **/
 typedef
 EFI_STATUS