UEFI原理与编程（九）：UEFI中的Protocol使用方法

大家好，欢迎来到IT知识分享网。

UEFI中的Protocol使用方法

前言

　　启动服务提供了丰富的服务供开发者操作Protocol，我们可以使用Protocol也可以开发Protocol。本文主要介绍如何使用Protocol。
　　使用Protocol一般分为下面三个步骤：
　　　　1. 通过启动服务找出Protocol对象；
　　　　2. 使用这个Protocol提供的服务；
　　　　3. 关闭打开的Protocol
　　可以使用OpenProtocolInformation服务查看打开某个Protocol的所有设备。
　　启动服务，有四种，分别为：OpenProtocol、HandleProtocol、LocateProtocol和LocalHandleBuffer。下面分别介绍它们。

一、OpenProtocol 服务

typedef EFI_STATUS (EFIAPI *EFI_OPEN_PROTOCOL) ( IN EFI_HANDLE Handle, IN EFI_GUID *Protocol, OUT VOID Interface , OPTIONAL IN EFI_HANDLE AgentHandle, IN EFI_HANDLE ControllerHandle, IN UINT32 Attributes );

返回值：

• Handle：查询次Handle提供的Protocol
• *Protocol：要打开的Protocol（指向次Protocol GUID的指针）
• Interface：返回打开的Protocol的对象
• AgentHandle：打开此Protocol的Image
• ControllerHandle：打开此Protocol的控制器
• Attributes：打开此Protocol的方式

  　　Handle是Protocol的提供者，如果Handle的Protocols链表中有该Protocol，则Protocol对象的指针写到*Interface，并返回EFI_SUCCESS，否则返回EFI_UNSUPPORTED。
  　　如果在驱动中调用OpenProtocol，则ControllerHandle是拥有该驱动的控制器，也就是请求使用这个Protocol的控制器；AgentHandle是拥有该EFI_DRIVER_BINDING_PROTOCOL对象的Handle。EFI_DRIVER_BINDING_PROTOCOL是UEFI驱动开发一定会用到的一个Protocol，它负责驱动的安装与卸载。
  　　如果调用OpenProtocol的是应用程序，那么AgentHandle是该用用程序的Handle，也就是UefiMain的第一个参数，ControllerHandle此时可以忽略。
  　　Attribute值列表：
  　
  注：截图来源于UEFI Spec 2_6。关于这部分可以查阅UEFI Spec。

OpenHandle示例程序片断：

/// 打开BlockIo EFI_HANDLE ImageHandle; EFI_DRIVER_BINDING_PROTOCOL *This; IN EFI_HADNLE ControllerHandle； extern EFI_GUID BlockIoProtocolGuid; EFI_BLOCK_IO_PROTOCOL *BlockIo; EFI_STATUS Status; //在应用程序中使用OpenProtocol，一般ControllerHandle会设为NULL Status = gBS->OpenProtocol( ControllerHandle, //Handle &gEfiBlockIoProtocolGuid, //Protocol &BlockIo, //Interface ImageHandle, //AgentHandle NULL, //ControllerHandle EFI_OPEN_PROTOCOL_BY_HANDLE_PROTOCOL //Attribute ) //在驱动中使用，OpenProtocol， ControllerHandle是控制器的Handle Status = gBS->OpenProtocol( ControllerHandle, //Handle &gEfiBlockIoProtocolGuid, //Protocol &BlockIo, //Interface This->DriverBindingHandle, //AgentHandle ControllerHandle, //ControllerHandle EFI_OPEN_PROTOCOL_GET_PROTOCOL //Attribute )

gEfiBlockIoProtocolGuid 是全局变量，变量定义在AutoGen.c 中。AutoGen.c 是由build工具根据 .inf 和 .dec 文件生成的，gEfiBlockIoProtocolGuid是EFI_GUID类型的变量，其EFI_GUID值定义在 .dec中。如果要在应用程序或驱动中使用gEfiBlockIoProtocolGuid，那么必须在 .inf 文件的[Protocols]中声明以便预处理时将其包含在AutoGen.c中。

二、HandleProtocol 服务

typedef EFI_STATUS (EFIAPI *EFI_HANDLE_PROTOCOL) ( IN EFI_HANDLE Handle, IN EFI_GUID *Protocol, OUT VOID Interface );

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

HandleProtocol使用示例：

