IntelFrameworkModulePkg/Bus/Isa/Ps2KeyboardDxe/Ps2Keyboard.h

   1 /**@file
   2   PS/2 keyboard driver header file
   3
   4 Copyright (c) 2006 - 2007, Intel Corporation
   5 All rights reserved. This program and the accompanying materials
   6 are licensed and made available under the terms and conditions of the BSD License
   7 which accompanies this distribution.  The full text of the license may be found at
   8 http://opensource.org/licenses/bsd-license.php
   9
  10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  12
  13 **/
  14
  15 #ifndef _PS2KEYBOARD_H
  16 #define _PS2KEYBOARD_H
  17
  18 #include <PiDxe.h>
  19 #include <Framework/StatusCode.h>
  20
  21 #include <Protocol/SimpleTextIn.h>
  22 #include <Protocol/SimpleTextInEx.h>
  23 #include <Protocol/IsaIo.h>
  24 #include <Protocol/DevicePath.h>
  25 #include <Protocol/Ps2Policy.h>
  26
  27 #include <Library/UefiDriverEntryPoint.h>
  28 #include <Library/UefiLib.h>
  29 #include <Library/UefiBootServicesTableLib.h>
  30 #include <Library/ReportStatusCodeLib.h>
  31 #include <Library/DebugLib.h>
  32 #include <Library/UefiRuntimeServicesTableLib.h>
  33 #include <Library/MemoryAllocationLib.h>
  34 #include <Library/BaseLib.h>
  35 #include <Library/BaseMemoryLib.h>
  36
  37 //
  38 // Driver Private Data
  39 //
  40 #define KEYBOARD_BUFFER_MAX_COUNT         32
  41 #define KEYBOARD_CONSOLE_IN_DEV_SIGNATURE SIGNATURE_32 ('k', 'k', 'e', 'y')
  42 #define KEYBOARD_CONSOLE_IN_EX_NOTIFY_SIGNATURE SIGNATURE_32 ('k', 'c', 'e', 'n')
  43
  44 typedef struct _KEYBOARD_CONSOLE_IN_EX_NOTIFY {
  45   UINTN                                 Signature;
  46   EFI_HANDLE                            NotifyHandle;
  47   EFI_KEY_DATA                          KeyData;
  48   EFI_KEY_NOTIFY_FUNCTION               KeyNotificationFn;
  49   LIST_ENTRY                            NotifyEntry;
  50 } KEYBOARD_CONSOLE_IN_EX_NOTIFY;
  51
  52
  53 typedef struct {
  54   UINTN                               Signature;
  55
  56   EFI_HANDLE                          Handle;
  57   EFI_SIMPLE_TEXT_INPUT_PROTOCOL      ConIn;
  58   EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL   ConInEx;
  59   EFI_ISA_IO_PROTOCOL                 *IsaIo;
  60
  61   EFI_EVENT                           TimerEvent;
  62
  63   UINT32                              DataRegisterAddress;
  64   UINT32                              StatusRegisterAddress;
  65   UINT32                              CommandRegisterAddress;
  66
  67   EFI_INPUT_KEY                       Key;
  68   EFI_KEY_STATE                       KeyState;
  69
  70   BOOLEAN                             LeftShift;
  71   BOOLEAN                             RightShift;
  72   BOOLEAN                             LeftLogo;
  73   BOOLEAN                             RightLogo;
  74   BOOLEAN                             Menu;
  75   BOOLEAN                             SysReq;
  76
  77   BOOLEAN                             Ctrl;
  78   BOOLEAN                             Alt;
  79   BOOLEAN                             Shift;
  80   BOOLEAN                             CapsLock;
  81   BOOLEAN                             NumLock;
  82   BOOLEAN                             ScrollLock;
  83
  84   //
  85   // Buffer storing key scancodes
  86   //
  87   UINT8                               ScancodeBuf[KEYBOARD_BUFFER_MAX_COUNT];
  88   UINT32                              ScancodeBufStartPos;
  89   UINT32                              ScancodeBufEndPos;
  90   UINT32                              ScancodeBufCount;
  91
  92   //
  93   // Indicators of the key pressing state, used in detecting Alt+Ctrl+Del
  94   //
  95   BOOLEAN                             Ctrled;
  96   BOOLEAN                             Alted;
  97
  98   //
  99   // Error state
 100   //
 101   BOOLEAN                             KeyboardErr;
 102
 103   EFI_UNICODE_STRING_TABLE            *ControllerNameTable;
 104
 105   EFI_DEVICE_PATH_PROTOCOL            *DevicePath;
 106   //
 107   // Notification Function List
 108   //
 109   LIST_ENTRY                          NotifyList;
 110 } KEYBOARD_CONSOLE_IN_DEV;
 111
 112 #define KEYBOARD_CONSOLE_IN_DEV_FROM_THIS(a)  CR (a, KEYBOARD_CONSOLE_IN_DEV, ConIn, KEYBOARD_CONSOLE_IN_DEV_SIGNATURE)
 113 #define TEXT_INPUT_EX_KEYBOARD_CONSOLE_IN_DEV_FROM_THIS(a) \
 114   CR (a, \
 115       KEYBOARD_CONSOLE_IN_DEV, \
 116       ConInEx, \
 117       KEYBOARD_CONSOLE_IN_DEV_SIGNATURE \
 118       )
 119
 120 #define TABLE_END 0x0
 121
 122 //
 123 // Global Variables
 124 //
 125 extern EFI_DRIVER_BINDING_PROTOCOL   gKeyboardControllerDriver;
 126 extern EFI_COMPONENT_NAME_PROTOCOL   gPs2KeyboardComponentName;
 127 extern EFI_COMPONENT_NAME2_PROTOCOL  gPs2KeyboardComponentName2;
 128
 129 extern EFI_GUID                      gSimpleTextInExNotifyGuid;
 130
 131 //
 132 // Driver entry point
 133 //
 134 /**
 135   The user Entry Point for module Ps2Keyboard. The user code starts with this function.
 136
 137   @param[in] ImageHandle    The firmware allocated handle for the EFI image.
 138   @param[in] SystemTable    A pointer to the EFI System Table.
 139
 140   @retval EFI_SUCCESS       The entry point is executed successfully.
 141   @retval other             Some error occurs when executing this entry point.
 142
 143 **/
 144 EFI_STATUS
 145 EFIAPI
 146 InstallPs2KeyboardDriver (
 147   IN EFI_HANDLE           ImageHandle,
 148   IN EFI_SYSTEM_TABLE     *SystemTable
 149   );
 150
 151 #define KEYBOARD_8042_DATA_REGISTER     0x60
 152 #define KEYBOARD_8042_STATUS_REGISTER   0x64
 153 #define KEYBOARD_8042_COMMAND_REGISTER  0x64
 154
 155 #define KEYBOARD_KBEN                   0xF4
 156 #define KEYBOARD_CMDECHO_ACK            0xFA
 157
 158 #define KEYBOARD_MAX_TRY                256     // 256
 159 #define KEYBOARD_TIMEOUT                65536   // 0.07s
 160 #define KEYBOARD_WAITFORVALUE_TIMEOUT   1000000 // 1s
 161 #define KEYBOARD_BAT_TIMEOUT            4000000 // 4s
 162 #define KEYBOARD_TIMER_INTERVAL         200000  // 0.02s
 163 #define SCANCODE_EXTENDED               0xE0
 164 #define SCANCODE_EXTENDED1              0xE1
 165 #define SCANCODE_CTRL_MAKE              0x1D
 166 #define SCANCODE_CTRL_BREAK             0x9D
 167 #define SCANCODE_ALT_MAKE               0x38
 168 #define SCANCODE_ALT_BREAK              0xB8
 169 #define SCANCODE_LEFT_SHIFT_MAKE        0x2A
 170 #define SCANCODE_LEFT_SHIFT_BREAK       0xAA
 171 #define SCANCODE_RIGHT_SHIFT_MAKE       0x36
 172 #define SCANCODE_RIGHT_SHIFT_BREAK      0xB6
 173 #define SCANCODE_CAPS_LOCK_MAKE         0x3A
 174 #define SCANCODE_NUM_LOCK_MAKE          0x45
 175 #define SCANCODE_SCROLL_LOCK_MAKE       0x46
 176 #define SCANCODE_LEFT_LOGO_MAKE         0x5B //GUI key defined in Keyboard scan code
 177 #define SCANCODE_LEFT_LOGO_BREAK        0xDB
 178 #define SCANCODE_RIGHT_LOGO_MAKE        0x5C
 179 #define SCANCODE_RIGHT_LOGO_BREAK       0xDC
 180 #define SCANCODE_MENU_MAKE              0x5D //APPS key defined in Keyboard scan code
 181 #define SCANCODE_MENU_BREAK             0xDD
 182 #define SCANCODE_SYS_REQ_MAKE           0x37
 183 #define SCANCODE_MAX_MAKE               0x60
 184
 185 //
 186 // Other functions that are used among .c files
 187 //
 188 /**
 189   Show keyboard status lights according to
 190   indicators in ConsoleIn.
 191
 192   @param ConsoleIn Pointer to instance of KEYBOARD_CONSOLE_IN_DEV
 193
 194   @return status
 195
 196 **/
 197 EFI_STATUS
 198 UpdateStatusLights (
 199   IN KEYBOARD_CONSOLE_IN_DEV *ConsoleIn
 200   );
 201
 202 /**
 203   write key to keyboard
 204
 205   @param ConsoleIn Pointer to instance of KEYBOARD_CONSOLE_IN_DEV
 206   @param Data      value wanted to be written
 207
 208   @retval EFI_TIMEOUT - GC_TODO: Add description for return value
 209   @retval EFI_SUCCESS - GC_TODO: Add description for return value
 210
 211 **/
 212 EFI_STATUS
 213 KeyboardRead (
 214   IN KEYBOARD_CONSOLE_IN_DEV  *ConsoleIn,
 215   OUT UINT8                   *Data
 216   );
 217
 218 /**
 219   Get scancode from scancode buffer
 220   and translate into EFI-scancode and unicode defined by EFI spec
 221   The function is always called in TPL_NOTIFY
 222
 223   @param ConsoleIn KEYBOARD_CONSOLE_IN_DEV instance pointer
 224
 225   @retval EFI_NOT_READY - Input from console not ready yet.
 226   @retval EFI_SUCCESS   - Function executed successfully.
 227
 228 **/
 229 EFI_STATUS
 230 KeyGetchar (
 231   IN OUT KEYBOARD_CONSOLE_IN_DEV *ConsoleIn
 232   );
 233
 234 /**
 235   Perform 8042 controller and keyboard Initialization
 236   If ExtendedVerification is TRUE, do additional test for
 237   the keyboard interface
 238
 239   @param ConsoleIn - KEYBOARD_CONSOLE_IN_DEV instance pointer
 240   @param ExtendedVerification - indicates a thorough initialization
 241
 242   @retval EFI_DEVICE_ERROR Fail to init keyboard
 243   @retval EFI_SUCCESS      Success to init keyboard
 244 **/
 245 EFI_STATUS
 246 InitKeyboard (
 247   IN OUT KEYBOARD_CONSOLE_IN_DEV *ConsoleIn,
 248   IN BOOLEAN                     ExtendedVerification
 249   );
 250
 251 /**
 252   Disable the keyboard interface of the 8042 controller
 253
 254   @param ConsoleIn   - the device instance
 255
 256   @return status of issuing disable command
 257
 258 **/
 259 EFI_STATUS
 260 DisableKeyboard (
 261   IN KEYBOARD_CONSOLE_IN_DEV *ConsoleIn
 262   );
 263
 264 /**
 265   Timer event handler: read a series of scancodes from 8042
 266   and put them into memory scancode buffer.
 267   it read as much scancodes to either fill
 268   the memory buffer or empty the keyboard buffer.
 269   It is registered as running under TPL_NOTIFY
 270
 271   @param Event - The timer event
 272   @param Context - A KEYBOARD_CONSOLE_IN_DEV pointer
 273
 274 **/
 275 VOID
 276 EFIAPI
 277 KeyboardTimerHandler (
 278   IN EFI_EVENT    Event,
 279   IN VOID         *Context
 280   );
 281
 282 /**
 283   logic reset keyboard
 284   Implement SIMPLE_TEXT_IN.Reset()
 285   Perform 8042 controller and keyboard initialization
 286
 287   @param This    Pointer to instance of EFI_SIMPLE_TEXT_INPUT_PROTOCOL
 288   @param ExtendedVerification Indicate that the driver may perform a more
 289                               exhaustive verification operation of the device during
 290                               reset, now this par is ignored in this driver
 291
 292 **/
 293 EFI_STATUS
 294 EFIAPI
 295 KeyboardEfiReset (
 296   IN  EFI_SIMPLE_TEXT_INPUT_PROTOCOL  *This,
 297   IN  BOOLEAN                         ExtendedVerification
 298   );
 299
 300 /**
 301   Implement SIMPLE_TEXT_IN.ReadKeyStroke().
 302   Retrieve key values for driver user.
 303
 304   @param This    Pointer to instance of EFI_SIMPLE_TEXT_INPUT_PROTOCOL
 305   @param Key     The output buffer for key value
 306
 307   @retval EFI_SUCCESS success to read key stroke
 308 **/
 309 EFI_STATUS
 310 EFIAPI
 311 KeyboardReadKeyStroke (
 312   IN  EFI_SIMPLE_TEXT_INPUT_PROTOCOL  *This,
 313   OUT EFI_INPUT_KEY                   *Key
 314   );
 315
 316 /**
 317   Event notification function for SIMPLE_TEXT_IN.WaitForKey event
 318   Signal the event if there is key available
 319
 320   @param Event    the event object
 321   @param Context  waitting context
 322
 323 **/
 324 VOID
 325 EFIAPI
 326 KeyboardWaitForKey (
 327   IN  EFI_EVENT               Event,
 328   IN  VOID                    *Context
 329   );
 330
 331 /**
 332   Read status register
 333
 334   @param ConsoleIn  Pointer to instance of KEYBOARD_CONSOLE_IN_DEV
 335
 336   @return value in status register
 337
 338 **/
 339 UINT8
 340 KeyReadStatusRegister (
 341   IN KEYBOARD_CONSOLE_IN_DEV *ConsoleIn
 342   );
 343
 344 /**
 345   Check whether there is Ps/2 Keyboard device in system by 0xF4 Keyboard Command
 346   If Keyboard receives 0xF4, it will respond with 'ACK'. If it doesn't respond, the device
 347   should not be in system.
 348
 349   @param[in]  BiosKeyboardPrivate   Keyboard Private Data Structure
 350
 351   @retval     TRUE                  Keyboard in System.
 352   @retval     FALSE                 Keyboard not in System.
 353 **/
 354 BOOLEAN
 355 EFIAPI
 356 CheckKeyboardConnect (
 357   IN KEYBOARD_CONSOLE_IN_DEV *ConsoleIn
 358   );
 359
 360 /**
 361   Event notification function for SIMPLE_TEXT_INPUT_EX_PROTOCOL.WaitForKeyEx event
 362   Signal the event if there is key available
 363
 364   @param Event    event object
 365   @param Context  waiting context
 366
 367 **/
 368 VOID
 369 EFIAPI
 370 KeyboardWaitForKeyEx (
 371   IN  EFI_EVENT               Event,
 372   IN  VOID                    *Context
 373   );
 374
 375 //
 376 // Simple Text Input Ex protocol function prototypes
 377 //
 378
 379 /**
 380   Reset the input device and optionaly run diagnostics
 381
 382   @param This                 - Protocol instance pointer.
 383   @param ExtendedVerification - Driver may perform diagnostics on reset.
 384
 385   @retval EFI_SUCCESS           - The device was reset.
 386   @retval EFI_DEVICE_ERROR      - The device is not functioning properly and could
 387                                   not be reset.
 388
 389 **/
 390 EFI_STATUS
 391 EFIAPI
 392 KeyboardEfiResetEx (
 393   IN EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL  *This,
 394   IN BOOLEAN                            ExtendedVerification
 395   );
 396
 397 /**
 398     Reads the next keystroke from the input device. The WaitForKey Event can
 399     be used to test for existance of a keystroke via WaitForEvent () call.
 400
 401
 402     @param This       - Protocol instance pointer.
 403     @param KeyData    - A pointer to a buffer that is filled in with the keystroke
 404                  state data for the key that was pressed.
 405
 406     @retval EFI_SUCCESS           - The keystroke information was returned.
 407     @retval EFI_NOT_READY         - There was no keystroke data availiable.
 408     @retval EFI_DEVICE_ERROR      - The keystroke information was not returned due to
 409                             hardware errors.
 410     @retval EFI_INVALID_PARAMETER - KeyData is NULL.
 411
 412 **/
 413 EFI_STATUS
 414 EFIAPI
 415 KeyboardReadKeyStrokeEx (
 416   IN  EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL *This,
 417   OUT EFI_KEY_DATA                      *KeyData
 418   );
 419
 420 /**
 421   Set certain state for the input device.
 422
 423   @param This              - Protocol instance pointer.
 424   @param KeyToggleState    - A pointer to the EFI_KEY_TOGGLE_STATE to set the
 425                         state for the input device.
 426
 427   @retval EFI_SUCCESS           - The device state was set successfully.
 428   @retval EFI_DEVICE_ERROR      - The device is not functioning correctly and could
 429                             not have the setting adjusted.
 430   @retval EFI_UNSUPPORTED       - The device does not have the ability to set its state.
 431   @retval EFI_INVALID_PARAMETER - KeyToggleState is NULL.
 432
 433 **/
 434 EFI_STATUS
 435 EFIAPI
 436 KeyboardSetState (
 437   IN EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL  *This,
 438   IN EFI_KEY_TOGGLE_STATE               *KeyToggleState
 439   );
 440
 441 /**
 442     Register a notification function for a particular keystroke for the input device.
 443
 444     @param This                    - Protocol instance pointer.
 445     @param KeyData                 - A pointer to a buffer that is filled in with the keystroke
 446                               information data for the key that was pressed.
 447     @param KeyNotificationFunction - Points to the function to be called when the key
 448                               sequence is typed specified by KeyData.
 449     @param NotifyHandle            - Points to the unique handle assigned to the registered notification.
 450
 451     @retval EFI_SUCCESS             - The notification function was registered successfully.
 452     @retval EFI_OUT_OF_RESOURCES    - Unable to allocate resources for necesssary data structures.
 453     @retval EFI_INVALID_PARAMETER   - KeyData or NotifyHandle is NULL.
 454
 455 **/
 456 EFI_STATUS
 457 EFIAPI
 458 KeyboardRegisterKeyNotify (
 459   IN EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL  *This,
 460   IN EFI_KEY_DATA                       *KeyData,
 461   IN EFI_KEY_NOTIFY_FUNCTION            KeyNotificationFunction,
 462   OUT EFI_HANDLE                        *NotifyHandle
 463   );
 464
 465 /**
 466     Remove a registered notification function from a particular keystroke.
 467
 468     @param This                    - Protocol instance pointer.
 469     @param NotificationHandle      - The handle of the notification function being unregistered.
 470
 471
 472     @retval EFI_SUCCESS             - The notification function was unregistered successfully.
 473     @retval EFI_INVALID_PARAMETER   - The NotificationHandle is invalid.
 474     @retval EFI_NOT_FOUND           - Can not find the matching entry in database.
 475
 476 **/
 477 EFI_STATUS
 478 EFIAPI
 479 KeyboardUnregisterKeyNotify (
 480   IN EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL  *This,
 481   IN EFI_HANDLE                         NotificationHandle
 482   );
 483
 484 #endif