5. HOB Code Definitions

5.1. HOB Introduction

This section contains the basic definitions of various HOBs. All HOBs consist of a generic header, EFI_HOB_GENERIC_HEADER , that specifies the type and length of the HOB. Each HOB has additional data beyond the generic header, according to the HOB type. The following data types and structures are defined in this section:

EFI_HOB_GENERIC_HEADER
EFI_HOB_HANDOFF_INFO_TABLE
EFI_HOB_MEMORY_ALLOCATION
EFI_HOB_MEMORY_ALLOCATION_STACK
EFI_HOB_MEMORY_ALLOCATION_BSP_STORE
EFI_HOB_MEMORY_ALLOCATION_MODULE
EFI_HOB_RESOURCE_DESCRIPTOR
EFI_HOB_GUID_TYPE
EFI_HOB_FIRMWARE_VOLUME
EFI_HOB_FIRMWARE_VOLUME2
EFI_HOB_FIRMWARE_VOLUME3
EFI_HOB_CPU
EFI_HOB_MEMORY_POOL
EFI_HOB_UEFI_CAPSULE
EFI_HOB_TYPE_UNUSED
EFI_HOB_TYPE_END_OF_HOB_LIST

This section also contains the definitions for additional data types and structures that are subordinate to the structures in which they are called. The following types or structures can be found in “Related Definitions” of the parent data structure definition:

EFI_HOB_MEMORY_ALLOCATION_HEADER
EFI_RESOURCE_TYPE
EFI_RESOURCE_ATTRIBUTE_TYPE

5.2. HOB Generic Header

5.2.1. EFI_HOB_GENERIC_HEADER

Summary

Describes the format and size of the data inside the HOB. All HOBs must contain this generic HOB header.

Prototype

typedef struct _EFI_HOB_GENERIC_HEADER{
  UINT16  HobType;
  UINT16  HobLength;
  UINT32  Reserved;
} EFI_HOB_GENERIC_HEADER;

Parameters

HobType: Identifies the HOB data structure type. See “Related Definitions” below for the HOB types that are defined in this specification.

HobLength: The length in bytes of the HOB.

Reserved: For this version of the specification, this field must always be set to zero.

Description

All HOBs have a common header that is used for the following:

Traversing to the next HOB
Describing the format and size of the data inside the HOB

The following values for HobType are defined by this specification.

//******************************************************
// HobType values
//******************************************************

#define EFI_HOB_TYPE_HANDOFF              0x0001
#define EFI_HOB_TYPE_MEMORY_ALLOCATION    0x0002
#define EFI_HOB_TYPE_RESOURCE_DESCRIPTOR  0x0003
#define EFI_HOB_TYPE_GUID_EXTENSION       0x0004
#define EFI_HOB_TYPE_FV                   0x0005
#define EFI_HOB_TYPE_CPU                  0x0006
#define EFI_HOB_TYPE_MEMORY_POOL          0x0007
#define EFI_HOB_TYPE_FV2                  0x0009
#define EFI_HOB_TYPE_LOAD_PEIM_UNUSED     0x000A
#define EFI_HOB_TYPE_UEFI_CAPSULE         0x000B
#define EFI_HOB_TYPE_FV3                  0x000C
#define EFI_HOB_TYPE_UNUSED               0xFFFE
#define EFI_HOB_TYPE_END_OF_HOB_LIST      0xffff

Other values for HobType are reserved for future use by this specification.

5.3. PHIT HOB

5.3.1. EFI_HOB_HANDOFF_INFO_TABLE (PHIT HOB)

Summary

Contains general state information used by the HOB producer phase. This HOB must be the first one in the HOB list.

Prototype

typedef struct _EFI_HOB_HANDOFF_INFO_TABLE {
  EFI_HOB_GENERIC_HEADER  Header;
  UINT32                  Version;
  EFI_BOOT_MODE           BootMode;
  EFI_PHYSICAL_ADDRESS    EfiMemoryTop;
  EFI_PHYSICAL_ADDRESS    EfiMemoryBottom;
  EFI_PHYSICAL_ADDRESS    EfiFreeMemoryTop;
  EFI_PHYSICAL_ADDRESS    EfiFreeMemoryBottom;
  EFI_PHYSICAL_ADDRESS    EfiEndOfHobList;
} EFI_HOB_HANDOFF_INFO_TABLE;

Parameters

Header: The HOB generic header. Header.HobType = EFI_HOB_TYPE_HANDOFF.

Version: The version number pertaining to the PHIT HOB definition. See “Related Definitions” below for the version numbers defined by this specification. This value is 4 bytes in length to provide an 8-byte aligned entry when it is combined with the 4-byte BootMode .

BootMode: The system boot mode as determined during the HOB producer phase. Type EFI_BOOT_MODE is a UINT32 ; if the PI Architecture-compliant implementation incorporates the PEI phase, the possible bit values are defined in the Platform Initialization Pre-EFI Initialization Core Interface Specification (PEI CIS).

EfiMemoryTop: The highest address location of memory that is allocated for use by the HOB producer phase. This address must be 4-KiB aligned to meet page restrictions of UEFI. Type EFI_PHYSICAL_ADDRESS is defined in AllocatePages() in the UEFI 2.0 specification.

EfiMemoryBottom: The lowest address location of memory that is allocated for use by the HOB producer phase.

EfiFreeMemoryTop: The highest address location of free memory that is currently available for use by the HOB producer phase. This address must be 4-KiB aligned to meet page restrictions of UEFI.

EfiFreeMemoryBottom: The lowest address location of free memory that is available for use by the HOB producer phase.

