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");
 }