A.5.1 Protocol File Template

The .h files for protocols are placed in the include directories of EDK II packages. The typical path to a protocol .h file is <<PackageName>>/Include/Protocol/<<ProtocolName>>.h. For example, all the protocols defined in the UEFI Specification can be found in the EDK II MdePkg in /MdePkg/Include/Protocol. When a new protocol is defined and added to an include directory of an EDK II package, the protocol must also be added to the [Protocols] section of a package's .dec file. The .dec file is where the C variable name for the protocol is declared and mapped to GUID value for the protocol. Defining a new protocol is not commonly required when implementing a new UEFI Driver. If a UEFI Driver implementation does require a new protocol definition, then the new protocol is usually added to the same EDK II package that contains the UEFI Driver implementation.

The example below shows a template for adding a new protocol to the [Protocols] section of an EDK II package .dec file. Example A-26 shows the template for the .h files for protocols placed in the include directory of an EDK II package.

Example A-26-Add protocol to an EDK II package

[Protocols]
Include/Protocol/<<ProtocolName>>.h
gEfi<<ProtocolName>>ProtocolGuid = <<GUID_STRUCT>>

Example A-27-Protocol include file template

/** @file
<<BriefDescription>>
<<DetailedDescription>>
<<Copyright>>
<<License>>
**/
#ifndef __<<PROTOCOL_NAME>>_H__
#define __<<PROTOCOL_NAME>>_H__
#define EFI_<<PROTOCOL_NAME>>_PROTOCOL_GUID \
<<GUID_STRUCT>>
///
/// Forward declaration
///
typedef struct _EFI_<<PROTOCOL_NAME>>_PROTOCOL EFI_<<PROTOCOL_NAME>>_PROTOCOL;
///
/// Function prototypes
///
typedef
EFI_STATUS
(EFIAPI * EFI_<<PROTOCOL_NAME>>_<<FUNCTION_NAME_1>>)(
IN EFI_<<PROTOCOL_NAME>>_PROTOCOL *This
//
// Place additional function arguments here
//
);
typedef EFI_STATUS
(EFIAPI *EFI_<<PROTOCOL_NAME>>_<<FUNCTION_NAME_2>>)(
IN EFI_<<PROTOCOL_NAME>>_PROTOCOL *This
//
// Place additional function arguments here
//
);
typedef EFI_STATUS
(EFIAPI *EFI_<<PROTOCOL_NAME>>_<<FUNCTION_NAME_N>>)(
IN EFI_<<PROTOCOL_NAME>>_PROTOCOL *This
//
// Place additional function arguments here
//
);
///
/// Protocol structure
///
typedef struct_EFI_<<PROTOCOL_NAME>>_PROTOCOL {
EFI_<<PROTOCOL_NAME>>_<<FUNCTION_NAME_1>> <<FunctionName1>>;
EFI_<<PROTOCOL_NAME>>_<<FUNCTION_NAME_2>> <<FunctionName2>>;
// . . .
EFI_<<PROTOCOL_NAME>>_<<FUNCTION_NAME_N>> <<FunctionNameN>>;
//
// Place protocol data fields here
//
}
extern EFI_GUID gEfi <<ProtocolName>>ProtocolGuid;
#endif