UEFI development learning 5 - simple use of protocol

1 Introduce

stay UEFI Spec You can see in Chapter 7 of ,Boot Service Provides a wealth of services for developers to operate Protocol, This article mainly introduces how to use Protocol.
Use Protocol There are generally three steps ：
1、 Find out by starting the service Protocol object ;
2、 Use this Protocol Services provided ;
3、 Close the open Protocol.
First, let's introduce some related services , Yes ：HandleProtocol、OpenProtocol、LoacalHandleBuffer and LocateProtocol.

1.1 HandleProtocol

The function of this service is to query Handle To determine whether it supports a Protocol. If the support , Then on return , Parameters Interface Point to a corresponding Protocol Interface The pointer to . Then you can put Interface Pass it on to any protocol service, To identify the context of the request .
The function prototype is ：

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

Note： All new applications and drivers Recommended OpenProtocol() Instead of HandleProtocol().

1.2 OpenProtocol

OpenProtocol Used to query the specified Handle Whether the specified Protocol, If the support , Then open the Protocol, Otherwise, the error code is returned . It is HandleProtocol Extended version of . It is associated with HandleProtocol Is the difference between the , open protocol interface Our agent is in EFI Inside handle Tracked in the database .UEFI The driving model uses the tracking function , It is also used to determine whether it is safe to uninstall or reinstall the protocol interface .
open protocol interface Your agent is AgentHandle、ControllerHandle and Attributes determine . If protocol interface Can open ,AgentHandle、ControllerHandle and Attributes Will be added to use Handle and Protocol designated protocol interface In the agent list of .
There are many reasons why this function call may return an error . If something goes wrong, compare it carefully Spec Well .
The function prototype is ：

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

1.3 LocateHandleBuffer

In the buffer allocated in the pool, return the... That supports the request protocol Of handle Array . This function returns one or more matching parameters SearchType Required handle.
The function prototype is ：

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

1.4 LocateProtocol

Returns a value that matches a given protocol One of the first protocol example .LocateProtocol() Function to find the first support Protocol Device handle for , And in the parameters interface Returns a point protocol interface The pointer to , If no protocol instance is found , The parameter interface Set to NULL.
The function prototype ：

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

2 Use

With LocateProtocol For example , First create a Module, newly build MyUseProtocol.inf and MyUseProtocol.c.
stay EmulatorPkg.dsc Of documents [Components] Add below EmulatorPkg/Application/MyUseProtocol
/MyUseProtocol.inf.
Be careful inf In the document FILE_GUID You can't make one up by yourself , Originally, I thought that as long as this format was satisfied , But I found that the compilation failed , Probably GUID There are still some rules for the generation of . And then in inf Of documents [Protocols] Add what we need to use Protocol Of guid. What I'm using here is gEfiDevicePathProtocolGuid.
MyUseProtocol.c The content of the document is ：

#include <Uefi.h>
#include <Library/UefiLib.h>
#include <Library/UefiApplicationEntryPoint.h>

EFI_STATUS 
EFIAPI
UefiMain(IN EFI_HANDLE ImageHandle,IN EFI_SYSTEM_TABLE *SystemTable)
{
    
    EFI_STATUS Status;
    VOID *Protocol;
    Status = SystemTable->BootServices->LocateProtocol (
						&gEfiDevicePathProtocolGuid,
						NULL,
						(VOID**) &Protocol
						);
    if (EFI_ERROR(Status))
    {
    
        SystemTable->ConOut->OutputString(SystemTable->ConOut, L"Use Fail!\n");   
    } else {
    
        SystemTable->ConOut->OutputString(SystemTable->ConOut, L"Use Success!\n");
    }	
    return EFI_SUCCESS;
}

Build after compilation efi The file in shell The results of running under are as follows ：

Here is just a simple use of LocateProtocol service , No matching protocol Service for , As in the example DevicePathProtocol. Of course, in addition to using the existing protocol, We can also create protocol, This is a little more complicated .