EfiEndOfHobList: The end of the HOB list.

Description

The Phase Handoff Information Table (PHIT) HOB must be the first one in the HOB list. A pointer to this HOB is available to a HOB producer phase component through some service. This specification commonly refers to this HOB as the PHIT HOB, or sometimes the handoff HOB.

The HOB consumer phase reads the PHIT HOB during its initialization.

//*****************************************************
// Version values
//*****************************************************

#define EFI_HOB_HANDOFF_TABLE_VERSION   0x000a

5.4. Memory Allocation HOB

5.4.1. Memory Allocation HOB

5.4.1.1. EFI_HOB_MEMORY_ALLOCATION

Summary

Describes all memory ranges used during the HOB producer phase that exist outside the HOB list. This HOB type describes how memory is used, not the physical attributes of memory.

Prototype

typedef struct _EFI_HOB_MEMORY_ALLOCATION {
  EFI_HOB_GENERIC_HEADER            Header;
  EFI_HOB_MEMORY_ALLOCATION_HEADER  AllocDescriptor;
  //
  // Additional data pertaining to the “Name” Guid memory
  // may go here.
  //
} EFI_HOB_MEMORY_ALLOCATION;

Parameters

Header: The HOB generic header. Header.HobType = EFI_HOB_TYPE_MEMORY_ALLOCATION .

AllocDescriptor: An instance of the EFI_HOB_MEMORY_ALLOCATION_HEADER that describes the various attributes of the logical memory allocation. The type field will be used for subsequent inclusion in the UEFI memory map. Type EFI_HOB_MEMORY_ALLOCATION_HEADER is defined in “Related Definitions” below.

Description

The memory allocation HOB is used to describe memory usage outside the HOB list. The HOB consumer phase does not make assumptions about the contents of the memory that is allocated by the memory allocation HOB, and it will not move the data unless it has explicit knowledge of the memory allocation HOB’s Name (EFI_GUID). Memory may be allocated in either the HOB producer phase memory area or other areas of present and initialized system memory.

The HOB consumer phase reads all memory allocation HOBs and allocates memory into the system memory map based on the following fields of EFI_HOB_MEMORY_ALLOCATION_HEADER of each memory allocation HOB:

MemoryBaseAddress
MemoryLength
MemoryType

The HOB consumer phase does not parse the GUID-specific data identified by the Name field of each memory allocation HOB, except for a specific set of memory allocation HOBs that defined by this specification. A HOB consumer phase driver that corresponds to the specific Name GUIDed memory allocation HOB can parse the HOB list to find the specifically named memory allocation HOB and then manipulate the memory space as defined by the usage model for that GUID.

Note: Special design care should be taken to ensure that two HOB consumer phase components do not modify memory space that is described by a memory allocation HOB, because unpredictable behavior might result.

This specification defines a set of memory allocation HOBs that are architecturally used to allocate memory used by the HOB producer and consumer phases. Additionally, the following memory allocation HOBs are defined specifically for use by the final stage of the HOB producer phase to describe the processor state prior to handoff into the HOB consumer phase:

BSP stack memory allocation HOB
BSP store memory allocation HOB
Memory allocation module HOB

//******************************************************
// EFI_HOB_MEMORY_ALLOCATION_HEADER
//******************************************************

typedef struct _EFI_HOB_MEMORY_ALLOCATION_HEADER {
  EFI_GUID                Name;
  EFI_PHYSICAL_ADDRESS    MemoryBaseAddress;
  UINT64                  MemoryLength;
  EFI_MEMORY_TYPE         MemoryType;   // UINT32
  UINT8 Reserved[4];                    // Padding for Itanium®
                                        // processor family
} EFI_HOB_MEMORY_ALLOCATION_HEADER;

Name: A GUID that defines the memory allocation region’s type and purpose, as well as other fields within the memory allocation HOB. This GUID is used to define the additional data within the HOB that may be present for the memory allocation HOB. Type EFI_GUID is defined in InstallProtocolInterface() in the UEFI 2.0 specification.

MemoryBaseAddress: The base address of memory allocated by this HOB. Type EFI_PHYSICAL_ADDRESS is defined in AllocatePages() in the UEFI 2.0 specification.

MemoryLength: The length in bytes of memory allocated by this HOB.

MemoryType: Defines the type of memory allocated by this HOB. The memory type definition follows the EFI_MEMORY_TYPE definition. Type EFI_MEMORY_TYPE is defined in AllocatePages() in the UEFI 2.0 specification.

Reserved For this version of the specification, this field will always be set to zero.

Note: MemoryBaseAddress and MemoryLength must each have 4-KiB granularity to meet the page size requirements of UEFI.

5.4.2. Boot-Strap Processor (BSP) Stack MemoryAllocation HOB

5.4.2.1. EFI_HOB_MEMORY_ALLOCATION_STACK

Summary

Describes the memory stack that is produced by the HOB producer phase and upon which all post-memory-installed executable content in the HOB producer phase is executing.

GUID

#define EFI_HOB_MEMORY_ALLOC_STACK_GUID \
  {0x4ed4bf27, 0x4092, 0x42e9, 0x80, 0x7d, 0x52, 0x7b, \
  0x1d, 0x0, 0xc9, 0xbd}

Prototype

typedef struct _EFI_HOB_MEMORY_ALLOCATION_STACK {
  EFI_HOB_GENERIC_HEADER            Header;
  EFI_HOB_MEMORY_ALLOCATION_HEADER  AllocDescriptor;
} EFI_HOB_MEMORY_ALLOCATION_STACK;

Parameters

