MdeModulePkg/Bus/Isa/Ps2KeyboardDxe/Ps2Keyboard.h

   1 /** @file
   2   PS/2 keyboard driver header file
   3
   4 Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
   5 SPDX-License-Identifier: BSD-2-Clause-Patent
   6
   7 **/
   8
   9 #ifndef _PS2KEYBOARD_H_
  10 #define _PS2KEYBOARD_H_
  11
  12 #include <Uefi.h>
  13
  14 #include <Protocol/SuperIo.h>
  15 #include <Protocol/SimpleTextIn.h>
  16 #include <Protocol/SimpleTextInEx.h>
  17 #include <Protocol/DevicePath.h>
  18 #include <Protocol/Ps2Policy.h>
  19
  20 #include <Library/IoLib.h>
  21 #include <Library/DevicePathLib.h>
  22 #include <Library/UefiDriverEntryPoint.h>
  23 #include <Library/UefiLib.h>
  24 #include <Library/UefiBootServicesTableLib.h>
  25 #include <Library/ReportStatusCodeLib.h>
  26 #include <Library/DebugLib.h>
  27 #include <Library/UefiRuntimeServicesTableLib.h>
  28 #include <Library/MemoryAllocationLib.h>
  29 #include <Library/BaseLib.h>
  30 #include <Library/BaseMemoryLib.h>
  31 #include <Library/TimerLib.h>
  32 #include <Library/PcdLib.h>
  33
  34 //
  35 // Global Variables
  36 //
  37 extern EFI_DRIVER_BINDING_PROTOCOL   gKeyboardControllerDriver;
  38 extern EFI_COMPONENT_NAME_PROTOCOL   gPs2KeyboardComponentName;
  39 extern EFI_COMPONENT_NAME2_PROTOCOL  gPs2KeyboardComponentName2;
  40
  41 //
  42 // Driver Private Data
  43 //
  44 #define KEYBOARD_CONSOLE_IN_DEV_SIGNATURE        SIGNATURE_32 ('k', 'k', 'e', 'y')
  45 #define KEYBOARD_CONSOLE_IN_EX_NOTIFY_SIGNATURE  SIGNATURE_32 ('k', 'c', 'e', 'n')
  46
  47 typedef struct _KEYBOARD_CONSOLE_IN_EX_NOTIFY {
  48   UINTN                      Signature;
  49   EFI_KEY_DATA               KeyData;
  50   EFI_KEY_NOTIFY_FUNCTION    KeyNotificationFn;
  51   LIST_ENTRY                 NotifyEntry;
  52 } KEYBOARD_CONSOLE_IN_EX_NOTIFY;
  53
  54 #define KEYBOARD_SCAN_CODE_MAX_COUNT  32
  55 typedef struct {
  56   UINT8    Buffer[KEYBOARD_SCAN_CODE_MAX_COUNT];
  57   UINTN    Head;
  58   UINTN    Tail;
  59 } SCAN_CODE_QUEUE;
  60
  61 #define KEYBOARD_EFI_KEY_MAX_COUNT  256
  62 typedef struct {
  63   EFI_KEY_DATA    Buffer[KEYBOARD_EFI_KEY_MAX_COUNT];
  64   UINTN           Head;
  65   UINTN           Tail;
  66 } EFI_KEY_QUEUE;
  67
  68 typedef struct {
  69   UINTN                                Signature;
  70
  71   EFI_HANDLE                           Handle;
  72   EFI_SIMPLE_TEXT_INPUT_PROTOCOL       ConIn;
  73   EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL    ConInEx;
  74
  75   EFI_EVENT                            TimerEvent;
  76
  77   UINT32                               DataRegisterAddress;
  78   UINT32                               StatusRegisterAddress;
  79   UINT32                               CommandRegisterAddress;
  80
  81   BOOLEAN                              LeftCtrl;
  82   BOOLEAN                              RightCtrl;
  83   BOOLEAN                              LeftAlt;
  84   BOOLEAN                              RightAlt;
  85   BOOLEAN                              LeftShift;
  86   BOOLEAN                              RightShift;
  87   BOOLEAN                              LeftLogo;
  88   BOOLEAN                              RightLogo;
  89   BOOLEAN                              Menu;
  90   BOOLEAN                              SysReq;
  91
  92   BOOLEAN                              CapsLock;
  93   BOOLEAN                              NumLock;
  94   BOOLEAN                              ScrollLock;
  95
  96   BOOLEAN                              IsSupportPartialKey;
  97   //
  98   // Queue storing key scancodes
  99   //
 100   SCAN_CODE_QUEUE                      ScancodeQueue;
 101   EFI_KEY_QUEUE                        EfiKeyQueue;
 102   EFI_KEY_QUEUE                        EfiKeyQueueForNotify;
 103
 104   //
 105   // Error state
 106   //
 107   BOOLEAN                              KeyboardErr;
 108
 109   EFI_UNICODE_STRING_TABLE             *ControllerNameTable;
 110
 111   EFI_DEVICE_PATH_PROTOCOL             *DevicePath;
 112   //
 113   // Notification Function List
 114   //
 115   LIST_ENTRY                           NotifyList;
 116   EFI_EVENT                            KeyNotifyProcessEvent;
 117 } KEYBOARD_CONSOLE_IN_DEV;
 118
 119 #define KEYBOARD_CONSOLE_IN_DEV_FROM_THIS(a)  CR (a, KEYBOARD_CONSOLE_IN_DEV, ConIn, KEYBOARD_CONSOLE_IN_DEV_SIGNATURE)
 120 #define TEXT_INPUT_EX_KEYBOARD_CONSOLE_IN_DEV_FROM_THIS(a) \
 121   CR (a, \
 122       KEYBOARD_CONSOLE_IN_DEV, \
 123       ConInEx, \
 124       KEYBOARD_CONSOLE_IN_DEV_SIGNATURE \
 125       )
 126
 127 #define TABLE_END  0x0
 128
 129 //
 130 // Driver entry point
 131 //
 132
 133 /**
 134   The user Entry Point for module Ps2Keyboard. The user code starts with this function.
 135
 136   @param[in] ImageHandle    The firmware allocated handle for the EFI image.
 137   @param[in] SystemTable    A pointer to the EFI System Table.
 138
 139   @retval EFI_SUCCESS       The entry point is executed successfully.
 140   @retval other             Some error occurs when executing this entry point.
 141
 142 **/
 143 EFI_STATUS
 144 EFIAPI
 145 InstallPs2KeyboardDriver (
 146   IN EFI_HANDLE        ImageHandle,
 147   IN EFI_SYSTEM_TABLE  *SystemTable
 148   );
 149
 150 #define KEYBOARD_8042_DATA_REGISTER     0x60
 151 #define KEYBOARD_8042_STATUS_REGISTER   0x64
 152 #define KEYBOARD_8042_COMMAND_REGISTER  0x64
 153
 154 #define KEYBOARD_KBEN         0xF4
 155 #define KEYBOARD_CMDECHO_ACK  0xFA
 156
 157 #define KEYBOARD_MAX_TRY                 256     // 256
 158 #define KEYBOARD_TIMEOUT                 65536   // 0.07s
 159 #define KEYBOARD_WAITFORVALUE_TIMEOUT    1000000 // 1s
 160 #define KEYBOARD_BAT_TIMEOUT             4000000 // 4s
 161 #define KEYBOARD_TIMER_INTERVAL          200000  // 0.02s
 162 #define SCANCODE_EXTENDED0               0xE0
 163 #define SCANCODE_EXTENDED1               0xE1
 164 #define SCANCODE_CTRL_MAKE               0x1D
 165 #define SCANCODE_CTRL_BREAK              0x9D
 166 #define SCANCODE_ALT_MAKE                0x38
 167 #define SCANCODE_ALT_BREAK               0xB8
 168 #define SCANCODE_LEFT_SHIFT_MAKE         0x2A
 169 #define SCANCODE_LEFT_SHIFT_BREAK        0xAA
 170 #define SCANCODE_RIGHT_SHIFT_MAKE        0x36
 171 #define SCANCODE_RIGHT_SHIFT_BREAK       0xB6
 172 #define SCANCODE_CAPS_LOCK_MAKE          0x3A
 173 #define SCANCODE_NUM_LOCK_MAKE           0x45
 174 #define SCANCODE_SCROLL_LOCK_MAKE        0x46
 175 #define SCANCODE_DELETE_MAKE             0x53
 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_SYS_REQ_BREAK           0xB7
 184 #define SCANCODE_SYS_REQ_MAKE_WITH_ALT   0x54
 185 #define SCANCODE_SYS_REQ_BREAK_WITH_ALT  0xD4
 186
 187 #define SCANCODE_MAX_MAKE  0x60
 188
 189 #define KEYBOARD_STATUS_REGISTER_HAS_OUTPUT_DATA   BIT0          ///< 0 - Output register has no data; 1 - Output register has data
 190 #define KEYBOARD_STATUS_REGISTER_HAS_INPUT_DATA    BIT1          ///< 0 - Input register has no data;  1 - Input register has data
 191 #define KEYBOARD_STATUS_REGISTER_SYSTEM_FLAG       BIT2          ///< Set to 0 after power on reset
 192 #define KEYBOARD_STATUS_REGISTER_INPUT_DATA_TYPE   BIT3          ///< 0 - Data in input register is data; 1 - Data in input register is command
 193 #define KEYBOARD_STATUS_REGISTER_ENABLE_FLAG       BIT4          ///< 0 - Keyboard is disable; 1 - Keyboard is enable
 194 #define KEYBOARD_STATUS_REGISTER_TRANSMIT_TIMEOUT  BIT5          ///< 0 - Transmit is complete without timeout; 1 - Transmit is timeout without complete
 195 #define KEYBOARD_STATUS_REGISTER_RECEIVE_TIMEOUT   BIT6          ///< 0 - Receive is complete without timeout; 1 - Receive is timeout without complete
 196 #define KEYBOARD_STATUS_REGISTER_PARITY            BIT7          ///< 0 - Odd parity; 1 - Even parity
 197
 198 #define KEYBOARD_8042_COMMAND_READ                          0x20
 199 #define KEYBOARD_8042_COMMAND_WRITE                         0x60
 200 #define KEYBOARD_8042_COMMAND_DISABLE_MOUSE_INTERFACE       0xA7
 201 #define KEYBOARD_8042_COMMAND_ENABLE_MOUSE_INTERFACE        0xA8
 202 #define KEYBOARD_8042_COMMAND_CONTROLLER_SELF_TEST          0xAA
 203 #define KEYBOARD_8042_COMMAND_KEYBOARD_INTERFACE_SELF_TEST  0xAB
 204 #define KEYBOARD_8042_COMMAND_DISABLE_KEYBOARD_INTERFACE    0xAD
 205
 206 #define KEYBOARD_8048_COMMAND_CLEAR_OUTPUT_DATA     0xF4
 207 #define KEYBOARD_8048_COMMAND_RESET                 0xFF
 208 #define KEYBOARD_8048_COMMAND_SELECT_SCAN_CODE_SET  0xF0
 209
 210 #define KEYBOARD_8048_RETURN_8042_BAT_SUCCESS  0xAA
 211 #define KEYBOARD_8048_RETURN_8042_BAT_ERROR    0xFC
 212 #define KEYBOARD_8048_RETURN_8042_ACK          0xFA
 213
 214 //
 215 // Keyboard Controller Status
 216 //
 217 #define KBC_PARE  0x80  // Parity Error
 218 #define KBC_TIM   0x40  // General Time Out
 219
 220 //
 221 // Other functions that are used among .c files
 222 //
 223
 224 /**
 225   Show keyboard status lights according to
 226   indicators in ConsoleIn.
 227
 228   @param ConsoleIn Pointer to instance of KEYBOARD_CONSOLE_IN_DEV
 229
 230   @return status
 231
 232 **/
 233 EFI_STATUS
 234 UpdateStatusLights (
 235   IN KEYBOARD_CONSOLE_IN_DEV  *ConsoleIn
 236   );
 237
 238 /**
 239   write key to keyboard.
 240
 241   @param ConsoleIn Pointer to instance of KEYBOARD_CONSOLE_IN_DEV
 242   @param Data      value wanted to be written
 243
 244   @retval EFI_TIMEOUT - GC_TODO: Add description for return value
 245   @retval EFI_SUCCESS - GC_TODO: Add description for return value
 246
 247 **/
 248 EFI_STATUS
 249 KeyboardRead (
 250   IN KEYBOARD_CONSOLE_IN_DEV  *ConsoleIn,
 251   OUT UINT8                   *Data
 252   );
 253
 254 /**
 255   Get scancode from scancode buffer and translate into EFI-scancode and unicode defined by EFI spec.
 256
 257   The function is always called in TPL_NOTIFY.
 258
 259   @param ConsoleIn KEYBOARD_CONSOLE_IN_DEV instance pointer
 260
 261 **/
 262 VOID
 263 KeyGetchar (
 264   IN OUT KEYBOARD_CONSOLE_IN_DEV  *ConsoleIn
 265   );
 266
 267 /**
 268   Process key notify.
 269
 270   @param  Event                 Indicates the event that invoke this function.
 271   @param  Context               Indicates the calling context.
 272 **/
 273 VOID
 274 EFIAPI
 275 KeyNotifyProcessHandler (
 276   IN  EFI_EVENT  Event,
 277   IN  VOID       *Context
 278   );
 279
 280 /**
 281   Perform 8042 controller and keyboard Initialization.
 282   If ExtendedVerification is TRUE, do additional test for
 283   the keyboard interface
 284
 285   @param ConsoleIn - KEYBOARD_CONSOLE_IN_DEV instance pointer
 286   @param ExtendedVerification - indicates a thorough initialization
 287
 288   @retval EFI_DEVICE_ERROR Fail to init keyboard
 289   @retval EFI_SUCCESS      Success to init keyboard
 290 **/
 291 EFI_STATUS
 292 InitKeyboard (
 293   IN OUT KEYBOARD_CONSOLE_IN_DEV  *ConsoleIn,
 294   IN BOOLEAN                      ExtendedVerification
 295   );
 296
 297 /**
 298   Timer event handler: read a series of scancodes from 8042
 299   and put them into memory scancode buffer.
 300   it read as much scancodes to either fill
 301   the memory buffer or empty the keyboard buffer.
 302   It is registered as running under TPL_NOTIFY
 303
 304   @param Event - The timer event
 305   @param Context - A KEYBOARD_CONSOLE_IN_DEV pointer
 306
 307 **/
 308 VOID
 309 EFIAPI
 310 KeyboardTimerHandler (
 311   IN EFI_EVENT  Event,
 312   IN VOID       *Context
 313   );
 314
 315 /**
 316   logic reset keyboard
 317   Implement SIMPLE_TEXT_IN.Reset()
 318   Perform 8042 controller and keyboard initialization
 319
 320   @param This    Pointer to instance of EFI_SIMPLE_TEXT_INPUT_PROTOCOL
 321   @param ExtendedVerification Indicate that the driver may perform a more
 322                               exhaustive verification operation of the device during
 323                               reset, now this par is ignored in this driver
 324
 325 **/
 326 EFI_STATUS
 327 EFIAPI
 328 KeyboardEfiReset (
 329   IN  EFI_SIMPLE_TEXT_INPUT_PROTOCOL  *This,
 330   IN  BOOLEAN                         ExtendedVerification
 331   );
 332
 333 /**
 334   Implement SIMPLE_TEXT_IN.ReadKeyStroke().
 335   Retrieve key values for driver user.
 336
 337   @param This    Pointer to instance of EFI_SIMPLE_TEXT_INPUT_PROTOCOL
 338   @param Key     The output buffer for key value
 339
 340   @retval EFI_SUCCESS success to read key stroke
 341 **/
 342 EFI_STATUS
 343 EFIAPI
 344 KeyboardReadKeyStroke (
 345   IN  EFI_SIMPLE_TEXT_INPUT_PROTOCOL  *This,
 346   OUT EFI_INPUT_KEY                   *Key
 347   );
 348
 349 /**
 350   Event notification function for SIMPLE_TEXT_IN.WaitForKey event
 351   Signal the event if there is key available
 352
 353   @param Event    the event object
 354   @param Context  waiting context
 355
 356 **/
 357 VOID
 358 EFIAPI
 359 KeyboardWaitForKey (
 360   IN  EFI_EVENT  Event,
 361   IN  VOID       *Context
 362   );
 363
 364 /**
 365   Read status register.
 366
 367   @param ConsoleIn  Pointer to instance of KEYBOARD_CONSOLE_IN_DEV
 368
 369   @return value in status register
 370
 371 **/
 372 UINT8
 373 KeyReadStatusRegister (
 374   IN KEYBOARD_CONSOLE_IN_DEV  *ConsoleIn
 375   );
 376
 377 /**
 378   Check whether there is Ps/2 Keyboard device in system by 0xF4 Keyboard Command
 379   If Keyboard receives 0xF4, it will respond with 'ACK'. If it doesn't respond, the device
 380   should not be in system.
 381
 382   @param[in]  ConsoleIn   Pointer to instance of KEYBOARD_CONSOLE_IN_DEV
 383
 384   @retval     TRUE                  Keyboard in System.
 385   @retval     FALSE                 Keyboard not in System.
 386 **/
 387 BOOLEAN
 388 EFIAPI
 389 CheckKeyboardConnect (
 390   IN KEYBOARD_CONSOLE_IN_DEV  *ConsoleIn
 391   );
 392
 393 /**
 394   Event notification function for SIMPLE_TEXT_INPUT_EX_PROTOCOL.WaitForKeyEx event
 395   Signal the event if there is key available
 396
 397   @param Event    event object
 398   @param Context  waiting context
 399
 400 **/
 401 VOID
 402 EFIAPI
 403 KeyboardWaitForKeyEx (
 404   IN  EFI_EVENT  Event,
 405   IN  VOID       *Context
 406   );
 407
 408 //
 409 // Simple Text Input Ex protocol function prototypes
 410 //
 411
 412 /**
 413   Reset the input device and optionally run diagnostics
 414
 415   @param This                 - Protocol instance pointer.
 416   @param ExtendedVerification - Driver may perform diagnostics on reset.
 417
 418   @retval EFI_SUCCESS           - The device was reset.
 419   @retval EFI_DEVICE_ERROR      - The device is not functioning properly and could
 420                                   not be reset.
 421
 422 **/
 423 EFI_STATUS
 424 EFIAPI
 425 KeyboardEfiResetEx (
 426   IN EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL  *This,
 427   IN BOOLEAN                            ExtendedVerification
 428   );
 429
 430 /**
 431     Reads the next keystroke from the input device. The WaitForKey Event can
 432     be used to test for existence of a keystroke via WaitForEvent () call.
 433
 434
 435     @param This       - Protocol instance pointer.
 436     @param KeyData    - A pointer to a buffer that is filled in with the keystroke
 437                  state data for the key that was pressed.
 438
 439     @retval EFI_SUCCESS           - The keystroke information was returned.
 440     @retval EFI_NOT_READY         - There was no keystroke data available.
 441     @retval EFI_DEVICE_ERROR      - The keystroke information was not returned due to
 442                             hardware errors.
 443     @retval EFI_INVALID_PARAMETER - KeyData is NULL.
 444
 445 **/
 446 EFI_STATUS
 447 EFIAPI
 448 KeyboardReadKeyStrokeEx (
 449   IN  EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL  *This,
 450   OUT EFI_KEY_DATA                       *KeyData
 451   );
 452
 453 /**
 454   Set certain state for the input device.
 455
 456   @param This              - Protocol instance pointer.
 457   @param KeyToggleState    - A pointer to the EFI_KEY_TOGGLE_STATE to set the
 458                         state for the input device.
 459
 460   @retval EFI_SUCCESS           - The device state was set successfully.
 461   @retval EFI_DEVICE_ERROR      - The device is not functioning correctly and could
 462                             not have the setting adjusted.
 463   @retval EFI_UNSUPPORTED       - The device does not have the ability to set its state.
 464   @retval EFI_INVALID_PARAMETER - KeyToggleState is NULL.
 465
 466 **/
 467 EFI_STATUS
 468 EFIAPI
 469 KeyboardSetState (
 470   IN EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL  *This,
 471   IN EFI_KEY_TOGGLE_STATE               *KeyToggleState
 472   );
 473
 474 /**
 475     Register a notification function for a particular keystroke for the input device.
 476
 477     @param This                    - Protocol instance pointer.
 478     @param KeyData                 - A pointer to a buffer that is filled in with the keystroke
 479                                      information data for the key that was pressed. If KeyData.Key,
 480                                      KeyData.KeyState.KeyToggleState and KeyData.KeyState.KeyShiftState are 0,
 481                                      then any incomplete keystroke will trigger a notification of the KeyNotificationFunction.
 482     @param KeyNotificationFunction - Points to the function to be called when the key
 483                                      sequence is typed specified by KeyData. This notification function
 484                                      should be called at <=TPL_CALLBACK.
 485     @param NotifyHandle            - Points to the unique handle assigned to the registered notification.
 486
 487     @retval EFI_SUCCESS             - The notification function was registered successfully.
 488     @retval EFI_OUT_OF_RESOURCES    - Unable to allocate resources for necessary data structures.
 489     @retval EFI_INVALID_PARAMETER   - KeyData or NotifyHandle is NULL.
 490
 491 **/
 492 EFI_STATUS
 493 EFIAPI
 494 KeyboardRegisterKeyNotify (
 495   IN EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL  *This,
 496   IN EFI_KEY_DATA                       *KeyData,
 497   IN EFI_KEY_NOTIFY_FUNCTION            KeyNotificationFunction,
 498   OUT VOID                              **NotifyHandle
 499   );
 500
 501 /**
 502     Remove a registered notification function from a particular keystroke.
 503
 504     @param This                    - Protocol instance pointer.
 505     @param NotificationHandle      - The handle of the notification function being unregistered.
 506
 507
 508     @retval EFI_SUCCESS             - The notification function was unregistered successfully.
 509     @retval EFI_INVALID_PARAMETER   - The NotificationHandle is invalid.
 510     @retval EFI_NOT_FOUND           - Can not find the matching entry in database.
 511
 512 **/
 513 EFI_STATUS
 514 EFIAPI
 515 KeyboardUnregisterKeyNotify (
 516   IN EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL  *This,
 517   IN VOID                               *NotificationHandle
 518   );
 519
 520 /**
 521   Push one key data to the EFI key buffer.
 522
 523   @param Queue     Pointer to instance of EFI_KEY_QUEUE.
 524   @param KeyData   The key data to push.
 525 **/
 526 VOID
 527 PushEfikeyBufTail (
 528   IN  EFI_KEY_QUEUE  *Queue,
 529   IN  EFI_KEY_DATA   *KeyData
 530   );
 531
 532 /**
 533   Judge whether is a registered key
 534
 535   @param RegsiteredData       A pointer to a buffer that is filled in with the keystroke
 536                               state data for the key that was registered.
 537   @param InputData            A pointer to a buffer that is filled in with the keystroke
 538                               state data for the key that was pressed.
 539
 540   @retval TRUE                Key be pressed matches a registered key.
 541   @retval FALSE               Match failed.
 542
 543 **/
 544 BOOLEAN
 545 IsKeyRegistered (
 546   IN EFI_KEY_DATA  *RegsiteredData,
 547   IN EFI_KEY_DATA  *InputData
 548   );
 549
 550 /**
 551   Initialize the key state.
 552
 553   @param  ConsoleIn     The KEYBOARD_CONSOLE_IN_DEV instance.
 554   @param  KeyState      A pointer to receive the key state information.
 555 **/
 556 VOID
 557 InitializeKeyState (
 558   IN  KEYBOARD_CONSOLE_IN_DEV  *ConsoleIn,
 559   OUT EFI_KEY_STATE            *KeyState
 560   );
 561
 562 #endif