BIOS知识枝桠——常用functions查阅

只提供最基础的参数描述以及函数作用，尚在不断完善，详细还需参阅SPEC
EFI_BOOT_SERVICES.AllocatePages()
AllocatePages()函数分配请求的页面数量，并返回一个指向内存所引用位置中页面范围的基址的指针。该函数扫描内存映射以定位空闲页。当它找到一个物理上连续的、足够大且满足Type分配要求的页块时，它会更改内存映射，以指示页现在是MemoryType类型。
一般来说，UEFI OS加载器和UEFI应用程序应该分配EfiLoaderData类型的内存(和内存池)。UEFI引导服务驱动必须分配EfiBootServicesData类型的内存(和内存池)。UREFI运行时驱动程序应该分配EfiRuntimeServicesData类型的内存(和内存池)(尽管这种分配只能在启动服务期间进行)。
类型为AllocateAnyPages的分配请求分配满足请求的任何可用页面范围。在输入时，内存指向的地址将被忽略。

typedef
EFI_STATUS
(EFIAPI *EFI_ALLOCATE_PAGES) (
IN EFI_ALLOCATE_TYPE          Type,//要执行的分配类型。
IN EFI_MEMORY_TYPE            MemoryType,
IN UINTN                      Pages,
IN OUT EFI_PHYSICAL_ADDRESS  *Memory
);

typedef enum {
AllocateAnyPages,
AllocateMaxAddress,
AllocateAddress,
MaxAllocateType
 } EFI_ALLOCATE_TYPE;

EFI_BOOT_SERVICES.FreePages()
函数的作用是:返回AllocatePages()分配给固件的内存。

typedef
EFI_STATUS
(EFIAPI *EFI_FREE_PAGES) (
IN EFI_PHYSICAL_ADDRESS      Memory,//要释放的页的基本物理地址。类型EFI_PHYSICAL_ADDRESS在EFI_BOOT_SERVICES.AllocatePages()描述中定义
IN UINTN                     Pages//要释放的连续4个KiB页的数目。
);

EFI_BOOT_SERVICES.AllocatePool()
AllocatePool()函数从PoolType类型的内存中分配一个Size字节的内存区域，并返回Buffer引用的位置中已分配内存的地址。这个函数根据需要从EfiConventionalMemory中分配页面，以增加请求的池类型。所有分配都是8字节对齐的。通过EFI_BOOT_SERVICES.FreePool()函数将分配的池内存返回给可用的池

typedef
EFI_STATUS
(EFIAPI *EFI_ALLOCATE_POOL) (
 IN EFI_MEMORY_TYPE      PoolType,//要分配的池类型。0x7FFFFFFF 预留给OEM使用。0xFFFFFFFF预留给操作系统厂商提供的UEFI OS加载器使用。
 IN UINTN                Size,//要从池中分配的字节数。
 OUT VOID                **Buffer//如果调用成功，则指向指向已分配缓冲区的指针;否则为未定义的。
 );

EFI_BOOT_SERVICES.FreePool()
函数的作用是:将Buffer指定的内存返回给系统。在返回时，内存的类型是 EfiConventionalMemory.。被释放的Buffer必须是由AllocatePool()分配的。

typedef
EFI_STATUS
(EFIAPI *EFI_FREE_POOL) (
IN VOID    *Buffer//指向要释放缓冲区的指针。
)

EFI_BOOT_SERVICES.InstallProtocolInterface()
在设备句柄上安装协议接口。如果句柄不存在，它将被创建并添加到系统的句柄列表中。InstallProtocolInterface()函数在一个设备句柄上安装一个协议接口(GUID/协议接口结构对)。同一个GUID不能在同一个句柄上安装多次。如果试图在句柄上安装重复的GUID，将会产生一个EFI_INVALID_PARAMETER。安装协议接口可以让其他组件找到Handle和安装在它上的接口

typedef
EFI_STATUS
(EFIAPI *EFI_INSTALL_PROTOCOL_INTERFACE) (
 IN OUT EFI_HANDLE      *Handle,//一个指向要安装接口的EFI_HANDLE的指针。如果*Handle在输入时为NULL，则在输出时创建一个新的句柄并返回。如果*Handle在输入时不为NULL，则将协议添加到句柄中，并不修改返回句柄。如果*Handle不是有效句柄，则返回EFI_INVALID_PARAMETER
 IN EFI_GUID            *Protocol,//协议接口的数字ID。类型EFI_GUID在相关定义中定义。传递一个有效的GUID是调用者的责任。
 IN EFI_INTERFACE_TYPE  InterfaceType,//指示Interface是否以本机形式提供。该值指示请求的原始执行环境。
 IN VOID                *Interface//一个指向协议接口的指针。接口必须遵循协议定义的结构。如果一个结构与协议没有关联，可以使用NULL
 );

EFI_BOOT_SERVICES.LocateProtocol()
返回与给定协议匹配的第一个协议实例，LocateProtocol()函数查找第一个支持协议的设备句柄，并在interface中从该句柄返回一个指向协议接口的指针。如果没有找到协议实例，则将Interface设置为NULL。
如果Interface为NULL，则返回EFI_INVALID_PARAMETER。
Protocol为NULL则返回EFI_INVALID_PARAMETER。
如果Registration为NULL，并且句柄数据库中没有支持Protocol的句柄，则返回EFI_NOT_FOUND

typedef
EFI_STATUS
(EFIAPI *EFI_LOCATE_PROTOCOL) (
 IN EFI_GUID        *Protocol,//提供要搜索的协议。
 IN VOID            *Registration OPTIONAL,//从EFI_BOOT_SERVICES.RegisterProtocolNotify()返回的可选注册键。如果Registration为NULL，则忽略它。
 OUT VOID           **Interface//返回时，指向第一个匹配协议和注册的接口的指针。
 );

