From ff1fcef8426337298b156f73abbbe57d98408627 Mon Sep 17 00:00:00 2001 From: klu2 Date: Mon, 14 Apr 2008 03:22:08 +0000 Subject: [PATCH] Add function's doxygen header for Ps2Mouse module. git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@5060 6f19259b-4bc3-4df7-8a09-765794883524 --- .../Bus/Isa/Ps2MouseDxe/CommPs2.c | 522 ++++++------------ .../Bus/Isa/Ps2MouseDxe/CommPs2.h | 367 ++++++------ .../Bus/Isa/Ps2MouseDxe/Ps2Mouse.c | 214 +++---- 3 files changed, 458 insertions(+), 645 deletions(-) diff --git a/IntelFrameworkModulePkg/Bus/Isa/Ps2MouseDxe/CommPs2.c b/IntelFrameworkModulePkg/Bus/Isa/Ps2MouseDxe/CommPs2.c index 4236d70702..ede1d5664c 100644 --- a/IntelFrameworkModulePkg/Bus/Isa/Ps2MouseDxe/CommPs2.c +++ b/IntelFrameworkModulePkg/Bus/Isa/Ps2MouseDxe/CommPs2.c @@ -19,26 +19,18 @@ UINT8 SampleRateTbl[MAX_SR] = { 0xa, 0x14, 0x28, 0x3c, 0x50, 0x64, 0xc8 }; UINT8 ResolutionTbl[MAX_CMR] = { 0, 1, 2, 3 }; +/** + Issue self test command via IsaIo interface. + + @param IsaIo Pointer to instance of EFI_ISA_IO_PROTOCOL + + @return EFI_SUCCESS Success to do keyboard self testing. + @return others Fail to do keyboard self testing. +**/ EFI_STATUS KbcSelfTest ( IN EFI_ISA_IO_PROTOCOL *IsaIo ) -/** - -Routine Description: - - GC_TODO: Add function description - -Arguments: - - IsaIo - GC_TODO: add argument description - -Returns: - - EFI_DEVICE_ERROR - GC_TODO: Add description for return value - EFI_SUCCESS - GC_TODO: Add description for return value - -**/ { EFI_STATUS Status; UINT8 Data; @@ -88,25 +80,17 @@ Returns: return EFI_SUCCESS; } +/** + Issue command to enable keyboard AUX functionality. + + @param IsaIo Pointer to instance of EFI_ISA_IO_PROTOCOL + + @return Status of command issuing. +**/ EFI_STATUS KbcEnableAux ( IN EFI_ISA_IO_PROTOCOL *IsaIo ) -/** - -Routine Description: - - GC_TODO: Add function description - -Arguments: - - IsaIo - GC_TODO: add argument description - -Returns: - - GC_TODO: add return values - -**/ { // // Send 8042 enable mouse command @@ -114,25 +98,17 @@ Returns: return Out8042Command (IsaIo, ENABLE_AUX); } +/** + Issue command to disable keyboard AUX functionality. + + @param IsaIo Pointer to instance of EFI_ISA_IO_PROTOCOL + + @return Status of command issuing. +**/ EFI_STATUS KbcDisableAux ( IN EFI_ISA_IO_PROTOCOL *IsaIo ) -/** - -Routine Description: - - GC_TODO: Add function description - -Arguments: - - IsaIo - GC_TODO: add argument description - -Returns: - - GC_TODO: add return values - -**/ { // // Send 8042 disable mouse command @@ -140,25 +116,17 @@ Returns: return Out8042Command (IsaIo, DISABLE_AUX); } +/** + Issue command to enable keyboard. + + @param IsaIo Pointer to instance of EFI_ISA_IO_PROTOCOL + + @return Status of command issuing. +**/ EFI_STATUS KbcEnableKb ( IN EFI_ISA_IO_PROTOCOL *IsaIo ) -/** - -Routine Description: - - GC_TODO: Add function description - -Arguments: - - IsaIo - GC_TODO: add argument description - -Returns: - - GC_TODO: add return values - -**/ { // // Send 8042 enable keyboard command @@ -166,25 +134,17 @@ Returns: return Out8042Command (IsaIo, ENABLE_KB); } +/** + Issue command to disable keyboard. + + @param IsaIo Pointer to instance of EFI_ISA_IO_PROTOCOL + + @return Status of command issuing. +**/ EFI_STATUS KbcDisableKb ( IN EFI_ISA_IO_PROTOCOL *IsaIo ) -/** - -Routine Description: - - GC_TODO: Add function description - -Arguments: - - IsaIo - GC_TODO: add argument description - -Returns: - - GC_TODO: add return values - -**/ { // // Send 8042 disable keyboard command @@ -192,27 +152,19 @@ Returns: return Out8042Command (IsaIo, DISABLE_KB); } +/** + Issue command to check keyboard status. + + @param IsaIo Pointer to instance of EFI_ISA_IO_PROTOCOL + @param KeyboardEnable return whether keyboard is enable. + + @return Status of command issuing. +**/ EFI_STATUS CheckKbStatus ( IN EFI_ISA_IO_PROTOCOL *IsaIo, OUT BOOLEAN *KeyboardEnable ) -/** - -Routine Description: - - GC_TODO: Add function description - -Arguments: - - IsaIo - GC_TODO: add argument description - KeyboardEnable - GC_TODO: add argument description - -Returns: - - EFI_SUCCESS - GC_TODO: Add description for return value - -**/ { EFI_STATUS Status; UINT8 Data; @@ -241,27 +193,17 @@ Returns: return EFI_SUCCESS; } +/** + Issue command to reset keyboard. + + @param IsaIo Pointer to instance of EFI_ISA_IO_PROTOCOL + + @return Status of command issuing. +**/ EFI_STATUS PS2MouseReset ( IN EFI_ISA_IO_PROTOCOL *IsaIo ) -/** - -Routine Description: - - GC_TODO: Add function description - -Arguments: - - IsaIo - GC_TODO: add argument description - -Returns: - - EFI_DEVICE_ERROR - GC_TODO: Add description for return value - EFI_DEVICE_ERROR - GC_TODO: Add description for return value - EFI_SUCCESS - GC_TODO: Add description for return value - -**/ { EFI_STATUS Status; UINT8 Data; @@ -296,27 +238,19 @@ Returns: return EFI_SUCCESS; } +/** + Issue command to set mouse's sample rate + + @param IsaIo Pointer to instance of EFI_ISA_IO_PROTOCOL + @param SampleRate value of sample rate + + @return Status of command issuing. +**/ EFI_STATUS PS2MouseSetSampleRate ( IN EFI_ISA_IO_PROTOCOL *IsaIo, IN MOUSE_SR SampleRate ) -/** - -Routine Description: - - GC_TODO: Add function description - -Arguments: - - IsaIo - GC_TODO: add argument description - SampleRate - GC_TODO: add argument description - -Returns: - - GC_TODO: add return values - -**/ { EFI_STATUS Status; @@ -333,27 +267,19 @@ Returns: return Status; } +/** + Issue command to set mouse's resolution. + + @param IsaIo Pointer to instance of EFI_ISA_IO_PROTOCOL + @param Resolution value of resolution + + @return Status of command issuing. +**/ EFI_STATUS PS2MouseSetResolution ( IN EFI_ISA_IO_PROTOCOL *IsaIo, IN MOUSE_RE Resolution ) -/** - -Routine Description: - - GC_TODO: Add function description - -Arguments: - - IsaIo - GC_TODO: add argument description - Resolution - GC_TODO: add argument description - -Returns: - - GC_TODO: add return values - -**/ { EFI_STATUS Status; @@ -370,27 +296,19 @@ Returns: return Status; } +/** + Issue command to set mouse's scaling. + + @param IsaIo Pointer to instance of EFI_ISA_IO_PROTOCOL + @param Scaling value of scaling + + @return Status of command issuing. +**/ EFI_STATUS PS2MouseSetScaling ( IN EFI_ISA_IO_PROTOCOL *IsaIo, IN MOUSE_SF Scaling ) -/** - -Routine Description: - - GC_TODO: Add function description - -Arguments: - - IsaIo - GC_TODO: add argument description - Scaling - GC_TODO: add argument description - -Returns: - - GC_TODO: add return values - -**/ { UINT8 Command; @@ -402,25 +320,17 @@ Returns: return Out8042AuxCommand (IsaIo, Command, FALSE); } +/** + Issue command to enable Ps2 mouse. + + @param IsaIo Pointer to instance of EFI_ISA_IO_PROTOCOL + + @return Status of command issuing. +**/ EFI_STATUS PS2MouseEnable ( IN EFI_ISA_IO_PROTOCOL *IsaIo ) -/** - -Routine Description: - - GC_TODO: Add function description - -Arguments: - - IsaIo - GC_TODO: add argument description - -Returns: - - GC_TODO: add return values - -**/ { // // Send auxiliary command to enable mouse @@ -428,26 +338,20 @@ Returns: return Out8042AuxCommand (IsaIo, ENABLE_CMD, FALSE); } +/** + Get mouse packet . Only care first 3 bytes + + @param MouseDev Pointer of PS2 Mouse Private Data Structure + + @retval EFI_NOT_READY Mouse Device not ready to input data packet, or some error happened during getting the packet + @retval EFI_SUCCESS The data packet is gotten successfully. + +**/ EFI_STATUS PS2MouseGetPacket ( PS2_MOUSE_DEV *MouseDev ) -/** -Routine Description: - - Get mouse packet . Only care first 3 bytes - -Arguments: - - MouseDev - Pointer of PS2 Mouse Private Data Structure - -Returns: - - EFI_NOT_READY - Mouse Device not ready to input data packet, or some error happened during getting the packet - EFI_SUCCESS - The data packet is gotten successfully. - -**/ { EFI_STATUS Status; BOOLEAN KeyboardEnable; @@ -569,6 +473,16 @@ Returns: } } +/** + Read data via IsaIo protocol with given number. + + @param IsaIo Pointer to instance of EFI_ISA_IO_PROTOCOL + @param Buffer Buffer receive data of mouse + @param BufSize The size of buffer + @param State Check input or read data + + @return status of reading mouse data. +**/ EFI_STATUS PS2MouseRead ( IN EFI_ISA_IO_PROTOCOL *IsaIo, @@ -576,24 +490,6 @@ PS2MouseRead ( IN OUT UINTN *BufSize, IN UINTN State ) -/** - -Routine Description: - - GC_TODO: Add function description - -Arguments: - - IsaIo - GC_TODO: add argument description - Buffer - GC_TODO: add argument description - BufSize - GC_TODO: add argument description - State - GC_TODO: add argument description - -Returns: - - GC_TODO: add return values - -**/ { EFI_STATUS Status; UINTN BytesRead; @@ -637,27 +533,20 @@ Returns: // // 8042 I/O function // +/** + I/O work flow of outing 8042 command. + + @param IsaIo Pointer to instance of EFI_ISA_IO_PROTOCOL + @param Command I/O command. + + @retval EFI_SUCCESS Success to excute I/O work flow + @retval EFI_TIMEOUT Keyboard controller time out. +**/ EFI_STATUS Out8042Command ( IN EFI_ISA_IO_PROTOCOL *IsaIo, IN UINT8 Command ) -/** - -Routine Description: - - GC_TODO: Add function description - -Arguments: - - IsaIo - GC_TODO: add argument description - Command - GC_TODO: add argument description - -Returns: - - EFI_SUCCESS - GC_TODO: Add description for return value - -**/ { EFI_STATUS Status; UINT8 Data; @@ -683,27 +572,20 @@ Returns: return EFI_SUCCESS; } +/** + I/O work flow of outing 8042 data. + + @param IsaIo Pointer to instance of EFI_ISA_IO_PROTOCOL + @param Data Data value + + @retval EFI_SUCCESS Success to excute I/O work flow + @retval EFI_TIMEOUT Keyboard controller time out. +**/ EFI_STATUS Out8042Data ( IN EFI_ISA_IO_PROTOCOL *IsaIo, IN UINT8 Data ) -/** - -Routine Description: - - GC_TODO: Add function description - -Arguments: - - IsaIo - GC_TODO: add argument description - Data - GC_TODO: add argument description - -Returns: - - EFI_SUCCESS - GC_TODO: Add description for return value - -**/ { EFI_STATUS Status; UINT8 temp; @@ -726,28 +608,20 @@ Returns: return EFI_SUCCESS; } +/** + I/O work flow of in 8042 data. + + @param IsaIo Pointer to instance of EFI_ISA_IO_PROTOCOL + @param Data Data value + + @retval EFI_SUCCESS Success to excute I/O work flow + @retval EFI_TIMEOUT Keyboard controller time out. +**/ EFI_STATUS In8042Data ( IN EFI_ISA_IO_PROTOCOL *IsaIo, IN OUT UINT8 *Data ) -/** - -Routine Description: - - GC_TODO: Add function description - -Arguments: - - IsaIo - GC_TODO: add argument description - Data - GC_TODO: add argument description - -Returns: - - EFI_TIMEOUT - GC_TODO: Add description for return value - EFI_SUCCESS - GC_TODO: Add description for return value - -**/ { UINTN Delay; UINT8 temp; @@ -777,32 +651,22 @@ Returns: return EFI_SUCCESS; } +/** + I/O work flow of outing 8042 Aux command. + + @param IsaIo Pointer to instance of EFI_ISA_IO_PROTOCOL + @param Command Aux I/O command + @param Resend Whether need resend the Aux command. + + @retval EFI_SUCCESS Success to excute I/O work flow + @retval EFI_TIMEOUT Keyboard controller time out. +**/ EFI_STATUS Out8042AuxCommand ( IN EFI_ISA_IO_PROTOCOL *IsaIo, IN UINT8 Command, IN BOOLEAN Resend ) -/** - -Routine Description: - - GC_TODO: Add function description - -Arguments: - - IsaIo - GC_TODO: add argument description - Command - GC_TODO: add argument description - Resend - GC_TODO: add argument description - -Returns: - - EFI_SUCCESS - GC_TODO: Add description for return value - EFI_DEVICE_ERROR - GC_TODO: Add description for return value - EFI_DEVICE_ERROR - GC_TODO: Add description for return value - EFI_SUCCESS - GC_TODO: Add description for return value - -**/ { EFI_STATUS Status; UINT8 Data; @@ -869,27 +733,20 @@ Returns: return EFI_SUCCESS; } +/** + I/O work flow of outing 8042 Aux data. + + @param IsaIo Pointer to instance of EFI_ISA_IO_PROTOCOL + @param Command Aux I/O command + + @retval EFI_SUCCESS Success to excute I/O work flow + @retval EFI_TIMEOUT Keyboard controller time out. +**/ EFI_STATUS Out8042AuxData ( IN EFI_ISA_IO_PROTOCOL *IsaIo, IN UINT8 Data ) -/** - -Routine Description: - - GC_TODO: Add function description - -Arguments: - - IsaIo - GC_TODO: add argument description - Data - GC_TODO: add argument description - -Returns: - - EFI_SUCCESS - GC_TODO: Add description for return value - -**/ { EFI_STATUS Status; UINT8 Temp; @@ -922,27 +779,20 @@ Returns: return EFI_SUCCESS; } +/** + I/O work flow of in 8042 Aux data. + + @param IsaIo Pointer to instance of EFI_ISA_IO_PROTOCOL + @param Data Buffer holding return value. + + @retval EFI_SUCCESS Success to excute I/O work flow + @retval EFI_TIMEOUT Keyboard controller time out. +**/ EFI_STATUS In8042AuxData ( IN EFI_ISA_IO_PROTOCOL *IsaIo, IN OUT UINT8 *Data ) -/** - -Routine Description: - - GC_TODO: Add function description - -Arguments: - - IsaIo - GC_TODO: add argument description - Data - GC_TODO: add argument description - -Returns: - - EFI_SUCCESS - GC_TODO: Add description for return value - -**/ { EFI_STATUS Status; @@ -959,26 +809,19 @@ Returns: return EFI_SUCCESS; } + +/** + Check keyboard controller status, if it is output buffer full and for auxiliary device + + @param IsaIo Pointer to instance of EFI_ISA_IO_PROTOCOL + + @retval EFI_SUCCESS Keyboard controller is ready + @retval EFI_NOT_READY Keyboard controller is not ready +**/ EFI_STATUS CheckForInput ( IN EFI_ISA_IO_PROTOCOL *IsaIo ) -/** - -Routine Description: - - GC_TODO: Add function description - -Arguments: - - IsaIo - GC_TODO: add argument description - -Returns: - - EFI_NOT_READY - GC_TODO: Add description for return value - EFI_SUCCESS - GC_TODO: Add description for return value - -**/ { UINT8 Data; @@ -994,28 +837,20 @@ Returns: return EFI_SUCCESS; } +/** + I/O work flow to wait input buffer empty in given time. + + @param IsaIo Pointer to instance of EFI_ISA_IO_PROTOCOL + @param Timeout Wating time. + + @retval EFI_TIMEOUT if input is still not empty in given time. + @retval EFI_SUCCESS input is empty. +**/ EFI_STATUS WaitInputEmpty ( IN EFI_ISA_IO_PROTOCOL *IsaIo, IN UINTN Timeout ) -/** - -Routine Description: - - GC_TODO: Add function description - -Arguments: - - IsaIo - GC_TODO: add argument description - Timeout - GC_TODO: add argument description - -Returns: - - EFI_TIMEOUT - GC_TODO: Add description for return value - EFI_SUCCESS - GC_TODO: Add description for return value - -**/ { UINTN Delay; UINT8 Data; @@ -1043,6 +878,15 @@ Returns: return EFI_SUCCESS; } +/** + I/O work flow to wait output buffer full in given time. + + @param IsaIo Pointer to instance of EFI_ISA_IO_PROTOCOL + @param Timeout given time + + @retval EFI_TIMEOUT output is not full in given time + @retval EFI_SUCCESS output is full in given time. +**/ EFI_STATUS WaitOutputFull ( IN EFI_ISA_IO_PROTOCOL *IsaIo, diff --git a/IntelFrameworkModulePkg/Bus/Isa/Ps2MouseDxe/CommPs2.h b/IntelFrameworkModulePkg/Bus/Isa/Ps2MouseDxe/CommPs2.h index 4bba9d2488..1796b09b4d 100644 --- a/IntelFrameworkModulePkg/Bus/Isa/Ps2MouseDxe/CommPs2.h +++ b/IntelFrameworkModulePkg/Bus/Isa/Ps2MouseDxe/CommPs2.h @@ -102,266 +102,184 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. // 0 - output buffer empty // 1 - keyboard controller data in output buffer // + +/** + Issue self test command via IsaIo interface. + + @param IsaIo Pointer to instance of EFI_ISA_IO_PROTOCOL + + @return EFI_SUCCESS Success to do keyboard self testing. + @return others Fail to do keyboard self testing. +**/ EFI_STATUS KbcSelfTest ( IN EFI_ISA_IO_PROTOCOL *IsaIo ) -/** - -Routine Description: - - GC_TODO: Add function description - -Arguments: - - IsaIo - GC_TODO: add argument description - -Returns: - - GC_TODO: add return values - -**/ ; +/** + Issue command to enable keyboard AUX functionality. + + @param IsaIo Pointer to instance of EFI_ISA_IO_PROTOCOL + + @return Status of command issuing. +**/ EFI_STATUS KbcEnableAux ( IN EFI_ISA_IO_PROTOCOL *IsaIo ) -/** - -Routine Description: - - GC_TODO: Add function description - -Arguments: - - IsaIo - GC_TODO: add argument description - -Returns: - - GC_TODO: add return values - -**/ ; +/** + Issue command to disable keyboard AUX functionality. + + @param IsaIo Pointer to instance of EFI_ISA_IO_PROTOCOL + + @return Status of command issuing. +**/ EFI_STATUS KbcDisableAux ( IN EFI_ISA_IO_PROTOCOL *IsaIo ) -/** - -Routine Description: - - GC_TODO: Add function description - -Arguments: - - IsaIo - GC_TODO: add argument description - -Returns: - - GC_TODO: add return values - -**/ ; +/** + Issue command to enable keyboard. + + @param IsaIo Pointer to instance of EFI_ISA_IO_PROTOCOL + + @return Status of command issuing. +**/ EFI_STATUS KbcEnableKb ( IN EFI_ISA_IO_PROTOCOL *IsaIo ) -/** - -Routine Description: - - GC_TODO: Add function description - -Arguments: - - IsaIo - GC_TODO: add argument description - -Returns: - - GC_TODO: add return values - -**/ ; +/** + Issue command to disable keyboard. + + @param IsaIo Pointer to instance of EFI_ISA_IO_PROTOCOL + + @return Status of command issuing. +**/ EFI_STATUS KbcDisableKb ( IN EFI_ISA_IO_PROTOCOL *IsaIo ) -/** - -Routine Description: - - GC_TODO: Add function description - -Arguments: - - IsaIo - GC_TODO: add argument description - -Returns: - - GC_TODO: add return values - -**/ ; +/** + Issue command to check keyboard status. + + @param IsaIo Pointer to instance of EFI_ISA_IO_PROTOCOL + @param KeyboardEnable return whether keyboard is enable. + + @return Status of command issuing. +**/ EFI_STATUS CheckKbStatus ( IN EFI_ISA_IO_PROTOCOL *IsaIo, OUT BOOLEAN *KeyboardEnable ) -/** - -Routine Description: - - GC_TODO: Add function description - -Arguments: - - IsaIo - GC_TODO: add argument description - KeyboardEnable - GC_TODO: add argument description - -Returns: - - GC_TODO: add return values - -**/ ; +/** + Issue command to reset keyboard. + + @param IsaIo Pointer to instance of EFI_ISA_IO_PROTOCOL + + @return Status of command issuing. +**/ EFI_STATUS PS2MouseReset ( IN EFI_ISA_IO_PROTOCOL *IsaIo ) -/** - -Routine Description: - - GC_TODO: Add function description - -Arguments: - - IsaIo - GC_TODO: add argument description - -Returns: - - GC_TODO: add return values - -**/ ; +/** + Issue command to set mouse's sample rate + + @param IsaIo Pointer to instance of EFI_ISA_IO_PROTOCOL + @param SampleRate value of sample rate + + @return Status of command issuing. +**/ EFI_STATUS PS2MouseSetSampleRate ( IN EFI_ISA_IO_PROTOCOL *IsaIo, IN MOUSE_SR SampleRate ) -/** - -Routine Description: - - GC_TODO: Add function description - -Arguments: - - IsaIo - GC_TODO: add argument description - SampleRate - GC_TODO: add argument description - -Returns: - - GC_TODO: add return values - -**/ ; +/** + Issue command to set mouse's resolution. + + @param IsaIo Pointer to instance of EFI_ISA_IO_PROTOCOL + @param Resolution value of resolution + + @return Status of command issuing. +**/ EFI_STATUS PS2MouseSetResolution ( IN EFI_ISA_IO_PROTOCOL *IsaIo, IN MOUSE_RE Resolution ) -/** - -Routine Description: - - GC_TODO: Add function description - -Arguments: - - IsaIo - GC_TODO: add argument description - Resolution - GC_TODO: add argument description - -Returns: - - GC_TODO: add return values - -**/ ; +/** + Issue command to set mouse's scaling. + + @param IsaIo Pointer to instance of EFI_ISA_IO_PROTOCOL + @param Scaling value of scaling + + @return Status of command issuing. +**/ EFI_STATUS PS2MouseSetScaling ( IN EFI_ISA_IO_PROTOCOL *IsaIo, IN MOUSE_SF Scaling ) -/** - -Routine Description: - - GC_TODO: Add function description - -Arguments: - - IsaIo - GC_TODO: add argument description - Scaling - GC_TODO: add argument description - -Returns: - - GC_TODO: add return values - -**/ ; +/** + Issue command to enable Ps2 mouse. + + @param IsaIo Pointer to instance of EFI_ISA_IO_PROTOCOL + + @return Status of command issuing. +**/ EFI_STATUS PS2MouseEnable ( IN EFI_ISA_IO_PROTOCOL *IsaIo ) -/** - -Routine Description: - - GC_TODO: Add function description - -Arguments: - - IsaIo - GC_TODO: add argument description - -Returns: - - GC_TODO: add return values - -**/ ; +/** + Get mouse packet . Only care first 3 bytes + + @param MouseDev Pointer of PS2 Mouse Private Data Structure + + @retval EFI_NOT_READY Mouse Device not ready to input data packet, or some error happened during getting the packet + @retval EFI_SUCCESS The data packet is gotten successfully. + +**/ EFI_STATUS PS2MouseGetPacket ( PS2_MOUSE_DEV *MouseDev ) -/** - -Routine Description: - - GC_TODO: Add function description - -Arguments: - - MouseDev - GC_TODO: add argument description - -Returns: - - GC_TODO: add return values - -**/ ; +/** + Read data via IsaIo protocol with given number. + + @param IsaIo Pointer to instance of EFI_ISA_IO_PROTOCOL + @param Buffer Buffer receive data of mouse + @param BufSize The size of buffer + @param State Check input or read data + + @return status of reading mouse data. +**/ EFI_STATUS PS2MouseRead ( IN EFI_ISA_IO_PROTOCOL *IsaIo, @@ -373,24 +291,61 @@ PS2MouseRead ( // // 8042 I/O function // +/** + I/O work flow of outing 8042 command. + + @param IsaIo Pointer to instance of EFI_ISA_IO_PROTOCOL + @param Command I/O command. + + @retval EFI_SUCCESS Success to excute I/O work flow + @retval EFI_TIMEOUT Keyboard controller time out. +**/ EFI_STATUS Out8042Command ( IN EFI_ISA_IO_PROTOCOL *IsaIo, IN UINT8 Command ); +/** + I/O work flow of in 8042 data. + + @param IsaIo Pointer to instance of EFI_ISA_IO_PROTOCOL + @param Data Data value + + @retval EFI_SUCCESS Success to excute I/O work flow + @retval EFI_TIMEOUT Keyboard controller time out. +**/ EFI_STATUS In8042Data ( IN EFI_ISA_IO_PROTOCOL *IsaIo, IN OUT UINT8 *Data ); +/** + I/O work flow of outing 8042 data. + + @param IsaIo Pointer to instance of EFI_ISA_IO_PROTOCOL + @param Data Data value + + @retval EFI_SUCCESS Success to excute I/O work flow + @retval EFI_TIMEOUT Keyboard controller time out. +**/ EFI_STATUS Out8042Data ( IN EFI_ISA_IO_PROTOCOL *IsaIo, IN UINT8 Data ); +/** + I/O work flow of outing 8042 Aux command. + + @param IsaIo Pointer to instance of EFI_ISA_IO_PROTOCOL + @param Command Aux I/O command + @param Resend Whether need resend the Aux command. + + @retval EFI_SUCCESS Success to excute I/O work flow + @retval EFI_TIMEOUT Keyboard controller time out. +**/ EFI_STATUS Out8042AuxCommand ( IN EFI_ISA_IO_PROTOCOL *IsaIo, @@ -398,29 +353,73 @@ Out8042AuxCommand ( IN BOOLEAN Resend ); +/** + I/O work flow of in 8042 Aux data. + + @param IsaIo Pointer to instance of EFI_ISA_IO_PROTOCOL + @param Data Buffer holding return value. + + @retval EFI_SUCCESS Success to excute I/O work flow + @retval EFI_TIMEOUT Keyboard controller time out. +**/ EFI_STATUS In8042AuxData ( IN EFI_ISA_IO_PROTOCOL *IsaIo, IN OUT UINT8 *Data ); +/** + I/O work flow of outing 8042 Aux data. + + @param IsaIo Pointer to instance of EFI_ISA_IO_PROTOCOL + @param Command Aux I/O command + + @retval EFI_SUCCESS Success to excute I/O work flow + @retval EFI_TIMEOUT Keyboard controller time out. +**/ EFI_STATUS Out8042AuxData ( IN EFI_ISA_IO_PROTOCOL *IsaIo, IN UINT8 Data ); +/** + Check keyboard controller status, if it is output buffer full and for auxiliary device + + @param IsaIo Pointer to instance of EFI_ISA_IO_PROTOCOL + + @retval EFI_SUCCESS Keyboard controller is ready + @retval EFI_NOT_READY Keyboard controller is not ready +**/ EFI_STATUS CheckForInput ( IN EFI_ISA_IO_PROTOCOL *IsaIo ); +/** + I/O work flow to wait input buffer empty in given time. + + @param IsaIo Pointer to instance of EFI_ISA_IO_PROTOCOL + @param Timeout Wating time. + + @retval EFI_TIMEOUT if input is still not empty in given time. + @retval EFI_SUCCESS input is empty. +**/ EFI_STATUS WaitInputEmpty ( IN EFI_ISA_IO_PROTOCOL *IsaIo, IN UINTN Timeout ); +/** + I/O work flow to wait output buffer full in given time. + + @param IsaIo Pointer to instance of EFI_ISA_IO_PROTOCOL + @param Timeout given time + + @retval EFI_TIMEOUT output is not full in given time + @retval EFI_SUCCESS output is full in given time. +**/ EFI_STATUS WaitOutputFull ( IN EFI_ISA_IO_PROTOCOL *IsaIo, diff --git a/IntelFrameworkModulePkg/Bus/Isa/Ps2MouseDxe/Ps2Mouse.c b/IntelFrameworkModulePkg/Bus/Isa/Ps2MouseDxe/Ps2Mouse.c index 53ce99e6ab..32b527c72c 100644 --- a/IntelFrameworkModulePkg/Bus/Isa/Ps2MouseDxe/Ps2Mouse.c +++ b/IntelFrameworkModulePkg/Bus/Isa/Ps2MouseDxe/Ps2Mouse.c @@ -28,6 +28,20 @@ EFI_DRIVER_BINDING_PROTOCOL gPS2MouseDriver = { NULL }; +/** + Test to see if this driver supports ControllerHandle. Any ControllerHandle + than contains a IsaIo protocol can be supported. + + @param This Protocol instance pointer. + @param ControllerHandle Handle of device to test + @param RemainingDevicePath Optional parameter use to pick a specific child + device to start. + + @retval EFI_SUCCESS This driver supports this device + @retval EFI_ALREADY_STARTED This driver is already running on this device + @retval other This driver does not support this device + +**/ EFI_STATUS EFIAPI PS2MouseDriverSupported ( @@ -35,20 +49,6 @@ PS2MouseDriverSupported ( IN EFI_HANDLE Controller, IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath ) -/** - -Routine Description: - - ControllerDriver Protocol Method - -Arguments: - -Returns: - -**/ -// GC_TODO: This - add argument and description to function comment -// GC_TODO: Controller - add argument and description to function comment -// GC_TODO: RemainingDevicePath - add argument and description to function comment { EFI_STATUS Status; EFI_ISA_IO_PROTOCOL *IsaIo; @@ -108,6 +108,21 @@ Returns: return Status; } +/** + Start this driver on ControllerHandle by opening a IsaIo + protocol, creating PS2_MOUSE_ABSOLUTE_POINTER_DEV device and install gEfiAbsolutePointerProtocolGuid + finnally. + + @param This Protocol instance pointer. + @param ControllerHandle Handle of device to bind driver to + @param RemainingDevicePath Optional parameter use to pick a specific child + device to start. + + @retval EFI_SUCCESS This driver is added to ControllerHandle + @retval EFI_ALREADY_STARTED This driver is already running on ControllerHandle + @retval other This driver does not support this device + +**/ EFI_STATUS EFIAPI PS2MouseDriverStart ( @@ -115,21 +130,6 @@ PS2MouseDriverStart ( IN EFI_HANDLE Controller, IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath ) -/** - -Routine Description: - Start protocol interfaces for the mouse device handles. - -Arguments: - This - Protocol instance pointer. - Controller - Handle of device to bind driver to. - RemainingDevicePath - Not used. - -Returns: - EFI_SUCCESS - This driver is added to DeviceHandle. - other - Errors occurred. - -**/ { EFI_STATUS Status; EFI_STATUS EmptyStatus; @@ -382,6 +382,20 @@ ErrorExit: return Status; } +/** + Stop this driver on ControllerHandle. Support stoping any child handles + created by this driver. + + @param This Protocol instance pointer. + @param ControllerHandle Handle of device to stop driver on + @param NumberOfChildren Number of Handles in ChildHandleBuffer. If number of + children is zero stop the entire bus driver. + @param ChildHandleBuffer List of Child Handles to Stop. + + @retval EFI_SUCCESS This driver is removed ControllerHandle + @retval other This driver was not removed from this device + +**/ EFI_STATUS EFIAPI PS2MouseDriverStop ( @@ -390,21 +404,6 @@ PS2MouseDriverStop ( IN UINTN NumberOfChildren, IN EFI_HANDLE *ChildHandleBuffer ) -/** - - Routine Description: - - Arguments: - - Returns: - -**/ -// GC_TODO: This - add argument and description to function comment -// GC_TODO: Controller - add argument and description to function comment -// GC_TODO: NumberOfChildren - add argument and description to function comment -// GC_TODO: ChildHandleBuffer - add argument and description to function comment -// GC_TODO: EFI_SUCCESS - add return value to function comment -// GC_TODO: EFI_SUCCESS - add return value to function comment { EFI_STATUS Status; EFI_SIMPLE_POINTER_PROTOCOL *SimplePointerProtocol; @@ -483,29 +482,23 @@ PS2MouseDriverStop ( return EFI_SUCCESS; } +/** + Reset the Mouse and do BAT test for it, if ExtendedVerification isTRUE and there is a mouse device connectted to system + + @param This - Pointer of simple pointer Protocol. + @param ExtendedVerification - Whether configure mouse parameters. True: do; FALSE: skip. + + + @retval EFI_SUCCESS - The command byte is written successfully. + @retval EFI_DEVICE_ERROR - Errors occurred during reseting keyboard. + +**/ EFI_STATUS EFIAPI MouseReset ( IN EFI_SIMPLE_POINTER_PROTOCOL *This, IN BOOLEAN ExtendedVerification ) -/** - -Routine Description: - - Reset the Mouse and do BAT test for it, if ExtendedVerification isTRUE and there is a mouse device connectted to system - -Arguments: - - This - Pointer of simple pointer Protocol. - ExtendedVerification - Whether configure mouse parameters. True: do; FALSE: skip. - -Returns: - - EFI_SUCCESS - The command byte is written successfully. - EFI_DEVICE_ERROR - Errors occurred during reseting keyboard. - -**/ { EFI_STATUS Status; PS2_MOUSE_DEV *MouseDev; @@ -605,26 +598,20 @@ Exit: return Status; } +/** + Check whether there is Ps/2 mouse device in system + + @param PS2_MOUSE_DEV - Mouse Private Data Structure + + @retval TRUE - Keyboard in System. + @retval FALSE - Keyboard not in System. + +**/ BOOLEAN CheckMouseConnect ( IN PS2_MOUSE_DEV *MouseDev ) -/** -Routine Description: - - Check whether there is Ps/2 mouse device in system - -Arguments: - - PS2_MOUSE_DEV - Mouse Private Data Structure - -Returns: - - TRUE - Keyboard in System. - FALSE - Keyboard not in System. - -**/ { EFI_STATUS Status; @@ -636,30 +623,22 @@ Returns: return FALSE; } +/** + Get and Clear mouse status. + + @param This - Pointer of simple pointer Protocol. + @param State - Output buffer holding status. + + @retval EFI_INVALID_PARAMETER Output buffer is invalid. + @retval EFI_NOT_READY Mouse is not changed status yet. + @retval EFI_SUCCESS Mouse status is changed and get successful. +**/ EFI_STATUS EFIAPI MouseGetState ( IN EFI_SIMPLE_POINTER_PROTOCOL *This, IN OUT EFI_SIMPLE_POINTER_STATE *State ) -/** - -Routine Description: - - GC_TODO: Add function description - -Arguments: - - This - GC_TODO: add argument description - State - GC_TODO: add argument description - -Returns: - - EFI_INVALID_PARAMETER - GC_TODO: Add description for return value - EFI_NOT_READY - GC_TODO: Add description for return value - EFI_SUCCESS - GC_TODO: Add description for return value - -**/ { PS2_MOUSE_DEV *MouseDev; EFI_TPL OldTpl; @@ -689,24 +668,22 @@ Returns: return EFI_SUCCESS; } +/** + + Event notification function for SIMPLE_POINTER.WaitForInput event + Signal the event if there is input from mouse + + @param Event event object + @param Context event context + +**/ + VOID EFIAPI MouseWaitForInput ( IN EFI_EVENT Event, IN VOID *Context ) -/** - -Routine Description: - - Event notification function for SIMPLE_POINTER.WaitForInput event - Signal the event if there is input from mouse - -Arguments: - -Returns: - -**/ // GC_TODO: Event - add argument and description to function comment // GC_TODO: Context - add argument and description to function comment { @@ -724,29 +701,21 @@ Returns: } +/** + Event notification function for TimerEvent event + If mouse device is connected to system, try to get the mouse packet data + + @param Event - TimerEvent in PS2_MOUSE_DEV + @param Context - Pointer to PS2_MOUSE_DEV structure + +**/ VOID EFIAPI PollMouse ( IN EFI_EVENT Event, IN VOID *Context ) -/** -Routine Description: - - Event notification function for TimerEvent event - If mouse device is connected to system, try to get the mouse packet data - -Arguments: - - Event - TimerEvent in PS2_MOUSE_DEV - Context - Pointer to PS2_MOUSE_DEV structure - -Returns: - - None - -**/ { PS2_MOUSE_DEV *MouseDev; @@ -793,3 +762,4 @@ InitializePs2Mouse( return Status; } +