Merge pull request #293 from timrobertsdev/impl_event_fns

Implement missing `Event`-related functions

Author: nicholasbishop

src/data_types/mod.rs

@@ -16,10 +16,21 @@ impl Handle {
 }
 
 /// Handle to an event structure
-#[derive(Clone, Copy)]
 #[repr(transparent)]
 pub struct Event(*mut c_void);
 
+impl Event {
+    /// Clone this `Event`
+    ///
+    /// # Safety
+    /// When an event is closed by calling `BootServices::close_event`, that event and ALL references
+    /// to it are invalidated and the underlying memory is freed by firmware. The caller must ensure
+    /// that any clones of a closed `Event` are never used again.
+    pub unsafe fn unsafe_clone(&self) -> Self {
+        Self(self.0)
+    }
+}
+
 /// Trait for querying the alignment of a struct
 ///
 /// Needed for dynamic-sized types because `mem::align_of` has a `Sized` bound (due to `dyn Trait`)

src/proto/console/pointer/mod.rs

@@ -47,8 +47,8 @@ impl<'boot> Pointer<'boot> {
 
     /// Event to be used with `BootServices::wait_for_event()` in order to wait
     /// for input from the pointer device
-    pub fn wait_for_input_event(&self) -> Event {
-        self.wait_for_input
+    pub fn wait_for_input_event(&self) -> &Event {
+        &self.wait_for_input
     }
 
     /// Returns a reference to the pointer device information.

src/proto/console/text/input.rs

@@ -44,8 +44,8 @@ impl Input {
 
     /// Event to be used with `BootServices::wait_for_event()` in order to wait
     /// for a key to be available
-    pub fn wait_for_key_event(&self) -> Event {
-        self.wait_for_key
+    pub fn wait_for_key_event(&self) -> &Event {
+        &self.wait_for_key
     }
 }
 

src/table/boot.rs

@@ -13,6 +13,7 @@ use core::cell::UnsafeCell;
 use core::ffi::c_void;
 use core::fmt::{Debug, Formatter};
 use core::mem::{self, MaybeUninit};
+use core::ptr::NonNull;
 use core::{ptr, slice};
 
 /// Contains pointers to all of the boot services.
@@ -48,17 +49,17 @@ pub struct BootServices {
         ty: EventType,
         notify_tpl: Tpl,
         notify_func: Option<EventNotifyFn>,
-        notify_ctx: *mut c_void,
-        event: *mut Event,
+        notify_ctx: Option<NonNull<c_void>>,
+        out_event: *mut Event,
     ) -> Status,
     set_timer: unsafe extern "efiapi" fn(event: Event, ty: u32, trigger_time: u64) -> Status,
     wait_for_event: unsafe extern "efiapi" fn(
         number_of_events: usize,
         events: *mut Event,
         out_index: *mut usize,
     ) -> Status,
-    signal_event: usize,
-    close_event: usize,
+    signal_event: extern "efiapi" fn(event: Event) -> Status,
+    close_event: unsafe extern "efiapi" fn(event: Event) -> Status,
     check_event: unsafe extern "efiapi" fn(event: Event) -> Status,
 
     // Protocol handlers
@@ -149,7 +150,14 @@ pub struct BootServices {
     set_mem: unsafe extern "efiapi" fn(buffer: *mut u8, len: usize, value: u8),
 
     // New event functions (UEFI 2.0 or newer)
-    create_event_ex: usize,
+    create_event_ex: unsafe extern "efiapi" fn(
+        ty: EventType,
+        notify_tpl: Tpl,
+        notify_fn: Option<EventNotifyFn>,
+        notify_ctx: Option<NonNull<c_void>>,
+        event_group: Option<NonNull<Guid>>,
+        out_event: *mut Event,
+    ) -> Status,
 }
 
 impl BootServices {
@@ -307,44 +315,81 @@ impl BootServices {
         &self,
         event_ty: EventType,
         notify_tpl: Tpl,
-        notify_fn: Option<fn(Event)>,
+        notify_fn: Option<EventNotifyFn>,
+        notify_ctx: Option<NonNull<c_void>>,
     ) -> Result<Event> {
         // Prepare storage for the output Event
         let mut event = MaybeUninit::<Event>::uninit();
 
-        // Use a trampoline to handle the impedance mismatch between Rust & C
-        unsafe extern "efiapi" fn notify_trampoline(e: Event, ctx: *mut c_void) {
-            let notify_fn: fn(Event) = mem::transmute(ctx);
-            notify_fn(e); // SAFETY: Aborting panics are assumed here
-        }
-        let (notify_func, notify_ctx) = notify_fn
-            .map(|notify_fn| {
-                (
-                    Some(notify_trampoline as EventNotifyFn),
-                    notify_fn as fn(Event) as *mut c_void,
-                )
-            })
-            .unwrap_or((None, ptr::null_mut()));
-
         // Now we're ready to call UEFI
         (self.create_event)(
             event_ty,
             notify_tpl,
-            notify_func,
+            notify_fn,
+            notify_ctx,
+            event.as_mut_ptr(),
+        )
+        .into_with_val(|| event.assume_init())
+    }
+
+    /// Creates a new `Event` of type `event_type`. The event's notification function, context,
+    /// and task priority are specified by `notify_fn`, `notify_ctx`, and `notify_tpl`, respectively.
+    /// The `Event` will be added to the group of `Event`s identified by `event_group`.
+    ///
+    /// If no group is specified by `event_group`, this function behaves as if the same parameters
+    /// had been passed to `create_event()`.
+    ///
+    /// Event groups are collections of events identified by a shared `Guid` where, when one member
+    /// event is signaled, all other events are signaled and their individual notification actions
+    /// are taken. All events are guaranteed to be signaled before the first notification action is
+    /// taken. All notification functions will be executed in the order specified by their `Tpl`.
+    ///
+    /// A single event can only be part of a single event group. An event may be removed from an
+    /// event group by using `close_event()`.
+    ///
+    /// The `EventType` of an event uses the same values as `create_event()`, except that
+    /// `EventType::SIGNAL_EXIT_BOOT_SERVICES` and `EventType::SIGNAL_VIRTUAL_ADDRESS_CHANGE`
+    /// are not valid.
+    ///
+    /// If `event_type` has `EventType::NOTIFY_SIGNAL` or `EventType::NOTIFY_WAIT`, then `notify_fn`
+    /// mus be `Some` and `notify_tpl` must be a valid task priority level, otherwise these parameters
+    /// are ignored.
+    ///
+    /// More than one event of type `EventType::TIMER` may be part of a single event group. However,
+    /// there is no mechanism for determining which of the timers was signaled.
+    ///
+    /// # Safety
+    ///
+    /// The caller must ensure they are passing a valid `Guid` as `event_group`, if applicable.
+    pub unsafe fn create_event_ex(
+        &self,
+        event_type: EventType,
+        notify_tpl: Tpl,
+        notify_fn: Option<EventNotifyFn>,
+        notify_ctx: Option<NonNull<c_void>>,
+        event_group: Option<NonNull<Guid>>,
+    ) -> Result<Event> {
+        let mut event = MaybeUninit::<Event>::uninit();
+
+        (self.create_event_ex)(
+            event_type,
+            notify_tpl,
+            notify_fn,
             notify_ctx,
+            event_group,
             event.as_mut_ptr(),
         )
         .into_with_val(|| event.assume_init())
     }
 
     /// Sets the trigger for `EventType::TIMER` event.
-    pub fn set_timer(&self, event: Event, trigger_time: TimerTrigger) -> Result {
+    pub fn set_timer(&self, event: &Event, trigger_time: TimerTrigger) -> Result {
         let (ty, time) = match trigger_time {
             TimerTrigger::Cancel => (0, 0),
             TimerTrigger::Periodic(hundreds_ns) => (1, hundreds_ns),
             TimerTrigger::Relative(hundreds_ns) => (2, hundreds_ns),
         };
-        unsafe { (self.set_timer)(event, ty, time) }.into()
+        unsafe { (self.set_timer)(event.unsafe_clone(), ty, time) }.into()
     }
 
     /// Stops execution until an event is signaled.
@@ -389,6 +434,35 @@ impl BootServices {
         )
     }
 
+    /// Place 'event' in the signaled stated. If 'event' is already in the signaled state,
+    /// then nothing further occurs and `Status::SUCCESS` is returned. If `event` is of type
+    /// `EventType::NOTIFY_SIGNAL`, then the event's notification function is scheduled to
+    /// be invoked at the event's notification task priority level.
+    ///
+    /// This function may be invoked from any task priority level.
+    ///
+    /// If `event` is part of an event group, then all of the events in the event group are
+    /// also signaled and their notification functions are scheduled.
+    ///
+    /// When signaling an event group, it is possible to create an event in the group, signal
+    /// it, and then close the event to remove it from the group.
+    pub fn signal_event(&self, event: &Event) -> Result {
+        // Safety: cloning this event should be safe, as we're directly passing it to firmware
+        // and not keeping the clone around.
+        unsafe { (self.signal_event)(event.unsafe_clone()).into() }
+    }
+
+    /// Removes `event` from any event group to which it belongs and closes it. If `event` was
+    /// registered with `register_protocol_notify()`, then the corresponding registration will
+    /// be removed. It is safe to call this function within the corresponding notify function.
+    ///
+    ///
+    /// Note: The UEFI Specification v2.9 states that this may only return `EFI_SUCCESS`, but,
+    /// at least for application based on EDK2 (such as OVMF), it may also return `EFI_INVALID_PARAMETER`.
+    pub fn close_event(&self, event: Event) -> Result {
+        unsafe { (self.close_event)(event).into() }
+    }
+
     /// Checks to see if an event is signaled, without blocking execution to wait for it.
     ///
     /// The returned value will be `true` if the event is in the signaled state,
@@ -1116,7 +1190,7 @@ bitflags! {
 }
 
 /// Raw event notification function
-type EventNotifyFn = unsafe extern "efiapi" fn(event: Event, context: *mut c_void);
+type EventNotifyFn = unsafe extern "efiapi" fn(event: Event, context: Option<NonNull<c_void>>);
 
 /// Timer events manipulation
 pub enum TimerTrigger {

uefi-services/src/lib.rs

@@ -14,12 +14,14 @@
 #![feature(asm)]
 #![feature(lang_items)]
 #![feature(panic_info_message)]
+#![feature(abi_efiapi)]
 
 #[macro_use]
 extern crate log;
 // Core types.
 extern crate uefi;
 
+use core::ffi::c_void;
 use core::ptr::NonNull;
 
 use cfg_if::cfg_if;
@@ -81,6 +83,7 @@ pub fn init(st: &mut SystemTable<Boot>) -> Result {
                 EventType::SIGNAL_EXIT_BOOT_SERVICES,
                 Tpl::NOTIFY,
                 Some(exit_boot_services),
+                None,
             )
             .map_inner(|_| ())
     }
@@ -107,19 +110,19 @@ unsafe fn init_logger(st: &mut SystemTable<Boot>) {
 }
 
 /// Notify the utility library that boot services are not safe to call anymore
-fn exit_boot_services(_e: Event) {
+/// As this is a callback, it must be `extern "efiapi"`.
+unsafe extern "efiapi" fn exit_boot_services(_e: Event, _ctx: Option<NonNull<c_void>>) {
     // DEBUG: The UEFI spec does not guarantee that this printout will work, as
     //        the services used by logging might already have been shut down.
     //        But it works on current OVMF, and can be used as a handy way to
     //        check that the callback does get called.
     //
     // info!("Shutting down the UEFI utility library");
-    unsafe {
-        SYSTEM_TABLE = None;
-        if let Some(ref mut logger) = LOGGER {
-            logger.disable();
-        }
+    SYSTEM_TABLE = None;
+    if let Some(ref mut logger) = LOGGER {
+        logger.disable();
     }
+
     uefi::alloc::exit_boot_services();
 }
 

uefi-test-runner/src/boot/misc.rs

@@ -1,3 +1,7 @@
+use core::ffi::c_void;
+use core::ptr::NonNull;
+
+use uefi::proto::console::text::Output;
 use uefi::table::boot::{BootServices, EventType, TimerTrigger, Tpl};
 use uefi::{prelude::*, Event};
 
@@ -6,26 +10,55 @@ pub fn test(bt: &BootServices) {
     test_timer(bt);
     info!("Testing events...");
     test_event_callback(bt);
+    test_callback_with_ctx(bt);
     info!("Testing watchdog...");
     test_watchdog(bt);
 }
 
 fn test_timer(bt: &BootServices) {
-    let timer_event = unsafe { bt.create_event(EventType::TIMER, Tpl::APPLICATION, None) }
+    let timer_event = unsafe { bt.create_event(EventType::TIMER, Tpl::APPLICATION, None, None) }
         .expect_success("Failed to create TIMER event");
-    let mut events = [timer_event];
-    bt.set_timer(timer_event, TimerTrigger::Relative(5_0 /*00 ns */))
+    let mut events = unsafe { [timer_event.unsafe_clone()] };
+    bt.set_timer(&timer_event, TimerTrigger::Relative(5_0 /*00 ns */))
         .expect_success("Failed to set timer");
     bt.wait_for_event(&mut events)
         .expect_success("Wait for event failed");
 }
 
 fn test_event_callback(bt: &BootServices) {
-    fn callback(_event: Event) {
+    extern "efiapi" fn callback(_event: Event, _ctx: Option<NonNull<c_void>>) {
         info!("Inside the event callback");
     }
-    let event = unsafe { bt.create_event(EventType::NOTIFY_WAIT, Tpl::CALLBACK, Some(callback)) }
-        .expect_success("Failed to create custom event");
+
+    let event =
+        unsafe { bt.create_event(EventType::NOTIFY_WAIT, Tpl::CALLBACK, Some(callback), None) }
+            .expect_success("Failed to create custom event");
+    bt.check_event(event)
+        .expect_success("Failed to check event");
+}
+
+fn test_callback_with_ctx(bt: &BootServices) {
+    extern "efiapi" fn callback(_event: Event, ctx: Option<NonNull<c_void>>) {
+        info!("Inside the event callback with context");
+        unsafe {
+            let ctx = &mut *(ctx.unwrap().as_ptr() as *mut Output);
+            // Clear the screen as a quick test that we successfully passed context
+            ctx.clear().expect_success("Failed to clear screen");
+        }
+    }
+
+    let ctx = unsafe { &mut *(bt.locate_protocol::<Output>().unwrap().unwrap().get()) };
+
+    let event = unsafe {
+        bt.create_event(
+            EventType::NOTIFY_WAIT,
+            Tpl::CALLBACK,
+            Some(callback),
+            Some(NonNull::new_unchecked(ctx as *mut _ as *mut c_void)),
+        )
+        .expect_success("Failed to create event with context")
+    };
+
     bt.check_event(event)
         .expect_success("Failed to check event");
 }