EFI-BIOS之Handler.doc

UEFI Spec 探讨----------- Handler&Protocol
1. UEFI Firmware Core OverView
首先再来回顾一下UEFI架构: UEFI整个系统以UEFI firmware core(kernel)为核心，在firmware core基础上可以编写platform driver/application,然后通过firmware services加载运行.
总的来看，UEFI firmware core主要功能包括:
1) Kernel Service Routines
提供EFI_SYSTEM_TABLE , 包含kernel services. 即boot services和runtime services
2) Image Management
a.通过Boot Services->LoadImage可以load其它driver/application的image,并生成ImageHandler, (关于ImageHandle, 第一个ImageHandle就是EFI firmware本身,即EfiCoreImageHandle)
b.通过boot services->StartImage运行driver/application的EntryPoint.并传入两个参数
如: 参看SBDxe.c
EFI_STATUS SBDXE_Init(
IN EFI_HANDLE ImageHandle,
IN EFI_SYSTEM_TABLE *SystemTable
)
通过SystemTable就可以调用Service了。
3) Driver Model/Protocol
对bus/device提供Driver Model/Protocol的管理机制
4) Event
参看UEFI Spec探讨之2 Event.doc
5) Boot Management

以下我们简单探讨下Device Handler，重点学习一下Protocol相关的资料：

2．UEFI Driver Model / Device Handler
Driver Model机制
1． Driver Image的load:
调用firmware core的LoadImage()/StartImage()，同时也将生成一个ImageHandle，而且firmware core将为这个ImageHandle安装好一个EFI_LOADED_IMAGE_PROTOCOL,并执行DriverImage Entry.
一般DriverImage Entry并不touch hardware. 只在ImageHandle上安装Driver Binding Protocol等Protocols. 只有当调用firmware core的ConnectController() service连接到一个Controller或Device时才会运行EFI_DRIVER_BINDING_PROTOCOL.Start()去管理Controller.
2． Driver Binding Protocl
最典型的是PCI Driver. 例如:
EFI_DRIVER_BINDING_PROTOCOL gPciBusDriverBinding = {
PciBusSupported, //Supported
PciBusStart, //PciBusDrvStart,
PciBusStop, //PciBusDrvStop,
((PCI_BUS_MAJOR_VER<<16)|(PCI_BUS_MINOR_VER<<8)|(PCI_BUS_REVISION)), //Version
NULL, //Image Handle
NULL //DriverBindingHandle
};
我们在POST PciBusEntryPoint时会Install 这个PciBusDriver,
在BDS阶段才Connect并运行PciBusStart会去Scan all PCI, 分配resource, 做PCI device的Initial等等.
3． Host Bus Controller
UEFI把整个Platform System看成一个由CPU+Core Chipsets延伸开来的树状体系。
每个core chipset为系统构建一个I/O Bus资源. UEFI driver model就是描述和管理各个I/O buses的. Core I/O Bus下面可能再连接其他的Bus,或者是devices.
如图:

Firmware core负责Initial Host Bus Controller,分派device handle.
4． controller的bus drivers将负责enumerate all devices. 为device创建child device handles, 并安装相应的bus protocols, firmware core将再调用ConnectController()为device联接合适的device driver.
Connect将call Drivers Binding Protocol的started() routine, 为device安装protocols.
举个例子:
Chapter 2.5.4 (Figure 12)

上面的PCI Host Bus Controller的例子：
首先PCI Host Bus Controller包含几个PCI Root Bridge, PCI root bridge通过PCI Root Bridge I/O protocol描述。在UEFI Driver model中, Root Bridge看成是一个device,被分派device handle加以管理. 一个PCI Bus Driver就可以被连接到root bridge中.Bus driver提供访问bus的protocol,并scan pci devices创建child device handles, 再连接相应的Device Driver. Device Driver中提供访问Device的Protocol.(device driver不再create new device handle.)

3．Protocol Handler Services
Protocols是建立在device handle或者Image handle上的,提供一些functions或者信息。
(handle是由firmware core分配的，比如Image handle，当firmware core通过LoadImage load一个image时，将分配一个Image handel,
device handle是firmware core给device设备分配的handle.
所有的handle组成系统handle database. 在这些handle上可以安装Protocol等)
(关于device handle更详细的讨论，请看UEFI Spec探讨之4 DriverModel.doc)
我们可以把Protocols看成是各Image/Driver提供的一些Services. 可以在需要的时候进行调用.
如图:

下面详细探讨:
1). Protocol Interface Structure
2). Protocol Install
3). Protocol Invoke

1)Protocols Interface Structer
一个Protocols Interface的组成包括:
i. Protocol GUID
ii. Protocol Interface structure
iii. Protocol services
2). Protocol Install
通过调用firmware core boot services:
InstallProtocolInterface()
或者
InstallMultipleProtocolInterfaces()
安装Protocol到handle上.

3). Protocol Invoke
通过调用firmware core boot services:
OpenProtocol
HandleProtocol
LocateProtocol
查找返回Protocol, 以便调用.

******************************************************************************
下面详细讲解和Protocols相关的boot service
(参看UEFI Spec. chapter 6.3: Protocol Handler Services)
.InstallProtocolInterface()
我们知道了Protocol Interface是安装在Device Handle或Image Handle上的。
UEFI Spec建议使用InstallMultipleProtocolInterfaces()替代。
typedef EFI_STATUS InstallProtocolInterface(
IN OUT EFI_HANDLE *Handle,
IN EFI_GUID *ProtocolGUID,
IN EFI_INTERFACE_TYPE InterfaceType,
IN VOID *Interface
);
参数说明:
*Handle: 在device handle上安装一个Protocols Interface.
如果参数Handle为NULL，将在系统handle lists中添加创建一个handle.
*ProtocolGUID: ProtocolGUID
InterfaceType： EFI_NATIVE_INTERFACE
*Interface： 指针指向Interface Structure.
例如:
#define CSM_PLATFORM_PROTOCOL_GUID \
{0x91fa9dfd,0xdbd4,0x44ae,0x97,0xa4,0xbd,0x18,0x37,0xd5,0xb4,0x62}

GUID_VARIABLE_DECLARATION(gCsmPlatformProtocolGuid,CSM_PLATFORM_PROTOCOL_GUID);

CSM_PLATFORM_PROTOCOL CsmPlatformProtocol =
{ CsmPlatform_PreProcessOpRom,
CsmPlatform_PostProcessOpRom,
CsmPlatform_GetAtapiDeviceType
};
EFI_STATUS InstallCsmPlatformProtocol()
{
EFI_HANDLE Handle = 0;

return pBS->InstallProtocolInterface (
&Handle, &gCsmPlatformProtocolGuid,
EFI_NATIVE_INTERFACE, &CsmPlatformProtocol
);
}

注: 特别要注意的是, 当一个Protocol Interface被Install时，将notify 所有已经注册的callback function.
即通过RegisterProtocolNotify()传入ProtocolInterface GUID注册的callback event. 后面会讲到具体这个Notify.

.RegisterProtocolNotify()
Register一个Event, 以便当一个ProtocolInterface被Install时运行该Event.
typedef EFI_STATUS RegisterProtocolNotify(
IN EFI_GUID *Protocol,
IN EFI_EVENT Event,
OUT VOID **Registration
);
参数说明:
*Protocol: Protocol GUID, 向该Protocol Register一个Event,当该Protocol被Install时，将触发Event的运行.
Event: 要Register的Event. 一般可通过CreateEvent()创建.
**Registration: 返回Registeration Value.

实例：参看CRBDXE_Init
Status = pBS->LocateProtocol(
&gAmiNbProtocolGuid,
NULL,
&gNbProtocol);
if (EFI_ERROR(Status))
{
Status = pBS->CreateEvent(
EVT_NOTIFY_SIGNAL,
TPL_NOTIFY,
CRBNbCallback, //;Create Event
NULL,
&Event);
if (!EFI_ERROR(Status))
{
Status = pBS->RegisterProtocolNotify(&gAmiNbProtocolGuid, Event, &gNbNotifyReg);
ASSERT_EFI_ERROR(Status);
}
}
这样当gAmiNbProtocolGuid被Installed的时候，将signal这个CRBNbCallback这个Event Function.

.UninstallProtocolInterface()
从一个device handle上uninstall一个protocol.
UEFI Spec建议用UninstallMultipleProtocolInterfaces()取代
typedef EFI_STATUS UninstallProtocolInterface(
IN EFI_HANDLE Handel,
IN EFI_GUID *Protocol,
IN VOID *Interface
);
参数说明:
Handle: handle
*Protocol: 要uninstall的Protocol GUID
*Interface: 要uninstall的Protocol Interface.

