Coding style modification.

[mirror_edk2.git] / IntelFrameworkModulePkg / Bus / Isa / Ps2MouseAbsolutePointerDxe / CommPs2.h

diff --git a/IntelFrameworkModulePkg/Bus/Isa/Ps2MouseAbsolutePointerDxe/CommPs2.h b/IntelFrameworkModulePkg/Bus/Isa/Ps2MouseAbsolutePointerDxe/CommPs2.h
index 869ac019923d5948cde54a01fa840dae81a65f22..0a914655012d4363cc8678cfd78b397f3b08e481 100644 (file)
--- a/IntelFrameworkModulePkg/Bus/Isa/Ps2MouseAbsolutePointerDxe/CommPs2.h
+++ b/IntelFrameworkModulePkg/Bus/Isa/Ps2MouseAbsolutePointerDxe/CommPs2.h
@@ -1,6 +1,5 @@
 /**@file\r
   PS2 Mouse Communication Interface \r
-\r
   \r
 Copyright (c) 2006 - 2007, Intel Corporation\r
 All rights reserved. This program and the accompanying materials\r
@@ -102,266 +101,184 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
 //    0 - output buffer empty\r
 //    1 - keyboard controller data in output buffer\r
 //\r
+\r
+/**\r
+  Issue self test command via IsaIo interface.\r
+  \r
+  @param IsaIo Pointer to instance of EFI_ISA_IO_PROTOCOL\r
+  \r
+  @return EFI_SUCCESS  Success to do keyboard self testing.\r
+  @return others       Fail to do keyboard self testing.\r
+**/\r
 EFI_STATUS\r
 KbcSelfTest (\r
   IN EFI_ISA_IO_PROTOCOL                  *IsaIo\r
   )\r
-/*++\r
-\r
-Routine Description:\r
-\r
-  GC_TODO: Add function description\r
-\r
-Arguments:\r
-\r
-  IsaIo - GC_TODO: add argument description\r
-\r
-Returns:\r
-\r
-  GC_TODO: add return values\r
-\r
---*/\r
 ;\r
 \r
+/**\r
+  Issue command to enable keyboard AUX functionality.\r
+  \r
+  @param IsaIo  Pointer to instance of EFI_ISA_IO_PROTOCOL\r
+  \r
+  @return Status of command issuing.\r
+**/\r
 EFI_STATUS\r
 KbcEnableAux (\r
   IN EFI_ISA_IO_PROTOCOL                  *IsaIo\r
   )\r
-/*++\r
-\r
-Routine Description:\r
-\r
-  GC_TODO: Add function description\r
-\r
-Arguments:\r
-\r
-  IsaIo - GC_TODO: add argument description\r
-\r
-Returns:\r
-\r
-  GC_TODO: add return values\r
-\r
---*/\r
 ;\r
 \r
+/**\r
+  Issue command to disable keyboard AUX functionality.\r
+  \r
+  @param IsaIo  Pointer to instance of EFI_ISA_IO_PROTOCOL\r
+  \r
+  @return Status of command issuing.\r
+**/\r
 EFI_STATUS\r
 KbcDisableAux (\r
   IN EFI_ISA_IO_PROTOCOL                  *IsaIo\r
   )\r
-/*++\r
-\r
-Routine Description:\r
-\r
-  GC_TODO: Add function description\r
-\r
-Arguments:\r
-\r
-  IsaIo - GC_TODO: add argument description\r
-\r
-Returns:\r
-\r
-  GC_TODO: add return values\r
-\r
---*/\r
 ;\r
 \r
+/**\r
+  Issue command to enable keyboard.\r
+  \r
+  @param IsaIo  Pointer to instance of EFI_ISA_IO_PROTOCOL\r
+  \r
+  @return Status of command issuing.\r
+**/\r
 EFI_STATUS\r
 KbcEnableKb (\r
   IN EFI_ISA_IO_PROTOCOL                  *IsaIo\r
   )\r
-/*++\r
-\r
-Routine Description:\r
-\r
-  GC_TODO: Add function description\r
-\r
-Arguments:\r
-\r
-  IsaIo - GC_TODO: add argument description\r
-\r
-Returns:\r
-\r
-  GC_TODO: add return values\r
-\r
---*/\r
 ;\r
 \r