EFI_BOOT_SERVICES.CreateEvent()
创建一个事件。CreateEvent()函数创建一个类型为type的新事件，并将其返回到event引用的位置。事件通知功能、事件上下文和任务优先级分别由“NotifyFunction”、“NotifyContext”和“NotifyTpl”指定。

typedef
EFI_STATUS
(EFIAPI *EFI_CREATE_EVENT) (
 IN UINT32            Type,//要创建的事件类型及其模式和属性。相关定义中的#define语句可以用来指定事件的模式和属性。
 IN EFI_TPL           NotifyTpl, //如果需要，事件通知的任务优先级级别。
 IN EFI_EVENT_NOTIFY  NotifyFunction, OPTIONAL//指向事件通知函数的指针(如果有的话)。
 IN VOID              *NotifyContext, OPTIONAL..//指向通知函数上下文的指针;
 OUT EFI_EVENT        *Event//如果调用成功，则指向新创建的事件;否则属于未定义的。
 );

EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.Io.Read()
EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.Io.Write()
PCI驱动访问PCI根桥I/O空间中的PCI控制器寄存器。Io.Read()和Io.Write()函数使驱动程序能够访问PCI根桥I/O空间中的PCI控制器寄存器。I/O操作完全按照请求执行。调用者负责满足平台上PCI根桥接器可能需要的任何对齐和I/O宽度限制.

typedef
EFI_STATUS
(EFIAPI *EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_IO_MEM) (
 IN EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL       *This,//指向EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL的指针。
 IN EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL_WIDTH Width,//表示内存操作的宽度。
 IN UINT64                                Address,//I/O操作的基址。如果需要，调用方负责对地址进行对齐。
 IN UINTN                                 Count,//I/O操作的次数。移动的字节为宽度大小*Count，从Address开始。
 IN OUT VOID                              *Buffer//对于读操作，用于存储结果的目标缓冲区。对于写操作，要从其中写入数据的源缓冲区。
 );

GetVariable（）
返回变量的值，每个供应商可以通过使用唯一的VendorGuid创建和管理自己的变量，而不会有名称冲突的风险。当设置一个变量时，将提供它的Attributes来指示系统应该如何存储和维护该数据变量。属性会影响访问变量的时间和数据的波动性。如果已经执行了EFI_BOOT_SERVICES.ExitBootServices()，没有EFI_VARIABLE_RUNTIME_ACCESS属性设置的数据变量对GetVariable()将不可见，并将返回一个EFI_NOT_FOUND错误。
如果Data缓冲区太小，无法容纳变量的内容，则返回错误EFI_BUFFER_TOO_SMALL，并将DataSize设置为获取数据所需的缓冲区大小。
EFI_VARIABLE_TIME_BASED_AUTHENTICATED_WRITE_ACCESS和EFI_VARIABLE_ AUTHENTICATED_WRITE_ACCESS可能都被设置在返回的属性位掩码的参数GetVariable()调用,但应该注意的是,EFI_VARIABLE_ AUTHENTICATED_WRITE_ACCESS属性是弃用,不应该再使用。EFI_VARIABLE_APPEND_WRITE属性永远不会在返回的Attributes位掩码参数中设置。
当调用GetVariable()时，使用EFI_VARIABLE_ENHANCED_AUTHENTICATED_ACCESS属性集存储的变量除了返回变量数据外，还将返回元数据。如果GetVariable()调用表明设置了这个属性，则必须根据元数据头解释GetVariable()有效负载。除了SetVariable()中描述的报头之外，下面的报头用于指示当前可能与变量关联的证书。

typedef
EFI_STATUS
GetVariable (
 IN CHAR16      *VariableName, //一个以null结束的字符串，它是供应商变量的名称。
 IN EFI_GUID    *VendorGuid,   //供应商的唯一标识符。 类型EFI_GUID在EFI_BOOT_SERVICES.InstallProtocolInterface()函数描述中定义。  
 OUT UINT32     *Attributes OPTIONAL,//如果不是NULL，那么当返回EFI_SUCCESS和EFI_BUFFER_TOO_SMALL时，在输出上设置Attributes  
 IN OUT UINTN   *DataSize,//在输入时，返回数据缓冲区的大小(以字节为单位)。在输出时，数据中返回的数据的大小。
 OUT VOID       *Data OPTIONAL//用于返回变量内容的缓冲区。为了确定所需的缓冲区大小，可以使用零DataSize为NULL。
 );

SetVariable（）
设置变量的值。此服务可用于创建新变量、修改现有变量的值或删除现有变量。

typedef
EFI_STATUS
SetVariable (
 IN CHAR16     *VariableName,//一个以空结束的字符串，它是供应商变量的名称。每个VariableName对于每个VendorGuid是唯一的。变量名必须包含1个或多个字符。如果VariableName是一个空字符串，则返回EFI_INVALID_PARAMETER。
 IN EFI_GUID   *VendorGuid, //供应商的唯一标识符。类型EFI_GUID在EFI_BOOT_SERVICES.InstallProtocolInterface()函数描述中定义
 IN UINT32     Attributes, //为该变量设置的位掩码属性。参考GetVariable()函数的描述。
 IN UINTN      DataSize, // 数据缓冲区的大小(以字节为单位)。当EFI_VARIABLE_APPEND_WRITE属性设置,那么SetVariable()调用的DataSize零不会导致任何改变变量值。在这种情况下，DataSize将不是零，因为将填充EFI_VARIABLE_AUTHENTICATION_2描述符)。
 IN VOID       *Data//变量的内容。
 );