Added some functions header.
[people/mcb30/edk2.git] / edk2 / MdeModulePkg / Universal / Console / TerminalDxe / Terminal.c
index a1c2d5a..21ae6ae 100644 (file)
@@ -16,6 +16,15 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
 \r
 #include "Terminal.h"\r
 \r
+/**\r
+  Free notify functions list.\r
+\r
+  @param  ListHead               The list head\r
+\r
+  @retval EFI_SUCCESS            Free the notify list successfully.\r
+  @retval EFI_INVALID_PARAMETER  ListHead is NULL.\r
+\r
+**/\r
 EFI_STATUS\r
 TerminalFreeNotifyList (\r
   IN OUT LIST_ENTRY           *ListHead\r
@@ -109,7 +118,19 @@ TERMINAL_DEV  gTerminalDevTemplate = {
 };\r
 \r
 \r
+/**\r
+  Test to see if this driver supports ControllerHandle. \r
+\r
+  @param  This                Protocol instance pointer.\r
+  @param  ControllerHandle    Handle of device to test\r
+  @param  RemainingDevicePath Optional parameter use to pick a specific child\r
+                              device to start.\r
+\r
+  @retval EFI_SUCCESS         This driver supports this device\r
+  @retval EFI_ALREADY_STARTED This driver is already running on this device\r
+  @retval other               This driver does not support this device\r
 \r
+**/\r
 EFI_STATUS\r
 EFIAPI\r
 TerminalDriverBindingSupported (\r
@@ -208,17 +229,20 @@ TerminalDriverBindingSupported (
   return Status;\r
 }\r
 \r
-\r
 /**\r
-  Start the controller.\r
+  Start this driver on ControllerHandle by opening a Serial IO protocol,\r
+  reading Device Path, and creating a child handle with a Simple Text In,\r
+  Simple Text In Ex and Simple Text Out protocol, and device path protocol.\r
+  And store Console Device Environment Variables.\r
 \r
-  @param  This                   A pointer to the EFI_DRIVER_BINDING_PROTOCOL\r
-                                 instance.\r
-  @param  Controller             The handle of the controller to start.\r
-  @param  RemainingDevicePath    A pointer to the remaining portion of a devcie\r
-                                 path.\r
+  @param  This                 Protocol instance pointer.\r
+  @param  ControllerHandle     Handle of device to bind driver to\r
+  @param  RemainingDevicePath  Optional parameter use to pick a specific child\r
+                               device to start.\r
 \r
-  @return EFI_SUCCESS.\r
+  @retval EFI_SUCCESS          This driver is added to ControllerHandle\r
+  @retval EFI_ALREADY_STARTED  This driver is already running on ControllerHandle\r
+  @retval other                This driver does not support this device\r
 \r
 **/\r
 EFI_STATUS\r
@@ -353,7 +377,9 @@ TerminalDriverBindingStart (
     }\r
 \r
     TerminalType = FixedPcdGet8 (PcdDefaultTerminalType);\r
-    // must be between PCANSITYPE (0) and VTUTF8TYPE (3)\r
+    //\r
+    // Must be between PCANSITYPE (0) and VTUTF8TYPE (3)\r
+    //\r
     ASSERT (TerminalType <= VTUTF8TYPE);\r
 \r
     CopyMem (&DefaultNode->Guid, gTerminalType[TerminalType], sizeof (EFI_GUID));\r
@@ -726,19 +752,19 @@ Error:
   return Status;\r
 }\r
 \r
-\r
 /**\r
-  Stop a device controller.\r
+  Stop this driver on ControllerHandle by closing Simple Text In, Simple Text\r
+  In Ex, Simple Text Out protocol, and removing parent device path from\r
+  Console Device Environment Variables.    \r
 \r
-  @param  This                   A pointer to the EFI_DRIVER_BINDING_PROTOCOL\r
-                                 instance.\r
-  @param  Controller             A handle to the device being stopped.\r
-  @param  NumberOfChildren       The number of child device handles in\r
-                                 ChildHandleBuffer.\r
-  @param  ChildHandleBuffer      An array of child handles to be freed.\r
+  @param  This              Protocol instance pointer.\r
+  @param  ControllerHandle  Handle of device to stop driver on\r
+  @param  NumberOfChildren  Number of Handles in ChildHandleBuffer. If number of\r
+                            children is zero stop the entire bus driver.\r
+  @param  ChildHandleBuffer List of Child Handles to Stop.\r
 \r
-  @retval EFI_SUCCESS            Operation successful.\r
-  @retval EFI_DEVICE_ERROR       Devices error.\r
+  @retval EFI_SUCCESS       This driver is removed ControllerHandle.\r
+  @retval other             This driver could not be removed from this device.\r
 \r
 **/\r
 EFI_STATUS\r
@@ -920,11 +946,12 @@ TerminalDriverBindingStop (
 \r
 \r
 /**\r
+  Free notify functions list.\r
 \r
   @param  ListHead               The list head\r
 \r
-  @retval EFI_SUCCESS            Free the notify list successfully\r
-  @retval EFI_INVALID_PARAMETER  ListHead is invalid.\r
+  @retval EFI_SUCCESS            Free the notify list successfully.\r
+  @retval EFI_INVALID_PARAMETER  ListHead is NULL.\r
 \r
 **/\r
 EFI_STATUS\r
@@ -952,7 +979,15 @@ TerminalFreeNotifyList (
 }\r
 \r
 \r
+/**\r
+  Update terminal device path in Console Device Environment Variables.\r
+\r
+  @param  VariableName           The Console Device Environment Variable.\r
+  @param  ParentDevicePath       The terminal devcie path to be updated.\r
+\r
+  @return None.\r
 \r
+**/\r
 VOID\r
 TerminalUpdateConsoleDevVariable (\r
   IN CHAR16                    *VariableName,\r
@@ -1010,10 +1045,10 @@ TerminalUpdateConsoleDevVariable (
 \r
 \r
 /**\r
-  Remove console device variable.\r
+  Remove terminal device path from Console Device Environment Variables.\r
 \r
-  @param  VariableName           A pointer to the variable name.\r
-  @param  ParentDevicePath       A pointer to the parent device path.\r
+  @param  VariableName           Console Device Environment Variables.\r
+  @param  ParentDevicePath       The terminal devcie path to be updated.\r
 \r
   @return None.\r
 \r
@@ -1202,6 +1237,18 @@ TerminalGetVariableAndSize (
   return Buffer;\r
 }\r
 \r
+/**\r
+  Build termial device path according to terminal type.\r
+\r
+  @param  TerminalType           The terminal type is PC ANSI, VT100, VT100+ or VT-UTF8.\r
+  @param  ParentDevicePath       Parent devcie path.\r
+  @param  TerminalDevicePath     Returned terminal device path, if building successfully.\r
+\r
+  @retval EFI_UNSUPPORTED        Terminal does not belong to the supported type.\r
+  @retval EFI_OUT_OF_RESOURCES   Generate terminal device path failed.\r
+  @retval EFI_SUCCESS            Build terminal device path successfully.\r
+\r
+**/\r
 EFI_STATUS\r
 SetTerminalDevicePath (\r
   IN  UINT8                       TerminalType,\r
@@ -1276,6 +1323,14 @@ SetTerminalDevicePath (
   return EFI_SUCCESS;\r
 }\r
 \r
+/**\r
+  Initialize the Raw Data FIFO.\r
+\r
+  @param TerminalDevice          The terminal device.\r
+\r
+  @return None.\r
+\r
+**/\r
 VOID\r
 InitializeRawFiFo (\r
   IN  TERMINAL_DEV  *TerminalDevice\r
@@ -1287,6 +1342,14 @@ InitializeRawFiFo (
   TerminalDevice->RawFiFo.Head = TerminalDevice->RawFiFo.Tail;\r
 }\r
 \r
+/**\r
+  Initialize the Unicode FIFO.\r
+\r
+  @param TerminalDevice          The terminal device.\r
+\r
+  @return None.\r
+\r
+**/\r
 VOID\r
 InitializeUnicodeFiFo (\r
   IN  TERMINAL_DEV  *TerminalDevice\r
@@ -1298,6 +1361,14 @@ InitializeUnicodeFiFo (
   TerminalDevice->UnicodeFiFo.Head = TerminalDevice->UnicodeFiFo.Tail;\r
 }\r
 \r
+/**\r
+  Initialize the EFI Key FIFO.\r
+\r
+  @param TerminalDevice          The terminal device.\r
+\r
+  @return None.\r
+\r
+**/\r
 VOID\r
 InitializeEfiKeyFiFo (\r
   IN  TERMINAL_DEV  *TerminalDevice\r