+/**\r
+  Issue command to disable keyboard.\r
+  \r
+  @param IsaIo  Pointer to instance of EFI_ISA_IO_PROTOCOL\r
+  \r
+  @return Status of command issuing.\r
+**/\r
 EFI_STATUS\r
 KbcDisableKb (\r
   IN EFI_ISA_IO_PROTOCOL                  *IsaIo\r
   )\r
-/*++\r
-\r
-Routine Description:\r
-\r
-  GC_TODO: Add function description\r
-\r
-Arguments:\r
-\r
-  IsaIo - GC_TODO: add argument description\r
-\r
-Returns:\r
-\r
-  GC_TODO: add return values\r
-\r
---*/\r
 ;\r
 \r
+/**\r
+  Issue command to check keyboard status.\r
+  \r
+  @param IsaIo          Pointer to instance of EFI_ISA_IO_PROTOCOL\r
+  @param KeyboardEnable return whether keyboard is enable.\r
+  \r
+  @return Status of command issuing.\r
+**/\r
 EFI_STATUS\r
 CheckKbStatus (\r
   IN EFI_ISA_IO_PROTOCOL                  *IsaIo,\r
   OUT BOOLEAN                             *KeyboardEnable\r
   )\r
-/*++\r
-\r
-Routine Description:\r
-\r
-  GC_TODO: Add function description\r
-\r
-Arguments:\r
-\r
-  IsaIo           - GC_TODO: add argument description\r
-  KeyboardEnable  - GC_TODO: add argument description\r
-\r
-Returns:\r
-\r
-  GC_TODO: add return values\r
-\r
---*/\r
 ;\r
 \r
+/**\r
+  Issue command to reset keyboard.\r
+  \r
+  @param IsaIo  Pointer to instance of EFI_ISA_IO_PROTOCOL\r
+  \r
+  @return Status of command issuing.\r
+**/\r
 EFI_STATUS\r
 PS2MouseReset (\r
   IN EFI_ISA_IO_PROTOCOL                  *IsaIo\r
   )\r
-/*++\r
-\r
-Routine Description:\r
-\r
-  GC_TODO: Add function description\r
-\r
-Arguments:\r
-\r
-  IsaIo - GC_TODO: add argument description\r
-\r
-Returns:\r
-\r
-  GC_TODO: add return values\r
-\r
---*/\r
 ;\r
 \r
+/**\r
+  Issue command to set mouse's sample rate\r
+  \r
+  @param IsaIo  Pointer to instance of EFI_ISA_IO_PROTOCOL\r
+  @param SampleRate value of sample rate \r
+  \r
+  @return Status of command issuing.\r
+**/\r
 EFI_STATUS\r
 PS2MouseSetSampleRate (\r
   IN EFI_ISA_IO_PROTOCOL                  *IsaIo,\r
   IN MOUSE_SR                             SampleRate\r
   )\r
-/*++\r
-\r
-Routine Description:\r
-\r
-  GC_TODO: Add function description\r
-\r
-Arguments:\r
-\r
-  IsaIo       - GC_TODO: add argument description\r
-  SampleRate  - GC_TODO: add argument description\r
-\r
-Returns:\r
-\r
-  GC_TODO: add return values\r
-\r
---*/\r
 ;\r
 \r
+/**\r
+  Issue command to set mouse's resolution.\r
+  \r
+  @param IsaIo  Pointer to instance of EFI_ISA_IO_PROTOCOL\r
+  @param Resolution value of resolution\r
+  \r
+  @return Status of command issuing.\r
+**/\r
 EFI_STATUS\r
 PS2MouseSetResolution (\r
   IN EFI_ISA_IO_PROTOCOL                  *IsaIo,\r
   IN MOUSE_RE                             Resolution\r
   )\r
-/*++\r
-\r
-Routine Description:\r
-\r
-  GC_TODO: Add function description\r
-\r
-Arguments:\r
-\r
-  IsaIo       - GC_TODO: add argument description\r
-  Resolution  - GC_TODO: add argument description\r
-\r
-Returns:\r
-\r
-  GC_TODO: add return values\r
-\r
---*/\r
 ;\r
 \r