Header: The HOB generic header. Header.HobType = EFI_HOB_TYPE_MEMORY_ALLOCATION .

AllocDescriptor: An instance of the EFI_HOB_MEMORY_ALLOCATION_HEADER that describes the various attributes of the logical memory allocation. The type field will be used for subsequent inclusion in the UEFI memory map. Type EFI_HOB_MEMORY_ALLOCATION_HEADER is defined in EFI_HOB_MEMORY_ALLOCATION .

Description

This HOB describes the memory stack that is produced by the HOB producer phase and upon which all post-memory-installed executable content in the HOB producer phase is executing. It is necessary for the hand-off into the HOB consumer phase to know this information so that it can appropriately map this stack into its own execution environment and describe it in any subsequent memory maps.

The HOB consumer phase reads this HOB during its initialization. The HOB consumer phase may elect to move or relocate the BSP’s stack to meet size and location requirements that are defined by the HOB consumer phase’s implementation. Therefore, other HOB consumer phase components cannot rely on the BSP stack memory allocation HOB to describe where the BSP stack is located during execution of the HOB consumer phase.

Note: BSP stack memory allocation HOB must be valid at the time of hand off to the HOB consumer phase. If BSP stack is reallocated during HOB producer phase, the component that reallocates the stack must also update BSP stack memory allocation HOB.

The BSP stack memory allocation HOB without any additional qualification describes either of the following:

The stack that is currently consumed by the BSP.
The processor that is currently executing the HOB producer phase and its executable content.
The model for the PI architecture and the HOB producer phase is that of a single-threaded execution environment, so it is this single, distinguished thread of control whose environment is described by this HOB. The Itanium ® processor family has the additional requirement of having to describe the value of the BSPSTORE (AR18) (“Backing Store Pointer Store”) register, which holds the successive location in memory where the Itanium processor family Register Stack Engine (RSE) will spill its values.
In addition, Itanium ® -based systems feature a system architecture where all processors come out of reset and execute the reset path concurrently. As such, the stack resources that are consumed by these alternate agents need to be described even though they are not responsible for executing the main thread of control through the HOB producer and consumer phases.

5.4.3. Boot-Strap Processor (BSP) BSPSTORE MemoryAllocation HOB

5.4.3.1. EFI_HOB_MEMORY_ALLOCATION_BSP_STORE

Note: This HOB is valid for the Itanium ® processor family only.

Summary

Defines the location of the boot-strap processor (BSP) BSPStore (“Backing Store Pointer Store”) register overflow store.

GUID

#define EFI_HOB_MEMORY_ALLOC_BSP_STORE_GUID \
  {0x564b33cd, 0xc92a, 0x4593, 0x90, 0xbf, 0x24, 0x73, \
  0xe4, 0x3c, 0x63, 0x22}

Prototype

typedef struct _EFI_HOB_MEMORY_ALLOCATION_BSP_STORE {
  EFI_HOB_GENERIC_HEADER            Header;
  EFI_HOB_MEMORY_ALLOCATION_HEADER  AllocDescriptor;
} EFI_HOB_MEMORY_ALLOCATION_BSP_STORE;

Parameters

Header: The HOB generic header. Header.HobType = EFI_HOB_TYPE_MEMORY_ALLOCATION .

AllocDescriptor: An instance of the EFI_HOB_MEMORY_ALLOCATION_HEADER that describes the various attributes of the logical memory allocation. The type field will be used for subsequent inclusion in the UEFI memory map. Type EFI_HOB_MEMORY_ALLOCATION_HEADER is defined in the HOB type EFI_HOB_MEMORY_ALLOCATION .

Description

The HOB consumer phase reads this HOB during its initialization. The HOB consumer phase may elect to move or relocate the BSP’s register store to meet size and location requirements that are defined by the HOB consumer phase’s implementation. Therefore, other HOB consumer phase components cannot rely on the BSP store memory allocation HOB to describe where the BSP store is located during execution of the HOB consumer phase.

Note: BSP BSPSTORE memory allocation HOB must be valid at the time of hand off to the HOB consumer phase. If BSP BSPSTORE is reallocated during HOB producer phase, the component that reallocates the stack must also update BSP BSPSTORE memory allocation HOB.

This HOB is valid for the Itanium processor family only.

5.4.4. Memory Allocation Module HOB

5.4.4.1. EFI_HOB_MEMORY_ALLOCATION_MODULE

Summary

Defines the location and entry point of the HOB consumer phase.

GUID

#define EFI_HOB_MEMORY_ALLOC_MODULE_GUID \
  {0xf8e21975, 0x899, 0x4f58, 0xa4, 0xbe, 0x55, 0x25, \
  0xa9, 0xc6, 0xd7, 0x7a}

Prototype

typedef struct {
  EFI_HOB_GENERIC_HEADER            Header;
  EFI_HOB_MEMORY_ALLOCATION_HEADER  MemoryAllocationHeader;
  EFI_GUID                          ModuleName;
  EFI_PHYSICAL_ADDRESS              EntryPoint;
} EFI_HOB_MEMORY_ALLOCATION_MODULE;

Parameters

Header: The HOB generic header. Header.HobType = EFI_HOB_TYPE_MEMORY_ALLOCATION .

MemoryAllocationHeader: An instance of the EFI_HOB_MEMORY_ALLOCATION_HEADER that describes the various attributes of the logical memory allocation. The type field will be used for subsequent inclusion in the UEFI memory map. Type EFI_HOB_MEMORY_ALLOCATION_HEADER is defined in the HOB type EFI_HOB_MEMORY_ALLOCATION .

