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