+/**\r
+  Issue command to set mouse's scaling.\r
+  \r
+  @param IsaIo  Pointer to instance of EFI_ISA_IO_PROTOCOL\r
+  @param Scaling value of scaling\r
+  \r
+  @return Status of command issuing.\r
+**/\r
 EFI_STATUS\r
 PS2MouseSetScaling (\r
   IN EFI_ISA_IO_PROTOCOL                  *IsaIo,\r
   IN MOUSE_SF                             Scaling\r
   )\r
-/*++\r
-\r
-Routine Description:\r
-\r
-  GC_TODO: Add function description\r
-\r
-Arguments:\r
-\r
-  IsaIo   - GC_TODO: add argument description\r
-  Scaling - GC_TODO: add argument description\r
-\r
-Returns:\r
-\r
-  GC_TODO: add return values\r
-\r
---*/\r
 ;\r
 \r
+/**\r
+  Issue command to enable Ps2 mouse.\r
+  \r
+  @param IsaIo  Pointer to instance of EFI_ISA_IO_PROTOCOL\r
+  \r
+  @return Status of command issuing.\r
+**/\r
 EFI_STATUS\r
 PS2MouseEnable (\r
   IN EFI_ISA_IO_PROTOCOL                  *IsaIo\r
   )\r
-/*++\r
-\r
-Routine Description:\r
-\r
-  GC_TODO: Add function description\r
-\r
-Arguments:\r
-\r
-  IsaIo - GC_TODO: add argument description\r
+;\r
 \r
-Returns:\r
+/**\r
+  Get mouse packet . Only care first 3 bytes\r
 \r
-  GC_TODO: add return values\r
+  @param MouseDev  Pointer of PS2 Mouse Private Data Structure \r
 \r
---*/\r
-;\r
+  @retval EFI_NOT_READY  Mouse Device not ready to input data packet, or some error happened during getting the packet\r
+  @retval EFI_SUCCESS    The data packet is gotten successfully.\r
 \r
+**/\r
 EFI_STATUS\r
 PS2MouseGetPacket (\r
   PS2_MOUSE_ABSOLUTE_POINTER_DEV     *MouseAbsolutePointerDev\r
   )\r
-/*++\r
-\r
-Routine Description:\r
-\r
-  GC_TODO: Add function description\r
-\r
-Arguments:\r
-\r
-  MouseDev  - GC_TODO: add argument description\r
-\r
-Returns:\r
-\r
-  GC_TODO: add return values\r
-\r
---*/\r
 ;\r
 \r
