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 EFI_SIGNATURE_32 ('k', 'k', 'e', 'y')
  42 #define KEYBOARD_CONSOLE_IN_EX_NOTIFY_SIGNATURE EFI_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_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_EXTENDED               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_LEFT_LOGO_MAKE         0x5B //GUI key defined in Keyboard scan code
 176 #define SCANCODE_LEFT_LOGO_BREAK        0xDB
 177 #define SCANCODE_RIGHT_LOGO_MAKE        0x5C
 178 #define SCANCODE_RIGHT_LOGO_BREAK       0xDC
 179 #define SCANCODE_MENU_MAKE              0x5D //APPS key defined in Keyboard scan code
 180 #define SCANCODE_MENU_BREAK             0xDD
 181 #define SCANCODE_SYS_REQ_MAKE           0x37
 182 #define SCANCODE_MAX_MAKE               0x60
 183
 184 //
 185 // Other functions that are used among .c files
 186 //
 187 /**
 188   Show keyboard status lights according to
 189   indicators in ConsoleIn.
 190
 191   @param ConsoleIn Pointer to instance of KEYBOARD_CONSOLE_IN_DEV
 192
 193   @return status
 194
 195 **/
 196 EFI_STATUS
 197 UpdateStatusLights (
 198   IN KEYBOARD_CONSOLE_IN_DEV *ConsoleIn
 199   );
 200
 201 /**
 202   write key to keyboard
 203
 204   @param ConsoleIn Pointer to instance of KEYBOARD_CONSOLE_IN_DEV
 205   @param Data      value wanted to be written
 206
 207   @retval EFI_TIMEOUT - GC_TODO: Add description for return value
 208   @retval EFI_SUCCESS - GC_TODO: Add description for return value
 209
 210 **/
 211 EFI_STATUS
 212 KeyboardRead (
 213   IN KEYBOARD_CONSOLE_IN_DEV  *ConsoleIn,
 214   OUT UINT8                   *Data
 215   );
 216
 217 /**
 218   Get scancode from scancode buffer
 219   and translate into EFI-scancode and unicode defined by EFI spec
 220   The function is always called in TPL_NOTIFY
 221
 222   @param ConsoleIn KEYBOARD_CONSOLE_IN_DEV instance pointer
 223
 224   @retval EFI_NOT_READY - Input from console not ready yet.
 225   @retval EFI_SUCCESS   - Function executed successfully.
 226
 227 **/
 228 EFI_STATUS
 229 KeyGetchar (
 230   IN OUT KEYBOARD_CONSOLE_IN_DEV *ConsoleIn
 231   );
 232
 233 /**
 234   Perform 8042 controller and keyboard Initialization
 235   If ExtendedVerification is TRUE, do additional test for
 236   the keyboard interface
 237
 238   @param ConsoleIn - KEYBOARD_CONSOLE_IN_DEV instance pointer
 239   @param ExtendedVerification - indicates a thorough initialization
 240
 241   @retval EFI_DEVICE_ERROR Fail to init keyboard
 242   @retval EFI_SUCCESS      Success to init keyboard
 243 **/
 244 EFI_STATUS
 245 InitKeyboard (
 246   IN OUT KEYBOARD_CONSOLE_IN_DEV *ConsoleIn,
 247   IN BOOLEAN                     ExtendedVerification
 248   );
 249
 250 /**
 251   Disable the keyboard interface of the 8042 controller
 252
 253   @param ConsoleIn   - the device instance
 254
 255   @return status of issuing disable command
 256
 257 **/
 258 EFI_STATUS
 259 DisableKeyboard (
 260   IN KEYBOARD_CONSOLE_IN_DEV *ConsoleIn
 261   );
 262
 263 /**
 264   Timer event handler: read a series of scancodes from 8042
 265   and put them into memory scancode buffer.
 266   it read as much scancodes to either fill
 267   the memory buffer or empty the keyboard buffer.
 268   It is registered as running under TPL_NOTIFY
 269
 270   @param Event - The timer event
 271   @param Context - A KEYBOARD_CONSOLE_IN_DEV pointer
 272
 273 **/
 274 VOID
 275 EFIAPI
 276 KeyboardTimerHandler (
 277   IN EFI_EVENT    Event,
 278   IN VOID         *Context
 279   );
 280
 281 /**
 282   logic reset keyboard
 283   Implement SIMPLE_TEXT_IN.Reset()
 284   Perform 8042 controller and keyboard initialization
 285
 286   @param This    Pointer to instance of EFI_SIMPLE_TEXT_INPUT_PROTOCOL
 287   @param ExtendedVerification Indicate that the driver may perform a more
 288                               exhaustive verification operation of the device during
 289                               reset, now this par is ignored in this driver
 290
 291 **/
 292 EFI_STATUS
 293 EFIAPI
 294 KeyboardEfiReset (
 295   IN  EFI_SIMPLE_TEXT_INPUT_PROTOCOL  *This,
 296   IN  BOOLEAN                         ExtendedVerification
 297   );
 298
 299 /**
 300   Implement SIMPLE_TEXT_IN.ReadKeyStroke().
 301   Retrieve key values for driver user.
 302
 303   @param This    Pointer to instance of EFI_SIMPLE_TEXT_INPUT_PROTOCOL
 304   @param Key     The output buffer for key value
 305
 306   @retval EFI_SUCCESS success to read key stroke
 307 **/
 308 EFI_STATUS
 309 EFIAPI
 310 KeyboardReadKeyStroke (
 311   IN  EFI_SIMPLE_TEXT_INPUT_PROTOCOL  *This,
 312   OUT EFI_INPUT_KEY                   *Key
 313   );
 314
 315 /**
 316   Event notification function for SIMPLE_TEXT_IN.WaitForKey event
 317   Signal the event if there is key available
 318
 319   @param Event    the event object
 320   @param Context  waitting context
 321
 322 **/
 323 VOID
 324 EFIAPI
 325 KeyboardWaitForKey (
 326   IN  EFI_EVENT               Event,
 327   IN  VOID                    *Context
 328   );
 329
 330 /**
 331   Read status register
 332
 333   @param ConsoleIn  Pointer to instance of KEYBOARD_CONSOLE_IN_DEV
 334
 335   @return value in status register
 336
 337 **/
 338 UINT8
 339 KeyReadStatusRegister (
 340   IN KEYBOARD_CONSOLE_IN_DEV *ConsoleIn
 341   );
 342
 343 /**
 344   Check whether there is Ps/2 Keyboard device in system by 0xF4 Keyboard Command
 345   If Keyboard receives 0xF4, it will respond with 'ACK'. If it doesn't respond, the device
 346   should not be in system.
 347
 348   @param[in]  BiosKeyboardPrivate   Keyboard Private Data Structure
 349
 350   @retval     TRUE                  Keyboard in System.
 351   @retval     FALSE                 Keyboard not in System.
 352 **/
 353 BOOLEAN
 354 EFIAPI
 355 CheckKeyboardConnect (
 356   IN KEYBOARD_CONSOLE_IN_DEV *ConsoleIn
 357   );
 358
 359 /**
 360   Event notification function for SIMPLE_TEXT_INPUT_EX_PROTOCOL.WaitForKeyEx event
 361   Signal the event if there is key available
 362
 363   @param Event    event object
 364   @param Context  waiting context
 365
 366 **/
 367 VOID
 368 EFIAPI
 369 KeyboardWaitForKeyEx (
 370   IN  EFI_EVENT               Event,
 371   IN  VOID                    *Context
 372   );
 373
 374 //
 375 // Simple Text Input Ex protocol function prototypes
 376 //
 377
 378 /**
 379   Reset the input device and optionaly run diagnostics
 380
 381   @param This                 - Protocol instance pointer.
 382   @param ExtendedVerification - Driver may perform diagnostics on reset.
 383
 384   @retval EFI_SUCCESS           - The device was reset.
 385   @retval EFI_DEVICE_ERROR      - The device is not functioning properly and could
 386                                   not be reset.
 387
 388 **/
 389 EFI_STATUS
 390 EFIAPI
 391 KeyboardEfiResetEx (
 392   IN EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL  *This,
 393   IN BOOLEAN                            ExtendedVerification
 394   );
 395
 396 /**
 397     Reads the next keystroke from the input device. The WaitForKey Event can
 398     be used to test for existance of a keystroke via WaitForEvent () call.
 399
 400
 401     @param This       - Protocol instance pointer.
 402     @param KeyData    - A pointer to a buffer that is filled in with the keystroke
 403                  state data for the key that was pressed.
 404
 405     @retval EFI_SUCCESS           - The keystroke information was returned.
 406     @retval EFI_NOT_READY         - There was no keystroke data availiable.
 407     @retval EFI_DEVICE_ERROR      - The keystroke information was not returned due to
 408                             hardware errors.
 409     @retval EFI_INVALID_PARAMETER - KeyData is NULL.
 410
 411 **/
 412 EFI_STATUS
 413 EFIAPI
 414 KeyboardReadKeyStrokeEx (
 415   IN  EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL *This,
 416   OUT EFI_KEY_DATA                      *KeyData
 417   );
 418
 419 /**
 420   Set certain state for the input device.
 421
 422   @param This              - Protocol instance pointer.
 423   @param KeyToggleState    - A pointer to the EFI_KEY_TOGGLE_STATE to set the
 424                         state for the input device.
 425
 426   @retval EFI_SUCCESS           - The device state was set successfully.
 427   @retval EFI_DEVICE_ERROR      - The device is not functioning correctly and could
 428                             not have the setting adjusted.
 429   @retval EFI_UNSUPPORTED       - The device does not have the ability to set its state.
 430   @retval EFI_INVALID_PARAMETER - KeyToggleState is NULL.
 431
 432 **/
 433 EFI_STATUS
 434 EFIAPI
 435 KeyboardSetState (
 436   IN EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL  *This,
 437   IN EFI_KEY_TOGGLE_STATE               *KeyToggleState
 438   );
 439
 440 /**
 441     Register a notification function for a particular keystroke for the input device.
 442
 443     @param This                    - Protocol instance pointer.
 444     @param KeyData                 - A pointer to a buffer that is filled in with the keystroke
 445                               information data for the key that was pressed.
 446     @param KeyNotificationFunction - Points to the function to be called when the key
 447                               sequence is typed specified by KeyData.
 448     @param NotifyHandle            - Points to the unique handle assigned to the registered notification.
 449
 450     @retval EFI_SUCCESS             - The notification function was registered successfully.
 451     @retval EFI_OUT_OF_RESOURCES    - Unable to allocate resources for necesssary data structures.
 452     @retval EFI_INVALID_PARAMETER   - KeyData or NotifyHandle is NULL.
 453
 454 **/
 455 EFI_STATUS
 456 EFIAPI
 457 KeyboardRegisterKeyNotify (
 458   IN EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL  *This,
 459   IN EFI_KEY_DATA                       *KeyData,
 460   IN EFI_KEY_NOTIFY_FUNCTION            KeyNotificationFunction,
 461   OUT EFI_HANDLE                        *NotifyHandle
 462   );
 463
 464 /**
 465     Remove a registered notification function from a particular keystroke.
 466
 467     @param This                    - Protocol instance pointer.
 468     @param NotificationHandle      - The handle of the notification function being unregistered.
 469
 470
 471     @retval EFI_SUCCESS             - The notification function was unregistered successfully.
 472     @retval EFI_INVALID_PARAMETER   - The NotificationHandle is invalid.
 473     @retval EFI_NOT_FOUND           - Can not find the matching entry in database.
 474
 475 **/
 476 EFI_STATUS
 477 EFIAPI
 478 KeyboardUnregisterKeyNotify (
 479   IN EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL  *This,
 480   IN EFI_HANDLE                         NotificationHandle
 481   );
 482
 483 #endif