ModuleName: The GUID specifying the values of the firmware file system name that contains the HOB consumer phase component. Type EFI_GUID is defined in InstallProtocolInterface() in the UEFI 2.0 specification.

EntryPoint: The address of the memory-mapped firmware volume that contains the HOB consumer phase firmware file. Type EFI_PHYSICAL_ADDRESS is defined in AllocatePages() in the UEFI 2.0 specification.

Description

The HOB consumer phase reads the memory allocation module HOB during its initialization. This HOB describes the memory location of the HOB consumer phase. The HOB consumer phase should use the information to create the image handle for the HOB consumer phase.

5.5. Resource Descriptor HOB

5.5.1. EFI_HOB_RESOURCE_DESCRIPTOR

Summary

Describes the resource properties of all fixed, nonrelocatable resource ranges found on the processor host bus during the HOB producer phase.

Prototype

typedef struct _EFI_HOB_RESOURCE_DESCRIPTOR {
  EFI_HOB_GENERIC_HEADER        Header;
  EFI_GUID                      Owner;
  EFI_RESOURCE_TYPE             ResourceType;
  EFI_RESOURCE_ATTRIBUTE_TYPE   ResourceAttribute;
  EFI_PHYSICAL_ADDRESS          PhysicalStart;
  UINT64                        ResourceLength;
} EFI_HOB_RESOURCE_DESCRIPTOR;

Parameters

Header: The HOB generic header. Header.HobType = EFI_HOB_TYPE_RESOURCE_DESCRIPTOR .

Owner: A GUID representing the owner of the resource. This GUID is used by HOB consumer phase components to correlate device ownership of a resource.

ResourceType: Resource type enumeration as defined by EFI_RESOURCE_TYPE. Type EFI_RESOURCE_TYPE is defined in “Related Definitions” below.

ResourceAttribute: Resource attributes as defined by EFI_RESOURCE_ATTRIBUTE_TYPE . Type EFI_RESOURCE_ATTRIBUTE_TYPE is defined in “Related Definitions” below.

PhysicalStart: Physical start address of the resource region. Type EFI_PHYSICAL_ADDRESS is defined in AllocatePages() in the UEFI 2.0 specification.

ResourceLength: Number of bytes of the resource region.

Description

The resource descriptor HOB describes the resource properties of all fixed, nonrelocatable resource ranges found on the processor host bus during the HOB producer phase. This HOB type does not describe how memory is used but instead describes the attributes of the physical memory present.

The HOB consumer phase reads all resource descriptor HOBs when it established the initial Global Coherency Domain (GCD) map. The minimum requirement for the HOB producer phase is that executable content in the HOB producer phase report one of the following:

The resources that are necessary to start the HOB consumer phase
The fixed resources that are not captured by HOB consumer phase driver components that were started prior to the dynamic system configuration performed by the platform boot-policy phase

For example, executable content in the HOB producer phase should report any physical memory found during the HOB producer phase. Another example is reporting the Boot Firmware Volume (BFV) that contains firmware volume(s). Executable content in the HOB producer phase does not need to report fixed system resources such as I/O port 70h/71h (real-time clock) because these fixed resources can be allocated from the GCD by a platform-specific chipset driver loading in the HOB consumer phase prior to the platform boot-policy phase, for example.

Current thinking is that the GCD does not track the HOB’s Owner GUID, so a HOB consumer phase component that assumes ownership of a device’s resource must deallocate the resource initialized by the HOB producer phase from the GCD before attempting to assign the devices resource to itself in the HOB consumer phase.

There can only be a single ResourceType field, characterized as follows.

//*********************************************************
// EFI_RESOURCE_TYPE
//*********************************************************

typedef UINT32 EFI_RESOURCE_TYPE;

#define EFI_RESOURCE_SYSTEM_MEMORY          0x00000000
#define EFI_RESOURCE_MEMORY_MAPPED_IO       0x00000001
#define EFI_RESOURCE_IO                     0x00000002
#define EFI_RESOURCE_FIRMWARE_DEVICE        0x00000003
#define EFI_RESOURCE_MEMORY_MAPPED_IO_PORT  0x00000004
#define EFI_RESOURCE_MEMORY_RESERVED        0x00000005
#define EFI_RESOURCE_IO_RESERVED            0x00000006
#define EFI_RESOURCE_MEMORY_UNACCEPTED      0x00000007
#define EFI_RESOURCE_MAX_MEMORY_TYPE        0x00000008

The following table describes the fields listed in the above definition.

EFI_RESOURCE_SYSTEM_MEMORY	Memory that persists out of the HOB producer phase.
EFI_RESOURCE_MEMORY_MAPPED_IO	Memory-mapped I/O that is programmed in the HOB producer phase.
EFI_RESOURCE_IO	Processor I/O space.
EFI_RESOURCE_FIRMWARE_DEVICE	Memory-mapped firmware devices.
EFI_RESOURCE_MEMORY_MAPPED_IO_PORT	Memory that is decoded to produce I/O cycles.
EFI_RESOURCE_MEMORY_RESERVED	Reserved memory address space.
EFI_RESOURCE_IO_RESERVED	Reserved I/O address space.
EFI_RESOURCE_MEMORY_UNACCEPTED	Memory that is unaccepted.
EFI_RESOURCE_MAX_MEMORY_TYPE	Any reported HOB value of this type or greater should be deemed illegal. This value could increase with successive revisions of this specification, so the “illegality” will also be based upon the revision field of the PHIT HOB

The ResourceAttribute field is characterized as follows:

//*******************************************************
// EFI_RESOURCE_ATTRIBUTE_TYPE
//*******************************************************