+/**\r
+  Read data via IsaIo protocol with given number.\r
+  \r
+  @param IsaIo   Pointer to instance of EFI_ISA_IO_PROTOCOL\r
+  @param Buffer  Buffer receive data of mouse\r
+  @param BufSize The size of buffer\r
+  @param State   Check input or read data\r
+  \r
+  @return status of reading mouse data.\r
+**/\r
 EFI_STATUS\r
 PS2MouseRead (\r
   IN EFI_ISA_IO_PROTOCOL                  *IsaIo,\r
@@ -373,24 +290,61 @@ PS2MouseRead (
 //\r
 // 8042 I/O function\r
 //\r
+/**\r
+  I/O work flow of outing 8042 command.\r
+  \r
+  @param IsaIo   Pointer to instance of EFI_ISA_IO_PROTOCOL\r
+  @param Command I/O command.\r
+  \r
+  @retval EFI_SUCCESS Success to excute I/O work flow\r
+  @retval EFI_TIMEOUT Keyboard controller time out.\r
+**/\r
 EFI_STATUS\r
 Out8042Command (\r
   IN EFI_ISA_IO_PROTOCOL                  *IsaIo,\r
   IN UINT8                                Command\r
   );\r
 \r
+/**\r
+  I/O work flow of in 8042 data.\r
+  \r
+  @param IsaIo   Pointer to instance of EFI_ISA_IO_PROTOCOL\r
+  @param Data    Data value\r
+  \r
+  @retval EFI_SUCCESS Success to excute I/O work flow\r
+  @retval EFI_TIMEOUT Keyboard controller time out.\r
+**/\r
 EFI_STATUS\r
 In8042Data (\r
   IN EFI_ISA_IO_PROTOCOL                  *IsaIo,\r
   IN OUT UINT8                            *Data\r
   );\r
 \r
+/**\r
+  I/O work flow of outing 8042 data.\r
+  \r
+  @param IsaIo   Pointer to instance of EFI_ISA_IO_PROTOCOL\r
+  @param Data    Data value\r
+  \r
+  @retval EFI_SUCCESS Success to excute I/O work flow\r
+  @retval EFI_TIMEOUT Keyboard controller time out.\r
+**/\r
 EFI_STATUS\r
 Out8042Data (\r
   IN EFI_ISA_IO_PROTOCOL                  *IsaIo,\r
   IN UINT8                                Data\r
   );\r
 \r
+/**\r
+  I/O work flow of outing 8042 Aux command.\r
+  \r
+  @param IsaIo   Pointer to instance of EFI_ISA_IO_PROTOCOL\r
+  @param Command Aux I/O command\r
+  @param Resend  Whether need resend the Aux command.\r
+  \r
+  @retval EFI_SUCCESS Success to excute I/O work flow\r
+  @retval EFI_TIMEOUT Keyboard controller time out.\r
+**/\r
 EFI_STATUS\r
 Out8042AuxCommand (\r
   IN EFI_ISA_IO_PROTOCOL                  *IsaIo,\r
@@ -398,29 +352,73 @@ Out8042AuxCommand (
   IN BOOLEAN                              Resend\r
   );\r
 \r
+/**\r
+  I/O work flow of in 8042 Aux data.\r
+  \r
+  @param IsaIo   Pointer to instance of EFI_ISA_IO_PROTOCOL\r
+  @param Data    Buffer holding return value.\r
+  \r
+  @retval EFI_SUCCESS Success to excute I/O work flow\r
+  @retval EFI_TIMEOUT Keyboard controller time out.\r
+**/\r
 EFI_STATUS\r
 In8042AuxData (\r
   IN EFI_ISA_IO_PROTOCOL                  *IsaIo,\r
   IN OUT UINT8                            *Data\r
   );\r
 \r
+/**\r
+  I/O work flow of outing 8042 Aux data.\r
+  \r
+  @param IsaIo   Pointer to instance of EFI_ISA_IO_PROTOCOL\r
+  @param Command Aux I/O command\r
+  \r
+  @retval EFI_SUCCESS Success to excute I/O work flow\r
+  @retval EFI_TIMEOUT Keyboard controller time out.\r
+**/\r
 EFI_STATUS\r
 Out8042AuxData (\r
   IN EFI_ISA_IO_PROTOCOL                  *IsaIo,\r
   IN UINT8                                Data\r
   );\r
 \r
+/**\r
+  Check keyboard controller status, if it is output buffer full and for auxiliary device\r
+  \r
+  @param IsaIo   Pointer to instance of EFI_ISA_IO_PROTOCOL\r
+  \r
+  @retval EFI_SUCCESS   Keyboard controller is ready\r
+  @retval EFI_NOT_READY Keyboard controller is not ready\r
+**/\r
 EFI_STATUS\r
 CheckForInput (\r
   IN EFI_ISA_IO_PROTOCOL                  *IsaIo\r
   );\r
 \r
+/**\r
+  I/O work flow to wait input buffer empty in given time.\r
+  \r
+  @param IsaIo   Pointer to instance of EFI_ISA_IO_PROTOCOL\r
+  @param Timeout Wating time.\r
+  \r
+  @retval EFI_TIMEOUT if input is still not empty in given time.\r
+  @retval EFI_SUCCESS input is empty.\r
+**/\r
 EFI_STATUS\r
 WaitInputEmpty (\r
   IN EFI_ISA_IO_PROTOCOL                  *IsaIo,\r
   IN UINTN                                Timeout\r
   );\r
 \r
+/**\r
+  I/O work flow to wait output buffer full in given time.\r
+  \r
+  @param IsaIo   Pointer to instance of EFI_ISA_IO_PROTOCOL\r
+  @param Timeout given time\r
+  \r
+  @retval EFI_TIMEOUT  output is not full in given time\r
+  @retval EFI_SUCCESS  output is full in given time.\r
+**/\r
 EFI_STATUS\r
 WaitOutputFull (\r
   IN EFI_ISA_IO_PROTOCOL                  *IsaIo,\r