Event support and general console protocol cleanup (#44)

- Implemented basic support for awaiting UEFI events.
- Made Handle and Event different newtypes of `void*` so assigning one to the other is an error
    * No ergonomics are lost since from the user's point of view these are opaque types anyway.
- Clarified the stateful nature of Pointer::get_state
- Made text input protocol more consistent with pointer protocol
- Improved documentation and method ordering of text output protocol

Author: HadrienG2

src/data_types/mod.rs

@@ -1,5 +1,14 @@
-/// A pointer to an opaque data structure.
-pub type Handle = *mut ();
+use core::ffi::c_void;
+
+/// Opaque handle to an UEFI entity (protocol, image...)
+#[derive(Clone, Copy)]
+#[repr(transparent)]
+pub struct Handle(*mut c_void);
+
+/// Handle to an event structure
+#[derive(Clone, Copy)]
+#[repr(transparent)]
+pub struct Event(*mut c_void);
 
 mod guid;
 pub use self::guid::Guid;

src/lib.rs

@@ -36,7 +36,7 @@ mod error;
 pub use self::error::{Result, Status};
 
 mod data_types;
-pub use self::data_types::{Guid, Handle};
+pub use self::data_types::{Event, Guid, Handle};
 
 pub mod table;
 

src/proto/console/pointer/mod.rs

@@ -1,14 +1,14 @@
 //! Pointer device access.
 
 use core::mem;
-use crate::{Result, Status};
+use crate::{Event, Result, Status};
 
 /// Provides information about a pointer device.
 #[repr(C)]
 pub struct Pointer {
     reset: extern "win64" fn(this: &mut Pointer, ext_verif: bool) -> Status,
     get_state: extern "win64" fn(this: &Pointer, state: &mut PointerState) -> Status,
-    _wait_for_input: usize,
+    wait_for_input: Event,
     mode: &'static PointerMode,
 }
 
@@ -25,13 +25,15 @@ impl Pointer {
         (self.reset)(self, extended_verification).into()
     }
 
-    /// Retrieves the pointer device's current state.
+    /// Retrieves the pointer device's current state, if a state change occured
+    /// since the last time this function was called.
     ///
-    /// Will return None if the state has not changed since the last query.
+    /// Use wait_for_input_event() with the BootServices::wait_for_event()
+    /// interface in order to wait for input from the pointer device.
     ///
     /// # Errors
     /// - `DeviceError` if there was an issue with the pointer device.
-    pub fn state(&self) -> Result<Option<PointerState>> {
+    pub fn read_state(&mut self) -> Result<Option<PointerState>> {
         let mut pointer_state = unsafe { mem::uninitialized() };
 
         match (self.get_state)(self, &mut pointer_state) {
@@ -41,6 +43,12 @@ impl Pointer {
         }
     }
 
+    /// Event to use with BootServices::wait_for_event() to wait for input from
+    /// the pointer device
+    pub fn wait_for_input_event(&self) -> Event {
+        self.wait_for_input
+    }
+
     /// Returns a reference to the pointer device information.
     pub fn mode(&self) -> &PointerMode {
         self.mode

src/proto/console/text/input.rs

@@ -1,45 +1,50 @@
 use core::mem;
-use crate::{Result, Status};
+use crate::{Event, Result, Status};
 
 /// Interface for text-based input devices.
 #[repr(C)]
 pub struct Input {
     reset: extern "win64" fn(this: &mut Input, extended: bool) -> Status,
     read_key_stroke: extern "win64" fn(this: &mut Input, key: &mut Key) -> Status,
+    wait_for_key: Event,
 }
 
 impl Input {
     /// Resets the input device hardware.
-    pub fn reset(&mut self, extended: bool) -> Result<()> {
-        (self.reset)(self, extended).into()
+    ///
+    /// The `extended_verification` parameter is used to request that UEFI
+    /// performs an extended check and reset of the input device.
+    ///
+    /// # Errors
+    ///
+    /// - `DeviceError` if the device is malfunctioning and cannot be reset.
+    pub fn reset(&mut self, extended_verification: bool) -> Result<()> {
+        (self.reset)(self, extended_verification).into()
     }
 
-    /// Reads the next keystroke from the input device.
+    /// Reads the next keystroke from the input device, if any.
+    ///
+    /// Use wait_for_key_event() with the BootServices::wait_for_event()
+    /// interface in order to wait for a key to be pressed.
     ///
-    /// Returns `Err(NotReady)` if no keystroke is available yet.
-    pub fn read_key(&mut self) -> Result<Key> {
+    /// # Errors
+    ///
+    /// - `DeviceError` if there was an issue with the input device
+    pub fn read_key(&mut self) -> Result<Option<Key>> {
         let mut key = unsafe { mem::uninitialized() };
-        (self.read_key_stroke)(self, &mut key)?;
-        Ok(key)
-    }
 
-    /// Blocks until a key is read from the device or an error occurs.
-    pub fn read_key_sync(&mut self) -> Result<Key> {
-        loop {
-            match self.read_key() {
-                // Received a key, exit loop.
-                Ok(key) => return Ok(key),
-                Err(code) => {
-                    match code {
-                        // Wait for key press.
-                        Status::NotReady => (),
-                        // Exit on error, no point in looping.
-                        _ => return Err(code),
-                    }
-                }
-            }
+        match (self.read_key_stroke)(self, &mut key) {
+            Status::Success => Ok(Some(key)),
+            Status::NotReady => Ok(None),
+            error => Err(error),
         }
     }
+
+    /// Event to use with BootServices::wait_for_event() to wait for a key to be
+    /// available
+    pub fn wait_for_key_event(&self) -> Event {
+        self.wait_for_key
+    }
 }
 
 /// A key read from the console.

src/proto/console/text/output.rs

@@ -62,7 +62,16 @@ impl Output {
         }
     }
 
-    /// Returns the width (column count) and height (row count) of this mode.
+    /// Returns the width (column count) and height (row count) of a text mode.
+    ///
+    /// Devices are required to support at least an 80x25 text mode and to
+    /// assign index 0 to it. If 80x50 is supported, then it will be mode 1,
+    /// otherwise querying for mode 1 will return the `Unsupported` error.
+    /// Modes 2+ will describe other text modes supported by the device.
+    ///
+    /// If you want to iterate over all text modes supported by the device,
+    /// consider using the iterator produced by `modes()` as a more ergonomic
+    /// alternative to this method.
     fn query_mode(&self, index: i32) -> Result<(usize, usize)> {
         let (mut columns, mut rows) = (0, 0);
         (self.query_mode)(self, index, &mut columns, &mut rows)?;
@@ -81,23 +90,26 @@ impl Output {
         Ok(OutputMode { index, dims })
     }
 
-    /// Enables or disables the cursor.
+    /// Make the cursor visible or invisible.
+    ///
+    /// The output device may not support this operation, in which case an
+    /// `Unsupported` error will be returned.
     pub fn enable_cursor(&mut self, visible: bool) -> Result<()> {
         (self.enable_cursor)(self, visible).into()
     }
 
+    /// Returns whether the cursor is currently shown or not.
+    pub fn cursor_visible(&self) -> bool {
+        self.data.cursor_visible
+    }
+
     /// Returns the column and row of the cursor.
     pub fn get_cursor_position(&self) -> (usize, usize) {
         let column = self.data.cursor_column;
         let row = self.data.cursor_row;
         (column as usize, row as usize)
     }
 
-    /// Returns whether the cursor is currently shown or not.
-    pub fn is_cursor_visible(&self) -> bool {
-        self.data.cursor_visible
-    }
-
     /// Sets the cursor's position, relative to the top-left corner, which is (0, 0).
     ///
     /// This function will fail if the cursor's new position would exceed the screen's bounds.
@@ -255,7 +267,7 @@ impl_proto! {
 #[derive(Debug, Copy, Clone)]
 #[repr(u8)]
 pub enum Color {
-    Black,
+    Black = 0,
     Blue,
     Green,
     Cyan,

src/table/boot.rs

@@ -2,9 +2,9 @@
 
 use super::Header;
 use bitflags::bitflags;
-use core::{mem, ptr};
+use core::{mem, ptr, result};
 use crate::proto::Protocol;
-use crate::{Guid, Handle, Result, Status};
+use crate::{Event, Guid, Handle, Result, Status};
 
 /// Contains pointers to all of the boot services.
 #[repr(C)]
@@ -29,7 +29,9 @@ pub struct BootServices {
     // Event & timer functions
     create_event: usize,
     set_timer: usize,
-    wait_for_event: usize,
+    wait_for_event:
+        extern "win64" fn(number_of_events: usize, events: *mut Event, out_index: &mut usize)
+            -> Status,
     signal_event: usize,
     close_event: usize,
     check_event: usize,
@@ -203,6 +205,43 @@ impl BootServices {
         (self.free_pool)(addr).into()
     }
 
+    /// Stops execution until an event is signaled
+    ///
+    /// This function must be called at priority level Tpl::Application. If an
+    /// attempt is made to call it at any other priority level, an `Unsupported`
+    /// error is returned.
+    ///
+    /// The input Event slice is repeatedly iterated from first to last until an
+    /// event is signaled or an error is detected. The following checks are
+    /// performed on each event:
+    ///
+    /// * If an event is of type NotifySignal, then an `InvalidParameter` error
+    ///   is returned together with the index of the event that caused the failure.
+    /// * If an event is in the signaled state, the signaled state is cleared
+    ///   and the index of the event that was signaled is returned.
+    /// * If an event is not in the signaled state but does have a notification
+    ///   function, the notification function is queued at the event's
+    ///   notification task priority level. If the execution of the event's
+    ///   notification function causes the event to be signaled, then the
+    ///   signaled state is cleared and the index of the event that was signaled
+    ///   is returned.
+    ///
+    /// To wait for a specified time, a timer event must be included in the
+    /// Event slice.
+    ///
+    /// To check if an event is signaled without waiting, an already signaled
+    /// event can be used as the last event in the slice being checked, or the
+    /// check_event() interface may be used.
+    pub fn wait_for_event(&self, events: &mut [Event]) -> result::Result<usize, (Status, usize)> {
+        let (number_of_events, events) = (events.len(), events.as_mut_ptr());
+        let mut index = unsafe { mem::uninitialized() };
+        match (self.wait_for_event)(number_of_events, events, &mut index) {
+            Status::Success => Ok(index),
+            s @ Status::InvalidParameter => Err((s, index)),
+            error => Err((error, 0)),
+        }
+    }
+
     /// Query a handle for a certain protocol.
     ///
     /// This function attempts to get the protocol implementation of a handle,

uefi-test-runner/src/proto/console/pointer.rs

@@ -12,7 +12,9 @@ pub fn test(bt: &BootServices) {
             .reset(false)
             .expect("Failed to reset pointer device");
 
-        let state = pointer.state().expect("Failed to retrieve pointer state");
+        let state = pointer
+            .read_state()
+            .expect("Failed to retrieve pointer state");
         if let Some(state) = state {
             info!("New pointer State: {:#?}", state);
         } else {