typedef UINT32 EFI_RESOURCE_ATTRIBUTE_TYPE;


// These types can be ORed together as needed.
//
// The following attributes are used to describe settings
//
#define EFI_RESOURCE_ATTRIBUTE_PRESENT                   0x00000001
#define EFI_RESOURCE_ATTRIBUTE_INITIALIZED               0x00000002
#define EFI_RESOURCE_ATTRIBUTE_TESTED                    0x00000004

#define EFI_RESOURCE_ATTRIBUTE_READ_PROTECTED            0x00000080
#define EFI_RESOURCE_ATTRIBUTE_WRITE_PROTECTED           0x00000100
#define EFI_RESOURCE_ATTRIBUTE_EXECUTION_PROTECTED
                                                         0x00000200
#define EFI_RESOURCE_ATTRIBUTE_PERSISTENT                0x00800000
#define EFI_RESOURCE_ATTRIBUTE_MORE_RELIABLE             0x02000000

// The rest of the attributes are used to describe capabilities
//
#define EFI_RESOURCE_ATTRIBUTE_SINGLE_BIT_ECC            0x00000008
#define EFI_RESOURCE_ATTRIBUTE_MULTIPLE_BIT_ECC          0x00000010
#define EFI_RESOURCE_ATTRIBUTE_ECC_RESERVED_1            0x00000020
#define EFI_RESOURCE_ATTRIBUTE_ECC_RESERVED_2            0x00000040
#define EFI_RESOURCE_ATTRIBUTE_UNCACHEABLE               0x00000400
#define EFI_RESOURCE_ATTRIBUTE_WRITE_COMBINEABLE         0x00000800
#define EFI_RESOURCE_ATTRIBUTE_WRITE_THROUGH_CACHEABLE   0x00001000
#define EFI_RESOURCE_ATTRIBUTE_WRITE_BACK_CACHEABLE      0x00002000
#define EFI_RESOURCE_ATTRIBUTE_16_BIT_IO                 0x00004000
#define EFI_RESOURCE_ATTRIBUTE_32_BIT_IO                 0x00008000
#define EFI_RESOURCE_ATTRIBUTE_64_BIT_IO                 0x00010000
#define EFI_RESOURCE_ATTRIBUTE_UNCACHED_EXPORTED         0x00020000
#define EFI_RESOURCE_ATTRIBUTE_READ_ONLY_PROTECTED       0x00040000


#define EFI_RESOURCE_ATTRIBUTE_READ_PROTECTABLE          0x00100000
#define EFI_RESOURCE_ATTRIBUTE_WRITE_PROTECTABLE         0x00200000
#define EFI_RESOURCE_ATTRIBUTE_EXECUTION_PROTECTABLE     0x00400000
#define EFI_RESOURCE_ATTRIBUTE_PERSISTABLE               0x01000000
#define EFI_RESOURCE_ATTRIBUTE_READ_ONLY_PROTECTABLE     0x00080000
#define EFI_RESOURCE_ATTRIBUTE_ENCRYPTED                 0x04000000
#define EFI_RESOURCE_ATTRIBUTE_SPECIAL_PURPOSE           0x08000000
#define EFI_RESOURCE_ATTRIBUTE_HOT_PLUGGABLE             0x10000000

