EFI基本概念之Event

1 基本概念及函数

    最近在帮公司弄一个ALPHA架构的EFI BIOS，在调DXE_CORE的时候，发现必须要装几个CPU架构相关的协议。如果这几个协议不去安装，代码就不会执行BDS阶段。代码侦测协议有没有安装，是通过CoreRegisterProtocolNotify()函数实现的，这个函数在未安装协议之前，便先建立PROTOCOL_ENTRY变量，然后将其链接到mProtocolDatabase链表中，并将已经有的Event链接到自己的Notify链表中。等到代码真正安装Protocol实例后，这个Event便会被调用，代码有Event NotifyFunction中便知道某个CPU架构类协议有没有建立起来。开始时代码中没加装载这几个协议的驱动，所以代码跑不到BDS阶段，只是打印出架构协议未安装的调试信息。这个设计很巧妙，也展现了EFIEvent强大的一角。

    新闻联播上总是说，北京时间XX点，发生了XX事件。这句话有两个重点，时间和事情。EFI的Event同样也有这两个特性：一，Event是个可发生（执行）的函数；二，Event需要在某个时间点发生。在EFI里，实现第一个特性是用CreateEvent()或CreateEventEx()，实现第二个特性需要使用SignalEvent()。Event除了这几个函数外，也包括关闭事件函数CloseEvent(),等待事件函数WaitForEvent(),检查事件函数CheckEvent()。下面分别介绍一下他们的基本用法。

1.1 创建事件

EFI_STATUS

EFIAPI

CoreCreateEvent (

  IN UINT32                   Type,

  IN EFI_TPL                  NotifyTpl,

  INEFI_EVENT_NOTIFY         NotifyFunction,OPTIONAL

  IN VOID                     *NotifyContext, OPTIONAL

  OUTEFI_EVENT               *Event

  )

这个函数创建了一个Type类别的，NotifyTpl级别的，拥有NotifyFunction函数的Event事件。NotifyFunction是可选的，如果NotifyTpl拥有EVT_NOTIFY_SIGNAL或EVT_NOTIFY_WAIT级别，则其作为有效参数被使用。

 

EFI_STATUS

EFIAPI

CoreCreateEventEx (

  IN UINT32                   Type,

  IN EFI_TPL                  NotifyTpl,

  INEFI_EVENT_NOTIFY         NotifyFunction,OPTIONAL

  IN CONSTVOID               *NotifyContext,OPTIONAL

  IN CONSTEFI_GUID           *EventGroup,    OPTIONAL

  OUTEFI_EVENT               *Event

  )

    此函数比CreateEvent()多了一个EventGroup函数，与CreateEvent创造的事件不同的是，BootServcies函数无法单独触发。

 

1.2 销毁事件

EFI_STATUS

EFIAPI

CoreCloseEvent (

  IN EFI_EVENT    UserEvent

  )

    此函数将UserEvent销毁，从链表中摘除，并释放占有的内存空间。

 

1.3 触发事件

EFI_STATUS

EFIAPI

CoreSignalEvent (

  IN EFI_EVENT    UserEvent

  )

    触发UserEvent事件。

 

1.4 等待事件

EFI_STATUS

EFIAPI

CoreWaitForEvent (

  IN UINTN        NumberOfEvents,

  IN EFI_EVENT    *UserEvents,

  OUT UINTN       *UserIndex

  )

    此函数停止当前的任务，等待NumberOfEvents个事件发生，若其中一个事件发生，则退出并反馈给用户这个信息：第userIndex个事件发生了。

 

1.5 检查事件

EFI_STATUS

EFIAPI

CoreCheckEvent (

  IN EFI_EVENT        UserEvent

  )

    此函数检查UserEvent的现在状态。

 

1.6 其它事件相关函数

1.6.1 CoreSetTimer()

    为Timer事件设置类型和触发时间，Timer那一章介绍过了，此处略过。

1.6.2 CoreRaiseTpl ()

    为当前任务升权。

1.6.3 CoreRestoreTpl ()

    恢复任务权限级别，所有Event级别比新的任务权限级别高的，都会得到执行。

 

 

2 Event相关结构

2.1 Event真身

typedef struct {

  UINTN                   Signature;

  UINT32                  Type;

  UINT32                  SignalCount;

  LIST_ENTRY              SignalLink;

  EFI_TPL                 NotifyTpl;

 EFI_EVENT_NOTIFY       NotifyFunction;

  VOID                    *NotifyContext;

  EFI_GUID                EventGroup;

  LIST_ENTRY              NotifyLink;

  BOOLEAN                 ExFlag;

 EFI_RUNTIME_EVENT_ENTRY RuntimeData;

 TIMER_EVENT_INFO        Timer;

} IEVENT;

    CreateEvent()函数最后一个参数是输出参数EVENT，它的真身就是IEVENT结构体。其它输入参数，都被赋于了这个结构体的成员。

 

2.2 gEfiCurrentTpl

    当前任务级别。可以将其看为Legacy BIOS中的当前中断优先级。

 

2.3 gEventQueue[]

    一个专门链接处于触发态的事件的双向链表，其有32个元素，当前只用了4个。分别是: TPL_APPLICATION,TPL_CALLBACK,TPL_NOTIFY,TPL_HIGH_LEVEL。

    Event事件被SignalEvent()后，便会将其塞入到gEventQueue[Event-> NotifyTpl]链表里。当CoreRestoreTpl()函数执行时，如果Event-> NotifyTpl大于恢复后的任务权限级别，gEventQueue [Event-> NotifyTpl]所链接的所有Event都会被执行，执行完后，Event从gEventQueue [Event-> NotifyTpl]中移除。

 

2.4 gEventPending

    该全局变量为一指示型变量。其每一位指示gEventQueue[]的每一个元素是否链接有相应的Event，若有则为1，没有值为0。因其类型为UINTN，但是gEvent[]的元素有32个。所以如果某一类型CPU的数据宽度小于32位，我们要强制将其类型设为大于或等于32位的。

 

2.5 gEventSignalQueue

    这是一个双向链表。当我们创造一个EVENT时，要将EVENT链入该链表中。当CloseEvent()时，从该链表中移除。

 

2.6 mEventTable[]

    有效的Event类型。EVENT类型不在此数组元素内，创建EVENT时不会成功。

（完，附上一张EVENT相关结构图，是2014年，小明刚学BIOS时，画的一张图。RuntimeData的直接忽略吧，毕竟代码还未支持，而且也没有支持的必要）