EmbeddedPkg/Drivers/VirtualKeyboardDxe/VirtualKeyboard.h

   1 /** @file
   2
   3 Copyright (c) 2006 - 2016, Intel Corporation. All rights reserved.<BR>
   4 Copyright (c) 2018, Linaro Ltd. All rights reserved.<BR>
   5
   6 SPDX-License-Identifier: BSD-2-Clause-Patent
   7
   8 **/
   9
  10 #ifndef _VIRTUAL_KEYBOARD_H_
  11 #define _VIRTUAL_KEYBOARD_H_
  12
  13
  14 #include <Guid/StatusCodeDataTypeId.h>
  15 #include <Protocol/DevicePath.h>
  16 #include <Protocol/PlatformVirtualKeyboard.h>
  17 #include <Protocol/SimpleTextIn.h>
  18 #include <Protocol/SimpleTextInEx.h>
  19
  20 #include <Library/BaseLib.h>
  21 #include <Library/BaseMemoryLib.h>
  22 #include <Library/DebugLib.h>
  23 #include <Library/MemoryAllocationLib.h>
  24 #include <Library/IoLib.h>
  25 #include <Library/PcdLib.h>
  26 #include <Library/ReportStatusCodeLib.h>
  27 #include <Library/UefiBootServicesTableLib.h>
  28 #include <Library/UefiDriverEntryPoint.h>
  29 #include <Library/UefiLib.h>
  30
  31 //
  32 // Driver Binding Externs
  33 //
  34 extern EFI_DRIVER_BINDING_PROTOCOL  gVirtualKeyboardDriverBinding;
  35 extern EFI_COMPONENT_NAME_PROTOCOL  gVirtualKeyboardComponentName;
  36 extern EFI_COMPONENT_NAME2_PROTOCOL gVirtualKeyboardComponentName2;
  37
  38
  39 //
  40 // VIRTUAL Keyboard Defines
  41 //
  42 #define CHAR_SCANCODE                        0xe0
  43 #define CHAR_ESC                             0x1b
  44
  45 #define KEYBOARD_TIMEOUT                     65536   // 0.07s
  46 #define KEYBOARD_WAITFORVALUE_TIMEOUT        1000000 // 1s
  47 #define KEYBOARD_BAT_TIMEOUT                 4000000 // 4s
  48 #define KEYBOARD_TIMER_INTERVAL              500000  // 0.5s
  49
  50 #define QUEUE_MAX_COUNT                      32
  51
  52 #define KEYBOARD_SCAN_CODE_MAX_COUNT         32
  53
  54 //
  55 // VIRTUAL Keyboard Device Structure
  56 //
  57 #define VIRTUAL_KEYBOARD_DEV_SIGNATURE SIGNATURE_32 ('V', 'K', 'B', 'D')
  58 #define VIRTUAL_KEYBOARD_CONSOLE_IN_EX_NOTIFY_SIGNATURE SIGNATURE_32 ('v', 'k', 'c', 'n')
  59
  60 typedef struct _VIRTUAL_KEYBOARD_CONSOLE_IN_EX_NOTIFY {
  61   UINTN                                      Signature;
  62   EFI_KEY_DATA                               KeyData;
  63   EFI_KEY_NOTIFY_FUNCTION                    KeyNotificationFn;
  64   LIST_ENTRY                                 NotifyEntry;
  65 } VIRTUAL_KEYBOARD_CONSOLE_IN_EX_NOTIFY;
  66
  67 typedef struct {
  68   UINTN                                      Front;
  69   UINTN                                      Rear;
  70   EFI_KEY_DATA                               Buffer[QUEUE_MAX_COUNT];
  71 } SIMPLE_QUEUE;
  72
  73 typedef struct {
  74   UINT8                                      Buffer[KEYBOARD_SCAN_CODE_MAX_COUNT];
  75   UINTN                                      Head;
  76   UINTN                                      Tail;
  77 } SCAN_CODE_QUEUE;
  78
  79 typedef struct {
  80   UINTN                                      Signature;
  81   EFI_HANDLE                                 Handle;
  82   PLATFORM_VIRTUAL_KBD_PROTOCOL              *PlatformVirtual;
  83   EFI_SIMPLE_TEXT_INPUT_PROTOCOL             SimpleTextIn;
  84   EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL          SimpleTextInputEx;
  85
  86   //
  87   // Buffer storing EFI_KEY_DATA
  88   //
  89   SIMPLE_QUEUE                               Queue;
  90   SIMPLE_QUEUE                               QueueForNotify;
  91
  92   //
  93   // Notification Function List
  94   //
  95   LIST_ENTRY                                 NotifyList;
  96   EFI_EVENT                                  KeyNotifyProcessEvent;
  97   EFI_EVENT                                  TimerEvent;
  98 } VIRTUAL_KEYBOARD_DEV;
  99
 100 #define VIRTUAL_KEYBOARD_DEV_FROM_THIS(a)  CR (a, VIRTUAL_KEYBOARD_DEV, SimpleTextIn, VIRTUAL_KEYBOARD_DEV_SIGNATURE)
 101 #define TEXT_INPUT_EX_VIRTUAL_KEYBOARD_DEV_FROM_THIS(a) \
 102   CR (a, \
 103       VIRTUAL_KEYBOARD_DEV, \
 104       SimpleTextInputEx, \
 105       VIRTUAL_KEYBOARD_DEV_SIGNATURE \
 106       )
 107
 108 //
 109 // Global Variables
 110 //
 111 extern EFI_DRIVER_BINDING_PROTOCOL   gVirtualKeyboardDriverBinding;
 112
 113 //
 114 // Driver Binding Protocol functions
 115 //
 116
 117 /**
 118   Check whether the driver supports this device.
 119
 120   @param  This                   The Udriver binding protocol.
 121   @param  Controller             The controller handle to check.
 122   @param  RemainingDevicePath    The remaining device path.
 123
 124   @retval EFI_SUCCESS            The driver supports this controller.
 125   @retval other                  This device isn't supported.
 126
 127 **/
 128 EFI_STATUS
 129 EFIAPI
 130 VirtualKeyboardDriverBindingSupported (
 131   IN EFI_DRIVER_BINDING_PROTOCOL  *This,
 132   IN EFI_HANDLE                   Controller,
 133   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath
 134   );
 135
 136 /**
 137   Starts the device with this driver.
 138
 139   @param  This                   The driver binding instance.
 140   @param  Controller             Handle of device to bind driver to.
 141   @param  RemainingDevicePath    Optional parameter use to pick a specific child
 142                                  device to start.
 143
 144   @retval EFI_SUCCESS            The controller is controlled by the driver.
 145   @retval Other                  This controller cannot be started.
 146
 147 **/
 148 EFI_STATUS
 149 EFIAPI
 150 VirtualKeyboardDriverBindingStart (
 151   IN EFI_DRIVER_BINDING_PROTOCOL  *This,
 152   IN EFI_HANDLE                   Controller,
 153   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath
 154   );
 155
 156 /**
 157   Stop the device handled by this driver.
 158
 159   @param  This                   The driver binding protocol.
 160   @param  Controller             The controller to release.
 161   @param  NumberOfChildren       The number of handles in ChildHandleBuffer.
 162   @param  ChildHandleBuffer      The array of child handle.
 163
 164   @retval EFI_SUCCESS            The device was stopped.
 165   @retval EFI_DEVICE_ERROR       The device could not be stopped due to a device error.
 166   @retval Others                 Fail to uninstall protocols attached on the device.
 167
 168 **/
 169 EFI_STATUS
 170 EFIAPI
 171 VirtualKeyboardDriverBindingStop (
 172   IN  EFI_DRIVER_BINDING_PROTOCOL  *This,
 173   IN  EFI_HANDLE                   Controller,
 174   IN  UINTN                        NumberOfChildren,
 175   IN  EFI_HANDLE                   *ChildHandleBuffer
 176   );
 177
 178 /**
 179   Retrieves a Unicode string that is the user readable name of the driver.
 180
 181   This function retrieves the user readable name of a driver in the form of a
 182   Unicode string. If the driver specified by This has a user readable name in
 183   the language specified by Language, then a pointer to the driver name is
 184   returned in DriverName, and EFI_SUCCESS is returned. If the driver specified
 185   by This does not support the language specified by Language,
 186   then EFI_UNSUPPORTED is returned.
 187
 188   @param  This[in]              A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or
 189                                 EFI_COMPONENT_NAME_PROTOCOL instance.
 190
 191   @param  Language[in]          A pointer to a Null-terminated ASCII string
 192                                 array indicating the language. This is the
 193                                 language of the driver name that the caller is
 194                                 requesting, and it must match one of the
 195                                 languages specified in SupportedLanguages. The
 196                                 number of languages supported by a driver is up
 197                                 to the driver writer. Language is specified
 198                                 in RFC 4646 or ISO 639-2 language code format.
 199
 200   @param  DriverName[out]       A pointer to the Unicode string to return.
 201                                 This Unicode string is the name of the
 202                                 driver specified by This in the language
 203                                 specified by Language.
 204
 205   @retval EFI_SUCCESS           The Unicode string for the Driver specified by
 206                                 This and the language specified by Language was
 207                                 returned in DriverName.
 208
 209   @retval EFI_INVALID_PAVIRTUALETER Language is NULL.
 210
 211   @retval EFI_INVALID_PAVIRTUALETER DriverName is NULL.
 212
 213   @retval EFI_UNSUPPORTED       The driver specified by This does not support
 214                                 the language specified by Language.
 215
 216 **/
 217 EFI_STATUS
 218 EFIAPI
 219 VirtualKeyboardComponentNameGetDriverName (
 220   IN  EFI_COMPONENT_NAME_PROTOCOL  *This,
 221   IN  CHAR8                        *Language,
 222   OUT CHAR16                       **DriverName
 223   );
 224
 225
 226 /**
 227   Retrieves a Unicode string that is the user readable name of the controller
 228   that is being managed by a driver.
 229
 230   This function retrieves the user readable name of the controller specified by
 231   ControllerHandle and ChildHandle in the form of a Unicode string. If the
 232   driver specified by This has a user readable name in the language specified by
 233   Language, then a pointer to the controller name is returned in ControllerName,
 234   and EFI_SUCCESS is returned.  If the driver specified by This is not currently
 235   managing the controller specified by ControllerHandle and ChildHandle,
 236   then EFI_UNSUPPORTED is returned.  If the driver specified by This does not
 237   support the language specified by Language, then EFI_UNSUPPORTED is returned.
 238
 239   @param  This[in]              A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or
 240                                 EFI_COMPONENT_NAME_PROTOCOL instance.
 241
 242   @param  ControllerHandle[in]  The handle of a controller that the driver
 243                                 specified by This is managing.  This handle
 244                                 specifies the controller whose name is to be
 245                                 returned.
 246
 247   @param  ChildHandle[in]       The handle of the child controller to retrieve
 248                                 the name of.  This is an optional parameter that
 249                                 may be NULL.  It will be NULL for device
 250                                 drivers.  It will also be NULL for a bus drivers
 251                                 that wish to retrieve the name of the bus
 252                                 controller.  It will not be NULL for a bus
 253                                 driver that wishes to retrieve the name of a
 254                                 child controller.
 255
 256   @param  Language[in]          A pointer to a Null-terminated ASCII string
 257                                 array indicating the language.  This is the
 258                                 language of the driver name that the caller is
 259                                 requesting, and it must match one of the
 260                                 languages specified in SupportedLanguages. The
 261                                 number of languages supported by a driver is up
 262                                 to the driver writer. Language is specified in
 263                                 RFC 4646 or ISO 639-2 language code format.
 264
 265   @param  ControllerName[out]   A pointer to the Unicode string to return.
 266                                 This Unicode string is the name of the
 267                                 controller specified by ControllerHandle and
 268                                 ChildHandle in the language specified by
 269                                 Language from the point of view of the driver
 270                                 specified by This.
 271
 272   @retval EFI_SUCCESS           The Unicode string for the user readable name in
 273                                 the language specified by Language for the
 274                                 driver specified by This was returned in
 275                                 DriverName.
 276
 277   @retval EFI_INVALID_PAVIRTUALETER ControllerHandle is NULL.
 278
 279   @retval EFI_INVALID_PAVIRTUALETER ChildHandle is not NULL and it is not a valid
 280                                 EFI_HANDLE.
 281
 282   @retval EFI_INVALID_PAVIRTUALETER Language is NULL.
 283
 284   @retval EFI_INVALID_PAVIRTUALETER ControllerName is NULL.
 285
 286   @retval EFI_UNSUPPORTED       The driver specified by This is not currently
 287                                 managing the controller specified by
 288                                 ControllerHandle and ChildHandle.
 289
 290   @retval EFI_UNSUPPORTED       The driver specified by This does not support
 291                                 the language specified by Language.
 292
 293 **/
 294 EFI_STATUS
 295 EFIAPI
 296 VirtualKeyboardComponentNameGetControllerName (
 297   IN  EFI_COMPONENT_NAME_PROTOCOL      *This,
 298   IN  EFI_HANDLE                       ControllerHandle,
 299   IN  EFI_HANDLE                       ChildHandle        OPTIONAL,
 300   IN  CHAR8                            *Language,
 301   OUT CHAR16                           **ControllerName
 302   );
 303
 304
 305 //
 306 // Simple Text Input Protocol functions
 307 //
 308 /**
 309   Reset the Keyboard and do BAT test for it, if (ExtendedVerification == TRUE) then do some extra keyboard validations.
 310
 311   @param  This                  Pointer of simple text Protocol.
 312   @param  ExtendedVerification  Whether perform the extra validation of keyboard. True: perform; FALSE: skip.
 313
 314   @retval EFI_SUCCESS           The command byte is written successfully.
 315   @retval EFI_DEVICE_ERROR      Errors occurred during resetting keyboard.
 316
 317 **/
 318 EFI_STATUS
 319 EFIAPI
 320 VirtualKeyboardReset (
 321   IN  EFI_SIMPLE_TEXT_INPUT_PROTOCOL  *This,
 322   IN  BOOLEAN                         ExtendedVerification
 323   );
 324
 325 /**
 326   Reset the input device and optionaly run diagnostics
 327
 328   @param  This                  Protocol instance pointer.
 329   @param  ExtendedVerification  Driver may perform diagnostics on reset.
 330
 331   @retval EFI_SUCCESS           The device was reset.
 332   @retval EFI_DEVICE_ERROR      The device is not functioning properly and could
 333                                 not be reset.
 334
 335 **/
 336 EFI_STATUS
 337 EFIAPI
 338 VirtualKeyboardResetEx (
 339   IN EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL  *This,
 340   IN BOOLEAN                            ExtendedVerification
 341   );
 342
 343 /**
 344   Set certain state for the input device.
 345
 346   @param  This              Protocol instance pointer.
 347   @param  KeyToggleState    A pointer to the EFI_KEY_TOGGLE_STATE to set the
 348                             state for the input device.
 349
 350   @retval EFI_SUCCESS           The device state was set successfully.
 351   @retval EFI_DEVICE_ERROR      The device is not functioning correctly and could
 352                                 not have the setting adjusted.
 353   @retval EFI_UNSUPPORTED       The device does not have the ability to set its state.
 354   @retval EFI_INVALID_PAVIRTUALETER KeyToggleState is NULL.
 355
 356 **/
 357 EFI_STATUS
 358 EFIAPI
 359 VirtualKeyboardSetState (
 360   IN EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL  *This,
 361   IN EFI_KEY_TOGGLE_STATE               *KeyToggleState
 362   );
 363
 364 /**
 365   Register a notification function for a particular keystroke for the input device.
 366
 367   @param  This                    Protocol instance pointer.
 368   @param  KeyData                 A pointer to a buffer that is filled in with the keystroke
 369                                   information data for the key that was pressed.
 370   @param  KeyNotificationFunction Points to the function to be called when the key
 371                                   sequence is typed specified by KeyData.
 372   @param  NotifyHandle            Points to the unique handle assigned to the registered notification.
 373
 374
 375   @retval EFI_SUCCESS             The notification function was registered successfully.
 376   @retval EFI_OUT_OF_RESOURCES    Unable to allocate resources for necesssary data structures.
 377   @retval EFI_INVALID_PAVIRTUALETER   KeyData or NotifyHandle is NULL.
 378
 379 **/
 380 EFI_STATUS
 381 EFIAPI
 382 VirtualKeyboardRegisterKeyNotify (
 383   IN EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL  *This,
 384   IN EFI_KEY_DATA                       *KeyData,
 385   IN EFI_KEY_NOTIFY_FUNCTION            KeyNotificationFunction,
 386   OUT VOID                              **NotifyHandle
 387   );
 388
 389 /**
 390   Remove a registered notification function from a particular keystroke.
 391
 392   @param  This                 Protocol instance pointer.
 393   @param  NotificationHandle   The handle of the notification function being unregistered.
 394
 395   @retval EFI_SUCCESS             The notification function was unregistered successfully.
 396   @retval EFI_INVALID_PAVIRTUALETER   The NotificationHandle is invalid.
 397
 398 **/
 399 EFI_STATUS
 400 EFIAPI
 401 VirtualKeyboardUnregisterKeyNotify (
 402   IN EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL  *This,
 403   IN VOID                               *NotificationHandle
 404   );
 405
 406 //
 407 // Private worker functions
 408 //
 409 /**
 410   Free keyboard notify list.
 411
 412   @param  ListHead   The list head
 413
 414   @retval EFI_SUCCESS           Free the notify list successfully
 415   @retval EFI_INVALID_PAVIRTUALETER ListHead is invalid.
 416
 417 **/
 418 EFI_STATUS
 419 VirtualKeyboardFreeNotifyList (
 420   IN OUT LIST_ENTRY           *ListHead
 421   );
 422
 423 /**
 424   Check if key is registered.
 425
 426   @param  RegsiteredData    A pointer to a buffer that is filled in with the keystroke
 427                             state data for the key that was registered.
 428   @param  InputData         A pointer to a buffer that is filled in with the keystroke
 429                             state data for the key that was pressed.
 430
 431   @retval TRUE              Key be pressed matches a registered key.
 432   @retval FLASE             Match failed.
 433
 434 **/
 435 BOOLEAN
 436 IsKeyRegistered (
 437   IN EFI_KEY_DATA  *RegsiteredData,
 438   IN EFI_KEY_DATA  *InputData
 439   );
 440
 441 /**
 442   Waiting on the keyboard event, if there's any key pressed by the user, signal the event
 443
 444   @param  Event       The event that be siganlled when any key has been stroked.
 445   @param  Context     Pointer of the protocol EFI_SIMPLE_TEXT_INPUT_PROTOCOL.
 446
 447 **/
 448 VOID
 449 EFIAPI
 450 VirtualKeyboardWaitForKey (
 451   IN  EFI_EVENT  Event,
 452   IN  VOID       *Context
 453   );
 454
 455 /**
 456   Waiting on the keyboard event, if there's any key pressed by the user, signal the event
 457
 458   @param  Event    The event that be siganlled when any key has been stroked.
 459   @param  Context  Pointer of the protocol EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL.
 460
 461 **/
 462 VOID
 463 EFIAPI
 464 VirtualKeyboardWaitForKeyEx (
 465   IN  EFI_EVENT  Event,
 466   IN  VOID       *Context
 467   );
 468
 469 /**
 470   Timer event handler: read a series of key stroke from 8042
 471   and put them into memory key buffer.
 472   It is registered as running under TPL_NOTIFY
 473
 474   @param  Event   The timer event
 475   @param  Context A VIRTUAL_KEYBOARD_DEV pointer
 476
 477 **/
 478 VOID
 479 EFIAPI
 480 VirtualKeyboardTimerHandler (
 481   IN EFI_EVENT    Event,
 482   IN VOID         *Context
 483   );
 484
 485 /**
 486   Process key notify.
 487
 488   @param  Event                 Indicates the event that invoke this function.
 489   @param  Context               Indicates the calling context.
 490 **/
 491 VOID
 492 EFIAPI
 493 KeyNotifyProcessHandler (
 494   IN  EFI_EVENT                 Event,
 495   IN  VOID                      *Context
 496   );
 497
 498 /**
 499   Read out the scan code of the key that has just been stroked.
 500
 501   @param  This        Pointer of simple text Protocol.
 502   @param  Key         Pointer for store the key that read out.
 503
 504   @retval EFI_SUCCESS The key is read out successfully.
 505   @retval other       The key reading failed.
 506
 507 **/
 508 EFI_STATUS
 509 EFIAPI
 510 VirtualKeyboardReadKeyStroke (
 511   IN  EFI_SIMPLE_TEXT_INPUT_PROTOCOL  *This,
 512   OUT EFI_INPUT_KEY                   *Key
 513   );
 514
 515 /**
 516   Reads the next keystroke from the input device. The WaitForKey Event can
 517   be used to test for existance of a keystroke via WaitForEvent () call.
 518
 519   @param  This         Protocol instance pointer.
 520   @param  KeyData      A pointer to a buffer that is filled in with the keystroke
 521                        state data for the key that was pressed.
 522
 523   @retval  EFI_SUCCESS           The keystroke information was returned.
 524   @retval  EFI_NOT_READY         There was no keystroke data availiable.
 525   @retval  EFI_DEVICE_ERROR      The keystroke information was not returned due to
 526                                  hardware errors.
 527   @retval  EFI_INVALID_PAVIRTUALETER KeyData is NULL.
 528
 529 **/
 530 EFI_STATUS
 531 EFIAPI
 532 VirtualKeyboardReadKeyStrokeEx (
 533   IN  EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL *This,
 534   OUT EFI_KEY_DATA                      *KeyData
 535   );
 536
 537 #endif /* _VIRTUAL_KEYBOARD_H_ */