Table 5.12 EFI_RESOURCE_ATTRIBUTE_TYPE fields
EFI_RESOURCE_ATTRIBUTE _PRESENT	Physical memory attribute: The memory region exists.
EFI_RESOURCE_ATTRIBUTE _INITIALIZED	Physical memory attribute: The memory region has been initialized.
EFI_RESOURCE_ATTRIBUTE _TESTED	Physical memory attribute: The memory region has been tested.
EFI_RESOURCE_ATTRIBUTE _SINGLE_BIT_ECC	Physical memory attribute: The memory region supports single-bit ECC.
EFI_RESOURCE_ATTRIBUTE _MULTIPLE_BIT_ECC	Physical memory attribute: The memory region supports multibit ECC.
EFI_RESOURCE_ATTRIBUTE _ECC_RESERVED_1	Physical memory attribute: The memory region supports reserved ECC.
EFI_RESOURCE_ATTRIBUTE _ECC_RESERVED_2	Physical memory attribute: The memory region supports reserved ECC.
EFI_RESOURCE_ATTRIBUTE _READ_PROTECTED	Physical memory protection attribute: The memory region is read protected.
EFI_RESOURCE_ATTRIBUTE _WRITE_PROTECTED	Physical memory protection attribute: The memory region is write protected. This is typically used as memory cacheability attribute today. NOTE: Since PI spec 1.4, please use EFI_RESOURCE_ATTRIBUTE_READ_ONLY_PROTECTED as Physical write protected attribute, and EFI_RESOURCE_ATTRIBUTE_WRITE_PROTECTED means Memory cacheability attribute: The memory supports being programmed with a write-protected cacheable attribute.
EFI_RESOURCE_ATTRIBUTE _EXECUTION_PROTECTED	Physical memory protection attribute: The memory region is execution protected.
EFI_RESOURCE_ATTRIBUTE _READ_ONLY_PROTECTED	Physical memory protection attribute: The memory region is write protected.
EFI_RESOURCE_ATTRIBUTE _PERSISTENT	Physical memory persistence attribute: This memory is configured for byte-addressable non-volatility.
EFI_RESOURCE_ATTRIBUTE _MORE_RELIABLE	Physical memory relative reliability attribute: This memory provides higher reliability relative to other memory in the system. If all memory has the same reliability, then this bit is not used.
EFI_RESOURCE_ATTRIBUTE _UNCACHEABLE	Memory cacheability attribute: The memory does not support caching.
EFI_RESOURCE_ATTRIBUTE _READ_PROTECTABLE	Memory capability attribute: The memory supports being protected from processor reads.
EFI_RESOURCE_ATTRIBUTE _WRITE_PROTECTABLE	Memory capability attribute: The memory supports being protected from processor writes. This is typically used as memory cacheability attribute today. NOTE: Since PI spec 1.4, please use EFI_RESOURCE_ATTRIBUTE_READ_ONLY_PROTECTABLE as Memory capability attribute: The memory supports being protected from processor writes, and EFI_RESOURCE_ATTRIBUTE_WRITE_PROTECTABLE means Memory cacheability attribute: The memory supports being programmed with a write-protected cacheable attribute.
EFI_RESOURCE_ATTRIBUTE _EXECUTION_PROTECTABLE	Memory capability attribute: The memory supports being protected from processor execution.
EFI_RESOURCE_ATTRIBUTE _READ_ONLY_PROTECTABLE	Memory capability attribute: The memory supports being protected from processor writes.
EFI_RESOURCE_ATTRIBUTE _PERSISTABLE	Memory capability attribute: This memory supports byte-addressable non-volatility.
EFI_RESOURCE_ATTRIBUTE _WRITE_THROUGH_CACHEABLE	Memory cacheability attribute: The memory supports being programmed with a write-through cacheable attribute.
EFI_RESOURCE_ATTRIBUTE _WRITE_COMBINEABLE	Memory cacheability attribute: The memory supports a write-combining attribute.
EFI_RESOURCE_ATTRIBUTE _WRITE_BACK_CACHEABLE	Memory cacheability attribute: The memory region supports being configured as cacheable with a write-back policy. Reads and writes that hit in the cache do not propagate to main memory. Dirty data is written back to main memory when a new cache line is allocated.
EFI_RESOURCE_ATTRIBUTE _16_BIT_IO	Memory physical attribute: The memory supports 16-bit I/O.
EFI_RESOURCE_ATTRIBUTE _32_BIT_IO	Memory physical attribute: The memory supports 32-bit I/O.
EFI_RESOURCE_ATTRIBUTE _64_BIT_IO	Memory physical attribute: The memory supports 64-bit I/O.
EFI_RESOURCE_ATTRIBUTE _UNCACHED_EXPORTED	Memory cacheability attribute: The memory region is uncacheable and exported and supports the fetch and add semaphore mechanism.
EFI_RESOURCE_ATTRIBUTE _ENCRYPTED	If this flag is set, the memory region is capable of being protected with the CPU’s memory cryptographic capabilities. If this flag is clear, the memory region is not capable of being protected with the CPU’s memory cryptographic capabilities or the CPU does not support CPU memory cryptographic capabilities.
EFI_RESOURCE_ATTRIBUTE _SPECIAL_PURPOSE	If this flag is set, the memory region is capable of being a Specific-purpose memory (SPM). The memory is earmarked for specific purposes such as for specific device drivers or applications. The SPM attribute serves as a hint to the OS to avoid allocating this memory for core OS data or code that can not be relocated. Prolonged use of this memory for purposes other than the intended purpose may result in suboptimal platform performance.
EFI_RESOURCE_ATTRIBUTE _HOT_PLUGGABLE	If this flag is set, the memory region is present and capable of having memory dynamically removed from the platform. This attribute serves as a hint to the OS prior to its ACPI subsystem initialization to avoid allocating this memory for core OS data or code that cannot be dynamically relocated at runtime. If this flag is clear, the memory region is not capable of being dynamically removed from the platform at runtime.

HOB Producer Phase Resource Types specifies the resource attributes applicable to each resource type.

Table 5.13 HOB Producer Phase Resource Types
EFI_RESOURCE_ATTRIBUTE_TYPE	HOB ProducerPhase SystemMemory	HOB ProducerPhase Memory-MappedI/O	HOB ProducerPhase I/O
Present	X
Initialized	X
Tested	X
SingleBitEcc	X
MultipleBitEcc	X
EccReserved1	X
EccReserved2	X
ReadProtected	X	X
WriteProtected	X	X
ExecutionProtected	X
ReadOnlyProtected	X	X
Uncacheable	X	X
ReadProtectable	X	X
WriteProtectable	X	X
ExecutionProtectable	X
ReadOnlyProtectable	X	X
WriteThroughCacheable	X	X
WriteCombineable	X	X
WriteBackCacheable	X	X
16bitIO			X
32bitIO			X
64bitIO			X
UncachedExported	X	X

5.6. GUID Extension HOB

5.6.1. EFI_HOB_GUID_TYPE

Summary

Allows writers of executable content in the HOB producer phase to maintain and manage HOBs whose types are not included in this specification. Specifically, writers of executable content in the HOB producer phase can generate a GUID and name their own HOB entries using this module-specific value.

Prototype

typedef struct _EFI_HOB_GUID_TYPE {
  EFI_HOB_GENERIC_HEADER  Header;
  EFI_GUID                Name;

  //
  // Guid specific data goes here
  //
} EFI_HOB_GUID_TYPE;

Parameters

Header: The HOB generic header. Header.HobType = EFI_HOB_TYPE_GUID_EXTENSION .

Name: A GUID that defines the contents of this HOB. Type EFI_GUID is defined in InstallProtocolInterface() in the UEFI 2.0 specification.

Description