Status = gBS->HandleProtocol( ControllerHandle, //Handle &gEfiBlockIoProtocolGuid, //Protocol &BlockIo, //Interface  )

三、LocateProtocol 服务

typedef EFI_STATUS (EFIAPI *EFI_LOCATE_PROTOCOL) ( IN EFI_GUID *Protocol, IN VOID *Registration，OPTIONAL OUT VOID Interface );

EFI_SIMPLE_FILE_SYSTE_PROTOCOL* SimpleFs; gBS->LocateProtocol( gEfiSimpleFileSystemProtocolGuid, NULL, &SimpleFs );

四、LocateProtocolBuffer服务

typedef EFI_STATUS (EFIAPI *EFI_LOCATE_HANDLE_BUFFER) ( IN EFI_LOCATE_SEARCH_TYPE SearchType, //查找方式 IN EFI_GUID *Protocol OPTIONAL, //指定的Protocol IN VOID *SearchKey OPTIONAL, //PROTOCOL_NOTIFY的类型 IN OUT UINTN *NoHandles, //返回找到的HANDLE数量 OUT EFI_HANDLE Buffer //分配Handle数组并返回 );

typedef enum{ AllHandles, ByRegisterNotify, ByProtocol } EFI_LOCATE_SEARCH_TYPE;

LocateHandle服务函数原型：

typedef EFI_STATUS (EFIAPI *EFI_LOCATE_HANDLE) ( IN EFI_LOCATE_SEARCH_TYPE SearchType, IN EFI_GUID *Protocol OPTIONAL, IN VOID *SearchKey OPTIONAL, IN OUT UINTN *BufferSize, OUT EFI_HANDLE *Buffer );

　　LocateHandle服务与LocateHandleBuffer服务最大的不同是需要调用者负责管理Buffer数组占用的内存。

五、其它Protocol 服务

　　除了Protocol和根据Protocol找出设备这些常用服务，启动服务关于使用Protocol的服务还有ProtocolsPerHandle和OpenProtocolInformation。

1. ProtocolsPerHandle

　　ProtocolsPerHandle用于获取指定设备所支持的所有Protocol。这些Protocol的GUID通过ProtocolBuffer返回给调用者，UEFI负责分配内存给ProtocolBuffer，调动者负责释放该内存。
　　
　　ProtocolsPerHandle函数原型：

typedef EFI_STATUS (EFIAPI *EFI_PROTOCOLS_PER_HANDLE) ( IN EFI_HANDLE Handle, OUT EFI_GUID *ProtocolBuffer, OUT UINTN *ProtocolBufferCount );

2. OpenProtocolInformation

　　OpenProtocolInformation用于获得指定设备上指定Protocol的打开信息。

　　OpenProtocolInformation函数原型：

typedef EFI_STATUS (EFIAPI *EFI_OPEN_PROTOCOL_INFORMATION) ( IN EFI_HANDLE Handle, IN EFI_GUID *Protocol, OUT EFI_OPEN_PROTOCOL_INFORMATION_ENTRY EntryBuffer, OUT UINTN *EntryCount ); 

//EFI_OPEN_PROTOCOL_INFORMATION_ENTRY数据结构 typedef struct { EFI_HANDLE AgentHandle; EFI_HANDLE ControllerHandle; UINT32 Attributes; UINT32 OpenCount; } EFI_OPEN_PROTOCOL_INFORMATION_ENTRY;

　　Ｈandle是这个设备的句柄，打开的信息存放在PROTOCOL_INTERDACE的OpenList列表中。设备上的同一Protocol可能被打开和关闭很多次。Protocol每一次被成功打开和关闭后都会更新OpenList列表。成功打开后，都会在设备句柄上添加一项EFI_OPEN_PROTOCOL_INFORMATION_ENTRY，若OpenList列表中已经存在一项与当前的（AgentHandle，ControllerHandle，Attributes）完全相同，则该项OpenCount加一。关闭Protocol则将OpenList对应项的OpenCount减一，OpenCount为零时删除对应项。

六、CloseProtocol 服务

typedef EFI_STATUS (EFIAPI *EFI_CLOSE_PROTOCOL) ( IN EFI_HANDLE Handle, IN EFI_GUID *Protocol, IN EFI_HANDLE AgentHandle, IN EFI_HANDLE ControllerHandle );

　　通过HandleProtocol和LocateProtocol打开的Protocol因为没有指定AgentHandle，所以无法关闭。如果一定要关闭它，则要调用OpenProtocolInformation（）获得AgentHandle和ControllerHandle，然后再关闭它。

七、总结

　　本部分，不住要讲解了Protocol的使用方法。Protocol提供了一种在UEFI应用程序以及UEFI驱动之间的通信方式。通过Protocol，用户可以使用驱动提供的服务，以及系统提供的其他服务。要熟悉自己使用的Protocol的数据结构。

参考资料

1. 《UEFI原理与编程》
2. UEFI Spec 2_6
3. EDK2 GitHub