Add comments for IntelFrameworkModulePkg Header file.

[mirror_edk2.git] / IntelFrameworkModulePkg / Include / Protocol / PciHotPlugRequest.h

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