The GUID extension HOB allows writers of executable content in the HOB producer phase to create their own HOB definitions using a GUID. This HOB type should be used by all executable content in the HOB producer phase to define implementation-specific data areas that are not architectural. This HOB type may also pass implementation-specific data from executable content in the HOB producer phase to drivers in the HOB consumer phase.

A HOB consumer phase component such as a HOB consumer phase driver will read the GUID extension HOB during the HOB consumer phase. The HOB consumer phase component must inherently know the GUID for the GUID extension HOB for which it is scanning the HOB list. This knowledge establishes a contract on the HOB’s definition and usage between the executable content in the HOB producer phase and the HOB consumer phase driver.

5.7. Firmware Volume HOB

5.7.1. EFI_HOB_FIRMWARE_VOLUME

Summary

Details the location of firmware volumes that contain firmware files.

Prototype

typedef struct {
  EFI_HOB_GENERIC_HEADER  Header;
  EFI_PHYSICAL_ADDRESS    BaseAddress;
  UINT64                  Length;
} EFI_HOB_FIRMWARE_VOLUME;

Parameters

Header: The HOB generic header. Header.HobType = EFI_HOB_TYPE_FV .

BaseAddress: The physical memory-mapped base address of the firmware volume. Type EFI_PHYSICAL_ADDRESS is defined in AllocatePages() in the UEFI 2.0 specification.

Length: The length in bytes of the firmware volume.

Description

The firmware volume HOB details the location of firmware volumes that contain firmware files. It includes a base address and length. In particular, the HOB consumer phase will use these HOBs to discover drivers to execute and the hand-off into the HOB consumer phase will use this HOB to discover the location of the HOB consumer phase firmware file.

The firmware volume HOB is produced in the following ways:

By the executable content in the HOB producer phase in the Boot Firmware Volume (BFV) that understands the size and layout of the firmware volume(s) that are present in the platform.
By a module that has loaded a firmware volume from some media into memory. The firmware volume HOB details this memory location.

Firmware volumes described by the firmware volume HOB must have a firmware volume header as described in this specification.

The HOB consumer phase consumes all firmware volume HOBs that are presented by the HOB producer phase for use by its read-only support for the PI Firmware Image Format. The HOB producer phase is required to describe any firmware volumes that may contain the HOB consumer phase or platform drivers that are required to discover other firmware volumes.

5.7.2. EFI_HOB_FIRMWARE_VOLUME2

Summary

Details the location of a firmware volume which was extracted from a file within another firmware volume.

Prototype

typedef struct {
  EFI_HOB_GENERIC_HEADER  Header;
  EFI_PHYSICAL_ADDRESS    BaseAddress;
  UINT64                  Length;
  EFI_GUID                FvName;
  EFI_GUID                FileName;
} EFI_HOB_FIRMWARE_VOLUME2;

Parameters

Header: The HOB generic header. Header.HobType = EFI_HOB_TYPE_FV2 .

BaseAddress: The physical memory-mapped base address of the firmware volume. Type EFI_PHYSICAL_ADDRESS is defined in AllocatePages() in the Unified Extensible Firmware Interface Specification, version 2.0.

Length: The length in bytes of the firmware volume.

FvName: The name of the firmware volume.

FileName: The name of the firmware file which contained this firmware volume.

Description

The firmware volume HOB details the location of a firmware volume that was extracted prior to the HOB consumer phase from a file within a firmware volume. By recording the volume and file name, the HOB consumer phase can avoid processing the same file again.

This HOB is created by a module that has loaded a firmware volume from another file into memory. This HOB details the base address, the length, the file name and volume name.

The HOB consumer phase consumes all firmware volume HOBs that are presented by the HOB producer phase for use by its read-only support for the PI Firmware Image format.

5.7.3. EFI_HOB_FIRMWARE_VOLUME3

Summary

Details the location of a firmware volume including authentication information, for both standalone and extracted firmware volumes.

Prototype

typedef struct {
  EFI_HOB_GENERIC_HEADER  Header;
  EFI_PHYSICAL_ADDRESS    BaseAddress;
  UINT64                  Length;
  UINT32                  AuthenticationStatus;
  BOOLEAN                 ExtractedFv;
  EFI_GUID                FvName;
  EFI_GUID                FileName;
} EFI_HOB_FIRMWARE_VOLUME3;

Parameters

Header: The HOB generic header. Header.HobType = EFI_HOB_TYPE_FV3 .

BaseAddress: The physical memory-mapped base address of the firmware volume. Type EFI_PHYSICAL_ADDRESS is defined in AllocatePages() in the Unified Extensible Firmware Interface Specification.

Length: The length in bytes of the firmware volume.

AuthenticationStatus: The authentication status. See Related Definitions of EFI_PEI_GUIDED_SECTION_EXTRACTION_PPI.ExtractSection() for more information.

ExtractedFv: TRUE if the FV was extracted as a file within another firmware volume. FALSE otherwise.

FvName: The name GUID of the firmware volume. Valid only if IsExtractedFv is TRUE .

FileName: The name GUID of the firmware file which contained this firmware volume. Valid only if IsExtractedFv is TRUE .

Description

The firmware volume HOB details the location of firmware volumes that contain firmware files. It includes a base address and length. In particular, the HOB consumer phase will use these HOBs to discover drivers to execute and the hand-off into the HOB consumer phase will use this HOB to discover the location of the HOB consumer phase firmware file.

The firmware volume HOB is produced in the following ways:

By the executable content in the HOB producer phase in the Boot Firmware Volume (BFV) that understands the size and layout of the firmware volume(s) that are present in the platform.
By a module that has loaded a firmware volume from some media into memory. The firmware volume HOB details this memory location.
By a module that has extracted the firmware volume from a file within a firmware file system. By recording the volume and file name, the HOB consumer phase can avoid processing the same file again.

