VirtualKeyboard.h 19 KB

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