xref: /illumos-gate/usr/src/boot/efi/include/Protocol/SimpleTextInEx.h (revision f334afcfaebea1b7dc3430015651d8d748fa8a3e)
1 /** @file
2   Simple Text Input Ex protocol from the UEFI 2.0 specification.
3 
4   This protocol defines an extension to the EFI_SIMPLE_TEXT_INPUT_PROTOCOL
5   which exposes much more state and modifier information from the input device,
6   also allows one to register a notification for a particular keystroke.
7 
8   Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
9   SPDX-License-Identifier: BSD-2-Clause-Patent
10 
11 **/
12 
13 #ifndef __SIMPLE_TEXT_IN_EX_H__
14 #define __SIMPLE_TEXT_IN_EX_H__
15 
16 #include <Protocol/SimpleTextIn.h>
17 
18 #define EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL_GUID \
19   {0xdd9e7534, 0x7762, 0x4698, { 0x8c, 0x14, 0xf5, 0x85, 0x17, 0xa6, 0x25, 0xaa } }
20 
21 typedef struct _EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL;
22 
23 /**
24   The Reset() function resets the input device hardware. As part
25   of initialization process, the firmware/device will make a quick
26   but reasonable attempt to verify that the device is functioning.
27   If the ExtendedVerification flag is TRUE the firmware may take
28   an extended amount of time to verify the device is operating on
29   reset. Otherwise the reset operation is to occur as quickly as
30   possible. The hardware verification process is not defined by
31   this specification and is left up to the platform firmware or
32   driver to implement.
33 
34   @param This                 A pointer to the EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL instance.
35 
36   @param ExtendedVerification Indicates that the driver may
37                               perform a more exhaustive
38                               verification operation of the
39                               device during reset.
40 
41 
42   @retval EFI_SUCCESS       The device was reset.
43 
44   @retval EFI_DEVICE_ERROR  The device is not functioning
45                             correctly and could not be reset.
46 
47 **/
48 typedef
49 EFI_STATUS
50 (EFIAPI *EFI_INPUT_RESET_EX)(
51   IN EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL *This,
52   IN BOOLEAN                           ExtendedVerification
53   );
54 
55 ///
56 /// EFI_KEY_TOGGLE_STATE. The toggle states are defined.
57 /// They are: EFI_TOGGLE_STATE_VALID, EFI_SCROLL_LOCK_ACTIVE
58 /// EFI_NUM_LOCK_ACTIVE, EFI_CAPS_LOCK_ACTIVE
59 ///
60 typedef UINT8 EFI_KEY_TOGGLE_STATE;
61 
62 typedef struct _EFI_KEY_STATE {
63   ///
64   /// Reflects the currently pressed shift
65   /// modifiers for the input device. The
66   /// returned value is valid only if the high
67   /// order bit has been set.
68   ///
69   UINT32                  KeyShiftState;
70   ///
71   /// Reflects the current internal state of
72   /// various toggled attributes. The returned
73   /// value is valid only if the high order
74   /// bit has been set.
75   ///
76   EFI_KEY_TOGGLE_STATE    KeyToggleState;
77 } EFI_KEY_STATE;
78 
79 typedef struct {
80   ///
81   /// The EFI scan code and Unicode value returned from the input device.
82   ///
83   EFI_INPUT_KEY    Key;
84   ///
85   /// The current state of various toggled attributes as well as input modifier values.
86   ///
87   EFI_KEY_STATE    KeyState;
88 } EFI_KEY_DATA;
89 
90 //
91 // Any Shift or Toggle State that is valid should have
92 // high order bit set.
93 //
94 // Shift state
95 //
96 #define EFI_SHIFT_STATE_VALID      0x80000000
97 #define EFI_RIGHT_SHIFT_PRESSED    0x00000001
98 #define EFI_LEFT_SHIFT_PRESSED     0x00000002
99 #define EFI_RIGHT_CONTROL_PRESSED  0x00000004
100 #define EFI_LEFT_CONTROL_PRESSED   0x00000008
101 #define EFI_RIGHT_ALT_PRESSED      0x00000010
102 #define EFI_LEFT_ALT_PRESSED       0x00000020
103 #define EFI_RIGHT_LOGO_PRESSED     0x00000040
104 #define EFI_LEFT_LOGO_PRESSED      0x00000080
105 #define EFI_MENU_KEY_PRESSED       0x00000100
106 #define EFI_SYS_REQ_PRESSED        0x00000200
107 
108 //
109 // Toggle state
110 //
111 #define EFI_TOGGLE_STATE_VALID  0x80
112 #define EFI_KEY_STATE_EXPOSED   0x40
113 #define EFI_SCROLL_LOCK_ACTIVE  0x01
114 #define EFI_NUM_LOCK_ACTIVE     0x02
115 #define EFI_CAPS_LOCK_ACTIVE    0x04
116 
117 //
118 // EFI Scan codes
119 //
120 #define SCAN_F11              0x0015
121 #define SCAN_F12              0x0016
122 #define SCAN_PAUSE            0x0048
123 #define SCAN_F13              0x0068
124 #define SCAN_F14              0x0069
125 #define SCAN_F15              0x006A
126 #define SCAN_F16              0x006B
127 #define SCAN_F17              0x006C
128 #define SCAN_F18              0x006D
129 #define SCAN_F19              0x006E
130 #define SCAN_F20              0x006F
131 #define SCAN_F21              0x0070
132 #define SCAN_F22              0x0071
133 #define SCAN_F23              0x0072
134 #define SCAN_F24              0x0073
135 #define SCAN_MUTE             0x007F
136 #define SCAN_VOLUME_UP        0x0080
137 #define SCAN_VOLUME_DOWN      0x0081
138 #define SCAN_BRIGHTNESS_UP    0x0100
139 #define SCAN_BRIGHTNESS_DOWN  0x0101
140 #define SCAN_SUSPEND          0x0102
141 #define SCAN_HIBERNATE        0x0103
142 #define SCAN_TOGGLE_DISPLAY   0x0104
143 #define SCAN_RECOVERY         0x0105
144 #define SCAN_EJECT            0x0106
145 
146 /**
147   The function reads the next keystroke from the input device. If
148   there is no pending keystroke the function returns
149   EFI_NOT_READY. If there is a pending keystroke, then
150   KeyData.Key.ScanCode is the EFI scan code defined in Error!
151   Reference source not found. The KeyData.Key.UnicodeChar is the
152   actual printable character or is zero if the key does not
153   represent a printable character (control key, function key,
154   etc.). The KeyData.KeyState is shift state for the character
155   reflected in KeyData.Key.UnicodeChar or KeyData.Key.ScanCode .
156   When interpreting the data from this function, it should be
157   noted that if a class of printable characters that are
158   normally adjusted by shift modifiers (e.g. Shift Key + "f"
159   key) would be presented solely as a KeyData.Key.UnicodeChar
160   without the associated shift state. So in the previous example
161   of a Shift Key + "f" key being pressed, the only pertinent
162   data returned would be KeyData.Key.UnicodeChar with the value
163   of "F". This of course would not typically be the case for
164   non-printable characters such as the pressing of the Right
165   Shift Key + F10 key since the corresponding returned data
166   would be reflected both in the KeyData.KeyState.KeyShiftState
167   and KeyData.Key.ScanCode values. UEFI drivers which implement
168   the EFI_SIMPLE_TEXT_INPUT_EX protocol are required to return
169   KeyData.Key and KeyData.KeyState values. These drivers must
170   always return the most current state of
171   KeyData.KeyState.KeyShiftState and
172   KeyData.KeyState.KeyToggleState. It should also be noted that
173   certain input devices may not be able to produce shift or toggle
174   state information, and in those cases the high order bit in the
175   respective Toggle and Shift state fields should not be active.
176 
177 
178   @param This     A pointer to the EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL instance.
179 
180   @param KeyData  A pointer to a buffer that is filled in with
181                   the keystroke state data for the key that was
182                   pressed.
183 
184 
185   @retval EFI_SUCCESS      The keystroke information was returned.
186   @retval EFI_NOT_READY    There was no keystroke data available.
187   @retval EFI_DEVICE_ERROR The keystroke information was not returned due to
188                            hardware errors.
189 
190 
191 **/
192 typedef
193 EFI_STATUS
194 (EFIAPI *EFI_INPUT_READ_KEY_EX)(
195   IN  EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL *This,
196   OUT EFI_KEY_DATA                      *KeyData
197   );
198 
199 /**
200   The SetState() function allows the input device hardware to
201   have state settings adjusted.
202 
203   @param This           A pointer to the EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL instance.
204 
205   @param KeyToggleState Pointer to the EFI_KEY_TOGGLE_STATE to
206                         set the state for the input device.
207 
208 
209   @retval EFI_SUCCESS       The device state was set appropriately.
210 
211   @retval EFI_DEVICE_ERROR  The device is not functioning
212                             correctly and could not have the
213                             setting adjusted.
214 
215   @retval EFI_UNSUPPORTED   The device does not support the
216                             ability to have its state set.
217 
218 **/
219 typedef
220 EFI_STATUS
221 (EFIAPI *EFI_SET_STATE)(
222   IN EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL *This,
223   IN EFI_KEY_TOGGLE_STATE              *KeyToggleState
224   );
225 
226 ///
227 /// The function will be called when the key sequence is typed specified by KeyData.
228 ///
229 typedef
230 EFI_STATUS
231 (EFIAPI *EFI_KEY_NOTIFY_FUNCTION)(
232   IN EFI_KEY_DATA *KeyData
233   );
234 
235 /**
236   The RegisterKeystrokeNotify() function registers a function
237   which will be called when a specified keystroke will occur.
238 
239   @param This                     A pointer to the EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL instance.
240 
241   @param KeyData                  A pointer to a buffer that is filled in with
242                                   the keystroke information for the key that was
243                                   pressed. If KeyData.Key, KeyData.KeyState.KeyToggleState
244                                   and KeyData.KeyState.KeyShiftState are 0, then any incomplete
245                                   keystroke will trigger a notification of the KeyNotificationFunction.
246 
247   @param KeyNotificationFunction  Points to the function to be called when the key sequence
248                                   is typed specified by KeyData. This notification function
249                                   should be called at <=TPL_CALLBACK.
250 
251 
252   @param NotifyHandle             Points to the unique handle assigned to
253                                   the registered notification.
254 
255   @retval EFI_SUCCESS           Key notify was registered successfully.
256 
257   @retval EFI_OUT_OF_RESOURCES  Unable to allocate necessary
258                                 data structures.
259 
260 **/
261 typedef
262 EFI_STATUS
263 (EFIAPI *EFI_REGISTER_KEYSTROKE_NOTIFY)(
264   IN  EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL *This,
265   IN  EFI_KEY_DATA                      *KeyData,
266   IN  EFI_KEY_NOTIFY_FUNCTION           KeyNotificationFunction,
267   OUT VOID                              **NotifyHandle
268   );
269 
270 /**
271   The UnregisterKeystrokeNotify() function removes the
272   notification which was previously registered.
273 
274   @param This               A pointer to the EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL instance.
275 
276   @param NotificationHandle The handle of the notification
277                             function being unregistered.
278 
279   @retval EFI_SUCCESS           Key notify was unregistered successfully.
280 
281   @retval EFI_INVALID_PARAMETER The NotificationHandle is
282                                 invalid.
283 
284 **/
285 typedef
286 EFI_STATUS
287 (EFIAPI *EFI_UNREGISTER_KEYSTROKE_NOTIFY)(
288   IN EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL  *This,
289   IN VOID                               *NotificationHandle
290   );
291 
292 ///
293 /// The EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL is used on the ConsoleIn
294 /// device. It is an extension to the Simple Text Input protocol
295 /// which allows a variety of extended shift state information to be
296 /// returned.
297 ///
298 struct _EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL {
299   EFI_INPUT_RESET_EX                 Reset;
300   EFI_INPUT_READ_KEY_EX              ReadKeyStrokeEx;
301   ///
302   /// Event to use with WaitForEvent() to wait for a key to be available.
303   ///
304   EFI_EVENT                          WaitForKeyEx;
305   EFI_SET_STATE                      SetState;
306   EFI_REGISTER_KEYSTROKE_NOTIFY      RegisterKeyNotify;
307   EFI_UNREGISTER_KEYSTROKE_NOTIFY    UnregisterKeyNotify;
308 };
309 
310 extern EFI_GUID  gEfiSimpleTextInputExProtocolGuid;
311 
312 #endif
313