Add lesson 39

Signed-off-by: Konstantin Aladyshev <aladyshev22@gmail.com>

1 files changed, 349 insertions, 0 deletions

diff --git a/Lessons/Lesson_39/README.md b/Lessons/Lesson_39/README.md
new file mode 100644
index 0000000..41aa82c
--- /dev/null
+++ b/Lessons/Lesson_39/README.md
@@ -0,0 +1,349 @@
+In this lesson we would create a driver that would register callbacks for hot key combinations.
+
+In UEFI in is possible to do with a help of `RegisterKeyNotify` function in `EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL`:
+```
+EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL.RegisterKeyNotify()
+
+Summary:
+Register a notification function for a particular keystroke for the input device.
+
+Prototype:
+typedef
+EFI_STATUS
+(EFIAPI *EFI_REGISTER_KEYSTROKE_NOTIFY) (
+ IN EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL *This,
+ IN EFI_KEY_DATA *KeyData,
+ IN EFI_KEY_NOTIFY_FUNCTION KeyNotificationFunction,
+ OUT VOID **NotifyHandle
+ );
+
+Parameters:
+This 				A pointer to the EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL instance.
+KeyData 			A pointer to a buffer that is filled in with the keystroke information
+				for the key that was pressed. If KeyData.Key, KeyData.KeyState.KeyToggleState and
+				KeyData.KeyState.KeyShiftState are 0, then any incomplete keystroke will trigger a
+				notification of the KeyNotificationFunction.
+KeyNotificationFunction		Points to the function to be called when the key sequence is typed
+				specified by KeyData.
+NotifyHandle 			Points to the unique handle assigned to the registered notification.
+
+Description:
+The RegisterKeystrokeNotify() function registers a function which will be called when a specified
+keystroke will occur. The keystroke being specified can be for any combination of KeyData.Key or
+KeyData.KeyState information.
+```
+
+The prototype for the callback function defined as:
+```
+typedef
+EFI_STATUS
+(EFIAPI *EFI_KEY_NOTIFY_FUNCTION) (
+ IN EFI_KEY_DATA *KeyData
+ );
+```
+
+As for `EFI_KEY_DATA` it is a structure with two fields:
+```
+typedef struct {
+ EFI_INPUT_KEY Key;            // The EFI scan code and Unicode value returned from the input device.
+ EFI_KEY_STATE KeyState;       // The current state of various toggled attributes as well as input modifier values.
+} EFI_KEY_DATA
+```
+
+The `EFI_INPUT_KEY` type is defined in the file https://github.com/tianocore/edk2/blob/master/MdePkg/Include/Protocol/SimpleTextIn.h:
+```
+typedef struct {
+  UINT16  ScanCode;
+  CHAR16  UnicodeChar;
+} EFI_INPUT_KEY;
+```
+We've already used it in our `InteractiveApp` application.
+
+`EFI_KEY_STATE` type is new, you can find in the https://github.com/tianocore/edk2/blob/master/MdePkg/Include/Protocol/SimpleTextInEx.h:
+```
+///
+/// EFI_KEY_TOGGLE_STATE. The toggle states are defined.
+/// They are: EFI_TOGGLE_STATE_VALID, EFI_SCROLL_LOCK_ACTIVE
+/// EFI_NUM_LOCK_ACTIVE, EFI_CAPS_LOCK_ACTIVE
+///
+typedef UINT8 EFI_KEY_TOGGLE_STATE;
+
+typedef struct _EFI_KEY_STATE {
+  ///
+  /// Reflects the currently pressed shift
+  /// modifiers for the input device. The
+  /// returned value is valid only if the high
+  /// order bit has been set.
+  ///
+  UINT32                KeyShiftState;
+  ///
+  /// Reflects the current internal state of
+  /// various toggled attributes. The returned
+  /// value is valid only if the high order
+  /// bit has been set.
+  ///
+  EFI_KEY_TOGGLE_STATE  KeyToggleState;
+} EFI_KEY_STATE;
+```
+
+To get an understanding of what information is coded in these `KeyShiftState`/`KeyToggleState` fields take a look at these defines from the same file:
+```
+//
+// Any Shift or Toggle State that is valid should have
+// high order bit set.
+//
+// Shift state
+//
+#define EFI_SHIFT_STATE_VALID     0x80000000
+#define EFI_RIGHT_SHIFT_PRESSED   0x00000001
+#define EFI_LEFT_SHIFT_PRESSED    0x00000002
+#define EFI_RIGHT_CONTROL_PRESSED 0x00000004
+#define EFI_LEFT_CONTROL_PRESSED  0x00000008
+#define EFI_RIGHT_ALT_PRESSED     0x00000010
+#define EFI_LEFT_ALT_PRESSED      0x00000020
+#define EFI_RIGHT_LOGO_PRESSED    0x00000040
+#define EFI_LEFT_LOGO_PRESSED     0x00000080
+#define EFI_MENU_KEY_PRESSED      0x00000100
+#define EFI_SYS_REQ_PRESSED       0x00000200
+
+//
+// Toggle state
+//
+#define EFI_TOGGLE_STATE_VALID    0x80
+#define EFI_KEY_STATE_EXPOSED     0x40
+#define EFI_SCROLL_LOCK_ACTIVE    0x01
+#define EFI_NUM_LOCK_ACTIVE       0x02
+#define EFI_CAPS_LOCK_ACTIVE      0x04
+```
+
+Also these edk2 files (https://github.com/tianocore/edk2/blob/master/MdePkg/Include/Protocol/SimpleTextIn.h and https://github.com/tianocore/edk2/blob/master/MdePkg/Include/Protocol/SimpleTextInEx.h) contain defines for the scan codes (up, down, right, left keys, home, end, delete, f1-f24, etc.). So if you'll ever what to use scan code for some exotic button, take a look in those files.
+
+Finally it is time to write code for our driver.
+
+Our driver would be called `HotKeyDriver`. It would register hot key combinations in its entry point function and unregister them in the unload function.
+
+UefiLessonsPkg/HotKeyDriver/HotKeyDriver.inf:
+```
+[Defines]
+  INF_VERSION                    = 1.25
+  BASE_NAME                      = HotKeyDriver
+  FILE_GUID                      = da316635-c66f-477e-9df6-880d2d729f1b
+  MODULE_TYPE                    = UEFI_DRIVER
+  VERSION_STRING                 = 1.0
+  ENTRY_POINT                    = HotKeyDriverEntryPoint
+  UNLOAD_IMAGE                   = HotKeyDriverUnload
+  
+[Sources]
+  HotKeyDriver.c
+
+[Packages]
+  MdePkg/MdePkg.dec
+
+[Protocols]
+  gEfiSimpleTextInputExProtocolGuid            # <----- guid for EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL
+
+[LibraryClasses]
+  UefiDriverEntryPoint
+  UefiLib
+```
+
+First in our driver entry point function we need to locate `EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL` by its guid `gEfiSimpleTextInputExProtocolGuid` (UefiLessonsPkg/HotKeyDriver/HotKeyDriver.c):
+```
+#include <Protocol/SimpleTextInEx.h>
+
+EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL* InputEx = NULL;
+
+EFI_STATUS
+EFIAPI
+HotKeyDriverEntryPoint(
+  IN EFI_HANDLE        ImageHandle,
+  IN EFI_SYSTEM_TABLE  *SystemTable
+  )
+{
+  EFI_STATUS Status = gBS->LocateProtocol(
+			 &gEfiSimpleTextInputExProtocolGuid,
+			 NULL,
+			 (VOID**)&InputEx
+			 );
+  if (EFI_ERROR(Status)) {
+    Print(L"Error! Can't locate EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL: %r", Status);
+    return Status;
+  }
+
+  ...
+
+  return EFI_SUCCESS;
+}
+```
+
+As we would need `EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL` in the unload function as well, we declare variable for it as global.
+
+Now it is time to use `RegisterKeyNotify` API. Let's create a callback that would be fired at `left ctrl + left alt + z` combination:
+```
+  EFI_KEY_DATA HotKey;
+  HotKey.Key.ScanCode = 0;
+  HotKey.Key.UnicodeChar = L'z';
+  HotKey.KeyState.KeyShiftState = EFI_LEFT_CONTROL_PRESSED | EFI_LEFT_ALT_PRESSED | EFI_SHIFT_STATE_VALID;
+  HotKey.KeyState.KeyToggleState = 0;
+
+  Status = InputEx->RegisterKeyNotify(InputEx,
+			&HotKey,
+			MyKeyNotificationFunction,
+                        (VOID**)&NotifyHandle);
+
+  if (EFI_ERROR(Status)) {
+    Print(L"Error! Can't perform RegisterKeyNotify: %r", Status);
+    return Status;
+  }
+```
+
+In the begining of our file we add a global variable for `NotifyHandle` (again, we need it global as it would be used in driver unload function) and define our `MyKeyNotificationFunction` callback function:
+```
+EFI_HANDLE NotifyHandle;
+
+EFI_STATUS EFIAPI MyKeyNotificationFunction(EFI_KEY_DATA* KeyData)
+{
+	Print(L"\nHot Key 1 is pressed\n");         // we add '\n' in the begining, so the output wouldn't interfere with the UEFI shell prompt
+	return EFI_SUCCESS;
+}
+```
+
+Let's write another callback that would be fired on any `z` press if numlock is active:
+```
+  HotKey.KeyState.KeyShiftState = 0;
+  HotKey.KeyState.KeyToggleState = EFI_TOGGLE_STATE_VALID | EFI_NUM_LOCK_ACTIVE | EFI_KEY_STATE_EXPOSED;
+  Status = InputEx->RegisterKeyNotify(InputEx,
+			&HotKey,
+			MyKeyNotificationFunction1,
+                        (VOID**)&NotifyHandle1);
+
+  if (EFI_ERROR(Status)) {
+    Print(L"Error! Can't perform RegisterKeyNotify: %r", Status);
+    return Status;
+  }
+```
+```
+EFI_HANDLE NotifyHandle1;
+
+EFI_STATUS EFIAPI MyKeyNotificationFunction1(EFI_KEY_DATA* KeyData)
+{
+	Print(L"\nHot Key 2 is pressed\n");     // we add '\n' in the begining, so the output wouldn't interfere with the UEFI shell prompt
+	return EFI_SUCCESS;                       // or another our callback function
+}
+```
+
+I've already mentioned couple of times, that we need to unregister callback function on driver unload. Why do we need that?
+
+Because these functions `MyKeyNotificationFunction` and `MyKeyNotificationFunction1` are defined in the `HotKeyDriver` memory. And as soon as we unload `HotKeyDriver` from memory, this memory would become freed/invalid. And on a hot key combination press system would try to dereference a callback function from the pointer to this invalid region. This would lead to an exception.
+
+For the unregister operation EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL defines `UnregisterKeyNotify` function:
+```
+EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL.UnregisterKeyNotify()
+
+Summary:
+Remove the notification that was previously registered.
+
+Prototype:
+typedef
+EFI_STATUS
+(EFIAPI *EFI_UNREGISTER_KEYSTROKE_NOTIFY) (
+ IN EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL *This,
+ IN VOID *NotificationHandle
+ );
+
+Parameters:
+This 			A pointer to the EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL instance.
+NotificationHandle	The handle of the notification function being unregistered.
+
+Description:
+The UnregisterKeystrokeNotify() function removes the notification which was previously registered. 
+```
+
+Let's use it to unregister our callbacks:
+```
+EFI_STATUS
+EFIAPI
+HotKeyDriverUnload(
+  IN EFI_HANDLE        ImageHandle
+  )
+{
+  if (!InputEx)
+    return EFI_SUCCESS;
+
+  EFI_STATUS Status;
+
+  if (!NotifyHandle) {
+    Status = InputEx->UnregisterKeyNotify(InputEx,
+                                   (VOID*)NotifyHandle);
+
+    if (EFI_ERROR(Status)) {
+      Print(L"Error! Can't perform RegisterKeyNotify: %r", Status);
+      return Status;
+    }
+  }
+
+  if (!NotifyHandle1) {
+    Status = InputEx->UnregisterKeyNotify(InputEx,
+                       (VOID*)NotifyHandle1);
+
+    if (EFI_ERROR(Status)) {
+      Print(L"Error! Can't perform RegisterKeyNotify: %r", Status);
+      return Status;
+    }
+  }
+
+  return EFI_SUCCESS;
+}
+```
+
+Now it is time to build and test our driver.
+
+To avoid terminal translations of non-ordinary keys to escape sequences we shouldn't run our QEMU with `-nographic` option as we usually do.
+
+We can either boot it with native graphics, or with graphics through the vnc server:
+```
+qemu-system-x86_64 \
+  -drive if=pflash,format=raw,file=Build/OvmfX64/RELEASE_GCC5/FV/OVMF.fd \
+  -drive format=raw,file=fat:rw:~/UEFI_disk
+```
+```
+qemu-system-x86_64 \
+  -drive if=pflash,format=raw,file=Build/OvmfX64/RELEASE_GCC5/FV/OVMF.fd \
+  -drive format=raw,file=fat:rw:~/UEFI_disk
+  -vnc :1
+```
+
+Once we boot QEMU, load our driver into OVMF:
+```
+FS0:\> load HotKeyDriver.efi
+Image 'FS0:\HotKeyDriver.efi' loaded at 6646000 - Success
+```
+
+If numlock is disabled only one callback is possible:
+- `left ctrl + left alt + z` produces
+```
+FS0:\>
+Hot Key 1 is pressed
+```
+If numlock is enabled:
+- `z` produces `Hot Key 2 is pressed`
+```
+FS0:\>
+Hot Key 2 is pressed
+```
+- `left ctrl + left alt + z` produces both prints:
+```
+FS0:\>
+Hot Key 1 is pressed
+Hot Key 2 is pressed
+```
+
+Don't forget to flush your screen with `cls` command in UEFI shell between different keystroke combinations, so you woudn't miss any new output.
+
+Also be aware that if QEMU is run in `-nographic` mode all the modifires are not parsed. So every `z` keystroke would always result with both callbacks:
+```
+FS0:\> z
+Hot Key 1 is pressed
+Hot Key 2 is pressed
+```
+