Firmware volumes described by the firmware volume HOB must have a firmware volume header as described in this specification.

The HOB consumer phase consumes all firmware volume HOBs that are presented by the HOB producer phase for use by its read-only support for the PI Firmware Image Format. The HOB consumer phase must provide appropriate authentication data reflecting AuthenticationStatus for clients accessing the corresponding firmware volumes. The HOB producer phase is required to describe any firmware volumes that may contain the HOB consumer phase or platform drivers that are required to discover other firmware volumes.

5.8. CPU HOB

5.8.1. EFI_HOB_CPU

Summary

Describes processor information, such as address space and I/O space capabilities.

Prototype

typedef struct _EFI_HOB_CPU {
  EFI_HOB_GENERIC_HEADER  Header;
  UINT8                   SizeOfMemorySpace;
  UINT8                   SizeOfIoSpace;
  UINT8                   Reserved[6];
} EFI_HOB_CPU;

Parameters

Header: The HOB generic header. Header.HobType = EFI_HOB_TYPE_CPU .

SizeOfMemorySpace: Identifies the maximum physical memory addressability of the processor.

SizeOfIoSpace: Identifies the maximum physical I/O addressability of the processor.

Reserved: For this version of the specification, this field will always be set to zero.

Description

The CPU HOB is produced by the processor executable content in the HOB producer phase. It describes processor information, such as address space and I/O space capabilities. The HOB consumer phase consumes this information to describe the extent of the GCD capabilities.

5.9. Memory Pool HOB

5.9.1. EFI_HOB_MEMORY_POOL

Summary

Describes pool memory allocations.

Prototype

typedef struct _EFI_HOB_MEMORY_POOL {
  EFI_HOB_GENERIC_HEADER        Header;
} EFI_HOB_MEMORY_POOL;

Parameters

Header: The HOB generic header. Header.HobType = EFI_HOB_TYPE_MEMORY_POOL .

Description

The memory pool HOB is produced by the HOB producer phase and describes pool memory allocations. The HOB consumer phase should be able to ignore these HOBs. The purpose of this HOB is to allow for the HOB producer phase to have a simple memory allocation mechanism within the HOB list. The size of the memory allocation is stipulated by the HobLength field in EFI_HOB_GENERIC_HEADER .

5.10. UEFI Capsule HOB

5.10.1. EFI_HOB_UEFI_CAPSULE

Summary

Details the location of coalesced each UEFI capsule memory pages.

Prototype

typedef struct {
    EFI_HOB_GENERIC_HEADER    Header;
    EFI_PHYSICAL_ADDRESS      BaseAddress;
    UINT64                    Length;
} EFI_HOB_UEFI_CAPSULE;

Parameters

Header: The HOB generic header where Header.HobType = EFI_HOB_TYPE_UEFI_CAPSULE.

BaseAddress: The physical memory-mapped base address of an UEFI capsule. This value is set to point to the base of the contiguous memory of the UEFI capsule. The length of the contiguous memory in bytes

Description

Each UEFI capsule HOB details the location of a UEFI capsule. It includes a base address and length which is based upon memory blocks with a EFI_CAPSULE_HEADER and the associated CapsuleImageSize -based payloads. These HOB’s shall be created by the PEI PI firmware sometime after the UEFI UpdateCapsule service invocation with the CAPSULE_FLAGS_POPULATE_SYSTEM_TABLE flag set in the EFI_CAPSULE_HEADER .

5.11. Unused HOB

5.11.1. EFI_HOB_TYPE_UNUSED

Summary

Indicates that the contents of the HOB can be ignored.

Prototype

#define EFI_HOB_TYPE_UNUSED     0xFFFE

Description

This HOB type means that the contents of the HOB can be ignored. This type is necessary to support the simple, allocate-only architecture of HOBs that have no delete service. The consumer of the HOB list should ignore HOB entries with this type field.

An agent that wishes to make a HOB entry ignorable should set its type to the prototype defined above.

5.12. End of HOB List HOB

5.12.1. EFI_HOB_TYPE_END_OF_HOB_LIST

Summary

Indicates the end of the HOB list. This HOB must be the last one in the HOB list.

Prototype

#define EFI_HOB_TYPE_END_OF_HOB_LIST    0xffff

Description

This HOB type indicates the end of the HOB list. This HOB type must be the last HOB type in the HOB list and terminates the HOB list. A HOB list should be considered ill formed if it does not have a final HOB of type EFI_HOB_TYPE_END_OF_HOB_LIST .

5.13. SMRAM Memory Hob

5.13.1. EFI_SMRAM_HOB_DESCRIPTOR_BLOCK

Summary

This is a special GUID extension Hob to describe SMRAM memory regions.

GUID

#define EFI_SMM_SMRAM_MEMORY_GUID { \
  0x6dadf1d1, 0xd4cc, 0x4910, 0xbb, 0x6e, 0x82, 0xb1, 0xfd,
0x80, 0xff, 0x3d \
}

Prototype

typedef struct {
  UINT32                      NumberOfSmmReservedRegions;
  EFI_SMRAM_DESCRIPTOR        Descriptor[1];
} EFI_SMRAM_HOB_DESCRIPTOR_BLOCK;

Parameters

NumberOfSmmReservedRegions: Designates the number of possible regions in the system that can be usable for SMRAM.
Descriptor: Used to describe the candidate regions for SMRAM that are supported by this platform.

Description

The GUID extension hob is to describe SMRAM memory regions supported by the platform.