UEFI development learning 6 - creation of protocol

1 Introduce

Also in UEFI Spec Chapter seven of Boot Service There are two about Protocol Functions created , Namely InstallProtocolInterface() and InstallMultipleProtocolInterfaces(). seeing the name of a thing one thinks of its function , The former is to install only one ProtocolInterface, The latter can install one or more ProtocolInterface, Besides ,InstallMultipleProtocolInterfaces() Than InstallProtocolInterface() Perform more error checking , therefore It is recommended to use InstallMultipleProtocolInterfaces(). But in this article InstallProtocolInterface() For example .

1.1 InstallProtocolInterface()

The function prototype is ：

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

Parameters ：
Handle： A point to the interface to be installed EFI_HANDLE The pointer to . If Handle At the time of input NULL, Then create a new handle and return when outputting . If Handle It is not NULL, Then the protocol is added to the handle , The handle is returned without modification . type EFI_HANDLE stay “ Related definitions ” In the definition of . If *Handle Is not a valid handle , Then return to EFI_INVALID_PARAMETER.
Protocol： GUID, To identify this Protocol. The caller is responsible for passing a valid GUID.
InterfaceType： Indicates whether to use native form Provide Interface. This value indicates the original execution environment of the request . It's an enumeration type . I don't quite understand here “native form” What does it mean .
Interface： A pointer to the protocol interface . The interface must conform to the structure defined by the Protocol . If a structure is not associated with a protocol , You can use NULL.

1.2 InstallMultipleProtocolInterfaces()

The function prototype is ：

typedef
EFI_STATUS
EFIAPI *EFI_INSTALL_MULTIPLE_PROTOCOL_INTERFACES) (
	IN OUT EFI_HANDLE *Handle,
	...
);

Parameters ：
Handle： Pointer to the handle on which to install the new protocol interface , Or if you want to allocate a new handle , Point to NULL.
… ： A list of variable parameters , Including the agreement guid And protocol interface .

2 Protocol establish

Protocol There are several parts to prepare for the creation of ：
1）Protocol GUID;
2） structure Protocol Member functions and structures of ;
3） Instantiate a Protocol Instance of structure type .
matters needing attention ：Protocol Member function of , Its function type must be EFIAPI Embellished , And the first function parameter must be This The pointer .

2.1 step

First create a Module, newly build CreateProtocol.inf and CreateProtocol.c.
stay EmulatorPkg.dsc Of documents [Components] Add below EmulatorPkg/Application/CreateProtocol
/CreateProtocol.inf. The contents of the document can be found in the following appendix .
And compile it into CreateProtocol.efi file , stay shell Load in the environment . The result is shown in Fig. ：

We can use LocateProtocol() Function to verify whether we can load the Protocol, This content is mentioned above Protocol It has been introduced in the use of . Just put the parameters in this function IN EFI_GUID *Protocol Instead, we define Protocol Of GUID That's all right. .
At this time, there will be problems in compilation , Because we still need to define GUID That is to say gEfiCreateProtocolGUID Add to /vUDK2017/MdePkg/MdePkg.dec Of documents [Protocols] Next .
After the compilation is completed, first in shell Run under Protocol The program , At this time, the program will not Locate To what we define Protocol, Because we haven't put it load Into memory ; And then we use load The order will CreateProtocol.efi Load into memory , Again Locate, At this time, the program can successfully find what we defined Protocol. The results are as follows ：

appendix

• CreateProtocol.c file

#include<Uefi.h>
#include<Library/UefiDriverEntryPoint.h>
#include<Library/UefiBootServicesTableLib.h>
#include<Library/UefiLib.h>

typedef EFI_STATUS(EFIAPI* EFI_INPUT_MSG)();

//protocol Structure 
struct _EFI_CREATE_PROTOCOL{
    
	UINT64 Revsion;  // edition 
	EFI_INPUT_MSG InputMsg;  // Member functions 
};

typedef struct _EFI_CREATE_PROTOCOL EFI_CREATE_PROTOCOL;
// Definition GUID
#define EFI_CREATE_PROTOCOL_GUID \ {
      0xa32ccd8b, 0x021b, 0x4a7f, {
      0x9d, 0xc0, 0xe5, 0x16, 0x35, 0x63, 0x8f, 0xb7}}

EFI_GUID gEfiCreateProtocolGUID = EFI_CREATE_PROTOCOL_GUID;

//Protocol Implementation of member functions in 
EFI_STATUS EFIAPI InputMsg(IN EFI_CREATE_PROTOCOL *This)
{
    
	gST->ConOut->OutputString(gST->ConOut,L"Create Protocol\n");
	return EFI_SUCCESS;
}
//Protocol Example 
EFI_CREATE_PROTOCOL gMyProtocol;
// initialization Protocol Examples of function 
EFI_STATUS MyCreateProtocolInit()
{
    
	EFI_CREATE_PROTOCOL* myProtocol = &gMyProtocol;
	myProtocol->Revsion = 0x101;
	myProtocol->InputMsg = InputMsg;
	return EFI_SUCCESS;
}

//Driver The entry function of 
EFI_STATUS
EFIAPI
CreateProtocolEntry(
	IN EFI_HANDLE ImageHandle,
	IN EFI_SYSTEM_TABLE *SystemTable
)
{
    
	EFI_STATUS	Status;
	MyCreateProtocolInit();
    //Install One Protocol
	Status = gBS->InstallProtocolInterface(
						&ImageHandle,
						&gEfiCreateProtocolGUID,
						EFI_NATIVE_INTERFACE,
						&gMyProtocol
						);
	if(!EFI_ERROR(Status))
	{
    
		gST->ConOut->OutputString(gST->ConOut,L"Success\n");
		return Status;
	}else{
    
		gST->ConOut->OutputString(gST->ConOut,L"Failed\n");
	}
	return Status;
}

• CreateProtocol.inf file

[Defines]
INF_VERSION = 0x00010005
BASE_NAME = CreateProtocol
FILE_GUID = 2d7ee62a-8f25-4a0c-bcc7-a0c8edc31643
MODULE_TYPE = UEFI_DRIVER
VERSION_STRING = 1.0
ENTRY_POINT = CreateProtocolEntry
 
[Sources]
CreateProtocol.c
 
[Packages]
MdePkg/MdePkg.dec
 
[LibraryClasses]
UefiDriverEntryPoint
UefiLib