实例：OemDxe.c
VOID SignalProtocolEvent(IN EFI_GUID *ProtocolGuid, IN VOID *Interface){
EFI_HANDLE Handle = NULL;
pBS->InstallProtocolInterface (
&Handle, ProtocolGuid, EFI_NATIVE_INTERFACE, Interface
);
pBS->UninstallProtocolInterface (
Handle, ProtocolGuid, Interface
);
}
注:
1. Caller自己负责其它driver不再需要调用该Uninstall的Protocol，否则可能出现问题。
2. (EFI 1.10 extension) 可能遇到要Uninstall的Protocol正在被其他driver使用的情形.

.ReinstallProtocolInterface()
在一个device handle上用新的protocol替换掉旧的protocol.
typedef EFI_STATUS ReinstallProtocolInterface(
IN EFI_HANDLE Handle,
IN EFI_GUID *Protocol,
IN VOID *OldInterface,
IN VOID *NewInterface
);
参数说明:
注:
1. ReinstallProtocolInterface()实际上会先调用UninstallProtocolInterface()旧的Protocol,
然后再调用InstallProtocolInterface(),最后将调用ConnectController().
2. (EFI 1.10 extension) 可能遇到要Reinstall的Protocol正在被其他driver使用的情形.

.HandleProtocol()
查询某个Handle是否支持某个Protocol, 如果支持，返回Protocol Interface.
typedef EFI_STATUS HandleProtocol(
IN EFI_HANDLE Handle,
IN EFI_GUID *Protocol,
OUT VOID **Interface
);
参数说明:
Handle:
*Protocol: Protocol GUID
**Interface: 如果成功,返回Protocol Interface
注:
(EFI 1.10 Extension) 在新的EFI中, 使用OpenProtocol()代替，定义为:
EFI_STATUS HandleProtocol(
IN EFI_HANDLE Handle,
IN EFI_GUID *Protocol,
OUT VOID **Interface
)
{
return OpenProtocol(
Handle,
Protocol,
Interface,
EfiCoreImageHandle,
NULL,
EFI_OPEN_PROTOCOL_BY_HANDLE_SUPPORT
);

.LocateHandle()
查找支持某Protocol的handles list. 返回指向handles list buffer的指针
typedef EFI_STATUS LocateHandle(
IN EFI_LOCATE_SEARCH_TYPE SearchType;
IN EFI_GUID *Protocol OPTIONAL,
IN VOID *SearchKey OPTIONAL,
IN OUT UINTN *BufferSize,
OUT EFI_HANDLE *Buffer
);
参数说明:
SearchType: AllHandles/ByRegisterNotify/ByProtocol
*Protocol OPTIONAL:
*SearchKey OPTIONAL:
------------------------------------------------------------------------------
SearchType *Protocol OPTIONAL *SearchKey OPTIONAL
------------------------------------------------------------------------------
AllHandles null null
ByRegisterNotify null 根据SearchKey(即RegisterProtocolNotify()返回的Registration查找)
ByProtocol 根据Protocol指定的GUID来找 null

.LocateProtocol()
根据ProtocolGUI查找Protocol,它返回第一个被找到的Protocol, 返回Protocol Interface指针.
typedef EFI_STATUS LocateProtocol(
IN EFI_GUID *ProtocolGUID,
IN VOID *Registration OPTIONAL,
OUT VOID **Interface
);
参数说明:
*ProtocolGUID:
*Registration: OPTIONAL, 从RegisterProtocolNotify()返回的registration key,提供这个参数是为专门给有RegisterNotify的event.
例如:
//
// Execute platform pre-OpROM function
//
pBS->LocateProtocol(&gCsmPlatformProtocolGuid, NULL, &CsmPlatformProtocol);

if (CsmPlatformProtocol) {
Status = CsmPlatformProtocol->PreProcessOpRom(CsmPlatformProtocol, PciIo, RomImage);
if (EFI_ERROR(Status)) {
CsmPlatformProtocol->PostProcessOpRom(CsmPlatformProtocol, PciIo, RomImage);
return Status;
}
}

上面在UninstallProtocolInterface()中提到过，可能遇到要Uninstall的Protocol正在被其他driver使用的情形.特别是在DriverModel机制中使用Protocol. 所以新的UEFI boot services增加了Protocol使用者Agent机制。
即在安装好的Protocol上，增加了Agents list. 这个实现是通过使用者在使用某个Protocol时调用新的UEFI Boot
Services: OpenProtocol(). 该BootService将在调用成功后在Protocol Interface上增加一个Agent Information.
参看: 6.3 Figure 17 与 Figure 18 所示
Figure 18: 增加了Agent.

一个Agent包括Image Handle, Controller Handle, Attributes三个元素。
ImageHandle是driver image handle.
ControllerHandle是打开该Protocol的Controller/Device handle. 因为一个driver可能管理多个Controller/Devices
Attribute是其他的一些信息，详细看OpenProtocol().

.OpenProtocol()
这是HandleProtocol的扩展，比HandleProtocol增加了Agent功能.
typedef EFI_STATUS (EFIAPI *EFI_OPEN_PROTOCOL) OpenProtocol(
IN EFI_HANDLE Handel,
IN EFI_GUID *Protocol,
OUT VOID **Interface OPTIONAL,
IN EFI_HANDLE AgentHandle,
IN EFI_HANDLE ControllerHandle,
IN UINT32 Attributes
);
参数说明:
Handle:
*Protocol: Protocol GUID
**Interface: 如果成功，返回Protocol Interface.
AgentHandle: 即使用该Protocol的driver image handle, 或者是application image handle
ControllerHandle: 即使用该Protocol的Controller handle
Attributes: OpenMode:
BY_HANDLE_PROTOCOL
GET_PROTOCOL
TEST_PROTOCOL
BY_CHILD_CONTROLLER
BY_DRIVER
EXCLUSIVE
后面三个参数AgentHandle,ControllerHandle,Attributes主要是为了增加一个Agent,
当OpenProtocol()调用成功，将在该Protocol的当前使用者list中增加AgentHandle, ControllerHandel, Attributes这
三个信息，表示该Protocol正在被使用，防止不安全的Uninstall和ReInstall.
同样CloseProtocol()将把正在使用该Protocol的Handle从Protocol当前使用者list中删除.

.CloseProtocol()
Close一个Protocol的使用者. 因为新的OpenProtocol()为Protocol增加了一个当前正在使用该Protocol的使用者list.
CloseProtocol()将关闭一个使用者信息，表示该使用者不再使用该Protocol了. 见OpenProtocol().
typedef EFI_STATUS (EFIAPI *EFI_CLOSE_PROTOCOL) CloseProtocol(
IN EFI_HANDLE Handel,
IN EFI_GUID *Protocol,
IN EFI_HANDLE AgentHandle,
IN EFI_HANDLE ControllerHandle
);
参数说明:
Handle: 之前被OpenProtocol()的Handle.
*Protocol: Protocol GUID
AgentHandle:
ControllerHandle:

.OpenProtocolInformation()
返回Protocol的Agents information
typedef EFI_STATUS (EFIAPI *EFI_OPEN_PROTOCOL_INFORMATION)
OpenProtocolInformation(
IN EFI_HANDLE Handle,
IN EFI_GUID *Protocol,
OUT EFI_OPEN_PROTOCOL_INFORMATION_ENTRY **EntryBuffer,
OUT UINTN *EntryCount
);
参数说明:
Handle: 要查询的哪个Handle上的Protocol
*Protocol: Protocol GUID
**EntryBuffer: 返回EFI_OPEN_PROTOCOL_INFORMATION_ENTRY结构的数据
*EntryCount: 返回Agent个数.

.InstallMultipleProtocolInterfaces()
在一个Handle上同时安装几个Protocol
typedef EFI_STATUS InstallMultipleProtocolInterfaces(
IN OUT EFI_HANDLE *Handle,
IN EFI_GUID *ProtocolGUID,
IN VOID *Interface
...
);

.UninstallMultipleProtocolInterfaces()
在一个Handle上卸载几个Protocol
typedef EFI_STATUS InstallMultipleProtocolInterfaces(
IN OUT EFI_HANDLE *Handle,
IN EFI_GUID *ProtocolGUID,
IN VOID *Interface
...
);